diff --git a/plugins/corbits-skills/skills/docs/SKILL.md b/plugins/corbits-skills/skills/docs/SKILL.md index 76147fdda..f6147c613 100644 --- a/plugins/corbits-skills/skills/docs/SKILL.md +++ b/plugins/corbits-skills/skills/docs/SKILL.md @@ -7,6 +7,8 @@ description: Maintain product, architecture, and implementation docs and detect Route what the operator tells you into the right document, then find the gaps it leaves and ask about them. This is not a filing system: recording the input is half the job. +Dispatch owns classification, operator questions, and synthesis. `spawn_agent(agent="shakespeare")` owns substantive documentation authorship and cross-document consistency; only obvious mechanical corrections may be DIY. Give shakespeare the input, relevant document paths and context, `success_criteria` covering the steps below, `do_not` forbidding product-code changes or unapproved document creation, and `report_focus` requesting contradictions and gaps. Workers start blank; include the applicable instructions. After operator answers, resume shakespeare with those decisions rather than taking over its edits. + ## Documents Look for `PRODUCT.md`, `ARCHITECTURE.md`, and `IMPLEMENTATION.md` (case-insensitive) in the repo root and `docs/`. Prefer the root when both exist. Create missing ones in the root after confirming with `ask_operator`. @@ -17,7 +19,7 @@ Look for `PRODUCT.md`, `ARCHITECTURE.md`, and `IMPLEMENTATION.md` (case-insensit | Architecture | Structure: components, interfaces, data and control flow, technology-agnostic decisions | parts and how they interact | | Implementation | Concrete choices: technologies, protocols, formats, config, deployment | "uses", "built on", named libraries | -Read the existing documents first. Their vocabulary beats the general signals above: a term the architecture doc already owns routes to architecture. +Have shakespeare read the existing documents first. Their vocabulary beats the general signals above: a term the architecture doc already owns routes to architecture. ## Steps diff --git a/plugins/corbits-skills/skills/implement/SKILL.md b/plugins/corbits-skills/skills/implement/SKILL.md index e08680824..2c51c2c3b 100644 --- a/plugins/corbits-skills/skills/implement/SKILL.md +++ b/plugins/corbits-skills/skills/implement/SKILL.md @@ -8,10 +8,12 @@ argument-hint: "[ticket-id]" Take a plan and a ticket to a pushed branch. Each commit is built, gated, and reviewed before the next one starts. `/implement` does not plan; `/plan` and `/issue` come first. +Dispatch coordinates the worktree, ticket, commits, findings dispositions, and handoff. Substantive work belongs to named specialists even when it changes one file or Dispatch already explored the area. Workers start blank: give each the worktree, relevant plan and context, `success_criteria`, `do_not`, and `report_focus`; do not assume they inherited this skill. + ## 1. Preflight - Requires a git repo. Run `git rev-parse --show-toplevel`; if it fails, stop and tell the operator to `git init` first. -- Requires a plan (files, acceptance criteria, non-goals, risks, ordered steps) and a ticket. If either is missing, stop and point to `/plan` or `/issue`. A tiny change the primary does itself may skip the plan but not the ticket. +- Requires a plan (files, acceptance criteria, non-goals, risks, ordered steps) and a ticket. If either is missing, stop and point to `/plan` or `/issue`. An obvious mechanical correction needing no diagnosis, design, new behavior, or new tests may skip the plan but not the ticket. - When the ticket is in Linear and Linear MCP is mounted, set it to In Progress now. If MCP is missing, say the status could not be updated. ## 2. Worktree @@ -25,10 +27,10 @@ Track the commit-sized units of the plan with `manage_tasks`. For each unit, in order: 1. **Approach.** For anything non-trivial, describe the approach to `spawn_agent(agent="planner")`: what changes and why, files touched, trade-offs, uncertainties. Adjust for real problems; disagree only with a reason. -2. **Implement and test.** Follow the repo's test conventions. Bug fixes start with a test that fails for the right reason, then the fix. Features get a test that asserts the designed behavior. The test lands in the same commit as the code, and so do doc updates the change requires. Keep scope to the unit; note other work for a later commit. -3. **Build gate.** Run the project's full pipeline (format, lint, build, test), never a partial one. Fix failures you caused. Report pre-existing failures to the operator. Record the commands and exit statuses. +2. **Implement and test.** `spawn_agent(agent="coder")` owns the unit's implementation and tests. Its brief requires the repo's test conventions: bug fixes start with a test that fails for the right reason, then the fix; features assert observable behavior. Tests and code-attached doc updates land with the code. Spawn `shakespeare` for required standalone product/architecture/implementation docs, after coder when the docs depend on its changes; do not assign concurrent writers to overlapping files. Keep scope to the unit; note other work for a later commit. Only an obvious mechanical correction under the Dispatch boundary may be DIY. +3. **Build gate.** Coder runs the project's full pipeline (format, lint, build, test) after all edits, never a partial one. Resume coder to fix failures it caused and rerun the gate after any later specialist edits. Dispatch checks the exact commands and exit statuses in the report and surfaces pre-existing failures; missing evidence is not a passing gate. 4. **Commit.** Follow `CONTRIBUTING.md` for the subject and body. No ticket ids or AI attribution in commit messages. -5. **Reviewer loop.** `spawn_agent(agent="reviewer")` on `git show HEAD` with the intent from step 1, limited to this commit's scope. Fix every verified or high-confidence finding, re-run the build gate, and amend (or `git rebase -i` with `edit` for an earlier commit). Repeat until clean or until what remains is a conscious decision, not an oversight. +5. **Reviewer loop.** `spawn_agent(agent="reviewer")` on `git show HEAD` with the intent from step 1, limited to this commit's scope. Route every verified or high-confidence finding back to coder (or shakespeare for docs), rerun the build gate, and amend (or `git rebase -i` with `edit` for an earlier commit). Dispatch does not take over the fix. Repeat until clean or until what remains is a conscious decision, not an oversight. The build must pass before every commit, amend, and rebase stop. diff --git a/plugins/corbits-skills/skills/plan/SKILL.md b/plugins/corbits-skills/skills/plan/SKILL.md index 5320cb1ad..a56c39abd 100644 --- a/plugins/corbits-skills/skills/plan/SKILL.md +++ b/plugins/corbits-skills/skills/plan/SKILL.md @@ -9,7 +9,7 @@ How to produce an engineering change plan. Does not implement. Does not file tra Requires a git repo. Run `git rev-parse --show-toplevel`; if it fails, stop and tell the operator to `git init` first. -If the change target is too fuzzy to plan, `ask_operator` first. To learn the code before planning, use `spawn_agent(agent="explorer")`; to pressure-test the approach, `spawn_agent(agent="planner")`. +If the change target is too fuzzy to plan, `ask_operator` first. Dispatch owns clarification and synthesis, not substantive plan authorship. Use `spawn_agent(agent="explorer")` for broader codebase mapping when needed, then `spawn_agent(agent="planner")` to author the plan and pressure-test the approach. Give planner the operator's requirements, explorer findings, relevant paths, output location, `success_criteria` covering the five sections below, `do_not` forbidding implementation and ticket creation, and `report_focus` naming decisions and blockers. Workers start blank; include the applicable instructions rather than assuming they inherited this skill. ## What the plan must contain @@ -24,7 +24,7 @@ When requirements are fuzzy, put open questions under Blockers instead of invent ## What this is not - Not `/issue`. If the operator wants tickets, they use `/issue` after the plan. -- Not an architecture gate. Planner reviews approach; this skill only authors the plan. +- Not an implementation gate. Planner authors the plan and reviews its approach; Dispatch presents it and resolves operator questions. - Not implementation. Do not ship the change. The plan is the input to `/issue` (the ticket) and `/implement` (which needs both). End by telling the operator the next step. diff --git a/plugins/corbits-skills/skills/refactor/SKILL.md b/plugins/corbits-skills/skills/refactor/SKILL.md index c47309f48..310ae4807 100644 --- a/plugins/corbits-skills/skills/refactor/SKILL.md +++ b/plugins/corbits-skills/skills/refactor/SKILL.md @@ -8,6 +8,8 @@ description: Document a directory's design and plan improvements with the operat Analyze existing code, document its design, and agree an improvement plan with the operator. This skill does not change code: the plan is executed later through `/plan` and `/implement`. +Dispatch owns scope clarification and the operator discussion. Spawn `explorer` for substantive directory mapping, then `planner` for design-analysis document and improvement-plan authorship. Each worker starts blank: give it the worktree, scoped paths, relevant context or preceding report, `success_criteria` covering its steps below, `do_not` forbidding product-code changes, and `report_focus` requesting evidence and open questions. Pass the document output path to planner. Resume planner with operator decisions instead of writing the analysis or plan yourself. + ## Preflight Requires a git repo. Run `git rev-parse --show-toplevel`; if it fails, stop and tell the operator to `git init` first. Work in a worktree from `origin/`, never in the main checkout: `use_skill("git-worktrees")` for the commands. @@ -25,7 +27,7 @@ If the directory is broad, ask clarifying questions: ### Step 2: Examine the Code -Explore the specified directory to understand: +Have `spawn_agent(agent="explorer")` map the specified directory to understand: - What the code does (purpose and behavior) - Key components and their responsibilities - How data flows through the system @@ -35,7 +37,7 @@ Explore the specified directory to understand: ### Step 3: Document Current Design -Write a structured markdown document to the current working directory. Choose a filename that reflects what was analyzed. +Have `spawn_agent(agent="planner")` write a structured markdown document to the worktree, using explorer's report and a filename that reflects what was analyzed. Document structure: @@ -63,7 +65,7 @@ After documenting the current state: ### Step 5: Write the Plan -Append an **Improvement Plan** section to the document with: +Resume planner with the agreed decisions to append an **Improvement Plan** section to the document with: - Specific changes to make - Rationale for each change diff --git a/plugins/corbits-skills/skills/review/SKILL.md b/plugins/corbits-skills/skills/review/SKILL.md index cdc58f97e..2d6aaad91 100644 --- a/plugins/corbits-skills/skills/review/SKILL.md +++ b/plugins/corbits-skills/skills/review/SKILL.md @@ -18,6 +18,8 @@ Requires a git repo. Run `git rev-parse --show-toplevel`; if it fails, stop and The primary dispatches with `spawn_agent`, one target per wave: `reviewer` always, `planner` when architecture, API, or approach is at stake, `designer` or `warden` only when the touched files warrant that lens (UI surface, security-sensitive code). Do not fan out a default wide fleet. +Reviewer owns the code-defect analysis and code verdict. Dispatch owns target resolution, the metadata checks below, findings dispositions, and synthesis; it does not redo the file-by-file review. Workers start blank: supply the worktree, scoped diff, intent, relevant context, `success_criteria`, `do_not` forbidding product fixes, and `report_focus` requiring concrete findings and verification evidence. + ## 2. Resolve the target and base For a PR (number, URL, or branch), review from a worktree, never the local checkout: @@ -38,7 +40,7 @@ When delegating, give the sub-agent `git diff ...HEAD -- `, not whol ## 4. Reviewer-of-record checks -The agent whose verdict ships runs these itself and reads the raw output. They are not delegable; a delegate collapses `Bin 0 -> 8181 bytes` on a `.ts` file into noise. +Dispatch runs these metadata checks itself and reads the raw output. They are not delegable; a delegate collapses `Bin 0 -> 8181 bytes` on a `.ts` file into noise. These checks complement reviewer's code verdict; they do not authorize Dispatch to take over behavioral review. - `git diff ...HEAD --stat`: look for `Bin` markers on files that should be text, and files outside the stated scope. - `git log --oneline ..HEAD`: commits must match the ticket's scope.