From 4ec41e92294f6b7a41c567fbb56f600313ea4bd7 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 10 Aug 2026 21:36:47 +0200 Subject: [PATCH 1/3] refactor(aidd-pm): migrate 01-ticket-info to router contract Moves tool/identifier lookup rules into references/tool-detection.md, standardizes the display output via assets/ticket-template.md, and replaces the old action table with the mermaid + | Action | Does | shape used by the other 7 aidd-pm skills. Part of #564; phase 1 of 3. Co-Authored-By: Claude Sonnet 5 --- .../phase-1.md | 65 +++++++++++++++++ .../phase-2.md | 64 +++++++++++++++++ .../phase-3.md | 72 +++++++++++++++++++ .../plan.md | 50 +++++++++++++ plugins/aidd-pm/CATALOG.md | 2 + .../aidd-pm/skills/01-ticket-info/SKILL.md | 20 +++--- .../01-ticket-info/actions/01-ticket-info.md | 12 ++-- .../01-ticket-info/assets/ticket-template.md | 12 ++++ .../references/tool-detection.md | 10 +++ 9 files changed, 288 insertions(+), 19 deletions(-) create mode 100644 aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-1.md create mode 100644 aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md create mode 100644 aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md create mode 100644 aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md create mode 100644 plugins/aidd-pm/skills/01-ticket-info/assets/ticket-template.md create mode 100644 plugins/aidd-pm/skills/01-ticket-info/references/tool-detection.md diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-1.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-1.md new file mode 100644 index 00000000..35233ec6 --- /dev/null +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-1.md @@ -0,0 +1,65 @@ +--- +status: done +--- + +# Instruction: Migrate `01-ticket-info` to the router contract + +## Architecture projection + +> ✅ create · ✏️ modify · ❌ delete + +```txt +. +└── plugins/aidd-pm/skills/01-ticket-info/ + ├── SKILL.md ✏️ mermaid flow, `| Action | Does |` table, canonical lead-in; drop the `| # | Action | Role | Input |` shape and duplicated process rules + ├── actions/01-ticket-info.md ✏️ cite references/ and assets/ instead of restating rules and output fields + ├── references/ ✅ create — issue scope mandates a references/ folder on every one of the 3 skills + │ └── tool-detection.md ✅ create — where the configured ticketing tool and identifier convention are declared + └── assets/ + └── ticket-template.md ✅ create — standardizes the display fields (title, status, assignee, priority, URL, description); user-requested during phase review, not in the original issue scope +``` + +## Tasks to do + +### `1)` Rebuild the router + +> Router keeps only the flow, the action table, and whatever rule truly belongs to no single action or reference (R6, R9, R10). + +1. Add a mermaid `flowchart LR`: one entry node (ticket id or branch-derived id) → `ticket-info` → terminal node (displayed ticket). Single action, no loop. +2. Replace the `| # | Action | Role | Input |` table with `| Action | Does |`: bare slug `ticket-info`, lowercase imperative half-line, no trailing period (R8). +3. Replace "Before running an action, read its file in `actions/`, not only the table or assets." with the canonical lead-in: "Run the flow above. Read only the next action file." (matches `07-epic`, `skill-template.md`). +4. Compare each line under `## Transversal rules` against `actions/01-ticket-info.md`'s `## Process` steps 1-3: every rule already stated there is deleted from the router, not restated (R17). +5. Drop the line repeating the frontmatter `Not for` list / intent — `description` already carries it (R3). + +### `2)` Create `references/tool-detection.md`, decide the rest + +> Issue Scope is explicit: "Give each of the three a `references/` folder." Not optional — this is the one reference file this skill gets. + +1. Create `references/tool-detection.md`: a table or list stating where the configured ticketing tool is declared (project memory first, otherwise repo configuration or environment) and the identifier-format convention (branch-derived id, project prefix/separator/casing) — the two facts that are lookup-order-shaped, not process-shaped (R15). +2. Cite it from the action's `## Process` steps 1 and 3 with a relative link (R14, R18) — delete the equivalent prose from the router's `## Transversal rules` once cited, don't keep both (R17). +3. Check whether "read-only: never create, comment, transition, or reassign" states something the frontmatter `description`'s `Not for` clause doesn't already cover. If it's pure duplication, delete it; otherwise it's the one line that stays in `## Transversal rules` (it governs the whole skill, not one process step). + +### `3)` Create `assets/ticket-template.md` + +> User-requested during phase review: standardize the display output. Checked first whether `aidd-orchestrator:01-sdlc` (the known caller, `references/01-frame.md:15-16`) needs a specific shape — it consumes `$resolved_source` as free text, no schema, so this is a display-consistency choice, not an external contract requirement. + +1. Create `assets/ticket-template.md` with the fields the action already outputs: title, status, assignee, priority, URL, description. Follow the existing template idiom (leading HTML comment instructing fill-and-strip, bracketed placeholders — see `spec-template.md`, `epic-template.md`). +2. Cite it from the action's `## Output` and the `## Process` "Display" step (R18) instead of enumerating the fields inline. +3. Do not add a router `## Assets` section — R6 forbids it; the citation lives in the action, same as every other asset in the plugin. + +### `4)` Verify the action still stands alone + +> The action file must state everything needed to run, citing references and assets rather than depending on the router. + +1. Re-read `actions/01-ticket-info.md`: confirm it states, on its own plus its citations, everything needed to run — no missing step because the router used to cover it. +2. Confirm each citation sits in the sentence that uses it (R18), not as a standalone line. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------------------------------------------------------------------------ | +| 1 | `SKILL.md` has a mermaid flow, a `\| Action \| Does \|` table, and the exact canonical lead-in sentence. | +| 1 | No line in `## Transversal rules` duplicates a `## Process` step in `actions/01-ticket-info.md`, nor the frontmatter `description`. | +| 2 | `references/tool-detection.md` exists, is cited from `actions/01-ticket-info.md`, and states a fact no action process step restates. | +| 3 | `assets/ticket-template.md` exists, is cited from `actions/01-ticket-info.md`, and `SKILL.md` has no `## Assets` section. | +| 4 | `actions/01-ticket-info.md` read together with its cited reference and asset fully describes how to run the action, with nothing left only in `SKILL.md`. | diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md new file mode 100644 index 00000000..2f103536 --- /dev/null +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md @@ -0,0 +1,64 @@ +--- +status: pending +--- + +# Instruction: Migrate `03-prd` to the router contract + +## Architecture projection + +> ✅ create · ✏️ modify · ❌ delete + +```txt +. +└── plugins/aidd-pm/skills/03-prd/ + ├── SKILL.md ✏️ mermaid, `| Action | Does |`, canonical lead-in, drop `## Assets`, drop duplicated rules + ├── actions/01-prd.md ✏️ absorb the `## Assets` note; stop naming individual sections, cite the template instead + ├── assets/prd-template.md — unchanged, stays sole source of truth for the 8 sections + ├── assets/task-template.md ❌ delete — unfilled, collides by name with 10-task's real Task template + └── references/ ✅ create — issue scope mandates a references/ folder on every one of the 3 skills + └── save-path.md ✅ create — the dated save-path convention and folder-reuse rule +``` + +## Tasks to do + +### `1)` Delete the dead asset + +> Nothing fills `task-template.md`; `01-prd.md` only ever fills `prd-template.md`. + +1. Delete `assets/task-template.md`. +2. Remove the `## Assets` section's line announcing it (falls out with task 2's `## Assets` removal anyway — do this first so nothing else references it in the interim). + +### `2)` Rebuild the router + +1. Add a mermaid `flowchart LR`: one entry node (feature description, optionally with user stories) → `prd` → terminal node (saved PRD). Single action, no loop at router level — the internal draft/validate/re-show cycle stays inside the action's own `## Process` (R12: a loop back inside one action is a dash sub-item of its step, not a router-level back-edge). +2. Replace the `| # | Action | Role | Input |` table with `| Action | Does |`. +3. Replace the lead-in with the canonical sentence: "Run the flow above. Read only the next action file." +4. Delete `## Assets` entirely (R6 forbids it; the remaining asset, `prd-template.md`, is cited from the action instead). +5. Compare each `## Transversal rules` line against `actions/01-prd.md`: "focus on what/why", "sections stay concise", "wait for explicit validation" — all 3 already stated (or belong) in the action's Process/Output — delete from the router. + +### `3)` Stop enumerating PRD sections outside the template + +> Issue: the 8 sections are named twice — once in `prd-template.md`, once in prose in `01-prd.md:16`. `SKILL.md:25` already declares the template the source of truth; that declaration is the fact that survives, everything else cites it. + +1. In `actions/01-prd.md` step 2 ("Draft"), stop spelling out "overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions" inline. Replace with a citation to `assets/prd-template.md` and state only "fill every section the template defines." +2. Move "save path: `aidd_docs/tasks//--prd.md`" and "source of truth for structure: `assets/prd-template.md`" out of the router — both already appear (or belong) in `01-prd.md`'s `## Output`/`## Process`; keep one instance, delete the other (R17). +3. Confirm acceptance criterion "adding a section to `prd-template.md` requires no other edit" holds: grep the skill folder for any other place the 8 section names are spelled out; there should be none left. + +### `4)` Create `references/save-path.md`, decide the rest + +> Issue Scope mandates a `references/` folder on every one of the 3 skills. The save-path convention is the fact that's list-shaped, not process-shaped (R15). + +1. Create `references/save-path.md`: states the dated path pattern (`aidd_docs/tasks//--prd.md`) and the rule to create the month directory when missing. +2. Cite it from `actions/01-prd.md`'s `## Output` line and `## Process` step 4 ("Save") with a relative link (R14, R18); delete the router's "Save path: ..." line once cited (R17). +3. Apply the same test as phase 1 to the remaining lines: "focus on what/why", "sections stay concise", "wait for explicit validation" — if each is already stated in `01-prd.md`'s Process/Output, delete the router copy. If nothing survives, omit `## Transversal rules`. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------------------------------- | +| 1 | `assets/task-template.md` no longer exists; nothing in `SKILL.md` or `actions/01-prd.md` references it. | +| 2 | `SKILL.md` has a mermaid flow, `\| Action \| Does \|` table, canonical lead-in, and no `## Assets` section. | +| 2 | No `## Transversal rules` line duplicates a step or output line in `actions/01-prd.md`. | +| 3 | The 8 PRD section names appear in exactly one file: `assets/prd-template.md`. | +| 3 | Adding a 9th section to `prd-template.md` requires editing no other file to stay accurate. | +| 4 | `references/save-path.md` exists, is cited from `actions/01-prd.md`, and the router no longer states the save path directly. | diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md new file mode 100644 index 00000000..52864c8d --- /dev/null +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md @@ -0,0 +1,72 @@ +--- +status: pending +--- + +# Instruction: Migrate `04-spec` to the router contract + +## Architecture projection + +> ✅ create · ✏️ modify · ❌ delete + +```txt +. +└── plugins/aidd-pm/skills/04-spec/ + ├── SKILL.md ✏️ mermaid with 2 entry nodes, `| Action | Does |`, canonical lead-in, drop `## Assets`, drop the `TBD:` rule + ├── actions/01-build.md ✏️ cite references/tbd-marker.md instead of restating TBD: + ├── actions/02-refine.md ✏️ same citation; fix the 2 drifted spellings (bare `TBD` at :11, short `TBD: ` at :27) + ├── assets/spec-template.md — unchanged + ├── assets/spec-validator.yml — unchanged + └── references/ + └── tbd-marker.md ✅ create — the one canonical `TBD:` spelling and rule +``` + +## Tasks to do + +### `1)` Create the `TBD:` marker's one home + +> Issue: 3 sites, 3 drifting spellings, no owner. All 3 sites already live inside `04-spec` — resolved during brainstorm as an intra-skill reference, not a cross-skill shared one (this codebase doesn't share references across skills). + +1. Create `references/tbd-marker.md`: states the exact literal `TBD: `, the rule "never guess, mark the gap instead", and nothing else (R15: one fact per reference). +2. In `SKILL.md`'s `## Transversal rules`, replace the inline "Mark every gap as `TBD: `..." line with a citation to the reference (R18) — the rule's text now lives only in `references/tbd-marker.md`. +3. In `actions/01-build.md` step 2 ("Gaps"), replace "Replace any missing required field with `TBD: `" with a citation to the reference. +4. In `actions/02-refine.md`: fix `:11`'s bare `` `TBD` `` (Output line) and `:18`/`:27`'s spellings so every occurrence either matches the canonical literal exactly or cites `references/tbd-marker.md` instead of re-typing it. + +### `2)` Rebuild the router with a branching mermaid + +> R7: the existing dispatch prose ("a spec path with findings runs `refine`; a request or PRD path runs `build`") is a branch — it belongs in the flow, not as router prose (R17: one fact, one home). + +1. Add a mermaid `flowchart LR` with 2 entry nodes: one for "request or PRD path" → `build`, one for "spec path + findings" → `refine`. Both converge on a terminal node (`spec.md` written/updated). +2. Delete the "Dispatch by input: ..." sentence from the router prose once the mermaid states it — do not keep both (R17). +3. Replace the `| # | Action | Role | Input |` table with `| Action | Does |`. +4. Replace the lead-in with the canonical sentence: "Run the flow above. Read only the next action file." +5. Delete `## Assets` entirely; `spec-template.md` and `spec-validator.yml` get cited from the actions that use them instead. + +### `3)` Sort the remaining `## Transversal rules` lines + +> Everything except the `TBD:` rule (moved in task 1) needs a home: stays as genuinely cross-cutting (both `build` and `refine` rely on it), or moves into one action if only one uses it. + +1. "The spec holds intent, never implementation..." — used by both actions (both write/rewrite the spec body) → stays a router transversal rule, or becomes `references/spec-shape.md` if it grows past what a router line should hold (R15 vs R9 — keep as a router line unless it's genuinely table/list-shaped). +2. "Keep it readable..." — same test as above. +3. "Output: one `spec.md` in the feature folder... Reuse the folder when it exists." — both actions write to the same path; verify it isn't already stated in both actions' `## Output`. If it is, delete the router copy (R17); if neither states it, it's genuinely transversal and stays. +4. "Immutable once validated: never rewrite a spec that has been locked." — check whether this constraint is enforced/stated anywhere in `02-refine.md`; if not, this is a gap the migration surfaces (not new scope, but flag it rather than silently drop it). + +### `4)` Verify the plugin-wide acceptance criteria + +> AC#1 ("same shape, sections, **and section order**") and AC#5 ("every asset in the plugin is filled by an action") aren't scoped to one skill — this is the last phase, so it's where they get checked across all 10. + +1. For each of the 10 `plugins/aidd-pm/skills/*/SKILL.md`, dump the `^#{1,2} ` heading sequence (`grep -n '^#\{1,2\} '`) and confirm all 10 now agree: `# Title`, `## Actions`, `## Transversal rules`, in that order, nothing else. +2. Enumerate `plugins/aidd-pm/skills/*/assets/*` and confirm each file is consumed by a named action: a template asset is filled (produces the output artifact), a validator/checklist asset is read against (gates the output). `04-spec/assets/spec-validator.yml` is the one checklist-shaped asset in scope — already cited from both `01-build.md` and `02-refine.md` — so it passes under "consumed by a named action", the actual defect AC#5 targets being `task-template.md`'s prior state: cited by nothing at all. State this reading to the user when reporting the phase, rather than re-litigating it live. +3. Report to the user: the issue's own count is off by one (it says "eight follow the contract, three don't" = eleven, and AC#1 says "eleven routers"; the plugin has 10 skills total, so it's seven already-migrated plus three migrated here). Flag this the same way the issue's "What already landed" section already flagged two other wrong claims — don't silently satisfy the literal "eleven". + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ---------------------------------------------------------------------------------------------------------------- | +| 1 | `grep -rn "TBD" plugins/aidd-pm/skills/04-spec/` shows exactly one canonical literal spelling, defined once in `references/tbd-marker.md`, cited (not restated) everywhere else. | +| 2 | `SKILL.md`'s mermaid shows both entry cases (build vs refine); no router prose duplicates the dispatch rule the mermaid now states. | +| 2 | `SKILL.md` has `\| Action \| Does \|`, canonical lead-in, no `## Assets` section. | +| 3 | Every remaining `## Transversal rules` line states a fact no single action's `## Process`/`## Output` already states. | +| 3 | The "immutable once locked" constraint is either confirmed enforced somewhere reachable from `02-refine.md`, or explicitly flagged in the phase review as a pre-existing gap. | +| 4 | All 10 `SKILL.md` heading sequences match exactly (title, Actions, Transversal rules, that order, nothing else). | +| 4 | Every `plugins/aidd-pm/skills/*/assets/*` file is confirmed consumed by a named action (template filled, or validator cited); `spec-validator.yml`'s read-only status is reported to the user as the resolved reading, not asked about. | +| 4 | The "eleven routers" vs. actual 10-skill count discrepancy is reported to the user, not silently absorbed. | diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md new file mode 100644 index 00000000..148981da --- /dev/null +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md @@ -0,0 +1,50 @@ +--- +objective: "01-ticket-info, 03-prd, and 04-spec routers match the aidd-pm contract (07-epic shape): references/ hold every rule an action doesn't, TBD: has one spelling in one file, and the PRD sections live only in prd-template.md." +status: in-progress +--- + +# Plan: Migrate ticket-info, PRD, spec to the router contract + +## Overview + +| Field | Value | +| ---------- | ---------------------------------------------------------------------- | +| **Goal** | Bring the 3 remaining `aidd-pm` skills in line with the other 7: mermaid flow, `\| Action \| Does \|` table, canonical lead-in, no `## Assets`, one rule one home. | +| **Source** | GitHub issue #564 (ai-driven-dev/framework) | + +Each phase migrates exactly one skill. Stop after each phase for interactive review before starting the next — explicit user instruction, not the default. + +## Phases + +| # | Phase | File | +| --- | ------------------------------- | ------------------------------ | +| 1 | Migrate `01-ticket-info` | [`phase-1.md`](./phase-1.md) | +| 2 | Migrate `03-prd` | [`phase-2.md`](./phase-2.md) | +| 3 | Migrate `04-spec` | [`phase-3.md`](./phase-3.md) | + +## Resources + +| Source | Verified | +| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| GitHub issue #564 | Scope, acceptance criteria, and the two corrected claims (argument-hint, `## Test` shape). | +| `plugins/aidd-pm/skills/07-epic/*` | Reference migration: router mermaid + `\| Action \| Does \|` shape, references/ split, canonical lead-in wording. | +| `plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md` | The contract, R1-R19, per artifact (skill, router, action, reference, asset). | +| `plugins/aidd-context/skills/04-skill-generate/assets/{skill,action}-template.md` | Exact canonical lead-in text and section order/frontmatter shape. | +| Direct read of all 3 target `SKILL.md` + `actions/*.md` | Confirmed every duplication the issue names, and the exact 3 spellings of `TBD:` in `04-spec`. | + +## Decisions + +| Decision | Why | +| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `TBD:` marker's one home is `04-spec/references/tbd-marker.md`, not a shared cross-skill reference | All 3 `TBD:` sites (`SKILL.md`, `01-build.md`, `02-refine.md`) live inside `04-spec`; this codebase doesn't share reference files across skills. | +| Every one of the 3 skills gets at least one named `references/` file — `01-ticket-info/references/tool-detection.md`, `03-prd/references/save-path.md`, `04-spec/references/tbd-marker.md` — not an optional folder | Issue Scope states it as a requirement ("Give each of the three a `references/` folder"), not a suggestion. | +| `01-ticket-info` and `03-prd` keep `## Transversal rules` thin (one line, or the skill-wide read-only/validation-wait constraint) rather than empty | The reference file absorbs the process-shaped duplication; what's left is genuinely skill-wide, not action-owned. | +| `04-spec`'s build-vs-refine dispatch moves into the mermaid as two entry nodes, not prose | R7: a branch stated in prose is a branch missing from the flow; R17: one fact, one home. | +| One phase per skill, review gate between phases | User-requested; keeps each migration independently verifiable against the shape criterion. | +| Verify AC#1 (section order, all 10 skills) and AC#5 (every plugin asset filled) in phase 3, not a separate phase | Both criteria span skills beyond any single phase's scope; checking them after the last migration is cheaper than a 4th review-gated phase. | +| AC#5's "filled by an action" reads as "consumed by a named action" — a template is filled, a validator/checklist is read against | `spec-validator.yml` is read, never written; the issue's actual named defect is `task-template.md` being cited by nothing at all. Resolving the reading now avoids relitigating it mid-phase-3. | +| Each of the 3 new `references/*.md` files stays a single file per skill, not split further | R19: split a path only when it needs one fact without the other. `tool-detection.md`'s two facts (tool source, identifier format) and `save-path.md`'s one fact are both consumed by the same single action's process — no path needs one without the other. | + +## Correction + +The issue's own arithmetic doesn't match the repo: "Eight `aidd-pm` skills follow the router contract. Three never migrated" (= 11) and AC#1 "the eleven `aidd-pm` routers" both assume 11 skills. `plugins/aidd-pm/skills/` holds 10 (`01`-`10`). 7 already match the contract (`02,05,06,07,08,09,10` — confirmed identical heading sequence, mermaid, and canonical lead-in against `07-epic`), plus the 3 this plan migrates = 10, not 11. Same category of error as the two claims the issue itself already corrected under "What already landed". Flagged for the user in phase 3, not silently resolved. diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 4f526419..42d5ed76 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -34,6 +34,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-ticket-info.md](skills/01-ticket-info/actions/01-ticket-info.md) | - | +| `assets` | [ticket-template.md](skills/01-ticket-info/assets/ticket-template.md) | - | +| `references` | [tool-detection.md](skills/01-ticket-info/references/tool-detection.md) | - | | `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display a ticket from the configured ticketing tool. Use when the user wants to see, show, or look up a ticket's details. Not for creating a ticket, or commenting on, transitioning, or reassigning one.` | #### `skills/02-user-stories` diff --git a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md index 15887ab2..1e90b79b 100644 --- a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md +++ b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md @@ -6,19 +6,15 @@ argument-hint: ticket # Ticket Info -Reads ticket details from the configured ticketing tool. Read-only and tool-agnostic. +```mermaid +flowchart LR + source([ticket id, or none]) --> ticket-info --> done([ticket displayed]) +``` ## Actions -| # | Action | Role | Input | -| --- | -------------- | ------------------------------------------------------------- | ---------------------------------- | -| 01 | `ticket-info` | Resolve ticket id, query the configured tool, display fields | ticket_id (optional) | +Run the flow above. Read only the next action file. -Before running an action, read its file in `actions/`, not only the table or assets. - -## Transversal rules - -- Read the configured ticketing tool from project memory first; otherwise inspect repo configuration or environment. -- Auto-detect the ticket identifier from the current branch name when none is provided. -- Format the identifier per project convention before querying. -- Read-only: never create, comment, transition, or reassign from this skill. +| Action | Does | +| ------------- | --------------------------------------------------------- | +| ticket-info | resolve ticket id, query configured tool, display fields | diff --git a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md index 134a1d28..95a09690 100644 --- a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md +++ b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md @@ -8,19 +8,17 @@ An optional ticket id or URL. When omitted, auto-detect it from the current bran ## Output -The ticket's title, description, status, assignee, priority, and URL, displayed for the user. +The ticket rendered per [ticket-template.md](../assets/ticket-template.md). ## Process -1. **Tool.** Use the ticketing tool declared in project memory. Otherwise inspect the repo configuration or environment for the configured tool. -2. **Identifier.** Use the provided ticket id when given. Otherwise take it from the current branch name, per project convention. -3. **Format.** Apply the project ticketing convention to the identifier (prefix, separator, casing). -4. **Query.** Invoke the configured ticketing tool to fetch the ticket record. -5. **Display.** Render the title, description, status, assignee, priority, and URL. +1. **Resolve.** Resolve the ticketing tool and the ticket identifier per [tool-detection.md](../references/tool-detection.md). +2. **Query.** Invoke the configured ticketing tool to fetch the ticket record. +3. **Display.** Fill [ticket-template.md](../assets/ticket-template.md) from the queried record and render it for the user. ## Test | Case | Pass | | --- | --- | -| The id resolves and the tool answers | title, description, status, assignee, priority, and URL match the queried record | +| The id resolves and the tool answers | every field `ticket-template.md` defines matches the queried record | | The displayed URL is opened | the tracker shows the same ticket | diff --git a/plugins/aidd-pm/skills/01-ticket-info/assets/ticket-template.md b/plugins/aidd-pm/skills/01-ticket-info/assets/ticket-template.md new file mode 100644 index 00000000..c34725e1 --- /dev/null +++ b/plugins/aidd-pm/skills/01-ticket-info/assets/ticket-template.md @@ -0,0 +1,12 @@ + + +# + +| Field | Value | +| --------- | ----------- | +| Status | <status> | +| Assignee | <assignee> | +| Priority | <priority> | +| URL | <url> | + +<Description, as written in the tracker.> diff --git a/plugins/aidd-pm/skills/01-ticket-info/references/tool-detection.md b/plugins/aidd-pm/skills/01-ticket-info/references/tool-detection.md new file mode 100644 index 00000000..92a44dca --- /dev/null +++ b/plugins/aidd-pm/skills/01-ticket-info/references/tool-detection.md @@ -0,0 +1,10 @@ +# Tool detection + +| Source, in order | Holds | +| -------------------- | ---------------------------- | +| project memory | the configured ticketing tool | +| repo configuration | fallback | +| environment | fallback | + +Ticket identifier: the one given, or the current branch name. +Format it per the project's ticketing convention (prefix, separator, casing). From c4c5bf0069574a4583480fde9fd8e952651c1d71 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com> Date: Thu, 13 Aug 2026 06:44:47 +0200 Subject: [PATCH 2/3] refactor(aidd-pm): migrate 03-prd to router contract Splits the single prd action into draft/finalize (single responsibility each, matching 08-three-amigos), restores the 5+1 Transversal rules boilerplate shared by 6 other aidd-pm skills, drops the dead task-template.md asset, and inlines the save path into finalize instead of a one-fact references/ file. Part of #564; phase 2 of 3. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --- .../phase-2.md | 65 ++++++------------- .../plan.md | 7 +- plugins/aidd-pm/CATALOG.md | 4 +- plugins/aidd-pm/skills/03-prd/SKILL.md | 30 ++++----- .../aidd-pm/skills/03-prd/actions/01-draft.md | 27 ++++++++ .../aidd-pm/skills/03-prd/actions/01-prd.md | 28 -------- .../skills/03-prd/actions/02-finalize.md | 24 +++++++ .../skills/03-prd/assets/task-template.md | 15 ----- 8 files changed, 92 insertions(+), 108 deletions(-) create mode 100644 plugins/aidd-pm/skills/03-prd/actions/01-draft.md delete mode 100644 plugins/aidd-pm/skills/03-prd/actions/01-prd.md create mode 100644 plugins/aidd-pm/skills/03-prd/actions/02-finalize.md delete mode 100644 plugins/aidd-pm/skills/03-prd/assets/task-template.md diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md index 2f103536..8f4b09fa 100644 --- a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- # Instruction: Migrate `03-prd` to the router contract @@ -11,54 +11,29 @@ status: pending ```txt . └── plugins/aidd-pm/skills/03-prd/ - ├── SKILL.md ✏️ mermaid, `| Action | Does |`, canonical lead-in, drop `## Assets`, drop duplicated rules - ├── actions/01-prd.md ✏️ absorb the `## Assets` note; stop naming individual sections, cite the template instead - ├── assets/prd-template.md — unchanged, stays sole source of truth for the 8 sections - ├── assets/task-template.md ❌ delete — unfilled, collides by name with 10-task's real Task template - └── references/ ✅ create — issue scope mandates a references/ folder on every one of the 3 skills - └── save-path.md ✅ create — the dated save-path convention and folder-reuse rule + ├── SKILL.md ✏️ mermaid (3-node chain), `| Action | Does |`, canonical lead-in, 5+1 Transversal rules, no `## Assets` + ├── actions/01-prd.md ❌ delete — split below + ├── actions/01-draft.md ✅ create — parse+fill+iterate to approval + ├── actions/02-finalize.md ✅ create — save+verify + ├── assets/prd-template.md — unchanged, sole source of truth for the 8 sections + └── assets/task-template.md ❌ delete — unfilled, collides by name with 10-task's real Task template ``` -## Tasks to do +No `references/` folder. Issue Scope says "give each of the three a `references/` folder", but the only candidate content (the save path, one sentence) isn't reference-shaped — no table, no branching, nothing 04-spec's `tbd-marker.md`-style multi-site drift applies to. The literal AC ("no router states a rule an action or reference could hold") is satisfied either way; inlined into `finalize`'s Process step 1 instead. -### `1)` Delete the dead asset +## Decisions made during review (deviate from the original phase draft) -> Nothing fills `task-template.md`; `01-prd.md` only ever fills `prd-template.md`. - -1. Delete `assets/task-template.md`. -2. Remove the `## Assets` section's line announcing it (falls out with task 2's `## Assets` removal anyway — do this first so nothing else references it in the interim). - -### `2)` Rebuild the router - -1. Add a mermaid `flowchart LR`: one entry node (feature description, optionally with user stories) → `prd` → terminal node (saved PRD). Single action, no loop at router level — the internal draft/validate/re-show cycle stays inside the action's own `## Process` (R12: a loop back inside one action is a dash sub-item of its step, not a router-level back-edge). -2. Replace the `| # | Action | Role | Input |` table with `| Action | Does |`. -3. Replace the lead-in with the canonical sentence: "Run the flow above. Read only the next action file." -4. Delete `## Assets` entirely (R6 forbids it; the remaining asset, `prd-template.md`, is cited from the action instead). -5. Compare each `## Transversal rules` line against `actions/01-prd.md`: "focus on what/why", "sections stay concise", "wait for explicit validation" — all 3 already stated (or belong) in the action's Process/Output — delete from the router. - -### `3)` Stop enumerating PRD sections outside the template - -> Issue: the 8 sections are named twice — once in `prd-template.md`, once in prose in `01-prd.md:16`. `SKILL.md:25` already declares the template the source of truth; that declaration is the fact that survives, everything else cites it. - -1. In `actions/01-prd.md` step 2 ("Draft"), stop spelling out "overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions" inline. Replace with a citation to `assets/prd-template.md` and state only "fill every section the template defines." -2. Move "save path: `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`" and "source of truth for structure: `assets/prd-template.md`" out of the router — both already appear (or belong) in `01-prd.md`'s `## Output`/`## Process`; keep one instance, delete the other (R17). -3. Confirm acceptance criterion "adding a section to `prd-template.md` requires no other edit" holds: grep the skill folder for any other place the 8 section names are spelled out; there should be none left. - -### `4)` Create `references/save-path.md`, decide the rest - -> Issue Scope mandates a `references/` folder on every one of the 3 skills. The save-path convention is the fact that's list-shaped, not process-shaped (R15). - -1. Create `references/save-path.md`: states the dated path pattern (`aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`) and the rule to create the month directory when missing. -2. Cite it from `actions/01-prd.md`'s `## Output` line and `## Process` step 4 ("Save") with a relative link (R14, R18); delete the router's "Save path: ..." line once cited (R17). -3. Apply the same test as phase 1 to the remaining lines: "focus on what/why", "sections stay concise", "wait for explicit validation" — if each is already stated in `01-prd.md`'s Process/Output, delete the router copy. If nothing survives, omit `## Transversal rules`. +- **Split `01-prd` into `draft` + `finalize`.** The 1-action design (parse+draft+validate+save in one file) was measurably more verbose per-action than every comparable migrated skill. Matches `08-three-amigos`'s 2-action, single-responsibility shape. Net behavior unchanged (same approval gate, same output) — action-count restructuring past issue #564's literal "no behaviour change" scope, so flagged here rather than silently absorbed. +- **Added the 5-line shared boilerplate + 1 skill-specific line to `## Transversal rules`.** 6 of 7 already-migrated skills (`02,05,06,07,09,10`) share these 5 lines verbatim; a missed pattern in the first draft. +- **Dropped `affected relations` and `before -> after`** from `finalize`'s report contract — both are copy-pasted from Task/Defect/Epic, neither applies (PRD has no `relations.md`, and always creates a fresh dated file — no update-in-place exists to diff). +- **No `references/persistence.md`.** See above. ## Test acceptance criteria -| Task | Acceptance criteria | -| ---- | -------------------------------------------------------------------------------------------------------------- | -| 1 | `assets/task-template.md` no longer exists; nothing in `SKILL.md` or `actions/01-prd.md` references it. | -| 2 | `SKILL.md` has a mermaid flow, `\| Action \| Does \|` table, canonical lead-in, and no `## Assets` section. | -| 2 | No `## Transversal rules` line duplicates a step or output line in `actions/01-prd.md`. | -| 3 | The 8 PRD section names appear in exactly one file: `assets/prd-template.md`. | -| 3 | Adding a 9th section to `prd-template.md` requires editing no other file to stay accurate. | -| 4 | `references/save-path.md` exists, is cited from `actions/01-prd.md`, and the router no longer states the save path directly. | +| # | Acceptance criteria | +| - | -------------------- | +| 1 | `assets/task-template.md` no longer exists; nothing references it. | +| 2 | `SKILL.md` has a mermaid flow, `\| Action \| Does \|` table, canonical lead-in, no `## Assets`, and the 5+1 `## Transversal rules`. | +| 3 | The 8 PRD section names appear in exactly one file: `assets/prd-template.md`. | +| 4 | `draft` never writes to disk; `finalize` only ever receives an already-approved draft. | +| 5 | Live headless run: both actions chain correctly, saved file matches `prd-template.md` exactly (verified). | diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md index 148981da..b2e433b9 100644 --- a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md @@ -37,13 +37,14 @@ Each phase migrates exactly one skill. Stop after each phase for interactive rev | Decision | Why | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `TBD:` marker's one home is `04-spec/references/tbd-marker.md`, not a shared cross-skill reference | All 3 `TBD:` sites (`SKILL.md`, `01-build.md`, `02-refine.md`) live inside `04-spec`; this codebase doesn't share reference files across skills. | -| Every one of the 3 skills gets at least one named `references/` file — `01-ticket-info/references/tool-detection.md`, `03-prd/references/save-path.md`, `04-spec/references/tbd-marker.md` — not an optional folder | Issue Scope states it as a requirement ("Give each of the three a `references/` folder"), not a suggestion. | -| `01-ticket-info` and `03-prd` keep `## Transversal rules` thin (one line, or the skill-wide read-only/validation-wait constraint) rather than empty | The reference file absorbs the process-shaped duplication; what's left is genuinely skill-wide, not action-owned. | +| `references/` is per-skill judgment, not mandatory on all 3 | Issue Scope says "give each of the three a `references/` folder", but the literal AC only requires a rule to live in *an action or reference* — not that the folder exist. `01-ticket-info` gets one (`tool-detection.md`, genuinely lookup-table-shaped). `03-prd` doesn't — its only candidate (a one-sentence save path) isn't reference-shaped, inlined into `finalize` instead. | +| `01-ticket-info` ends up with no `## Transversal rules`; `03-prd` gets the 6-line pattern | `01-ticket-info`: every prior line moved to a reference or was a pure duplicate of `description` — real precedent, 8 framework skills ship `## Actions` with no `## Transversal rules`. `03-prd`: 6 of 7 already-migrated skills share 5 verbatim boilerplate lines + 1 skill-specific line — missed in the first draft, restored during review. | +| `03-prd` splits into `draft` + `finalize` (2 actions), matching `08-three-amigos`'s single-responsibility shape | User-requested during phase 2 review: the 1-action design (parse+draft+validate+save) was measurably more verbose per-action than every comparable migrated skill. Net behavior unchanged (same approval gate, same output) but this is action-count restructuring — past issue #564's literal "no behaviour change" scope. Extension flagged, not silently absorbed. | +| `03-prd`'s report contract drops `affected relations` and `before -> after` | Both copy-pasted from Task/Defect/Epic; neither applies — PRD has no `relations.md`, and always creates a fresh dated file (no update-in-place to diff). | | `04-spec`'s build-vs-refine dispatch moves into the mermaid as two entry nodes, not prose | R7: a branch stated in prose is a branch missing from the flow; R17: one fact, one home. | | One phase per skill, review gate between phases | User-requested; keeps each migration independently verifiable against the shape criterion. | | Verify AC#1 (section order, all 10 skills) and AC#5 (every plugin asset filled) in phase 3, not a separate phase | Both criteria span skills beyond any single phase's scope; checking them after the last migration is cheaper than a 4th review-gated phase. | | AC#5's "filled by an action" reads as "consumed by a named action" — a template is filled, a validator/checklist is read against | `spec-validator.yml` is read, never written; the issue's actual named defect is `task-template.md` being cited by nothing at all. Resolving the reading now avoids relitigating it mid-phase-3. | -| Each of the 3 new `references/*.md` files stays a single file per skill, not split further | R19: split a path only when it needs one fact without the other. `tool-detection.md`'s two facts (tool source, identifier format) and `save-path.md`'s one fact are both consumed by the same single action's process — no path needs one without the other. | ## Correction diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 42d5ed76..33553589 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -65,9 +65,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | +| `actions` | [01-draft.md](skills/03-prd/actions/01-draft.md) | - | +| `actions` | [02-finalize.md](skills/03-prd/actions/02-finalize.md) | - | | `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | - | -| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | | `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a need, idea, or brainstorm, confirmed before save. Use when the user wants to draft or generate a PRD or product requirements. Not for user stories or a technical plan.` | #### `skills/04-spec` diff --git a/plugins/aidd-pm/skills/03-prd/SKILL.md b/plugins/aidd-pm/skills/03-prd/SKILL.md index c367c401..683b1ba3 100644 --- a/plugins/aidd-pm/skills/03-prd/SKILL.md +++ b/plugins/aidd-pm/skills/03-prd/SKILL.md @@ -6,25 +6,25 @@ argument-hint: need | brainstorm # PRD -Drafts a structured Product Requirements Document covering scope, goals, and acceptance criteria. +```mermaid +flowchart LR + source([feature description, optionally with user stories]) --> draft --> finalize --> done([saved PRD]) +``` ## Actions -| # | Action | Role | Input | -| --- | ------- | ---------------------------------------------------- | ----------------------------------------------- | -| 01 | `prd` | Parse input, draft per template, validate, save | feature_description, user_stories (optional) | +Run the flow above. Read only the next action file. -Before running an action, read its file in `actions/`, not only the table or assets. +| Action | Does | +| -------- | -------------------------------------- | +| draft | draft per template, iterate to approval | +| finalize | save the approved draft | ## Transversal rules -- Focus on what and why; never include technical implementation detail. -- Sections stay concise and actionable. -- Always wait for explicit user validation before saving. -- Save path: `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`. -- Source of truth for structure: `assets/prd-template.md`. - -## Assets - -- `assets/prd-template.md`: PRD body template. -- `assets/task-template.md`: Lightweight task template referenced from the PRD when needed. +- Keep product and lifecycle decisions with the user. +- Separate evidence, decisions, and assumptions. +- Preserve source links and existing edits. +- Ask natural questions; never expose actions, references, or unchanged state. +- Require explicit approval or caller-provided bounded authority before any write. +- State what and why; never a technical plan or user stories. diff --git a/plugins/aidd-pm/skills/03-prd/actions/01-draft.md b/plugins/aidd-pm/skills/03-prd/actions/01-draft.md new file mode 100644 index 00000000..068cf11e --- /dev/null +++ b/plugins/aidd-pm/skills/03-prd/actions/01-draft.md @@ -0,0 +1,27 @@ +# 01 - Draft + +Draft a PRD from the template, iterating with the user to approval. + +## Input + +A feature description, and optionally existing user stories. + +## Output + +One approved PRD draft. + +## Process + +1. **Parse.** Extract scope, goals, and constraints from the description and any user stories. +2. **Fill.** Draft [prd-template.md](../assets/prd-template.md), keeping every section concise and actionable. +3. **Show.** Present the full draft and wait for explicit approval. +4. **Revise.** Fold corrections and re-show until approved. + +## Test + +| Case | Pass | +| --- | --- | +| Draft shown | every section `prd-template.md` defines is present, and no other | +| Solution detail proposed | none: no tech-stack, data-model, architecture section, or code | +| Revision requested | draft updates, then re-shown | +| Approved | unchanged draft passed to `finalize` | diff --git a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md deleted file mode 100644 index 8cd6ab10..00000000 --- a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md +++ /dev/null @@ -1,28 +0,0 @@ -# 01 - PRD - -Parse the feature input, draft a structured PRD from the template, validate with the user, then save the file under `aidd_docs/tasks/`. - -## Input - -A feature description (required), and optionally existing user stories (ids or text) to anchor the PRD. - -## Output - -The saved PRD at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`, carrying all eight sections. After writing, report its stable identity, changed fields as `before -> after`, affected relations, and verification result. Without a write, state that no persisted change occurred. - -## Process - -1. **Parse.** Extract the feature scope, goals, and constraints from the description and any user stories. -2. **Draft.** Fill [prd-template.md](../assets/prd-template.md) with its eight sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions. -3. **Validate.** Show the full draft, wait for explicit approval, and re-show after each revision. -4. **Save.** Write the approved PRD to its dated path, creating the month directory when missing. - -## Test - -| Case | Pass | -| --- | --- | -| The action completes | the PRD file exists on disk | -| The file is read back | it holds the eight headings of `assets/prd-template.md` and no other | -| Solution detail was proposed | no tech-stack, data-model, architecture section, `## Implementation` heading, or source code was written | -| A write happened | the result reports the stable identity, `before -> after` fields, affected relations, and verification result | -| No write happened | the result states that no persisted change occurred | diff --git a/plugins/aidd-pm/skills/03-prd/actions/02-finalize.md b/plugins/aidd-pm/skills/03-prd/actions/02-finalize.md new file mode 100644 index 00000000..c52db39e --- /dev/null +++ b/plugins/aidd-pm/skills/03-prd/actions/02-finalize.md @@ -0,0 +1,24 @@ +# 02 - Finalize + +Save the approved PRD. + +## Input + +One approved PRD draft. + +## Output + +The saved PRD, or no change if not written. + +## Process + +1. **Save.** Write to `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`, creating the month directory when missing. +2. **Verify.** Read the saved PRD back and report what changed. + +## Test + +| Case | Pass | +| --- | --- | +| Save succeeds | the PRD file exists on disk | +| Save reported | identity and verification result | +| No write happened | the result states that no persisted change occurred | diff --git a/plugins/aidd-pm/skills/03-prd/assets/task-template.md b/plugins/aidd-pm/skills/03-prd/assets/task-template.md deleted file mode 100644 index 5f71ea95..00000000 --- a/plugins/aidd-pm/skills/03-prd/assets/task-template.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: task -description: Task tracking system to ensure all tasks are categorized and addressed ---- - -# Task [<feature_name>] - -{{Full description}} - -## Main step 1 - -- [ ] {Task 1} -- [ ] {Task 2} -- [ ] {Task 3} -- ... From 7104696c99c7f4640eafd865d62691c3a7700a09 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com> Date: Thu, 13 Aug 2026 23:30:17 +0200 Subject: [PATCH 3/3] refactor(aidd-pm): migrate 04-spec to router contract Moves the build-vs-refine dispatch into the mermaid as two entry nodes, gives TBD: one canonical spelling in references/tbd-marker.md (fixing the 2 drifted spellings in 02-refine.md), and keeps spec's own Transversal rules rather than the epic/task/prd boilerplate, which doesn't fit a skill with no approval gate. Also fixes two pre-existing gaps caught while auditing citations: spec-template.md was never actually linked from build.md, and the feature-folder resolve step was underspecified. Two follow-up issues filed for behavior gaps out of this issue's "no behaviour change" scope: #625 (SDLC never validates a spec before handing it to Deliver) and #626 (spec-template.md has no home for TBD markers, confirmed non-deterministic placement). Closes #564. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --- .../phase-3.md | 73 +++++-------------- .../plan.md | 4 +- plugins/aidd-pm/CATALOG.md | 1 + plugins/aidd-pm/skills/04-spec/SKILL.md | 32 ++++---- .../skills/04-spec/actions/01-build.md | 18 +++-- .../skills/04-spec/actions/02-refine.md | 9 ++- .../skills/04-spec/references/tbd-marker.md | 3 + 7 files changed, 56 insertions(+), 84 deletions(-) create mode 100644 plugins/aidd-pm/skills/04-spec/references/tbd-marker.md diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md index 52864c8d..7a2b5100 100644 --- a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- # Instruction: Migrate `04-spec` to the router contract @@ -11,62 +11,27 @@ status: pending ```txt . └── plugins/aidd-pm/skills/04-spec/ - ├── SKILL.md ✏️ mermaid with 2 entry nodes, `| Action | Does |`, canonical lead-in, drop `## Assets`, drop the `TBD:` rule - ├── actions/01-build.md ✏️ cite references/tbd-marker.md instead of restating TBD: <precise question> - ├── actions/02-refine.md ✏️ same citation; fix the 2 drifted spellings (bare `TBD` at :11, short `TBD: <question>` at :27) - ├── assets/spec-template.md — unchanged - ├── assets/spec-validator.yml — unchanged + ├── SKILL.md ✏️ mermaid (2 entry nodes: build vs refine), `| Action | Does |`, canonical lead-in, no `## Assets`, own 4-line Transversal rules (not the epic/task/prd boilerplate — spec has no approval gate, doesn't fit) + ├── actions/01-build.md ✏️ cite tbd-marker.md, cite spec-template.md (pre-existing gap, was never actually linked), drop before->after/affected relations (always creates fresh, no diff) + ├── actions/02-refine.md ✏️ cite tbd-marker.md, fix 2 drifted TBD spellings, keep before->after (legitimate — rewrites in place), drop affected relations └── references/ - └── tbd-marker.md ✅ create — the one canonical `TBD:` spelling and rule + └── tbd-marker.md ✅ create — the one canonical `TBD: <precise question>` spelling ``` -## Tasks to do +## Decisions -### `1)` Create the `TBD:` marker's one home +- **No epic/task/prd Transversal-rules boilerplate.** Checked each of the 5 shared lines against what `build`/`refine` actually do: no approval gate before write, no lifecycle, uses TBD-marking instead of interactive questioning. None of it fits — inventing it would add behavior that doesn't exist. Kept spec's own rules instead (matches `08-three-amigos`'s precedent of not sharing the boilerplate either). +- **Dispatch-by-input moved into the mermaid** as two entry nodes (request/PRD → `build`, spec+findings → `refine`), replacing the router prose that stated the same branch (R7, R17). +- **`before -> after` kept in `refine`, dropped from `build`.** `refine` genuinely rewrites an existing file in place (real diff). `build` always creates a fresh dated file — no prior state exists to diff. +- **Router never cites a reference.** No other router does (checked all 7) — R18 only names Process/Output/Test as valid citation sites. Router states policy in plain words ("Never invent; mark every gap instead of guessing"); the actions cite `tbd-marker.md` where they apply it. +- **`tbd-marker.md` trimmed to the literal string only** (`TBD: <precise question>`, no policy prose) — the policy already lives once in the router; anything more would duplicate it. +- **`build.md`'s Source step split into 2 sub-bullets** (PRD path vs free-form request) instead of one dense sentence; "never explore the codebase" promoted out of it into the router's Transversal rules (applies to both actions, not just Source). +- **`refine.md`'s Output cut to one line**, TBD citation removed from Output (stays in Process step 4 only — was duplicated), added an explicit `Verify` step so `before -> after` reporting has a Process home instead of living only in prose. +- **Two pre-existing gaps fixed while auditing citations, not part of the original scope:** `build.md` never linked `spec-template.md` (called it "the template" in prose only); the router's "reuse the folder when it exists" line was deleted without moving its actual path pattern into `build.md` (first draft), caught by a live headless run hitting the gap itself. Second catch: the fixed version still lost the word "resolve" (search-then-reuse-or-create), reducing it to a same-day-only check — restored the two-outcome framing. +- **Two follow-up issues filed, not fixed here** (behavior changes, out of #564's "no behaviour change" scope): [#625](https://github.com/ai-driven-dev/framework/issues/625) — SDLC's Frame stage never checks `spec-validator.yml` before handing a spec to Deliver. [#626](https://github.com/ai-driven-dev/framework/issues/626) — `spec-template.md` has no `## Open Questions` section, so TBD placement is non-deterministic (confirmed: same feature, two runs, two different placements). -> Issue: 3 sites, 3 drifting spellings, no owner. All 3 sites already live inside `04-spec` — resolved during brainstorm as an intra-skill reference, not a cross-skill shared one (this codebase doesn't share references across skills). +## Plugin-wide verification (AC#1, AC#5 — span all 10 skills, checked here as the last phase) -1. Create `references/tbd-marker.md`: states the exact literal `TBD: <precise question>`, the rule "never guess, mark the gap instead", and nothing else (R15: one fact per reference). -2. In `SKILL.md`'s `## Transversal rules`, replace the inline "Mark every gap as `TBD: <precise question>`..." line with a citation to the reference (R18) — the rule's text now lives only in `references/tbd-marker.md`. -3. In `actions/01-build.md` step 2 ("Gaps"), replace "Replace any missing required field with `TBD: <precise question>`" with a citation to the reference. -4. In `actions/02-refine.md`: fix `:11`'s bare `` `TBD` `` (Output line) and `:18`/`:27`'s spellings so every occurrence either matches the canonical literal exactly or cites `references/tbd-marker.md` instead of re-typing it. - -### `2)` Rebuild the router with a branching mermaid - -> R7: the existing dispatch prose ("a spec path with findings runs `refine`; a request or PRD path runs `build`") is a branch — it belongs in the flow, not as router prose (R17: one fact, one home). - -1. Add a mermaid `flowchart LR` with 2 entry nodes: one for "request or PRD path" → `build`, one for "spec path + findings" → `refine`. Both converge on a terminal node (`spec.md` written/updated). -2. Delete the "Dispatch by input: ..." sentence from the router prose once the mermaid states it — do not keep both (R17). -3. Replace the `| # | Action | Role | Input |` table with `| Action | Does |`. -4. Replace the lead-in with the canonical sentence: "Run the flow above. Read only the next action file." -5. Delete `## Assets` entirely; `spec-template.md` and `spec-validator.yml` get cited from the actions that use them instead. - -### `3)` Sort the remaining `## Transversal rules` lines - -> Everything except the `TBD:` rule (moved in task 1) needs a home: stays as genuinely cross-cutting (both `build` and `refine` rely on it), or moves into one action if only one uses it. - -1. "The spec holds intent, never implementation..." — used by both actions (both write/rewrite the spec body) → stays a router transversal rule, or becomes `references/spec-shape.md` if it grows past what a router line should hold (R15 vs R9 — keep as a router line unless it's genuinely table/list-shaped). -2. "Keep it readable..." — same test as above. -3. "Output: one `spec.md` in the feature folder... Reuse the folder when it exists." — both actions write to the same path; verify it isn't already stated in both actions' `## Output`. If it is, delete the router copy (R17); if neither states it, it's genuinely transversal and stays. -4. "Immutable once validated: never rewrite a spec that has been locked." — check whether this constraint is enforced/stated anywhere in `02-refine.md`; if not, this is a gap the migration surfaces (not new scope, but flag it rather than silently drop it). - -### `4)` Verify the plugin-wide acceptance criteria - -> AC#1 ("same shape, sections, **and section order**") and AC#5 ("every asset in the plugin is filled by an action") aren't scoped to one skill — this is the last phase, so it's where they get checked across all 10. - -1. For each of the 10 `plugins/aidd-pm/skills/*/SKILL.md`, dump the `^#{1,2} ` heading sequence (`grep -n '^#\{1,2\} '`) and confirm all 10 now agree: `# Title`, `## Actions`, `## Transversal rules`, in that order, nothing else. -2. Enumerate `plugins/aidd-pm/skills/*/assets/*` and confirm each file is consumed by a named action: a template asset is filled (produces the output artifact), a validator/checklist asset is read against (gates the output). `04-spec/assets/spec-validator.yml` is the one checklist-shaped asset in scope — already cited from both `01-build.md` and `02-refine.md` — so it passes under "consumed by a named action", the actual defect AC#5 targets being `task-template.md`'s prior state: cited by nothing at all. State this reading to the user when reporting the phase, rather than re-litigating it live. -3. Report to the user: the issue's own count is off by one (it says "eight follow the contract, three don't" = eleven, and AC#1 says "eleven routers"; the plugin has 10 skills total, so it's seven already-migrated plus three migrated here). Flag this the same way the issue's "What already landed" section already flagged two other wrong claims — don't silently satisfy the literal "eleven". - -## Test acceptance criteria - -| Task | Acceptance criteria | -| ---- | ---------------------------------------------------------------------------------------------------------------- | -| 1 | `grep -rn "TBD" plugins/aidd-pm/skills/04-spec/` shows exactly one canonical literal spelling, defined once in `references/tbd-marker.md`, cited (not restated) everywhere else. | -| 2 | `SKILL.md`'s mermaid shows both entry cases (build vs refine); no router prose duplicates the dispatch rule the mermaid now states. | -| 2 | `SKILL.md` has `\| Action \| Does \|`, canonical lead-in, no `## Assets` section. | -| 3 | Every remaining `## Transversal rules` line states a fact no single action's `## Process`/`## Output` already states. | -| 3 | The "immutable once locked" constraint is either confirmed enforced somewhere reachable from `02-refine.md`, or explicitly flagged in the phase review as a pre-existing gap. | -| 4 | All 10 `SKILL.md` heading sequences match exactly (title, Actions, Transversal rules, that order, nothing else). | -| 4 | Every `plugins/aidd-pm/skills/*/assets/*` file is confirmed consumed by a named action (template filled, or validator cited); `spec-validator.yml`'s read-only status is reported to the user as the resolved reading, not asked about. | -| 4 | The "eleven routers" vs. actual 10-skill count discrepancy is reported to the user, not silently absorbed. | +- All 10 `SKILL.md` files: `# Title` → `## Actions` (mermaid + `| Action | Does |` + canonical lead-in) → optional `## Transversal rules`. Section presence varies only where content is legitimately absent (`01-ticket-info` has none — real precedent elsewhere in the framework, e.g. `aidd-dev:01-plan`), never order. +- Every asset in `plugins/aidd-pm/skills/*/assets/*` is cited from a named action. `spec-validator.yml` is read against, not filled — the "consumed by a named action" reading (see `plan.md` Decisions) covers it. +- **Issue count correction:** issue #564 says "eight follow the contract, three don't" (= 11) and AC#1 says "the eleven routers." The plugin holds 10 skills, not 11 — 7 already matched the contract, 3 migrated here. Reporting this rather than silently treating "eleven" as satisfied. diff --git a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md index b2e433b9..d48df384 100644 --- a/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md +++ b/aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md @@ -1,6 +1,6 @@ --- objective: "01-ticket-info, 03-prd, and 04-spec routers match the aidd-pm contract (07-epic shape): references/ hold every rule an action doesn't, TBD: has one spelling in one file, and the PRD sections live only in prd-template.md." -status: in-progress +status: implemented --- # Plan: Migrate ticket-info, PRD, spec to the router contract @@ -45,6 +45,8 @@ Each phase migrates exactly one skill. Stop after each phase for interactive rev | One phase per skill, review gate between phases | User-requested; keeps each migration independently verifiable against the shape criterion. | | Verify AC#1 (section order, all 10 skills) and AC#5 (every plugin asset filled) in phase 3, not a separate phase | Both criteria span skills beyond any single phase's scope; checking them after the last migration is cheaper than a 4th review-gated phase. | | AC#5's "filled by an action" reads as "consumed by a named action" — a template is filled, a validator/checklist is read against | `spec-validator.yml` is read, never written; the issue's actual named defect is `task-template.md` being cited by nothing at all. Resolving the reading now avoids relitigating it mid-phase-3. | +| `04-spec` keeps its own 4-line `## Transversal rules`, not the epic/task/prd 5+1 boilerplate | Checked each shared line against what `build`/`refine` actually do: no approval gate before write, no lifecycle, TBD-marking instead of interactive questioning. None fit — matches `08-three-amigos`'s precedent of not sharing the boilerplate either. | +| `04-spec`'s report contract keeps `before -> after` in `refine`, drops it from `build`; drops `affected relations` from both | `refine` rewrites an existing file in place (real diff); `build` always creates fresh (nothing to diff). No `relations.md` exists for spec, same as PRD. | ## Correction diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 33553589..027f408b 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -77,6 +77,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-build.md](skills/04-spec/actions/01-build.md) | - | | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | +| `references` | [tbd-marker.md](skills/04-spec/references/tbd-marker.md) | - | | `-` | [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 when the user wants to draft or refine a spec. Not for writing code, a full PRD, or changing a locked spec.` | #### `skills/05-spike` diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index 9763776f..10afd34c 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -6,27 +6,25 @@ argument-hint: request | prd | spec # Spec -Generate or refine the immutable contract for a feature: its target, hard constraints, non-goals, and done-when. +```mermaid +flowchart LR + request([request or PRD path]) --> build --> done([spec.md]) + target([spec path + findings]) --> refine --> done +``` ## Actions -| # | 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 | +Run the flow above. Read only the next action file. -Dispatch by input: a spec path with findings runs `refine`; a request or PRD path runs `build`. -Before running an action, read its file in `actions/`, not only the table or assets. +| Action | Does | +| ------ | -------------------------------------------------- | +| build | draft a fresh spec from a request or PRD | +| refine | rewrite an existing spec to address findings | ## Transversal rules -- Never invent. Mark every gap as `TBD: <precise question>` 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/<yyyy_mm>/<yyyy_mm_dd>_<slug>/`), 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`: the spec's structure. -- `assets/spec-validator.yml`: the checklist a spec is validated against. +- Never invent; mark every gap instead of guessing. +- Never explore the codebase. +- Hold intent, never implementation: solution-agnostic, no how, few acceptance criteria. +- Keep it readable: clear headers, bulleted criteria, explicit non-goals. +- Immutable once validated: never rewrite a locked spec. 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 a2076de9..ba2e7111 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -8,15 +8,18 @@ A free-form request, or a path to an existing PRD. A feature name for the folder ## Output -The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted. Report its stable identity, changed fields as `before -> after`, affected relations, and verification result. Without a write, state that no persisted change occurred. +The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted, or no write when the request is too vague. ## Process -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. -2. **Gaps.** Replace any missing required field with `TBD: <precise question>`. Never guess. -3. **Check.** Confirm every section the validator requires is present. Omit an optional section (stakeholders, context) that has nothing to say rather than emit a placeholder. -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. +1. **Qualify.** When the request is too vague to draft anything useful, stop and ask for a clearer one. +2. **Source.** Map the input onto [spec-template.md](../assets/spec-template.md), dropping any implementation detail. + - PRD path: lift its target, hard constraints, non-goals, and done-when. + - Free-form request: map it directly onto the template sections. +3. **Gaps.** Replace any missing required field per [tbd-marker.md](../references/tbd-marker.md). +4. **Check.** Confirm every section the validator requires is present. Omit an optional section (stakeholders, context) that has nothing to say rather than emit a placeholder. +5. **Write.** Resolve the feature folder: reuse an existing `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/` match for this feature, or create one. Save it there. +6. **Return.** Surface its path and the notes. ## Test @@ -25,5 +28,4 @@ The path to `spec.md` in the feature folder, drafted from the template, with the | The action completes | `spec.md` exists in the feature folder | | The file is validated | every section required by [spec-validator.yml](../assets/spec-validator.yml) is present | | The spec is read back | it carries no library name, framework pattern, or source-file layout | -| A write happened | the result reports the stable identity, `before -> after` fields, affected relations, and verification result | -| No write happened | the result states that no persisted change occurred | +| Too vague | no write; one clarifying question returned | 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 06cf699d..cf4e7f6f 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -8,15 +8,16 @@ The path to the current spec, and the findings to address, a list or free text. ## Output -The refined spec at the same path, with the changes applied and any residual `TBD` questions noted. Report its stable identity, changed fields as `before -> after`, affected relations, and verification result. Without a write, state that no persisted change occurred. +The refined spec at the same path, or no change if not written. ## Process 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: <precise question>`. Never guess. +4. **Gaps.** Replace any field still unanswered per [tbd-marker.md](../references/tbd-marker.md). 5. **Check.** Confirm every section the validator requires is present, then overwrite the spec at its path. +6. **Verify.** Report what changed as `before -> after`, and the verification result. ## Test @@ -24,6 +25,6 @@ The refined spec at the same path, with the changes applied and any residual `TB | --- | --- | | The action completes | the spec still exists at its path with every section required by [spec-validator.yml](../assets/spec-validator.yml) | | A finding is resolved | the spec changed at the section it names | -| A finding cannot be resolved | an explicit `TBD: <question>` marks it in place | -| A write happened | the result reports the stable identity, `before -> after` fields, affected relations, and verification result | +| A finding cannot be resolved | the marker from [tbd-marker.md](../references/tbd-marker.md) marks it in place | +| A write happened | the result reports the stable identity, `before -> after` fields, and verification result | | No write happened | the result states that no persisted change occurred | diff --git a/plugins/aidd-pm/skills/04-spec/references/tbd-marker.md b/plugins/aidd-pm/skills/04-spec/references/tbd-marker.md new file mode 100644 index 00000000..9cbcbda6 --- /dev/null +++ b/plugins/aidd-pm/skills/04-spec/references/tbd-marker.md @@ -0,0 +1,3 @@ +# TBD marker + +`TBD: <precise question>`