@williambeto/ai-workflow 1.19.1 → 2.2.0

package/runbooks/apply-starter-to-real-project.md

@@ -1,445 +0,0 @@
-# Apply Starter to a Real Project
-
-## Purpose
-
-Use this runbook to apply `ai-workflow` to a real software project without copying everything blindly.
-
-The goal is to choose the smallest useful workflow, adapt it to the target repository, and use the starter as an operating model for discovery, planning, implementation, review, validation, release, and handoff.
-
-This starter is not application code. Do not copy it into a project as if it were a framework boilerplate.
-
-## Quick Start (5-minute onboarding)
-
-1. **Pick a real project** — identify project name, type, stack, and main goal (Step 1).
-2. **Choose adoption level** — start with Level 1 (minimal) or Level 2 (operational) from Step 3.
-3. **Select agents and skills** — use Step 4 and Step 5 tables to pick the smallest set that covers your work.
-4. **Run OpenCode smoke test** — verify `opencode.jsonc` loads correctly (Step 4 → OpenCode first-run smoke test).
-5. **Create first PR plan** — follow Step 7 to break work into small, reviewable PRs.
-
-> **Rule of thumb**: Start with Level 2 (Operational) for serious projects. Use Level 1 for bug fixes. Add skills only when the task needs them.
-
-## When to use this runbook
-
-Use this runbook when:
-
-- starting a new project;
-- auditing an existing project;
-- setting up Codex/OpenCode workflows;
-- preparing a target project;
-- creating a PR-driven implementation plan;
-- reducing repeated prompt/context setup.
-
-## Adoption principles
-
-- Do not copy everything blindly.
-- Start with the smallest useful workflow.
-- Keep project-specific rules close to the target project.
-- Use this starter as an operating model, not as application code.
-- Validate before every commit and merge.
-- Prefer small PRs.
-
-## Step 1 — Choose the target project
-
-Pick one real target project before selecting agents, skills, prompts, or runbooks.
-
-Example project types:
-
-- Nuxt dashboard;
-- WordPress site/theme/plugin;
-- frontend refactor;
-- testing automation project;
-- documentation/prompt repository.
-
-Expected output:
-
-- project name;
-- project type;
-- stack;
-- main goal;
-- current pain points;
-- constraints.
-
-Do not continue if the project goal is still broad enough to become multiple unrelated workstreams.
-
-### Fast bootstrap command
-
-Run the standalone installer in the target repository:
-
-```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
-```
-
-This installs workflow assets under `.ai-workflow/` and links expected project paths for tool compatibility.
-
-## Step 2 — Run initial discovery
-
-Use discovery to understand the project before estimating or planning implementation.
-
-Reference:
-
-```txt
-opencode/agents/discovery.md
-.codex/prompts/plan-from-requirement.md
-schemas/requirement.schema.json
-```
-
-Expected output:
-
-- discovery brief;
-- assumptions;
-- risks;
-- open questions;
-- decision whether to estimate or plan.
-
-If discovery finds missing business context, unclear ownership, unknown validation commands, or risky production constraints, record those as open questions before creating a PR plan.
-
-## Step 3 — Decide adoption depth
-
-Choose one adoption level for the project. Start lower, then expand only when the workflow proves useful.
-
-| Level | When to use | What to copy/adapt | Risk |
-| ----- | ----------- | ------------------ | ---- |
-| Level 1 — Minimal | Small bug fixes, short documentation updates, or early trials in an existing project. | `AGENTS.md`, `README.md`, `.codex/prompts/`, and `npm run validate` only if the validation scripts are copied. | May not provide enough structure for multi-PR work, team handoff, or repeatable review. |
-| Level 2 — Operational | Serious feature work, production projects, repo audits, or teams that need recurring Codex/OpenCode workflows. | `AGENTS.md`, `harness/`, `opencode/commands/`, `opencode/agents/`, selected skills, and validation scripts. | Requires project-specific adaptation; copied rules can drift if nobody owns them. |
-| Level 3 — Full workflow | Long-lived products, team workflow design, training repositories, or projects that need examples and structured contracts. | `prompts/`, `templates/`, `harness/`, `schemas/`, `examples/`, agents, skills, runbooks, and validation scripts. | Highest setup cost; can become process-heavy if copied without pruning. |
-
-Do not use Level 3 just because the starter contains more files. Use it when the target project needs a durable workflow system.
-
-## Step 4 — Select agents
-
-Agents own workflow roles and handoffs. Choose agents based on the work type, not based on how many files exist in this starter.
-
-Client/project discovery:
-
-- discovery;
-- planner.
-
-Feature delivery:
-
-- planner;
-- implementer;
-- reviewer;
-- validator;
-- release-manager.
-
-Bug fix:
-
-- fixer;
-- reviewer;
-- validator;
-- release-manager.
-
-Frontend architecture:
-
-- planner;
-- implementer;
-- reviewer;
-- validator.
-
-WordPress project:
-
-- discovery;
-- wordpress-engineer;
-- reviewer;
-- validator;
-- release-manager.
-
-Prompt/system improvement:
-
-- prompt-engineer;
-- reviewer;
-- validator;
-- release-manager.
-
-Use the fewest agents that cover the handoff. Too many agents can create duplicated analysis and unclear ownership.
-
-### OpenCode first-run smoke test
-
-If the target team will use OpenCode commands, run a one-time smoke test before execution:
-
-- verify `opencode.jsonc` is recognized by the local OpenCode setup;
-- verify configured agents load from `opencode/agents/`;
-- verify commands load from `opencode/commands/` (`start`, `plan`, `execute`, `review`, `validate`);
-- run one small cycle and capture validation evidence.
-
-Reference:
-
-```txt
-opencode/README.md
-```
-
-Do not proceed with production work until routing and prompt resolution work without manual path fixes.
-
-## Step 5 — Select skills
-
-Skills are reusable capabilities, not agents.
-
-Use skills to give Codex stronger technical behavior inside a selected task. Do not treat a skill as an owner of the whole workflow.
-
-Examples:
-
-| Project/work type | Useful skills |
-| ----------------- | ------------- |
-| Nuxt Dashboard | `vue-nuxt`, `vue-nuxt`, `frontend-implementer`, `build-and-validate` |
-| WordPress | `wordpress-engineer`, `docs-writer`, `build-and-validate`, `tester` |
-| Testing automation | `tester`, `build-and-validate` |
-| Prompt/system work | `token-economy`, `opencode-agent-design`, `pr-orchestrator`, `docs-writer` |
-| Release flow | `deploy-engineer`, `build-and-validate` |
-
-Select one primary skill for the current task. Add supporting skills only when they improve the result.
-
-## Step 6 — Create project-local rules
-
-The target project should have its own local rules.
-
-Create or adapt:
-
-- `AGENTS.md`;
-- `DESIGN.md` if UI/design rules matter;
-- `README.md`;
-- project-specific validation commands;
-- project-specific examples.
-
-Keep project-specific rules inside the target project. For example, WordPress PHP compatibility, Nuxt routing conventions, client deployment steps, and test commands should live with the project that uses them.
-
-Do not blindly copy the entire starter into every project.
-
-## Step 7 — Create a first PR plan
-
-Turn discovery into a small, reviewable implementation sequence.
-
-Reference:
-
-```txt
-harness/workflows/requirement-to-pr.md
-schemas/pr-breakdown.schema.json
-templates/PR-PLAN.template.md
-examples/nuxt-dashboard/
-```
-
-Expected output:
-
-- PR list;
-- dependencies;
-- validation per PR;
-- risks;
-- recommended first PR.
-
-The first PR should create enough value to validate the workflow without locking the project into a large refactor.
-
-## Step 8 — Execute one PR
-
-Implement only the selected PR.
-
-Reference:
-
-```txt
-opencode/agents/implementer.md
-.codex/prompts/execute-selected-pr.md
-harness/workflows/implement-review-validate.md
-```
-
-Rules:
-
-- one PR only;
-- no opportunistic refactors;
-- no regression;
-- validate before commit.
-
-If implementation reveals unrelated work, document it as a follow-up instead of adding it to the current PR.
-
-## Step 9 — Review and validate
-
-Review the implemented PR before release or merge.
-
-Reference:
-
-```txt
-opencode/agents/reviewer.md
-opencode/agents/validator.md
-.codex/prompts/review-implementation.md
-.codex/prompts/validate-work.md
-```
-
-Expected output:
-
-- verdict;
-- findings by severity;
-- commands run;
-- merge recommendation.
-
-The reviewer should identify defects and risks. The validator should confirm commands, acceptance criteria, and evidence. Do not use the reviewer as a substitute for validation.
-
-## Step 10 — Release and handoff
-
-Prepare the selected PR for merge only after review and validation are complete.
-
-Reference:
-
-```txt
-opencode/agents/release-manager.md
-```
-
-Include:
-
-- commit message;
-- PR summary;
-- merge plan;
-- post-merge validation;
-- branch cleanup;
-- documentation update.
-
-The handoff should state what changed, what was validated, what was not validated, and what follow-up work remains out of scope.
-
-### Two-account PR approval flow (private repositories)
-
-Use this flow when branch protection capabilities are limited by the repository plan.
-
-Core rules:
-
-- PR authors must not approve their own PRs.
-- Do not merge directly into `main`.
-- Require validation evidence before approval.
-- Use squash merge as the default strategy.
-
-#### Author checklist
-
-1. Create a scoped branch and implement only the selected PR.
-2. Run validation and prepare evidence.
-3. Push branch and open PR.
-4. Request review from a second account.
-
-```bash
-git switch -c <type>/<short-pr-slug>
-npm run validate
-git push -u origin <type>/<short-pr-slug>
-gh pr create --base main --title "<title>" --body "<summary-and-evidence>"
-```
-
-#### Reviewer checklist (second account)
-
-1. Review scope, risk, and evidence.
-2. Request changes for unresolved medium/high issues.
-3. Approve only when validation evidence is explicit.
-
-```bash
-gh pr checkout <pr-number>
-gh pr diff <pr-number>
-gh pr review <pr-number> --approve
-```
-
-#### Merge and cleanup checklist
-
-Use squash merge by default. Only use merge/rebase with explicit PR justification.
-
-```bash
-gh pr merge <pr-number> --squash --delete-branch
-git switch main
-git pull
-git fetch --prune
-```
-
-#### Fallback policy when formal branch protection is unavailable
-
-- Treat this workflow as mandatory team policy.
-- Block merge when reviewer approval is missing.
-- Block merge when validation evidence is missing.
-- Record exceptions in the PR description with reason and risk.
-
-## Practical adoption examples
-
-### A. Nuxt Dashboard
-
-Recommended adoption:
-
-- Level 2 or 3.
-
-Agents:
-
-- planner;
-- implementer;
-- reviewer;
-- validator;
-- release-manager.
-
-Skills:
-
-- `vue-nuxt`;
-- `vue-nuxt`;
-- `frontend-implementer`;
-- `build-and-validate`.
-
-Use Level 2 when the project already has its own examples, conventions, and validation commands. Use Level 3 when the team needs repeatable planning documents, schemas, and long-lived workflow examples.
-
-### B. WordPress project
-
-Recommended adoption:
-
-- Level 2.
-
-Agents:
-
-- discovery;
-- wordpress-engineer;
-- reviewer;
-- validator;
-- release-manager.
-
-Skills:
-
-- `wordpress-engineer`;
-- `docs-writer`;
-- `tester`;
-- `release-manager`.
-
-Keep WordPress version constraints, hosting limits, plugin rules, ACF/WooCommerce assumptions, and deployment steps in the project-local `AGENTS.md` or runbook.
-
-### C. Bug fix in existing project
-
-Recommended adoption:
-
-- Level 1 or 2.
-
-Agents:
-
-- fixer;
-- reviewer;
-- validator;
-- release-manager.
-
-Skills:
-
-- `tester`;
-- `build-and-validate`;
-- `release-manager`.
-
-Use Level 1 when the bug is isolated and validation commands are already known. Use Level 2 when the bug touches shared behavior, unclear ownership, or risky release paths.
-
-## Checklist
-
-- [ ] Target project selected.
-- [ ] Adoption level chosen.
-- [ ] Agents selected.
-- [ ] Skills selected.
-- [ ] Project-local `AGENTS.md` created/adapted.
-- [ ] Validation commands identified.
-- [ ] First PR planned.
-- [ ] First PR executed.
-- [ ] Review completed.
-- [ ] Validation passed.
-- [ ] Release/handoff completed.
-
-## Common mistakes
-
-- Copying everything into every project.
-- Using implementer before planner.
-- Using reviewer as validator.
-- Creating too many agents.
-- Skipping project-specific rules.
-- Not validating before merge.
-- Mixing discovery, estimate, and implementation in one step.
-
-## Final recommendation
-
-Start with Level 2 adoption for serious projects. Use Level 1 for small bug fixes. Use Level 3 only when building a long-lived project or team workflow.

package/runbooks/commands-cheatsheet.md

@@ -1,71 +0,0 @@
-# Command Cheat Sheet
-
-## Codex Prompt Entrypoints (`.codex/prompts/`)
-
-| Command | When to Use |
-|---------|-------------|
-| `start-project.md` | Start a new session with safe defaults (`orchestrator` with fallbacks to `discovery`, `prompt-engineer`, or `planner`). |
-| `plan-from-requirement.md` | Turn a user request or rough idea into requirement, spec, technical plan, PR breakdown, and optional handoff. |
-| `execute-selected-pr.md` | Implement one selected PR from a plan or handoff. |
-| `review-implementation.md` | Review the current implementation or diff before merging. |
-| `validate-work.md` | Validate the current repository or PR before commit or merge. |
-
-### Spec-Driven prompts (`.codex/prompts/specs/`)
-
-| Command | When to Use |
-|---------|-------------|
-| `create-spec-from-requirement.md` | Draft a testable spec from an approved requirement. |
-| `review-spec.md` | Validate spec readiness before technical plan. |
-| `spec-to-technical-plan.md` | Convert approved spec into technical plan output. |
-| `spec-to-pr-breakdown.md` | Split approved spec into small PRs for execution. |
-
-## OpenCode Commands (`opencode/commands/`)
-
-| Command | When to Use |
-|---------|-------------|
-| `start.md` | Default entrypoint; routes to appropriate starting agent (`orchestrator` by default). |
-| `ship.md` | Run low-touch end-to-end delivery with automatic delegation and required confirmations. |
-| `plan.md` | Turn a user request or rough idea into requirement, spec, tech plan, PR breakdown, and optional handoff. |
-| `execute.md` | Implement one selected PR from a plan or handoff. |
-| `review.md` | Review the current implementation or diff before merge. |
-| `validate.md` | Validate the current repository or PR before commit or merge. |
-| `orchestrate.md` | Automatically route work across agents using gate-based handoff checks. |
-| `deploy.md` | Prepare deployment readiness, rollout steps, and rollback plan. |
-
-## Usage Examples
-
-### Codex
-
-```bash
-# Start a new session
-codex .codex/prompts/start-project.md
-
-# Plan from requirement
-codex .codex/prompts/plan-from-requirement.md
-
-# Execute selected PR
-codex .codex/prompts/execute-selected-pr.md
-```
-
-### OpenCode
-
-```bash
-# Start workflow
-opencode start
-
-# Plan work
-opencode plan
-
-# Execute PR
-opencode execute
-
-```
-
-## Safety Rules
-
-- Always check branch status before making changes (`git status -sb`)
-- Never implement directly on `main`; use scoped branches
-- Validate changes before committing (`npm run validate`)
-- Keep PRs small, reviewable, and independently useful
-- Do not introduce unrelated refactors or dependency changes
-- Preserve existing behavior unless explicitly changed