@williambeto/ai-workflow 1.19.0 → 2.1.0

package/docs/full-documentation.md

@@ -1,661 +0,0 @@
-# AI Workflow Kit full documentation
-
-## Purpose
-
-This document is the detailed reference for **AI Workflow Kit**.
-
-Use the root `README.md` as the landing page. Use this document when you need the full repository map, workflow explanation, role model, validation model, and adoption guidance.
-
-## What AI Workflow Kit is
-
-AI Workflow Kit is a documentation-first workflow system for AI-assisted software delivery.
-
-It helps developers and teams use Codex, OpenCode, and agentic coding tools with:
-
-- clear requirements before implementation;
-- functional specifications before technical plans;
-- small PRs instead of uncontrolled generation;
-- specialist roles instead of generic assistant behavior;
-- validation evidence before approval;
-- no-regression rules;
-- local-first safety gates;
-- explicit handoffs across planning, implementation, review, validation, and release.
-
-## What AI Workflow Kit is not
-
-This repository is intentionally not:
-
-- an application starter;
-- a framework boilerplate;
-- a Nuxt, React, WordPress, Node.js, or Python production template;
-- a UI kit;
-- a design system implementation;
-- a hosted service;
-- a replacement for senior technical judgment.
-
-Stack-specific variants exist to guide workflows, not to generate complete applications.
-
-## Core philosophy
-
-Most AI coding failures come from starting too late in the workflow.
-
-Weak path:
-
-```txt
-Idea → Generate code → Review huge diff → Discover missing context
-```
-
-Preferred path:
-
-```txt
-Idea
-→ Requirement
-→ Functional specification
-→ Technical plan
-→ PR breakdown
-→ Implement one PR
-→ Review and fix
-→ Validate with evidence
-→ Ship only when ready
-```
-
-The goal is not to make AI write more code. The goal is to make AI work with clearer context, smaller scope, stronger constraints, and real validation.
-
-## Repository structure
-
-```txt
-ai-workflow/
-├── .agents/
-│   ├── napkin.md
-│   └── skills/
-├── .codex/
-│   └── prompts/
-├── .github/
-│   └── workflows/
-├── docs/
-│   └── adr/
-├── examples/
-├── harness/
-│   ├── handoffs/
-│   └── workflows/
-├── opencode/
-│   ├── agents/
-│   └── commands/
-├── prompts/
-│   └── commands/
-├── runbooks/
-├── schemas/
-├── scripts/
-├── templates/
-├── tests/
-├── variants/
-├── AGENTS.md
-├── README.md
-├── ROADMAP.md
-└── package.json
-```
-
-## Directory guide
-
-| Path | Purpose |
-| --- | --- |
-| `AGENTS.md` | Main operational contract for AI agents in this repository. |
-| [`.agents/skills/`](.agents/skills/) | Reusable specialist skill definitions. |
-| [`.agents/napkin.md`](.agents/napkin.md) | Durable project memory index. |
-| [`.codex/prompts/`](.codex/prompts/) | Compact Codex prompt entrypoints. |
-| [`docs/`](docs/) | Architecture policy, design pattern policy, ADRs, and project documentation. |
-| [`examples/`](examples/) | Documentation-only workflow examples. |
-| [`harness/`](harness/) | Workflow gates, handoff contracts, and execution harness documents. |
-| [`opencode/agents/`](opencode/agents/) | OpenCode role prompts. |
-| [`opencode/commands/`](opencode/commands/) | OpenCode command entrypoints. |
-| [`prompts/`](prompts/) | Ordered workflow prompts from bootstrap to deploy. |
-| [`runbooks/`](runbooks/) | Operational procedures for real usage. |
-| [`schemas/`](schemas/) | Lightweight JSON Schema contracts for workflow outputs. |
-| [`scripts/`](scripts/) | Validation and workflow helper scripts. |
-| [`templates/`](templates/) | Reusable document templates. |
-| [`tests/`](tests/) | End-to-end validation tests. |
-| [`variants/`](variants/) | Optional stack-specific workflow variants. |
-
-## Main workflow
-
-Use the full workflow for medium or high-risk changes:
-
-| Step | Output | Primary file |
-| ---: | --- | --- |
-| 00 | Project foundation | [`prompts/00-bootstrap-project.md`](prompts/00-bootstrap-project.md) |
-| 01 | Requirement | [`prompts/01-create-requirement.md`](prompts/01-create-requirement.md) |
-| 02 | Functional specification | [`prompts/02-create-spec.md`](prompts/02-create-spec.md) |
-| 03 | Technical plan | [`prompts/03-create-tech-plan.md`](prompts/03-create-tech-plan.md) |
-| 04 | PR breakdown | [`prompts/04-breakdown-prs.md`](prompts/04-breakdown-prs.md) |
-| 05 | Implemented PR | [`prompts/05-implement-pr.md`](prompts/05-implement-pr.md) |
-| 06 | Review and fixes | [`prompts/06-review-and-fix.md`](prompts/06-review-and-fix.md) |
-| 07 | Design pass | [`prompts/07-apply-design.md`](prompts/07-apply-design.md) |
-| 08 | Validation report | [`prompts/08-validate.md`](prompts/08-validate.md) |
-| 09 | Deploy plan | [`prompts/09-deploy.md`](prompts/09-deploy.md) |
-
-For small documentation fixes, use a proportional workflow:
-
-```txt
-Define change → Edit file → Validate Markdown/references → Review scope
-```
-
-## Codex usage
-
-For installation and first-run setup, see [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md).
-
-Codex is fully supported through shared repository rules and prompt entrypoints.
-
-Use [`AGENTS.md`](AGENTS.md) as the main operating contract and select the prompt that matches the current step.
-
-| Prompt | Purpose |
-| --- | --- |
-| [`.codex/prompts/start-project.md`](.codex/prompts/start-project.md) | Start a project workflow. |
-| [`.codex/prompts/plan-from-requirement.md`](.codex/prompts/plan-from-requirement.md) | Plan from an existing requirement. |
-| [`.codex/prompts/execute-selected-pr.md`](.codex/prompts/execute-selected-pr.md) | Execute one selected PR. |
-| [`.codex/prompts/review-implementation.md`](.codex/prompts/review-implementation.md) | Review an implementation. |
-| [`.codex/prompts/validate-work.md`](.codex/prompts/validate-work.md) | Validate work with evidence. |
-| [`.codex/prompts/orchestrate-next.md`](.codex/prompts/orchestrate-next.md) | Progress gate-based handoffs manually. (OpenCode equivalent: [`opencode/commands/orchestrate.md`](opencode/commands/orchestrate.md)) |
-| [`.codex/prompts/fix-issue.md`](.codex/prompts/fix-issue.md) | Diagnose and fix an issue. (OpenCode equivalent: [`opencode/agents/fixer.md`](opencode/agents/fixer.md)) |
-| [`.codex/prompts/autopilot.md`](.codex/prompts/autopilot.md) | Use a local-first task router. |
-| [`.codex/prompts/deploy.md`](.codex/prompts/deploy.md) | Prepare deployment readiness. |
-| [`.codex/prompts/token-economy-mode.md`](.codex/prompts/token-economy-mode.md) | Reduce output verbosity. |
-| [`.codex/prompts/minimal-context-mode.md`](.codex/prompts/minimal-context-mode.md) | Reduce input context loading. |
-| [`.codex/prompts/roadmap-audit.md`](.codex/prompts/roadmap-audit.md) | Audit roadmap state and next work. |
-
-Spec-Driven prompts:
-
-| Prompt | Purpose |
-| --- | --- |
-| [`.codex/prompts/specs/create-spec-from-requirement.md`](.codex/prompts/specs/create-spec-from-requirement.md) | Draft a testable spec from an approved requirement. |
-| [`.codex/prompts/specs/review-spec.md`](.codex/prompts/specs/review-spec.md) | Review spec readiness before technical planning. |
-| [`.codex/prompts/specs/spec-to-technical-plan.md`](.codex/prompts/specs/spec-to-technical-plan.md) | Convert an approved spec into technical planning output. |
-| [`.codex/prompts/specs/spec-to-pr-breakdown.md`](.codex/prompts/specs/spec-to-pr-breakdown.md) | Split an approved spec into small, reviewable PRs. |
-
-Codex orchestration is explicit and prompt-driven. It should follow gates manually using [`harness/workflows/multi-agent-handoff.md`](harness/workflows/multi-agent-handoff.md).
-
-## OpenCode usage
-
-For installation and first-run setup, see [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md).
-
-OpenCode is the primary integrated experience because this repository includes project configuration, command prompts, agent roles, and routing conventions.
-
-OpenCode assets:
-
-- [`opencode.jsonc`](opencode.jsonc) — project registry for commands and agents;
-- [`opencode/commands/`](opencode/commands/) — command entrypoints;
-- [`opencode/agents/`](opencode/agents/) — role prompts.
-
-| Command | Purpose |
-| --- | --- |
-| [`opencode/commands/start.md`](opencode/commands/start.md) | Start workflow discovery. |
-| [`opencode/commands/plan.md`](opencode/commands/plan.md) | Create scoped planning output. |
-| [`opencode/commands/execute.md`](opencode/commands/execute.md) | Execute one selected PR. |
-| [`opencode/commands/review.md`](opencode/commands/review.md) | Review implementation. |
-| [`opencode/commands/validate.md`](opencode/commands/validate.md) | Validate with evidence. |
-| [`opencode/commands/orchestrate.md`](opencode/commands/orchestrate.md) | Run gate-based handoff routing. |
-| [`opencode/commands/ship.md`](opencode/commands/ship.md) | Run end-to-end shipping workflow. |
-| [`opencode/commands/autopilot.md`](opencode/commands/autopilot.md) | Use a local-first task router. |
-| [`opencode/commands/deploy.md`](opencode/commands/deploy.md) | Prepare deployment readiness. |
-| [`opencode/commands/token-economy.md`](opencode/commands/token-economy.md) | Use compact output mode. |
-| [`opencode/commands/roadmap-audit.md`](opencode/commands/roadmap-audit.md) | Audit roadmap state and next work. |
-
-Spec-Driven commands:
-
-| Command | Purpose |
-| --- | --- |
-| [`opencode/commands/specs/create-spec-from-request.md`](opencode/commands/specs/create-spec-from-request.md) | Turn a vague request into a lightweight change artifact before coding. |
-| [`opencode/commands/specs/create-spec-from-requirement.md`](opencode/commands/specs/create-spec-from-requirement.md) | Draft a testable spec from an approved requirement. |
-| [`opencode/commands/specs/review-spec.md`](opencode/commands/specs/review-spec.md) | Review spec readiness before technical planning. |
-| [`opencode/commands/specs/spec-to-technical-plan.md`](opencode/commands/specs/spec-to-technical-plan.md) | Convert an approved spec into technical planning output. |
-| [`opencode/commands/specs/spec-to-pr-breakdown.md`](opencode/commands/specs/spec-to-pr-breakdown.md) | Split an approved spec into small, reviewable PRs. |
-| [`opencode/commands/specs/spec-to-tasks.md`](opencode/commands/specs/spec-to-tasks.md) | Convert approved spec into small implementation tasks with validation and evidence. |
-
-Consumer-project artifact path convention for lightweight specs:
-
-```txt
-docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
-```
-
-## OpenCode agent model
-
-OpenCode agents are operational roles. Skills are reusable capabilities. Commands are user-facing entrypoints.
-
-| Agent | Role |
-| --- | --- |
-| [`atlas`](opencode/agents/atlas.md) | Primary senior engineering partner and workflow orchestrator. |
-| [`discovery`](opencode/agents/discovery.md) | Explore project context before planning. |
-| [`spec-engineer`](opencode/agents/spec-engineer.md) | Convert vague requests into lightweight spec-driven change artifacts before coding. |
-| [`planner`](opencode/agents/planner.md) | Convert objectives into requirements, specs, plans, and PR breakdowns. |
-| [`orchestrator`](opencode/agents/orchestrator.md) | Route multi-step work across gates and specialists. |
-| [`implementer`](opencode/agents/implementer.md) | Implement scoped changes. |
-| [`fixer`](opencode/agents/fixer.md) | Diagnose and fix issues. |
-| [`reviewer`](opencode/agents/reviewer.md) | Review implementation quality and scope. |
-| [`validator`](opencode/agents/validator.md) | Run validation and collect evidence. |
-| [`release-manager`](opencode/agents/release-manager.md) | Prepare release, deployment, and rollback readiness. |
-| [`wordpress-engineer`](opencode/agents/wordpress-engineer.md) | Handle WordPress/PHP-specific workflow. |
-| [`prompt-engineer`](opencode/agents/prompt-engineer.md) | Improve prompts, commands, and agent instructions. |
-
-## Specialist skills
-
-Skills define focused behavior for AI agents. Use exactly one primary skill per task unless a supporting skill closes a concrete gap.
-
-| Skill | Use when |
-| --- | --- |
-| [`product-manager`](.agents/skills/product-manager/SKILL.md) | Clarifying requirements, users, scope, and acceptance criteria. |
-| [`tech-lead`](.agents/skills/tech-lead/SKILL.md) | Planning architecture, trade-offs, risks, and sequencing. |
-| [`pr-orchestrator`](.agents/skills/pr-orchestrator/SKILL.md) | Splitting, executing, reviewing, and summarizing small PRs. |
-| [`frontend-implementer`](.agents/skills/frontend-implementer/SKILL.md) | Frontend UI, routing, state, styling, and accessibility work. |
-| [`backend-implementer`](.agents/skills/backend-implementer/SKILL.md) | APIs, services, data, validation, auth, and server-side tests. |
-| [`tester`](.agents/skills/tester/SKILL.md) | Acceptance criteria, regression coverage, and validation evidence. |
-| [`build-and-validate`](.agents/skills/build-and-validate/SKILL.md) | Build, lint, typecheck, test, and validation failures. |
-| [`docs-writer`](.agents/skills/docs-writer/SKILL.md) | README, runbooks, prompts, templates, and documentation updates. |
-| [`deploy-engineer`](.agents/skills/deploy-engineer/SKILL.md) | Release, deployment, rollback, and CI/CD readiness. |
-| [`interface-design`](.agents/skills/interface-design/SKILL.md) | Product interface design and UI quality passes. |
-| [`minimal-context`](.agents/skills/minimal-context/SKILL.md) | Input context discipline and scoped file reading. |
-| [`napkin`](.agents/skills/napkin/SKILL.md) | Durable project memory updates. |
-| [`opencode-agent-design`](.agents/skills/opencode-agent-design/SKILL.md) | OpenCode agent, command, and routing design. |
-| [`playwright-cli`](.agents/skills/playwright-cli/SKILL.md) | Browser test workflows and Playwright evidence. |
-| [`stack-variant-creator`](.agents/skills/stack-variant-creator/SKILL.md) | Creating new stack-specific workflow variants. |
-| [`token-economy`](.agents/skills/token-economy/SKILL.md) | Compact output while preserving evidence. |
-| [`vue-nuxt`](.agents/skills/vue-nuxt/SKILL.md) | Vue/Nuxt architecture, dashboards, CRUD patterns, stores, composables, and TypeScript contracts. |
-| [`wordpress-engineer`](.agents/skills/wordpress-engineer/SKILL.md) | WordPress, WooCommerce, ACF, themes, and PHP 7-compatible work. |
-| [`seo-audit`](.agents/skills/seo-audit/SKILL.md) | Auditing SEO, AEO, and GEO signals with evidence-based findings. |
-
-## Skill routing
-
-| Expected output | Primary skill |
-| --- | --- |
-| Requirement or acceptance criteria | `product-manager` |
-| Technical plan | `tech-lead` |
-| PR breakdown | `pr-orchestrator` |
-| Frontend implementation | `frontend-implementer` |
-| Backend implementation | `backend-implementer` |
-| Test strategy or review | `tester` |
-| Command evidence or failure diagnosis | `build-and-validate` |
-| Documentation | `docs-writer` |
-| Deployment readiness | `deploy-engineer` |
-| SEO/AEO/GEO audit | `seo-audit` |
-| OpenCode agent/config design | `opencode-agent-design` |
-| Stack variant creation | `stack-variant-creator` |
-
-## Architecture and design policy
-
-Before proposing application code structure, apply [`docs/architecture-policy.md`](docs/architecture-policy.md).
-
-Required behavior:
-
-- classify work as `simple-site`, `feature-app`, `domain-app`, `package-tooling`, or `wordpress`;
-- choose the lowest-complexity architecture that fits;
-- avoid Clean/Hexagonal defaults unless escalation criteria are met;
-- do not introduce repositories, use cases, entities, DTOs, mappers, or DI by default.
-
-Before introducing formal design patterns, apply [`docs/design-patterns-policy.md`](docs/design-patterns-policy.md).
-
-Required behavior:
-
-- patterns are optional tools, not defaults;
-- justify pattern use before implementation;
-- prefer simple functions, modules, services, composables, and component composition first;
-- do not create abstractions for a single implementation without explicit justification.
-
-## Handoff and gate model
-
-The harness documents define how work moves between steps and agents:
-
-| File | Purpose |
-| --- | --- |
-| [`harness/workflows/requirement-to-pr.md`](harness/workflows/requirement-to-pr.md) | Convert requirement work into PR-ready plans. |
-| [`harness/workflows/implement-review-validate.md`](harness/workflows/implement-review-validate.md) | Move implementation through review and validation. |
-| [`harness/workflows/multi-agent-handoff.md`](harness/workflows/multi-agent-handoff.md) | Define deterministic multi-agent gate transitions. |
-| [`harness/workflows/planner-executor-workflow.md`](harness/workflows/planner-executor-workflow.md) | Separate planning and execution responsibilities. |
-| [`harness/workflows/agent-evaluation-checklist.md`](harness/workflows/agent-evaluation-checklist.md) | Evaluate whether agent output is useful, safe, scoped, and validated. |
-| [`harness/handoffs/HANDOFF.template.md`](harness/handoffs/HANDOFF.template.md) | Standard handoff packet template. |
-
-Gate transitions should be `Pass` only when required evidence exists. Otherwise they should be `Blocked` with the smallest safe fix request.
-
-## Templates
-
-Templates are reusable starting points, not completed project documents.
-
-| Template | Purpose |
-| --- | --- |
-| [`templates/AGENTS.template.md`](templates/AGENTS.template.md) | Base AI-agent instruction file. |
-| [`templates/DESIGN.template.md`](templates/DESIGN.template.md) | Design guidance template. |
-| [`templates/README.template.md`](templates/README.template.md) | Base project README. |
-| [`templates/REQUIREMENT.template.md`](templates/REQUIREMENT.template.md) | Product requirement. |
-| [`templates/SPEC.template.md`](templates/SPEC.template.md) | Functional specification. |
-| [`templates/change-proposal.template.md`](templates/change-proposal.template.md) | Lightweight change proposal/spec artifact. |
-| [`templates/TECH-PLAN.template.md`](templates/TECH-PLAN.template.md) | Technical plan. |
-| [`templates/PR-PLAN.template.md`](templates/PR-PLAN.template.md) | PR plan. |
-
-## Runbooks
-
-Runbooks are operational guides for applying the workflow.
-
-| Runbook | Purpose |
-| --- | --- |
-| [`runbooks/quick-start-guide.md`](runbooks/quick-start-guide.md) | Fastest path to first value. |
-| <!-- consolidated into quick-start-guide.md --> | |
-| [`runbooks/apply-starter-to-real-project.md`](runbooks/apply-starter-to-real-project.md) | Apply this workflow to a target project. |
-| [`runbooks/validate-starter-in-real-project.md`](runbooks/validate-starter-in-real-project.md) | Prove adoption in a real project. |
-| [`runbooks/how-to-use-skills.md`](runbooks/how-to-use-skills.md) | Choose specialist skills. |
-| [`runbooks/commands-cheatsheet.md`](runbooks/commands-cheatsheet.md) | Choose Codex/OpenCode commands. |
-| [`runbooks/spec-driven-development.md`](runbooks/spec-driven-development.md) | Run lightweight spec-first flow and artifact conventions before implementation. |
-| [`runbooks/agent-delegation-workflow.md`](runbooks/agent-delegation-workflow.md) | Use orchestrator and handoff routing. |
-| [`runbooks/use-linear-for-operational-planning.md`](runbooks/use-linear-for-operational-planning.md) | Use Linear as the operational backlog when the roadmap is too large for daily planning. |
-| [`runbooks/validation-checklist.md`](runbooks/validation-checklist.md) | Validate docs, code, PRs, builds, security, accessibility, and deploy readiness. |
-| [`runbooks/team-governance-pr-readiness.md`](runbooks/team-governance-pr-readiness.md) | Define PR readiness and approval policy. |
-| [`runbooks/deploy-checklist.md`](runbooks/deploy-checklist.md) | Prepare deploy, smoke tests, and rollback. |
-| [`runbooks/use-napkin-project-memory.md`](runbooks/use-napkin-project-memory.md) | Maintain durable project memory. |
-| [`runbooks/tutorial-walkthroughs.md`](runbooks/tutorial-walkthroughs.md) | Run self-guided tutorials or video walkthroughs. |
-| [`runbooks/publish-package-checklist.md`](runbooks/publish-package-checklist.md) | Guarded npm publish and rollback steps. |
-
-## Stack variants
-
-Variants tailor the generic workflow to specific project families without polluting the generic core.
-
-| Variant | Purpose |
-| --- | --- |
-| [`variants/nuxt/`](variants/nuxt/) | Nuxt/Vue frontend and dashboard workflow. |
-| [`variants/wordpress/`](variants/wordpress/) | WordPress/PHP workflow. |
-| [`variants/docs-only/`](variants/docs-only/) | Documentation-only repository workflow. |
-| [`variants/nodejs-api/`](variants/nodejs-api/) | Node.js API workflow. |
-| [`variants/python-api/`](variants/python-api/) | Python API workflow. |
-
-## Examples
-
-Examples demonstrate workflow outputs without becoming application boilerplates.
-
-| Example | Purpose |
-| --- | --- |
-| [`examples/nuxt-dashboard/`](examples/nuxt-dashboard/) | Nuxt dashboard workflow example with requirement, spec, plan, PR breakdown, handoff, validation, and orchestration report. |
-| [`examples/docs-only-repo/`](examples/docs-only-repo/) | Documentation-only workflow example. |
-| [`examples/react-dashboard/`](examples/react-dashboard/) | React dashboard workflow example. |
-| [`examples/wordpress-theme/`](examples/wordpress-theme/) | WordPress theme workflow example. |
-
-## Schemas
-
-Schemas are lightweight completeness contracts. They are guardrails, not heavy process requirements.
-
-| Schema | Purpose |
-| --- | --- |
-| [`schemas/requirement.schema.json`](schemas/requirement.schema.json) | Requirement output contract. |
-| [`schemas/functional-spec.schema.json`](schemas/functional-spec.schema.json) | Functional specification contract. |
-| [`schemas/technical-plan.schema.json`](schemas/technical-plan.schema.json) | Technical plan contract. |
-| [`schemas/pr-breakdown.schema.json`](schemas/pr-breakdown.schema.json) | PR breakdown contract. |
-| [`schemas/handoff.schema.json`](schemas/handoff.schema.json) | Handoff packet contract. |
-| [`schemas/validation-report.schema.json`](schemas/validation-report.schema.json) | Validation report contract. |
-| [`.workflow-state.schema.json`](.workflow-state.schema.json) | Workflow state contract. |
-
-See [`schemas/README.md`](schemas/README.md) for schema guidance.
-
-## Validation
-
-Run the complete local validation suite:
-
-```bash
-npm run validate
-```
-
-Focused checks:
-
-```bash
-npm run validate:md
-npm run validate:json
-npm run validate:refs
-npm run validate:links
-npm run validate:docs-consistency
-npm run validate:workflow
-npm run validate:schemas
-npm run validate:skills
-npm run validate:delegation
-npm run validate:structure
-npm run test:e2e
-```
-
-Validation evidence must include:
-
-- command executed;
-- command result;
-- relevant error output if any;
-- file path or line reference when useful;
-- skipped checks and why they were skipped.
-
-Invalid evidence includes:
-
-- “looks good” without support;
-- assumed success;
-- hidden skipped checks;
-- vague approval without command or manual evidence.
-
-## Git and branch safety
-
-Before edits, check branch state:
-
-```bash
-git status -sb
-```
-
-Do not edit directly on `main`. Create a scoped branch first:
-
-```bash
-git switch -c docs-short-task-slug
-```
-
-See [`docs/branch-flow.md`](docs/branch-flow.md) for canonical branch policy and [`docs/branch-flow-audit.md`](docs/branch-flow-audit.md) for audit context.
-
-Do not commit, push, merge, publish, release, or deploy unless explicitly requested.
-
-## Autopilot behavior
-
-Autopilot is a local-first workflow entrypoint. The command/prompt files are the source of truth; this section summarizes the contract.
-
-It should:
-
-- parse the user objective;
-- define the smallest safe scope;
-- choose the lightest valid route (`planner`, `orchestrator`, or specialist owner);
-- route to existing agents, prompts, skills, and workflow contracts only;
-- run branch safety checks before write operations;
-- validate proportionally to risk;
-- stop as `Blocked` when required context is missing, scope is too broad, or validation fails;
-- ask before push, publish, remote repository creation, merge PR, release, or deploy actions.
-
-It should not:
-
-- create new architecture;
-- create new agents;
-- create new skills;
-- skip gates;
-- bypass local-first safety.
-
-Expected output should include selected route, scope, active step/gate, files changed, validation commands/results, risks/open questions, and next safe step.
-
-Primary files:
-
-- [`opencode/commands/autopilot.md`](opencode/commands/autopilot.md)
-- [`.codex/prompts/autopilot.md`](.codex/prompts/autopilot.md)
-- [`opencode/agents/orchestrator.md`](opencode/agents/orchestrator.md)
-
-## Notes
-
-- The recommended install path is `npx @williambeto/ai-workflow init`. See `docs/npm-consumer-quickstart.md`.
-- AI Workflow Kit now uses `.ai-workflow/` with symlinked workflow paths as the default installation model.
-
-## Recommended tool path
-
-AI Workflow Kit works with both OpenCode and Codex.
-
-| Tool | Recommendation | Workflow style |
-| --- | --- | --- |
-| OpenCode | Best integrated experience | Commands, agents, routing, and `opencode.jsonc` automation |
-| Codex | Fully supported | `AGENTS.md`, `.codex/prompts/`, and explicit prompt-driven orchestration |
-
-OpenCode is the primary integrated experience. Codex is fully supported through the same shared rules and prompts, but the orchestration is more manual.
-
-## Adoption levels
-
-| Level | Use when | Start here |
-| --- | --- | --- |
-| Minimal | You only want prompts and templates | `prompts/`, `templates/` |
-| Operational | You want a repeatable PR workflow | `runbooks/quick-start-guide.md` |
-| Full | You want agent-based delivery | `.codex/prompts/`, `opencode/commands/` |
-| Standalone CLI | You want the default install path for another repo | `npx @williambeto/ai-workflow init --yes` |
-| Governance | You want team review and readiness policy | `runbooks/team-governance-pr-readiness.md` |
-
-## Supported project types
-
-| Project type | Support level | Useful assets |
-| --- | --- | --- |
-| Nuxt/Vue dashboards | Native high | `vue-nuxt`, `variants/nuxt/` |
-| WordPress/PHP projects | Native high | `wordpress-engineer`, `variants/wordpress/` |
-| Documentation repositories | Native high | `docs-writer`, `variants/docs-only/` |
-| Node.js APIs | Variant support | `backend-implementer`, `variants/nodejs-api/` |
-| Python APIs | Variant support | `backend-implementer`, `variants/python-api/` |
-| React/Next.js applications | Generic support | `frontend-implementer`, `interface-design` |
-| Microservices | Generic support | `backend-implementer`, `deploy-engineer` |
-
-Native high means this repository includes a dedicated skill or complete applied example. Generic support means the workflow applies, but project-specific conventions still need human judgment.
-
-## Repository status
-
-| Area | Status |
-| --- | --- |
-| Skills | Complete |
-| Prompts | Complete |
-| Codex prompt entrypoints | Complete |
-| OpenCode command entrypoints | Complete |
-| OpenCode agent roles | Complete |
-| Templates | Complete |
-| Runbooks | Complete |
-| README | Landing page |
-| AGENTS.md | Complete |
-| ROADMAP | Complete |
-| Examples | Complete (nuxt-dashboard, docs-only-repo, react-dashboard, wordpress-theme) |
-| Automated Markdown validation | Complete |
-| Stack-specific variants | Complete (Nuxt, WordPress, docs-only, Node.js API, Python API) |
-| opencode.jsonc | Added |
-| CI workflow | Added |
-| package.json / version | Added |
-| CHANGELOG | Added |
-| LICENSE | Added |
-
-## Success criteria
-
-This project is successful if it helps produce:
-
-- clearer requirements;
-- safer technical plans;
-- smaller pull requests;
-- fewer uncontrolled AI changes;
-- stronger validation before approval;
-- better Codex/OpenCode handoffs;
-- more predictable AI-assisted software delivery.
-
-## Final idea
-
-The goal is not to make AI write more code.
-
-The goal is to make AI work with clearer context, smaller scope, stronger constraints, and real validation.
-
-## Token economy and minimal context
-
-Use [`token-economy`](.agents/skills/token-economy/SKILL.md) to reduce output verbosity while preserving evidence and decisions.
-
-Use [`minimal-context`](.agents/skills/minimal-context/SKILL.md) to reduce input context loading by reading only task-relevant files.
-
-Useful entrypoints:
-
-- [`.codex/prompts/token-economy-mode.md`](.codex/prompts/token-economy-mode.md)
-- [`.codex/prompts/minimal-context-mode.md`](.codex/prompts/minimal-context-mode.md)
-- [`opencode/commands/token-economy.md`](opencode/commands/token-economy.md)
-
-## Napkin project memory
-
-Napkin is durable, discoverable project memory.
-
-Use it for reusable decisions, recurring corrections, project conventions, and operational memory. Do not use it for temporary notes or secrets.
-
-Files:
-
-- [`.agents/napkin.md`](.agents/napkin.md)
-- [`.agents/skills/napkin/SKILL.md`](.agents/skills/napkin/SKILL.md)
-- [`runbooks/use-napkin-project-memory.md`](runbooks/use-napkin-project-memory.md)
-
-## Governance
-
-Team adoption can use lightweight readiness and approval rules from [`runbooks/team-governance-pr-readiness.md`](runbooks/team-governance-pr-readiness.md).
-
-Recommended governance principles:
-
-- define Definition of Ready before implementation;
-- define Definition of Done before approval;
-- assign reviewer responsibility;
-- escalate unclear ownership;
-- keep merge authority explicit;
-- require validation evidence before approval.
-
-## Release and deployment readiness
-
-Use deployment guidance only after validation passes and the user explicitly requests release or deployment work.
-
-Primary assets:
-
-- [`prompts/09-deploy.md`](prompts/09-deploy.md)
-- [`.codex/prompts/deploy.md`](.codex/prompts/deploy.md)
-- [`opencode/commands/deploy.md`](opencode/commands/deploy.md)
-- [`runbooks/deploy-checklist.md`](runbooks/deploy-checklist.md)
-- [`.agents/skills/deploy-engineer/SKILL.md`](.agents/skills/deploy-engineer/SKILL.md)
-
-Deployment plans should include:
-
-- environment assumptions;
-- pre-deploy checks;
-- smoke tests;
-- rollback plan;
-- monitoring or verification steps;
-- explicit skipped checks.
-
-## Maintenance rules
-
-When maintaining this repository:
-
-- keep changes small and reviewable;
-- evolve file by file;
-- preserve existing patterns before adding new ones;
-- validate Markdown safety;
-- update references when files move;
-- avoid duplicated long sections that drift;
-- keep generic files framework-agnostic;
-- keep stack-specific details inside variants, examples, or skills;
-- update [`ROADMAP.md`](ROADMAP.md) when priorities change;
-- do not make commits unless explicitly requested.
-
-## Current limitations
-
-- OpenCode has the most integrated experience; Codex orchestration is more manual.
-- Stack variants guide workflow behavior but do not replace project-specific engineering decisions.
-- Public package identity is `@williambeto/ai-workflow`; historical `codex-repo-starter` references should appear only where they explain migration history or legacy submodule paths.
-
-## Recommended reading order
-
-For new users:
-
-1. `README.md`
-2. [`runbooks/quick-start-guide.md`](runbooks/quick-start-guide.md)
-3. [`runbooks/how-to-use-skills.md`](runbooks/how-to-use-skills.md)
-4. [`AGENTS.md`](AGENTS.md)
-
-For maintainers:
-
-1. [`AGENTS.md`](AGENTS.md)
-2. [`ROADMAP.md`](ROADMAP.md)
-3. [`docs/architecture-policy.md`](docs/architecture-policy.md)
-4. [`docs/design-patterns-policy.md`](docs/design-patterns-policy.md)
-5. [`harness/workflows/multi-agent-handoff.md`](harness/workflows/multi-agent-handoff.md)
-
-## Final note
-
-AI Workflow Kit should make AI-assisted delivery more deliberate, not heavier.
-
-Use the smallest workflow that protects quality for the current risk level.