git:20260924.1101a9b to git:20261007.aaa7079
21 added, 74 removed. Audit A to A.
- # superdev/skills
-
- ## Purpose
+ # docs/archive/superdev/skills - the 20 frozen superdev skills and how they chain
- The skill layer of superdev: 20 skill directories. Grouped here by role rather than listed
- flatly - derive the grouping from each skill's actual `description:` and body when it drifts.
- The authoritative contract of a skill is its own body (`# Input contract` / `# Output format`),
- never this node - this node says who owns what and how they chain.
+ Each skill is `<name>/SKILL.md` with its own `references/`, `templates/`, `assets/` or `scripts/` beside it. This area owns the skill-to-skill flow and the files skills share. The agents they dispatch, the shared `references/` and the plugin-level `scripts/` sit beside `skills/` in the parent directory, and the old tests belong to `docs/archive/superdev/tests/`.
- ## Groups
+ ## Terms
- - **Interview / planning front ends** (model-invocable, main context): `intent`, `phases`,
- `superspec`, `superspec-refine`, `superplan`, `simpleplan`, `tdd`, `simpledebug`.
- - **Planning reviewers** (read-only forks, invoked only by their front end): `phases-reviewer`,
- `superspec-reviewer`, `superplan-reviewer`, `simpleplan-reviewer`.
- - **Build orchestrators** (main context): `superbuild` (Super track), `simplebuild` (Simple
- track). Every worker they dispatch is an agent - the build reviewers moved to `../agents/`
- with the rest, so no skill in this layer takes part in a build round.
- - **Support forks**: `executor` (runs one shell command out of context, returns a short
- verdict), `adr` (judges confirmed decisions against the three ADR criteria), `e2e` (user-only,
- generates/verifies Playwright tests from a QA handoff file).
- - **Memory and rules fronts**: `superdev-memory`, `superdev-rules`.
- - **User-only commands** (`disable-model-invocation: true`, never routed): `setup`, `e2e`.
+ - Simple track: `intent` -> `simpleplan` -> `simplebuild`. Spec track: `intent` -> `superspec` -> `superplan` -> `superbuild`. Phases track: `phases` cuts one intent into phase intents at `docs/.workflows/<run>/phases/<NN>-<slug>/intent.md`, and each phase then starts again with `intent` on one of the other two tracks.
+ - Run directory: `docs/.workflows/<date>-<slug>/`. It holds the run's `intent.md`, `refresh.md`, `spec.md` and `phases.md`.
- ## Contracts & invariants
+ ## Relationships
- - `allowed-tools` does NOT restrict the tool set - it is a one-turn permission pre-approval
- only. Every other tool stays in the model's pool and remains callable; an unlisted tool merely
- prompts the user and stalls the run. A strictly read-only worker needs `disallowed-tools:` in
- its frontmatter (bare tool names, never `Tool(pattern)`), plus an explicit body line naming
- its only tools - "read-only" in the frontmatter alone still leaves `git`/`ls`/`rg` looking
- allowed.
- - A skill that both `!`-preloads a script and denies bare `Bash` is undefined behavior. A
- strictly read-only worker takes its inputs as PATHS in `"$ARGUMENTS"` and reads them itself,
- with no preload.
- - Shell portability of `!` preloads (top trap, confirmed by the user): the host shell varies per
- machine (zsh/macOS, bash/Linux, bash-Git-Bash/Windows). Single-quote any argument bearing `?`,
- `*` or `[`. bash leaves an unmatched glob as a literal; zsh's default `nomatch` aborts the WHOLE
- command, killing the fork preload so it loads with no input - invisible on bash, only surfaces
- on zsh. Never rely on bash-only behavior; assume the strictest shell. No PowerShell syntax
- anywhere. No preload in the repo carries such an argument today (the optional-label
- `resolve-input.sh` that did is gone with the build reviewers), so `tests/portability.test.ts`
- is the only thing standing between a future author and this trap.
- - **Pre-approved bundled-script calls (preload and runtime).** A preload is permission-checked
- like any Bash call; a bare `Bash` entry in `allowed-tools` does NOT cover it. Both required:
- the skill's `allowed-tools` carries a PATTERN entry for the preload, and the bundled script is
- invoked DIRECTLY, never through an interpreter - so every preloaded script keeps its exec bit
- (`100755` in the git index) and its `#!/usr/bin/env bash` shebang. The same two requirements
- bind a runtime call - a bundled script a skill has the model run via the `Bash` tool
- mid-session, not as a preload: it is one literal line,
- `"${CLAUDE_PLUGIN_ROOT}/…/x.sh" <args>` (a `run.sh` call pipes its input through a heredoc on
- stdin instead of an arg), never prefixed with `bash`, never assigned to a variable, never
- preceded by `cd`, never chained with `;`; the skill declares one
- `Bash(${CLAUDE_PLUGIN_ROOT}/…/x.sh:*)` pattern per such script; the script itself keeps the
- same `100755` exec bit and `#!/usr/bin/env bash` shebang. Reason: the auto-mode permission
- classifier matches a command's literal prefix, so any other form of the same call - a
- different prefix, an added flag, an interpreter wrapper - is a new, unapproved
- classification.
- - `AskUserQuestion` takes at most FOUR options per question. A gate that has to offer more picks
- one of two shapes, never a fifth option: make two of them mutually exclusive by condition, or
- keep the least-used one out of the option list and name it in one prose line under the question
- (the user reaches it through **Other**). `intent`'s handoff gate is the worked example - Simple,
- Spec, Phases and `Stop here` fill exactly four slots, and Phases is offered only when the intent
- path has no `phases/` segment.
- - A worker must NEVER appear in both `plugin.json` `skills[]` and `agents[]`.
- - A user-only command (`disable-model-invocation: true`) does not participate in routing - that
- gap is deliberate, do not "fix" it.
- - superdev injects NOTHING at session start: there is no manifest and no `hooks/content/` dir
- (the `SessionStart` hook only prints the obsolescence banner). Routing lives entirely in each
- skill's own CSO `description:`, and standing rules belong to `viber`'s manifest, not here - do
- not reintroduce one.
+ - Who starts whom (the Skill tool): the `intent` handoff gate runs `simpleplan`, `superspec` or `phases` with `intent: <path>`. `simpledebug` hands a proven fix to `simpleplan`. `superspec-refine` runs `intent` over an existing spec. `intent` calls `adr` only when the config's `adr:` is `true`.
+ - Each reviewer (`phases-reviewer`, `simpleplan-reviewer`, `superspec-reviewer`, `superplan-reviewer`) is a forked, read-only skill. Only its own author skill invokes it.
+ - Agents dispatched: `simplebuild` uses `simplebuild-task-implementor` and `simplebuild-reviewer`. `superbuild` uses `superbuild-task-implementor`, `superbuild-task-reviewer`, `superbuild-reviewer-spec` and `superbuild-reviewer-change`. Both builders use `qa-writer`, `memory-writer`, `rules-writer` and `changelog-writer`. `superdev-memory` uses `memory-writer`, `superdev-rules` uses `rules-writer` and `e2e` uses `e2e-writer`.
+ - No skill calls `executor`. Plugin-level `scripts/run-gate.sh` runs `executor/scripts/run.sh` directly.
+ - Shared files: `phases` reads `intent/references/intent-template.md`. `simpleplan`, `superplan` and `simpleplan-reviewer` read `references/plan-review-checklist.md`. The plan authors and both builders read `references/review-contract.md`, and the plan authors also read `references/adr-task.md`.
+ - `intent`, `simplebuild` and `superbuild` preload `scripts/read-config.sh`, which reads the `.claude/superdev.yml` switches.
- ## Anti-patterns
+ ## Contracts
- - Adding, removing or renaming a skill without updating `superdev/.claude-plugin/plugin.json`
- `skills[]` and this node.
- - Restating a skill's full `# Input contract` here instead of pointing at its own body.
+ - Build routing: a plan's first line, `# SimplePlan` or `# SuperPlan`, and its second line naming `simplebuild` or `superbuild` come from `simpleplan/templates/plan.md` and `superplan/templates/plan.md`. The `review-plan.sh` hook checks that pair, and a builder starts only from an approved plan that names it.
+ - A plan author saves the plan to the path plan mode's own message gives and writes that path into the plan's `Plan:` line before review. It calls `ExitPlanMode` only after its reviewer returns `VERDICT: PASS`. Reviewer arguments are a labelled block of paths, never pasted content.
+ - Refresh gate: `intent` writes `refresh.md` beside every `intent.md` it writes. For an intent under `docs/.workflows/` with no `refresh.md`, `superspec` and `simpleplan` hand that path back to `intent` and stop. They check only that the file exists and never read it.
+ - The `Intent:` line carries through the Spec track: `superspec-refine` keeps the spec's `Intent:` line unchanged, and `superplan` copies it verbatim into the plan.
+ - Both builders carry `disallowed-tools: Edit, Write, NotebookEdit` and make every change through agents and the plugin-level scripts.
- ## Related context
+ ## Change together
- - Plugin-wide facts (config switches, knowledge layers, scripts): `../CLAUDE.md`
- - Agent layer: `../agents/CLAUDE.md`
- - Review vocabulary owner: `../references/review-contract.md`
+ - `setup/assets/config.yml` seeds `.claude/superdev.yml`, and its keys (`adr`, `rules`, `memory`, `changelog`, `cleanup`, `stats`, `qa`, `e2e-ui`, `e2e-api`) are the fixed key list in `scripts/read-config.sh`.
+ - `simplebuild/SKILL.md` and `superbuild/SKILL.md` repeat the same config, wave and cleanup steps. A fix to one applies to the other.