Skip to content

refactor(aidd-pm): migrate ticket-info, prd, and spec to router contract #628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
blafourcade merged 3 commits into from
Aug 14, 2026
Merged

refactor(aidd-pm): migrate ticket-info, prd, and spec to router contract #628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4ec41e9
refactor(aidd-pm): migrate 01-ticket-info to router contract
blafourcade Aug 10, 2026
c4c5bf0
refactor(aidd-pm): migrate 03-prd to router contract
blafourcade Aug 13, 2026
7104696
refactor(aidd-pm): migrate 04-spec to router contract
blafourcade Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`. |
39 changes: 39 additions & 0 deletions aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
status: done
---

# Instruction: Migrate `03-prd` to the router contract

## Architecture projection

> ✅ create · ✏️ modify · ❌ delete

```txt
.
└── plugins/aidd-pm/skills/03-prd/
├── 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
```

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.

## Decisions made during review (deviate from the original phase draft)

- **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

| # | 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). |
37 changes: 37 additions & 0 deletions aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/phase-3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
status: done
---

# Instruction: Migrate `04-spec` to the router contract

## Architecture projection

> ✅ create · ✏️ modify · ❌ delete

```txt
.
└── plugins/aidd-pm/skills/04-spec/
├── 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: <precise question>` spelling
```

## Decisions

- **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).

## Plugin-wide verification (AC#1, AC#5 — span all 10 skills, checked here as the last phase)

- 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.
53 changes: 53 additions & 0 deletions aidd_docs/tasks/2026_08/2026_08_10_migrate-pm-router-contract/plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
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: implemented
---

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

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