diff --git a/skills/plan-orchestrate/SKILL.md b/skills/plan-orchestrate/SKILL.md index 9145b5b65..0780ed566 100644 --- a/skills/plan-orchestrate/SKILL.md +++ b/skills/plan-orchestrate/SKILL.md @@ -1,105 +1,82 @@ --- name: plan-orchestrate -description: Read a plan document, decompose it into steps, design a per-step agent chain from the ECC catalogue, and emit ready-to-paste /orchestrate custom prompts. Generative only — never invokes /orchestrate itself. Use when the user has a multi-step plan and wants to drive it through orchestrate without composing chains by hand. +description: Read a plan document, decompose it into steps, classify each step, and emit ready-to-paste ECC slash commands from the current default command surface. Generative only — never invokes commands itself. Use when the user has a multi-step plan and wants the right command for each step without picking it by hand. metadata: origin: ECC --- # Plan Orchestrate -Bridge a plan document to `/orchestrate custom` by emitting one ready-to-paste invocation per step. The skill is generative only — it never executes `/orchestrate`. The user pastes each line when ready. +Bridge a plan document to the current ECC slash-command surface by emitting one ready-to-paste command per step. The skill is generative only — it never executes commands. The user pastes each line when ready. ## When to Activate -- User has a multi-step plan document (PRD, RFC, implementation plan) and wants to drive it through `/orchestrate`. -- User says "orchestrate this plan", "give me orchestrate prompts for each step", "compose chains for this plan". -- A step-by-step plan exists but the user does not want to manually pick agents per step. +- User has a multi-step plan document (PRD, RFC, implementation plan) and wants ready-to-paste commands for each step. +- User says "turn this plan into commands", "what command should I run for each step", "orchestrate this plan". +- A step-by-step plan exists but the user does not want to manually pick a command per step. Skip when: -- The work is one ad-hoc step → call `/orchestrate custom` directly. +- The work is one ad-hoc step → run the appropriate slash command directly (see the catalogue below). - The plan is unreadable or empty. Lack of explicit numbering alone is not a skip condition — see the "No clear steps" edge case below. +- The plan should run autonomously in the background → prefer `dmux-workflows` or the native `workflows/*.workflow.js` scripts instead. ## Inputs ``` - [--lang=python|typescript|go|rust|cpp|java|kotlin|flutter|auto] [--scope=all|step:|range:-] [--dry-run] + [--scope=all|step:|range:-] [--dry-run] ``` - `` — required; relative or absolute path (`@docs/...` accepted). -- `--lang` — reviewer language variant; defaults to `auto` (detected from project). - `--scope` — limits emitted steps; defaults to `all`. -- `--dry-run` — print decomposition + chain rationale only; do not emit final prompts. +- `--dry-run` — print decomposition + command rationale only; do not emit final commands. -## Authoritative `/orchestrate` shape (do not deviate) +## Authoritative output shape (do not deviate) ``` -{ORCH_CMD} custom ",,...," "" +/ "" ``` -Where `{ORCH_CMD}` is determined in Phase 0 (see below). The command string in the emitted output **always uses one concrete form** — never both, never a placeholder. +- The command must be one of the commands in the catalogue below. No `legacy-command-shims/` commands and no `/orchestrate` or `/ecc:orchestrate` — those are retired. +- One concrete command per step — never a placeholder or multiple forms. +- No `--mode`, `--gate`, `--agents=...`, or similar invented flags. +- Embedded double quotes in the task description are escaped as `\"`. +- The task description is 200–600 characters, one line, self-contained, and starts with `[Plan: #step-]`. -- `custom` is a sequential chain; each agent's HANDOFF feeds the next. -- Comma-separated agent list. No spaces preferred; one space tolerated. -- No `--mode` / `--gate` / `--agents=...` flags exist — never invent them. -- Agent names come from the catalogue in this skill. Embedded double quotes in the task description are escaped as `\"`. +## Command catalogue -## ECC install form and namespacing +Classify each step by its primary tag and emit the matching command. The command itself decides which agents and skills to run. -Two install forms determine the prefix on **both** the slash command and every agent name. The two MUST stay in sync — one form per output, never mixed: - -Let `` denote the Claude Code home directory: `~/.claude` on macOS/Linux, `%USERPROFILE%\.claude` on Windows. Resolve it the way the host platform resolves the user home directory (do not hardcode `~`). - -| Form | Detection | `{ORCH_CMD}` | Agent name format | +| Tag | Trigger words | Command | Why | |---|---|---|---| -| Plugin install (2.0.0+) | `/plugins/marketplaces/ecc/` exists | `/ecc:orchestrate` | `ecc:` | -| Legacy bare install | Above absent; agent files under `/agents/` | `/orchestrate` | `` | +| `design` | architecture, design, choose, evaluate, RFC | `/plan` | Needs human-approved implementation plan before code. | +| `plan` | plan, breakdown, milestone | `/plan` | Produces a step-by-step plan for approval. | +| `impl` | implement, build, add, create, port | `/orch-add-feature` | Net-new capability. | +| `fix` | fix, bug, broken, defect, repair, regression | `/orch-fix-defect` | Existing behavior is wrong. | +| `change` | change, alter, tweak, modify, behavior | `/orch-change-feature` | Existing working behavior should behave differently. | +| `refactor` | refactor, cleanup, dedupe, split, restructure | `/orch-refine-code` | Behavior-preserving restructure. | +| `migration` | migrate, upgrade, rewrite, port | `/orch-change-feature` | Replacing one implementation with another; if behavior must stay identical, classify as `refactor`. | +| `db` | schema, migration, index, SQL, Postgres, alembic, sqlmodel | `/orch-add-feature` | New schema/migration is a net-new capability in the current codebase. | +| `security` | encrypt, auth, secret, OWASP, PII, audit | `/security-scan` | Security review/audit when no `impl`/`fix` tag is primary. | +| `build` | build, compile, lint failure, CI | `/build-fix` | Fix build/type/lint errors. | +| `docs` | docs, readme, codemap, changelog | `/update-docs` | Update or add documentation. | +| `lookup` | lookup, reference, API usage | `/plan` | Research/lookup becomes a plan with findings. | +| `review` | review, audit, verify | `/code-review` | Review local uncommitted changes or a PR; pass the PR number in the task description for PR mode. | +| `test` | test, coverage, e2e, integration | `/test-coverage` | Add or analyze tests. | +| `loop` | loop, autonomous, watchdog | `/loop-start` | Start an autonomous loop. | -Why this matters: under the plugin install, agents register as `ecc:tdd-guide`. Bare names force fuzzy matching, which fails intermittently under parallel calls. Under legacy, the prefixed forms are not registered and fail outright. - -## Available agent catalogue (must pick from these) - -General: -- `planner` — requirement restatement, risk decomposition, step planning -- `architect` — architecture, system design, refactor proposals -- `tdd-guide` — write tests → implement → 80%+ coverage -- `code-reviewer` — generic code review -- `security-reviewer` — security audit, OWASP, secret leakage -- `refactor-cleaner` — dead code, duplicates, knip-class cleanup -- `doc-updater` — documentation, codemap, README -- `docs-lookup` — third-party library API lookups (Context7) -- `e2e-runner` — end-to-end test orchestration -- `database-reviewer` — PostgreSQL schema, migration, performance -- `harness-optimizer` — local agent harness configuration -- `loop-operator` — long-running autonomous loops -- `chief-of-staff` — multi-channel triage (rarely a fit for plan steps) - -Build error resolvers: -- `build-error-resolver` (generic) / `cpp-build-resolver` / `go-build-resolver` / `java-build-resolver` / `kotlin-build-resolver` / `rust-build-resolver` / `pytorch-build-resolver` - -Code reviewers: -- `python-reviewer` / `typescript-reviewer` / `go-reviewer` / `rust-reviewer` / `cpp-reviewer` / `java-reviewer` / `kotlin-reviewer` / `flutter-reviewer` - -A misspelled agent name fails `/orchestrate`. Cross-check against this list before emitting. +Tag resolution rules: +1. **Primary tag selection**: when a step matches multiple tags, the **first one in table order** (top of the table = highest priority) is the primary. The command for the primary tag is what gets emitted. +2. **Multi-tag notes**: write a one-line command rationale when a secondary tag meaningfully changes risk (for example, an `impl,security` step still emits `/orch-add-feature`, but the rationale notes that the security trigger will pull in `security-reviewer` automatically). +3. **Zero-tag steps**: default to `/code-review` and write the rationale `no tag matched; default review command`. +4. **Step with an explicit agent name**: if the plan text names an agent (for example, `tdd-guide`), map the step to the command that exercises that agent. For example, a step that says "write tests with tdd-guide" is an `impl` step → `/orch-add-feature`; a step that says "run python-reviewer over auth" is a `review` step → `/code-review` (or `/python-review` if the language is clearly Python). Do not emit raw agent names as commands. ## How It Works -### Phase 0 — Detect ECC mode + language +### Phase 0 — Read the plan 1. Read ``. If missing or empty, report and stop. -2. Detect ECC install form once and freeze it into `ECC_MODE`. Algorithm (run in order, stop at the first match): - 1. If `/plugins/marketplaces/ecc/` exists → `ECC_MODE=plugin`. - 2. Else if `/agents/` exists and contains at least one ECC agent file (e.g. `tdd-guide.md`, `code-reviewer.md`) → `ECC_MODE=legacy`. - 3. Else → default to `ECC_MODE=legacy` and emit a one-line warning at the top of the output: `> Warning: could not detect ECC install; defaulting to legacy form. If you use the plugin install, edit the prefixes manually.` - 4. If both markers exist (mixed install), `plugin` wins — the plugin namespace is the only one that resolves agent names without fuzzy matching. - - From this point on, every emitted line uses the matching prefix on **both** the slash command and every agent name. **Never emit both forms in the same output.** -3. Resolve `--lang`. When `auto`, run a polyglot-aware detection: - - Probe markers: `pyproject.toml` / `uv.lock` / `requirements.txt` → python; `package.json` → typescript; `go.mod` → go; `Cargo.toml` → rust; `CMakeLists.txt` or top-level `*.cpp` → cpp; `pom.xml` / `build.gradle` (Java) → java; `build.gradle.kts` or top-level Kotlin → kotlin; `pubspec.yaml` → flutter. - - **Polyglot tie-break**: if more than one marker matches, pick the language whose source files outnumber the others (count via `git ls-files`, excluding `vendor/`, `node_modules/`, `dist/`, `build/`, `.venv/`, generated files, and obvious test fixtures). On a tie or when no language exceeds 60% of source files, set `lang=unknown`. - - No marker matched → set `lang=unknown`. - - `lang=unknown` is a sentinel — it is **not** an agent name. Phase 2 rules 4 and 5 turn it into `code-reviewer` / `build-error-resolver` at chain composition time. -4. Detect a **PyTorch sub-profile**: when `lang=python` and any of `pyproject.toml` / `requirements.txt` / `uv.lock` declares a dependency on `torch`, set `pytorch=true`. This only affects `build` chain selection (Phase 2 rule below); the reviewer remains `python-reviewer`. -5. **Normalize any agent names declared in the plan**: if the plan text references agents by their plugin-prefixed form (e.g. `ecc:tdd-guide`), strip the prefix to get the bare catalogue name before validating or composing chains. Re-prefixing happens only at output time per `ECC_MODE` (Phase 4). Never let a pre-prefixed name flow into chain composition — it would double-prefix in plugin mode. +2. Optionally detect the dominant project language from markers (`pyproject.toml` / `uv.lock` / `requirements.txt` → python; `package.json` → typescript; `go.mod` → go; `Cargo.toml` → rust; `CMakeLists.txt` or top-level `*.cpp` → cpp; `pom.xml` / `build.gradle` → java; `build.gradle.kts` or top-level Kotlin → kotlin; `pubspec.yaml` → flutter). This is informational and can be included in the task description so the chosen command has context. +3. Normalize any agent names declared in the plan to tags or commands using the catalogue above. Never emit a bare agent name as the command. ### Phase 1 — Decompose steps @@ -112,76 +89,36 @@ Identify "step units" in priority order: Per step extract `id` (1-based), `title` (≤ 80 chars), `intent` (1–3 sentences), `tags`. -### Phase 2 — Tag and pick chain +### Phase 2 — Tag and pick command -Tag by intent (multi-tag allowed; chain built from primary + stacked secondaries): - -Trigger words below are matched case-insensitively. Multilingual plans are supported by matching the word stems in any language as long as the meaning aligns with the listed English trigger words. - -| Tag | Trigger words | Default chain | -|---|---|---| -| `design` | architecture, design, choose, evaluate, RFC | `planner,architect` | -| `plan` | plan, breakdown, milestone | `planner` | -| `impl` | implement, build, add, create, port | `tdd-guide,-reviewer` | -| `test` | test, coverage, e2e, integration | `tdd-guide,e2e-runner` | -| `refactor` | refactor, cleanup, dedupe, split | `architect,refactor-cleaner,-reviewer` | -| `migration` | migrate, upgrade, rewrite, port | `architect,tdd-guide,-reviewer` | -| `db` | schema, migration, index, SQL, Postgres, alembic, sqlmodel | `database-reviewer,-reviewer` | -| `security` | encrypt, auth, secret, OWASP, PII | `security-reviewer,-reviewer` | -| `build` | build, compile, lint failure, CI | `-build-resolver` (falls back to `build-error-resolver`) | -| `docs` | docs, readme, codemap, changelog | `doc-updater` | -| `lookup` | lookup, reference, API usage | `docs-lookup` | -| `review` | review, audit, verify | `-reviewer,code-reviewer` | -| `loop` | loop, autonomous, watchdog | `loop-operator` | - -Chain composition rules: -1. **Primary tag selection**: when a step matches multiple tags, the **first one in table order** (top of the table = highest priority) is the primary; the rest are secondaries. Composition rules 2 and 3 below handle specific multi-tag combinations explicitly; otherwise, append secondary chains in tag table order. -2. `impl` + `security` → `tdd-guide,-reviewer,security-reviewer`. -3. `impl` + `db` → `tdd-guide,database-reviewer,-reviewer`. -4. **Deduplicate** the resulting chain (preserve first occurrence). E.g. `review` + `lang=unknown` would yield `code-reviewer,code-reviewer` after rule 5; deduplication collapses it to `code-reviewer`. -5. `-reviewer` resolves to `code-reviewer` when `lang=unknown`. -6. `-build-resolver` resolves to `build-error-resolver` when `lang=unknown`. **Special case**: if Phase 0 set `pytorch=true`, use `pytorch-build-resolver` for `build` chains regardless of ``. There is no `python-build-resolver`; `--lang=python` without `pytorch=true` resolves to `build-error-resolver`. -7. **Zero-tag steps**: if no trigger word matches, set chain to `code-reviewer` and write `no tag matched; default review-only chain` under "Chain rationale". -8. Chain length ≤ 4 after deduplication. If exceeded, drop weakest tag (`lookup` and `docs` first). -9. Do not pair `planner` and `architect` in an `impl` chain (token waste). Pair them only on `design` steps. -10. Steps tagged `impl`, `refactor`, or `migration` end with a **reviewer-class** agent — any of `-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`. The most domain-specific reviewer wins the tail position (e.g. rule 2's `impl+security` ends with `security-reviewer`; rule 3's `impl+db` ends with `-reviewer` because `database-reviewer` already gates the migration earlier in the chain). `test` and `build` steps are gated by their own validators (`e2e-runner` and the build resolver respectively) and do not require an additional reviewer. +Use the catalogue above. The output of this phase is a single command per step, not an agent chain. The command itself runs the right agent pipeline. ### Phase 3 — Compress task description Each emitted `` must: -- Be self-contained (the first agent does not need the plan document open). + +- Be self-contained (the command does not need the plan document open). - Start with `[Plan: #step-]`. -- Include 1–3 verifiable Acceptance criteria. +- Include 1–3 verifiable acceptance criteria. - Include a Scope guard (`Out of scope: ...`) **only if the plan declares one for this step**. Inherit verbatim. If the plan has no out-of-scope statement, omit the clause entirely — do not invent one. - Be 200–600 characters; one line; embedded `"` escaped as `\"`; no literal newlines. ### Phase 4 — Output -Emit Markdown using **the form determined by `ECC_MODE`**. The output uses one form throughout — every `{ORCH_CMD}` and every agent name is rendered with the matching prefix from Phase 0. **Do not emit both forms; do not include "this is plugin form" / "strip the prefix" instructions in the rendered output.** - -Concrete rendering rules: - -- `{ORCH_CMD}` = `/ecc:orchestrate` under `plugin`, `/orchestrate` under `legacy`. -- `{AGENT(name)}` = `ecc:` under `plugin`, `` under `legacy`. -- The overview-table "Chain" column uses the same `{AGENT(name)}` rendering. -- Per-step bash blocks contain only the runnable command. **No `# plugin form` or `# legacy form` comments** — the form is implicit and uniform across the whole output. - -Output structure: +Emit Markdown: ````markdown # Plan-Orchestrate Result **Plan**: `` -**Lang**: `` -**ECC mode**: `` **Steps**: **Scope**: ## Steps overview -| # | Title | Tags | Chain | +| # | Title | Tags | Command | |---|---|---|---| -| 1 | ... | impl, db | `{AGENT(tdd-guide)},{AGENT(database-reviewer)},{AGENT(python-reviewer)}` | +| 1 | ... | impl, security | `/orch-add-feature` | | ... | | | | --- @@ -190,29 +127,21 @@ Output structure: **Intent**: <1–3 sentences> **Tags**: -**Chain rationale**: +**Command rationale**: ```bash -{ORCH_CMD} custom "{AGENT(tdd-guide)},{AGENT(database-reviewer)},{AGENT(python-reviewer)}" "[Plan: docs/foo.md#step-1] ; Acceptance: <1–3 items>; Out of scope: <…>" +/orch-add-feature "[Plan: docs/foo.md#step-1] ; Acceptance: <1–3 items>; Out of scope: <…>" ``` ```` -> The `{ORCH_CMD}` and `{AGENT(...)}` notation above describes the substitution this skill performs at runtime. The actual emitted Markdown contains the resolved strings, never the placeholders. - Append a final "Batch execution" block aggregating every step's command in order so the user can paste them all at once. **Skip the Batch block in overview-only mode** (see "Large plan" edge case): when only the overview table is being emitted, there are no per-step commands to aggregate. ### Phase 5 — Self-check (run before emitting) -- [ ] Every agent in every chain comes from the catalogue (after stripping any `ecc:` prefix that appeared in the plan; see Phase 0 step 5). -- [ ] Resolved `{ORCH_CMD}` and every resolved `{AGENT(...)}` use the **same** form (`plugin` or `legacy`) — never mixed in one output. -- [ ] No `# plugin form` / `# legacy form` annotations and no "strip the prefix" instructions remain in the rendered output. -- [ ] No invented `--mode` / `--gate` / `--agents=...` fields. +- [ ] Every command is from the catalogue above; no `/orchestrate`, `/ecc:orchestrate`, or legacy-shim command appears in the rendered output. +- [ ] No invented `--mode`, `--gate`, or `--agents=...` fields. - [ ] Each task description is single-line, double-quoted, with embedded `"` escaped. - [ ] Each task description begins with `[Plan: #step-]` and includes Acceptance (1–3 items). The `Out of scope:` clause is present only when inherited from the plan. -- [ ] No duplicate agent in any chain after Phase 2 dedup. -- [ ] Chain length ≤ 4. -- [ ] Steps tagged `impl`/`refactor`/`migration` end with a reviewer-class agent (`-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`). `test` and `build` are exempt — see Phase 2 rule 10. -- [ ] Zero-tag steps emit `code-reviewer` with the rationale `no tag matched; default review-only chain`. - [ ] Overview table lists every step in the plan, regardless of `--scope`. - [ ] Per-step detail block count matches the resolved `--scope` (full plan when `--scope=all`; one block for `step:n`; range size for `range:a-b`). In overview-only mode, no per-step blocks and no Batch block are emitted. @@ -220,44 +149,43 @@ Append a final "Batch execution" block aggregating every step's command in order - **No clear steps**: prefer H2/H3 splitting; if still ambiguous, report "no structured steps detected" with the document outline and ask the user to confirm running by outline. - **Large plan (>1500 lines)**: enter **overview-only mode** — emit only the overview table and ask the user to narrow with `--scope` before re-running for details. In this mode, skip per-step detail blocks and skip the Batch execution block. -- **Step too broad** (e.g. "complete all backend work"): do not force a single chain. Suggest splitting into N.a and N.b and propose a split. -- **Plan declares agents** (rare): first **strip any `ecc:` prefix** to get the bare catalogue name (Phase 0 step 5), then validate against the catalogue. Replace invalid agents and explain under "Chain rationale". The bare name is re-prefixed at output time per `ECC_MODE`. -- **Polyglot project where `--lang=auto` cannot pick a winner**: set `lang=unknown`; reviewer resolves to `code-reviewer` and build resolver to `build-error-resolver`. Mention the fallback under "Chain rationale". +- **Step too broad** (e.g. "complete all backend work"): do not force a single command. Suggest splitting into N.a and N.b and propose a split. +- **Polyglot project**: mention the detected languages in the rationale and default the command to the generic form (`/orch-add-feature`, `/code-review`, etc.). Do not emit a language-specific command unless the language is clear from the step's scope. ## Examples ### Example 1 — Plugin mode, Python plan Input: + ``` -plan-orchestrate @docs/plan/example-feature.md --lang=python +plan-orchestrate @docs/plan/example-feature.md ``` Excerpt of expected output: + ````markdown ## Step 2 — Encrypt sensitive UserProfile fields **Intent**: Introduce an `EncryptedString` SQLAlchemy type and AES-GCM encrypt `birth_datetime` / `location` before persistence; load the key from an environment variable. **Tags**: impl, security, db -**Chain rationale**: Security-sensitive write path, so `security-reviewer` closes the chain; `database-reviewer` validates the alembic migration; `python-reviewer` covers typing and PEP 8. +**Command rationale**: Security-sensitive write path, so `/orch-add-feature` will run `tdd-guide`, then `database-reviewer` for the alembic migration, then `python-reviewer`, and finally `security-reviewer` because the security trigger is touched. ```bash -/ecc:orchestrate custom "ecc:tdd-guide,ecc:database-reviewer,ecc:python-reviewer,ecc:security-reviewer" "[Plan: docs/plan/example-feature.md#step-2] Implement EncryptedString SQLAlchemy type and migrate UserProfile.birth_datetime/location columns; key from ENV APP_DB_KEY; Acceptance: encrypt/decrypt roundtrip tests pass; alembic upgrade/downgrade clean on empty DB; no plaintext in DB after migrate; Out of scope: cross-tenant profile sharing logic" +/orch-add-feature "[Plan: docs/plan/example-feature.md#step-2] Implement EncryptedString SQLAlchemy type and migrate UserProfile.birth_datetime/location columns; key from ENV APP_DB_KEY; Acceptance: encrypt/decrypt roundtrip tests pass; alembic upgrade/downgrade clean on empty DB; no plaintext in DB after migrate; Out of scope: cross-tenant profile sharing logic" ``` ```` -### Example 2 — Legacy mode, same step +### Example 2 — Fix step -If `ECC_MODE=legacy` were detected, the same step would be emitted as a single uniform command (no plugin-prefixed forms anywhere in the output): +If a step reads "Fix the poller crash on empty NWS response", it is tagged `fix` and emits: ```bash -/orchestrate custom "tdd-guide,database-reviewer,python-reviewer,security-reviewer" "[Plan: docs/plan/example-feature.md#step-2] ..." +/orch-fix-defect "[Plan: docs/plan/example-feature.md#step-5] Fix poller crash on empty NWS response; Acceptance: reproduce crash with a failing regression test; fix makes the test pass; review the diff for error-handling gaps" ``` -The two examples above illustrate **the two possible outputs** for two different environments. A single skill invocation produces only one of them, end to end. - ## Notes -- Generative only. Never invoke `/orchestrate` from inside this skill. -- Match the language of the plan document for task descriptions (agent names always remain English). +- Generative only. Never invoke `/orch-add-feature`, `/code-review`, or any other command from inside this skill. +- Match the language of the plan document for task descriptions. - Do not insert "Co-Authored-By" lines or emoji in the output unless the user explicitly asks.