@williambeto/ai-workflow 1.19.1 → 2.2.0

package/docs/setup-codex-opencode.md

@@ -1,313 +0,0 @@
-# Setup Codex and OpenCode
-
-## Purpose
-
-This guide explains how to install and start using Codex or OpenCode with **AI Workflow Kit**.
-
-Use this when you need the tool setup path before running the workflow in this repository or in a target project.
-
-## Recommendation
-
-AI Workflow Kit works with both OpenCode and Codex.
-
-Recommended path:
-
-- Use **OpenCode** for the best integrated experience with commands, agents, routing, and `opencode.jsonc`.
-- Use **Codex** when you want OpenAI's terminal coding agent and prefer explicit prompt-driven workflow control.
-
-Summary:
-
-| Tool | Best for | Workflow style |
-| --- | --- | --- |
-| OpenCode | Full local workflow automation | Commands, agents, routing, project config |
-| Codex | OpenAI CLI workflow | `AGENTS.md`, `.codex/prompts/`, manual gate progression |
-
-## Before installing
-
-Recommended prerequisites:
-
-- Git installed;
-- Node.js/npm available for repository validation commands;
-- a terminal environment that can run local project commands;
-- access to the AI provider account or API key required by the tool you choose.
-
-Security notes:
-
-- Do not paste secrets into prompts unless required and safe.
-- Do not commit `.env` files or credentials.
-- Prefer provider sign-in flows or environment variables for credentials.
-- Review generated changes before running destructive commands.
-
-## Install OpenCode
-
-OpenCode is an open source AI coding agent available as a terminal interface, desktop app, or IDE extension.
-
-Install with the official script:
-
-```bash
-curl -fsSL https://opencode.ai/install | bash
-```
-
-Alternative install with npm:
-
-```bash
-npm install -g opencode-ai
-```
-
-Alternative install with Homebrew:
-
-```bash
-brew install anomalyco/tap/opencode
-```
-
-On Windows, OpenCode recommends WSL for the best terminal experience.
-
-## Configure OpenCode
-
-Start OpenCode:
-
-```bash
-opencode
-```
-
-Connect a provider from the OpenCode TUI:
-
-```txt
-/connect
-```
-
-Follow the provider sign-in/API key flow in OpenCode.
-
-Then initialize OpenCode in a project:
-
-```txt
-/init
-```
-
-OpenCode may create or update an `AGENTS.md` file. Commit project-level agent instructions when they are intentional and safe.
-
-## Use AI Workflow Kit with OpenCode
-
-OpenCode is the most integrated path because AI Workflow Kit can install or reference OpenCode commands, agents, and config.
-
-For most projects, use the standalone CLI first:
-
-```bash
-npx @williambeto/ai-workflow init --yes --profile=operational
-npx @williambeto/ai-workflow doctor
-```
-
-The CLI creates or merges a project-root `opencode.jsonc`. That generated config is the file OpenCode reads in the target project. The repository-root `opencode.jsonc` is the reference config used by this kit itself.
-
-Repository reference assets:
-
-The paths below are shown from the repository root so they also work with this repository's reference validator.
-
-- [`opencode.jsonc`](opencode.jsonc);
-- [`opencode/commands/`](opencode/commands/);
-- [`opencode/agents/`](opencode/agents/);
-- [`opencode/agents/orchestrator.md`](opencode/agents/orchestrator.md);
-- specialist skills in [`.agents/skills/`](.agents/skills/).
-
-Common OpenCode commands:
-
-| Command file | Use when |
-| --- | --- |
-| [`opencode/commands/start.md`](opencode/commands/start.md) | Starting workflow discovery. |
-| [`opencode/commands/plan.md`](opencode/commands/plan.md) | Creating a plan from a requirement. |
-| [`opencode/commands/execute.md`](opencode/commands/execute.md) | Implementing one selected PR. |
-| [`opencode/commands/review.md`](opencode/commands/review.md) | Reviewing implementation. |
-| [`opencode/commands/validate.md`](opencode/commands/validate.md) | Validating work with evidence. |
-| [`opencode/commands/orchestrate.md`](opencode/commands/orchestrate.md) | Running gate-based handoff routing. |
-| [`opencode/commands/ship.md`](opencode/commands/ship.md) | Running the end-to-end shipping workflow. |
-| [`opencode/commands/autopilot.md`](opencode/commands/autopilot.md) | Routing a local-first task through existing workflow assets. |
-| [`opencode/commands/deploy.md`](opencode/commands/deploy.md) | Preparing deployment readiness. |
-
-Recommended first OpenCode workflow:
-
-```txt
-/start
-→ /plan
-→ /execute
-→ /review
-→ /validate
-```
-
-Use `/ship` only when you want an end-to-end workflow and are ready for gate-based progression.
-
-## Install Codex
-
-Codex CLI is OpenAI's coding agent that runs locally in your terminal.
-
-Install with npm:
-
-```bash
-npm install -g @openai/codex
-```
-
-Alternative install with Homebrew:
-
-```bash
-brew install --cask codex
-```
-
-Then start Codex:
-
-```bash
-codex
-```
-
-Codex supports ChatGPT sign-in and API key-based setup. Use the authentication method appropriate for your account and environment.
-
-## Use AI Workflow Kit with Codex
-
-Codex works well through explicit prompt entrypoints and the shared agent contract.
-
-After CLI initialization, start from the project-local files the CLI creates:
-
-- `README.workflow.md` for local workflow instructions;
-- `.codex/prompts/README.md` for Codex prompt entrypoint guidance;
-- `.ai-workflow.json` for install profile and managed file metadata.
-
-The complete reference prompt set remains in this repository. Copy or adapt only the prompt entrypoints your project needs.
-
-Primary Codex assets:
-
-- [`AGENTS.md`](AGENTS.md);
-- [`.codex/prompts/`](.codex/prompts/);
-- ordered prompts in [`prompts/`](prompts/);
-- handoff rules in [`harness/workflows/`](harness/workflows/).
-
-Common Codex prompt entrypoints:
-
-| Prompt file | Use when |
-| --- | --- |
-| [`.codex/prompts/start-project.md`](.codex/prompts/start-project.md) | Starting a project workflow. |
-| [`.codex/prompts/plan-from-requirement.md`](.codex/prompts/plan-from-requirement.md) | Creating a plan from a requirement. |
-| [`.codex/prompts/execute-selected-pr.md`](.codex/prompts/execute-selected-pr.md) | Implementing one selected PR. |
-| [`.codex/prompts/review-implementation.md`](.codex/prompts/review-implementation.md) | Reviewing implementation. |
-| [`.codex/prompts/validate-work.md`](.codex/prompts/validate-work.md) | Validating work with evidence. |
-| [`.codex/prompts/orchestrate-next.md`](.codex/prompts/orchestrate-next.md) | Progressing gate-based handoffs manually. |
-| [`.codex/prompts/fix-issue.md`](.codex/prompts/fix-issue.md) | Diagnosing and fixing an issue. |
-| [`.codex/prompts/autopilot.md`](.codex/prompts/autopilot.md) | Routing a local-first task through existing workflow assets. |
-| [`.codex/prompts/deploy.md`](.codex/prompts/deploy.md) | Preparing deployment readiness. |
-
-Codex wrapper commands from the standalone CLI (copy/paste helper):
-
-```bash
-npx @williambeto/ai-workflow codex:start
-npx @williambeto/ai-workflow codex:orchestrate
-npx @williambeto/ai-workflow codex:plan
-npx @williambeto/ai-workflow codex:execute
-npx @williambeto/ai-workflow codex:review
-npx @williambeto/ai-workflow codex:validate
-```
-
-These commands print the generated local prompt content (for example, `.codex/prompts/start-project.md`) so it can be pasted directly into Codex sessions.
-
-Recommended first Codex workflow:
-
-```txt
-start-project
-→ plan-from-requirement
-→ execute-selected-pr
-→ review-implementation
-→ validate-work
-```
-
-For multi-step work, use [`.codex/prompts/orchestrate-next.md`](.codex/prompts/orchestrate-next.md) and [`harness/workflows/multi-agent-handoff.md`](harness/workflows/multi-agent-handoff.md) to progress gates manually.
-
-## OpenCode vs Codex differences
-
-| Area | OpenCode | Codex |
-| --- | --- | --- |
-| Best fit in this repo | Primary integrated experience | Fully supported explicit workflow |
-| Configuration | `opencode.jsonc` | `AGENTS.md` and prompt files |
-| Commands | OpenCode command registry | Prompt entrypoints |
-| Agent routing | More automated | More manual |
-| Handoffs | Orchestrator can route steps | User/Codex follows gates explicitly |
-| Local-first safety | Enforced by commands and agents | Enforced by `AGENTS.md` and prompts |
-| Agent files | `opencode/agents/` (auto-spawn, auto-routing) | `.codex/prompts/` only (manual paste or explicit invocation); OpenCode agent files are not Codex subagents |
-
-## Use autopilot safely
-
-Autopilot is a local-first workflow entrypoint, not permission to bypass review or validation.
-
-Use autopilot when you want the tool to apply the existing workflow contract:
-
-1. parse the objective;
-2. define the smallest safe scope;
-3. choose the lightest valid route;
-4. route to existing agents, prompts, skills, and workflow contracts only;
-5. check branch safety before writing;
-6. validate proportionally to risk;
-7. stop as `Blocked` when required context, safe scope, or validation is missing;
-8. ask before push, publish, remote repository creation, merge PR, release, or deploy actions.
-
-Autopilot must not create new architecture, agents, or skills during execution.
-
-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)
-
-## First validation
-
-When developing this repository, install dependencies and run validation:
-
-```bash
-npm install
-npm run validate
-```
-
-Expected result:
-
-```txt
-Validation passed: 10 check(s) completed.
-```
-
-If validation fails, inspect the failing command output before continuing.
-
-## Applying this to another project
-
-Use the adoption runbook:
-
-```txt
-runbooks/apply-starter-to-real-project.md
-```
-
-Use the standalone CLI for most target projects:
-
-```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
-```
-
-AI Workflow Kit uses `.ai-workflow/` as managed workflow source with symlinked project paths by default. Use the standalone CLI (`npx @williambeto/ai-workflow init`) for new and existing projects.
-
-## Troubleshooting
-
-| Problem | Check |
-| --- | --- |
-| Command not found | Confirm the CLI is installed and available in `PATH`. |
-| OpenCode has no provider | Run `/connect` and configure a provider/API key. |
-| Codex cannot authenticate | Confirm ChatGPT sign-in or API key setup. |
-| Validation fails | Run the failing `npm run validate:*` command directly and inspect output. |
-| Agent ignores project rules | Confirm `AGENTS.md` exists and the selected command/prompt references it. |
-| Changes are too broad | Stop, restate scope, and use requirement/spec/plan before implementation. |
-
-## Source links
-
-Tool installation changes over time. Confirm current official installation details when needed:
-
-- Codex: <https://github.com/openai/codex>
-- OpenCode: <https://opencode.ai/docs>
-
-## Final guidance
-
-Start with OpenCode if you want the most integrated AI Workflow Kit experience.
-
-Start with Codex if you prefer OpenAI's CLI and explicit prompt-driven control.
-
-In both cases, keep the same delivery discipline: scope first, small PRs, validation evidence, and no-regression rules.

package/harness/README.md

@@ -1,106 +0,0 @@
-# Execution Harness
-
-## Purpose
-
-The harness turns the repository's prompts, templates, runbooks, and skills into repeatable execution workflows.
-
-It is not a framework, build system, or task runner. It is a small operating layer for moving work between planning, implementation, review, and validation with clear handoffs.
-
-`schemas/` provides lightweight contracts that future harness tooling can use to check structured outputs. `examples/` shows what completed workflow artifacts look like in a concrete project context.
-
-## When To Use
-
-Use the harness when a request needs more structure than a single prompt:
-
-- turning a user idea into a scoped PR;
-- handing planned work to an implementer;
-- reviewing an implementation before merge;
-- validating Markdown, commands, scope, and acceptance criteria.
-
-For small typo fixes or narrow Markdown cleanup, use a proportional workflow and validate the changed file directly.
-
-## Workflows
-
-Current workflows:
-
-- `harness/workflows/requirement-to-pr.md` — turns a user request into a requirement, specification, technical plan, PR breakdown, and implementer handoff.
-- `harness/workflows/implement-review-validate.md` — implements one selected PR, reviews it, fixes issues, validates it, and prepares a commit recommendation.
-- `harness/workflows/multi-agent-handoff.md` — enforces deterministic gate-based transitions between planner, implementer, reviewer, validator, and release-manager.
-
-## Handoff Contract
-
-Use `harness/handoffs/HANDOFF.template.md` when one agent transfers work to another.
-
-A handoff must define:
-
-- the objective;
-- context and decisions already made;
-- files in and out of scope;
-- constraints;
-- required validation;
-- known risks;
-- stop conditions;
-- expected output.
-
-The receiving agent should stop if the handoff is missing required context or asks for work outside the approved scope.
-
-## Validation Mindset
-
-Validation is evidence-based.
-
-Every workflow should identify:
-
-- what was checked;
-- which command or manual review was used;
-- what passed;
-- what failed;
-- what was not checked and why.
-
-Do not claim validation passed without command output, file evidence, or a clear manual check result.
-
-## Workflow State Tracker
-
-The optional `.workflow-state.json` file tracks the current project workflow phase and PR progress. It is used by `npm run validate:workflow` to check phase ordering and detect skipped steps.
-
-### Phase order
-
-```txt
-bootstrap → requirement → specification → technicalPlan → prBreakdown
-```
-
-### Phase rules
-
-- Each phase must reach `done` before the next phase can begin.
-- A phase can be marked `skipped` if explicitly decided.
-- The `current` block tracks which phase is active and which PR number is being worked on.
-- The `completed.prs` array records merged PRs with number, title, and merge date.
-
-### Valid status values
-
-- `pending` — phase not started
-- `done` — phase completed
-- `skipped` — phase explicitly skipped
-
-### Example usage
-
-Before running `prompts/05-implement-pr.md`, verify:
-
-```bash
-npm run validate:workflow
-```
-
-This checks that the prerequisite phases exist and are marked `done`.
-
-### Optional
-
-This tracker is optional. The repository validates without it. It becomes useful when a project needs explicit workflow state tracking or automated phase-gate enforcement.
-
-## Related Repository Areas
-
-- `prompts/` provides ordered task instructions.
-- `templates/` provides reusable document structures.
-- `runbooks/` provides operational procedures.
-- `.agents/skills/` provides specialist behavior for Codex-style agents.
-
-- `schemas/` provides lightweight contracts for structured outputs and handoffs.
-- `examples/` provides concrete workflow demonstrations for real project contexts.

package/opencode/README.md

@@ -1,84 +0,0 @@
-# OpenCode Assets
-
-`opencode/` contains Markdown prompt assets for adapting this repository's workflow to OpenCode-based usage.
-
-These files are portable workflow assets. They are not a guarantee that every OpenCode installation will register every file automatically. Adapt file names, registration, and invocation style to the target OpenCode setup.
-
-## Configuration
-
-`opencode.jsonc` registers project agents, commands, and skill discovery paths using the current OpenCode config schema at `https://opencode.ai/config.json`.
-
-There are two common config sources:
-
-| Source | Use when | Notes |
-| --- | --- | --- |
-| Generated project `opencode.jsonc` | Most projects installed with `npx @williambeto/ai-workflow init`. | The CLI creates or merges managed sections while preserving existing project config. |
-| Repository `opencode.jsonc` | Maintaining this kit. | Treat it as a reference config for workflow command/agent behavior. |
-
-Before using `opencode.jsonc` in a production environment:
-
-- verify the configuration against the target OpenCode version;
-- keep the top-level keys aligned with the OpenCode schema, especially `agent`, `command`, and `skills`;
-- note that the config uses JSONC (JSON with `//` comments) and requires a JSONC-aware parser.
-
-If the OpenCode config format changes, update `opencode.jsonc` to match. The agent and command files in `opencode/agents/` and `opencode/commands/` remain the primary source of truth for agent behavior.
-
-## Adoption model
-
-Use the standalone CLI.
-
-Generated workflow assets are installed under `.ai-workflow/` and linked into expected project paths (for example `.codex/`, `.agents/`, and `opencode/`).
-
-Do not manually edit files inside `.ai-workflow/`; treat it as managed workflow source.
-
-## Model
-
-Use this distinction consistently:
-
-| Type | Meaning | Location |
-| ---- | ------- | -------- |
-| Agent | Operational role in a workflow, such as discovery, planning, implementation, review, validation, or release. | `opencode/agents/` |
-| Command | Compact entrypoint for a recurring action. | `opencode/commands/` |
-| Skill | Reusable technical capability that can guide Codex or agent behavior. | `.agents/skills/` |
-
-Do not confuse the generic skills in `.agents/skills/` with OpenCode agents. Skills such as `frontend-implementer`, `tester`, or `docs-writer` are capabilities. OpenCode agents are role prompts that decide how work should move through a real workflow.
-
-## Folders
-
-- `opencode/agents/` defines practical role prompts for Atlas-led triage, discovery, estimation, planning, implementation, fixing, review, validation, release, and selected specialist domains.
-- `opencode/commands/` defines short command prompts for repeated planning, execution, review, and validation actions.
-- `opencode/commands/start.md` is the recommended startup router: default to `orchestrator`, fallback to `discovery` for vague scope, fallback to `prompt-engineer` for prompt/skill-centric requests, and fallback to `planner` for planning-only requests.
-
-Commands can route work into agents, and agents can reference skills when a reusable capability is relevant.
-
-## Napkin project memory
-
-OpenCode workflows should treat Napkin as always discoverable but contextually applied:
-
-- check `.agents/napkin.md` at relevant task start;
-- use `.agents/skills/napkin/SKILL.md` for read/update/cleanup rules;
-- keep memory concise and durable;
-- do not store secrets or sensitive data;
-- do not use Napkin as a task-log dump.
-
-## First-run verification checklist
-
-Before team adoption, run this quick smoke test in the target repository:
-
-1. Confirm `opencode.jsonc` is detected by your OpenCode installation.
-2. Confirm agents referenced in `opencode.jsonc` load without file-path errors.
-3. Confirm commands resolve their templates:
-   - `start`
-   - `plan`
-   - `execute`
-   - `review`
-   - `validate`
-4. Run one small end-to-end cycle (`plan -> execute -> review -> validate`) and record evidence.
-
-Expected outcome:
-
-- command routing works without manual path rewrites;
-- agent prompts load from `opencode/agents/` successfully;
-- validation evidence is produced for the selected test task.
-
-If any command cannot load, verify relative paths in `opencode.jsonc` and your OpenCode command registration mechanism before continuing.

package/opencode/agents/README.md

@@ -1,113 +0,0 @@
-# OpenCode Agents
-
-OpenCode agents in this repository are operational role prompts for real project workflows.
-
-Use this model:
-
-| Type | Definition |
-| ---- | ---------- |
-| Agent | Operational role in the workflow. |
-| Skill | Technical capability reused by agents or Codex. |
-| Command | Short trigger or entrypoint for a recurring action. |
-
-Do not treat generic skills as OpenCode agents. A skill explains how to perform a capability. An agent owns a workflow role, input expectations, stop conditions, and handoff output.
-
-## Recommended Workflows
-
-Client/request discovery:
-
-```txt
-discovery → spec-engineer → planner
-```
-
-Lightweight spec-first delivery:
-
-```txt
-request → spec-engineer → implementer
-```
-
-Feature delivery:
-
-```txt
-atlas → planner → orchestrator → implementer → reviewer → validator → release-manager
-```
-
-Bug fix:
-
-```txt
-fixer → reviewer → validator → release-manager
-```
-
-Frontend architecture:
-
-```txt
-planner → implementer → reviewer → validator
-```
-
-WordPress project:
-
-```txt
-discovery → wordpress-engineer → reviewer → validator → release-manager
-```
-
-Prompt/system improvement:
-
-```txt
-prompt-engineer → reviewer → validator → release-manager
-```
-
-Orchestrated delivery (automatic routing gates):
-
-```txt
-orchestrator (gate A/B/C/D) -> next agent by pass/block result
-```
-
-Discovery routing guard:
-
-- `discovery` is clarification-only.
-- If execution, file edits, validation execution, release actions, or specialist delegation is requested during discovery, the correct behavior is `Blocked` + handoff to `orchestrator`.
-
-Delegation policy baseline:
-
-- route ownership by dominant task type using `AGENTS.md` delegation matrix;
-- send handoffs with explicit contract fields (task summary, files, constraints, expected output, validation, risk, do-not-change list, evidence);
-- require specialist outputs with summary, files changed/inspected, risks, validation commands, open questions, and recommendation;
-- avoid overdelegation (no trivial one-file delegation, max 2 delegated agents unless cross-functional).
-
-## Skill auto-load baseline
-
-When routing to an agent, use this baseline skill auto-load map:
-
-```txt
-planner -> product-manager + tech-lead + pr-orchestrator
-implementer -> pr-orchestrator + tester + (frontend-implementer or backend-implementer)
-reviewer -> tester + pr-orchestrator
-validator -> build-and-validate + tester
-release-manager -> deploy-engineer
-```
-
-Contextual additions:
-
-- add `napkin` when recurring operational decisions should be preserved for future sessions;
-- add `interface-design` only for interface-focused tasks.
-
-When `napkin` is used, read `.agents/napkin.md` at relevant task start and apply progressive disclosure (only relevant entries).
-
-Do not use Napkin as a temporary task log, and never store secrets.
-
-## Agent Index
-
-| Agent | Purpose | Use when | Should not do |
-| ----- | ------- | -------- | ------------- |
-| `atlas` | Act as the primary senior engineering partner and workflow orchestrator. | Users need default triage, critical planning, safe implementation guidance, review, validation, or delegation to existing workflow agents. | Replace specialists blindly, skip evidence, over-engineer, or bypass branch/confirmation gates. |
-| `discovery` | Turn vague requests into a discovery brief. | Scope, risks, dependencies, and unknowns are unclear. | Estimate price, implement, edit files, perform execution/delegation routing directly (must return `Blocked` and route to `orchestrator`). |
-| `spec-engineer` | Turn vague/risky requests into lightweight change artifacts for implementation handoff. | Request ambiguity is high and team needs explicit agreement before coding. | Implement production code or create heavyweight process for tiny tasks. |
-| `planner` | Turn approved scope into requirements, specs, technical plans, and PR breakdowns. | Scope is approved and implementation needs a handoff. | Implement. |
-| `implementer` | Implement one selected PR. | A PR plan or handoff exists. | Expand scope or do opportunistic refactors. |
-| `fixer` | Diagnose and fix bugs, regressions, failures, and warnings. | There is broken behavior or failed validation. | Rewrite large areas without evidence. |
-| `reviewer` | Critically review the current diff before merge. | A PR or implementation needs risk review. | Nitpick without impact or approve without evidence. |
-| `validator` | Run objective repository or PR validation. | Work needs command-based evidence. | Modify files unless explicitly requested. |
-| `release-manager` | Close the Git and PR cycle safely. | Work is validated and ready for commit, PR, merge, or cleanup. | Merge with a dirty worktree or skip validation. |
-| `wordpress-engineer` | Guide WordPress, WooCommerce, ACF, PHP 7, hooks, shortcodes, templates, and security work. | WordPress implementation or review needs platform-specific judgment. | Use PHP 8-only syntax unless allowed or bypass WordPress APIs. |
-| `prompt-engineer` | Improve prompts, commands, handoffs, agents, skills, and token-efficient workflows. | Workflow instructions need sharper routing, shorter context, or clearer outputs. | Duplicate large context or remove operational constraints. |
-| `orchestrator` | Run low-touch end-to-end workflow and route work across agents using gate checks. | The user wants minimal interaction with required checkpoints and deterministic multi-step handoff control. | Skip confirmations, bypass blocked gates, implement feature changes directly, or skip gate evidence. |