diff --git a/skills/plan-orchestrate/SKILL.md b/skills/plan-orchestrate/SKILL.md index e7e05053d..5d6693d5b 100644 --- a/skills/plan-orchestrate/SKILL.md +++ b/skills/plan-orchestrate/SKILL.md @@ -9,7 +9,7 @@ metadata: 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 +## When to Use - 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". @@ -54,7 +54,7 @@ For these commands, do **not** pass the full task description as a quoted argume | Command | Output form | Notes | |---|---|---| | `/build-fix` | `/build-fix` | Detects and fixes the current project’s build errors. | -| `/code-review` | `/code-review` for local uncommitted changes; `/code-review ` if the step references a PR | Without a PR, reviews the current diff. | +| `/code-review` | `/code-review` for local uncommitted changes; `/code-review `; or `/code-review ` if the step references a PR | A number or URL is used as-is; without one, reviews the current diff. | | `/loop-start` | `/loop-start sequential --mode safe` | Default pattern; use `rfc-dag` only when the step explicitly describes a DAG-style loop. | | `/security-scan` | `/security-scan` or `/security-scan ` | Default path is the project root. Only pass a path if the step names a specific directory. | | `/test-coverage` | `/test-coverage` | Analyzes and improves project-wide coverage. | @@ -79,9 +79,9 @@ Classify each step by its primary tag and emit the matching command. The command | `migration` | migrate, upgrade, rewrite, port | `/orch-change-feature` | `/ ""` | Replacing one implementation with another; if behavior must stay identical, classify as `refactor`. | | `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. | -| `review` | review, audit, verify | `/code-review` | `/code-review` or `/code-review ` | Review local uncommitted changes or a PR. | +| `review` | review, audit, verify | `/code-review` | `/code-review`; `/code-review `; or `/code-review ` | Review local uncommitted changes or a PR. | | `security` | encrypt, auth, secret, OWASP, PII, audit | `/security-scan` | `/security-scan` or `/security-scan ` | Security review/audit when no `impl`/`fix` tag is primary. | -| `impl` | implement, build, add, create, port | `/orch-add-feature` | `/ ""` | Net-new capability. | +| `impl` | implement, add, create | `/orch-add-feature` | `/ ""` | Net-new capability. | | `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. | | `lookup` | lookup, reference, API usage | `/plan` | `/ ""` | Research/lookup becomes a plan with findings. | @@ -89,24 +89,27 @@ Classify each step by its primary tag and emit the matching command. The command | `loop` | loop, autonomous, watchdog | `/loop-start` | `/loop-start sequential --mode safe` | Start an autonomous loop. | Tag resolution rules: -1. **Primary tag selection**: a step may match multiple tags. Pick the primary tag using the **precedence order below** (highest first). The command for the primary tag is what gets emitted; the agent chain is composed from the primary and any secondary tags. -2. **Precedence order**: - 1. `build` — when the step is about build/compile/lint/CI failure or build-system work. Beats `fix`: "fix the build error" → `/build-fix`. - 2. `fix` — when existing behavior is broken/wrong and the domain is not `build`/`test`/`db`/`migration`. Example: "fix the poller crash" → `/orch-fix-defect`. Beats `impl` and `test`: "fix the broken test" → `/orch-fix-defect` (not `/test-coverage`). - 3. `test` — when the step is about adding or analyzing tests/coverage/e2e, and not fixing a broken test. Beats `impl`: "add tests for the parser" → `/test-coverage`. - 4. `db` — when the step is about schema/migration/index and not fixing existing behavior. Beats `impl`: "add a users index" → `/orch-add-feature`. - 5. `migration` — when the step is about porting/upgrading/rewriting and not fixing existing behavior. Beats `impl`: "port the service to Go" → `/orch-change-feature`. - 6. `change` — when working behavior should change and the domain is not covered above. - 7. `refactor` — when behavior-preserving restructure and the domain is not covered above. - 8. `review` — when the step is about reviewing/auditing code or a PR. Beats `security` for general code audits: "audit the code" → `/code-review`. - 9. `security` — when the step is about hardening a security control (encrypt, auth, secrets, PII). Use this over `review` when the audited object is a security control: "audit the encryption module" → `/security-scan`. - 10. `impl` — net-new capability; default when the step matches only broad verbs like "implement", "add", "create". Example: "implement OAuth2 login" → `/orch-add-feature`. - 11. `design`, `plan`, `lookup` — planning/research. - 12. `docs` — documentation. - 13. `loop` — autonomous loop. -3. **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`; the rationale notes that the composed chain ends with `security-reviewer`). -4. **Zero-tag steps**: chain is `code-reviewer`; command is `/code-review`; rationale `no tag matched; default review-only chain`. -5. **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 "add tests with tdd-guide" is a `test` step → `/test-coverage`; 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. +1. **Primary tag selection**: a step may match multiple tags. Pick the primary tag using the **precedence order below** (highest first) and the **special-case overrides** that follow it. The command for the primary tag is what gets emitted; the agent chain is composed from the primary and any secondary tags. +2. **Precedence order** (highest first): + 1. `build` + 2. `fix` + 3. `test` + 4. `db` + 5. `migration` + 6. `change` + 7. `refactor` + 8. `review` + 9. `security` + 10. `impl` + 11. `design`, `plan`, `lookup` + 12. `docs` + 13. `loop` +3. **Special-case overrides** (override the numeric precedence for the stated pairs): + - `impl` + `security`: primary is `impl`. The command is `/orch-add-feature`; the chain includes `security-reviewer` as a secondary agent. This prevents net-new feature work from being reduced to a scan. + - `review` + `security`: if the audited object is a security control (encryption, auth, secrets, PII, OWASP), primary is `security`; otherwise primary is `review`. +4. **Multi-tag notes**: write a one-line command rationale when a secondary tag meaningfully changes risk (for example, an `impl,security` step emits `/orch-add-feature`; the rationale notes that the composed chain ends with `security-reviewer`). +5. **Zero-tag steps**: chain is `code-reviewer`; command is `/code-review`; rationale `no tag matched; default review-only chain`. +6. **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 "add tests with tdd-guide" is a `test` step → `/test-coverage`; a step that says "run python-reviewer over auth" is a `review` step → `/python-review` if a matching `/python-review` command exists in `commands/`, otherwise `/code-review`. Do not emit raw agent names as commands. ### Agent chain catalogue @@ -114,14 +117,14 @@ The skill still composes the per-step agent chain. The chain is then mapped to t | Tag | Default agent chain | |---|---| -| `build` | `-build-resolver` (falls back to `build-error-resolver` when `lang=unknown`; `pytorch-build-resolver` when `pytorch=true`) | +| `build` | `build-error-resolver` (use `-build-resolver` only when a matching language-specific build command is the emitted command) | | `fix` | `tdd-guide, -reviewer` | | `test` | `tdd-guide, e2e-runner` | | `db` | `tdd-guide, database-reviewer, -reviewer` | | `migration` | `architect, tdd-guide, -reviewer` | | `change` | `tdd-guide, -reviewer` | | `refactor` | `architect, refactor-cleaner, -reviewer` | -| `review` | `-reviewer, code-reviewer` | +| `review` | `code-reviewer` (use `-reviewer` only when a matching language-specific review command like `/python-review` is the emitted command) | | `security` | `security-reviewer, -reviewer` | | `impl` | `tdd-guide, -reviewer` | | `design` | `planner, architect` | @@ -132,14 +135,14 @@ The skill still composes the per-step agent chain. The chain is then mapped to t #### Chain composition rules -1. **Base chain**: start with the primary tag's default chain. -2. **Multi-tag append**: for each secondary tag, append its unique, non-overlapping agents in catalogue order. +1. **Base chain**: start with the primary tag's default chain, with `` resolved. +2. **Multi-tag append**: for each secondary tag, append its unique, non-overlapping agents in catalogue order, before the base chain's tail reviewer. - `impl` + `security` → `tdd-guide, -reviewer, security-reviewer`. - `impl` + `db` → `tdd-guide, database-reviewer, -reviewer`. 3. **Deduplicate** the resulting chain, preserving first occurrence. -4. **`` resolution**: `-reviewer` → `code-reviewer` when `lang=unknown`. `-build-resolver` → `build-error-resolver` when `lang=unknown`; use `pytorch-build-resolver` when `pytorch=true`. -5. **Chain length ≤ 4** after deduplication. If exceeded, drop `lookup` and `docs` first. -6. **Reviewer-class tail**: steps tagged `impl`, `refactor`, or `migration` must end with a reviewer-class agent (`-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`). The most domain-specific reviewer wins the tail position. +4. **`` resolution**: `-reviewer` → `code-reviewer` when `lang=unknown` or when no `-reviewer` agent exists. `-build-resolver` → `build-error-resolver` when `lang=unknown` or when no `-build-resolver` agent exists; use `pytorch-build-resolver` when `pytorch=true`. +5. **Chain length ≤ 4** after deduplication. If exceeded, drop lower-priority agents first: `lookup` and `docs`, then non-reviewer planning/build agents that are not required by the primary tag, then the least-specific reviewer if a more specific reviewer is already present. +6. **Reviewer-class tail**: after appending, deduplication, and capping, the chain must end with a reviewer-class agent (`-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`). The most domain-specific reviewer wins the tail position. If the chain would end with a non-reviewer (e.g., `architect` appended by a `migration` secondary on a `db` primary), move the most domain-specific reviewer to the end. If the chain is now too long, drop the lowest-priority non-reviewer first, but always keep a reviewer tail. 7. **Zero-tag steps**: chain is `code-reviewer`; command is `/code-review`. ## How It Works @@ -147,7 +150,7 @@ The skill still composes the per-step agent chain. The chain is then mapped to t ### Phase 0 — Read the plan 1. Read ``. If missing or empty, report and stop. -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 used to resolve `-reviewer` and `-build-resolver` in the agent chain. It can also be included in the task description so the chosen command has context. +2. Optionally detect the dominant project language from markers (`pyproject.toml` / `uv.lock` / `requirements.txt` → python; `package.json` → node (resolve to `typescript` only when `tsconfig.json`, TypeScript source files, or an explicit TypeScript dependency is present; otherwise `javascript` or `unknown` if no such marker); `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 used to resolve `-reviewer` and `-build-resolver` in the agent chain. If a `-reviewer` or `-build-resolver` agent does not exist for the detected language, fall back to `code-reviewer` or `build-error-resolver`. It can also 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 @@ -180,6 +183,8 @@ For commands that take a quoted task description, each emitted `#step-]` and includes Acceptance (1–3 items). The `Out of scope:` clause is present only when inherited from the plan. +- [ ] Each quoted task description is 200–600 characters and does not request secret access, unapproved tool use, destructive operations, or data exfiltration. - [ ] Commands that run self-contained use the bare or flag form from the catalogue; the step context is in the command rationale, not a forced quoted argument. - [ ] 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.