Ready

Verify readiness for AI-driven development for the Jira item: the argument (text following the ready: trigger)

ready: is the status-anchored readiness gate. Given a Jira VI (or VI + Epic) key, it reads the declared Jira workflow status — never inferred, never re-derived — and checks whether the ARD/spec/design artifacts that actually exist, taken together, justify that status and the next transition, against the rubric in ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/workflow-states.md. It returns SUPPORTED / PARTIAL / NOT-SUPPORTED with a requirement coverage roll-up and named gaps, gated on the Opus readiness-reviewer.

Key distinction from every other pipeline command: ready: authors nothing in the VI/Epic/ARD/spec/design sense — it never writes any of those, and it never touches Jira. Its only authored write is an overwritten _readiness.md snapshot under $SPECS_PATH, and it branches only via the phase-handoff.md §4.3 consent choice to hand that snapshot off, creating ready/<KEY>-<slug> — specs-preflight itself still creates none, switching $SPECS_PATH only between branches that already exist and are plugin-created (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.2). _readiness.md is likewise committed only through that same §4.3 choice, never automatically — declining leaves it uncommitted; the terminal commit-artifacts step commits ONLY the run's bounded session-artifact paths (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.1), which _readiness.md is not. Where design:'s repo gate is a strict, hard-stop mount check because it is about to ground code decisions, ready:'s repo check is best-effort presence only — it never scans code, it only notes whether a needed repo is mounted.

Key distinction from every other consumer of ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md §3 (require-on-main) and ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-resolution.md: every other caller stops when a gated ARD/spec/design resolves off the specs repo's default branch; ready: never does. That state becomes a readiness finding — "authored but not handed off" — that caps the eventual verdict at PARTIAL; an artifact that is absent outright is recorded as missing in the coverage roll-up, exactly as before this feature. Reporting readiness is ready:'s whole function, so a run that stops instead of reporting has failed at the one thing it exists to do.

Key distinction from design:'s Epic-picker behavior: ready:'s two-key grammar treats a null focus_key as a first-class VI-level check (workflow-states.md's VI ladder), not something that must be resolved down to a single Epic. Pass an explicit <VI> <Epic> to scope the check to one Epic (the Epic ladder) instead.

Phase 0 — Resolve input

1. Resolve the Jira input via the shared front-end. Execute ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/jira-input-resolution.md against the argument (text following the ready: trigger). ready: is jira-driven only: expect mode: jira-driven. The front-end owns the $VAULT_PATH / jira-products validation, Fallbacks A/B and D/E, and the VI-selector (key-or-directory) + focus-Epic grammar. Carry forward jira_key, focus_key, jira_export_root, source.

   Define <VI> = jira_key and <EPIC> = focus_key (may be null) — the two-key grammar.

   If the front-end returns mode: direct (no Jira input), stop with READY_NEEDS_JIRA: ready: needs a Jira key or an imported-Jira directory. — ready: has no direct-prompt behavior.

2. Resolve $SPECS_PATH. ready: reads the ARD/spec/design artifacts and writes _readiness.md under $SPECS_PATH/specifications/. If $SPECS_PATH is unset, stop with a clear error naming SPECS_PATH: choices: ["Set SPECS_PATH (enter the path)", "Cancel"].

Specs-repo preflight. Cite ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md and execute its specs-preflight entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. Prompt-free and silent when the specs repo is clean and on its default branch. If a guard fires, emit its §5 notice; if it returns specs_git: blocked (§3.3 G0), carry that flag for the whole run — the terminal commit-artifacts step skips on it.

3. Read from a clean specs-repo main — never a branch. The specs repo's main (or master) branch is the handoff surface for every artifact ready: judges (per design:'s Phase 0 rule). Check git -C $SPECS_PATH branch --show-current and git -C $SPECS_PATH status --porcelain:

   • Not on main/master, or the tree is dirty → warn (a non-main or dirty checkout may show unmerged, in-flight artifacts as if they were the handed-off truth) and ask: choices: ["I've switched to a clean main — re-check", "Proceed anyway on the current checkout (read-only; noted in the report)", "Cancel", "Other… (describe)"]
   • Clean main/master → proceed silently.

4. Map onto the specs repo (VI dir + optional Epic subdir). Resolve the VI dir $SPECS_PATH/specifications/<VI>-<vslug>/ by key-number match (tolerate a stray -/_ after the key and a human-adjusted slug — the same tolerance ard-resolution.md and design: use). When focus_key is set, additionally resolve the per-Epic subdir <VI-dir>/<EPIC>-<eslug>/ by the same tolerance. Unlike design:, a missing dir is NOT a hard stop — an early-lifecycle VI (e.g. Open / Problem stated) legitimately has no specs-repo footprint yet, and "nothing exists" is itself readiness-relevant data, not an error. Record whichever dir(s) resolved (or "not found — no specs-repo footprint yet").

ready: is cwd-agnostic — it reads an absolute $SPECS_PATH-rooted feature folder and (Phase 3) best-effort-checks repos under $REPOS_PATH; cwd need not be inside either.

Phase 1 — Clarify + artifact inventory

Rule: Ask, don't guess. This rule is absolute. Use choices arrays; the last choice in every array MUST be "Other… (describe)".

1. Confirm the resolved scope. choices: ["Use <VI dir> [+ <Epic subdir>] (Recommended)", "Use a different path (you'll be prompted)", "Cancel", "Other… (describe)"]

2. Artifact inventory (mechanical presence + handoff check — no content judgment yet). By mode:

   • VI-level (focus_key null) — locate <VI-dir>/<VI>_ARD.md (resolved via Phase 2.5, not here) and <VI-dir>/specification.md (a VI-level spec is optional per workflow-states.md); then enumerate every Epic subdirectory under <VI-dir> that matches a key-number pattern, and for each locate {<EPIC>_ARD.md, specification.md, design.md} — this is per-Epic and plural, because a VI's "Ready for Implementation" status requires every in-scope Epic to carry spec + design (workflow-states.md's VI row).
   • Epic-level (focus_key set) — locate the VI-level <VI-dir>/<VI>_ARD.md (inherited invariants) plus the single focus Epic's {<EPIC>_ARD.md, specification.md, design.md} under <VI-dir>/<EPIC>-<eslug>/.

   For each specification.md and design.md path located above (the _ARD.md files are handled by Phase 2.5's ard-resolution.md, not here), execute require-on-main (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md §3) against its repo-relative path and map its §3.7 return value by stopped first, never by on_main alone — never a stop, per this command's defining trait: stopped: false with on_main: pass/pass_amending → present (with its absolute path); stopped: false with on_main: absent → missing, exactly as before this feature (§3.4's ready: row — this is row F only, never rows D/E, which also read absent on origin/<default> but return stopped: true); stopped: false with on_main: unmanaged → fall back to a raw filesystem presence check, exactly as before this feature (row H's own silent-skip contract); stopped: true → still never a stop for ready: — map the row to exactly one of three ⚠ reasons, never conflating them, because they are three different repository states, not one: rows D/E → ⚠ authored only on <branch>, not merged (naming the branch and any open PR); rows C′/C after a failed retry → ⚠ on <default> but your local checkout is stale or dirty, so it could not be confirmed; rows G/I (including the run's own specs_git: blocked) → ⚠ could not be verified against any ref (naming the returned degraded clause where present). Each is recorded verbatim as a readiness finding — ready: itself never asks a further question, retries, or stops on top of what came back: row C's own prompt-once-and-re-test-once (phase-handoff.md §3.3 row C, :139-143) and row C′'s own immediate stop naming the blocking files are require-on-main's contract, already executed synchronously inside this very step; ready: only records whichever stopped/degraded state the call returned. Record each ARD as present (with its absolute path) or absent — its on-main state is Phase 2.5's job. Do not open/read file contents yet beyond what's needed for these checks — full reads happen in Phase 4 via the reviewer.

3. Quick Jira status peek (display only — not the ground truth). Read <jira_export_root>/<jira_key>-index.md's | Key | Type | Status | Summary | Role | table directly (mechanical — no subagent) and note the Status column for <VI> and, when set, <EPIC>. This is for Phase 1 display context only; Phase 2's jira-reader read is the authoritative source the reviewer verifies against.

4. Display (context, no further prompt): resolved cwd; resolved VI dir (+ Epic subdir); resolved $SPECS_PATH; the artifact inventory table from step 2; the status peek from step 3.

No branching context is shown — nothing here branches this run; the only branch ready: ever creates is ready/<KEY>-<slug>, and only later, at Phase 5's handoff, and only on the §4.3 consent choice. specs-preflight itself still creates none, switching $SPECS_PATH only between branches that already exist and are plugin-created, per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.2.

Phase 1.5 — Classify

Load and follow the model-routing policy at ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md, then classify the task as exactly one of: SIMPLE, MODERATE, SIGNIFICANT, or HIGH-RISK. Readiness verification is typically MODERATE (bounded scope, a single VI or Epic, read-only, no code changes) — escalate to SIGNIFICANT only for an unusually large multi-Epic VI where the coverage chain spans many Epics/repos. State the classification and a one-sentence reason.

ready: has no delegated writer/implementation subagent — the Phase 3 skeleton is deterministic and orchestrator-inline, and the only judgment-heavy delegate is the readiness-reviewer gate (Opus, caller-pinned via task(model:), mandatory regardless of tier). Resolve the per-step routing per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md §9:

model_routing:
  classification: MODERATE        # typical; SIGNIFICANT possible for a large multi-Epic VI
  reason: <one-line>
  current_model: <the model this orchestrator is running under>
  detection_model: <§2.1 detection chain: claude-sonnet-4.6, fallback claude-sonnet-4.5/gpt-5.4>   # jira-reader (Phase 2); the Phase 3 deterministic skeleton is mechanical and runs orchestrator-inline, not delegated
  review_model:    <§2 Opus chain>     # readiness-reviewer (caller-pinned; recorded)
  opus_available: <true if a §2 Opus model resolved, else false>
  notes: <any §2/§2.1 fallback or degradation>

No relaunch advisory for MODERATE — the mechanical steps run on their detection pin and the orchestration runs on current_model, which §3.1 allows. If no Opus is available, readiness-reviewer falls to the Sonnet floor — record the degradation in notes and the final report.

Phase 2 — Read ground truth

Invoke jira-reader with depth: vi-plus-epics — this is the authoritative status/requirement source the reviewer verifies the declared status against (never Phase 1's status peek).

→ task(agent_type: "dev-workflows:jira-reader", model: <detection_model — §9 / §2.1 detection chain>):

"Return the structured handoff for this brief:

jira_export_root: [resolved jira_export_root] jira_key: [resolved jira_key] depth: vi-plus-epics"

Wait for the handoff. If status: NOT_FOUND or status: EMPTY, surface the Jira key dir not found rule in ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md (["Re-enter key", "Cancel"]). On OK, carry forward:

• value_increment.status — the VI's declared status (VI ladder).
• linked_items[] filtered to type == Epic and their .status — each Epic's declared status (Epic ladder). When focus_key is set, validate it is among these; if not, surface READY_FOCUS_NOT_FOUND: <focus_key> is not a linked Epic of <jira_key>. with choices: ["Check VI-level readiness instead (the whole VI)", "Re-enter the Epic key", "Cancel"].
• requirements[] (+ requirements_source) — the coverage ground truth for Phase 3(a).

These declared statuses are passed to the reviewer exactly as read — never inferred, never re-derived (per readiness-reviewer.md's hard rules).

Phase 2.5 — Resolve ARD

Resolve any applicable ARD by citing ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-resolution.md with vi = jira_key, epic = focus_key (may be null), and $SPECS_PATH.

• status: none (including $SPECS_PATH unset/unresolvable) → the ARD dimension is inactive for this run — no prompt, no extra output, readiness-reviewer's ARD-conformance dimension is skipped entirely (no-regression, per ard-resolution.md).
• status: found → carry the returned invariants (AD#N list, VI-level inherited + Epic-level when in scope) forward to Phase 4 as applicable_ard. ready: never edits the ARD and never authors a deviation record itself — it only checks whether one already exists in the artifacts it reads (an artifact that violates an AD#N without a matching - ARD deviation: … flag: architect line is a BLOCKER per the reviewer's ARD-conformance dimension).
• status: unmerged → never stop, the one exemption ard-resolution.md's no-regression rule names. Carry the returned invariants forward to Phase 4 as applicable_ard exactly as found does, and additionally carry the returned branch/pr forward as a readiness finding — "ARD authored, not handed off" — into Phase 3(b)'s status-expectation table, so it reaches readiness-reviewer and caps the eventual verdict at PARTIAL rather than letting a not-yet-merged ARD read as equivalent to a merged one.

Phase 3 — Deterministic skeleton

Mechanically build three inputs for the reviewer — orchestrator-inline, no subagent, no user prompt.

(a) Coverage map. For each requirement in Phase 2's requirements[] (by id), grep its ID token across the in-scope Epic .md file(s) and any specification.md(s)/design.md(s) Phase 1 found locally — that is every artifact except the one ⚠ reason where no local copy exists at all: authored only on <branch>, not merged (rows D/E), which has no local path on the checked-out <default> to grep and is excluded from this grep pass, not silently treated as absent; its own ⚠ finding already carries in Phase 3(b). The other two ⚠ reasons (rows C′/C's stale-or-dirty local checkout; rows G/I's unverifiable-against- any-ref) still have a local file on disk and are grepped exactly like a ✅ artifact — their ⚠ is about handoff verification, not about content availability. Record, per requirement: which Epic(s) mention it, whether a specification.md mentions it, whether a design.md mentions it, or "not found by ID in any artifact". Acknowledge the limitation (carried to the final report's Assumptions section): this is an ID-grep, not semantic matching — an artifact may cover a requirement thematically without repeating its literal ID; readiness-reviewer reads the full artifact text and can catch what the grep misses.

(b) Status-expectation checklist. Look up the declared VI status (and, when in scope, each Epic status) on the matching ladder in ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/workflow-states.md, list that status's "Expected artifacts" column, and mark each expected artifact present ✅, absent ❌, or — per Phase 1's require-on-main check and Phase 2.5's status: unmerged handling — ⚠, carrying forward whichever of Phase 1's three reasons applies (authored only on a branch, not merged; on <default> but locally unconfirmed; or unverifiable against any ref) against Phase 1's inventory. A ⚠ artifact of any of the three reasons is a finding for the reviewer's "Status consistency" dimension, at no less than MAJOR severity — it does not satisfy the status the way a merged ✅ does, but it is not a BLOCKER and never stops this run. This is the mechanical half of that dimension.

(c) Repo-availability presence-check (best-effort, presence only — never scanning).

1. Derive candidate repo names from: each in-scope Epic's ## Pull Requests section URLs (the repo-name segment of each URL, per jira-reader's PR URL formats); the confirmed-repos line of any design.md found (design-format.md's header - **Repos**: <the confirmed implementation repos this design spans>); and any ARD's grounded_repos: frontmatter list (ard-format.md). Dedupe.
2. Build the slug→clone map exactly as epics.md Phase 4 does: for each top-level directory under each entry of ${REPOS_PATH:-/workspace}, run timeout 5 git -C <dir> remote get-url origin 2>/dev/null, strip a trailing .git, and take the URL's last path segment as that clone's slug. Skip directories with no .git or whose git remote call fails/times out.
3. Match each derived candidate against the map: mounted (record the resolved path) or not-mounted. Presence only — never dispatch code-scanner, never confirm/mount-gate like design:'s Phase 3; this is informative context for the reviewer's "Repo availability" dimension, not a hard gate.
4. If no repo names are derivable from any source (no PRs yet, no design.md, no ARD grounded_repos) → record repos: not-yet-determinable rather than an empty/false "all missing" result — this is the normal case pre-implementation and must not read as a gap.

Phase 4 — Readiness review

Dispatch readiness-reviewer (Opus, caller-pinned via task(model:)) with the Phase 3 skeleton, the artifact paths from Phase 1 (the reviewer reads each end-to-end itself — it carries view/glob/ grep), the Phase 2 declared statuses, applicable_ard (omit entirely when Phase 2.5 was none), and a pointer to the rubric.

→ task(agent_type: "dev-workflows:readiness-reviewer", model: <review_model — §2 Opus chain>):

"Review readiness for this brief:

Task description: [one paragraph: [+ ], the declared status(es), what is being verified] requirements: [paste the requirements[] array from Phase 2] coverage_map: [paste Phase 3(a)] status_expectation: [paste Phase 3(b), plus the workflow-states.md rubric reference] repo_availability: [paste Phase 3(c)] artifact paths: VI: [/.md if read, or the jira-reader handoff's VI summary] ARD: [absolute path(s), or 'none'] Epics: [absolute path(s) in scope] specs: [absolute path(s) in scope] designs: [absolute path(s) in scope] declared_status: [VI: ; Epics: =, …] applicable_ard: [the Phase 2.5 invariants, or omit entirely if status was none] workflow_states_rubric: ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/workflow-states.md"

Carry back the verdict (SUPPORTED / PARTIAL / NOT-SUPPORTED) and the full Findings section (by dimension) for Phase 5. readiness-reviewer never modifies files and never re-derives status — a run that returns without a verdict or without the declared-status/requirements[] ground truth is a plugin-gap halt (see Invariants).

Phase 5 — Write report

1. Compose the readiness artifact. Build the report content: a header stamping the run timestamp (ISO 8601 UTC), the specs-repo git rev (git -C $SPECS_PATH rev-parse --short HEAD), the checked Jira status(es) exactly as read in Phase 2, the verdict, the coverage roll-up (N/M requirements covered, P%, each ❌ gap requirement ID named), and the full Findings section from Phase 4.

2. Write _readiness.md, overwriting any prior run, to the VI dir (VI-level) or the Epic subdir (Epic-level):

   ---
   type: dev-workflows-readiness
   vi: <JIRA_KEY>
   epic: <FOCUS_KEY>            # omitted when VI-level (focus_key null)
   ---
   
   # Readiness check — <run timestamp, ISO 8601 UTC>
   
   - Specs repo rev: <short HEAD>
   - Checked status: VI=<status>[, Epic <KEY>=<status>, …]
   - Verdict: SUPPORTED | PARTIAL | NOT-SUPPORTED
   
   ## Coverage roll-up
   <N/M requirements covered (P%); each ❌ gap requirement ID, one per line>
   
   ## Findings
   <the readiness-reviewer's Findings section, verbatim, by dimension>
   
   ## Repo availability
   <Phase 3(c) result>
   
   ---
   Generated by `ready:`. Committing and handing this off to `<default>` is offered, never automatic —
   see this run's terminal report for the outcome.
   

3. Hand off _readiness.md (commit-when-asked — never automatic). Present ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md §4.3's consent choice verbatim: choices: ["Branch + commit + push + open PR to main (Recommended)", "Just write the files — I'll handle git (the next phase will stop until this is on main)", "Cancel"]. On the first choice, execute handoff-to-main (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md §2) with prefix: ready; feature_folder = the VI dir or Epic subdir step 2 wrote into; deliverable_paths = _readiness.md; title: <VI|EPIC> Update readiness snapshot; and body_facts = the verdict, the coverage roll-up (N/M, P%), and the checked Jira status(es). Because _readiness.md is overwritten every run, §2.2's collision rule fires on most re-runs against an already-merged prior branch — expect the -2/-3 substitution, and report it via the §4.1 outcome line as that section requires. Emit that line in the terminal report's Phase handoff section (step 4).

4. Emit the terminal report to stdout:

   ## Readiness Report
   
   ### Classification
   [MODERATE | SIGNIFICANT] — [one-line reason]
   
   ### Model Routing
   - Session model (current_model): [model]
   - Detection steps — jira-reader (detection_model): [model]
   - readiness-reviewer (review_model): [model]
   - Opus available: [yes | no]
   
   ### Scope
   - VI: <JIRA_KEY> — [summary]
   - Epic: <FOCUS_KEY> — [summary] — _or_ "none — VI-level check"
   - Specs repo rev: <short HEAD>
   
   ### Declared status (Phase 2 — authoritative)
   - VI: <status>
   - Epic <KEY>: <status> — _or omit when VI-level_
   
   ### Artifact inventory (Phase 1)
   [present ✅ / absent ❌ / authored, not handed off ⚠ (branch/PR named) per artifact, one line each]
   
   ### Verdict
   [SUPPORTED | PARTIAL | NOT-SUPPORTED]
   
   ### Requirement coverage
   [N/M covered (P%); list each ❌ gap requirement ID] — _or_ "derived (coarse) — VI had no structured requirements"
   
   ### Findings
   [readiness-reviewer's Findings section, by dimension]
   
   ### Repo availability
   [Phase 3(c) result]
   
   ### ARD conformance
   [verdict + any `- ARD deviation:` lines the reviewer found] — _omit this whole section when Phase 2.5 status was none_
   
   ### Assumptions & limitations
   - Coverage map (Phase 3a) is an ID-grep, not semantic matching — the reviewer's full read may find
     coverage the grep missed, and vice versa.
   - [any other caveats — e.g. non-main/dirty specs checkout override]
   
   ### `_readiness.md`
   Written (overwritten) to: <absolute path>.
   
   ### Phase handoff
   [the step-3 §4.1 outcome line — e.g. "Phase handoff: ready/<KEY>-<slug> pushed — PR #<n> open (<url>).
   The next phase runs once it is merged." or the declined/gate-failed/nothing-to-commit variant]
   
   ### Next step
   [Per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/next-phase-offer.md` — guidance only, never auto-invoked. SUPPORTED →
   `implement: <VI> [<Epic>]` (same lane, no handoff). PARTIAL / NOT-SUPPORTED → resolve the named gaps above and update the
   Jira status to match reality, then re-run `ready: <VI> [<Epic>]`.]
   
   ### Context hygiene
   The resume pointer is written in the terminal follow-up phase (Phase 7), per
   `session-hygiene.md` §1, recording the readiness verdict as a carry-forward line. Then:
   
   - **SUPPORTED → `implement: <VI> [<Epic>]` (still Dev)?** → run **`/compact`** — context stays relevant.
   - **PARTIAL / NOT-SUPPORTED → resolving the gaps yourself now?** → **`/compact`**.
   - Consider **`/rename <VI-ID>-<slug>-dev`** to relocate this session later.
   
   Guidance only — see `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md`.
   

ready: NEVER writes to Jira, jira-products/, or the vault. It commits and hands off _readiness.md only through step 3's phase-handoff.md §4.3 consent choice — declining leaves it uncommitted; that handoff is independent of the terminal commit-artifacts step, which stages ONLY the run's bounded session-artifact paths (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.1) and never _readiness.md itself. Phases 6–7 below append their own short trailing notices after this report; they do not reopen or restate it.

Phase 6 — Post-run maintenance & feedback

Mirrors epics.md Phase 8, run as a genuinely terminal phase (unlike epics:, where maintenance feeds the still-to-come final report — here the readiness report already printed in Phase 5).

a. project_root = $SPECS_PATH for this run (where _readiness.md was written). Run git diff --stat from project_root if it is a git repo (it should be, per Phase 0 step 3) — just to report what changed. Phase 5 step 3 already ran the only commit _readiness.md ever gets, so this diff is clean if the user consented there and still shows _readiness.md if they declined; this phase itself commits nothing beyond the bounded artifact paths the terminal commit-artifacts step stages (~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.1). b. Compose a change summary block:

Implementation: [one-sentence: readiness check for <VI> [<Epic>], verdict SUPPORTED | PARTIAL | NOT-SUPPORTED]
Change type: docs
Classification: MODERATE
Files changed:
<absolute path of _readiness.md>
Notable additions/removals: _readiness.md (over)written with the Phase 4 verdict
Readiness verdict: [SUPPORTED | PARTIAL | NOT-SUPPORTED]

Then spawn all four maintenance agents in a single task message. They are independent and run concurrently.

Agent 1 — Documentation (general-purpose):

"Post-run documentation review. Change summary: [paste change summary block]

The project root is the specs repo ($SPECS_PATH). Look only for internal documentation files that reference readiness gates or the dev-workflows/ per-VI artifact area (e.g. a dev-workflows/README.md index). Determine if any such file needs updating. Skip if: no such file exists or readiness runs aren't indexed centrally. If an update is warranted: apply minimal edits. Return: file updated and what changed, OR 'no update required (reason)'."

Agent 2 — Knowledge base (general-purpose):

"Post-run knowledge review. Change summary: [paste change summary block]

Check ~/.copilot/memory/ (global) and .copilot/memory/ (project-level) for existing knowledge files. Determine if a new knowledge entry is warranted — look for: recurring readiness-gate gaps for this VI-family, non-obvious status/artifact mismatches uncovered, repo-availability surprises. If YES: append to the most appropriate existing file (never create a new file if an existing one fits) using this format:

[Short title]

• Context: what problem/situation triggered this
• Insight: the learned rule, pattern, or gotcha
• When it applies: conditions under which this matters
• Date: YYYY-MM-DD
• Ref: [first 60 chars of the Jira key + VI summary] Return: file updated/created and summary of entry, OR 'no update required'."

Agent 3 — Instructions (general-purpose):

"Post-run instructions review. Change summary: [paste change summary block]

Check .github/copilot-instructions.md in the project root and ~/.copilot/copilot-instructions.md (global). Determine if any readiness-gate rules, guidance, or guardrails are missing because of what this run revealed. Skip if: the run followed existing conventions with no surprises. If YES: apply minimal, additive, scoped changes only. Return: what was changed and why, OR 'no update required'."

Agent 4 — Session maintenance (dev-workflows:impl-maintenance):

"Analyse this session and return a Lessons Learned report.

Session handoff:

• Command run: ready:
• What was done: [one-paragraph summary of the readiness check performed]
• Key events: [status mismatches found, missing repos, non-main/dirty specs checkout override, or 'none']
• Workarounds used: [manual steps not automated by the workflow — or 'none']
• Review verdict: [SUPPORTED | PARTIAL | NOT-SUPPORTED]
• Test result: N/A (no tests in ready: — read-only artifact gate)
• Project root: [resolved project_root]"

Persist plugin feedback (automatic). After Agent 4 (impl-maintenance) returns, project its plugin-facing slice into the specs repo by citing ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md and calling its emit-auto entry point (§6). Pass Agent 4's Lessons Learned report, command: ready:, the run's jira_key and source, and plugin_version (read from ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/.plugin/plugin.json). emit-auto renders only the report's Command workflow improvements, New agents / skills, and plugin Reference docs sections plus the Key observations that triggered them (§4 plugin-facing predicate) — never target-project copilot-instructions.md/hook advice — as origin: auto entries, dedupes by stable id (§3), resolves the target via the §2 specs-first ladder, and writes silently.

Emit this phase's own short output:

### Post-run maintenance (Phase 6)
- Documentation (Agent 1): [result]
- Knowledge base (Agent 2): [result]
- Instructions (Agent 3): [result]
- Session learnings (Agent 4): [top suggestions, or "no suggestions — routine session"]
- Feedback persisted: [path, or "no plugin-facing signal — nothing persisted"]

ADDITIVE — this phase NEVER fails the run and NEVER commits its own output (still true — it writes only the maintenance/feedback artifacts, which the terminal commit-artifacts step in Phase 7 commits, per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §4; the only commit this run makes before Phase 7 is Phase 5 step 3's _readiness.md handoff, which is unrelated), and NEVER writes into jira-products/, jira_export_root, or the current working directory.

Phase 7 — Emit follow-up tasks

Terminal phase — runs AFTER the Phase 5 report is composed; NEVER interrupts an earlier phase. Persist the run's manual-step / out-of-scope follow-ups by citing ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/followup-emission.md and executing its steps inline.

1. Collect the qualifying follow-ups: the named readiness gaps from Phase 4's Findings that a PARTIAL / NOT-SUPPORTED verdict surfaced (each gap → one follow-up: "resolve , see _readiness.md"), plus a standing "update the Jira status to match the artifacts (or vice versa)" reminder whenever the verdict is not a clean SUPPORTED at the declared status.
2. Filter them with the reference's §6 qualifying predicate — a SUPPORTED run with no gaps qualifies nothing; this phase is then a silent no-op (byte-identical to a run without it).
3. Resolve the write target via the §4 ladder using jira_key and source; render + place tasks and verbose notes per §1–§3; dedupe per §5.
4. Preview + confirm per §7 (approve-all | select | cancel), then write.

Emit this phase's own short output:

### Follow-up tasks (Phase 7)
[N follow-ups written to <target>, OR "none — verdict SUPPORTED with a clean coverage roll-up"]

ADDITIVE — the follow-ups also remain in the Phase 5 report's Findings/coverage sections. This phase NEVER fails the run and NEVER commits its own output (still true — it only writes follow-up files, which the terminal commit-artifacts step at the end of this phase commits, per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §4; unrelated to Phase 5 step 3's _readiness.md handoff, the only commit this run makes before this phase), and NEVER writes into jira-products/, jira_export_root, or the current working directory.

Then write the resume pointer. Cite ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md §1 and write/overwrite <VI-dir>/dev-workflows/resume.md now — after the follow-up entries above, so the pointer reflects the completed run, and before the commit step below, so it is included in it. Redact per §1. Silent; the printed ### Context hygiene guidance already appeared in the Phase 5 report.

Then commit session artifacts (terminal). Cite ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md and execute its commit-artifacts entry point (§4) inline — the LAST action of the run. It stages ONLY the §2.1 bounded artifact paths inside $SPECS_PATH, commits <KEY> Add dev-workflows session artifacts (ready:), and pushes per §4 step 5. It NEVER touches a code/docs repo, the vault, or the current working directory; NEVER force-pushes; NEVER fails the run; and skips entirely when the run carries specs_git: blocked (§3.3 G0), re-emitting that notice. Because the Phase 5 report was composed before this phase, print its §6 outcome line here, as the run's last output — prefixed Specs repo:, with any guard notice repeated in full.

ADDITIVE — this phase itself NEVER fails the run and touches neither _readiness.md's commit nor its branch (whichever of those happened, happened earlier, in Phase 5 step 3, behind the §4.3 consent choice — ready/<KEY>-<slug> is the only branch ready: ever creates, and this terminal step neither creates it nor undoes it; it only commits the bounded session-artifact paths in $SPECS_PATH onto whatever branch Phase 5 left checked out), and NEVER writes to Jira or into jira-products/, jira_export_root, or the current working directory; no user name is ever written.

Invariants (always enforced)

• NEVER set or write Jira status — status is read-only input (Phase 2), never output
• NEVER write inside jira-products/ or the vault
• Branches only via the Phase 5 step 3 phase-handoff.md §4.3 consent choice, creating ready/<KEY>-<slug> — specs-preflight itself still creates no branch, a hard invariant: it only switches $SPECS_PATH between branches that already exist, and only plugin-created ones, per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md §2.2
• NEVER auto-commit _readiness.md — the commit is offered at that same §4.3 choice, never automatic; declining leaves _readiness.md uncommitted (still true — _readiness.md is the deliverable, an OTHER path the terminal commit-artifacts step never stages, §2.1)
• NEVER stop on a require-on-main or ard-resolution.md outcome for a gated ARD/spec/design (Phase 1 step 2, Phase 2.5) — ready: is the one caller these gates never stop: an artifact off <default> becomes a readiness finding ("authored, not handed off") that caps the verdict at PARTIAL; an absent artifact is recorded as missing in the coverage roll-up, exactly as before this feature
• ALWAYS run specs-preflight at Phase 0 and commit-artifacts as the run's last action (per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md) — bounded to $SPECS_PATH's artifact paths (§2.1) and to plugin-created branches (§2.2), always git -C "$SPECS_PATH" and never a cd (§1 rule 1), never force-pushing, and never failing the run
• doc-only — repo check is presence-only, no scanning (Phase 3c; never dispatches code-scanner)
• ALWAYS end with a ### Next step per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/next-phase-offer.md — guidance only, never auto-invoked
• ALWAYS emit-block (per ~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md) before escalating a halt caused by a plugin / skill / command / reference gap — a readiness-reviewer run that cannot get a verdict because the plugin lacked something it needed still records it. NEVER for the reviewer's own PARTIAL/NOT-SUPPORTED verdict (a finding about the work, not the plugin) or an environment/user halt (specs-repo dirty/non-main, jira-not-found, cancellation)
• ALWAYS resolve input via the shared Jira-input front-end (Phase 0) and reject mode: direct
• ALWAYS require $SPECS_PATH — stop naming it explicitly if unset (like design:)
• ALWAYS read artifacts from the specs repo's clean main — never a branch
• ALWAYS pass the Phase 2 declared status to readiness-reviewer exactly as read — never inferred, never re-derived
• ALWAYS resolve the model_routing block at Phase 1.5 and pin jira-reader to the §2.1 detection chain; readiness-reviewer is pinned by the caller to the §2 Opus chain; coordination + the Phase 3 deterministic skeleton run on current_model
• ALWAYS invoke readiness-reviewer before Phase 5 — no verdict is written or reported without it
• ALWAYS pass Change type: docs in the Phase 6 change summary block
• ALWAYS pass Command run: ready: in the Phase 6 Agent 4 session handoff
• ALWAYS spawn Phase 6's four maintenance agents in a single message — never sequentially
• ALWAYS use choices arrays for decision points; last choice is always "Other… (describe)"
• ARD steps (Phase 2.5, the reviewer's applicable_ard, the report's ARD-co

…(truncated)