project-workflow 0.2.0__py3-none-any.whl

project_workflow/prompts/Implement.prompt.md

@@ -0,0 +1,99 @@
+---
+name: project.implement
+description: Implement a change with tracker status updates and an explicit validation plan.
+argument-hint: taskId=TASK-330-Superuser workItem="#2" scope="..."
+agent: agent
+---
+
+Use this prompt to make code changes.
+
+Reference docs:
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- Canonical tracker: `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`
+- Requirements source of truth: `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md`
+- E2E exception rules (only if editing `front-end/apps/e2e/**`): [../instructions/e2e.instructions.md](../instructions/e2e.instructions.md)
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Work item: `${input:workItem:#}`
+- Scope: `${input:scope:What are we changing?}`
+
+Defaults and inference:
+
+- If `taskId` is omitted, infer it from the current branch name when possible (e.g., `feature/TASK-482-...` -> `TASK-482`).
+- If `workItem` is omitted, infer the next work item with status `To do` in `/.project-workflow/TRACKER.md`; if none exist, default to `1`.
+- If `scope` is omitted, default to: `Implement work item ${input:workItem} per REQUIREMENTS.md`.
+- Only ask the user for missing inputs when inference is not possible.
+- After inference, restate the inferred work item and scope as a hard boundary and proceed without extra confirmation.
+- Do not implement, update, or mark status for any acceptance criteria outside the inferred `workItem`.
+- If any change would touch a different work item, stop and ask for explicit user instruction.
+
+Required workflow:
+
+- Before coding, run the relevant ready gate:
+  - standalone task: `./.project-workflow/cli/workflow task ready --id ${input:taskId}`
+  - epic child: `./.project-workflow/cli/workflow epic ready-child --epic-id <EPIC_ID> --id ${input:taskId}`
+- If the ready gate fails, remediate the listed requirements/planning/clarification/approval/evidence gaps or ask the owner only for the specific material decision required. Do not code from an unapproved or stale requirements/AC envelope.
+- If approval is missing or stale after requirements and ACs are ready, record the one owner-approved envelope with `task approve-requirements` or `epic approve-requirements` as applicable; do not treat the implementation request itself as approval.
+- For a new standalone task, require `Ready` after Planner, post-plan Clarify, and `task ready`.
+  `Plan Confirmed` is accepted only as a legacy-compatible predecessor.
+- Before coding, move the relevant row to `In Progress` with the workflow CLI. For unchanged work inside an approved envelope, do not ask for repeated owner approval.
+- After implementation, run the relevant status command to move the row to `Testing`.
+- Do not set it to `Complete`; completion is owned by `project.qa-review` after QA/code review passes and the user explicitly approves completion.
+
+Sequence enforcement:
+
+- Do NOT ask whether to “move on” or start the next work item until you have completed the Validation step for the current work item.
+- The next step after implementation is always Validation: run the most relevant automated checks (tests/typecheck/lint) and perform any required manual verification steps.
+- Only after you have (1) executed validation, (2) summarized results, and (3) set the work item/story to `Testing`, may you ask for next-step instructions.
+- The next lifecycle step after `Testing` is `project.qa-review`.
+
+Requirements guardrails:
+
+- Before coding, read `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` and treat it as the source of truth for outcomes and expectations.
+- If the task is an epic child, also read the parent epic `EPIC-CONTRACT.md`, `DECOMPOSITION.md`, `AMENDMENTS.md`, and the child `Child Charter`; those define inherited invariants, invalid substitutes, artifact targets, and proof ownership.
+- If `REQUIREMENTS.md` does not exist yet, stop and instruct the user to run the `project.requirements` prompt to create it.
+- If you discover a conflict between the current codebase constraints and `REQUIREMENTS.md` (or the `## User Story` in `IMPLEMENTATION.md`), stop and route to the `project.clarify` prompt; after the user chooses an option, ensure the decision is recorded in `REQUIREMENTS.md` before continuing.
+- Before coding, list the AC IDs in the inferred `workItem` and map each planned change to them. If any change does not map to an AC ID, do not proceed.
+- Before coding, cross-check the inferred work-item acceptance criteria against `REQUIREMENTS.md` and `IMPLEMENTATION.md`; if they conflict, stop and route to `project.clarify` and record the decision in `REQUIREMENTS.md`.
+- Before coding, identify any triggered proof recipes. Visual/reference-fidelity work must have calibration before implementation; runtime/deployment/source work must identify the exact target/source pair to prove. If the required recipe or artifact identity is missing, stop and fix the workflow artifacts before coding.
+
+User story tracker workflow:
+
+- `/.project-workflow/TRACKER.md` is part of the process and must be kept up-to-date.
+- Before coding, ensure there is a story row for `${input:taskId}` and move story `Status` to `In Progress` with the lifecycle command.
+- After implementation (when the work item is set to `Testing`), move story `Status` to `Testing` with the lifecycle command.
+- Do not set story `Status` to `Complete` from this prompt. Route to `project.qa-review` for completion approval.
+
+Implementation doc structure:
+
+- Ensure `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` begins with a `## User Story` section at the very top (with acceptance criteria). If it’s missing, add it.
+
+Output expectations:
+
+- Make the smallest safe change that satisfies the requirement.
+- Add or update tests when appropriate.
+- If requirements or material claims trigger a proof recipe, create or update child-local `EVIDENCE.json` with the structured claim record and evidence artifact path. Do not rely on implementation prose, tests, builds, or a surrogate artifact for recipe-specific proof.
+- Provide a short validation checklist (commands + manual steps) and call out any risks.
+- Tell the user that QA/code review is the next required step before completion.
+
+Validation execution requirement:
+
+- Do not merely propose validation commands—run them using available repo tools (e.g. `run_task`, `runTests`, terminal) and report the results.
+- If a broad check (e.g. whole-app typecheck) fails due to pre-existing issues unrelated to your change, do not stop early: still validate what you changed with the narrowest meaningful checks available (package-level typecheck, targeted tests, file-level checks) and clearly state the limitation.
+- After tracker or task-doc updates, run `./.project-workflow/cli/workflow doctor` when available and report any workflow-state warnings or errors.
+
+Validation alignment guardrail:
+
+- Use `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` as the validation checklist source of truth.
+- Explicitly map each `## Acceptance Criteria` item by AC ID (and any must-have `## Requirements`) to at least one validation step (automated test, manual verification, or query).
+- After running validation, report results in AC-by-AC form (`AC1 -> validation evidence/result`, `AC2 -> ...`) for the current work item.
+- If a requirement is not verifiable, stop and route to Clarify to make it testable and record the decision/update in `REQUIREMENTS.md`.
+
+E2E exception:
+
+- If you are working under `front-end/apps/e2e/**`, maintain the suite-local `implementation.md` per the E2E instructions.

project_workflow/prompts/Planner.prompt.md

@@ -0,0 +1,157 @@
+---
+name: project.planner
+description: Turn confirmed requirements into a phased implementation plan with validation steps.
+argument-hint: taskId=TASK-330-Superuser planFocus="..."
+agent: agent
+---
+
+Use this prompt to produce a safe, incremental plan after the owner has approved the
+requirements/acceptance-criteria envelope. The plan is agent-owned execution detail inside that
+authority; a second generic human plan-approval ceremony is not required by default.
+
+Reference docs:
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- Canonical task tracker location: `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`
+- Requirements source of truth: `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md`
+- Project outcomes: [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Plan focus: `${input:planFocus:What are we planning (feature/bug/area)?}`
+
+Output (Markdown, use headings exactly):
+
+## Goal
+
+-
+
+## Approach
+
+-
+
+## Phases
+
+### Phase 1
+
+- Changes:
+- Validation:
+- Tracker updates:
+
+### Phase 2
+
+- Changes:
+- Validation:
+- Tracker updates:
+
+## Task List (for IMPLEMENTATION.md)
+
+Produce (or update) an agile task list in `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`.
+
+Task quality rules (must follow):
+
+- Each task must be independently _testable_ and have a clear “done” outcome.
+- Tasks must be **outcome-based** (deliverable behavior or user-visible capability), not a checklist of implementation steps.
+- Each task must map to explicit **Acceptance Criteria IDs** from `REQUIREMENTS.md` or the `## Acceptance Criteria` section in `IMPLEMENTATION.md` (`AC1`, `AC2`, etc.).
+- Each task must include a **User Verification** step that a non-developer user can perform (or a precise dev command if it’s inherently technical).
+- Every acceptance criterion must be covered by at least one task row.
+- If a row claims visual/reference fidelity, external contract alignment, deployed/published artifact alignment, runtime target/source verification, or responsive/multi-context behavior, include the matching proof recipe and expected evidence artifact. Do not plan to satisfy those claims with code review, tests, build output, surrogate surfaces, or a related environment.
+- A task row may map to multiple ACs, for example `AC1, AC3: <criteria summary>`.
+- Avoid vague tasks like “ensure X works” or “verify Y” without stating what to check and how.
+- Prefer vertical slices when possible (deliver value incrementally), but don’t mix unrelated concerns in one task.
+
+If the repo uses a task table, include at least: `Title`, `Description`, `Acceptance Criteria`, `User Verification`, `Status`.
+
+Use this exact table format in `IMPLEMENTATION.md` (copy/paste):
+
+```md
+|  ID | Title     | Description                         | Acceptance Criteria               | User Verification            | Status |
+| --: | --------- | ----------------------------------- | --------------------------------- | ---------------------------- | ------ |
+|   1 | <Outcome> | <What changes for the user/system?> | AC1: <observable pass/fail criteria> | <steps a user can perform> | To Do  |
+```
+
+### Table formatting rules (critical)
+
+Markdown tables break if you put literal newlines inside a cell.
+
+- Every task row **must be a single physical line** (one `| ... | ... |` line per task).
+- For multiple bullets/steps inside a cell, use HTML line breaks: `<br>`.
+- Do not include raw `|` characters inside cell text. If you need them, escape as `\|`.
+- Do not wrap table rows across multiple lines.
+
+Good example (multi-line content in a cell, but still one row):
+
+```md
+| 1 | Example | Short description | AC1, AC2: First observable criterion.<br>AC3: Second observable criterion. | Step 1<br>Step 2 | To Do |
+```
+
+Example (good outcome-based tasks; replace with your task’s domain):
+
+```md
+|  ID | Title                                    | Description                                                                                                                     | Acceptance Criteria                                                                                                                    | User Verification                                                                                                                                                                            | Status |
+| --: | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+|   1 | Enforce server-side allocation on create | When creating an entity, server assigns allocation based on trusted server context, ignoring client-supplied allocation fields. | AC1: Create succeeds and persisted `team_id` equals the server-derived team.<br>AC2: Passing a different `team_id` has no effect. | In the app UI, create an entity under Team A and confirm it appears under Team A only.<br>(Dev) POST with a mismatched `team_id`; confirm response still allocates to Team A. | To Do |
+|   2 | Fail fast on required config missing | If a required env/config value is missing, the request fails with a stable error contract. | AC3: API responds with HTTP 500 and a stable error body when config is missing. | Temporarily remove the config in a test environment and confirm the API returns the documented error contract. | To Do |
+```
+
+Anti-examples (do NOT write tasks like this):
+
+- “Find where call creation happens”
+- “Add helper function to compute team id”
+- “Refactor X” (without a user-visible or measurable outcome)
+- “Verify billing works” (without specifying the scenario and what to check)
+
+## Files / Areas Likely to Change
+
+-
+
+## Data / RLS / RPC / Migrations
+
+-
+
+## Risks & Mitigations
+
+-
+
+Planning guardrails:
+
+- Base the plan on `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` (outcomes/expectations), not assumptions.
+- If `REQUIREMENTS.md` is missing, stop and instruct the user to run the `project.requirements` prompt first.
+- If `REQUIREMENTS.md` has any unresolved `## Open Questions`, stop and instruct the user to run the `project.clarify` prompt (or answer directly) and ensure the outcomes/decisions are recorded back into `REQUIREMENTS.md` before planning.
+- Exception: you may proceed with a plan only if the user explicitly accepts the unresolved items as risks AND that acceptance is recorded in `REQUIREMENTS.md` (e.g., in `## Decisions Log`).
+- Before planning, verify the requirements approval envelope. If approval is missing or stale,
+  stop and return to owner review; do not ask an agent to self-approve it.
+- After approval, move the task to `Analysing`, write the plan, run a post-plan clarification pass
+  against requirements and repo constraints, then run `task ready`. Remediate repo-gatherable plan
+  gaps autonomously. Return to the owner only for material scope drift, new product decisions,
+  exceptional authority, or a deliberately requested/high-risk plan review.
+- If you detect conflicts between `REQUIREMENTS.md`, the `## User Story` in `IMPLEMENTATION.md`, and repo constraints, stop and instruct the user to run the `project.clarify` prompt to resolve them and record decisions back into `REQUIREMENTS.md`.
+
+Task list guardrails:
+
+- The `project.planner` prompt owns the implementation task list in `IMPLEMENTATION.md`.
+- Do not treat AC mapping as optional; a task row without an `AC#` reference is not ready for implementation.
+- The user should be able to verify each task without reading code (unless explicitly unavoidable).
+- Ensure every acceptance criterion in `REQUIREMENTS.md` is mapped to at least one concrete task row and validation step in the task list (`Acceptance Criteria`, `User Verification`, or explicit validation notes).
+- Keep AC IDs stable. Do not renumber existing ACs unless the user explicitly approves the requirements change.
+- If any requirement/acceptance criterion is not covered by the plan, stop and route to `project.clarify` to resolve and record the decision in `REQUIREMENTS.md` before planning continues.
+- For delegate-execution stories (`project.delegate`), explicitly cover mode defaults, dependency-map validation, worker-limit behavior, and fail-fast/halted reporting in planned outcomes and validation steps.
+
+Tracker rules:
+
+- Use statuses: `To Do`, `Analysing`, `Ready`, `Plan Confirmed` (legacy-compatible), `In Progress`, `Blocked`, `Testing`, `Review`, `Complete`, `N/A`.
+- Only mark `Complete` after implementation validation and QA/code review have passed AND the user explicitly instructs you to mark it `Complete`.
+
+User story tracker rules:
+
+- `/.project-workflow/TRACKER.md` is part of the process. When moving into planning for a story/task, ensure there is a row for `${input:taskId}` and use the lifecycle command to update its `Status`.
+- Use the same status vocabulary as above.
+- During planning, run `./.project-workflow/cli/workflow task status --id ${input:taskId} --to Analysing`.
+- When the post-plan clarification pass and `task ready` succeed, run
+  `./.project-workflow/cli/workflow task status --id ${input:taskId} --to Ready` and continue inside
+  the approved envelope. `Plan Confirmed` remains valid for legacy tasks but is not the default
+  human checkpoint for new work.
+- Do not set story `Status` to `Complete` unless QA/code review has passed AND the user explicitly instructs you to mark it `Complete`.

project_workflow/prompts/QAReview.prompt.md

@@ -0,0 +1,86 @@
+---
+name: project.qa-review
+description: Run the QA and code review gate after implementation validation, before completion.
+argument-hint: taskId=TASK-330-Superuser scope="review changed work"
+agent: agent
+---
+
+Use this prompt after `project.implement` has made changes and moved the task or work item to `Testing`.
+
+Purpose:
+
+- Independently verify the implemented work against requirements and acceptance criteria.
+- Review the changed code for correctness, maintainability, security, data safety, and scope control.
+- Record review results before any task is marked `Complete`.
+
+Reference docs:
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- Canonical task tracker: `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`
+- Requirements source of truth: `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md`
+- Project outcomes: [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Scope: `${input:scope:What changed or what should be reviewed?}`
+
+Defaults and inference:
+
+- If `taskId` is omitted, infer it from the current branch name when possible.
+- If `scope` is omitted, review the current uncommitted diff plus the task docs.
+- Ask only when the task cannot be inferred safely.
+
+Required workflow:
+
+1. Read `REQUIREMENTS.md`, `IMPLEMENTATION.md`, and the tracker row for the task.
+2. Confirm implementation has reached `Testing`. If it has not, stop and direct the user to run `project.implement` first.
+3. Run the relevant workflow status command to move the row to `Review` before starting QA/code review:
+   - standalone task: `./.project-workflow/cli/workflow task status --id ${input:taskId} --to Review`
+   - epic child: `./.project-workflow/cli/workflow epic status --epic-id <EPIC_ID> --id ${input:taskId} --to Review`
+4. Inspect the changed files and map each acceptance criterion ID to evidence:
+   - automated test, typecheck, lint, build, or script result
+   - manual verification result
+   - code inspection finding
+5. If a requirement, acceptance criterion, child charter, epic contract, or material claim triggers a proof recipe, inspect child-local `EVIDENCE.json` and the referenced evidence artifact before accepting the claim. Visual/reference fidelity requires rendered comparison against the delivered user-facing artifact, not code review, tests, build output, or a surrogate surface. Runtime target/source proof requires the exact target/source pair and positive proof that target used that source.
+6. Run any missing narrow validation that is necessary to support the review. Do not ask the user to manually test behavior that the agent can validate directly with available commands, tests, scripts, browser tools, screenshots, or local tools. Do not rerun broad checks unless they are the most meaningful available check.
+7. Review code for:
+   - correctness against requirements and decisions
+   - unintended scope expansion
+   - error handling and edge cases
+   - security, permissions, privacy, and data integrity
+   - migrations, rollback, observability, and operational risk where relevant
+   - tests and documentation appropriate to the change
+8. Record results in `IMPLEMENTATION.md` under `## QA & Code Review` with:
+   - date
+   - reviewer/agent context
+   - files or areas reviewed
+   - validation evidence
+   - a clear distinction between verified evidence and deferred setup, owner-only actions, or unavailable connector/OAuth checks
+   - findings, if any
+   - verdict: `Pass`, `Pass with follow-ups`, or `Changes requested`
+9. Run `./.project-workflow/cli/workflow doctor` when available and include any workflow-state warnings or errors in the review output.
+10. If issues are found:
+   - keep tracker status as `Review` or set it to `Blocked` if the issue prevents safe release
+   - list findings first, ordered by severity, with file references where possible
+   - do not mark anything `Complete`
+11. If review passes:
+   - say that QA/code review passed
+   - only run the relevant workflow command to mark `Complete` if the user explicitly asked you to complete the task after review
+   - otherwise leave status as `Review` and ask for explicit completion approval
+
+Output expectations:
+
+- Findings first when any exist.
+- Validation evidence with exact commands or manual checks, reported by AC ID.
+- A concise verdict.
+- The next step is `project.retro` only after the task is marked `Complete`.
+
+Guardrails:
+
+- Do not mark `Complete` based on implementation validation alone. QA/code review must pass first.
+- Do not use this prompt to implement new scope. Small review fixes are allowed only when they directly address review findings and remain within the accepted requirements.
+- If review reveals a requirements conflict, route back to `project.clarify` and record the decision before continuing.
+- Do not accept unsupported prose claims as closeout evidence. If prose claims contradict structured evidence, report the contradiction as a blocking finding.

project_workflow/prompts/Requirements.prompt.md

@@ -0,0 +1,205 @@
+---
+name: project.requirements
+description: Capture and confirm what we are building (problem, scope, acceptance criteria).
+argument-hint: taskId=TASK-330-Superuser goal="..." context="..."
+agent: agent
+---
+
+Use this prompt to produce a crisp, testable set of requirements.
+
+This is an iterative prompt. Expect to run it multiple times:
+
+- Pass 1: ask what the feature/bugfix is, draft an initial user story, produce a best-effort `REQUIREMENTS.md`, and ask the minimum questions needed to remove ambiguity.
+- Pass N: incorporate the user’s answers, resolve open questions, tighten acceptance criteria, and strengthen the validation plan.
+
+Operating model: the owner/PM/BA provides product intent and decisions conversationally; the agent extracts, drafts, records, and validates workflow artifacts. Do not ask the owner to manually fill templates as the normal path.
+
+Approval model: requirements capture ends with one explicit owner review of requirements and acceptance criteria. Record that approval with `task approve-requirements` or `epic approve-requirements` only after the owner confirms the drafted requirements/ACs. Do not treat the agent's draft, implementation intent, or silence as approval.
+
+After that approval, the agent normally continues autonomously through Planner, a post-plan
+Clarify pass, `task ready`, and `Ready`. Pause after requirements only when the user requests a
+setup/review-only boundary, a material product decision remains, or the plan is exceptional/high
+risk enough to justify an explicit review.
+
+Minimum intake context to gather before downstream planning:
+
+- Problem or opportunity
+- Desired outcome
+- Affected user, actor, or system
+- Scope boundaries and non-goals
+- Acceptance signal for done
+- Constraints, priority/risk, and examples or failure modes
+
+Context sources (reference, don’t duplicate):
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- Project outcomes (north stars): [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- E2E exception rules (only if editing `front-end/apps/e2e/**`): [../instructions/e2e.instructions.md](../instructions/e2e.instructions.md)
+
+Canonical task docs:
+
+- `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` (this prompt produces/updates this file)
+- `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` (must include `## User Story` at the top; keep it in sync with `REQUIREMENTS.md`)
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Goal: `${input:goal:Describe the user outcome}`
+- Optional context: `${input:context:Links, routes, screenshots, logs, constraints}`
+
+Output (Markdown, use headings exactly):
+
+Primary output artifact:
+
+- Write/update `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` with the contents of this prompt output.
+
+This is not a technical design doc. Focus on outcomes, expectations, and “what done means”.
+
+Process:
+
+- Step 0 (always first): Discovery — identify what we are building.
+  - If the feature/bugfix is not explicitly described in the conversation context and inputs, ask the user:
+    - “What is the new feature or bugfix?”
+    - And only the minimal freeform context needed to draft a user story (where in the product, who is affected, and what success looks like).
+  - IMPORTANT: In Discovery, do NOT ask A/B/C-style questions yet. You do not have a user story to anchor them to.
+  - If Discovery information is missing, STOP after asking the Discovery questions. Do not draft a user story, do not write/update files, and do not ask additional questions.
+  - If the request is explicitly discovery work, record it as `Type: Discovery` with a question, decision enabled, boundary, output, and validation signal.
+
+- Step 1: Draft the user story (only after Discovery is answered).
+  - Based on the user’s Discovery answer (or the provided inputs), write a first-draft user story (may be imperfect) and put it in BOTH:
+    - `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` under `## User Story`
+    - `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` under `## User Story`
+  - IMPORTANT: This prompt may only create/update the `## User Story` section in `IMPLEMENTATION.md`.
+    - Do NOT add or modify `## Tasks`, task lists, phases, checklists, or implementation steps in `IMPLEMENTATION.md`.
+    - Task planning belongs to the `project.planner` prompt.
+
+- Step 2: Clarify only after the user story exists.
+  - If any critical requirement is ambiguous, untestable, or missing, write it as an open question.
+  - Ask the user the minimum set of questions to resolve it.
+  - A/B/C-style multiple-choice questions are allowed ONLY here (after the user story exists), and must be explicitly anchored to the current user story.
+  - Stop after asking questions. Do not proceed to planning/implementation until open questions are resolved or explicitly accepted as risks and recorded.
+
+- Read `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` if it exists. Treat it as the current draft.
+- Read `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` and treat its user story as canonical for implementation, but keep it synced with `REQUIREMENTS.md` as discovery evolves.
+- Cross-check for conflicts across: Goal input, the user’s described feature/bugfix, the user story, existing REQUIREMENTS, and repo constraints.
+- Update `REQUIREMENTS.md` to be internally consistent.
+- If any critical requirement is ambiguous, untestable, or missing, write it as an open question and then ask the user the minimum set of questions to resolve it.
+- Stop after asking questions. Do not proceed to planning/implementation until open questions are resolved or explicitly accepted as risks and recorded.
+- Once open questions are resolved and the owner confirms the final requirements/ACs, record the approval envelope with the workflow CLI. After that, downstream agents should not ask for repeated approval unless the requirements/ACs, artifact identity, source-of-truth interpretation, proof obligations, or scope materially change.
+
+## Overview
+
+- Goal (in user terms):
+- Primary user(s):
+- Desired outcome:
+
+## User Story
+
+Derive the user story from the user’s described feature/bugfix via the discovery back-and-forth.
+
+- In Pass 1, it is acceptable for the user story to be a first draft.
+- In Pass N, refine the user story as ambiguities are resolved.
+- Always keep the user story consistent across:
+  - `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md`
+  - `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`
+
+-
+
+## In Scope
+
+-
+
+## Out of Scope
+
+-
+
+## Requirements
+
+List requirements as outcomes/expectations, not implementation details.
+
+### Functional Requirements
+
+-
+
+### Non-Functional Requirements
+
+- Performance / latency:
+- Security / permissions:
+- Accessibility:
+- Observability (logs/metrics/audit expectations):
+
+## Acceptance Criteria
+
+- AC1:
+- AC2:
+
+## Assumptions
+
+-
+
+## Open Questions
+
+-
+
+If this section is non-empty, also ask the user these questions at the end of your response.
+
+Rules for asking questions:
+
+- Do not ask A/B/C questions until `## User Story` is drafted.
+- When you do ask A/B/C questions, explicitly reference the user story they relate to.
+
+## Decisions Log
+
+Capture resolved questions and selected options from the Clarify step.
+
+- Decision:
+  - Context:
+  - Options considered:
+  - Chosen:
+  - Why:
+
+## Validation Plan (User-Facing)
+
+- How the user will verify “done”:
+- Rollout notes (if any):
+- Required proof recipes, if triggered by requirements/claims:
+- Invalid substitutes for those proof recipes:
+
+## Review Questions (Answer Needed)
+
+Include this section only when `## Open Questions` is non-empty.
+
+Rules:
+
+- Ask the minimum set of questions required to make the requirements complete and testable.
+- Prefer multiple choice with 2–4 options (A/B/C/…) when it helps remove ambiguity; include tradeoffs.
+- Do not use A/B/C until `## User Story` exists (in both docs) and your question is explicitly anchored to that story.
+- If the user already answered in the conversation context, do not ask again; instead record the decision in `## Decisions Log` and remove it from `## Open Questions`.
+
+-
+
+Also:
+
+- Ensure `/.project-workflow/TRACKER.md` has a row for `${input:taskId}`. Keep a new task at `To Do`
+  while requirements are being drafted. Move to `Analysing` only after the owner approval envelope
+  is recorded and planning begins.
+- Ensure `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md` exists and begins with a `## User Story` section at the very top.
+  - If you need to create the file, keep it minimal (user story only, plus placeholders if required by repo convention).
+  - Do not generate or populate any task list here.
+- Create or update `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md` with the contents of this output.
+
+Guardrails:
+
+- The requirements must be internally consistent (no contradictions across sections).
+- Every item in `## Acceptance Criteria` must have a stable ID (`AC1`, `AC2`, etc.) and be verifiable in `## Validation Plan (User-Facing)`.
+- In `## Validation Plan (User-Facing)`, include an explicit AC-by-AC mapping (`AC1 -> verification step`, `AC2 -> verification step`, etc.).
+- If the owner says the work must match a design, reference, screenshot, visual state, deployed/runtime behavior, external contract, or multi-context behavior, explicitly name the required proof recipe and the invalid substitutes. Examples: visual fidelity requires rendered comparison against the delivered user-facing artifact; runtime target/source proof requires the exact target, source/artifact under test, observation method, and positive proof that target used that source.
+- Preserve existing AC IDs when revising requirements. Do not renumber existing ACs unless the user explicitly approves the requirements change.
+- If this story includes delegated execution (`project.delegate`), ensure requirements, acceptance criteria, and decisions explicitly cover: execution modes, default `sequential` behavior, dependency-map input + strict validation (unknown IDs, self-dependencies, cycles), default parallel worker limit (`4`), fail-fast semantics (stop new launches, allow in-flight completion), and final status reporting (including halted items).
+- If delegated-execution decisions evolve, update both `## Acceptance Criteria` and `## Decisions Log` in the same pass so downstream planning/implementation stay aligned.
+- Do not create or update implementation task lists in `IMPLEMENTATION.md` from this prompt; the `project.planner` prompt owns tasks.
+- Do not move the story to `Analysing` before owner approval. After approval, hand off directly to
+  Planner unless the user requested a pause.
+- After requirements and implementation planning are complete, the agent must use `./.project-workflow/cli/workflow task ready --id ${input:taskId}` before implementation-oriented status transitions. If it reports missing or stale owner approval, collect the specific owner confirmation once and record it with `task approve-requirements`; do not continue into implementation from an unapproved envelope.

project_workflow/prompts/Retro.prompt.md

@@ -0,0 +1,70 @@
+---
+name: project.retro
+description: Run the post-completion retro to keep conventions, agent guidance, and workflow assets current.
+argument-hint: taskId=TASK-330-Superuser focus="conventions, agents, follow-ups"
+agent: agent
+---
+
+Use this prompt after a task has passed QA/code review and has been marked `Complete`.
+
+Purpose:
+
+- Capture reusable lessons from the finished task.
+- Update durable repo conventions, agent instructions, prompts, skills, or workflow rules when the task exposed a repeatable gap.
+- Keep future tasks internally consistent without adding one-off implementation details to global guidance.
+
+Reference docs:
+
+- Technical constraints/instructions: [../copilot-instructions.md](../copilot-instructions.md)
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- User story tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+- Canonical task tracker: `/.project-workflow/tasks/${input:taskId}/IMPLEMENTATION.md`
+- Requirements source of truth: `/.project-workflow/tasks/${input:taskId}/REQUIREMENTS.md`
+- Project outcomes: [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+- Agent definitions: `/.github/prompts/`, `/AGENTS.md`, `/.agents/skills/`, and `/.cursor/rules/` when present
+
+Inputs:
+
+- Task: `${input:taskId:TASK-000-Example}`
+- Focus: `${input:focus:What should the retro pay attention to?}`
+
+Required workflow:
+
+1. Read the completed task's `REQUIREMENTS.md`, `IMPLEMENTATION.md`, QA/code review notes, and tracker row.
+2. Confirm the task is already `Complete`. If not, stop and direct the user to finish `project.qa-review` and explicit completion first.
+3. Inspect the final diff and decisions for reusable lessons:
+   - repo conventions or coding patterns that should be documented
+   - recurring validation commands or QA checks
+   - agent prompt/skill gaps that caused drift or rework
+   - project-workflow lifecycle rules that need tightening
+   - follow-up work that should become a separate task
+4. Decide where each durable update belongs:
+   - product outcomes: `.project-workflow/CONSTITUTION.md`
+   - technical conventions: `.project-workflow/guidance.md`, `AGENTS.md`, `.github/copilot-instructions.md`, or equivalent repo guidance
+   - Copilot workflow behavior: `.github/prompts/*.prompt.md`
+   - Codex workflow behavior: `.agents/skills/project-*/SKILL.md`
+   - Cursor workflow behavior: `.cursor/rules/project-workflow.mdc`
+   - packaged project-workflow templates, when working in this repository: `src/project_workflow/**`
+5. Make only durable, generally useful updates. Do not encode task-specific implementation details as global rules.
+6. Record the retro in `IMPLEMENTATION.md` under `## Retro` with:
+   - date
+   - reusable lessons
+   - conventions or agent assets updated
+   - follow-up task suggestions, if any
+   - "No durable updates needed" when nothing should change
+7. If follow-up work is needed, propose a new task rather than reopening the completed task.
+8. Keep follow-up tasks separate from missed in-scope work. Missed in-scope work should be recorded as a completion/process issue unless it was explicitly deferred with owner approval and a follow-up reference.
+
+Output expectations:
+
+- Summarize convention/agent changes made.
+- List any files updated.
+- List proposed follow-up tasks separately.
+- List missed in-scope work separately from follow-up suggestions.
+- Leave the completed task status as `Complete` unless the user explicitly asks to reopen it.
+
+Guardrails:
+
+- Retro is a maintenance step, not a new implementation phase.
+- Do not change accepted requirements after completion; create a follow-up task for new scope.
+- If a convention update would materially change project direction, ask before editing product-level guidance.

project_workflow/prompts/SmokeBomb.prompt.md

@@ -0,0 +1,14 @@
+---
+name: project.smoke-bomb
+description: Prepare a reviewed, sanitized client ZIP from an agency-owned project-workflow repository.
+argument-hint: clientAgent=codex output=../client-handoff.zip validation="npm test"
+agent: agent
+---
+
+Use this prompt when the user asks for a Smoke Bomb or sanitized client handoff.
+
+Read the repository README, agent instructions, `.project-workflow/guidance.md`, and active delivery state. Recommend a disposable handoff branch but leave Git branch operations under user control. Prepare substantive client-facing human and agent context without inventing undocumented knowledge.
+
+Run `project smoke-bomb` in plan mode with the intended client-agent target, explicit reviewed validation commands, and a ZIP output path outside the repository. Review and resolve every action, ownership decision, blocker, warning, archive exclusion, and plan fingerprint. Apply only the exact reviewed fingerprint, using `--yes` only with user authority.
+
+Report the exported ZIP path and SHA-256, validation results, selected client-agent instructions, and archive inventory. The ZIP—not the agency repository or its history—is the handoff artifact. Do not bypass secret-like path, unsafe file, ambiguous ownership, missing guidance, dirty-worktree, or residual-reference blockers. Smoke Bomb does not replace legal, security, license, or data-loss-prevention review.