project-workflow 0.2.0__py3-none-any.whl

project_workflow/codex/skills/project-planner/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: project-planner
+description: Use when turning confirmed project-workflow requirements into a phased implementation plan and testable work-item table.
+---
+
+# Project Planner
+
+Turn confirmed requirements into a safe, incremental implementation plan.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for an implementation plan, phases, or testable work items for a project-workflow task, even if they ask in natural language.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- If the task folder does not exist, use `project-task` first so the CLI creates the required files and tracker row.
+- If requirements are missing or unclear, use `project-requirements` or `project-clarify` before planning.
+- Verify the owner-approved requirements/AC envelope before planning. Planning must not be used to
+  manufacture or infer that approval.
+- Planning is a document workflow unless the CLI adds an explicit planner command.
+
+## Required Files
+
+- `.project-workflow/tasks/<TASK>/REQUIREMENTS.md`
+- `.project-workflow/tasks/<TASK>/IMPLEMENTATION.md`
+- `.project-workflow/TRACKER.md`
+- `.project-workflow/CONSTITUTION.md` if present
+- `AGENTS.md` and other repo instructions if present
+
+## Workflow
+
+1. Read requirements first and treat them as the source of truth.
+2. If requirements are missing, unclear, or internally inconsistent, stop and use `project-requirements` or `project-clarify`.
+3. Produce or update `IMPLEMENTATION.md` with:
+   - `## User Story` at the top
+   - `## Goal`
+   - `## Approach`
+   - `## Phases`
+   - `## Tasks`
+4. Assign or preserve stable acceptance criteria IDs (`AC1`, `AC2`, etc.) from
+   `REQUIREMENTS.md` and the `## Acceptance Criteria` section in
+   `IMPLEMENTATION.md`.
+5. Make every task independently testable and outcome-based.
+6. Map every task row to one or more AC IDs, and ensure every AC ID is 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
+   evidence artifact expectation in the row. Do not use code review, tests,
+   builds, surrogate surfaces, or related environments as recipe substitutes.
+7. Use this table shape for tasks:
+
+```md
+|  ID | Title | Description | Acceptance Criteria | User Verification | Status |
+| --: | ----- | ----------- | ------------------- | ----------------- | ------ |
+|   1 | <Outcome> | <What changes for the user/system?> | AC1: <observable pass/fail criteria> | <steps or command> | To Do |
+```
+
+8. Keep each table row on one physical line. Use `<br>` for multiple items
+   inside a cell and escape literal `|` characters.
+9. Include validation steps for each phase.
+10. Move to `Analysing`, write the plan, then run `project-clarify` as a post-plan consistency pass.
+11. Run `./.project-workflow/cli/workflow task ready --id <TASK-ID>` and fix repo-gatherable
+    gaps. If it passes, move to `Ready` and continue inside the approved envelope. `Plan Confirmed`
+    remains legacy-compatible; explicit human plan review is optional for requested or exceptional
+    high-risk plans, not the default checkpoint.
+12. Return to the owner if the plan exposes material scope drift, a new product decision,
+    exceptional authority, or changed proof obligations/artifact identity.
+13. Include QA/code review as the required gate after implementation validation
+    and before completion.
+14. Do not implement code during planning.

project_workflow/codex/skills/project-qa-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: project-qa-review
+description: Use after implementation validation to run the QA and code review gate before a project-workflow task is completed.
+---
+
+# Project QA & Code Review
+
+Run the post-implementation quality gate for a project-workflow task.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for QA, review, code review, verification, release readiness, or completion approval for a project-workflow task.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- If implementation has not reached `Testing`, use `project-implement` first.
+- QA/code review is a document and validation workflow unless the CLI adds an explicit review command.
+
+## Required Files
+
+- `.project-workflow/tasks/<TASK>/REQUIREMENTS.md`
+- `.project-workflow/tasks/<TASK>/IMPLEMENTATION.md`
+- `.project-workflow/TRACKER.md`
+- Repo instruction files such as `AGENTS.md` or `.github/copilot-instructions.md`
+
+## Workflow
+
+1. Infer the task ID from the user prompt or current branch if possible. Ask only if it cannot be inferred.
+2. Read requirements, implementation notes, tracker status, and the current diff before reviewing.
+3. Confirm the task or work item is in `Testing`. If not, stop and route to `project-implement`.
+4. Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Review` before review work begins.
+5. Map every relevant acceptance criterion ID to validation evidence.
+6. If requirements or claims trigger a proof recipe, verify child-local `EVIDENCE.json` has passing structured claim records. QA prose cannot satisfy recipe-triggered visual/reference fidelity, external contract alignment, deployed artifact alignment, runtime target/source, or responsive visual behavior claims.
+7. Run any missing narrow validation needed to support the review. Do not ask the user to manually test behavior that the agent can validate directly with available commands, tests, scripts, or local tools.
+8. Review the changed code for correctness, scope control, maintainability, edge cases, tests, docs, security, permissions, privacy, data integrity, and operational risk.
+9. Record results in `IMPLEMENTATION.md` under `## QA & Code Review` with date, reviewed areas, validation evidence, findings, and verdict. Clearly separate verified evidence from deferred setup, owner-only actions, unavailable connector/OAuth checks, and invalid substitutes.
+10. Run `./.project-workflow/cli/workflow doctor` and include any workflow-state warnings or errors in the review output.
+11. If findings exist, report them first with severity and file references. Keep status as `Review` or set `Blocked` for release-blocking issues.
+12. If review passes, say so. Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Complete` only when the user explicitly asks to complete the task after review.
+13. After completion, route to `project-retro`.
+
+## Verdicts
+
+- `Pass`: no blocking findings and validation evidence covers the acceptance criteria by AC ID.
+- `Pass with follow-ups`: safe to complete, but separate follow-up work is recommended.
+- `Changes requested`: completion is blocked until findings are addressed.

project_workflow/codex/skills/project-requirements/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: project-requirements
+description: Use when drafting or updating project-workflow REQUIREMENTS.md with user story, scope, acceptance criteria, decisions, and open questions.
+---
+
+# Project Requirements
+
+Capture what is being built before planning or coding.
+
+Project Workflow is owner-directed and agent-operated. The owner provides product context and decisions conversationally; the agent extracts them into workflow artifacts and asks focused questions only when needed.
+
+Requirements capture must end with one explicit owner confirmation of requirements and acceptance
+criteria before planning. Record that authority with `task approve-requirements` or
+`epic approve-requirements` after confirmation. Do not treat an agent draft, silence, or
+implementation request as approval. After approval, normally continue autonomously through
+Planner, post-plan Clarify, `task ready`, and `Ready`; pause only for material drift, exceptional
+authority, requested/high-risk plan review, or an explicit setup-only boundary.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for requirements, scope, acceptance criteria, open questions, decisions, or a validation plan, even if they ask in natural language.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- If the task folder does not exist, use `project-task` first so the CLI creates the required files and tracker row.
+- After the task exists, requirements capture is a document workflow unless the CLI adds an explicit requirements command.
+
+## Required Files
+
+- `.project-workflow/tasks/<TASK>/REQUIREMENTS.md`
+- `.project-workflow/tasks/<TASK>/IMPLEMENTATION.md`
+- `.project-workflow/CONSTITUTION.md` if present
+- `.github/copilot-instructions.md` or `AGENTS.md` if present
+
+## Workflow
+
+1. Identify the task folder. If it does not exist, use `project-task` first.
+2. Read existing `REQUIREMENTS.md` and the `## User Story` section of `IMPLEMENTATION.md`.
+3. If the feature or bugfix is not clear, ask only for discovery context: what change, where in the product, who is affected, and what success looks like.
+   Minimum context should cover problem/opportunity, desired outcome, affected user or system, scope boundaries, acceptance signal, constraints, priority/risk, and examples or failure modes.
+4. Draft or update `REQUIREMENTS.md` with:
+   - Overview
+   - User Story
+   - Goal
+   - Non-Goals
+   - Users & Context
+   - Outcome-focused requirements
+   - Verifiable acceptance criteria with stable IDs (`AC1`, `AC2`, etc.)
+   - Open questions
+   - Resolved decisions
+   - Validation plan
+5. Preserve existing AC IDs when requirements change. Do not renumber existing
+   ACs unless the user explicitly approves the requirements change.
+6. If requirements mention matching a visual/reference, deployed/runtime behavior, external contract, or responsive/multi-context behavior, record the relevant proof recipe, artifact identity, and invalid substitutes in the validation plan.
+7. Keep only the `## User Story` section in `IMPLEMENTATION.md` synced with `REQUIREMENTS.md`. Do not add implementation tasks here.
+8. If critical requirements are ambiguous, record them as open questions in `REQUIREMENTS.md`, then ask the user the minimum questions needed.
+9. Do not proceed to planning or implementation until open questions are resolved or explicitly accepted as risks and recorded.
+10. After requirements and ACs are complete, ask the owner to confirm that exact requirements/AC envelope once, then record approval with the workflow CLI. Downstream work inside that unchanged envelope should not ask for repeated approval.
+11. After approval, move to `Analysing`, run `project-planner`, run a post-plan
+    `project-clarify` pass, validate with `task ready`, and move to `Ready` without another generic
+    approval request.
+12. If the work is intentionally exploratory, record it as discovery with a question, decision enabled, boundary, output artifact, and validation signal.

project_workflow/codex/skills/project-retro/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: project-retro
+description: Use after a project-workflow task is complete to update durable conventions, agent guidance, and follow-up tasks.
+---
+
+# Project Retro
+
+Run the post-completion retro for a project-workflow task.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for a retro, retrospective, lessons learned, convention updates, agent updates, prompt updates, or post-completion cleanup for a project-workflow task.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- Only run after QA/code review has passed and the task is marked `Complete`.
+- Retro is a maintenance workflow unless the CLI adds an explicit retro command.
+
+## Required Files
+
+- `.project-workflow/tasks/<TASK>/REQUIREMENTS.md`
+- `.project-workflow/tasks/<TASK>/IMPLEMENTATION.md`
+- `.project-workflow/TRACKER.md`
+- Repo instruction files and agent assets such as `AGENTS.md`, `.github/copilot-instructions.md`, `.github/prompts/`, `.agents/skills/`, and `.cursor/rules/` when present
+
+## Workflow
+
+1. Infer the task ID from the user prompt or current branch if possible. Ask only if it cannot be inferred.
+2. Read the completed task docs, QA/code review notes, tracker row, final diff, and repo guidance.
+3. Confirm the task is `Complete`. If not, stop and route to `project-qa-review`.
+4. Identify reusable lessons:
+   - repo conventions or coding patterns that should be documented
+   - validation or QA checks that should become standard
+   - agent prompt, skill, or rule gaps that caused drift or rework
+   - follow-up work that should become a separate task
+   - missed in-scope work that should have blocked completion unless explicitly deferred
+5. Update the narrowest durable guidance file that owns each lesson. Do not add one-off task details to global instructions.
+6. Record the retro in `IMPLEMENTATION.md` under `## Retro` with date, lessons, updated assets, follow-up suggestions, and a separate note for any missed in-scope work.
+7. Leave tracker status as `Complete` unless the user explicitly asks to reopen the task.
+
+## Placement Rules
+
+- Product outcome changes belong in `.project-workflow/CONSTITUTION.md`.
+- Technical workflow conventions belong in `.project-workflow/guidance.md`, or the narrowest equivalent repo guidance file.
+- Copilot workflow behavior belongs in `.github/prompts/*.prompt.md`.
+- Codex workflow behavior belongs in `.agents/skills/project-*/SKILL.md`.
+- Cursor workflow behavior belongs in `.cursor/rules/project-workflow.mdc`.
+- Packaged project-workflow behavior belongs in `src/project_workflow/**` when working in this repository.

project_workflow/codex/skills/project-smoke-bomb/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: project-smoke-bomb
+description: Use when preparing a sanitized client ZIP from an agency-owned project-workflow repository.
+---
+
+<!-- project-workflow:generated -->
+
+# Project Smoke Bomb
+
+Prepare a deliberate client handoff without transferring agency-only workflow state or stripping the project of useful human and agent context.
+
+## Invocation Rules
+
+- Use this skill when the user asks for a Smoke Bomb, sanitized client handoff, clean client ZIP, or removal of project-workflow from a delivery copy.
+- Read `AGENTS.md`, `.project-workflow/guidance.md`, `README.md`, the active task state, and repository-specific delivery instructions before preparing the handoff.
+- Use the canonical `project smoke-bomb` command for planning, mutation, validation, and export. Do not imitate it with broad deletion commands or an unconstrained ZIP operation.
+
+## Workflow
+
+1. Confirm the agency-owned repository is authoritative and identify the exact client, intended client agent targets, and ZIP output path.
+2. Recommend a disposable branch such as `smoke-bomb/<client-or-handoff>`. Branch creation, commits, pushes, and deletion remain normal user-controlled Git operations; do not force them inside Smoke Bomb.
+3. Review and prepare client-facing context before cleanup:
+   - keep a substantive `README.md` with purpose, setup, architecture pointers, validation, and delivery guidance;
+   - retain substantive user-authored `AGENTS.md` content outside the project-workflow managed block, or place verified repository guidance in `.project-workflow/guidance.md` so the command can produce the canonical client agent guide;
+   - choose only the client agent targets actually needed: `codex`, `claude-code`, `cursor`, or `github-copilot`;
+   - identify explicit non-interactive validation commands; never invent a command or claim undocumented architecture.
+4. Commit or otherwise clean the dedicated worktree before planning. Smoke Bomb refuses dirty worktrees so the reviewed plan has an exact source state.
+5. Run a non-mutating plan, preferably JSON for automation:
+
+   ```bash
+   project smoke-bomb \
+     --client-agent codex \
+     --validation-command "<reviewed command>" \
+     --output "<path outside the repository>/client-handoff.zip" \
+     --plan --format json
+   ```
+
+6. Review repository and branch identity, every delete/replace/create action, ownership evidence, README and agent targets, validation commands, exclusions, blockers, warnings, and the plan fingerprint.
+7. Resolve every blocker in the source branch and regenerate the plan. Never bypass an ambiguous ownership, secret-like path, unsafe file type, missing guidance, dirty state, or residual project-workflow reference finding.
+8. Apply only the exact reviewed plan. Authorized non-interactive agents add `--yes`; human invocation confirms interactively:
+
+   ```bash
+   project smoke-bomb \
+     --client-agent codex \
+     --validation-command "<reviewed command>" \
+     --output "<path outside the repository>/client-handoff.zip" \
+     --apply --plan-fingerprint <SHA256> --yes --format json
+   ```
+
+9. Verify the result reports `exported`, all reviewed validations passed, the ZIP path and SHA-256 are present, the inventory contains no `.git` or `.project-workflow`, and the intended README and client-agent instructions are included.
+10. Hand over the ZIP and its SHA-256. Keep the agency repository and normal branches intact; the client may initialize its own repository from the snapshot.
+
+## Guardrails
+
+- Smoke Bomb is not a secret scanner, legal review, license audit, or proof that every file is client-appropriate. Resolve those responsibilities separately before handoff.
+- Do not hand over the agency Git repository or history when the agreed deliverable is the sanitized ZIP.
+- Do not treat the absence of the string `project-workflow` as sufficient proof; rely on the reviewed action inventory, exact Git-visible archive inventory, validation results, and client guidance checks.
+- If validation fails, no ZIP is produced. Inspect the failure and the branch diff before deciding whether to restore, amend, or rerun.

project_workflow/codex/skills/project-task/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: project-task
+description: Use when creating a new project-workflow task folder, tracker row, and optional branch for a feature or bugfix.
+---
+
+# Project Task
+
+Create the minimal workflow artifacts for one new task.
+
+Project Workflow is owner-directed and agent-operated: the owner provides product context and decisions conversationally, while the agent runs commands and records workflow state.
+
+Task creation is only scaffolding. Requirements and ACs still need one explicit owner confirmation
+before planning; record that confirmation with `task approve-requirements` after requirements are
+ready. The agent then normally plans, clarifies, validates readiness, and moves to `Ready`
+autonomously. Do not repeatedly ask for approval inside the unchanged envelope.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks to create a project-workflow task, story, feature folder, tracker row, or new tracked work item, even if they ask in natural language.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- The local workflow CLI is mandatory for supported task scaffold operations. Do not manually create task folders, starter files, or tracker rows when the CLI command is available.
+- If another project-workflow skill needs a task folder that does not exist, route through this skill first.
+
+## Inputs
+
+Determine these from the user prompt, current branch, or follow-up questions:
+
+- Task title, such as `Account Usage Export`
+- Whether to create a branch
+- If creating a branch: base branch, default `develop`, and branch prefix, default `feature/`
+
+Minimum context to gather before planning or implementation:
+
+- 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
+
+## Workflow
+
+1. Confirm `.project-workflow/TRACKER.md` exists. If missing, tell the user to run `project init` first.
+2. If creating a branch, ensure the working tree is clean before switching branches.
+3. Run the local scaffolder from the repo root and let it assign the next ID.
+   Repositories may choose task ID namespaces and ID generation in
+   `.project-workflow/config.json`; pass `--prefix <PREFIX>` only when the user
+   or repo guidance calls for a configured non-default prefix.
+
+Without branch:
+
+```bash
+./.project-workflow/cli/workflow task init --title "<TITLE>" --update-tracker
+```
+
+Configured prefix:
+
+```bash
+./.project-workflow/cli/workflow task init --prefix <PREFIX> --title "<TITLE>" --update-tracker
+```
+
+With branch:
+
+```bash
+./.project-workflow/cli/workflow task init --title "<TITLE>" --update-tracker --create-branch --base-branch <BASE> --branch-prefix <PREFIX>
+```
+
+4. Run `./.project-workflow/cli/workflow doctor` and report any workflow-state warnings or errors.
+5. Report the created task folder, assigned task ID, tracker update, and branch name if one was created.
+6. Continue to requirements capture when the user is ready, then proceed through owner
+   confirmation, `task approve-requirements`, planning, post-plan clarification, `task ready`,
+   `Ready`, implementation, QA/code review, and retro. Pause after scaffolding only when the user
+   explicitly requested setup/review-only work.

project_workflow/cursor/rules/project-workflow.mdc

@@ -0,0 +1,75 @@
+---
+description: Project Workflow for routing, Fix/task/epic scaffolding, requirements authority, planning, implementation, QA, and validation.
+globs:
+alwaysApply: true
+---
+
+# Project Workflow
+
+This repository uses project-workflow for spec-driven development. Keep workflow artifacts in `.project-workflow/` as the shared source of truth, and read `.project-workflow/guidance.md` for repo-specific workflow guidance when present.
+
+Project Workflow is owner-directed and agent-operated. The owner supplies product context, constraints, examples, decisions, and approvals; the agent runs commands, drafts artifacts, asks targeted questions, validates readiness, implements, reviews, and records evidence.
+
+## Workflow Order
+
+1. Constitution: establish or update `.project-workflow/CONSTITUTION.md` for product outcomes.
+2. Backlog: optionally capture future intent in `.project-workflow/BACKLOG.md` before it becomes committed task or epic workflow state.
+3. Route: keep in-scope corrections in active work; use one lightweight Fix for a bounded
+   post-completion correction, a Task for a new outcome/multiple independent items, and an Epic for
+   coordinated workstreams. The agent recommends the route from evidence; the user's label is not
+   binding.
+4. Requirements: capture the task outcome, scope, acceptance criteria, decisions, and validation.
+5. Owner approval: record the requirements/AC envelope before planning with
+   `task approve-requirements` or `epic approve-requirements`.
+6. Planner: autonomously turn the approved envelope into testable work items.
+7. Clarify: run a post-plan consistency pass; return to the owner only for material drift.
+8. Ready: run `task ready` and move new tasks to `Ready`; `Plan Confirmed` is legacy-compatible.
+9. Implement: make the smallest scoped change, validate it, and move it to testing.
+10. QA & Code Review: independently verify acceptance criteria and review code before completion.
+11. Retro: after completion, record reusable lessons or follow-up work when present.
+
+## Cursor Usage
+
+- Read `.project-workflow/guidance.md` before changing workflow state when the file exists.
+- Use `.project-workflow/BACKLOG.md` for future intent, rough priority, options, and promotion history. Backlog is optional; direct task/epic creation is still valid for clear immediate work.
+- For broad future objectives, draft outcome-focused backlog candidates from project context and ask for owner review before accepting or promoting rows.
+- Promoted rows remain in the backlog with `Promoted To` pointing at the created task or epic ID. Active execution status belongs only in `.project-workflow/TRACKER.md`, epic trackers, and task/epic docs.
+- Existing roadmap/backlog documents outside `.project-workflow/BACKLOG.md` are preserved. Do not import or transform them automatically; create a repo-local migration task if needed.
+- Read `.project-workflow/config.json` for repo-owned task ID namespaces, ID generation, and accepted doctor warning fingerprints when it exists. Sequential IDs look like `TASK-001`; unique IDs keep the prefix and use a 5-character base36 suffix by default, such as `WF-K7F3Q`.
+- Do not report accepted doctor warnings as active issues after `doctor` hides them. Use `doctor --show-accepted` only when auditing accepted workflow debt.
+- If a task folder does not exist, run `./.project-workflow/cli/workflow task init --title "<TITLE>" --update-tracker` from the repo root and let the CLI assign the next configured task ID. Add `--prefix <PREFIX>` only when the user or repo guidance calls for a configured non-default prefix.
+- For one bounded correction against delivered/accepted behavior, run
+  `./.project-workflow/cli/workflow fix init --title "<TITLE>"`. Fixes use one `FIX.md`, the shared
+  tasks directory, and the global tracker. Do not create a separate fixes directory/tracker.
+- Read `.project-workflow/tasks/<ID>-*/REQUIREMENTS.md` before planning, implementing, reviewing, or running retro.
+- Read `.project-workflow/tasks/<ID>-*/IMPLEMENTATION.md` before implementing, reviewing, or running retro for a work item.
+- When planning, make every implementation task row map to one or more stable acceptance criteria IDs (`AC1`, `AC2`, etc.) from the task requirements or implementation acceptance criteria section.
+- If requirements, acceptance criteria, child charters, epic contracts, or material claims trigger a proof recipe, record structured evidence in `EVIDENCE.json` and verify the referenced artifact. Visual/reference fidelity needs rendered comparison against the delivered user-facing artifact; runtime target/source proof needs the exact execution target, source/artifact under test, observation method, and positive proof that the target used that source.
+- For epic-managed work, keep parent epic AC coverage visible from the epic tracker through child requirements, implementation, QA evidence, and closeout. New epic trackers use `Parent ACs`; legacy trackers may carry coverage in `Notes` as `Covers AC1, AC3`.
+- Before implementation-oriented status transitions, run `task ready`, `epic ready`, or `epic ready-child` where applicable. If a gate fails, fix repo-gatherable gaps directly and ask the owner only for missing product decisions, initial requirements/AC approval, amendments, deviations, changed artifact identity, changed proof obligations, or deferrals. Do not ask for repeated approval when the work remains inside the unchanged approved envelope.
+- For new tasks, owner approval comes before planning. After approval, run Planner, post-plan
+  Clarify, `task ready`, and move to `Ready` autonomously unless material drift or exceptional risk
+  requires owner input.
+- For new/adopted epics, `EPIC-CONTRACT.md` and `DECOMPOSITION.md` are authority artifacts. Child rows must come from the approved decomposition plan or an `AMENDMENTS.md` record; direct tracker edits outside that authority cannot advance through gated transitions.
+- The global tracker summarizes epic rows; each epic `TRACKER.md` owns child rows. Proposed child rows stay in the epic tracker until approved and scaffolded.
+- Keep `.project-workflow/TRACKER.md` status aligned with the current workflow state using `./.project-workflow/cli/workflow task status --id <TASK-ID> --to <STATUS>` when the command is available.
+- Do not mark a task or work item `Complete` unless implementation validation and QA/code review have passed and the user explicitly asks for completion.
+
+## Status Rules
+
+- New scaffolded tasks start as `To Do`.
+- Move new tasks to `Analysing` only after requirements/AC approval; move them to `Ready` after
+  planning, clarification, and `task ready` pass.
+- Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to "In Progress"` before implementation work begins.
+- Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Testing` after implementation and validation have been run.
+- Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Review` while QA/code review is running.
+- Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Complete` only after QA/code review passes and the user explicitly requests it.
+- Leave the tracker row as `Complete` during retro unless the user explicitly asks to reopen the task.
+
+## Validation
+
+- Run `.project-workflow/cli/workflow doctor` when workflow state is uncertain or before continuing after tracker/task doc edits.
+- Use `.project-workflow/cli/workflow doctor --strict` when safety warnings should block autonomous work.
+- Keep command ownership explicit: init creates a new installation, Doctor diagnoses without mutation, and canonical UVX upgrade plans and applies managed assets and repository schema together. Existing repositories must not run init first. Use `--yes` for authorized one-command agent operation or `--plan` plus `--apply --plan-fingerprint <SHA256>` for separate automation review.
+- Run the most relevant available tests, type checks, linters, or manual verification steps for the changed work.
+- If broad validation fails for unrelated pre-existing reasons, run the narrowest meaningful checks and report the limitation.

project_workflow/prompts/Backlog.prompt.md

@@ -0,0 +1,90 @@
+---
+name: project.backlog
+description: Capture, refine, validate, and promote optional project backlog items before they become task or epic workflow state.
+argument-hint: action=add|list|status|update|validate|promote title="..." id=BL-001
+agent: agent
+---
+
+Use this prompt to operate the optional project backlog in `.project-workflow/BACKLOG.md`.
+
+Reference docs:
+
+- Repo-specific workflow guidance: [../../.project-workflow/guidance.md](../../.project-workflow/guidance.md)
+- Project outcomes: [../../.project-workflow/CONSTITUTION.md](../../.project-workflow/CONSTITUTION.md)
+- Backlog: [../../.project-workflow/BACKLOG.md](../../.project-workflow/BACKLOG.md)
+- Active tracker: [../../.project-workflow/TRACKER.md](../../.project-workflow/TRACKER.md)
+
+Inputs:
+
+- Action: `${input:action:add|list|status|update|validate|promote}`
+- Backlog ID: `${input:id:BL-001}`
+- Title: `${input:title:}`
+- Outcome: `${input:outcome:}`
+- Type: `${input:type:Idea|Task Candidate|Epic Candidate|Discovery|Follow-Up}`
+- Priority: `${input:priority:High|Medium|Low|Unset}`
+- Status: `${input:status:Proposed|Accepted|Deferred|Rejected|Superseded|Promoted}`
+- Promotion target: `${input:promoteTo:task|epic}`
+
+Backlog purpose:
+
+- `CONSTITUTION.md` records durable product outcomes and principles.
+- `BACKLOG.md` records future intent, rough priority, options, and promotion history.
+- `TRACKER.md` and epic trackers record committed execution lifecycle state.
+- Task/epic folders record executable requirements, plans, validation evidence, QA, and retros.
+
+Rules:
+
+- Backlog use is optional. If work is already clear and immediate, `project.task` or `project.epic` may be used directly.
+- Do not use the backlog as a second active tracker.
+- `Accepted` means worth keeping or preparing; it does not mean ready to implement.
+- Promoted rows stay in the backlog with status `Promoted` and `Promoted To` set to the created task or epic ID.
+- Existing roadmap/backlog documents outside `.project-workflow/BACKLOG.md` must be preserved. Do not import or transform them automatically; create a repo-local migration task if needed.
+- Promotion requires owner confirmation. If the owner explicitly asks to accept and promote in one operation, pass `--accept`.
+
+Broad-objective workflow:
+
+1. Read project context first: `CONSTITUTION.md`, `BACKLOG.md` if present, `TRACKER.md`, active epic trackers, and `.project-workflow/guidance.md` if present.
+2. Draft one or more outcome-focused candidate rows using the canonical schema: ID, Title, Type, Priority, Status, Outcome, Promoted To, Notes.
+3. Recommend whether each candidate should remain an idea, become a task, become an epic, or require discovery.
+4. Do not create tracker rows, task folders, or epic folders while only proposing candidates.
+5. Ask for owner review before accepting rows or promoting them.
+6. If context is insufficient, ask focused questions instead of inventing strategy.
+
+CLI operations:
+
+- Initialize backlog if missing:
+
+`./.project-workflow/cli/workflow backlog init`
+
+- Add a row:
+
+`./.project-workflow/cli/workflow backlog add --title "<TITLE>" --outcome "<OUTCOME>" --type "Idea" --priority Unset`
+
+- List rows:
+
+`./.project-workflow/cli/workflow backlog list`
+
+- Update status:
+
+`./.project-workflow/cli/workflow backlog status --id BL-001 --to Accepted`
+
+- Update fields:
+
+`./.project-workflow/cli/workflow backlog update --id BL-001 --priority High --notes "<NOTES>"`
+
+- Validate backlog:
+
+`./.project-workflow/cli/workflow backlog validate`
+
+- Promote an accepted row:
+
+`./.project-workflow/cli/workflow backlog promote --id BL-001 --to task`
+
+`./.project-workflow/cli/workflow backlog promote --id BL-001 --to epic`
+
+Output:
+
+- Report the exact command run.
+- Summarize created or updated rows.
+- For promotion, report the created task or epic ID, generated files, and backlog `Promoted To` reference.
+- Run `./.project-workflow/cli/workflow doctor` after promotion or structural backlog edits and report warnings/errors.