refactor(framework): executor/checker agents + SDLC orchestration redesign (recipe-not-spawn)

README.md

@@ -18,7 +18,7 @@
 <p><b>🇫🇷 The first French open-source framework for AI-driven development.</b></p>
 
 <p>
-  <!--counts:start--><kbd>7 plugins</kbd> · <kbd>40 skills</kbd> · <kbd>3 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
+  <!--counts:start--><kbd>7 plugins</kbd> · <kbd>41 skills</kbd> · <kbd>2 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
 </p>
 
 [![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.
 

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.

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
 

docs/GLOSSARY.md

@@ -28,7 +28,7 @@ A single atomic step inside a skill, stored at `plugins/<plugin>/skills/<NN-name
 
 ## Agent
 
-A specialized AI persona under `plugins/<plugin>/agents/<name>.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/<plugin>/agents/<name>.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
 

plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md

@@ -16,7 +16,7 @@ model: <e.g. opus>                         # 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.
 -->

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.

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",

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.` |