From ea548f9ba1e5f95e0c1fd976fc67ec591b79ecc6 Mon Sep 17 00:00:00 2001 From: prode Date: Tue, 15 Sep 2026 19:01:01 -0300 Subject: [PATCH] chore(workspace): bring the committed scaffold up to template version 31 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #46 landed just below #47, so the .claude/ tree committed by the knowledge-base run was already a version behind main's own templates: it still carried .claude/commands/ and the unprefixed skill and agent names that #46 removed. `scc update` closes that, and `scc update --dry-run` is clean afterwards. create 8 scc-* skills, scc-code-review, scc-security-review update rules/delivery.md, knowledge-base.md, specs.md, tasks.md delete .claude/commands/ entirely, the unprefixed skills and agents Two things were verified rather than assumed. The manifest's `check` object survives the rebuild — Manifest.CarryOver does what it says, so the four gate commands recorded by #47 are untouched. And .claude/rules/project.md and CLAUDE.md were both reported as yours and left alone. The emptied directories are removed by hand, because `scc update` does not prune them: it deletes the managed file and leaves the directory, and the skills validator then reports skill.missing-skill-md on each one — eight of them here. Git does not track empty directories, so this never reaches a clone, but it fires for anyone running `scc update` in place. Recorded as n-0006; fixing internal/scaffold is not this branch's job. --- .../{code-review.md => scc-code-review.md} | 2 +- ...urity-review.md => scc-security-review.md} | 6 +- .claude/commands/scc-adr.md | 15 -- .claude/commands/scc-codewiki.md | 13 -- .claude/commands/scc-glossary.md | 12 -- .claude/commands/scc-init.md | 22 --- .claude/commands/scc-plan-run.md | 32 ---- .claude/commands/scc-prd.md | 16 -- .claude/commands/scc-stack.md | 16 -- .claude/commands/scc-wiki.md | 13 -- .claude/rules/delivery.md | 2 +- .claude/rules/knowledge-base.md | 5 + .claude/rules/specs.md | 5 + .claude/rules/tasks.md | 6 + .claude/scc-manifest.json | 138 +++++++----------- .claude/skills/{adr => scc-adr}/SKILL.md | 10 +- .../{codewiki => scc-codewiki}/SKILL.md | 12 +- .../{glossary => scc-glossary}/SKILL.md | 12 +- .claude/skills/{init => scc-init}/SKILL.md | 8 +- .../{plan-run => scc-plan-run}/SKILL.md | 8 +- .claude/skills/{prd => scc-prd}/SKILL.md | 11 +- .claude/skills/{stack => scc-stack}/SKILL.md | 19 ++- .claude/skills/{wiki => scc-wiki}/SKILL.md | 11 +- docs/notes.md | 1 + 24 files changed, 141 insertions(+), 254 deletions(-) rename .claude/agents/{code-review.md => scc-code-review.md} (99%) rename .claude/agents/{security-review.md => scc-security-review.md} (96%) delete mode 100644 .claude/commands/scc-adr.md delete mode 100644 .claude/commands/scc-codewiki.md delete mode 100644 .claude/commands/scc-glossary.md delete mode 100644 .claude/commands/scc-init.md delete mode 100644 .claude/commands/scc-plan-run.md delete mode 100644 .claude/commands/scc-prd.md delete mode 100644 .claude/commands/scc-stack.md delete mode 100644 .claude/commands/scc-wiki.md rename .claude/skills/{adr => scc-adr}/SKILL.md (89%) rename .claude/skills/{codewiki => scc-codewiki}/SKILL.md (86%) rename .claude/skills/{glossary => scc-glossary}/SKILL.md (87%) rename .claude/skills/{init => scc-init}/SKILL.md (95%) rename .claude/skills/{plan-run => scc-plan-run}/SKILL.md (95%) rename .claude/skills/{prd => scc-prd}/SKILL.md (89%) rename .claude/skills/{stack => scc-stack}/SKILL.md (81%) rename .claude/skills/{wiki => scc-wiki}/SKILL.md (91%) diff --git a/.claude/agents/code-review.md b/.claude/agents/scc-code-review.md similarity index 99% rename from .claude/agents/code-review.md rename to .claude/agents/scc-code-review.md index e875d7d..ecf7bb2 100644 --- a/.claude/agents/code-review.md +++ b/.claude/agents/scc-code-review.md @@ -1,5 +1,5 @@ --- -name: code-review +name: scc-code-review description: Reviews a diff for correctness and quality against the task list, re-runs the feature's tests and lint, and reports. Use it after the last task of a spec or plan is verified and before opening the PR — never on your own work as the author. tools: Read, Grep, Glob, Bash model: sonnet diff --git a/.claude/agents/security-review.md b/.claude/agents/scc-security-review.md similarity index 96% rename from .claude/agents/security-review.md rename to .claude/agents/scc-security-review.md index 64056b9..67e24b3 100644 --- a/.claude/agents/security-review.md +++ b/.claude/agents/scc-security-review.md @@ -1,6 +1,6 @@ --- -name: security-review -description: Reviews a diff for exploitable weaknesses, attack-class agnostic — traces attacker-controlled input to effect and reports reachable paths. Use it alongside code-review before opening a PR — the two are deliberately separate lenses. +name: scc-security-review +description: Reviews a diff for exploitable weaknesses, attack-class agnostic — traces attacker-controlled input to effect and reports reachable paths. Use it alongside scc-code-review before opening a PR — the two are deliberately separate lenses. tools: Read, Grep, Glob, Bash model: sonnet effort: high @@ -9,7 +9,7 @@ effort: high You review a diff for security defects and nothing else. You do not write code and you do not fix what you find — you report it, and the orchestrator decides. -Separate from `code-review` on purpose: **one reviewer asked for "everything" +Separate from `scc-code-review` on purpose: **one reviewer asked for "everything" reliably under-weights security**, because correctness findings are easier to produce and crowd it out. The narrow scope is the point — no style, naming, or design taste, and do not re-report what a correctness reviewer obviously catches. diff --git a/.claude/commands/scc-adr.md b/.claude/commands/scc-adr.md deleted file mode 100644 index 35c68da..0000000 --- a/.claude/commands/scc-adr.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Record a hard-to-reverse decision as a numbered ADR under docs/adr/, or supersede one that stopped being true -argument-hint: [the decision, or the ADR being superseded] ---- - -Use the `adr` skill. - -Decision: $ARGUMENTS - -First ask whether this is an ADR at all: how expensive would it be to undo? A -decision that is cheap to change belongs in the spec's `design.md`, and an `adr/` -full of reversible choices buries the records that actually explain the system. - -If an existing record is being replaced, write the new one and mark the old one -superseded — never edit its prose. diff --git a/.claude/commands/scc-codewiki.md b/.claude/commands/scc-codewiki.md deleted file mode 100644 index 34c58e0..0000000 --- a/.claude/commands/scc-codewiki.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: Narrate an area of the codebase into docs/codewiki/, every section citing the exact lines it explains -argument-hint: [area or path to narrate | repair] ---- - -Use the `codewiki` skill. - -Area: $ARGUMENTS - -If no area was named, run `scc validate` and repair the `codewiki.*` findings it -reports — a broken citation means the code moved and the prose describing it is now -suspect, so re-read before re-numbering. If there are no findings and no area was -named, ask which area is hard to enter cold rather than picking one at random. diff --git a/.claude/commands/scc-glossary.md b/.claude/commands/scc-glossary.md deleted file mode 100644 index 85c7d6f..0000000 --- a/.claude/commands/scc-glossary.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Add, settle, or rename a canonical term in docs/glossary.md, and list the synonyms to avoid -argument-hint: [term, or the ambiguity to settle] ---- - -Use the `glossary` skill. - -Term: $ARGUMENTS - -Read `docs/glossary.md` before adding to it — an entry that duplicates an existing -concept under a different name makes the canonical source itself ambiguous. If -nothing was named, run `scc validate` and resolve the `glossary.*` findings. diff --git a/.claude/commands/scc-init.md b/.claude/commands/scc-init.md deleted file mode 100644 index d96e8b0..0000000 --- a/.claude/commands/scc-init.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: Bootstrap the knowledge base from the code that is already here — survey the repository, then write stack, glossary, the project rule's real commands, the wiki, and the ADRs for decisions already taken -argument-hint: [anchors | full, and the subtree to cover if not the whole repository] ---- - -Use the `init` skill. - -Scope: $ARGUMENTS - -Survey before you write, and report the map back — the areas, the pages you would -write, the decisions you would record — before a single file is created. Ask the -graph and the history rather than reading the tree file by file. - -**Write only what you can point at.** Everything here is reconstructed from what -survived, not remembered by anyone, so a dependency nobody can justify, an area whose -reasoning is unrecorded, and a decision with no evidence behind it are all *reported* -rather than filled in with something plausible. A gap is visible; an invention is -believed. - -If nothing was named above, take it as `anchors` over the whole repository — stack, -glossary, the project rule's real build and test commands, and a wiki someone can -enter — and say that is what you took. diff --git a/.claude/commands/scc-plan-run.md b/.claude/commands/scc-plan-run.md deleted file mode 100644 index e3531d6..0000000 --- a/.claude/commands/scc-plan-run.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Run a plan under plans/ to completion — implement group by group, then deliver as one PR per group or one at the end, and settle CI before calling it delivered -argument-hint: [the plan, plus how to run it and any standing instruction] ---- - -Use the `plan-run` skill. - -Plan, and how to run it: $ARGUMENTS - -Brief the plan — `scc map brief ` — then `scc map ` for the counts, and -name the groups back, numbered and in order, before writing any code. The order is the -one thing the user can correct cheaply now and expensively after three merges. - -**Never open the plan file.** `brief` is its header and `tasks` is its checklist; -there is nothing else in it, and opening one as the first act of a run puts all of it -in context for every turn of a loop that lasts hours. Inside a group, ask `scc map -tasks --next` for the one task to do, and ask again once it is ticked. - -Then take every answer the line above already gave and ask only for what is left. -"Implement the whole plan, one PR at the end, delivered when CI is green" has settled -most of it; re-asking what someone just typed is the friction that stops people using -this at all. Restate what you took so a wrong reading is cheap to correct, then put -the remaining questions in one exchange — automatic or gated, one PR at the end or one -per group, and what happens once a PR is open. **These are the developer's calls.** Anything the plan's frontmatter already -records is a proposed answer to confirm, not a decision already made. - -The plan is delivered when CI is green on its pull request — never on the strength of -a passing local suite. - -Anything said above about *how* to implement is a standing instruction: it applies -to every group, and you carry it into each one explicitly rather than trusting it to -survive from the first group to the last. diff --git a/.claude/commands/scc-prd.md b/.claude/commands/scc-prd.md deleted file mode 100644 index 3325d18..0000000 --- a/.claude/commands/scc-prd.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Turn an initiative too large for one spec into a plan under plans/ — decomposed into specs and tasks -argument-hint: [the initiative, epic, or PRD] ---- - -Use the `prd` skill. - -Initiative: $ARGUMENTS - -Check the routing question before you start: work that is one feature with unsettled -requirements is a spec, not a plan — run `scc spec new ` instead of wrapping -one feature in a plan for ceremony. - -If the initiative is too vague to decompose, ask a small batch of concrete -multiple-choice questions once, then decompose. Do not guess at the scope, and do not -interview at length — stop asking the moment you can name the leaves. diff --git a/.claude/commands/scc-stack.md b/.claude/commands/scc-stack.md deleted file mode 100644 index 25b6297..0000000 --- a/.claude/commands/scc-stack.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Record an adopted technology in docs/stack.md, or account for a dependency that nobody decided on -argument-hint: [technology being adopted or dropped] ---- - -Use the `stack` skill. - -Technology: $ARGUMENTS - -If nothing was named, run `scc validate` and work through the -`stack.undocumented-dependency` findings: for each one, either record the decision or -establish that nobody can justify the dependency and remove it. Both are correct -outcomes; listing a name with no reason is not. - -Adopting technology is a decision with a long tail. If it is not obviously the right -call, stop and ask rather than committing on someone else's behalf. diff --git a/.claude/commands/scc-wiki.md b/.claude/commands/scc-wiki.md deleted file mode 100644 index 38ba7a2..0000000 --- a/.claude/commands/scc-wiki.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: Build or maintain docs/wiki/ — ingest a source from docs/raw/, answer from what is known, or clear wiki.* findings -argument-hint: [ingest | query | maintain] ---- - -Use the `wiki` skill. - -Request: $ARGUMENTS - -If nothing was asked for specifically, look at `docs/raw/` first — anything sitting -there is unprocessed work and is the default job. If `raw/` is empty, run -`scc validate` and clear whatever `wiki.*` findings it reports. If there are none, -say so rather than inventing pages. diff --git a/.claude/rules/delivery.md b/.claude/rules/delivery.md index 9efe8d6..c9b110b 100644 --- a/.claude/rules/delivery.md +++ b/.claude/rules/delivery.md @@ -24,7 +24,7 @@ Once the last task is done: 1. **`scc validate --checks --pr`** on the integrated branch — artifacts, record and the four gates together, build first and stopping at the first failure; `2` is not done. Per-task runs cannot see breakage between tasks, and this is what `pre-push` runs. -2. **`code-review` and `security-review`** subagents on the diff, dispatched together. +2. **`scc-code-review` and `scc-security-review`** subagents on the diff, dispatched together. **Both, every time, on every PR** — not "when the change looks risky", which is the judgment call that ends with neither being run. Each returns a verdict, what it checked, and findings by severity; you fix from that report and do not re-review. diff --git a/.claude/rules/knowledge-base.md b/.claude/rules/knowledge-base.md index a247e15..6e17b14 100644 --- a/.claude/rules/knowledge-base.md +++ b/.claude/rules/knowledge-base.md @@ -1,3 +1,8 @@ +--- +paths: + - "docs/**" +--- + # The knowledge base — `docs/` A spec answers *what this feature does now*. `docs/` answers *why* — the durable diff --git a/.claude/rules/specs.md b/.claude/rules/specs.md index 36c0454..0c3b2c6 100644 --- a/.claude/rules/specs.md +++ b/.claude/rules/specs.md @@ -1,3 +1,8 @@ +--- +paths: + - "specs/**" +--- + # Specs — the three artifacts `specs//` holds exactly three files. `scc spec new ` creates them; diff --git a/.claude/rules/tasks.md b/.claude/rules/tasks.md index 0237e21..5f03f32 100644 --- a/.claude/rules/tasks.md +++ b/.claude/rules/tasks.md @@ -1,3 +1,9 @@ +--- +paths: + - "specs/**" + - "plans/**" +--- + # Task grammar One grammar governs every task line, in a spec's `tasks.md` or a plan's checklist. diff --git a/.claude/scc-manifest.json b/.claude/scc-manifest.json index c921e87..0d30d5d 100644 --- a/.claude/scc-manifest.json +++ b/.claude/scc-manifest.json @@ -8,104 +8,64 @@ "codegraph": [], "files": [ { - "hash": "4b40900366093c80ea0b97f51dbbb01e451189f6395d2d0c65fcd1a659cb0770", - "path": ".claude/agents/code-review.md", - "version": "29" - }, - { - "hash": "96042c83eb675680617782022d1590e3f827b1c246073696406b83ee79109277", - "path": ".claude/agents/security-review.md", - "version": "29" - }, - { - "hash": "9d5f7c92e706247690fdbbed4fa74a34b1c10ed790f3984d3e593e591e3a8f24", - "path": ".claude/commands/scc-adr.md", - "version": "29" - }, - { - "hash": "6ee3a8ce85c76c6f3c1d83fa1124f092bbe37793fea01ab79dabe9986ddc23d9", - "path": ".claude/commands/scc-codewiki.md", - "version": "29" - }, - { - "hash": "6139363a873cc0ab8909351290bb2ed974cb8da1d61fe255e6fbe500f4bd34b5", - "path": ".claude/commands/scc-glossary.md", - "version": "29" - }, - { - "hash": "611f1f16576d9f3eaa39cda3b09617de44af327f3b848b47b7e209c1ce1b3654", - "path": ".claude/commands/scc-init.md", - "version": "29" - }, - { - "hash": "3dd1b39a83b47f8e738ced47f9c6c111fad0e6d9d34fad6316a32fef26ad2f2c", - "path": ".claude/commands/scc-plan-run.md", - "version": "29" - }, - { - "hash": "2a7e1f3e6dd1be62f81e2ceedf0bd6c7361e83fc49bbfdedcbdf4825a2223208", - "path": ".claude/commands/scc-prd.md", - "version": "29" - }, - { - "hash": "304b1ce1ec486edc0cffb85671810c19ca4343a8ddb048805cdbd97755633e35", - "path": ".claude/commands/scc-stack.md", - "version": "29" + "hash": "08141d3f57fbe10f46ea557de9969fe06f96e4aceca90cd14079aea0162e4a73", + "path": ".claude/agents/scc-code-review.md", + "version": "31" }, { - "hash": "f0bba07b8e2cd1d67dcadd827843e21316de1a2c870171d7c13ad72fd58f5697", - "path": ".claude/commands/scc-wiki.md", - "version": "29" + "hash": "86ae07c5864d0c38932cf9781e5b0ac5d6f6e36925577efdef646e779abbe65b", + "path": ".claude/agents/scc-security-review.md", + "version": "31" }, { "hash": "f3132fd6be0b859b5ffb063e22ba3b840226c5bfdde2613cd21993ff12afa477", "path": ".claude/rules/artifacts.md", - "version": "29" + "version": "31" }, { "hash": "f5299384ccab206eac0eab1d6b93095831745d308cec32deac687b6359dbb900", "path": ".claude/rules/autonomy.md", - "version": "29" + "version": "31" }, { "hash": "8eee2d450faada83295a4a04e5a1267bf5f717df9e7ac7da5fddd7649c666499", "path": ".claude/rules/caveman.md", - "version": "29" + "version": "31" }, { "hash": "cfe46c6623c20b6da46c9f18ef9b35e0f554c6c4568791ff190648dda3524706", "path": ".claude/rules/code-search.md", - "version": "29" + "version": "31" }, { - "hash": "3ef328b1b6c05fa9d499417d99b0d45a6502a557d304f8b7a0b2b2653f4535b6", + "hash": "3ad4d9513a212bcced1b99db171a9ed53ccb4be38063f345ae722e6c8f36fa20", "path": ".claude/rules/delivery.md", - "version": "29" + "version": "31" }, { - "hash": "a1ae9fa25877b9291d208d0c5146281e6d40fe422f22626f4f63b8e69c90e4fb", + "hash": "ffca716ea25746d8e100ba3a7a7b884907736adebf3a7131b989fa4e9fcd0d80", "path": ".claude/rules/knowledge-base.md", - "version": "29" + "version": "31" }, { "hash": "59bb916a2002d4176353463b017c366868192cf95c80fd1dce74265188b738c3", "path": ".claude/rules/ladder.md", - "version": "29" + "version": "31" }, { "hash": "79d5cbf1ab7fd09d26e9ea9119f3f283615467dbc35d3a4b1d4a030044b3598f", "path": ".claude/rules/methodology.md", - "version": "29" + "version": "31" }, { "hash": "7dcbf5cd9d2e9e8d08aed4eeaa96ee28af85da1d6de51fc35870b8430e30f331", "path": ".claude/rules/notes.md", - "version": "29" + "version": "31" }, { "hash": "52c5033fc427445b4e669c7865dbd8d5c2fc27d57f7200aeeb2cc48bc8e050d3", "path": ".claude/rules/prior-art.md", - "version": "29" + "version": "31" }, { "hash": "ae0030df2e1f053642a84953648e1d6038b0f0fbae831edf1c349badfb00485c", @@ -115,62 +75,62 @@ { "hash": "c8502ace5978c7b9c0543c49ebb5c9550584b1a3405e12c0217b595647e27722", "path": ".claude/rules/routing.md", - "version": "29" + "version": "31" }, { - "hash": "ee77189c4fc13ef5d08b796d42e1f3e41c75bbf72343dc6f6ec9b9f3a1736d54", + "hash": "0b86b1a73769c6ebd37c338c5ec3cbee8dda70b21d43b27a1c95eebc5ee70a9f", "path": ".claude/rules/specs.md", - "version": "29" + "version": "31" }, { - "hash": "350bfe758d894f0318517fa8000ce7160094ef71e15bd41e3771b492de14fcf6", + "hash": "d64a118d493424b10ad8af24861083c34541f7946a92dae92fb153b0ab739c26", "path": ".claude/rules/tasks.md", - "version": "29" + "version": "31" }, { "hash": "403174a8133018b54adc69c3047c46f8ff603b8a91759c62da1e7ca6b7f45463", "path": ".claude/rules/verification.md", - "version": "29" + "version": "31" }, { - "hash": "d79136eed898f20dfb3db233ab4deb4021aa1a7b3350201c06a6d7129e48bb15", - "path": ".claude/skills/adr/SKILL.md", - "version": "29" + "hash": "cce99457f203766837ec2b8165a9370924178d9ee377c7848dba65880461cf3f", + "path": ".claude/skills/scc-adr/SKILL.md", + "version": "31" }, { - "hash": "4cc0b1ac151610cfb6a9e4cf5735d44b1351d9bc24c5ff53ba2aac01035cec12", - "path": ".claude/skills/codewiki/SKILL.md", - "version": "29" + "hash": "fc2ecb43e7e3c157082dc359d1d0fb20c99fdb6fb774cfcead3c8c0961fef922", + "path": ".claude/skills/scc-codewiki/SKILL.md", + "version": "31" }, { - "hash": "88b152ef75a40b6691554730d86a58e240152ed7683333a8638fec5107474f09", - "path": ".claude/skills/glossary/SKILL.md", - "version": "29" + "hash": "60e80dcee7e68498679735ac40812ac90641340fef6bd75d3e7de64d209f8716", + "path": ".claude/skills/scc-glossary/SKILL.md", + "version": "31" }, { - "hash": "ef9bef5dd84dc63ed9b62ac4b87a36319f42b850c8b7de133cec9e198b308d64", - "path": ".claude/skills/init/SKILL.md", - "version": "29" + "hash": "9d21e953cce950ccf495810c94411a98706780b2b8d38817e3ce13bfc0c74625", + "path": ".claude/skills/scc-init/SKILL.md", + "version": "31" }, { - "hash": "de8a01ad55219f152ec682d4a49a452f61cdd3379c08f932e3cccbcf87f7b0b8", - "path": ".claude/skills/plan-run/SKILL.md", - "version": "29" + "hash": "2385f307f96cc4261e44d1a0d49bb39d6a5842a3205cee317e3228ced0f6aeb6", + "path": ".claude/skills/scc-plan-run/SKILL.md", + "version": "31" }, { - "hash": "1e9206e87770898bc7382348db30f6446f63c8716770669c1d84f0df9b413275", - "path": ".claude/skills/prd/SKILL.md", - "version": "29" + "hash": "3d3773f869d73beeab4c2061397c9ad81faf6d4c11d1ef423470aca432c5a9e1", + "path": ".claude/skills/scc-prd/SKILL.md", + "version": "31" }, { - "hash": "865f88cef91fa59f6a42650ef1c518141f662d194058caf5fa8a1cc6093bc1dc", - "path": ".claude/skills/stack/SKILL.md", - "version": "29" + "hash": "42dff0d55f15c60da604f62fc1dfe8af5b73de2e2497553411447aae57698e1b", + "path": ".claude/skills/scc-stack/SKILL.md", + "version": "31" }, { - "hash": "15aa510d8b7af6f7b72c1093ae772b66135c63e8192af1d0662f1e17de232765", - "path": ".claude/skills/wiki/SKILL.md", - "version": "29" + "hash": "aa53b7ddf701ea495d68ea12aa23a6d352c202edc0e308b7218a1bf685b09f21", + "path": ".claude/skills/scc-wiki/SKILL.md", + "version": "31" }, { "hash": "9dc2f234756bfdc79aa5697e8470f80766e68a0e72b6cda98107e25ea8a9427a", @@ -179,5 +139,5 @@ } ], "harness": "claude", - "scc": "v0.24.1" + "scc": "dev" } diff --git a/.claude/skills/adr/SKILL.md b/.claude/skills/scc-adr/SKILL.md similarity index 89% rename from .claude/skills/adr/SKILL.md rename to .claude/skills/scc-adr/SKILL.md index 83f2ad2..382aebe 100644 --- a/.claude/skills/adr/SKILL.md +++ b/.claude/skills/scc-adr/SKILL.md @@ -1,6 +1,7 @@ --- -name: adr -description: Record a decision that is hard to reverse as a numbered ADR under docs/adr/, and supersede an old record rather than editing it. Use it when a choice is made that would be expensive to undo — storage, wire protocol, a module boundary, a vendor holding data, a framework the code will shape itself around — when someone asks why the project is built this way, and when `scc validate` reports adr.* findings such as a numbering gap, a superseded record with no successor, or a citation resolving to no record. +name: scc-adr +description: Record a decision that is hard to reverse as a numbered ADR under docs/adr/, and supersede rather than edit an old one. Use it when a choice would be expensive to undo — storage, a wire protocol, a module boundary, a vendor — and on any adr.* finding. +argument-hint: [the decision, or the ADR being superseded] --- You write the record of a decision, so that the reasoning survives the people who @@ -8,6 +9,11 @@ were in the room. The filename shape, the frontmatter, and the citation form are `.claude/rules/knowledge-base.md`. This skill is when to write one and how to write one worth reading. +## Nothing asked for + +`$ARGUMENTS` is the decision, or the record being superseded. Empty, run +`scc validate` and clear the `adr.*` findings. + ## Is this an ADR? One question: **how expensive would it be to undo?** diff --git a/.claude/skills/codewiki/SKILL.md b/.claude/skills/scc-codewiki/SKILL.md similarity index 86% rename from .claude/skills/codewiki/SKILL.md rename to .claude/skills/scc-codewiki/SKILL.md index 759451a..3247ec3 100644 --- a/.claude/skills/codewiki/SKILL.md +++ b/.claude/skills/scc-codewiki/SKILL.md @@ -1,6 +1,7 @@ --- -name: codewiki -description: Narrate an area of this codebase into docs/codewiki/, where every section cites the exact lines it explains. Use it when a subsystem is hard to enter cold and the code does not say why it is shaped that way, when someone asks for onboarding notes or an architecture walkthrough, and when `scc validate` reports codewiki.* findings — a citation that no longer resolves, one that runs past the end of its file, or a section that cites nothing at all. +name: scc-codewiki +description: Narrate an area of this codebase into docs/codewiki/, every section citing the lines it explains. Use it when a subsystem is hard to enter cold, when someone asks for an architecture walkthrough, and on any codewiki.* finding. +argument-hint: [area or path to narrate | repair] --- You write prose that explains code, and every section of it points at the lines it @@ -11,6 +12,13 @@ becoming a lie. The format is in `.claude/rules/knowledge-base.md`. This skill is the procedure and the judgment. +## Nothing asked for + +`$ARGUMENTS` is the area to narrate. Empty, run `scc validate` and repair the +`codewiki.*` findings — a broken citation means the code moved and the prose +describing it is now suspect, so re-read before re-numbering. With no findings and no +area named, ask which area is hard to enter cold rather than picking one at random. + ## The citation form A link whose text is `path:start-end` and whose target is empty: diff --git a/.claude/skills/glossary/SKILL.md b/.claude/skills/scc-glossary/SKILL.md similarity index 87% rename from .claude/skills/glossary/SKILL.md rename to .claude/skills/scc-glossary/SKILL.md index 396d9d4..f5e64a7 100644 --- a/.claude/skills/glossary/SKILL.md +++ b/.claude/skills/scc-glossary/SKILL.md @@ -1,6 +1,7 @@ --- -name: glossary -description: Own docs/glossary.md — one canonical term per concept, and the synonyms nobody should use for it. Use it when a domain term is coined, contested, fuzzy, or renamed; before naming a spec, a plan, a wiki page, or an identifier that will outlive the session; and when `scc validate` reports glossary.* findings — a duplicate entry, a term listed as both canonical and avoided, or an avoided synonym used somewhere in docs/. +name: scc-glossary +description: Own docs/glossary.md — one canonical term per concept, and the synonyms nobody should use for it. Use it when a domain term is coined, contested or renamed, before naming anything that will outlive the session, and on any glossary.* finding. +argument-hint: [term, or the ambiguity to settle] --- You own the project's vocabulary. Domain language drifts by default: two people @@ -11,6 +12,13 @@ two documents are describing the same concept or two different ones. The entry format is in `.claude/rules/knowledge-base.md`. This skill is when to reach for it and how to decide. +## Nothing asked for + +`$ARGUMENTS` is the term, or the ambiguity to settle. Read `docs/glossary.md` before +adding to it: an entry duplicating an existing concept under a different name makes +the canonical source itself ambiguous. With nothing named, run `scc validate` and +resolve the `glossary.*` findings. + ## The entry One entry per line, in `docs/glossary.md`: diff --git a/.claude/skills/init/SKILL.md b/.claude/skills/scc-init/SKILL.md similarity index 95% rename from .claude/skills/init/SKILL.md rename to .claude/skills/scc-init/SKILL.md index 74d4f4c..8ed4073 100644 --- a/.claude/skills/init/SKILL.md +++ b/.claude/skills/scc-init/SKILL.md @@ -1,9 +1,11 @@ --- -name: init -description: Bootstrap this project's knowledge base from the code that already exists — survey the repository, then write docs/stack.md, docs/glossary.md, the wiki, the codewiki, the ADRs for decisions already taken, and the project rule's real build, test, and lint commands, and the delivery gate's four. Use it on a workspace whose docs/ is still the four seeded anchors, when someone asks to document an existing codebase, when a repository has just been scaffolded and nothing under docs/ is filled in, or when someone runs /scc-init. Not for one page or one new decision — the wiki, glossary, stack, codewiki, and adr skills each own their own artifact, and this run is what calls them. +name: scc-init +description: Bootstrap this project's knowledge base from the code that already exists: survey the repository, then write the stack, glossary, wiki, codewiki and ADRs, and the project's real build, test, lint and format commands. Use it on a workspace whose docs/ is still the seeded anchors, or to document an existing codebase. +argument-hint: [anchors | full, and the subtree to cover if not the whole repository] --- -You fill an empty knowledge base from a repository that already exists. +You fill an empty knowledge base from a repository that already exists. `$ARGUMENTS` +is the scope, if one was given; the table below is what to do when it was not. The formats are not yours. Each artifact has an owner — the `stack`, `glossary`, `wiki`, `codewiki`, and `adr` skills — and the rule they all enforce is diff --git a/.claude/skills/plan-run/SKILL.md b/.claude/skills/scc-plan-run/SKILL.md similarity index 95% rename from .claude/skills/plan-run/SKILL.md rename to .claude/skills/scc-plan-run/SKILL.md index 62c8431..376111b 100644 --- a/.claude/skills/plan-run/SKILL.md +++ b/.claude/skills/scc-plan-run/SKILL.md @@ -1,9 +1,11 @@ --- -name: plan-run -description: Drive a whole plan under plans/ to completion — brief the plan once, report the groups, take whatever the invocation already decided and ask only for the rest, then implement group by group, asking scc for the next task rather than opening the file, and deliver either one PR per group or one at the end, settling CI before calling the plan delivered. Resumes from the repository rather than from memory. Use it when someone asks to implement an entire plan, to keep going until the plan is finished, or runs /scc-plan-run. Not for a single spec or a one-off change, which delivery.md already carries end to end on its own. +name: scc-plan-run +description: Drive a whole plan under plans/ to completion — brief it once, then implement group by group, asking scc for the next task rather than opening the file, and deliver per group or at the end. Resumes from the repository, not from memory. Use it to implement or finish an entire plan. +argument-hint: [the plan, plus how to run it and any standing instruction] --- -You run a plan to the end. +You run a plan to the end. `$ARGUMENTS` names the plan and, often, how to run it — +take every answer it already gave and ask only for what is left. The mechanics of delivering *one* unit of work are not here — they are in `.claude/rules/delivery.md`, and repeating them would give this project two diff --git a/.claude/skills/prd/SKILL.md b/.claude/skills/scc-prd/SKILL.md similarity index 89% rename from .claude/skills/prd/SKILL.md rename to .claude/skills/scc-prd/SKILL.md index eef5865..6a708e2 100644 --- a/.claude/skills/prd/SKILL.md +++ b/.claude/skills/scc-prd/SKILL.md @@ -1,6 +1,7 @@ --- -name: prd -description: Turn an initiative that spans more than one feature into a plan under plans/ — a short header, a checklist of tasks, and references to the specs that will be built separately. Use it when someone arrives with a PRD, a roadmap item, an epic, or a rough idea too large for one spec, and the first job is to find out what it actually decomposes into. For a single feature whose shape is already clear, skip this and run `scc spec new`. +name: scc-prd +description: Turn an initiative spanning more than one feature into a plan under plans/: a short header, a checklist, and references to the specs built separately. Use it for a PRD, a roadmap item, an epic, or an idea too large for one spec. +argument-hint: [the initiative, epic, or PRD] --- You take an initiative that is too big for one spec and turn it into a plan: one @@ -12,6 +13,12 @@ artifact is a **plan**, and the vocabulary in `.claude/rules/routing.md` is what the rest of the workspace uses. Do not create a `docs/prd/` directory. +## Nothing asked for + +`$ARGUMENTS` is the initiative. Check the routing question before you start: work +that is one feature with unsettled requirements is a spec, not a plan — run +`scc spec new ` rather than wrapping one feature in a plan for ceremony. + ## First, check this is a plan at all `.claude/rules/routing.md` asks one question, and it is worth asking diff --git a/.claude/skills/stack/SKILL.md b/.claude/skills/scc-stack/SKILL.md similarity index 81% rename from .claude/skills/stack/SKILL.md rename to .claude/skills/scc-stack/SKILL.md index 9ad8ce4..f325455 100644 --- a/.claude/skills/stack/SKILL.md +++ b/.claude/skills/scc-stack/SKILL.md @@ -1,6 +1,7 @@ --- -name: stack -description: Own docs/stack.md — every adopted technology with one line on why it earned its place. Use it before adding a dependency to go.mod, package.json, or any other manifest; when a technology is being swapped, dropped, or evaluated; and when `scc validate` reports stack.missing or stack.undocumented-dependency, which means something is installed that nobody recorded a decision about. +name: scc-stack +description: Own docs/stack.md — every adopted technology with one line on why it earned its place. Use it before adding a dependency to any manifest, when a technology is swapped or dropped, and on any stack.* finding. +argument-hint: [technology being adopted or dropped] --- You own `docs/stack.md`. The rule it enforces is in @@ -8,9 +9,17 @@ You own `docs/stack.md`. The rule it enforces is in not listed here is an open decision, never something adopted silently.** This is checkable because dependency manifests are structured data. `scc validate` -reads the direct dependencies out of `go.mod` and `package.json` and reports any -that `stack.md` does not mention. Indirect dependencies are skipped — nobody decided -those. +reads the direct dependencies out of every manifest it knows — `go.mod`, +`package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, +`composer.json`, `pom.xml` — and reports any that `stack.md` does not mention. +Indirect dependencies are skipped: nobody decided those. + +## Nothing asked for + +`$ARGUMENTS` is the technology being adopted or dropped. Empty, run `scc validate` +and work through the `stack.undocumented-dependency` findings: for each, either +record the decision or establish that nobody can justify the dependency and remove +it. Both are correct outcomes; listing a name with no reason is not. ## Adding a dependency is two steps diff --git a/.claude/skills/wiki/SKILL.md b/.claude/skills/scc-wiki/SKILL.md similarity index 91% rename from .claude/skills/wiki/SKILL.md rename to .claude/skills/scc-wiki/SKILL.md index d54a641..bdf256c 100644 --- a/.claude/skills/wiki/SKILL.md +++ b/.claude/skills/scc-wiki/SKILL.md @@ -1,6 +1,7 @@ --- -name: wiki -description: Build and maintain docs/wiki/ — one page per concept, linked with wikilinks and reachable from index.md. Use it when a source lands in docs/raw/ and has to be distilled into a page, when a question is better answered from accumulated knowledge than from re-reading the code, and when `scc validate` reports wiki.* findings — a broken wikilink, an orphan page, a changelog naming a page that no longer exists, or a source still sitting unprocessed in docs/raw/. +name: scc-wiki +description: Build and maintain docs/wiki/ — one page per concept, linked with wikilinks and reachable from index.md. Use it to distil a source from docs/raw/, to answer from accumulated knowledge, and on any wiki.* finding. +argument-hint: [ingest | query | maintain] --- You own `docs/wiki/`: the durable half of what this project knows. A spec says what @@ -10,6 +11,12 @@ The format is not yours to invent — it is in `.claude/rules/knowledge-base.md`, and `scc validate` enforces it. This skill is the procedure. +## Nothing asked for + +`$ARGUMENTS` is the request. Empty, the default job is `docs/raw/`: anything sitting +there is unprocessed work. If `raw/` is empty, run `scc validate` and clear whatever +`wiki.*` findings it reports. If there are none, say so rather than inventing pages. + ## Ingest — something landed in `docs/raw/` `raw/` is a drop box, not storage. A file still there is unfinished work, and diff --git a/docs/notes.md b/docs/notes.md index 0d5abce..9e3492f 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -43,3 +43,4 @@ over this file answers with the example above as well as with the notes. --> - n-0003 2026-09-15 #platform @Makefile — make is absent on a default Windows host, so the delivery gate calls go and golangci-lint directly rather than Makefile targets - n-0004 2026-09-15 #gotcha @tools/go.mod — tools/ is a nested module so the root's ./... never sees it — a helper in the main module would land in the coverage profile at 0% - n-0005 2026-09-15 #gotcha @.devcontainer/Dockerfile — bash -lc re-runs /etc/profile and rebuilds PATH, discarding every Docker ENV, so container tooling must be linked into /usr/local/bin +- n-0006 2026-09-15 #gotcha @internal/scaffold — scc update deletes a managed file but never prunes the directory it emptied, and the skills validator then reports skill.missing-skill-md on the empty dir