project-workflow 0.2.0__py3-none-any.whl

project_workflow/codex/AGENTS.md

@@ -0,0 +1,131 @@
+# 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.
+
+## Workflow Order
+
+1. Constitution: use `project-constitution` to establish or update `.project-workflow/CONSTITUTION.md` for product outcomes.
+2. Backlog: use `project-backlog` when future intent should be captured before it becomes committed task or epic workflow state.
+3. Route: keep in-scope corrections in active work; use `project-fix` for one bounded correction
+   against delivered/accepted behavior, `project-task` for a new outcome or multiple independent
+   items, and `project-epic` for coordinated workstreams.
+4. Requirements: use `project-requirements` to capture the user story, scope, acceptance criteria,
+   open questions, decisions, and validation plan. The owner approves this envelope before planning.
+5. Planner: after approval, use `project-planner` to turn requirements into testable work items.
+6. Clarify: run `project-clarify` after planning to reconcile the plan with requirements, repo
+   constraints, and product outcomes; return to the owner only for material drift.
+7. Ready: run `task ready` and move new tasks to `Ready`. `Plan Confirmed` remains a legacy status,
+   not the default human checkpoint.
+8. Implement: use `project-implement` to make the smallest scoped code change for one work item,
+   validate it, and move it to testing.
+9. QA & Code Review: use `project-qa-review` to independently verify acceptance criteria and review
+   the code before completion.
+10. Retro: use `project-retro` after completion when there is a reusable lesson or follow-up.
+
+For multi-item orchestration, use `project-delegate` after planning. For large bodies of work, use `project-epic` to create proposal-first epic trackers and approved child tasks.
+
+Backlog is optional and sits between constitution and tracker state. Keep `.project-workflow/BACKLOG.md` for future intent, rough priority, options, and promotion history. 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.
+
+Project Workflow is owner-directed and agent-operated. The owner supplies intent, constraints, examples, decisions, and approvals; the agent runs commands, drafts artifacts, asks focused questions, validates readiness, implements, reviews, and records evidence. Do not make manual template completion the normal user path.
+
+The user's work-item label is non-binding. The agent must make and state an evidence-based routing
+recommendation. Clear authorized cases may proceed; genuinely ambiguous or materially different
+cases require one focused question. Do not reopen or rewrite completed work by default.
+
+For epic-managed work, preserve parent epic acceptance criteria coverage from the epic tracker through child requirements, child implementation, QA evidence, and closeout. New epic trackers use a `Parent ACs` field; legacy trackers may carry coverage in `Notes` as `Covers AC1, AC3`. The global tracker summarizes epic rows; epic `TRACKER.md` files own child rows, including Proposed rows.
+
+When a user asks to initialize project-workflow in a new repository, run the canonical UVX init command from that repository root:
+
+```bash
+uvx --from project-workflow==0.2.0 project init
+```
+
+When a user asks to update, refresh, reinstall, align, or upgrade an existing repository, use canonical UVX upgrade instead; do not run init first:
+
+```bash
+uvx --from project-workflow==0.2.0 project upgrade
+```
+
+Add `--agent codex`, `--agent cursor`, `--agent claude-code`, or `--agent github-copilot` for the target mode. Canonical UVX upgrade obtains current software and plans managed assets and repository schema together. Use `--yes` for an authorized non-interactive one-command apply, or `--plan --format json` followed by `--apply --plan-fingerprint <SHA256>` when automation requires separate review.
+
+## Workflow Skill Map
+
+- If the user asks to create, update, review, or align the product constitution, use `.agents/skills/project-constitution/SKILL.md`.
+- If the user asks to capture, refine, validate, accept, defer, reject, supersede, or promote future project intent before task/epic execution, use `.agents/skills/project-backlog/SKILL.md`.
+- If the user asks to create a task, story, feature folder, tracker row, or new project-workflow item, use `.agents/skills/project-task/SKILL.md`.
+- If the user reports a bounded post-completion defect, regression, change request, incident, or
+  hotfix, or asks whether work should be a Fix, use `.agents/skills/project-fix/SKILL.md`.
+- If the user asks to create, decompose, approve, or scaffold epic-managed work, use `.agents/skills/project-epic/SKILL.md`.
+- If the user asks to capture requirements, define scope, write acceptance criteria, record open questions, or prepare a validation plan, use `.agents/skills/project-requirements/SKILL.md`.
+- If the user asks to plan implementation, break requirements into phases, or create testable work items, use `.agents/skills/project-planner/SKILL.md`.
+- If the user asks to resolve ambiguity, reconcile conflicting requirements, or decide between unclear options, use `.agents/skills/project-clarify/SKILL.md`.
+- If the user asks to implement a planned project-workflow item, use `.agents/skills/project-implement/SKILL.md`.
+- If the user asks to coordinate or run multiple planned work items, use `.agents/skills/project-delegate/SKILL.md`.
+- If the user asks for QA, code review, verification, release readiness, or completion approval, use `.agents/skills/project-qa-review/SKILL.md`.
+- If the user asks for a retro, retrospective, lessons learned, convention updates, agent updates, prompt updates, or post-completion cleanup, use `.agents/skills/project-retro/SKILL.md`.
+- If a task-specific workflow is requested but the task folder does not exist, run `project-task` first before requirements, planning, clarification, implementation, review, or retro.
+- Do not skip directly to planning or implementation when requirements are missing, ambiguous, or not accepted as explicit risks.
+
+## Drift Gate Requirements
+
+- Before implementation-oriented work, record one owner-approved requirements/AC envelope with `task approve-requirements` or `epic approve-requirements`. Do not treat an agent draft, silence, or implementation request as approval.
+- Do not ask for repeated generic approval when work remains inside the unchanged approved envelope. Fix concrete drift/evidence gaps directly, and ask the owner only for material scope changes, amendments, deviations, deferrals, artifact identity changes, or proof-obligation changes.
+- For pre-existing work, use `task adopt` or `epic adopt`; pre-adoption inferred evidence remains untrusted until refreshed.
+- New/adopted epics require non-placeholder `EPIC-CONTRACT.md` before decomposition, child approval/scaffolding, or movement into `Ready`/`In Progress`.
+- Epic child rows must come from `DECOMPOSITION.md` or an approved `AMENDMENTS.md` record. Direct tracker edits outside that authority cannot advance through approval, scaffold, readiness, Review, or Complete gates.
+- Scaffolded epic children inherit parent AC coverage, child charters, proof ownership, artifact targets, invalid substitutes, and child-local `EVIDENCE.json`.
+- If requirements, acceptance criteria, child charters, epic contracts, or material claims trigger a proof recipe, structured evidence is required. QA prose, code review, tests, builds, surrogate surfaces, and wrong target/source pairs are invalid substitutes where the recipe requires stronger proof.
+- Visual/reference fidelity requires calibration before implementation and rendered comparison against the delivered user-facing artifact before Review/Complete. Runtime target/source proof requires the exact execution target, source/artifact under test, observation method, and positive proof that the target used that source.
+
+## CLI Requirements
+
+- Treat `.project-workflow/cli/workflow` as the authoritative way to perform operations it supports.
+- Use the CLI for backlog row creation, status changes, validation, and promotion. Do not hand-edit backlog lifecycle state when the CLI can do it.
+- Use the CLI for task scaffolding and tracker-safe task creation. Do not manually create task folders, starter `REQUIREMENTS.md`, starter `IMPLEMENTATION.md`, or tracker rows when the CLI can do it.
+- Use the CLI for Fix scaffolding, triage, lifecycle, promotion, and closeout. Keep Fix records under
+  `.project-workflow/tasks/FIX-<ID>-<Suffix>/FIX.md` and in the one global tracker; do not create a
+  separate Fix tracker or top-level fixes directory.
+- Run project-workflow CLI commands from the repository root.
+- If a selected project-workflow skill documents a CLI command, run that command instead of recreating its behavior manually.
+- If the CLI does not support the selected workflow step, follow the selected skill and update the relevant Markdown files directly.
+- If the CLI command fails, stop and report the failure before attempting a manual fallback.
+
+## Codex Usage
+
+- Use the repo-scoped skills in `.agents/skills/project-*` when the user asks for project workflow steps, even when the user asks in natural language rather than naming the skill.
+- Read `.project-workflow/guidance.md` before changing workflow state when the file exists.
+- For broad future objectives, use `project-backlog` to draft outcome-focused backlog candidates from project context. Do not create tracker rows, task folders, or epic folders until the owner accepts or promotes the row.
+- 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.
+- 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.
+- When planning epic-managed child tasks, keep both the child AC IDs and parent epic AC coverage visible in requirements, implementation rows, validation evidence, and QA notes.
+- Before implementation-oriented status transitions, run readiness gates where available: `task ready`, `epic ready`, or `epic ready-child`. If a gate fails, remediate repo-gatherable gaps directly and ask the owner only for decisions, missing product context, or material authority changes listed above.
+- Owner approval of requirements/ACs occurs before planning. After approval, run Planner,
+  post-plan Clarify, `task ready`, and move to `Ready` autonomously unless setup-only scope,
+  material drift, exceptional authority, or optional requested/high-risk plan review requires a pause.
+- 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 a new task to `Analysing` only after its requirements/AC approval envelope is recorded.
+- Move a planned and clarified new task to `Ready` after `task ready` passes. `Plan Confirmed` is
+  supported for legacy tasks.
+- 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/codex/skills/project-backlog/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: project-backlog
+description: Use when capturing, refining, validating, or promoting optional project-workflow backlog items before they become task or epic workflow state.
+---
+
+# Project Backlog
+
+Capture future intent in `.project-workflow/BACKLOG.md` before it becomes executable task or epic workflow state.
+
+## Invocation Rules
+
+- Use this skill when the user asks to create, review, refine, validate, accept, defer, reject, supersede, or promote project backlog items.
+- Read `.project-workflow/guidance.md` if present, `.project-workflow/CONSTITUTION.md`, `.project-workflow/BACKLOG.md` if present, `.project-workflow/TRACKER.md`, and active epic trackers before drafting candidates from a broad objective.
+- Backlog is optional. If the user gives clear immediate implementation scope, `project-task` or `project-epic` can be used directly.
+- Do not use backlog rows as implementation lifecycle state.
+
+## Required Files
+
+- `.project-workflow/BACKLOG.md`
+- `.project-workflow/CONSTITUTION.md` if present
+- `.project-workflow/TRACKER.md`
+- `.project-workflow/guidance.md` if present
+
+## Backlog Model
+
+- `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.
+
+Allowed type values: `Idea`, `Task Candidate`, `Epic Candidate`, `Discovery`, `Follow-Up`.
+
+Allowed priority values: `High`, `Medium`, `Low`, `Unset`.
+
+Allowed status values: `Proposed`, `Accepted`, `Deferred`, `Rejected`, `Superseded`, `Promoted`.
+
+`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.
+
+## Workflow
+
+1. For broad objectives, read project context first and draft outcome-focused candidate rows.
+2. Recommend whether each candidate should remain an idea, become a task, become an epic, or require discovery.
+3. Do not create tracker rows, task folders, or epic folders while only proposing backlog candidates.
+4. Ask for owner review before accepting or promoting rows.
+5. If context is insufficient, ask focused questions instead of inventing strategy.
+6. Use the CLI for deterministic row operations.
+
+## CLI
+
+Initialize backlog if missing:
+
+```bash
+./.project-workflow/cli/workflow backlog init
+```
+
+Add a row:
+
+```bash
+./.project-workflow/cli/workflow backlog add --title "<TITLE>" --outcome "<OUTCOME>" --type "Idea" --priority Unset
+```
+
+List rows:
+
+```bash
+./.project-workflow/cli/workflow backlog list
+```
+
+Update status:
+
+```bash
+./.project-workflow/cli/workflow backlog status --id BL-001 --to Accepted
+```
+
+Update fields:
+
+```bash
+./.project-workflow/cli/workflow backlog update --id BL-001 --priority High --notes "<NOTES>"
+```
+
+Validate backlog:
+
+```bash
+./.project-workflow/cli/workflow backlog validate
+```
+
+Promote an accepted row:
+
+```bash
+./.project-workflow/cli/workflow backlog promote --id BL-001 --to task
+./.project-workflow/cli/workflow backlog promote --id BL-001 --to epic
+```
+
+Use `--accept` only when the owner explicitly confirms accepting and promoting in one operation.
+
+## Output
+
+- Report commands run.
+- Summarize created or updated rows.
+- For promotion, report the created task/epic ID and generated files.
+- Run `./.project-workflow/cli/workflow doctor` after promotion or structural backlog edits and report warnings/errors.

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

@@ -0,0 +1,47 @@
+---
+name: project-clarify
+description: Use when project-workflow requirements, implementation plan, repo constraints, or user intent conflict or need clarification.
+---
+
+# Project Clarify
+
+Resolve ambiguity before planning or implementation continues. Also run this skill after Planner
+as the normal autonomous consistency pass.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks to clarify, resolve ambiguity, reconcile conflicting requirements, or decide between unclear options 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 when a tracked task is needed.
+- Clarification is a document workflow unless the CLI adds an explicit clarify command.
+
+## Required Files
+
+- `.project-workflow/tasks/<TASK>/REQUIREMENTS.md`
+- `.project-workflow/tasks/<TASK>/IMPLEMENTATION.md`
+- `.project-workflow/CONSTITUTION.md` if present
+- Repo instruction files such as `AGENTS.md` or `.github/copilot-instructions.md`
+
+## Workflow
+
+1. Read the `## User Story` section from `IMPLEMENTATION.md`.
+2. Read `REQUIREMENTS.md` and treat it as the source of truth for agreed outcomes and decisions.
+3. Cross-check for ambiguities or conflicts that affect scope, safety, security, billing, data correctness, validation, or user-visible behavior.
+4. If the user story is missing or unusable, stop and direct the user to run requirements capture first.
+5. Record each ambiguity in `REQUIREMENTS.md` as a numbered open question with:
+   - the conflict or missing decision
+   - why it matters
+   - 2 to 4 actionable options
+6. Ask one unresolved question at a time unless the user explicitly wants batching.
+7. After the user answers, immediately update `REQUIREMENTS.md` decisions and open questions.
+8. Preserve existing acceptance criteria IDs (`AC1`, `AC2`, etc.) when updating
+   requirements. Do not renumber ACs unless the user explicitly approves that
+   requirements change.
+9. Keep `IMPLEMENTATION.md` aligned with confirmed decisions, including any
+   AC-to-task mapping affected by the decision.
+10. Repeat until no unresolved blocking questions remain or the user explicitly accepts remaining risks.
+11. During a post-plan pass, resolve implementation-detail inconsistencies inside the approved
+    envelope autonomously. If resolution changes requirements, ACs, proof obligations, artifact
+    identity, or scope materially, return the changed envelope to the owner for re-approval.
+12. When the post-plan pass is clean, run `task ready`, move the task to `Ready`, and continue when
+    implementation is authorized.

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

@@ -0,0 +1,62 @@
+---
+name: project-constitution
+description: Use when creating or refining .project-workflow/CONSTITUTION.md with stable product outcomes for a repository.
+---
+
+# Project Constitution
+
+Create or update the product outcome guide for the repository.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for project-workflow constitution work, 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.
+- Do not use the CLI for constitution work unless `.project-workflow/cli/workflow` adds an explicit constitution command.
+- If the user asks for implementation or workflow rules while discussing the constitution, put those rules in `.project-workflow/guidance.md` rather than `.project-workflow/CONSTITUTION.md`.
+
+## Required Context
+
+Read these when present:
+
+- `README.md`
+- `.project-workflow/TRACKER.md`
+- `.project-workflow/guidance.md`
+- `.project-workflow/CONSTITUTION.md`
+- `AGENTS.md`
+- `.github/copilot-instructions.md`
+- Product docs under `docs/**`, `specs/**`, `product/**`, or `roadmap/**`
+
+## Workflow
+
+1. Summarize current product intent from the repo and user brief.
+2. If the brief is missing or too vague, ask the minimum questions needed.
+3. Create or update `.project-workflow/CONSTITUTION.md`.
+4. Keep the constitution outcome-focused and stable. Do not include framework choices, lint rules, folder layouts, or implementation details.
+5. Preserve useful existing content while removing technical directives.
+6. Use this structure:
+
+```md
+# Constitution
+
+## Mission
+
+- <What this project exists to achieve>
+
+## Target Users
+
+- <Primary users>
+
+## Core Outcomes
+
+- <Outcome 1>
+
+## Product Principles
+
+- <Principle>
+
+## Non-Goals
+
+- <What this project should not optimize for>
+```
+
+7. If technical workflow guidance is missing, offer to add it to `.project-workflow/guidance.md` rather than the constitution.

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

@@ -0,0 +1,38 @@
+---
+name: project-delegate
+description: Use when coordinating multiple planned project-workflow work items with sequential or dependency-aware parallel execution.
+---
+
+# Project Delegate
+
+Coordinate multiple work items from an existing project-workflow implementation plan.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks to delegate, coordinate, batch, parallelize, or run multiple planned work items.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- Requirements, clarification, and planning must already be complete before delegation.
+- Delegation routes each eligible work item through `project-implement`; it does not bypass validation, QA/code review, or retro.
+
+## 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`
+
+## Workflow
+
+1. Identify the task and the requested work items from the user prompt or `IMPLEMENTATION.md`.
+2. Read requirements and implementation plan before launching any work.
+3. Validate the delegation mode:
+   - `sequential` when order matters or mode is omitted
+   - `parallel` only when dependencies are explicit and independent items can safely run together
+4. Validate dependency maps strictly:
+   - no unknown work item IDs
+   - no self-dependencies
+   - no cycles
+5. Route each eligible item through `project-implement` with a clear scope boundary.
+6. Use fail-fast launch behavior for new items while allowing in-flight work to finish and report results.
+7. After delegated implementation reaches `Testing`, run `project-qa-review` before completion.
+8. After completion, run `project-retro` for durable convention or agent updates.

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

@@ -0,0 +1,121 @@
+---
+name: project-epic
+description: Use when creating, decomposing, approving, or scaffolding proposal-first project-workflow epics.
+---
+
+# Project Epic
+
+Manage proposal-first epic work under `.project-workflow/tasks/`.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks for an epic, epic decomposition, proposed child work, approval of epic rows, or scaffolding an approved epic child task.
+- Read `AGENTS.md` and `.project-workflow/guidance.md` if present, then follow the project-workflow managed block and CLI requirements.
+- Use the local workflow CLI for every supported epic operation.
+- Do not scaffold child task folders until the relevant epic tracker row is `Approved`.
+
+## Workflows
+
+Create a new epic:
+
+```bash
+./.project-workflow/cli/workflow epic init --title "<TITLE>"
+```
+
+Decompose an epic into proposed child rows only:
+
+```bash
+./.project-workflow/cli/workflow epic approve-requirements --epic-id <EPIC-ID> --approved-by "<OWNER>" --source "<APPROVAL SOURCE>"
+./.project-workflow/cli/workflow epic decompose --epic-id <EPIC-ID> --limit 5 --type Task
+```
+
+Approve one proposed child row:
+
+```bash
+./.project-workflow/cli/workflow epic approve --epic-id <EPIC-ID> --id <TASK-ID>
+```
+
+Scaffold one approved child row:
+
+```bash
+./.project-workflow/cli/workflow epic scaffold-child --epic-id <EPIC-ID> --id <TASK-ID>
+```
+
+Scaffold one approved child row with a branch from an existing epic branch:
+
+```bash
+./.project-workflow/cli/workflow epic scaffold-child --epic-id <EPIC-ID> --id <TASK-ID> --create-branch --epic-branch <EPIC-BRANCH>
+```
+
+Move one epic tracker row through lifecycle statuses:
+
+```bash
+./.project-workflow/cli/workflow epic status --epic-id <EPIC-ID> --id <TASK-ID> --to Testing
+./.project-workflow/cli/workflow epic status --epic-id <EPIC-ID> --id <TASK-ID> --to Review
+./.project-workflow/cli/workflow epic status --epic-id <EPIC-ID> --id <TASK-ID> --to Complete
+```
+
+Generate an epic acceptance audit:
+
+```bash
+./.project-workflow/cli/workflow epic audit --epic-id <EPIC-ID>
+```
+
+Validate epic requirements before decomposition:
+
+```bash
+./.project-workflow/cli/workflow epic ready --epic-id <EPIC-ID>
+```
+
+Move the global epic row through the minimal epic lifecycle:
+
+```bash
+./.project-workflow/cli/workflow epic lifecycle --epic-id <EPIC-ID> --to Ready
+./.project-workflow/cli/workflow epic lifecycle --epic-id <EPIC-ID> --to "In Progress"
+./.project-workflow/cli/workflow epic lifecycle --epic-id <EPIC-ID> --to Closeout
+```
+
+Validate one child task before implementation/testing:
+
+```bash
+./.project-workflow/cli/workflow epic ready-child --epic-id <EPIC-ID> --id <TASK-ID>
+```
+
+Validate epic closeout, optionally completing the global epic row when gates pass:
+
+```bash
+./.project-workflow/cli/workflow epic closeout --epic-id <EPIC-ID> [--complete]
+```
+
+## Rules
+
+- `epic init` creates an epic `REQUIREMENTS.md`, `EPIC-CONTRACT.md`, epic `TRACKER.md`, `DEFERRALS.md`, `AMENDMENTS.md`, `RETRO.md`, and `ACCEPTANCE-MAP.md`.
+- `ACCEPTANCE-MAP.md` is a working parent AC coverage view derived from requirements, epic tracker rows, deferrals, and child evidence. Epic lifecycle commands refresh it when coverage state changes.
+- Epic acceptance criteria should use stable IDs (`AC1`, `AC2`, etc.).
+- `epic ready` must pass before decomposition; if it fails, ask the owner only for missing product decisions/context and record answers in `REQUIREMENTS.md`.
+- `epic approve-requirements` records the owner-approved authority envelope once requirements/ACs are ready. Do not require repeated owner approval for unchanged child rows inside that envelope.
+- Approval gates are drift checks. If a gate fails, fix the concrete stale-requirements, out-of-envelope, or evidence gap unless an actual amendment/deviation decision is needed.
+- `EPIC-CONTRACT.md` records sources of truth, invalid substitutes, invariants, artifact targets, and parent AC proof owners. New/adopted epics must replace placeholder contract content before decomposition, child approval/scaffolding, or movement into `Ready`/`In Progress`.
+- `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`.
+- `epic decompose` writes Proposed child rows and `DECOMPOSITION.md`, the approved child-row authority plan. It does not create child task folders.
+- If requirements include a `Proposed Child Work` table, `epic decompose` uses that owner-reviewed decomposition before falling back to generated requirement/AC candidates.
+- `epic decompose` reads `.project-workflow/config.json` namespace and ID generation guidance by default and may produce mixed child prefixes such as `MCP-001` or `UI-K7F3Q`; use `--prefix <PREFIX>` only for an explicitly homogeneous batch.
+- 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`.
+- `epic approve`, `epic scaffold-child`, `epic ready-child`, and `epic status` reject child rows whose ID, title, or parent AC coverage does not match `DECOMPOSITION.md`; matching rows inside the plan do not need separate per-row owner approval.
+- `epic amend` records an owner-approved amendment in `AMENDMENTS.md` and appends the matching Proposed child row. Use it for mid-epic reactive fixes, new child work, or material changes outside the approved decomposition plan; direct tracker edits remain blocked.
+- `epic adopt` brings pre-existing epics under current approval gates with a `Legacy Adoption` block. Pre-adoption inferred evidence is untrusted unless `--evidence-refreshed` is used after proof has been rerun.
+- `epic scaffold-child` only accepts `Approved` child rows and moves them to `In Progress` after scaffold. It copies parent AC coverage plus a contract-derived `Child Charter` into the child docs.
+- `epic scaffold-child` also creates child-local `EVIDENCE.json`. Fill it when requirements or material claims trigger a proof recipe.
+- Built-in proof recipes are `visual-reference-fidelity`, `external-contract-alignment`, `deployed-artifact-alignment`, `runtime-target-source`, and `responsive-visual-behavior`.
+- When a proof recipe is triggered, `epic status` blocks `Review`/`Complete`, `epic audit` refuses parent AC credit, and `doctor` fails invalid current states until `EVIDENCE.json` has passing structured claim records with recipe-specific fields and evidence artifacts.
+- Invalid substitutes are rejected. Visual/reference fidelity needs rendered comparison against the delivered user-facing artifact, not code review, tests, build output, or surrogate surfaces. Runtime target/source proof needs the exact execution target, source/artifact under test, observation method, and positive proof that the target used that source.
+- `epic status` moves planned child rows through `Testing`, `Review`, and `Complete`; `Complete` requires QA/code-review evidence and parent AC evidence.
+- Scaffolded epic child task docs must include parent AC coverage, child charter, and parent AC evidence sections. Their implementation plans must map every task row to one or more stable child AC IDs and keep the parent AC mapping visible.
+- `epic ready-child` must pass before implementation/testing; if it fails, remediate missing child requirements, planning, validation, parent AC coverage, or owner decisions first.
+- 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; the acceptance map is the in-progress coverage view.
+- `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.
+- `RETRO.md` must record lessons, follow-up tasks, deferrals, and missed in-scope work before closeout. Explicit `None.` entries are valid when there is nothing to report.
+- Child IDs remain globally unique within their configured task prefix namespaces across standalone and epic-managed work.
+- When `--create-branch` is used, the epic branch must already exist; do not fall back to a base branch.
+- After any epic tracker or child scaffold change, run `./.project-workflow/cli/workflow doctor` and report workflow-state warnings or errors.

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

@@ -0,0 +1,49 @@
+---
+name: project-fix
+description: Use when routing or managing a bounded post-completion defect, regression, change request, incident, or hotfix.
+---
+
+# Project Fix
+
+Manage one bounded post-completion correction using the lightweight Fix subtype. Fixes share
+`.project-workflow/tasks/` and `.project-workflow/TRACKER.md` with tasks and epics and use one
+`FIX.md`; never create a second fix directory tree or tracker.
+
+## Routing
+
+- Keep in-flight, in-scope corrections in the active task or epic child.
+- Choose Fix for one bounded correction against delivered/accepted behavior.
+- Choose Task for a new outcome, material product decision/discovery, or multiple independent
+  work items.
+- Choose Epic for several coordinated outcomes/workstreams.
+- Treat the user's label as evidence, not a binding classification. State the rationale and
+  proceed when clear and authorized; ask one focused question when materially ambiguous.
+- Do not reopen completed work by default. Link it if identified; otherwise record
+  `Not identified`, the delivered baseline, and report evidence without exhaustive archaeology.
+
+## Commands
+
+```bash
+./.project-workflow/cli/workflow fix init --title "<TITLE>"
+./.project-workflow/cli/workflow fix triage --id <FIX-ID>
+./.project-workflow/cli/workflow fix status --id <FIX-ID> --to "In Progress"
+./.project-workflow/cli/workflow fix status --id <FIX-ID> --to Testing
+./.project-workflow/cli/workflow fix status --id <FIX-ID> --to Review
+./.project-workflow/cli/workflow fix close --id <FIX-ID> --disposition Fixed --decision "<SUMMARY>" --closed-by "<IDENTITY>"
+./.project-workflow/cli/workflow fix promote --id <FIX-ID> --to task --reason "<WHY>" --promoted-by "<IDENTITY>"
+```
+
+Complete the single `FIX.md` before triage. Classify the work as `Defect`, `Regression`,
+`Change Request`, or `Incident`; use `Mode: Hotfix` only for emergency sequencing. Capture
+severity, impact, urgency, owner, risk, rollback/containment, related work, primary repo, repos
+touched, branch/PR/evidence links, verification plan, regression evidence, and residual risk.
+
+A normal Fix must pass `fix triage` before implementation. A Hotfix may bypass `Ready` only when
+the emergency minimum safety packet validates. Promote work that no longer fits a bounded Fix.
+Run `doctor` after scaffold and lifecycle changes.
+
+Use `fix close` with `Duplicate`, `Rejected`, or `Deferred` to record a non-delivery terminal
+decision as `N/A`; do not move directly to `N/A` without its disposition and audit details.
+
+Do not require a retro for every Fix. Route a repeatable workflow, process, quality, or prevention
+gap to a retro or explicit follow-up task without reopening completed originating work.

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

@@ -0,0 +1,46 @@
+---
+name: project-implement
+description: Use when implementing one project-workflow work item with requirements alignment, tracker updates, validation, and concise reporting.
+---
+
+# Project Implement
+
+Implement one scoped work item from a project-workflow task and move it to testing.
+
+## Invocation Rules
+
+- Use this skill whenever the user asks to implement a project-workflow task or planned 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.
+- If the task folder does not exist, use `project-task` first so the CLI creates the required files and tracker row.
+- If requirements or implementation tasks are missing, use `project-requirements` and `project-planner` before coding.
+- Use the CLI for any supported tracker-safe operation before editing Markdown manually.
+
+## 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`
+
+## Workflow
+
+1. Infer the task ID from the user prompt or current branch if possible. Ask only if it cannot be inferred.
+2. Infer the work item from the user prompt or the next `To Do` task in `IMPLEMENTATION.md`. Ask only if ambiguous.
+3. Read `REQUIREMENTS.md` and `IMPLEMENTATION.md` before editing code.
+4. Run `./.project-workflow/cli/workflow task ready --id <TASK-ID>` before coding. If approval is missing or stale after requirements are ready, record the single owner approval envelope with `task approve-requirements`; for pre-existing legacy tasks use `task adopt` and treat pre-adoption evidence as untrusted until refreshed. Otherwise remediate the listed drift/evidence gaps without asking for generic approval.
+5. Restate the selected work item and scope boundary.
+6. Map each planned change to the relevant AC IDs. If a change does not map,
+   stop and ask for direction.
+7. Ensure the new-task lifecycle is `Ready` (or legacy `Plan Confirmed`) after the post-plan
+   clarification/readiness pass, then run
+   `./.project-workflow/cli/workflow task status --id <TASK-ID> --to "In Progress"` before coding.
+   Do not ask for repeated approval for unchanged work inside the approved envelope.
+8. Make the smallest safe code change that satisfies the selected work item.
+9. Add or update tests when appropriate.
+10. Run relevant automated checks and any required manual verification steps.
+11. Run `./.project-workflow/cli/workflow task status --id <TASK-ID> --to Testing` after implementation and validation have run.
+12. Run `./.project-workflow/cli/workflow doctor` and report workflow-state warnings or errors.
+13. Do not set status to `Complete`; completion is owned by `project-qa-review` after QA/code review passes and the user explicitly asks.
+14. Report changed files, validation results, remaining risks, and that `project-qa-review` is the next required lifecycle step.
+
+If requirements conflict with repo constraints or validation is not testable, stop and use `project-clarify`.