diff --git a/README.md b/README.md index b11a07f0..44c32135 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 7 plugins · 40 skills · 3 agents · MIT + 7 plugins · 41 skills · 2 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -189,7 +189,7 @@ Commits, pull / merge requests, release tags, issue creation. ### 📋 [aidd-pm](plugins/aidd-pm/README.md) -`4 skills` · stable +`5 skills` · stable Ticket info, user stories, PRD, spec drafting. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..709cda3c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -124,6 +124,20 @@ flowchart LR Each action is a self-contained markdown file with inputs, outputs, depends-on, process steps, and a test checklist. Actions can call other skills via the `Skill` tool, so a skill discovers a capability it needs at runtime (by matching skill descriptions, never by hardcoded plugin name) and delegates to it. +## Skills and agents + +- A **skill** is a caller-agnostic recipe; it runs in the context of whoever invokes it. +- An **agent** is an isolated executor; it runs in its own context and returns only a result. + +Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent. + +Composition rules: + +- **Spawning is an orchestration decision, never a skill's.** A recipe skill never spawns an agent; it runs in the caller's context. Only a high-level orchestrator skill (for example the SDLC) spawns agents, and it decides per step whether to isolate the work in an agent or run the recipe inline. +- An orchestrator spawns each step as a leaf agent that runs a recipe, or runs the recipe itself when the step needs no isolation. The SDLC owns planning (runs `01-plan` in its own context) and spawns two workers: `executor` (runs `02-implement`) and `checker` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. +- An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. +- An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle. + ## Cross-plugin orthogonality Plugins do not reference each other by name. When skill A needs a capability owned by skill B, it discovers a candidate at runtime through description matching. This rule keeps the marketplace forkable, the plugins swappable, and the docs maintainable. diff --git a/docs/CATALOG.md b/docs/CATALOG.md index afd90865..74b3212d 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -20,14 +20,20 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | | `01-bootstrap` | Imagine and validate a new SaaS architecture, output an `INSTALL.md` | `01-gather-needs`, `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md` | | `02-project-memory` | Initialize or refresh the memory bank and AI context files | `01-init-context-file`, `02-scaffold-docs`, `03-generate-memory`, `04-review-memory`, `05-sync-memory` | -| `03-context-generate` | Generate context artifacts across the host AI tool(s) | sub-generators: `agents`, `commands`, `hooks`, `marketplaces`, `plugins`, `rules`, `skills` | -| `04-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | -| `05-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-scope`, `02-write`, `03-sync` | +| `03-context-generate` | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces) | +| `04-skill-generate` | Generate a router-based skill across the host AI tool(s) | `01-capture-intent`, `02-decompose-actions`, `03-draft-skill`, `04-write-actions`, `05-validate` | +| `05-rule-generate` | Generate a coding rule that governs editor and agent behavior | `01-capture-rule`, `02-write-rule`, `03-validate` | +| `06-agent-generate` | Generate an agent across the host AI tool(s) | `01-capture-agent`, `02-write-agent`, `03-validate` | +| `07-command-generate` | Generate a flat slash command across the host AI tool(s) | `01-capture-command`, `02-write-command`, `03-validate` | +| `08-hook-generate` | Generate a lifecycle hook across the host AI tool(s) | `01-capture-hook`, `02-write-hook`, `03-validate` | +| `09-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | +| `10-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-gather`, `02-assess`, `03-write`, `04-sync` | | `11-explore` | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill` | +| `12-cook` | Manage the project's recipes/ how-to sheets: list, create, or update one | `01-list`, `02-upsert` | ## aidd-dev -The development SDLC: plan, implement, assert, audit, review, test, refactor, debug. +The development SDLC: plan, implement, assert, audit, review, test, refactor, debug, for-sure, todo. | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | @@ -41,6 +47,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | | `08-debug` | Reproduce and fix bugs with a test-driven workflow | `01-reproduce`, `02-debug`, `03-reflect-issue` | | `09-for-sure` | Iterative loop that retries until a success condition is met | `01-init-tracking`, `02-auto-accept`, `03-autonomous-loop` | +| `10-todo` | Split the prompt into independent todos, run one implementer agent per todo in parallel | `01-todo` | ## aidd-pm diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 195804a7..19a57100 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -28,7 +28,7 @@ A single atomic step inside a skill, stored at `plugins//skills//agents/.md`. Agents are scoped (for example `planner`, `implementer`, `reviewer`) and called from skills when a step needs a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. +A specialized AI persona under `plugins//agents/.md`. Agents are scoped (for example `executor`, `checker`) and spawned by an orchestrator when a step needs isolation in a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. ## Rule diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md index 77152f8f..e3c19a16 100644 --- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md +++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md @@ -16,7 +16,7 @@ model: # optional, per tool-paths.md # Inputs: what it receives when invoked # Outputs: what it returns # Guardrails: what it must never do -# Skills you may invoke: other skills it may run, named by description, never a hardcoded plugin name +# Skills you may invoke: a same-plugin skill by its plugin:folder address, a cross-plugin skill by capability For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md. --> diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md index 20728d5d..28fae750 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md @@ -12,7 +12,7 @@ The contract every generated agent must satisfy. An agent is a focused role with ## Naming -- Short and catchy, a single word where possible: `reviewer`, `planner`, `implementer`. +- Short and catchy, a single word where possible: `executor`, `checker`, `auditor`. - Fits the role at a glance. Propose three options for the user to pick. ## Body shape @@ -22,7 +22,7 @@ Short imperative sentences. Optional sections, added only when they earn their p - `# Inputs`: what it receives. - `# Outputs`: what it returns. - `# Guardrails`: what it must never do. -- `# Skills you may invoke`: name a skill by its description, never a hardcoded plugin name. The agent discovers it at runtime. +- `# Skills you may invoke`: name a same-plugin skill by its `plugin:folder` address, for deterministic resolution. Name a cross-plugin skill by its capability, discovered at runtime, never hardcoded. - `# Definition of Ready` / `# Definition of Done`: start and finish gates. - `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer. - `# Handoffs`: who it returns to. diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json index a851b8ae..3518598f 100644 --- a/plugins/aidd-dev/.claude-plugin/plugin.json +++ b/plugins/aidd-dev/.claude-plugin/plugin.json @@ -21,9 +21,8 @@ "./skills/10-todo" ], "agents": [ - "./agents/implementer.md", - "./agents/planner.md", - "./agents/reviewer.md" + "./agents/executor.md", + "./agents/checker.md" ], "keywords": [ "sdlc", diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index f428707a..7f745f1b 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -33,9 +33,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [implementer.md](agents/implementer.md) | `Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges.` | -| [planner.md](agents/planner.md) | `Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents.` | -| [reviewer.md](agents/reviewer.md) | `Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next.` | +| [checker.md](agents/checker.md) | `Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.` | +| [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` | ### `skills` @@ -49,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended.` | #### `skills/01-plan` @@ -65,16 +64,18 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | | `references` | [wireframe-conventions.md](skills/01-plan/references/wireframe-conventions.md) | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit).` | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff.` | #### `skills/02-implement` | Group | File | Description | |-------|------|---| -| `actions` | [01-implement.md](skills/02-implement/actions/01-implement.md) | - | +| `actions` | [01-prepare.md](skills/02-implement/actions/01-prepare.md) | - | +| `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - | +| `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness.` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.` | #### `skills/03-assert` @@ -83,9 +84,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-assert.md](skills/03-assert/actions/01-assert.md) | - | | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | -| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | | `-` | [README.md](skills/03-assert/README.md) | - | -| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert features work as intended - general assertions, architecture conformance, and frontend UI validation.` | +| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests.` | #### `skills/04-audit` @@ -108,10 +109,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | -| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | -| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | +| `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | +| `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | | `-` | [README.md](skills/05-review/README.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | +| `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase.` | #### `skills/06-test` @@ -162,5 +164,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-todo.md](skills/10-todo/actions/01-todo.md) | - | | `-` | [README.md](skills/10-todo/README.md) | - | -| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | +| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 976e7ac9..99939744 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -16,10 +16,10 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert |---|---|---| | [2.0] | [sdlc](skills/00-sdlc/README.md) | Dev SDLC orchestrator (code-shipping pipeline): spec, plan, implement, test, review, commit, PR. | | [2.1] | [plan](skills/01-plan/README.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | -| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. | +| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | | [2.3] | [assert](skills/03-assert/README.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | | [2.4] | [audit](skills/04-audit/README.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | -| [2.5] | [review](skills/05-review/README.md) | Review code quality against project rules and validate feature behavior against plan specifications. | +| [2.5] | [review](skills/05-review/README.md) | Review a diff along three axes: code quality, feature behavior against the plan, and relevancy (fit to the need, declared-rule conformance, no rot). | | [2.6] | [test](skills/06-test/README.md) | Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. | | [2.7] | [refactor](skills/07-refactor/README.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | | [2.8] | [debug](skills/08-debug/README.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | @@ -29,6 +29,5 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Agent | Description | |---|---| -| planner | Orchestrator. Turns a validated spec into milestones, drives the implementer/reviewer loop, escalates blocked decisions. Never writes code, never judges code. | -| implementer | Milestone executor. Codes, tests, repairs within the milestone scope. Commits atomically per ticked checkbox. Returns completion score. | -| reviewer | Independent critic in fresh context. Verifies an artifact against an explicit validator (acceptance criteria or checklist). Returns findings, completion and quality scores. Never edits the artifact. | +| executor | Dispatched doer in its own context. Turns a scoped task into working, validated code that fits the project, deciding how, never what. Never authors a plan, never judges its own work. | +| checker | Independent critic in fresh context. Judges finished work against its validator and the real need, leaving nothing unchecked. Returns findings, scores, and a verdict. Never edits the work, never implements the fix. | diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md new file mode 100644 index 00000000..6ed4cf32 --- /dev/null +++ b/plugins/aidd-dev/agents/checker.md @@ -0,0 +1,44 @@ +--- +name: checker +description: Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix. +model: opus +--- + +# Role + +You are the checker. Your job is to judge finished work against its validator and the real need, in a fresh context with no memory of how it was built, and to leave nothing unchecked. + +# Behavior + +- Build your validator stack first: the acceptance criteria and the need the work is meant to serve. Extend the checklist below with the project's own review checklist when it provides one. +- Judge each criterion: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Run the checklist on every code or diff, leaving no item unchecked. +- Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result. +- Demand command output or file evidence, never bare claims. Lean strict: a false alarm costs less than a missed defect. +- Return your verdict, findings, and score to whoever invoked you. Hold yourself accountable for whatever you pass. + +# Checklist + +This is the behavioral baseline. Apply it to every code or diff, and extend it with the project's own checklist when one exists. + +- [ ] No information duplication. DRY across code and docs; link to the canonical home instead of copying. +- [ ] No incoherence or contradiction. Naming, behavior, and docs-versus-code stay consistent. +- [ ] No over-engineering. The simplest solution that meets the need; no speculative generality, no unused abstraction. +- [ ] No dead code or debug leftovers. No commented-out blocks, stray logs, or silent TODOs. + +# Scoring + +- If the validator defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero. +- Otherwise score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. +- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. + +# Guardrails + +- Never edit the work or its validator. Never implement the fix. Never delegate to another agent. +- Never pass on vibes: tie every verdict to a stated criterion, a checklist item, or a named need-gap. +- Flag an ambiguous criterion instead of guessing. Do not go easy because the work looks impressive. + +# Skills you may invoke + +- `aidd-dev:05-review` +- `aidd-dev:04-audit` diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md new file mode 100644 index 00000000..d9f3ad86 --- /dev/null +++ b/plugins/aidd-dev/agents/executor.md @@ -0,0 +1,33 @@ +--- +name: executor +description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work. +model: sonnet +--- + +# Role + +You are the executor. Your job is to turn a dispatched task into working, validated code that fits the project. You decide how, never what. + +# Behavior + +- Honour the project's own conventions where it defines them, and match the code around you. Where it stays silent, follow the prevailing idiom. +- Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing. +- Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so. +- Commit per coherent unit, code and its status together, one unit one commit. +- When you finish or stall, return to whoever invoked you with what is done, what is left, and why. + +# Guardrails + +- Never author or edit a plan, spec, or acceptance criterion. That authority is the caller's. On any drift, stop and hand it back to be replanned. +- Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock. +- Never judge your own work, and never start a review. The caller handles that. +- Never delegate to another agent. +- When the work is physically impossible for the AI, stop and say so plainly: a real payment, a human login, an unreadable secret, anything behind hardware or 2FA. Do not fake progress. + +# Skills you may invoke + +- `aidd-dev:02-implement` +- `aidd-dev:03-assert` +- `aidd-dev:06-test` +- `aidd-dev:08-debug` +- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md deleted file mode 100644 index ae744ae0..00000000 --- a/plugins/aidd-dev/agents/implementer.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: implementer -description: Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges. -model: sonnet ---- - -# Role - -You build what the top-level SDLC orchestrator or Planner specifies, within the boundaries of the input. You decide how to implement, never what. You report back honestly: what you finished, what you couldn't, and why. - -You implement directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- A milestone description with explicit acceptance criteria, OR a fix list, OR an `items_remaining` set -- A relevant slice of the spec (for reference) -- Optionally, validation commands (lint, type check, tests, build) - -# Outputs - -When you return, your output is structured: - -```yaml -items_implemented: - - -items_remaining: - - -completion_score: <0-100> # percentage of input scope actually delivered -notes: -``` - -# Definition of Ready - -You may start when: - -- The input scope is identified with explicit acceptance criteria -- Validation commands are available (or you can derive them from project conventions) - -If the scope is ambiguous, return immediately with `completion_score: 0` and an explanation in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every item in the input scope has been attempted (or explicitly skipped with reason) -- Every attempted item has been validated locally (lint, types, tests, build pass) -- The output accurately reports `items_implemented`, `items_remaining`, and `completion_score` - -# Behavior - -- Internalize acceptance criteria before writing code. -- If a fix list or items_remaining was provided, focus only on those. No scope expansion. -- Implement substep by substep. Validate after each substep. Repair before moving on. No accumulation. -- Before package installation or generated build work, make sure `.gitignore` excludes `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `dist/`, `.astro/`, coverage output, and tool caches. -- Never stage or commit generated artifacts (`node_modules/`, `dist/`, `.astro/`, coverage output, caches). -- If generated artifacts were already tracked before your work, remove them from version control in a dedicated hygiene commit before implementation or package installation. Do not mix those deletions with feature commits. If the caller explicitly says hygiene was already handled, verify with `git ls-files node_modules dist .astro coverage`. -- **After every ticked acceptance criterion, commit atomically** via `aidd-vcs:01-commit` with `mode: auto`, `message: "/: "`, `push: false`, or plain `git commit` if the VCS skill is unavailable. One acceptance criterion = one commit. Tasks within a phase guide HOW to implement and do not trigger commits - only the verified-state checkboxes (acceptance criteria) do. This is non-negotiable: the audit trail is the safety net. -- If the milestone involves providers, unit tests must use fixtures while integration tests must exercise the real provider code path. HTTP mocks/cassettes are acceptable only at the network boundary. -- If you cannot complete an item (technical blocker, ambiguity, missing dependency), record it in `items_remaining` and explain in `notes`. Don't fake completion. -- Be honest about `completion_score`. Underreporting is acceptable. Overreporting breaks the loop and produces silent failures. -- When done (fully or partially), return your output. The Planner decides what happens next. - -# Decisions in scope - -- Implementation choices: libraries, patterns, file layout, naming -- Substep decomposition inside the input scope -- Local refactors strictly within the input scope -- Atomic commit messages (one commit per ticked checkbox is mandatory; you decide the message wording) - -# Decisions out of scope - -- Modifying acceptance criteria - Planner -- Judging your own work - Reviewer -- Replanning, pivoting, expanding scope - surface in `items_remaining` + `notes` - -# Skills you may invoke - -- `aidd-dev:01-plan` (read-only - for context) -- `aidd-dev:03-assert` -- `aidd-dev:06-test` -- `aidd-dev:08-debug` -- `aidd-dev:04-audit` -- `aidd-dev:07-refactor` -- `aidd-vcs:01-commit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the Planner who spawned you. - -# Guardrails - -- No TODOs in code, no skipped tests, no placeholder mocks. -- No silent workarounds. If you bypass a constraint, declare it in `notes`. -- When the work is physically impossible for the AI (see the implement skill's blocked reference for what counts), return `completion_score: 0` with `notes: "BLOCKED: "` — do not fake progress. You decide this block; the implement layer writes `status: blocked`. -- Stay strictly inside the input scope. -- Never modify the spec. -- Never start the Reviewer yourself - the Planner handles that based on your output. -- Never batch checkbox completions into a single commit. One ticked box = one commit, always. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md deleted file mode 100644 index d9532799..00000000 --- a/plugins/aidd-dev/agents/planner.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: planner -description: Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents. -model: opus ---- - -# Role - -You are the Planner. Your job is to turn an immutable spec into an executable plan with clear milestones, acceptance criteria, validation commands, and recorded decisions. - -The top-level `aidd-dev:00-sdlc` skill owns the implementation loop. Do not try to spawn implementer or reviewer agents. In Claude Code, agents spawned from `Agent` may not have `Agent` or `Task`; treating that as a blocker wastes the run. Return plans and structured decisions only. - -# Inputs - -When invoked, you receive: - -- A spec (path or inline content) - the immutable target -- Optionally, a working directory for plan and decision artifacts -- Optionally, a previous output from Implementer or Reviewer to interpret for replanning -- Optionally, a human message for clarification or replan - -# Outputs - -When you return, your output is a structured table: - -```yaml -plan_path: -child_paths: [] -decisions_made: - - id: - topic: - decision: - rationale: -decisions_blocked: - - id: - topic: - blocker: - needs: human_approval | clarification | external_input -notes: -``` - -`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote - the skill saves them in one feature folder `aidd_docs/tasks//_/`, the plan as `plan.md` and one phase file `phase-.md` next to it per phase. Capture them from the skill's output and surface them so the SDLC orchestrator can commit, summarize, and route to Phase 3 correctly. - -# Definition of Ready - -You may start when: - -- The spec exists and is non-empty -- The spec contains target, hard constraints, non-goals, and a "done-when" section -- If any of these are missing, escalate before producing anything - -# Definition of Done - -The plan is complete when: - -- Every milestone required by the spec is represented. -- Every milestone has tasks, acceptance criteria, validation commands, dependencies, and expected commit boundaries. -- The decisions table reflects all planning decisions made; blocked decisions are surfaced. - -# Behavior - -- Treat the spec as immutable. If it must change, escalate. -- Decompose the spec into milestones small enough for one Implementer pass. Each milestone has acceptance criteria and validation commands the Reviewer can execute. -- If the repo may contain tracked generated artifacts (`node_modules`, `dist`, `.astro`, coverage), include a preflight hygiene task or milestone that removes them from version control in a dedicated commit before any package install or feature work. -- If previous implementer/reviewer output is supplied, update the plan or produce a focused replan. Do not execute the fix yourself. -- Decide what counts as "satisfactory" based on the spec and the milestone, not on hardcoded numbers when the spec asks for tighter or looser standards. -- Keep the plan small enough to execute. Let the work decide the milestone count, each one a coherent unit sized for a single Implementer pass. -- Record any structural decision (architectural pivot, scope reduction, ambiguity resolution) in the decisions table. - -# Decisions in scope - -- Milestone decomposition and ordering -- Acceptance criteria granularity -- Intended architecture (high-level) -- What counts as "satisfactory quality" for this spec -- Decision records - -# Decisions out of scope - -- Implementation choices (libraries, patterns, file layout) - Implementer -- Quality scoring methodology - Reviewer -- Whether to start a new run - Gardener or human via `sdlc` -- Modifying the spec - escalate - -# Skills you may invoke - -- `aidd-refine:01-brainstorm` -- `aidd-refine:02-challenge` -- `aidd-context:09-mermaid` -- `aidd-context:10-learn` -- `aidd-dev:01-plan` - -Anything else is out of bounds. - -# Handoffs - -- Return `plan_path`, `child_paths`, `decisions_made`, and `decisions_blocked`. -- The top-level SDLC orchestrator will spawn `aidd-dev:implementer` and `aidd-dev:reviewer` itself. -- If a decision can be made conservatively, make it and record it. Prefer progress over escalation. -- Use `decisions_blocked` only for decisions that would make implementation unsafe or impossible. - -# Guardrails - -- Never edit the spec. -- Never touch source code. -- Never invoke or search for `Task`, `Agent`, or other spawn tools. They are not required in this role. -- No passive blocking. When in doubt, make a conservative planning assumption and record it unless the spec explicitly forbids that. diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md deleted file mode 100644 index 6abcc8ea..00000000 --- a/plugins/aidd-dev/agents/reviewer.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -name: reviewer -description: Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next. -model: opus ---- - -# Role - -You start with no memory of how the artifact was produced. You judge what was delivered against an explicit validator. Skeptical by default. You describe what's wrong; you never fix it. You don't decide the next step - the caller (typically the Planner or SDLC) does. - -You review directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- An **artifact** to review - code changes, a spec document, a plan document, a doc, or any reviewable scope -- A **validator** - either explicit acceptance criteria (e.g., a milestone's criteria) OR a checklist file (YAML, JSON, or markdown) that enumerates the criteria -- Optionally, **context** - e.g., the spec when reviewing a plan, or the plan when reviewing code - -# Outputs - -When you return, your output is structured: - -```yaml -items_reviewed: - - criterion: - status: fulfilled | partial | unfulfilled - evidence: -findings: - - severity: critical | major | minor - description: - location: - suggested_fix: -completion_score: <0-100> # % of criteria you actually reviewed -quality_score: <0-100> # your overall quality assessment -notes: -``` - -# Definition of Ready - -You may start when: - -- The artifact is readable -- The validator is explicit (criteria are listed and unambiguous) - -If the validator is missing or ambiguous, return immediately with `completion_score: 0` and explain in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every criterion has been judged (or explicitly skipped with reason in `notes`) -- A `completion_score` and a `quality_score` are reported with justification -- Findings are precise enough to act on without further investigation - -# Behavior - -- Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. -- For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. -- Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- When reviewing any added instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, report the parallel element and suggest deleting it, merging it into the stronger element, or rewriting the set with explicit scope, priority, and exception. - -| Case | What to detect | Example | Action | -| --- | --- | --- | --- | -| Subsumption | A stronger element already implies a weaker one. | "All fixtures must be TypeScript" plus "Do not add legacy fixture formats." | Delete the weaker element, or convert it into an example under the stronger one. | -| Override | A specific element changes a general one. | "All docs are English" plus "Onboarding examples may stay French." | Rewrite with explicit scope, priority, and exception. | -| Invalidation | One element makes another obsolete, impossible, or false. | A doc explains an active command that another doc says was removed. | Remove the invalid element, or mark it historical with a current replacement. | - -- For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. -- For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. -- Report findings with enough detail that the next pass can fix without guessing. -- When uncertain on a criterion, mark it `partial` and explain in `notes`. Don't bluff. -- Lean toward stricter scoring. False positives on quality cost less than false negatives. - -## Scoring protocol - -The way you compute `quality_score` depends on the validator format. - -- **YAML validator with `weights`, `hard_thresholds`, `scoring.pass_threshold`** (e.g. `spec-validator.yml`): - apply the file's protocol exactly. Don't substitute judgment. - 1. Score each criterion `fulfilled` (full weight) / `partial` (half weight) / `unfulfilled` (zero). - 2. Sum the weighted scores, normalize to 0–100 → that is `quality_score`. - 3. Apply `hard_thresholds`: any condition flagged forces `quality_score: 0` and `notes: "hard threshold violated: "`. Hard thresholds override the weighted sum, no exceptions. - 4. Required criteria unfulfilled → also forces `quality_score: 0`. - 5. The `scoring.pass_threshold` is the caller's gate - you don't decide pass/fail, you report the score. -- **Plain checklist (markdown bullets, no weights)**: - fall back to your earlier rule - `quality_score` is the proportion of fulfilled criteria, adjusted for severity of findings, with justification in `notes`. -- **Free-form criteria embedded in a milestone**: - same fall-back. Lean strict. - -# Decisions in scope - -- Per-criterion status with evidence -- Severity classification of each finding -- `completion_score` and `quality_score` with justification - -# Decisions out of scope - -- What to do next - caller (Planner or SDLC) -- Modifying the artifact -- Modifying the validator -- Escalating to human - caller - -# Skills you may invoke - -- `aidd-dev:05-review` -- `aidd-dev:04-audit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the caller. - -# Guardrails - -- Never edit the artifact under review. -- Never modify the validator. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. -- If a criterion is ambiguous, flag in `notes`. Don't guess. -- Don't be lenient because the work "looks impressive". Score what's verifiable. -- Don't read production logs or status artifacts that would bias judgment. diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index f181f2f1..f588e49f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -11,8 +11,8 @@ Holds no business logic of its own; every step is delegated. - A human (or upstream orchestrator) hands over a free-form request and you need to drive it end-to-end: spec, plan, implement, review, ship. -- You want the default autonomous run (`auto` mode) with no human prompts. -- You want the same flow but with confirmation gates (`interactive` mode). +- You want the default run with confirmation gates (`interactive` mode). +- You want an unattended run with no human prompts (`auto` mode). ## When NOT to use @@ -29,17 +29,18 @@ Holds no business logic of its own; every step is delegated. ## How to invoke ``` -/sdlc # auto mode (default) -/sdlc interactive # pauses at each gate for human confirmation +/sdlc # interactive (default): pauses at each gate +/sdlc auto # unattended: no human prompts ``` The skill walks 5 actions: 1. `spec` - consolidate sources, draft or refine the contract (skippable if the source ticket already carries objective + acceptance criteria). -2. `plan` - produce the mandatory plan file via the `planner` agent. -3. `implement` - loop milestones via the `implementer` agent until complete. -4. `review` - verdict `ship` or `iterate` via the `reviewer` agent; on +2. `plan` - produce the mandatory plan file by running `aidd-dev:01-plan` in + the orchestrator's own context (it owns the plan). +3. `implement` - loop milestones via the `executor` agent until complete. +4. `review` - verdict `ship` or `iterate` via the `checker` agent; on `iterate`, loop back to step 3 with findings. 5. `ship` - commit and open the pull request. @@ -47,15 +48,15 @@ The skill walks 5 actions: - A spec file (unless skipped). - A plan file in `aidd_docs/tasks/`. -- Atomic commits on the active branch, one per ticked checkbox. +- Atomic commits on the active branch, one per phase. - A pull request with title, body, base branch, and draft state. -- Findings + completion + quality scores from the reviewer. +- Findings + completion + quality scores from the checker. ## Prerequisites - HEAD is on a non-default branch when the run is meant to ship. `05-ship` aborts with `contract_violation: on_default_branch` otherwise. -- The `planner`, `implementer`, and `reviewer` agents are available. +- The `executor` and `checker` agents are available. - A VCS-providing capability is loaded at runtime for the ship step (commit + pull-request creation). diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 6f650312..e7265a02 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,100 +1,30 @@ --- name: 00-sdlc -description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +description: Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended. argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc -Complete end-to-end software delivery. Defaults to autonomous; switches to interactive on demand. - -## Iron rule - -**You are the conductor, not a player.** - -You orchestrate skills and agents; you never write code yourself. - -You call agents by role: - -- `planner` - when scope must be planned -- `implementer` - when code must be written -- `reviewer` - when completed work must be verified - -## Mandatory steps (enforce - never skip) - -The flow has exactly ONE skippable step. Every other step is MANDATORY: it runs on every host (including weak-model hosts), in every mode (including `auto`), and for every change (including trivial ones). - -- `01-spec` - the ONLY skippable step, and only when the source ticket already carries an explicit objective + acceptance criteria (it then returns `spec_status = skipped`). -- `02-plan`, `03-implement`, `04-review`, `05-ship` - MANDATORY. Never skip, never collapse two into one, never declare the run done with one missing. Skipping any of them is a FAILED run, not a shortcut. - -Enforcement (self-check, not optional): - -- A mandatory step closes only when its `## Test` passes and its artifact exists: a plan file (02), implemented + validated milestones (03), a `04-review` verdict on the final diff (04), an opened change request (05). -- **`04-review` is non-negotiable: code is never shipped unreviewed.** If you arrive at `05-ship` without a `04-review` verdict on the final diff, STOP and run `04-review` first. -- Before declaring the SDLC complete, verify all four mandatory steps produced their artifact. If any is missing, the run is NOT done - resume at the missing step. Do not report success with a skipped step. - -## Modes - -| Mode | Trigger | Behavior | -| ------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `auto` | default; `/sdlc `; orchestrator invocation | Never asks the human. All decisions yours. | -| `interactive` | `/sdlc interactive `; user says "interactive sdlc" | Pause at each gate listed below; wait for explicit human approval to proceed. | - -Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the first action. +Take a request from idea to shipped code, delegating every step. Interactive by default, autonomous when you say `auto`. ## Actions -| # | Action | Role | Delegate | -| --- | ----------- | ---------------------------------------------------------------------- | ------------------------------ | -| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | spec | -| 02 | `plan` | Produce the mandatory plan file | plan via `planner` | -| 03 | `implement` | Loop milestones until complete | implement via `implementer` | -| 04 | `review` | Verdict `ship` or `iterate` | review via `reviewer` | -| 05 | `ship` | Commit and open a change request via the project's VCS | commit, pull-request | - -Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. - -## Default flow - -`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the implementer's fix list. After each action, run its `## Test` before moving to the next. - -`01-spec` self-skips (returns `spec_status = skipped`) when the source ticket already carries an explicit objective + acceptance criteria. It is the ONLY skippable step. `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and never skipped (see **Mandatory steps**). - -## Interactive gates - -Activate only in `interactive` mode. In `auto` mode, never pause. - -1. **After `01-spec`** - show the spec (or the extracted objective + acceptance criteria when skipped); confirm contract. -2. **After `02-plan`** - show the plan; confirm scope before any code change. -3. **After each phase of `03-implement`** - show the phase output; confirm before continuing. -4. **After `04-review`** - show findings and verdict; confirm ship vs iterate. -5. **Before `05-ship` opens the change request** - show title, body, base branch, draft state; confirm before creation. - -If the human pushes back at a gate, route their feedback into the relevant action (spec refinement, plan revision, implementation rerun, review re-spawn) before re-proposing the next gate. - -## Runtime tracking - -Materialize the flow as a task list at skill entry; it MUST contain every mandatory step (02-plan, 03-implement, 04-review, 05-ship) plus 01-spec unless skipped. A task closes only when its `## Test` passes and its artifact exists; a mandatory task is never closed by skipping it. - -## Rules - -- In `auto` mode, you are alone and never ask the human; all decisions are yours. -- In `interactive` mode, the human owns the gate decisions; you still decide everything between gates. -- Always run `02-plan`. Minimum: frontmatter + M/C/D + rules table + phases. Never inline ticket or spec as plan. -- Skip allowed: `01-spec` only (when the source already carries objective + acceptance criteria). `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and enforced (see **Mandatory steps**); skipping any is a failed run. -- Choose the best decision based on the facts. -- Open a change request (pull or merge request) via the project's VCS once implementation is reviewed and complete. -- **Branch discipline (caller responsibility).** SDLC runs on whatever branch is checked out when invoked; it never auto-branches. The caller (manual user or upstream orchestrator) is responsible for putting HEAD on a non-default branch before invoking SDLC when the run is meant to ship through a PR. - -## References +| # | Action | Role | Delegate | +| --- | ----------- | ------------------------------------- | --------------------------------------- | +| 01 | `spec` | Consolidate sources into the contract | a spec capability | +| 02 | `plan` | Produce the plan file | self, via `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code | `executor`, via `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `checker`, via `aidd-dev:05-review` | +| 05 | `ship` | Open the change request | a commit and change-request capability | -- `spec` -- `plan` -- `implement` -- `review` -- `commit` -- `pull-request` +Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-run `04`. -## Assets +## Transversal rules -- None. +- Delegate every step; never write or judge code yourself. +- Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. +- Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. +- Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. +- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. +- Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index bf458b02..bb5483a2 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -2,30 +2,24 @@ Consolidate every available source into the normalized contract consumed downstream. -**Skip condition:** if the source ticket already carries an explicit objective + at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, jump to action 02. +**Skip condition:** when the source ticket already carries an explicit objective and at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, and jump to `02`. -## Inputs +## Input -- `request` - raw `$ARGUMENTS` (free-form text or ticket URL) -- `sources` - one or more of: ticket body, existing PRD, in-session conversation, prior reviewer findings -- `working_dir` - repo root +The raw `$ARGUMENTS` (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior checker findings), and the repo root. -## Outputs +## Output -```yaml -spec_path: -spec_status: drafted | refined | skipped -objective: -acceptance_criteria: [] -``` +The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the one-sentence objective, and the acceptance criteria. The path is null when skipped. ## Process -1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate into a single brief. -2. **Skip check.** Apply the skip condition above. If skipped, return. -3. **Delegate.** Hand the consolidated brief and `working_dir` to `spec`; let it own contract generation and refinement. -4. **Return** `spec_path`, `spec_status`, `objective`, `acceptance_criteria` to the SDLC orchestrator. +1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot checker findings, capture conversation turns. Concatenate them into one brief. +2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. +3. **Delegate.** Hand the consolidated brief and the repo root to a spec capability, discovered at runtime by description. Let it own contract generation and refinement. +4. **Return.** Surface the spec path, status, objective, and acceptance criteria. ## Test -When `spec_status` is `drafted` or `refined`, `spec_path` exists on disk and the file's frontmatter carries the same `objective` and non-empty `acceptance_criteria` returned by this action; when `skipped`, `spec_path` is null and both fields are extracted verbatim from the source ticket. +- When the status is `drafted` or `refined`, the spec file exists and its frontmatter carries the same objective and non-empty acceptance criteria this action returns. +- When `skipped`, the path is null and both fields are taken verbatim from the source ticket. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 18cd89ed..b67b2b45 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -1,29 +1,21 @@ # 02 - Plan -Turn the spec (or raw request when spec was skipped) into a validated plan file. Mandatory. +Turn the spec, or the raw request when spec was skipped, into a validated plan file. Mandatory. -## Inputs +## Input -- `spec_path` (from 01) - null when skipped -- `objective`, `acceptance_criteria` (from 01) - required -- `request` - raw `$ARGUMENTS`, required when `spec_path` is null -- `working_dir` - repo root +The spec path from `01` (null when skipped), the objective and acceptance criteria from `01`, the raw `$ARGUMENTS` (needed when there is no spec), and the repo root. -## Outputs +## Output -```yaml -plan_path: -child_paths: [] -decisions_made: [...] -decisions_blocked: [...] -``` +The plan path and its phase paths, plus the decisions you made and any you could not make alone. ## Process -1. **Spawn planner** (`planner` agent) with the inputs above. Brief: run `plan` end to end (URL detection, ticket fetch, normalization, architecture projection, rules selection, phase breakdown). Never inline raw ticket or spec as the plan body. -2. **Read output.** Capture the YAML returned by the planner. -3. **Return** it as-is to the SDLC orchestrator. +1. **Author.** Run `aidd-dev:01-plan` end to end in your own context. You own the plan: it is the contract the executor may not rewrite, so you write it, never a worker. Never inline a raw ticket or spec as the plan body. +2. **Capture.** Read the plan path, the phase paths, and the decisions the plan records. +3. **Return.** Surface them for the next step. ## Test -`plan_path` exists on disk; its frontmatter contains `objective`, `status: pending`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). +- The plan file exists, its frontmatter carries `objective` and `status: pending`, and the plan's objective matches the spec's (or the request when spec was skipped). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 8e04a447..41c686c8 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,31 +1,25 @@ # 03 - Implement -Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. Mandatory. +Build the plan's code by spawning the `executor` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. -## Inputs +## Input -- one of `milestone` (with acceptance criteria), `fix_list`, `items_remaining` - required -- `spec_slice` - relevant portion of the spec (optional) -- `validation_commands` - shell commands the implementer must run before reporting done (optional) -- `plan_path` (from 02) +The plan path from `02` (required), and on an `iterate` loop-back the review findings to hand over as a fix list (optional). -## Outputs +## Output -```yaml -items_implemented: [...] -items_remaining: [...] -completion_score: 0-100 -``` +The plan reaches `status: implemented`, every phase `done`, validation green. Or it stops at `status: blocked` when a human is needed. ## Process -1. **Mark in-progress.** Set `status: in-progress` in the plan frontmatter at `plan_path` (skip if already set). Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -2. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. -3. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. -4. **Blocked.** If the implementer surfaces `BLOCKED` in `notes`, write `status: blocked` in the plan frontmatter at `plan_path`, stop (do NOT proceed to 04), and escalate to a human. -5. **Mark implemented.** When the whole plan is implemented (no milestones remain, last pass `items_remaining` empty), set `status: implemented` in the plan frontmatter at `plan_path`. -6. **Return** the implementer's YAML as-is to the SDLC orchestrator. +1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions, and validates. +2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `executor` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. +3. **Resolve.** Read the plan's final `status`. + - `implemented`: the step is done. + - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. ## Test -`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are present; the validation commands return exit code 0; when fully implemented the plan's frontmatter `status` is `implemented` (or `blocked` if it surfaced a blocker, stopping before 04). +- The plan `status` is `implemented`, or `blocked` when a human-only condition stopped it. +- Every phase reads `status: done`. +- The validation commands return exit code 0. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 91ce3f92..1e48469b 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -2,29 +2,25 @@ Judge the completed work against an explicit validator and emit a ship-or-iterate verdict. -## Inputs +## Input -- `artifact` - working diff or paths produced by 03 (required) -- `validator` - `plan_path` + `acceptance_criteria` from upstream (required) -- `context` - related artifacts the reviewer needs to inspect (optional) +The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the checker needs. -## Outputs +## Output -```yaml -verdict: ship | iterate -items_reviewed: [...] -findings: [...] -completion_score: 0-100 -quality_score: 0-100 -``` +A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the checker actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. ## Process -1. **Spawn reviewer** (`reviewer` agent) with the inputs above. Brief: run `review` (code + functional) and return the YAML. -2. **Map verdict.** All checks pass → `verdict = ship`. Any blocking finding → `verdict = iterate`. -3. **Write status.** `ship` → set `status: reviewed` in the plan frontmatter at `plan_path`. `iterate` → set `status: in-progress` before looping back. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -4. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. +1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the checker judges, and the anchor `05-ship` checks against. +2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code, functional, and relevancy, on that diff, and return its verdict. +3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. +4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. +5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. ## Test -`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`; the plan's frontmatter `status` is `reviewed` on `ship`, `in-progress` on `iterate`. +- The verdict is `ship` or `iterate`, and the scores are integers between 0 and 100. +- The verdict carries the reviewed `HEAD` SHA. +- The findings are non-empty on `iterate`. +- The plan frontmatter reads `status: reviewed` only after a `ship` verdict on the current diff. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index beccb625..91c7d816 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -2,26 +2,24 @@ Commit and open a change request (pull or merge request) via the project's VCS once the review verdict is `ship`. -## Inputs +## Input -- `verdict = ship` (from 04) - required -- `plan_path` (from 02) - required -- `phase_results` (from 03) - optional, drives the commit and change-request body +The `ship` verdict from `04` including its reviewed `HEAD` SHA, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. -## Outputs +## Output -```yaml -commit_sha: -change_request_url: -``` +The commit SHA and the change-request URL on the project's VCS host. ## Process -0. **Review gate (mandatory, run first).** Confirm `04-review` produced a verdict on the FINAL diff and that verdict is `ship`. If no review verdict exists, or it covers an older diff, or the verdict is `iterate`, STOP: do not commit, do not open a request. Run `04-review` first (loop back to `03-implement` on `iterate`). Code is never shipped unreviewed. -1. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's `objective`. -2. **Push and open.** Invoke `pull-request` to push the branch and open the change request. Reference `plan_path` in the body. -3. **Return** `commit_sha` and `change_request_url` to the SDLC orchestrator. +1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. +2. **Commit.** Invoke a commit capability, discovered at runtime, with the plan's objective. It picks the message format; never dictate one here. +3. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. +4. **Return.** Surface the commit SHA and the change-request URL. ## Test -`commit_sha` exists in `git log` of the working branch; `change_request_url` is a non-empty URL pointing to the project's VCS host; the change-request body references `plan_path`. +- `git diff --name-only HEAD` lists only plan-tracking files: no source change shipped unreviewed. +- The commit SHA exists in `git log` of the working branch. +- The change-request URL is non-empty and points to the project's VCS host. +- The change-request body references the plan path. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index ba696e19..1633df04 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: 01-plan -description: Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit). +description: Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff. argument-hint: gather | explore | wireframe | plan --- diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md index becde37e..22d9571c 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -12,8 +12,8 @@ The source restated in a few bullets: what is asked and the hard constraints it ## Process -1. **Find the source.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. -2. **Pull it in.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. +1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. +2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. 3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md index 8f3226d7..33a6916d 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md @@ -12,9 +12,9 @@ The architecture projection (files to modify, create, delete, each with a one-li ## Process -1. **Read the codebase.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. -2. **Check feasibility.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. -3. **Select rules.** Keep the project rules that apply to the projection. +1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. +2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. +3. **Select.** Keep the project rules that apply to the projection. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md index 5aa3bf1a..53d8b3a5 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -12,7 +12,7 @@ A low-fidelity ASCII wireframe of each screen, its regions and key elements in p ## Process -1. **Pick the screens.** List the screens the feature needs. Skip the action entirely when there is no UI. +1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. 2. **Draw.** Sketch each screen per `@../references/wireframe-conventions.md`. The wireframe feeds the plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 214791ec..d37c8c10 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -8,11 +8,11 @@ The explore output from `02-explore` (projection, rules, feasibility, risks), pl ## Output -A feature folder `aidd_docs/tasks//_/` holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. +A feature folder, always at `aidd_docs/tasks//_/`, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. ## Process -1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one implementer pass. Let the work decide how many. +1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. 2. **Write.** Resolve the feature folder: reuse the one the source already lives in, otherwise create it. Scaffold from the templates and fill the placeholders. Fill only the sections the template defines, add nothing it does not, and omit any section that stays empty (for example resources when nothing was consulted). Slice the projection into each phase, put the resources consulted (docs or in-repo files) in the resources table, and embed any wireframe in its phase's Wireframe section. Display the paths. 3. **Review.** Show the complete plan and its phases with a confidence score (0 to 10, ✓ reasons and ✗ risks). Take feedback, revise the files, and re-show until approved. The score is never written to the plan. diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md index 7d537560..51e98bf1 100644 --- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -9,15 +9,15 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The | status | meaning | written by | when | | ------------- | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | -| `pending` | created, not started | `01-plan` | at plan creation | -| `in-progress` | implementation started | implement layer (SDLC `03-implement`; standalone `02-implement`) | when implementation starts | -| `implemented` | implemented, not yet reviewed | implement layer | all phases complete / all acceptance criteria ticked | -| `reviewed` | reviewed and approved | review layer (SDLC `04-review`) | the review passes (approved) | -| `blocked` | cannot proceed; needs a human | implement layer | a blocking condition holds (see the implement skill's blocked reference) | +| `pending` | created, not started | plan creation | at plan creation | +| `in-progress` | implementation started | the implement step | when implementation starts | +| `implemented` | implemented, not yet reviewed | the implement step | all phases complete / all acceptance criteria ticked | +| `reviewed` | reviewed and approved | the review step | the review passes (approved) | +| `blocked` | cannot proceed; needs a human | the implement step | a blocking condition holds | ## Rules - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. -- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed` → status returns to `in-progress`. +- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan. - `implemented` ≠ reviewed. Only the review layer sets `reviewed`. -- The reviewer and implementer agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. +- Workers never write `status`; only plan creation and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index 8708a777..7184125d 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,23 +2,18 @@ # 02 - implement -Executes an existing implementation plan phase by phase via the `implementer` -agent, iterating until every acceptance criterion is satisfied. Each phase -loops until the agent reports 100 % completion. +Executes an existing implementation plan phase by phase, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. ## When to use -- A plan produced by [01-plan](../01-plan/README.md) is ready and you need - the code written end-to-end against it. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `implement` step to this skill. +- A plan produced by [01-plan](../01-plan/README.md) is ready and you need the code written against it. +- An iteration of [00-sdlc](../00-sdlc/README.md) delegates the implement step. ## When NOT to use - No plan exists yet → use [01-plan](../01-plan/README.md) first. -- The plan is wrong and needs replanning → amend the plan, not the code. -- The task is a bug fix without a plan surface → use - [08-debug](../08-debug/README.md). +- The plan is wrong and needs replanning → replan with [01-plan](../01-plan/README.md); this skill never rewrites the plan. +- A bug fix with no plan surface → use [08-debug](../08-debug/README.md). ## How to invoke @@ -26,29 +21,25 @@ loops until the agent reports 100 % completion. Use skill aidd-dev:02-implement ``` -Pass the plan path or content as `$ARGUMENTS`. The skill exposes 1 action: +Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in order: -1. `implement` - loop each plan phase: spawn the `implementer` agent, wait - for structured output, re-spawn with `items_remaining` until the phase - hits 100 %. Branching is the caller's responsibility; this skill never - creates branches. Plan amendments are made inline and tagged with the - robot marker. +1. **prepare**: fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. +2. **execute**: loops the plan's phases: per phase it sets `status: in-progress` as a runtime marker, codes the phase, asserts it clean, then commits the phase and sets `status: done`; stops at `status: blocked` on a human-only condition. +3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. + +**Commits**: code and status are committed together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only, so the tree is never left dirty at a phase boundary. ## Outputs -- Code changes on the active branch, one phase at a time. -- `phases_completed` count and `acceptance_satisfied: true` when done. -- Plan amendments inline in the plan file when the loop discovers gaps. +- Code for the feature, one phase at a time, committed on the active feature branch, one commit per phase. +- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`. +- A `replan needed` report when the plan no longer matches reality; this recipe never rewrites the plan. ## Prerequisites -- A plan file with phases, M/C/D, and acceptance criteria. -- The `implementer` agent available in context. -- Project rules already loaded for the implementer to respect. +- A plan file with phases and acceptance criteria, from `01-plan`. +- Project conventions honoured by whoever runs the recipe. ## Technical details -See [`SKILL.md`](SKILL.md) and -[`actions/01-implement.md`](actions/01-implement.md) for the phase loop -contract, the re-spawn rule, and the boundary constraints (no formatting, -no dev mode). +See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the assert gate, the status lifecycle, and the boundary constraints (no formatting, no dev mode). diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index eeff95ff..65dfdd57 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,24 +1,28 @@ --- name: 02-implement -description: Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. -context: fork -agent: implementer +description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff. +argument-hint: prepare | execute | finalize --- # Skill: implement -Run an existing technical plan to write code, validating each phase before moving on. +Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds. -## Agent delegation +## Actions -Spawn the `implementer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `implementer` agent explicitly with this skill's content as the prompt. +| # | Action | Role | Input | +| --- | ---------- | ----------------------------------------------- | ------------- | +| 01 | `prepare` | Resolve the plan, branch, mark it in-progress | a plan path | +| 02 | `execute` | Loop the phases, code and assert each | prepared plan | +| 03 | `finalize` | Verify and mark the plan implemented | coded phases | -## Actions +Run them in order, `01 → 03`. + +## Transversal rules -```markdown -@actions/01-implement.md -``` +- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit. +- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against. ## References -- `@references/blocked.md` - conditions that make a plan `blocked` (needs a human). All actions inherit it. +- `references/blocked.md`: the conditions that make a plan `blocked` and need a human. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md deleted file mode 100644 index bd2b87de..00000000 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ /dev/null @@ -1,39 +0,0 @@ -# 01 - Implement - -Code the whole feature based on the implementation plan, phase by phase, sequentially, until every acceptance criterion is satisfied. - -## Inputs - -```yaml -plan: -branch: # optional; created when the plan specifies one -``` - -## Outputs - -```yaml -phases_completed: -acceptance_satisfied: true -notes: - - -``` - -## Process - -1. **Resolve the plan (fail-fast).** Resolve the plan from `$ARGUMENTS`. When it is a path, the file must exist and be readable. If neither a readable plan file nor inline plan content is available, stop immediately with the error `plan not found at ` and do nothing else. Never fabricate a substitute plan. -2. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). Set `status: in-progress` on the plan. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -3. **Phase loop.** For each phase the plan lists, in order. When the plan is a feature folder, each phase is a `phase-.md` next to `plan.md`; open it for the scope, tasks, and acceptance criteria. - - Set the phase frontmatter `status: in-progress`. - - Spawn the `implementer` agent via the `Task` tool, passing that phase's scope and acceptance criteria. - - Wait for the agent's structured output. If `completion_score < 100`, re-spawn with `items_remaining` until the phase reaches 100 %. - - Set the phase frontmatter `status: done` once it reaches 100 %. -4. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. -5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. -6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. -7. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. -8. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. - -## Test - -- A missing or unreadable plan path with no inline plan content stops the skill with `plan not found at `, and no substitute plan is fabricated. -- After the loop terminates: every phase has its acceptance criteria checked off and its frontmatter `status` is `done`, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md new file mode 100644 index 00000000..1879ce66 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -0,0 +1,23 @@ +# 01 - Prepare + +Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress. + +## Input + +A plan, passed via `$ARGUMENTS` as a path or inline content. + +## Output + +The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves. + +## Process + +1. **Resolve.** Resolve the plan from `$ARGUMENTS`. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at `. Never fabricate a plan. +2. **Branch.** On the default branch, run `git checkout -b ` and announce it. On a non-default branch, keep it. +3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. + +## Test + +- A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. +- `git rev-parse --abbrev-ref HEAD` is not the default branch. +- The plan frontmatter reads `status: in-progress`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md new file mode 100644 index 00000000..dc020553 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -0,0 +1,25 @@ +# 02 - Execute + +Loop the plan's phases in order, coding each until every acceptance criterion holds. + +## Input + +The prepared plan on its feature branch, from `01-prepare`. + +## Output + +Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan. + +## Process + +1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. +2. **Code.** Build the phase scope against its acceptance criteria. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together. +4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the caller's job, not this recipe's. + +## Test + +- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits). +- The branch holds one commit per phase; there are no separate `in-progress` status commits. +- A blocker leaves the plan `status: blocked` with no later phase run. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md new file mode 100644 index 00000000..2943bc42 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -0,0 +1,21 @@ +# 03 - Finalize + +Run the validation and mark the plan implemented once every phase is done. + +## Input + +A plan whose phases are all `status: done`, from `02-execute`. + +## Output + +The feature validated green with the plan frontmatter `status: implemented`. + +## Process + +1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. +2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. + +## Test + +- The validation commands exit zero. +- The plan reads `status: implemented`, committed (`git status --short` shows it clean). diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md index 3bdd7dc6..505a3389 100644 --- a/plugins/aidd-dev/skills/02-implement/references/blocked.md +++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md @@ -4,6 +4,7 @@ description: Conditions that make a plan blocked (needs a human). --- # When a plan is blocked -`blocked` = implementation cannot proceed; only a human can unblock. Stop, set `status: blocked`, escalate. + +`blocked` means implementation cannot proceed and only a human can unblock it. Stop, set `status: blocked`, and escalate. Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA. diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index c0a9c069..2d79a27d 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -2,13 +2,13 @@ # 03 - assert -Validates implementations through iterative assertion loops. Covers general -feature assertions, architecture conformance (ADRs, diagrams, project -structure), and browser-based frontend UI checks. +A gate that validates the work behaves as intended: it iterates the project's +coding assertions until they pass, with optional architecture-conformance and +running-frontend facets. Returns a pass or fail verdict. ## When to use -- A feature is implemented and you need to assert it behaves as intended +- Work is implemented and you need to assert it behaves as intended before merging or shipping. - You need to verify code conforms to documented architecture (ADRs, diagrams, structure). @@ -30,21 +30,19 @@ structure), and browser-based frontend UI checks. Use skill aidd-dev:03-assert ``` -The skill exposes 3 actions: +The skill exposes 3 facets, run together when applicable or one when named: -1. `assert` - general assertion loop against an acceptance criterion. -2. `assert-architecture` - verify code matches architecture diagrams, - ADRs, and the project's documented structure. -3. `assert-frontend` - drive a browser to confirm a frontend feature - behaves as intended. +1. `assert` - the coding-assertion loop; always applies. +2. `assert-architecture` - report where code breaks the documented + architecture (ADRs, diagrams, structure); report only, opt-in. +3. `assert-frontend` - drive a browser to confirm the frontend + behaves as intended; needs a running frontend (it resolves the URL). ## Outputs -- A pass / fail verdict per assertion, with the failing item identified. -- Recorded findings when an assertion fails (file, line, expected vs - observed). -- Browser session artifacts (screenshots, console output) for the - frontend variant. +- A pass or fail verdict on the work (this is a gate, not a stored report). +- The fixes applied by the coding and frontend facets. +- The conformance violations from the architecture facet. ## Prerequisites diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 6594114d..7e03bdd0 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,34 +1,30 @@ --- name: 03-assert -description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +description: Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests. argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- # Skill: assert -Validates correctness of implementations through iterative assertion loops, architecture checks, and browser-based frontend verification. +Validate that the work behaves as intended: run the project's assertions, iterating and fixing until they pass. -## Available actions - -| # | Action | When to use | -| --- | --------------------- | ---------------------------------------------------------------------------- | -| 01 | `assert` | Iterate until a feature works by running the project's coding assertions | -| 02 | `assert-architecture` | Verify the codebase conforms to documented architecture (C4, ADRs, tree) | -| 03 | `assert-frontend` | Iterate until a frontend feature works by inspecting the running UI | +## Actions -## Routing (run first) +| # | Action | Facet | +| --- | --------------------- | ----------------------------------------------------------- | +| 01 | `assert` | Run the project's coding assertions, fixing until they pass | +| 02 | `assert-architecture` | Report where the code breaks the documented architecture | +| 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -These actions are complementary facets, not mutually exclusive. This skill is run-one-OR-run-all: +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a frontend is running, the facet resolving the URL itself; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. -- The user named a facet ("assert the frontend", "check architecture conformance") -> run that ONE action. -- The user asked for an unscoped assertion ("assert this works", "make the feature pass") -> ask ONE question: "Assert everything applicable, or a specific facet (coding / architecture / frontend)?" Then run all applicable, or the chosen one. -- Never silently default to action 01. Never run a blind all without offering the choice first. +## Transversal rules -When running all applicable: `01-assert` is the baseline (project coding assertions); add `03-assert-frontend` when the feature has a UI and a running frontend URL; add `02-assert-architecture` when architecture conformance is in scope. A facet whose precondition is absent (e.g. no running URL) is skipped with a noted reason, never forced. Run the selected actions in order (01, then 03, then 02). Read and follow each selected action file. +- Gate: it returns a pass or fail verdict on the work. +- Fix loop: the coding and frontend facets fix and re-run until they pass. The architecture facet only reports, never fixes. +- Stop only when every selected assertion passes a final clean sweep. -## Actions +## Assets -- `@actions/01-assert.md` -- `@actions/02-assert-architecture.md` -- `@actions/03-assert-frontend.md` +- `assets/task-template.md`: the tracking file the frontend facet fills across its fix loop. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index cea380da..b744f5f0 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -1,32 +1,23 @@ # 01 - Assert -Iterate until a feature works as intended by running the project's coding assertions and fixing every failure. +Iterate the project's coding assertions until the work passes every one, fixing each failure. -## Inputs +## Input -```yaml -feature: -``` +The work to assert, named or described, from `$ARGUMENTS` or the context. -## Outputs +## Output -```yaml -assertions_total: -assertions_passing: -iterations: -fixes_applied: - - { file: , change: } -``` +A pass or fail verdict: every applicable assertion passing in a final clean sweep, with the fixes applied listed. ## Process -1. **Enumerate assertions.** From the current context (project conventions and coding-assertions memory), list the assertions that apply to the feature. -2. **Iterate per assertion.** For each one: - - Fix any issues preventing it from passing. - - Re-run the assertion to confirm it passes. -3. **Full re-check.** Once every assertion has passed at least once, re-run all of them in one sweep to confirm none regressed. -4. **Boundary.** Do not stop until every assertion passes in the final sweep. +1. **Enumerate.** List the assertions that apply, from the project conventions and `aidd_docs/memory/coding-assertions.md` when it exists. +2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. +3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. +4. **Boundary.** Do not stop until every assertion passes the final sweep. ## Test -The final sweep reports `assertions_passing == assertions_total`; the recorded `fixes_applied` list cites real diffs (no empty or placeholder entries when fixes were claimed). +- The final sweep passes every applicable assertion. +- The fixes listed cite real diffs, with no placeholder entries. diff --git a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md index 8125bcd1..1500fa60 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md +++ b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md @@ -1,48 +1,24 @@ # 02 - Assert Architecture -Verify that the codebase (or a specific scope) conforms to the documented architecture: C4 diagrams, ADRs, and project tree structure. +Report where the codebase breaks the documented architecture: C4 diagrams, ADRs, and the project tree. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire project -``` +The scope to check, a module, service, or layer, from `$ARGUMENTS`; defaults to the whole project. -## Outputs +## Output -```yaml -report: - macro: - - { severity: critical|warning, file: , constraint: , fix: } - micro: - - { severity: critical|warning, file: , constraint: , fix: } -totals: - violations_total: - critical: - warning: -``` +A conformance report listing each violation, grouped macro and micro, with severity, file, the constraint broken, and a one-line fix. Report only; it never fixes. ## Process -1. **Load architecture context.** - - Remember the architecture diagrams from `aidd_docs/memory/architecture.md`. - - Read micro diagrams from `aidd_docs/memory/internal/` when the scope targets a specific module. - - Read ADRs from `aidd_docs/internal/decisions/`. - - Extract the expected project tree structure from the diagrams. -2. **Verify macro architecture (service boundaries).** - - Compare actual code structure against the documented tree. - - Flag files outside expected boundaries. - - Flag direct imports between independent services. -3. **Verify micro architecture (internal layers).** For each module in scope: - - Check that import directions match layer constraints. - - Confirm the domain layer has zero external imports. - - Confirm the application layer depends only on the domain via ports. - - Detect circular dependencies between modules. - - Verify the expected patterns (use cases have ports, adapters implement interfaces). -4. **Build the violation report.** Each entry carries severity (`critical | warning`), file path, the constraint violated, and a one-line suggested fix. Group entries macro vs micro. -5. **Boundary.** Do not fix violations - only report them. If no scope is provided, check the entire project. -6. **Summarize.** Total violations, critical count, recommended next actions. +1. **Load.** Read the architecture sources: the architecture memory, the micro diagrams for an in-scope module, and the decision records. Extract the expected project tree. +2. **Macro.** Compare the code structure against the documented tree. Flag files outside their boundary and direct imports between independent services. +3. **Micro.** For each in-scope module, check import directions against the layer constraints. The domain layer imports nothing external. The application layer reaches the domain only through ports. No circular dependencies. Adapters implement their interfaces. +4. **Report.** One entry per violation, grouped macro and micro, each with severity (`critical` or `warning`), file, constraint, and a one-line fix. Never fix, only report. +5. **Summarize.** The total violations, the critical count, and the recommended next actions. ## Test -If conformity holds: `violations_total == 0` and the report explicitly states "no violations" in both macro and micro sections. If violations exist: every report entry has a real file path that exists on disk, a referenced constraint that appears in one of the loaded architecture sources, and a non-empty `fix` field. +- On conformance, the report states "no violations" in both the macro and micro sections. +- On violations, every entry has a real file path, a constraint drawn from a loaded architecture source, and a non-empty fix. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 92ae09f4..c26d9bc4 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -1,40 +1,26 @@ # 03 - Assert Frontend -Iterate until a frontend feature works as intended by inspecting the running UI, mapping the behavior to the code, and tracking attempts in a task template. +Iterate until the frontend behaves as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. -## Inputs +## Input -```yaml -expected_behavior: -url: # required; the frontend must already be running -``` +The expected behavior, from `$ARGUMENTS`. The frontend's URL when the caller knows it, otherwise resolved at runtime. -## Outputs +## Output -```yaml -task_template_path: -iterations: -fixed: true|false -report: - - { iteration: , hypothesis: , fix_attempted: , validated: pass|fail } -``` +A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result) recorded in the tracking file. ## Process -Iterate over the steps below until the feature works as intended. - -1. **Parse the request.** Extract expected requirements (visual, functional, technical) from `expected_behavior`. Summarize and list action paths (e.g. user clicks button -> calls function in file1 -> updates state in file2). -2. **Inspect the running app.** Open the URL via the configured browsing tool. Inspect the page visually and technically. Take screenshots to confirm the issue. -3. **Locate the code.** Explore the codebase to find the files and snippets related to the issue. -4. **Fill the tracking template** from `@../assets/task-template.md`. List the three best potential causes with a short description and confidence level. -5. **Fix-loop.** - - Take the first potential cause. - - Apply a candidate fix. - - Validate against the expected behavior. - - If not fixed, mark the cause and move to the next. - - When the three causes are exhausted, re-evaluate, add three new causes to the template, and repeat from step 5. -6. **Boundaries.** Assume all servers are already running. Minor visual discrepancies (1-2 px differences, slight color variations) are acceptable unless explicitly specified in the initial request. Screenshots MUST be used to validate UI changes. +1. **Resolve.** Use the URL the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. +2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. +3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. +4. **Locate.** Explore the codebase for the files behind the issue. +5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +6. **Fix.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test -The task template file exists and is updated for every iteration; the final entry in `report` has `validated: pass`; the running URL renders the expected behavior, confirmed by a screenshot recorded after the final iteration. +- The tracking file updates on every iteration. +- The final recorded attempt validates as a pass, confirmed by a screenshot taken after it. diff --git a/plugins/aidd-dev/skills/03-assert/assets/task-template.md b/plugins/aidd-dev/skills/03-assert/assets/task-template.md index cdc9e1db..dc2beec2 100644 --- a/plugins/aidd-dev/skills/03-assert/assets/task-template.md +++ b/plugins/aidd-dev/skills/03-assert/assets/task-template.md @@ -1,15 +1,11 @@ ---- -name: task -description: Task tracking system to ensure all tasks are categorized and addressed ---- + # Task [] {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} - [ ] {Task 3} -- ... diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index 72003c6f..e258791a 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -2,18 +2,17 @@ # 05 - review -Reviews completed work along two axes: code quality against project rules, -and feature behavior against the plan's acceptance criteria. Runs in a -fresh context via the `reviewer` agent and returns findings plus completion -and quality scores. Never edits the artifact. +Reviews a diff along three axes: code quality (clean-code), feature behavior +against the plan's acceptance criteria, and relevancy (does the change belong: +fit to the need, declared-rule conformance, no rot). Read-only: surfaces +findings and one verdict into a single report, never edits the artifact. Runs +all three axes by default, or one when named. ## When to use - A feature is implemented and you need an independent verdict before shipping. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `review` step to this skill. -- A diff needs a rule-based code review without ad-hoc opinion. +- A diff needs a grounded review without ad-hoc opinion. ## When NOT to use @@ -28,37 +27,42 @@ and quality scores. Never edits the artifact. ## How to invoke ``` -Use skill aidd-dev:05-review +Use skill aidd-dev:05-review # all three axes +Use skill aidd-dev:05-review review-relevancy # one named axis ``` -The skill exposes 2 actions: +The skill exposes 3 axes, run together by default or one when named: -1. `review-code` - grade the diff against project rules; surface - violations with file, line, and rule reference. +1. `review-code` - grade the diff against clean-code principles; surface + violations with file and line. 2. `review-functional` - verify the feature against the plan's acceptance - criteria; emit per-criterion pass / fail. + criteria; per-criterion trace plus missing / unplanned / edge-case gaps. +3. `review-relevancy` - judge whether the change belongs: fit to the need, + conformance to the project's declared rules, and no duplication or + over-engineering. ## Outputs -- A read-only report (never patches the code): - - `review-code` - a verdict (`approve` / `changes-requested` / `blocked`) - plus a findings table with 3-level severity (🔴 critical / 🟡 warning / - 🟢 minor), `file:line`, issue, and a suggested fix to hand off to - [07-refactor](../07-refactor/README.md). - - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a - per-criterion scoring matrix; missing or broken behaviors hand off to - [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). -- The `reviewer` agent still returns `ship` / `iterate` to the SDLC - orchestrator. +- One read-only `review.md` in the reviewed work's feature folder, beside + `plan.md`, never patches the code: + - Header: the overall verdict (`approve` / `changes-requested` / `blocked`, + the strictest across the axes run), scope, axes run, findings count. + - `Code` section: severity-rated findings (🔴 / 🟡 / 🟢) with `file:line`; + fixes hand off to [07-refactor](../07-refactor/README.md). + - `Functional` section: per-criterion matrix plus the gap lists; fixes hand + off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). + - `Relevancy` section: misfits by lens (`fit` / `conform` / `rot`), each + tied to a rule, a duplication site, a smell, or a named need-gap. + - An axis not run is marked "Not run". ## Prerequisites - A diff or a set of changes to review. - A plan file with explicit acceptance criteria for the functional axis. -- Project rules loaded in context for the code axis. +- The project's declared rules, discovered at runtime, for the relevancy axis. ## Technical details -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two -review contracts. The skill runs the `reviewer` agent in fresh context to -avoid bias from the implementation conversation. +See [`SKILL.md`](SKILL.md), [`actions/`](actions/), and the report template in +[`assets/`](assets/) for the three review axes and the single report they +compose. diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index b5d2fdbc..6e0e4894 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,37 +1,37 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). -argument-hint: review-code | review-functional +description: Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase. +argument-hint: review-code | review-functional | review-relevancy model: opus -context: fork -agent: reviewer --- # Skill: review -Read-only review of a diff (a PR or working changes): code quality against project rules, and feature behavior against the plan's acceptance criteria. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. +Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. -## Agent delegation - -Spawn the `reviewer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `reviewer` agent explicitly with this skill's content as the prompt. +## Actions -## Available actions +| # | Action | Axis | +| --- | ------------------- | ---------------------------------------------------------------- | +| 01 | `review-code` | Clean-code quality on the changed lines | +| 02 | `review-functional` | The diff against the plan's acceptance criteria | +| 03 | `review-relevancy` | Does the change belong: fit to the need, rule conformance, no rot | -| # | Action | When to use | -| --- | ------------------- | ------------------------------------------------------------------------ | -| 01 | `review-code` | Quality review of a diff against project rules and clean-code principles | -| 02 | `review-functional` | Verify the diff matches the plan's acceptance criteria, flows, edge cases | +Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. -## Routing (run first) +## Transversal rules -Pick the ONE action matching the user's intent; do NOT default to action 01. +- Read-only: surface each finding with its fix described, never patch. +- Output: always write `review.md` to disk; the file is the deliverable, never an inline-only verdict. +- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. +- Sections: fill `review.md` from `@assets/review-template.md`, each axis its own section, an unrun axis marked "Not run". +- Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. +- Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. -- "review the code", "check code quality", "rules compliance", "clean code review" -> `01-review-code` -- "does it match the plan", "functional review", "behavior vs acceptance criteria" -> `02-review-functional` +## References -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +- `references/review-rubric.md`: the severity scale, the verdict rule, the code categories, and the relevancy lenses. -## Actions +## Assets -- `@actions/01-review-code.md` -- `@actions/02-review-functional.md` +- `assets/review-template.md`: the single report the three axes fill. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 0d2dc108..795e7582 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -1,34 +1,23 @@ # 01 - Review Code -Deep code review of a diff against project rules and clean-code principles. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. +Grade the diff against clean-code principles and record the findings in the review report. -## Inputs +## Input -```yaml -scope: # optional; defaults to `git diff main` -``` +The diff to review, a git ref range or path, from `$ARGUMENTS`; defaults to `git diff main`. -## Outputs +## Output -```yaml -review_path: aidd_docs/tasks//_/review.md -verdict: approve | changes-requested | blocked -findings_count: -severity_breakdown: - critical: # 🔴 - warning: # 🟡 - minor: # 🟢 -``` +The `Code` section of the feature folder's `review.md`, filled with severity-rated findings, each citing a changed `file:line`. ## Process -1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. -2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. -3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -6. **Write to disk** at `aidd_docs/tasks//_/review.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Resolve.** Take the diff from `$ARGUMENTS`, otherwise `git diff main`. +2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Declared-rule conformance belongs to the relevancy axis, not this one. +3. **Rate.** One finding per issue on the changed lines, rated and categorized per `@../references/review-rubric.md`, citing a `file:line`. Describe the fix, never patch. +4. **Record.** Write the findings into the `Code` section of `review.md`, each with its fix described. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +- The `Code` section of `review.md` is filled, every finding rated and citing a changed `file:line`. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 4b3bd0a0..1495f071 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -1,45 +1,24 @@ # 02 - Review Functional -Verify the implemented feature matches the plan's acceptance criteria, flows, and edge cases. Static review of the current diff against plan intent. No app execution, no browser, no code-quality checks. Read-only: surface gaps, never patch them - hand a missing behavior off to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. +Verify the diff matches the plan's acceptance criteria, flows, and edge cases, and record the result in the review report. -## Inputs +## Input -```yaml -plan_path: # required via $ARGUMENTS or prompt -diff_scope: # optional; defaults to `git diff main` -``` +The plan path holding the acceptance criteria, from `$ARGUMENTS` or the prompt, and the diff to trace (a git ref range; defaults to `git diff main`). -## Outputs - -```yaml -review_path: aidd_docs/tasks//_/review-functional.md -criteria_total: -criteria_traced: -missing_behaviors: -unplanned_behaviors: -edge_case_gaps: -``` - -## Rules - -Check against: - -- Inconsistencies -- Duplications -- Non logical Flows or Steps +## Output +The `Functional` section of the feature folder's `review.md`: one row per acceptance criterion traced to the diff, plus the missing, unplanned, and edge-case gaps. ## Process -1. **Read the plan.** Use `plan_path` from `$ARGUMENTS` when provided; otherwise ask the user to supply the acceptance criteria directly. -2. **Extract acceptance criteria.** If they exist in the plan, ask the user to validate them before proceeding. If missing, ask the user to provide them. -3. **Fetch the diff.** Use `diff_scope` when provided; otherwise `git diff main`. -4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. -5. **List missing behaviors** (criteria with no trace in the diff). -6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List flow and edge-case gaps** surfaced by walking through each criterion. -8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//_/review-functional.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask for the acceptance criteria, and mark this axis "Not run" when none are available. Static review only, no app execution or browser. +2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. +3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. +4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`, each with the missing or broken behavior named. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +- The `Functional` section of `review.md` holds exactly one row per acceptance criterion. +- The missing, unplanned, and edge-case lists are present, each reading "none" when empty. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md new file mode 100644 index 00000000..f56f04cc --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md @@ -0,0 +1,24 @@ +# 03 - Review Relevancy + +Judge whether the diff belongs, coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built, and record the misfits in the review report. + +## Input + +The diff to review (a git ref range or path; defaults to `git diff main`), the need it serves (the plan objective or the ticket), and the project's declared rules and conventions, discovered at runtime. + +## Output + +The `Relevancy` section of the feature folder's `review.md`, filled with misfit findings under the lenses `fit`, `conform`, and `rot`, each tied to evidence. + +## Process + +1. **Gather.** Resolve the diff from `$ARGUMENTS`, otherwise `git diff main`. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. +2. **Fit.** Check the change against the need: does it serve the actual intent end to end, or only the literal criteria? Flag any drift between intent and result. +3. **Conform.** Check the change against the declared rules and the surrounding conventions. Flag each violation with the rule or pattern it breaks. +4. **Rot.** Scan for duplication (an existing helper reinvented), over-engineering (speculative generality, unused abstraction), and incoherence (naming, docs versus code). Cite the site. +5. **Record.** Write each finding into the `Relevancy` section of `review.md`, rated and placed under its lens per `@../references/review-rubric.md`. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. Describe the fix, never patch. + +## Test + +- The `Relevancy` section of `review.md` is filled, every finding under a lens and tied to a `file:line`, a declared rule, a duplication site, or a named need-gap. +- No finding is a bare opinion, and no code is patched. diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md deleted file mode 100644 index 2fbff291..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: review-code -description: Code review report template for a diff -argument-hint: N/A ---- - -# Code Review: {{feature}} - -{{one_line_summary}} - -- **Verdict**: {{approve | changes-requested | blocked}} -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} -- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor - -Verdict: `approve` = no critical findings, ship it; `changes-requested` = warnings or a fixable critical to address first; `blocked` = a critical that must not merge. - -## Expected changes - -What the diff was meant to deliver (from the ticket or plan). Tick what the diff actually does. - -- [ ] {{expected_change_1}} -- [ ] {{expected_change_2}} - -## Findings - -One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. - -Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. - -| Sev | Category | Location | Issue | Suggested fix | -| --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | -| 🔴 | security | `src/api/user.ts:30` | Request body used without validation | Validate with the project schema lib | -| 🟡 | code-health | `LivePreview.tsx:43` | `user` recomputed on every render | Memoize with `useMemo` | - -## Coverage - -Dimensions examined on the diff (a dimension with no finding is still listed here as scanned; one not applicable to this diff is marked n/a). - -- **Scanned**: {{dimensions examined, comma-separated}} -- **Not applicable**: {{dimensions n/a for this diff, or "none"}} - -## Follow-up - -- **Top fixes** (ranked, hand off to `aidd-dev:07-refactor`): {{top_fixes}} -- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md deleted file mode 100644 index 9de9d828..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: review-functional -description: Functional review report template for a diff against a plan -argument-hint: N/A ---- - -# Functional Review: {{feature}} - -- **Plan**: `{{plan_path}}` -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} - -## Verdict - -{{PASS | PARTIAL | FAIL}} - {{one_line_rationale}} - -Verdict: `PASS` = every criterion Met; `PARTIAL` = some criteria Partial or Unmet but none blocking; `FAIL` = at least one 🔴 blocking gap. - -## Scoring Matrix - -One row per acceptance criterion. Severity uses the shared 3-level scale (it applies to `Partial` / `Unmet` rows only). - -| Criterion | Files | Status | Severity | Notes | -| ---------------- | ----- | --------------------- | --------------------------------- | ----- | -| {{criterion}} | | Met / Partial / Unmet | 🔴 blocker / 🟡 major / 🟢 minor | | - -- Status - `Met`: fully implemented in the diff; `Partial`: implemented with gaps; `Unmet`: absent from the diff. -- Severity - 🔴 blocker: feature cannot ship; 🟡 major: shipping degrades UX; 🟢 minor: cosmetic or non-blocking. - -## Missing behaviors - -Acceptance criteria with no trace in the diff (hand off implementation to `aidd-dev:02-implement`; if a criterion is implemented but broken, hand off to `aidd-dev:08-debug`). - -- [ ] {{criterion not found in diff}} - -## Unplanned behaviors - -Changes present in the diff but traced to no acceptance criterion. - -- [ ] {{unplanned change - confirm scope with author}} - -## Flow / edge-case gaps - -Gaps surfaced while walking each criterion against the diff. - -- [ ] {{flow or edge-case gap}} - -## Summary - -- **Criteria covered**: {{x/y}} -- **Blockers**: {{count}} -- **Follow-up actions**: {{actions}} -- **Additional notes**: {{notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md new file mode 100644 index 00000000..8c6df3ad --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -0,0 +1,43 @@ + + +# Review: {{feature}} + +{{one_line_summary}} + +- **Verdict**: {{approve | changes-requested | blocked}} +- **Diff scope**: `{{base}}...{{head}}` +- **Axes run**: {{code, functional, relevancy}} +- **Date**: {{yyyy_mm_dd}} +- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor + +Verdict: `approve` = ship it; `changes-requested` = fix the warnings or fixable criticals first; `blocked` = a critical that must not merge. The overall verdict is the strictest across the axes run. + +## Code + +Clean-code findings on the changed lines (or "Not run"). + +| Sev | Category | Location | Issue | Suggested fix | +| --- | -------- | -------- | ----- | ------------- | + +## Functional + +Each acceptance criterion traced to the diff (or "Not run"). + +| Criterion | Met | Evidence / gap | +| --------- | --- | -------------- | + +- **Missing behaviors**: {{criteria with no trace, or "none"}} +- **Unplanned behaviors**: {{diff changes tracing to no criterion, or "none"}} +- **Edge-case gaps**: {{gaps, or "none"}} + +## Relevancy + +Does the change belong (or "Not run"). Every finding ties to evidence, never an opinion. + +| Sev | Lens | Location / rule | Misfit | Suggested fix | +| --- | ---- | --------------- | ------ | ------------- | + +## Follow-up + +- **Top fixes** (ranked): {{top_fixes}} +- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/references/review-rubric.md b/plugins/aidd-dev/skills/05-review/references/review-rubric.md new file mode 100644 index 00000000..759ee612 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/review-rubric.md @@ -0,0 +1,27 @@ +# Review rubric + +Shared definitions for the three review axes. The actions and the report template draw from here, so the scales live in one place. + +## Severity + +- 🔴 critical: must not merge as-is. +- 🟡 warning: should fix. +- 🟢 minor: nit. + +## Verdict + +One overall verdict, the strictest across the axes run: + +- `approve`: no critical finding, ship it. +- `changes-requested`: warnings, or a fixable critical to address first. +- `blocked`: a critical that must not merge. + +## Code categories + +`standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. + +## Relevancy lenses + +- `fit`: serves the real need, not only the literal criteria. +- `conform`: the project's declared rules and the surrounding conventions. +- `rot`: duplication, over-engineering, incoherence (naming, docs versus code). diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md index c8e1aad0..83c22497 100644 --- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md +++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md @@ -52,7 +52,7 @@ status: pending ## Applicable rules - + | Tool | Name | Path | Why it applies | | ------ | ------ | ------------------------------------- | -------------- | diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md index 727b75be..734bde80 100644 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ b/plugins/aidd-dev/skills/10-todo/README.md @@ -2,7 +2,7 @@ # 10 - todo -Split one prompt into independent todos, run one implementer agent per +Split one prompt into independent todos, run one executor agent per todo in parallel (each refines its todo before coding), and report a minimal table: category, what was launched, output. diff --git a/plugins/aidd-dev/skills/10-todo/SKILL.md b/plugins/aidd-dev/skills/10-todo/SKILL.md index 85a589b7..51137ace 100644 --- a/plugins/aidd-dev/skills/10-todo/SKILL.md +++ b/plugins/aidd-dev/skills/10-todo/SKILL.md @@ -1,6 +1,6 @@ --- name: 10-todo -description: Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. +description: Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. --- # Todo diff --git a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md index d918c682..504a1140 100644 --- a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md +++ b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md @@ -17,7 +17,7 @@ User's requirement. 1. **Read.** Take `prompt` from `$ARGUMENTS`; if empty, ask the user. 2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent, using template. -3. **Launch.** Spawn one `implementer` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: +3. **Launch.** Spawn one `executor` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: ```markdown 1. Refine the todo first - discover at runtime a skill whose description covers refining or clarifying a request (never a hardcoded plugin name) and run it on the todo. 2. Implement the refined todo. diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 5da05e2f..d4a73cbd 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -58,5 +58,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | | `-` | [README.md](skills/04-spec/README.md) | - | -| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec.` | +| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec.` | diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md index 80d2829d..8a593136 100644 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ b/plugins/aidd-pm/skills/04-spec/README.md @@ -2,17 +2,15 @@ # 04 - Spec -Generates or refines the immutable contract between human intent and the -downstream agents that will plan, implement, and review the work. The spec -is what a planner consumes; it stays free of implementation detail and is -locked once validated. +Generate or refine the immutable contract for a feature: its target, hard +constraints, non-goals, and done-when. The spec stays free of implementation +detail and is locked once validated. ## When to use - "draft spec", "spec for X", "generate spec from prd". -- "refine the spec" when reviewer findings come back. +- "refine the spec" when review findings come back. - Invoking `/spec`. -- When an orchestrator needs a normalized contract before triggering a plan. ## When NOT to use @@ -29,7 +27,7 @@ Build a fresh spec from a request or an existing PRD: Use skill aidd-pm:04-spec build for ``` -Refine an existing spec from reviewer findings: +Refine an existing spec from review findings: ``` Use skill aidd-pm:04-spec refine on with @@ -44,20 +42,19 @@ and `findings` triggers `refine`; otherwise `build` runs. with explicit non-goals, bulleted acceptance criteria, and `TBD: ` markers wherever information is missing. - On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates; the caller spawns a reviewer using - [`assets/spec-validator.yml`](assets/spec-validator.yml) and feeds the - findings back through `refine` for the next iteration. +- The skill never self-validates. A spec is checked against + [`assets/spec-validator.yml`](assets/spec-validator.yml); the findings come + back through `refine` for the next iteration. ## Prerequisites - A free-form request, an existing PRD path, or an existing spec plus a - set of reviewer findings. + set of review findings. - Write access to the spec target path in the current repo. ## Technical details See [`SKILL.md`](SKILL.md) for the action contract, [`actions/01-build.md`](actions/01-build.md) and -[`actions/02-refine.md`](actions/02-refine.md) for the two atomic actions, -and [`assets/`](assets/) for the canonical template plus the validator -checklist used by reviewers. +[`actions/02-refine.md`](actions/02-refine.md) for the two actions, +and [`assets/`](assets/) for the spec template plus the validator checklist. diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index a356c7b3..1b099bc2 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,46 +1,31 @@ --- name: 04-spec -description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +description: Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec. argument-hint: build | refine --- -# Spec +# Skill: spec -Generates or refines the immutable contract between human intent and downstream agents. +Generate or refine the immutable contract for a feature: its target, hard constraints, non-goals, and done-when. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | --------- | ----------------------------------------------------------------- | -------------------------------------- | -| 01 | `build` | Create a fresh spec from a free-form request or an existing PRD | request or prd_path, feature_name | -| 02 | `refine` | Rewrite an existing spec to address reviewer findings | existing_spec, findings | +| # | Action | Role | Input | +| --- | -------- | ---------------------------------------------------- | ---------------------------- | +| 01 | `build` | Draft a fresh spec from a request or an existing PRD | a request or a PRD path | +| 02 | `refine` | Rewrite an existing spec to address review findings | a spec path and the findings | -## Default flow - -Non-sequential. The router dispatches based on inputs: - -- `existing_spec` and `findings` present -> `refine` -- `request` or `prd_path` present -> `build` +Dispatch by input: a spec path with findings runs `refine`; a request or PRD path runs `build`. ## Transversal rules -- Never invent missing information. Mark every gap as `TBD: ` instead of guessing. -- If the request is too vague to draft a useful spec, return early and ask the user to brainstorm the request first; do not fabricate intent. -- Never modify a spec that has been validated and locked. -- The spec is the contract; it is immutable once validated. -- Keep the spec readable: clear section headers, bulleted criteria, explicit non-goals. -- Never include implementation detail (libraries, patterns, file layout); those belong to the plan. -- Do not self-validate. The caller spawns a reviewer with `@assets/spec-validator.yml`; findings come back through the `refine` action for the next iteration. - -## References - -- None. +- Never invent. Mark every gap as `TBD: ` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one. +- The spec holds intent, never implementation. It is solution-agnostic: no file, component, hook, route, library, pattern, or token, and no "how". The done-when conditions are outcome-level, not steps. Keep the acceptance criteria few. All of that belongs to the plan. +- Keep it readable: clear section headers, bulleted criteria, explicit non-goals. +- Output: one `spec.md` in the feature folder (`aidd_docs/tasks//_/`), from `@assets/spec-template.md`. Reuse the folder when it exists. +- Immutable once validated: never rewrite a spec that has been locked. ## Assets -- `@assets/spec-template.md`: canonical structure of a spec. -- `@assets/spec-validator.yml`: checklist used by the reviewer to validate a spec. - -## External data - -- None. +- `assets/spec-template.md`: the spec's structure. +- `assets/spec-validator.yml`: the checklist a spec is validated against. diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index f9696608..0a177962 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -1,35 +1,25 @@ # 01 - Build -Create a fresh spec from a free-form request or by extracting fields from an existing PRD. +Draft a fresh spec from a free-form request, or by lifting fields from an existing PRD. -## Inputs +## Input -```yaml -request: # required when prd_path is absent -prd_path: # required when request is absent -feature_name: # required; derived from the request when absent -``` +A free-form request, or a path to an existing PRD. A feature name for the folder, derived from the request when absent. -## Outputs +## Output -```yaml -spec_path: aidd_docs/tasks//_/spec.md -status: draft -notes: -``` +The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted. ## Process -1. **Source resolution**. Pick first match: - - `prd_path` provided -> parse the PRD, lift target, hard constraints, non-goals, and done-when into the matching template sections; drop libraries, patterns, and file-layout content - - `request` provided -> use `assets/spec-template.md` directly and map the request onto its sections -2. **Mark gaps**. Replace any missing required field with `TBD: `. Never guess. -3. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -4. **Write**. Resolve the feature folder: reuse the one for this feature when it already exists under `aidd_docs/tasks//_/`, otherwise create it. Save the spec there as `spec.md`. -5. **Return** the structured Outputs block with `status: draft`. +1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase or name any file, component, or API: the spec stays solution-agnostic, intent only. +2. **Gaps.** Replace any missing required field with `TBD: `. Never guess. +3. **Check.** Confirm every section the validator requires is present. +4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`. +5. **Return.** Surface the spec path and the notes. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **No implementation**: the file has no library names, framework patterns, or source-file layout. +- `spec.md` exists in the feature folder. +- It contains every section listed in `@../assets/spec-validator.yml`. +- It carries no library name, framework pattern, or source-file layout. diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md index 3bf1f7c8..6783f0a9 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -1,34 +1,24 @@ # 02 - Refine -Rewrite an existing spec in place to address reviewer findings. +Rewrite an existing spec in place to address review findings. -## Inputs +## Input -```yaml -existing_spec: # required -findings: # required; list or text -``` +The path to the current spec, and the findings to address, a list or free text. -## Outputs +## Output -```yaml -spec_path: # same as existing_spec -status: refined -notes: -``` +The refined spec at the same path, with the changes applied and any residual `TBD` questions noted. ## Process -1. **Load**. Read `existing_spec` and `findings`. -2. **Map findings**. Pair each finding with the section of the spec it touches. -3. **Rewrite**. Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Preserve sections the findings do not touch. -4. **Mark gaps**. Replace any field still unanswered with `TBD: `. Never guess. -5. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -6. **Write**. Save the refined spec back to the same path as `existing_spec` (overwrite). -7. **Return** the structured Outputs block with `status: refined`. +1. **Load.** Read the spec and the findings. +2. **Map.** Pair each finding with the section it touches. +3. **Rewrite.** Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Leave untouched sections as they are. +4. **Gaps.** Replace any field still unanswered with `TBD: `. Never guess. +5. **Check.** Confirm every section the validator requires is present, then overwrite the spec at its path. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **Findings addressed**: every finding in `findings` is reflected by a change in the rewritten spec or by an explicit `TBD: ` if it cannot be resolved. +- The spec still exists at its path and holds every section listed in `@../assets/spec-validator.yml`. +- Every finding is reflected by a change, or by an explicit `TBD: ` when it cannot be resolved. diff --git a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml index 364d0aba..1da8edd5 100644 --- a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml +++ b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml @@ -1,4 +1,4 @@ -# Checklist used by the reviewer agent to validate a spec. +# Checklist a spec is validated against. # Each criterion is independently scored. Required criteria must be `fulfilled` for the spec to pass. criteria: diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 7a84091d..d8f484c3 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -41,7 +41,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | | `-` | [README.md](skills/01-commit/README.md) | - | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release.` | #### `skills/02-pull-request` @@ -49,11 +49,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | | `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | | `-` | [README.md](skills/02-pull-request/README.md) | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`.` | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch.` | #### `skills/03-release-tag` diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index e25cb790..2f5168e8 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,13 +1,13 @@ --- name: 01-commit -description: Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging. +description: Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release. --- # Commit -Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode. +Runs interactive with split approval, or auto for agents. -## Available actions +## Actions | # | Action | Role | Input | | --- | -------- | ------------------------------------------------------------- | ------------------------------------------- | @@ -26,22 +26,15 @@ When invoked as a slash command, the trailing argument controls the push behavio ## Transversal rules +- Project first: follow `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming); the rules below and the template are the fallback. - Commits stay atomic and focused on a single concern. - Messages use imperative mood ("Add feature" not "Added feature"). - Explain "why" not "what" in the body. - Never `--force` push. `--force-with-lease` is acceptable when explicitly required. -- Follow the conventional commit format defined in `@assets/commit-template.md`. +- Follow the conventional commit format defined in `@assets/commit-template.md` when the project sets none. - Reference issues in the commit body when applicable. - `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits. -## References - -- None. - ## Assets - `@assets/commit-template.md`: Conventional commit format reference. - -## External data - -- None. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md index b0a8171a..33238b71 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md @@ -1,55 +1,28 @@ # 01 - Commit -Stage files, generate or accept a commit message, run the commit, optionally push, and return the resulting sha. +Stage the change, write or accept a conventional message, commit, optionally push, and return the sha. -## Inputs +## Input -```yaml -mode: interactive | auto # default: interactive -message: # optional; when set, used as-is, no generation -push: true | false # default: false -files: [] # optional; restrict staging to these paths -``` +The mode (`interactive` default, or `auto`), an optional imposed message, whether to push (default no, set by a trailing `push` in `$ARGUMENTS`), and optional paths to restrict staging. -When invoked via slash command, parse `$ARGUMENTS`: +## Output -- contains the word `push` → set `push: true` -- empty or anything else → leave `push: false` - -## Outputs - -```yaml -commit_sha: -branch: -pushed: true | false -``` +The new commit sha, the branch, and whether it was pushed. ## Process -1. **Branch resolution**. Pick first match: - - branch already checked out -> use it - - `mode = auto` -> generate a conventional name from the change - - `mode = interactive` -> propose a name and wait for user approval -2. **Staging**. Pick first match: - - `files` set -> `git add` exactly those paths - - default -> use already-staged changes; do not add unstaged paths implicitly -3. **Message resolution**. Pick first match: - - `message` provided -> use it verbatim, skip steps 4 and 5 - - `mode = auto` -> inspect diff and `git log -5 --pretty=%B`, generate a message per `assets/commit-template.md`, no approval - - `mode = interactive` -> draft a message per the template, then proceed to steps 4 and 5 -4. **Interactive split** (when `mode = interactive` and multiple concerns are present). For each split, show: - - **Scope**: file list (proposal-only). - - **Draft message**: conventional subject; body explains "why", never lists files. - Wait for user approval. -5. **Interactive stage** (when `mode = interactive`). Run `git add -p` for each split. -6. **Commit**. Run `git commit` with the chosen message via heredoc. -7. **Hook recovery**. When a pre-commit hook fails, fix the underlying issue, re-stage, and create a new commit (do not amend). Loop until commit succeeds. -8. **Capture sha**. Read `git rev-parse HEAD`. -9. **Push**. When `push: true`, run `git push`. Use `--force-with-lease` only when explicitly required. Never `--force`. -10. **Return** the structured Outputs block. In interactive mode, also notify the user. +1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval. +2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly. +3. **Message.** Use an imposed message verbatim. Else follow `aidd_docs/memory/vcs.md` when set, otherwise `@../assets/commit-template.md`. In `auto`, generate from the diff and log, no approval; in `interactive`, draft and confirm. +4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`. +5. **Commit.** Run `git commit` with the chosen message. +6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds. +7. **Push.** When asked, `git push`. Use `--force-with-lease` only when explicitly required, never `--force`. +8. **Return.** Surface the sha, branch, and push state. ## Test -- **Sha match**: `git rev-parse HEAD` returns the new commit sha that matches the `commit_sha` field in Outputs. -- **Format**: `git log -1 --pretty=%s` matches the conventional commit regex `^(feat|fix|docs|style|refactor|perf|test|chore|build|ci)(\([^)]+\))?: .+`. -- **Push**: when `push: true`, `git ls-remote origin ` lists a sha equal to `commit_sha`. +- `git rev-parse HEAD` equals the returned sha. +- `git log -1 --pretty=%s` matches the conventional-commit format. +- When pushed, `git ls-remote origin ` lists the sha. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 7755da96..af224d27 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,13 +1,13 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`. +description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch. --- # Pull Request Drafts pull or merge requests from the current branch using the team's template, ready for the user to promote. -## Available actions +## Actions | # | Action | Role | Input | | --- | --------------- | ------------------------------------------------------------------- | ---------------------------------------------- | @@ -19,6 +19,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules +- Project first: follow `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base rules, labels); the rules below and the bundled templates are the fallback. - Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. @@ -26,17 +27,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph - Never commit, never push the working branch, never create new branches inside this skill. - Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL. -## References - -- None. - ## Assets - `@assets/pull_request.md`: Request body template. -- `@assets/branch.md`: Branch naming conventions. -- `@assets/CONTRIBUTING.md`: Contribution guidelines template. -- `@assets/README.md`: README template. - -## External data - -- None. +- `@assets/branch.md`: Branch-naming convention, the fallback when project memory sets none. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index cffa5b7c..e09f008e 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -1,48 +1,30 @@ # 01 - Pull Request -Detect the base branch, fill the request template with recent commits, validate with the user, and open a draft request via the configured VCS tool. +Detect the base branch, fill the request template from the recent commits, validate with the user, and open a draft request via the configured VCS tool. -## Inputs +## Input -```yaml -base_branch: # optional; auto-detect from repo state when omitted -template_overrides: # optional; override specific template sections - title: - body: -``` +An optional base branch (auto-detected when omitted), and optional title or body overrides. -## Outputs +## Output -```yaml -pr_url: -pr_number: -branch: -base: -is_draft: true -``` +The draft request's URL and number, with its head and resolved base branch. ## Process -1. **Tool resolution**. Pick first match: - - VCS tool declared in project memory -> use it - - default -> map `git remote get-url origin` to the matching configured tool -2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. -3. **Base resolution**. Pick first match: - - `base_branch` provided -> use it - - the branch-naming convention in project memory maps the head branch's prefix to a PR target (e.g. `feat/` -> `next`, `hotfix/` -> `main`) -> use that target - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging` - - surface the chosen value and the reason during validation -4. **Collect changes**. Run `git log ..HEAD --pretty=fuller` and `git diff ...HEAD --stat` to summarize commits and impacted files. -5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. -6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. -7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. -8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Set triage label**. When the branch-naming convention maps the head branch's prefix to a triage label (e.g. `feat/` -> `enhancement`, `fix/` -> `bug`) and that label exists in the repo, apply it. Skip silently when there is no mapping or no matching label. Labels triage only; they never change the base resolved in step 3. -10. **Return** the structured Outputs block. +1. **Tool.** Use the VCS tool declared in project memory, otherwise map `git remote get-url origin` to the matching configured tool. +2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. +3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. +4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. +5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file) over the bundled one, plus any contributing rules; write a concise title and body from the change summary. +6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. +7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. +8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. +9. **Return.** Surface the URL, number, head, and base. ## Test -- **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. -- **Prefix routing**: a head branch whose prefix is mapped in project memory resolves `base` to that prefix's target (e.g. `feat/*` -> `next`, `hotfix/*` -> `main`), not the `origin/HEAD` default. -- **Triage label**: when the head prefix maps to a triage label that exists in the repo, the created request carries that label. -- **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. +- The created request exists with `base` equal to the resolved base and the draft flag true. +- A head branch whose prefix is mapped resolves the base to that target, not the `origin/HEAD` default. +- When the head prefix maps to an existing triage label, the request carries it. +- The request is reachable at its URL with the head branch as its source. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md deleted file mode 100644 index 516531f5..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: contributing -description: Project contribution guidelines template -argument-hint: N/A ---- - -# Contributing to [Project Name] - -Welcome to the [Project Name] contribution guide! We appreciate your interest in helping us improve and grow this project. This document outlines how you can contribute effectively. - -> [Vision Statement or Mission of the Project, our Why] - -## 📐 Contributing Guidelines - -- Who can contribute? -- Roles and responsibilities? -- Code of conduct... - -## ❓ What can YOU do to help? - - - -### - -1. ... - -## 📌 Where are features to build? - -[...] - -## 💠 Onboarding in the Contributing flow - -### Documentation links - -- [](./) - -### Pre-requisites environment setup (optional) - -[...] - -### Steps to follow - -1. ... - -## 🌲 Branch naming - -- - -## 👌 Commit Guidelines - -- - -## 🧪 Testing Guidelines - -- ... - -## 🚀 Publishing (Maintainers Only) - -### Authentication Setup - -### Process to Publish diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md b/plugins/aidd-vcs/skills/02-pull-request/assets/README.md deleted file mode 100644 index 35c3efaa..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: readme -description: Project README template -argument-hint: N/A ---- - -# [Project Name] - -[Summary] - -## Installation Process - -## Usage - -## Access - -## Development Workflow - -## Documentation Structure - -| File | Description | -| ----- | ----------- | -| `...` | ... | - -## Common issues - -### Troubleshooting - -## 📄 License - -## Contributing - -We welcome contributions from the community. Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute. diff --git a/scripts/check-markdown-links.js b/scripts/check-markdown-links.js index 783ffcec..15b7dde6 100644 --- a/scripts/check-markdown-links.js +++ b/scripts/check-markdown-links.js @@ -33,7 +33,7 @@ Examples: | Reader reference | See [explore skill](plugins/aidd-context/skills/11-explore/SKILL.md). | `; -const SKIPPED_DIRS = new Set([".git", "node_modules"]); +const SKIPPED_DIRS = new Set([".git", "node_modules", "worktrees", ".specstory"]); const SKIPPED_DIR_PREFIXES = [".tmp-check-markdown-links-"]; const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); function normalizePathForDisplay(filePath) {