diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index 9170aefa1..62c707cbb 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -4,37 +4,64 @@ The contract every generated skill satisfies. `skill-generate` obeys it too. ## The skill -- **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 ` and an optional `Not for `. 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. +- **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 ` and an optional `Not for `. + 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. - **R5.** English only, one idea per sentence. + In any bullet, start each complete sentence on a new source line. ## 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. `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. +- **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. + `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. +- **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. ## 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. -- **R15.** A reference carries one fact per row: a table, a mermaid, or a list. Prose is what is left when neither fits. +- **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. +- **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 -- **R16.** An asset states how it is filled and what is removed. Nothing of its scaffold survives in the artifact produced from it. +- **R16.** An asset states how it is filled and what is removed. + Generated prose gives general guidance without boilerplate such as "per template". + An action still links to an asset template it must read. + Trust the model's judgment for routine choices. + Remove the asset's scaffold from the produced artifact. ## 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.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. It 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. -- **R19.** One file, one artifact. Split two apart only when a path needs one without the other. +- **R17.** One fact, one home. + An action follows its already loaded `SKILL.md` router without linking back to it. + It cites only distinct files it needs, without restating their rules. +- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. + It 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. +- **R19.** One file, one artifact. + Split two apart only when a path needs one without the other. diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index dd77f0fd3..51105f6f2 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -21,8 +21,22 @@ Before running an action, read its file in `actions/`, not only the table or ass ## Transversal rules -- 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. +- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. + Never commit an `in-progress` marker alone. +- Commit timing: follow the user's explicit instruction, else `AI should auto commit` in VCS memory. + `never` or absent means no automatic commits. + `after task done` commits a verified `###` category; defer an unverifiable or final category until the phase assertion. + `after phase` waits for that assertion; `after feature` and `post-tests` wait for final validation. + An explicit commit request without timing also waits for final validation. +- Commit unit: one coherent `###` category under `## Tasks to do`, including all numbered steps, per commit; never commit per step or checkbox. + Keep category changes separable even in shared files; if impossible, report `replan needed`. + The last category commit includes phase `done`; commit plan `implemented` separately after final validation. + Commit only implementation-owned changes due at the checkpoint; leave unrelated pre-existing edits untouched. + Without authorization, leave changes uncommitted. +- Commit handoff: at a due checkpoint, discover an installed atomic local commit capability by purpose. + Delegate staging, message, commit, and hook handling for each due unit. + Stop and report if the provider is absent or rejects a commit. + Automatic commits require a non-default branch; never request a push. ## References diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md index 7e99042de..42fa665f3 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -12,9 +12,14 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress` ## Process -1. **Resolve.** Resolve the plan from the 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, create a feature branch 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. +1. **Resolve.** Resolve the plan from the 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, create a feature branch and announce it. + On a non-default branch, keep it. +3. **Mark.** Set plan frontmatter `status: in-progress`. + Include it at the first authorized commit checkpoint, or with `implemented` when there is no phase. ## Test diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 2c531ffb4..c8a80974f 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -8,19 +8,29 @@ 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. +Each phase asserted and marked `status: done`, or a stop at `status: blocked` or `replan needed`. ## 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. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. +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 by category.** Complete the numbered steps under each `###` heading in `## Tasks to do`; check relevant behavior and retain separable changes. + For legacy phases without headings, treat the phase as one category. + Hand off only categories due at the current checkpoint. +3. **Assert the phase.** Assert all acceptance criteria; repair the owning category and repeat on failure. + Keep corrections to an earlier committed category separate until an authorized checkpoint. + On success, set `status: done`; hand off categories due now and retain the others for finalization. 4. **Guard.** Stop the loop on either condition: - - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop. - - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. + - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked` and stop; do not automatically commit an unverified unit. + - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. + Never rewrite the plan; replanning is the caller's job. ## 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. +- Each due category has one scoped commit, including all its steps. + Any correction to an earlier commit stays scoped to that category. +- The full assertion passes before `status: done`; when committed, that status rides in the last category's commit. +- Without authorization, no commits are made. + Unrelated pre-existing edits remain untouched. - 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 index 2943bc426..1fd8149ca 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -12,10 +12,13 @@ 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. +1. **Verify.** Run the plan's validation commands and tests. + Never format code, never run dev mode. +2. **Mark.** When every phase is done and validation passes, set plan `status: implemented`. + Hand off retained categories separately in phase order, then the plan status, at their authorized checkpoints. + Without authorization, leave changes uncommitted. ## Test - The validation commands exit zero. -- The plan reads `status: implemented`, committed (`git status --short` shows it clean). +- The plan reads `status: implemented`; authorized commits include only due implementation changes and status.