project-workflow 0.2.0__py3-none-any.whl

project_workflow/prompts/Clarify.prompt.md

@@ -0,0 +1,137 @@
+---
+name: project.clarify
+description: Ask the minimum set of questions needed to remove ambiguity before planning/implementing.
+argument-hint: topic="..." taskId=TASK-330-Superuser
+agent: agent
+---
+
+Use this prompt when requirements, a generated plan, or repo constraints are unclear. It may run
+before owner approval to resolve product questions or immediately after Planner as an autonomous
+consistency pass.
+
+Reference docs:
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- Project outcomes: [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- Canonical task docs:
+  - `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` (must include `## User Story` at the top)
+  - `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` (source of truth for agreed outcomes/expectations)
+
+Inputs:
+
+- Task (optional): `${input:taskId:TASK-000-Example}`
+- Topic: `${input:topic:What needs clarifying?}`
+
+Output (Markdown):
+
+Workflow (must follow):
+
+1. Read context first
+
+- Read the `## User Story` section from `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`.
+- Read `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` (if it exists) and treat it as the source of truth for what’s already been agreed.
+- Cross-check against repo constraints in `../copilot-instructions.md`, repo-specific workflow guidance in `../../.project-workflow/guidance.md`, and project outcomes in `../../.project-workflow/CONSTITUTION.md`.
+
+Guardrail:
+
+- If `IMPLEMENTATION.md` does not have a usable `## User Story` yet, STOP and instruct the user to run the `project.requirements` prompt first. Do not invent clarifying questions without a user story anchor.
+
+2. Proactively log questions BEFORE asking the user
+
+- Identify every ambiguity/conflict that would change scope, safety, security, billing attribution, data correctness, or user-visible behavior.
+- For each ambiguity, write it into `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` as a numbered open question (e.g. `Q1`, `Q2`, …) with 2–4 options labeled `A/B/C/...`.
+- Each question must be explicitly anchored to the current user story and include a short “why it matters”.
+
+3. Work through questions item-by-item until resolved
+
+- Ask the user ONE unresolved question per response (default) so decisions are made sequentially.
+  - If there are many low-risk questions and the user explicitly asks for batching, you may ask up to 2–3 at a time.
+- After the user answers:
+  - Update `REQUIREMENTS.md` immediately: record the decision in a decisions log, mark the question resolved, and remove/strike it from open questions.
+  - Preserve existing acceptance criteria IDs (`AC1`, `AC2`, etc.). Do not renumber ACs unless the user explicitly approves that requirements change.
+  - Keep `IMPLEMENTATION.md` in sync with the confirmed decisions.
+  - Keep the `IMPLEMENTATION.md` task list in sync:
+    - If `IMPLEMENTATION.md` has a `## Tasks` or `## Task List` section, update it to reflect the confirmed decisions and preserve AC-to-task mappings.
+    - If `IMPLEMENTATION.md` does NOT yet have a `## Tasks` section, you MAY add a minimal `## Tasks` section limited to tracking clarification work (e.g., “Resolve Q1…Qn”). Do NOT invent a full implementation plan here — the `project.planner` prompt owns full task planning.
+- Repeat until `REQUIREMENTS.md` has no unresolved open questions (or the user explicitly accepts remaining items as risks and that acceptance is recorded).
+
+## User Story (from IMPLEMENTATION.md)
+
+-
+
+## Conflicts / Ambiguities Found
+
+For each conflict/issue:
+
+- Explain what is conflicting and why it matters.
+- Propose 2–4 reasonable options (labeled A/B/C/…); each option should be actionable, realistic for this repo, and include tradeoffs.
+- Ask the user to choose an option (or provide a different preference).
+
+Example format:
+
+### Issue 1: <short title>
+
+- Conflict: <what conflicts with what>
+- Why it matters: <risk / impact>
+- Options:
+  - A: <option> (pros/cons)
+  - B: <option> (pros/cons)
+  - C: <option> (pros/cons)
+- Question: Which option should we take?
+
+## Clarifying Questions
+
+### Product / UX
+
+-
+
+### Permissions / Security
+
+-
+
+### Data / DB / RLS
+
+-
+
+### Migration / Rollout
+
+-
+
+### Observability
+
+-
+
+## Decisions to Record in REQUIREMENTS.md
+
+Always ensure the questions exist in `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` BEFORE you ask them.
+
+If the user’s answers are present in the conversation context, document the decisions and chosen options immediately in `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` (including rationale/tradeoffs where relevant), and do not ask again.
+
+If the user’s answers are not present yet:
+
+- First, write/update `REQUIREMENTS.md` with the open questions (Q1/Q2/…) and their A/B/C options.
+- Then ask the user the next single unanswered question.
+
+Also keep the implementation tracker up to date:
+
+- After recording each decision in `REQUIREMENTS.md`, update `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` to keep BOTH:
+  - `## User Story` (and any decision-dependent notes) consistent with `REQUIREMENTS.md`, and
+  - `## Tasks` / `## Task List` consistent with the confirmed decisions, including AC-to-task mappings where a plan already exists.
+- Clarify may update an existing task list (or add a minimal “clarification tracking” task list), but must not generate a full multi-phase implementation plan — Planner owns full task planning.
+
+-
+
+## Suggested Defaults (if the user doesn’t care)
+
+-
+
+Guardrail: don't start implementation until unresolved questions are cleared (or explicitly accepted as risks) and decisions are recorded in `REQUIREMENTS.md`.
+
+Post-plan clarification guardrail: fix implementation-detail inconsistencies inside the approved
+envelope without another generic approval request. If resolution would change requirements, ACs,
+proof obligations, artifact identity, or scope materially, stop, update the proposed requirements,
+and return the changed envelope to the owner for review/re-approval. When no such drift remains,
+run `task ready`, move the task to `Ready`, and continue autonomously if implementation was
+authorized.

project_workflow/prompts/Constitution.prompt.md

@@ -0,0 +1,115 @@
+---
+name: project.constitution
+description: Create or refine the project's outcome-focused constitution from a brief and repo context.
+argument-hint: projectBrief="..." context="..."
+agent: agent
+---
+
+Use this agent to establish or update the canonical project outcomes document at `/.project-workflow/CONSTITUTION.md`.
+
+Purpose:
+
+- Define **what success means** for this project in user/business terms.
+- Keep outcome guidance separate from implementation guidance.
+- Ensure technical workflow constraints live in `/.project-workflow/guidance.md` (or repo equivalent), not in the constitution.
+
+Inputs:
+
+- Project brief: `${input:projectBrief:One-paragraph description of the product and intended users}`
+- Optional context: `${input:context:Roadmap links, docs, constraints, notes}`
+
+Reference docs to read first (if present):
+
+- `README.md`
+- `/.project-workflow/TRACKER.md`
+- `/.project-workflow/guidance.md`
+- Existing `/.project-workflow/CONSTITUTION.md`
+- `/.github/copilot-instructions.md`
+- Common product docs in repo root (`docs/**`, `specs/**`, `product/**`, `roadmap/**`)
+
+Rules:
+
+- `CONSTITUTION.md` is **not** a technical implementation doc.
+- Do not put framework choices, folder structure, lint rules, or coding conventions in `CONSTITUTION.md`.
+- Keep the constitution stable and outcome-focused; avoid sprint-level details.
+- If repo context conflicts with user brief, ask clarifying questions before finalizing.
+
+Workflow (must follow):
+
+1. Discovery + scan
+
+- Read the files above and summarize current product intent in 5–10 bullets.
+- If `projectBrief` is missing or too vague, ask the minimum questions needed to proceed.
+
+2. Draft or refine constitution
+
+- Create/update `/.project-workflow/CONSTITUTION.md` using the structure below.
+- Preserve useful existing content; improve clarity and remove technical directives.
+
+3. Validate boundaries
+
+- Ensure each section is outcome-oriented and testable at a product level.
+- Remove technical implementation instructions from constitution and point those to copilot instructions.
+
+4. Copilot instructions fallback
+
+- If `/.project-workflow/guidance.md` does not exist, explicitly offer to create it.
+- If the user accepts, create a minimal technical guidance file with repo conventions/tooling constraints.
+- If the user declines, continue and note that technical guidance is currently missing.
+
+Required output artifact:
+
+- Write/update `/.project-workflow/CONSTITUTION.md`.
+
+Use this constitution template (adapt content to project):
+
+```md
+# Constitution
+
+## Mission
+
+- <What this project exists to achieve>
+
+## Target Users
+
+- <Primary users>
+- <Secondary users>
+
+## Core Outcomes
+
+- <Outcome 1: user/business result>
+- <Outcome 2>
+- <Outcome 3>
+
+## Non-Goals
+
+- <Explicitly out of scope>
+
+## Product Principles
+
+- <Principle 1>
+- <Principle 2>
+- <Principle 3>
+
+## Success Signals
+
+- <How we know outcomes are being achieved>
+
+## Decision Filters
+
+- <How to choose between competing options>
+
+## Assumptions & Risks
+
+- <High-level assumptions and product risks>
+
+## Change Log
+
+- <YYYY-MM-DD>: <summary of constitution change>
+```
+
+Final response requirements:
+
+- Summarize what changed in `CONSTITUTION.md`.
+- Call out any unresolved product questions.
+- If workflow guidance is missing, include: “I can create `/.project-workflow/guidance.md` now — proceed?”

project_workflow/prompts/Delegate.prompt.md

@@ -0,0 +1,48 @@
+---
+name: project.delegate
+description: Coordinate delegated work items by routing each item through project.implement.
+argument-hint: taskId=TASK-330-Superuser workItems="1,2,3" mode=sequential dependencies="{}"
+agent: agent
+---
+
+Use this prompt to coordinate delegated execution for task work items.
+
+Read `/.project-workflow/guidance.md` if present before changing workflow state.
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Work items: `${input:workItems:1,2,3}`
+- Mode: `${input:mode:sequential|parallel}`
+- Dependencies: `${input:dependencies:{"2":["1"]}}`
+- Worker limit: `${input:workers:4}`
+
+Defaults:
+
+- If `mode` is omitted, use `sequential`.
+- If `mode` is `parallel` and `workers` is omitted, use `4`.
+
+Execution contract:
+
+- For each delegated work item, invoke `project.implement` as the execution path.
+- After delegated implementation reaches `Testing`, route the completed set through `project.qa-review`; after completion, route through `project.retro`.
+- Accept the provided work-item list and selected mode as the execution plan input.
+- In `sequential` mode, execute exactly one work item at a time, in listed order.
+- In `sequential` mode, initialize each item as `not started`, set current item to `in progress`, then mark it `completed` or `failed` before starting the next item.
+- Emit a completion status line for each item before moving to the next item.
+- Use the explicit dependency map provided in `dependencies` as the only prerequisite source.
+- Before starting any item in `parallel` mode, validate dependency input strictly: reject unknown item IDs, self-dependencies, and cyclic dependencies.
+- On dependency-validation failure, reject immediately and start no work items.
+- In `parallel` mode, launch only eligible items whose prerequisites are completed.
+- In `parallel` mode, allow independent eligible items to run concurrently up to the worker limit.
+- Keep dependent items in `not started` until all prerequisites complete.
+- On first work-item failure, enter fail-fast mode and stop launching any new pending items.
+- Allow already `in progress` items to finish and report their terminal states.
+- Mark any items that never started because of fail-fast as `halted` in run output.
+- Final summary must clearly include overall result, failed item(s), failure cause, and halted item(s).
+- End with a final aggregate summary that includes overall result and per-item terminal status.
+- Preserve existing `project.*` agent behavior; do not rename or replace existing commands.
+
+Scope note:
+
+- This prompt defines the delegate entrypoint and routing contract only.

project_workflow/prompts/Epic.prompt.md

@@ -0,0 +1,210 @@
+---
+name: project.epic
+description: Manage epic lifecycle (init, approval, contract, decomposition, amendment, adoption, scaffold child, status, audit, closeout).
+argument-hint: action=setup|init|approve-requirements|lifecycle|decompose|amend|approve|scaffold-child|status|audit|closeout title="..." epicId=EPIC-001 id=TASK-001
+agent: agent
+---
+
+Use this prompt to run epic workflow operations through the local workflow CLI.
+
+Read `/.project-workflow/guidance.md` if present before changing workflow state.
+
+Inputs:
+
+- Action: `${input:action:setup|init|ready|approve-requirements|lifecycle|decompose|amend|adopt|approve|scaffold-child|ready-child|status|audit|closeout}`
+- Epic title (required for `init`): `${input:title:}`
+- Epic ID (required for all non-init actions): `${input:epicId:EPIC-001}`
+- Row ID (required for `approve` and `scaffold-child`): `${input:id:TASK-014}`
+- Status target (required for `status`): `${input:status:Testing|Review|Complete}`
+ - Epic lifecycle target (required for `lifecycle`): `${input:lifecycleStatus:Analysing|Ready|In Progress|Closeout|Complete}`
+- Decompose limit (optional, default 5): `${input:limit:5}`
+- Decompose type (optional, default Task): `${input:type:Task}`
+- Create branch for scaffold-child (optional): `${input:createBranch:no}`
+- Epic branch for scaffold-child branch creation (optional, default epic/main): `${input:epicBranch:epic/main}`
+- Branch prefix for scaffold-child branch creation (optional, default feature/): `${input:branchPrefix:feature/}`
+
+Defaults and inference:
+
+- If action is omitted, infer from provided inputs:
+  - `title` only -> `setup`
+  - `epicId` + no `id` -> `ready` then `decompose`
+  - `epicId` + `id` + intent to approve -> `approve`
+  - `epicId` + `id` + intent to scaffold -> `scaffold-child`
+  - `epicId` + `id` + lifecycle intent -> `status`
+  - `epicId` + intent to audit -> `audit`
+  - `epicId` + intent to close -> `closeout`
+- If inference is unclear, ask one clarifying question and stop.
+
+Required preflight for `init`:
+
+- Never run `init` with an implicit/default title.
+- If `title` is missing, empty, or still a placeholder/example value, ask exactly one clarifying question for the epic title and stop.
+- If action is `init` and title is provided, echo the exact title back before executing.
+
+Guided setup mode (`action=setup`):
+
+- Use this as the default for new epics in chat.
+- Drive the complete lifecycle so users do not miss gates:
+  1. Initialize epic.
+  2. Verify epic requirements are ready for decomposition.
+  3. Ask the owner to confirm the drafted requirements, acceptance criteria, and authority envelope once.
+  4. Record that approval with `epic approve-requirements`.
+  5. Confirm `EPIC-CONTRACT.md` has concrete sources of truth, invalid substitutes, invariants, artifact targets, and proof owners.
+  6. Decompose into Proposed rows and `DECOMPOSITION.md`.
+  7. Approve/scaffold matching rows inside the approved decomposition plan as needed; do not ask for repeated owner approval unless the row is outside the plan or changes material scope.
+- Ask at most one clarifying question at a time.
+- After each completed step, explicitly state the next required step and offer to run it.
+
+Requirements readiness gate (before `decompose`):
+
+- Run `./.project-workflow/cli/workflow epic ready --epic-id <EPIC_ID>` before `decompose`.
+- Do not run `decompose` until epic `REQUIREMENTS.md` contains concrete, non-placeholder bullets under `## Requirements` and/or `## Acceptance Criteria`.
+- Acceptance criteria should use stable IDs (`AC1`, `AC2`, etc.). Preserve existing IDs; do not renumber them unless the user explicitly approves the requirements change.
+- If requirements are missing/skeletal, lead the user through filling them:
+  - Ask focused questions to capture intended outcomes and verifiable criteria.
+  - Update epic `REQUIREMENTS.md` with the provided answers.
+  - Re-check readiness, then continue.
+- If the user declines to provide requirements details, stop and explain that decomposition cannot proceed yet.
+
+Requirements interview flow (when requirements are missing/skeletal):
+
+- Ask exactly one question at a time and wait for the answer before continuing.
+- Offer two input modes: (a) step-by-step answers, or (b) one pasted requirements/PRD block.
+- If the user provides a large pasted block, treat it as preferred epic input (do not force short answers first).
+- Capture, then write answers into epic `REQUIREMENTS.md` using these prompts in order:
+  1. Goal: "What user/business outcome should this epic deliver?"
+  2. Scope boundaries: "What is explicitly out of scope for this epic?"
+  3. Requirements bullets: "List 3-7 outcome-focused requirements as bullets."
+  4. Acceptance bullets: "List 3-7 verifiable acceptance criteria as bullets."
+  5. Open questions: "What unknowns still need decisions?"
+- Normalize answers into concise bullet points and replace placeholder lines like `- ____` in matching sections.
+- Prefix acceptance criteria with stable IDs when writing them, for example `- AC1: <verifiable outcome>`.
+- For pasted blocks, extract and map content into sections:
+  - Product outcome/business goal -> `## Goal`
+  - Platform/UX behavior statements -> `## Requirements (Outcome-Focused)`
+  - Testable "As a user..." or acceptance statements -> `## Acceptance Criteria (Verifiable)`
+  - Unknowns/dependencies/API notes -> `## Open Questions (Answer Needed)`
+- Keep source fidelity: preserve critical terms, links, and proper nouns from the pasted text.
+- If the pasted block includes desktop/mobile/backend variants, keep those distinctions explicit in the normalized bullets.
+- Read back the drafted `## Requirements` and `## Acceptance Criteria` bullets and ask for confirmation before decomposition.
+- Only proceed after the owner confirms the drafted requirements and acceptance criteria, then record that confirmation with `epic approve-requirements`.
+- If requirements, acceptance criteria, `EPIC-CONTRACT.md`, or `DECOMPOSITION.md` materially change after approval, re-run the relevant gate and seek owner confirmation only for the changed authority envelope.
+
+Readiness minimums for decomposition:
+
+- `## Requirements` has at least 3 non-placeholder bullet items, or `## Acceptance Criteria` has at least 3 non-placeholder bullet items.
+- At least one acceptance bullet is objectively testable (contains a measurable or observable outcome).
+- `EPIC-CONTRACT.md` has non-placeholder sources of truth, invalid substitutes, invariants, artifact targets, and proof owners before decomposition or child lifecycle movement.
+
+Execution:
+
+- Run from repo root using the local workflow script:
+
+`./.project-workflow/cli/workflow epic <subcommand> ...`
+
+- Action mappings:
+  - `setup` (orchestrated flow):
+
+`./.project-workflow/cli/workflow epic init --title "<TITLE>"`
+
+`./.project-workflow/cli/workflow epic approve-requirements --epic-id <EPIC_ID> --approved-by "<OWNER>" --source "<OWNER CONFIRMATION SOURCE>"`
+
+`./.project-workflow/cli/workflow epic decompose --epic-id <EPIC_ID> --limit <LIMIT> --type <TYPE>`
+
+When `.project-workflow/config.json` defines multiple task namespaces,
+decomposition classifies each proposed child row with `prefix_guidance` by
+default. Use `--prefix <PREFIX>` only when intentionally forcing every proposed
+child row into one configured namespace.
+
+`./.project-workflow/cli/workflow epic approve --epic-id <EPIC_ID> --id <ROW_ID>` (one or more user-selected rows)
+
+`./.project-workflow/cli/workflow epic scaffold-child --epic-id <EPIC_ID> --id <ROW_ID> [--create-branch --epic-branch <EPIC_BRANCH> --branch-prefix <PREFIX>]` (optional)
+
+- `init`:
+
+`./.project-workflow/cli/workflow epic init --title "<TITLE>"`
+
+- `decompose`:
+
+`./.project-workflow/cli/workflow epic decompose --epic-id <EPIC_ID> --limit <LIMIT> --type <TYPE>`
+
+- `approve-requirements`:
+
+`./.project-workflow/cli/workflow epic approve-requirements --epic-id <EPIC_ID> --approved-by "<OWNER>" --source "<OWNER CONFIRMATION SOURCE>"`
+
+- `amend`:
+
+`./.project-workflow/cli/workflow epic amend --epic-id <EPIC_ID> --id <ROW_ID> --title "<TITLE>" --parent-acs "<AC1, AC2>" --reason "<OWNER-APPROVED REASON>"`
+
+- `adopt`:
+
+`./.project-workflow/cli/workflow epic adopt --epic-id <EPIC_ID> --approved-by "<OWNER>" --source "<ADOPTION SOURCE>"`
+
+- `ready`:
+
+`./.project-workflow/cli/workflow epic ready --epic-id <EPIC_ID>`
+
+- `lifecycle`:
+
+`./.project-workflow/cli/workflow epic lifecycle --epic-id <EPIC_ID> --to <LIFECYCLE_STATUS>`
+
+- `approve`:
+
+`./.project-workflow/cli/workflow epic approve --epic-id <EPIC_ID> --id <ROW_ID>`
+
+- `scaffold-child` without branch:
+
+`./.project-workflow/cli/workflow epic scaffold-child --epic-id <EPIC_ID> --id <ROW_ID>`
+
+- `scaffold-child` with branch:
+
+`./.project-workflow/cli/workflow epic scaffold-child --epic-id <EPIC_ID> --id <ROW_ID> --create-branch --epic-branch <EPIC_BRANCH> --branch-prefix <PREFIX>`
+
+- `ready-child`:
+
+`./.project-workflow/cli/workflow epic ready-child --epic-id <EPIC_ID> --id <ROW_ID>`
+
+- `status`:
+
+`./.project-workflow/cli/workflow epic status --epic-id <EPIC_ID> --id <ROW_ID> --to <STATUS>`
+
+- `audit`:
+
+`./.project-workflow/cli/workflow epic audit --epic-id <EPIC_ID>`
+
+- `closeout`:
+
+`./.project-workflow/cli/workflow epic closeout --epic-id <EPIC_ID> [--complete]`
+
+Constraints to enforce in responses:
+
+- Requirements/AC approval is an authority envelope, not a recurring ceremony. Ask the owner to confirm requirements and ACs once before decomposition or implementation; after that, use gates to detect drift and ask again only for material changes, amendments, deviations, artifact identity changes, proof-obligation changes, or deferrals.
+- New/adopted epics require non-placeholder `EPIC-CONTRACT.md` before decomposition, child approval/scaffolding, or `In Progress`.
+- `DECOMPOSITION.md` is the child-row authority source. Matching rows inside it may be approved/scaffolded by the agent without repeated owner approval; rows outside it require `epic amend`.
+- For pre-existing epics, use `epic adopt`; inferred legacy evidence is not trusted for closeout until refreshed.
+- Proof recipes triggered by requirements, ACs, contracts, child charters, or material claims require child-local `EVIDENCE.json`. QA prose, code review, tests, build output, surrogate artifacts, and wrong target/source pairs are invalid substitutes where the recipe says so.
+- Visual/reference-fidelity work requires calibration before implementation and delivered-artifact comparison before Review/Complete.
+- Decomposition is proposal-first: it writes Proposed rows and does not scaffold child folders.
+- `ACCEPTANCE-MAP.md` is the in-progress parent AC coverage view. It is created on `epic init` and refreshed by epic lifecycle commands from requirements, tracker rows, deferrals, and child evidence.
+- Proposed child rows should preserve source AC IDs in the epic tracker `Parent ACs` field when they come from numbered acceptance criteria. Legacy trackers may still carry coverage in `Notes` as `Covers AC1, AC3`.
+- Proposed child rows should preserve configured task prefixes such as `UI`, `MCP`, `DEV`, or `WF`, and their `Notes` should include prefix classification rationale.
+- Scaffolded epic child tasks must carry parent AC coverage and parent AC evidence sections forward into their docs. Their `IMPLEMENTATION.md` planning table must map each row to child AC IDs while keeping the parent AC mapping visible.
+- The global tracker summarizes epic rows; the epic tracker owns child rows. Proposed child rows must stay in the epic tracker and must not be added to the global tracker.
+- `epic audit` writes `ACCEPTANCE-AUDIT.md` with parent AC coverage, child evidence, deferrals, and verdicts. The audit is the closeout evidence artifact; `ACCEPTANCE-MAP.md` is the working coverage map.
+- `epic closeout` must block if any parent AC is unmapped, lacks evidence, lacks a QA pass verdict, lacks an approved deferral with follow-up, or if `RETRO.md` is missing/incomplete.
+- Before closeout, ensure `RETRO.md` records lessons, follow-up tasks, deferrals, and missed in-scope work. Use explicit `None.` entries when a section has nothing to report.
+- `epic status --to Complete` must block unless the child row is in `Review` and its docs contain QA/code-review evidence plus parent AC evidence for its assigned parent ACs.
+- `epic ready-child` must pass before implementation/testing for an epic child; if it fails, remediate missing child requirements, planning, parent AC coverage, or owner decisions before coding.
+- `epic lifecycle` updates the global epic row through `Analysing`, `Ready`, `In Progress`, and `Closeout`. `Ready`, `In Progress`, and `Closeout` are gated; `Complete` remains owned by `epic closeout --complete`.
+- Approval gate: only Approved rows may be scaffolded.
+- Child task IDs remain globally unique within their configured prefix namespaces and are managed by workflow behavior.
+- If branch creation is requested for `scaffold-child`, the epic branch must already exist; no fallback branch is allowed.
+- In setup mode, do not skip required gates even if the user asks for later steps first; explain what is missing, satisfy the gate, then continue.
+
+Output to user:
+
+- Report the exact command run (for setup mode, report each command in order).
+- Summarize resulting epic/task ID, files/folders created, tracker updates, and branch result (if any).
+- Run `./.project-workflow/cli/workflow doctor` after epic tracker or child scaffold changes and report any warnings or errors.
+- If command fails, return the error and the next remediation step from the error message.
+- In setup mode, also include a short checklist of completed steps and the single next recommended action.

project_workflow/prompts/Fix.prompt.md

@@ -0,0 +1,58 @@
+---
+name: project.fix
+description: Route and manage a bounded post-completion correction as a lightweight Fix.
+argument-hint: title="..." relatedWork="TASK-001 or Not identified"
+agent: agent
+---
+
+# Fix
+
+Use a Fix for one bounded correction against a delivered or accepted baseline. A Fix is a
+lightweight work-item subtype in the same `.project-workflow/tasks/` directory and global
+`TRACKER.md` as tasks and epics; it is not a separate tracking system.
+
+## Route before scaffolding
+
+The agent owns the initial recommendation. The user's label is useful evidence but is not
+binding.
+
+- Keep an in-scope correction inside an active task or epic child.
+- Use a Fix for one bounded defect, regression, change request, or incident against delivered
+  or accepted behavior.
+- Use a Task when the request creates a new outcome, requires material product decisions or
+  discovery, or contains multiple independent work items.
+- Use an Epic when several coordinated outcomes or workstreams are required.
+- State the rationale and proceed for a clear, authorized case. Ask one focused question when
+  the classification is genuinely ambiguous or materially changes scope/authority.
+
+Do not reopen or rewrite completed work by default. Link it when identifiable. If finding the
+origin would require disproportionate archaeology, record `Not identified` plus the delivered
+baseline and report evidence.
+
+## Workflow
+
+1. Read `AGENTS.md` and `.project-workflow/guidance.md` when present.
+2. Scaffold with:
+
+   `./.project-workflow/cli/workflow fix init --title "<TITLE>"`
+
+3. Complete the single `FIX.md`: report/baseline, routing rationale, classification, risk,
+   related work, repo metadata, bounded plan, and verification plan.
+4. Classify `Type` as `Defect`, `Regression`, `Change Request`, or `Incident`. `Hotfix` is a
+   mode, not a fifth type.
+5. Run `fix triage --id <FIX-ID>` to validate the authority/risk packet and move to `Ready`.
+   A Hotfix may move directly from `To Do` to `In Progress` only after its emergency safety
+   packet is complete.
+6. Use `fix status` for `In Progress`, `Testing`, and `Review` transitions.
+7. Record verification/regression evidence and residual risk, then use `fix close` from Review.
+   Duplicate, rejected, or deferred reports may close directly to `N/A` with an explicit
+   disposition, decision, closer, and date instead of delivery evidence.
+8. If triage reveals a larger outcome, use `fix promote --to task|epic`; do not stretch the Fix
+   envelope.
+9. Run `doctor` after lifecycle changes.
+10. Do not require a retro for ordinary Fix closeout. Use retro or create an explicit follow-up
+    only when the Fix reveals a reusable workflow, process, quality, or prevention gap; never
+    reopen the completed originating work for that follow-up.
+
+For a workspace, use canonical component identities/paths for `Primary repo` and `Repos touched`
+and keep per-repo branch, PR, and evidence links in `FIX.md`. In a single repo, `.` is sufficient.