kollektiv

The umbrella for a small suite of Minecraft tools:

Product	What it is	Stack
Konnekt	Desktop dashboard for Minecraft servers	Wails v2 · Go · React 19
Kommands	Command generator for Java Edition	Vite · React 19, and a Wails v2 · Go desktop shell

This repo owns conventions, domain knowledge, and agent tooling. It does not own builds, CI, or releases — each product keeps its own.

---

Why this exists

The two products share a design language, a domain, and a set of working rules, and each of those was written down twice. Kommands' docs/design-tokens.md restated Konnekt's entire palette by hand. That palette now lives in design/tokens.json, and both products generate from their vendored copy of it. Both repos carry their own health-check prose. Both are exposed to the same failure mode: Minecraft syntax changes between versions in ways that produce commands which look correct and silently do nothing, and model training data on that syntax is frequently stale.

Written twice, those rules drift. Held here as a plugin, they do not.

A monorepo would be the wrong shape. The products have separate release cycles and unrelated failure modes: Konnekt publishes binaries and an .rpm off v* tags, Kommands deploys a web build continuously and derives its data from pinned mcmeta tags. Both are now a Go shell around a React frontend, and that is a reason to share more, not to merge: what converged is the shell, what stayed separate is everything either product releases.

---

Layout

This repo is the workspace root. The products are cloned as siblings beneath it and are not tracked here.

kollektiv/
├── suite.repos.json            the product manifest
├── CLAUDE.md                   what an agent landing here needs to know
├── scripts/bootstrap.sh        clones missing products
├── scripts/sync-tokens.sh      vendors design/tokens.json into each product
│                               (--check reports drift and writes nothing)
├── scripts/validate-schemas.sh validates every manifest against its schema
├── .github/workflows/ci.yml    this repo's own checks, and the aislop gate
├── .github/workflows/drift.yml the cross-repo drift checks, on every push and nightly
├── plugins/suite-kit/workflows/ the workflows every product runs identically, vendored
│                               into each product (aislop, CodeQL, pr-labelled, Scorecard)
├── .github/workflows/issue-priority.yml
│                               master copy of the workflow that turns a form answer
│                               into a p* label, vendored into each product
├── .aislop/base.yml            the suite's aislop policy, vendored into each product
├── .claude-plugin/             marketplace manifest
├── design/tokens.json          the shared design-token source
├── design/tokens.schema.json   its schema
├── design/labels.json          the shared GitHub/Linear label taxonomy
├── design/labels.schema.json   its schema
├── design/suite.schema.json    schema for each repo's .claude/suite.json
├── scripts/sync-labels.sh      applies design/labels.json's GitHub side via gh
│                               (--check reports drift and writes nothing)
├── scripts/sync-runner.sh      vendors the runner trio into each product
│                               (--check reports drift and writes nothing)
├── scripts/sync-notes.sh       vendors the release-notes generator into each product
├── scripts/sync-aislop.sh      vendors .aislop/base.yml into each product
├── scripts/sync-priority.sh    vendors the priority workflow and the forms' question
├── scripts/check-participation.sh
│                               permissions floor, manifest paths, formatting settings,
│                               and that vendored files are excluded from product tools
├── scripts/cloud-setup.sh      the cloud environment's setup script, pasted into the
│                               environment dialog rather than run from a checkout
├── scripts/adopt.sh            scaffolds a repo's suite.json, settings block,
│                               .gitignore lines and the vendored files
├── plugins/suite-kit/          the shared plugin
├── .claude/                    this repo's own suite-kit + superpowers adoption
├── docs/adopting.md            how a repo adopts suite-kit
├── docs/conventions.md         cross-repo rules: tracking, PRs, permissions
├── docs/linear.md              the Linear structure /suite-kit:suite-sync mirrors into
├── docs/roadmap.md             this repo's own roadmap — direction, not work items
├── website/                    the suite's home page, styled from design/tokens.json
├── Konnekt/                    cloned, untracked
└── Kommands/                   cloned, untracked

Getting started

git clone https://github.com/kollektiv-mc/Kollektiv
cd Kollektiv
./scripts/bootstrap.sh
./scripts/sync-tokens.sh

Both scripts are idempotent and never delete: a product directory that already contains a working clone is left alone, and a vendored token file that already matches the source is not rewritten.

---

Design tokens

design/tokens.json is the suite's single source of truth for design values — tech-neutral JSON, semantic name to value, no CSS syntax baked in. Both products are consumers: sync-tokens.sh vendors the file into each clone as tokens.source.json, and each product's own generator transforms it into whatever its stack needs.

Nothing both produces and consumes the token set, which is what makes regenerating safe. See design/README.md.

---

suite-kit

A Claude Code plugin, published from this repo's own marketplace, carrying the rules both products share.

Skill	Purpose
/suite-kit:health	Run a product's checks and invariants, report a table
/suite-kit:health-sweep	Run those checks across every repo and file findings as issues
/suite-kit:mc-syntax	Verify Minecraft syntax against pinned data before writing it
/suite-kit:design-tokens	The no-literal-hex, no-literal-px rule
/suite-kit:suite-sync	Mirror each repo's GitHub Issues into Linear
@mc-reviewer	Review a diff for version-trait and hardcoded-value violations

The skills are generic. Everything product-specific — the actual commands, the actual grep invariants, where the repo is tracked — lives in that product's .claude/suite.json, next to the code it constrains. See docs/adopting.md.

The checks do not depend on the plugin. plugins/suite-kit/suite-check.py runs everything .claude/suite.json declares, and scripts/sync-runner.sh vendors it into each product the same way sync-tokens.sh vendors the token source. Declaring a plugin in .claude/settings.json does not install it, so in a cloud container or an unattended session the vendored runner is the only thing that reaches the checks at all.

What stays in the plugin is judgement: whether a matched line is the legitimate exception its diagnosis describes, whether a Minecraft identifier is right for the target version. A grep never needed to be a skill.

Deliberately no hooks. Konnekt already binds graphify hook-guard to PreToolUse on Bash, Read, and Glob; stacking more matchers on top is the fastest way to make both feel broken.

superpowers

obra/superpowers is declared alongside suite-kit in every repo in the suite. It replaces Oh-My-ClaudeCode, which this repo no longer uses or documents — OMC's workspace-sharing feature (.omc-workspace) is gone along with it; the sibling-clone layout bootstrap.sh produces stands on its own and never depended on it.

Declaring a marketplace runs third-party code with your privileges — that is a trust decision made per repo, same as any extraKnownMarketplaces entry.

---

Tracking

GitHub Issues is the one source of truth for work items across the suite — every repo declares tracking: "github-issues". Linear is a downstream mirror, kept current by /suite-kit:suite-sync on a schedule. See docs/conventions.md and docs/linear.md for the full model: teams, projects, milestones, and the label taxonomy shared by both sides.

The Linear workspace (Kollektiv-MC, since renamed Kollektiv) holds two teams — Kollektiv and Apps — under one Kollektiv Suite initiative. Linear's MCP exposes no create_team; teams are hand-made in the Linear UI.

The workspace was recreated from scratch on 2026-08-04 (previously KonnektMC); old KON-* issue references in Konnekt's merged PRs point at IDs that no longer exist in the replacement workspace.

Scheduled runs

Two cloud Routines drive the suite on a schedule, both created over MCP against this repo:

Routine	Cron (UTC)	What it does
Suite sync — GitHub → Linear	30 6 * * *	Runs /suite-kit:suite-sync
Weekly suite health check	0 7 * * 1	Runs /suite-kit:health-sweep

The sweep clones every repo in suite.repos.json, runs each one's /suite-kit:health, runs every cross-repo drift check .github/workflows/drift.yml runs, reviews the week's commits and one health pillar per product, and files findings as GitHub issues labelled health-check in the repo they belong to. It never commits, pushes, or opens pull requests. Its issues carry a Health-Check-Key: line so the next week's run comments on an open issue rather than filing a duplicate.

Every run, findings or none, also adds one comment to a standing log issue in this repo carrying Health-Sweep-Log: kollektiv — the counts, the pillar covered and what could not run. A clean week has no issue of its own, and without that comment it is indistinguishable from a week the Routine never fired.

Routine cron is evaluated in UTC and does not follow DST, so these drift by an hour in local terms twice a year — see docs/roadmap.md.