refactor(aidd-context): simplify skill generation rules

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 |

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.

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 |

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.

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.

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.

plugins/aidd-context/skills/04-skill-generate/assets/action-template.md

@@ -12,13 +12,11 @@
 
 ## Process
 
-1. **<Label>.** <Imperative step. Sub-bullet for a branch or a loop back.>
-2. **<Label>.** <Next step.>
+1. <Imperative step. Sub-bullet for a branch or a loop back.>
+2. <Run the observable success check and handle failure.>
 
-## Test
+## Rules
 
-| Case | Pass |
-| --- | --- |
-| <what is run> | <the observable result it gives> |
+- **<Important opening words>** <constraint not owned by a process step; omit this section when none>
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.

plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md

@@ -23,6 +23,6 @@ Run the flow above. Read only the next action file.
 
 <Rules owned by no reference or single action, one per line.>
 
-- <rule>
+- **<Important opening words>** <rest of the rule>
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.

plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md

@@ -1,24 +1,10 @@
 # Scope frame
 
-The fields a scoped skill must define.
-
-- subject:
-- purpose: one sentence.
-- name: kebab-case.
-- flow: visible user journey.
-- mode: optional, `auto` or `interactive`.
-- target: detected tool, plugin source, or dedicated tool.
-
-Modes:
-
-- `auto`: runs through the flow without planned user checkpoints.
-- `interactive`: pauses for user input at defined checkpoints.
-
-Output shape:
-
-- subject:
-- purpose:
-- name:
-- flow:
-- mode: omit when absent.
-- target:
+Fill these fields; omit mode when absent.
+
+- **Subject.** Domain.
+- **Purpose.** One sentence.
+- **Name.** Kebab-case.
+- **Flow.** Visible user journey.
+- **Mode.** `auto` runs without planned checkpoints; `interactive` pauses for user input.
+- **Target.** Detected tool, plugin source, or dedicated tool.

plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md

@@ -7,26 +7,26 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 - **R1.** One skill, one domain. Named per `naming.md`.
 - **R2.** `name` is not the invocation token: a colon or prefix breaks loading. In prose call a skill `plugin:folder`.
 - **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to <intents>` and an optional `Not for <X>`. No colon or dash, no other skill or `/command` named.
-- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case, never the action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
+- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case; avoid action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
 - **R5.** English only, one idea per sentence.
 
 ## The router
 
 - **R6.** The router holds the flow, the action table, and the transversal rules. Nothing else.
 - **R7.** The mermaid flow shows every path a run can take: the nominal chain, one entry node per case, a back-edge per loop, a terminal node per outcome. A branch stated in prose is a branch missing from the flow.
-- **R8.** The action table is `| Action | Does |`, one row per action file, in run order. `Action` is the bare slug, no backticks and no number; two actions sharing a slug keep their number (`01-plan`, `04-plan`). `Does` is a lowercase imperative half-line with no final period. Above the table, one sentence: what to read next, nothing more.
+- **R8.** The action table is `| Action | Does |`, one row per action file, in run order. `Action` is the bare slug, no backticks and no number; duplicate slugs retain their action numbers. `Does` is a lowercase imperative half-line with no final period. Above the table, one sentence: what to read next, nothing more.
 - **R9.** `## Transversal rules` holds the rules no single action or reference owns. A rule stated there is stated nowhere else.
 - **R10.** The router is loaded on every call, an action only when its turn comes: the router carries nothing an action or a reference could carry.
 
 ## An action
 
-- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, `## Test`. A section earns its content or is omitted, never invented or reordered.
-- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
-- **R13.** `## Test` is a `| Case | Pass |` table, each row observable by real execution, never a mock.
+- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, and optional `## Rules`. Omit unnecessary sections; preserve names and order.
+- **R12.** Write concise imperative process steps. Number sequential steps; use dash sub-items for cases, branches, loops, or constraints. In bullets, bold important opening words instead of adding procedural labels. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
+- **R13.** Verify observable success in `## Process` through real execution. `## Rules` holds only constraints no process step owns; no separate `## Test` or duplicated checks.
 
 ## A reference
 
-- **R14.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. It names a sibling in backticks and never links it.
+- **R14.** References stay flat, nesting one directory deep only as a load boundary. Keep each self-contained; name siblings in backticks rather than linking them.
 - **R15.** A reference carries one fact per row: a table, a mermaid, or a list. Prose is what is left when neither fits.
 
 ## An asset
@@ -35,6 +35,7 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## Across all of them
 
-- **R17.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either.
-- **R18.** The first citation of a file in each authoring file is a relative Markdown link, `[name](path)`, except for sibling references under R14. Repeat mentions within the same file use only the filename in backticks when unambiguous; retain the link when ambiguous. Never an `@` include: nothing resolves those. A citation sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Test` line to conform to it. Never a block or a line of its own.
+- **R17.** One fact, one home. Apply router rules and cite shared references instead of restating them.
+- **R18.** Link a file on its first citation, except sibling references under R14; use its unambiguous filename in backticks thereafter. Use relative Markdown links rather than unresolved `@` includes. Place citations in the process, output, or rule that uses them.
 - **R19.** One file, one artifact. Split two apart only when a path needs one without the other.
+- **R20.** Prefer positive instructions or `avoid` over `never`. Express mandatory boundaries as explicit conditions.