diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index abe4c6e43..54f3c03c5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -102,6 +102,8 @@ flowchart TB Action --> Result["Result or artifact"] ``` +Recipe actions carry inputs, outputs, process steps, and rules. + ### Agents and delegation | Role | Contract | diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md index 6e546fb72..358b4897f 100644 --- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md +++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md @@ -25,7 +25,7 @@ Run the flow above. Read only the next action file. ## Transversal rules -- Default to `create`; follow `modify` when asked. -- If a cited reference cannot be read, stop and report the missing file. -- Confirm every target and name with the user. -- Never write silently. +- **Default to `create`**; follow `modify` when asked. +- **If a cited reference cannot be read**, stop and report the missing file. +- **Confirm every target and name** with the user. +- **Announce intended writes** before editing. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md index 2ed28f681..d7f85953c 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md @@ -13,16 +13,6 @@ The confirmed frame, written nowhere, per [scope-frame.md](../references/scope-f ## Process 1. **Detect.** Detect the installed tools per [tool-detect.md](../references/tool-detect.md). -2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question. -3. **Check.** Check the name per [naming.md](../references/naming.md) and surface any overlap. +2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question at a time. +3. **Check.** Check the name per [naming.md](../references/naming.md), reporting overlaps or none. 4. **Confirm.** Hand the confirmed frame to plan. - -## Test - -| Case | Pass | -| --- | --- | -| The action runs to completion | `git status --porcelain` reads the same after as before | -| A name overlaps an installed skill | the overlap is surfaced before the frame is handed on | -| No name overlaps | the run states that it found none | -| A frame field needs the user | one question is asked, and only that one | -| The frame is handed to plan | its target was confirmed by the user first | diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md index 41c70fa72..baaf0f3cd 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md @@ -1,27 +1,20 @@ # 02 - Plan -Break the skill into atomic, testable actions: one action, one job. +Break the skill into atomic actions: one action, one job. ## Input -- From scope, the create frame. -- For a modify, the existing skill, read in place. +- **Create.** The frame from scope. +- **Modify.** The existing skill, read in place. ## Output -A plan table, one row per action: slug, input to output, test, and any dependency. +A plan table, one row per action: slug, input to output, observable success, and dependencies. ## Process -1. **List.** List every distinct job the output needs. Modify: start from the existing actions, touch only the jobs the user named. -2. **Atomize.** Prefer few actions, a job each, not a step. Merge two that share most logic. -3. **Number.** Name, number, and give each an observable test, per [skill-authoring.md](../references/skill-authoring.md). -4. **Confirm.** Present the table, validate each test with the user. - -## Test - -| Case | Pass | -| --- | --- | -| The table is presented | every row is one job carrying a checkable test | -| A row consumes an output | that output comes from an earlier row, never a later one | -| The run is a modify | only the jobs the user named have a row | +1. **List.** List every distinct job the output needs. + - **Modify.** Keep only jobs the user named. +2. **Atomize.** Prefer few actions, a job each; merge two that share most logic. +3. **Order.** Name and number each action per [skill-authoring.md](../references/skill-authoring.md), placing consumed outputs before their consumers. +4. **Confirm.** Present the table and confirm each observable success condition with the user. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md index 595826e48..eefe567a9 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md @@ -4,8 +4,8 @@ Write the skill tree from the plan. ## Input -- The plan from 02. -- The target from 01, or for a modify the existing skill's own location. +- **Plan.** The plan from 02. +- **Target.** The target from 01, or for a modify the existing skill's own location. ## Output @@ -14,21 +14,10 @@ The skill tree at the target, and the list of files written. ## Process 1. **Tree.** Create the shape in [skill-tree.md](../references/skill-tree.md). -2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md), strip the scaffold. - - Modify: revise the existing SKILL.md in place, keeping the user's edits. -3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row against [skill-authoring.md](../references/skill-authoring.md), its test copied from the plan. - - Modify: revise a changed action in place. Leave an untouched one alone. +2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md). + - **Modify.** Revise the existing SKILL.md in place, keeping the user's edits. +3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row, weaving its success check into the process. + - **Modify.** Revise changed actions in place; leave untouched ones alone. 4. **Hint.** Set `argument-hint` per [skill-authoring.md](../references/skill-authoring.md). -5. **Place.** Write once per confirmed target, using [tool-write.md](../references/tool-write.md). -6. **Check.** Confirm every written path is relative, inside the workspace, outside the plugin install directory, and under the chosen target. Else stop and report it. - -## Test - -| Case | Pass | -| --- | --- | -| The router is written | it holds a `mermaid` flowchart and an `Action \| Does` table | -| The action table is read back | every slug is bare and every `Does` is a lowercase imperative with no final period | -| An action file is written | it holds `## Output`, `## Process`, and a `Case \| Pass` `## Test` | -| The tree is written | its shape matches [skill-tree.md](../references/skill-tree.md) | -| Any written file is read back | no `<` placeholder and no template instruction line survives | -| A path resolves outside the chosen target | the run stops and reports that path | +5. **Place.** Write once per confirmed target using [tool-write.md](../references/tool-write.md), stopping if a path escapes the workspace or target or enters a plugin install directory. +6. **Read back.** Check the tree and every file against the contract, removing placeholders and scaffold instructions before validation. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md index fca3dacbb..9f9af8f1e 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md @@ -8,18 +8,10 @@ The skill written by 03. ## Output -A report, one row per file: what was checked and any fix applied. +A report, one row per written file: checks, findings or none, and fixes applied. ## Process 1. **Review.** Review each file against [review-protocol.md](../references/review-protocol.md). -2. **Fix.** Apply the confirmed fixes on disk, then re-review the changed files. -3. **Report.** Deliver the findings, even when clean. - -## Test - -| Case | Pass | -| --- | --- | -| The report is delivered | every written file has a row, with its findings or none | -| The review finds a breach | it names the broken rule and a `file:line` | -| A fix is confirmed | the file differs on disk and is reviewed again | +2. **Fix.** Apply the confirmed fixes on disk, read them back, and re-review until no breach remains. +3. **Report.** Deliver the report, even when clean. diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md index be7d9cc99..d872560f3 100644 --- a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md +++ b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md @@ -12,13 +12,11 @@ ## Process -1. **