@williambeto/ai-workflow 1.19.0 → 2.1.0

package/.codex/prompts/README.md

@@ -1,44 +0,0 @@
-# Codex Prompt Entrypoints
-
-These files are compact prompt entrypoints for Codex.
-
-Use them instead of repeatedly pasting large workflow prompts. Each command points Codex at the repository assets that hold the detailed rules and contracts:
-
-- `AGENTS.md`
-- `prompts/`
-- `harness/`
-
-- `schemas/`
-- `examples/`
-
-The command files are intentionally short. They should start the right workflow, gather only the needed context, and keep token use lower by referencing existing files instead of duplicating them.
-
-## Commands
-
-| File | Use when |
-| ---- | -------- |
-| `start-project.md` | Start a new session with `orchestrator` by default and safe fallbacks (`discovery`, `prompt-engineer`, or `planner` for planning-only requests). |
-| `plan-from-requirement.md` | Turn a user request or rough idea into a requirement, specification, technical plan, PR breakdown, and optional handoff. |
-| `execute-selected-pr.md` | Implement one selected PR from an existing plan or handoff. |
-| `review-implementation.md` | Review the current implementation or diff before merge. |
-| `validate-work.md` | Validate the current repository or PR before commit or merge. |
-| `autopilot.md` | Run a local-first autopilot entrypoint that routes tasks through existing workflow gates and agents. |
-| `roadmap-audit.md` | Run a compact technical roadmap audit with severity-tagged findings and smallest-safe next PR recommendation. |
-| `token-economy-mode.md` | Force compact output contracts (`compact`, `terse`, `audit`, `handoff`) for current task. |
-
-### Specs workflow (`.codex/prompts/specs/`)
-
-| File | Use when |
-| ---- | -------- |
-| `create-spec-from-requirement.md` | Draft a functional spec from an approved requirement. |
-| `review-spec.md` | Review spec readiness before technical planning. |
-| `spec-to-technical-plan.md` | Convert approved spec to technical plan. |
-| `spec-to-pr-breakdown.md` | Split approved spec into small PRs. |
-
-## How To Use
-
-1. Open the command file that matches the current workflow step.
-2. Paste or invoke it in Codex with the current user request, issue, handoff, or PR context.
-3. Let Codex read the referenced repository assets before producing output.
-4. Keep each run scoped to one workflow step.
-5. Use the next command only after the current step has evidence and a clear handoff.

package/.codex/prompts/autopilot.md

@@ -1,50 +0,0 @@
-# Codex Prompt - Autopilot
-
-## Purpose
-
-Run a local-first workflow entrypoint that interprets a user task, routes to existing workflow assets, and enforces safety gates.
-
-Do not create new architecture, agents, or skills inside this prompt.
-
-## Context To Read
-
-Minimum-first context loading:
-
-1. Always read first:
-   - `.codex/prompts/orchestrate-next.md`
-2. Read only when route requires it:
-   - `harness/workflows/requirement-to-pr.md` (planner behavior)
-   - `harness/workflows/implement-review-validate.md` (implementation behavior)
-   - `harness/workflows/multi-agent-handoff.md` (orchestrated gate progression)
-3. Read only relevant sections of `AGENTS.md` for delegation matrix, constraints, and validation.
-
-## Instructions
-
-1. Parse user objective and define the smallest safe scope (in-scope/out-of-scope).
-2. Choose the lightest valid route:
-   - `planner` behavior for requirement/spec/plan output;
-   - `orchestrator` behavior for multi-step or cross-functional delivery;
-   - specialist owner from the AGENTS delegation matrix for focused work.
-3. Reuse existing prompts, skills, and workflow contracts only; do not create new ones during execution.
-4. Enforce local-first git safety before write operations:
-   - run `git status -sb`;
-   - if on `main`, create/switch to scoped branch `git switch -c <type>/<short-task-slug>`;
-   - continue only off `main`.
-5. Keep execution local-first:
-   - do not push, publish, create remote repos, merge PRs, release, or deploy unless explicitly approved.
-6. Validate proportionally to risk and provide evidence.
-7. Stop and report `Blocked` when:
-   - required context is missing;
-   - task scope is too broad;
-   - validation fails.
-8. At the end, ask whether user wants push/publish/remote-repo/merge/release/deploy actions.
-
-## Expected Output
-
-- Selected route and reason
-- Scope (in-scope / out-of-scope)
-- Active step and gate (`Pass`/`Blocked`)
-- Files changed
-- Validation commands and results
-- Risks and open questions
-- Next safe step (including optional push/publish/remote/merge/release/deploy question)

package/.codex/prompts/deploy.md

@@ -1,33 +0,0 @@
-# Deploy
-
-## Purpose
-
-Prepare, validate, or review deployment readiness before releasing a change to a target environment.
-
-## Instructions For Codex
-
-1. Read the relevant context:
-   - `AGENTS.md`
-   - `prompts/09-deploy.md`
-   - `.agents/skills/deploy-engineer/SKILL.md`
-   - `runbooks/deploy-checklist.md`
-   - Validation evidence and selected PR summary
-2. Confirm deployment scope, target environment, and release objective.
-3. Confirm required validation evidence exists before any deploy recommendation.
-4. Identify deployment steps, rollback steps, and ownership.
-5. Check environment prerequisites, CI/CD requirements, secrets handling, and smoke-test plan.
-6. Classify risks and blockers using `High`, `Medium`, `Low` severity.
-7. Recommend `Proceed`, `Needs changes`, or `Blocked` with explicit evidence.
-8. Do not claim deploy success without execution evidence.
-9. Do not expose secrets or credentials.
-
-## Expected Output
-
-- Deployment scope
-- Target environment and method
-- Preconditions and validation evidence
-- Deployment steps
-- Smoke tests
-- Rollback or recovery plan
-- Risks and blockers
-- Final recommendation

package/.codex/prompts/execute-selected-pr.md

@@ -1,35 +0,0 @@
-# Execute Selected PR
-
-## Purpose
-
-Implement one selected PR only.
-
-## Instructions For Codex
-
-1. Read the relevant context from:
-   - `AGENTS.md`
-   - `harness/workflows/implement-review-validate.md`
-   - the selected PR prompt, plan, issue, or handoff provided by the user
-2. If a handoff exists, use it as the scope contract.
-3. Confirm the selected PR objective, files likely to change, files out of scope, and validation expectations before editing.
-4. Enforce a branch gate before editing:
-   - run `git status -sb`;
-   - if `HEAD` is `main`, stop and create a scoped branch with `git switch -c <type>/<short-pr-slug>`;
-   - continue only when current branch is not `main`.
-5. Preserve scope and no-regression rules.
-6. Avoid unrelated refactors, dependency changes, formatting churn, and future PR work.
-7. Follow existing project patterns before introducing new structure.
-8. Keep changes minimal and reviewable.
-9. Run available validation commands that are proportional to the change.
-10. Report validation evidence, skipped checks, and remaining risks.
-11. Do not commit unless explicitly asked.
-
-## Expected Output
-
-- Summary
-- Files changed
-- Implementation notes
-- Validation performed
-- Remaining risks
-- Suggested commit message
-- Effort: AI elapsed ~Xm | Senior dev estimate ~Ym

package/.codex/prompts/fix-issue.md

@@ -1,34 +0,0 @@
-# Fix Issue
-
-## Purpose
-
-Diagnose and fix bugs, regressions, failing tests, build failures, validation errors, or broken behavior. Apply the smallest safe fix with evidence.
-
-## Instructions For Codex
-
-1. Read the relevant context:
-   - `AGENTS.md`
-   - `harness/workflows/implement-review-validate.md`
-   - The error output, failing command, bug report, or reproduction steps
-   - Current diff and relevant files
-2. Reproduce or inspect the problem. Gather concrete evidence (command output, stack trace, file path, line reference).
-3. Identify the likely root cause. If uncertain, state it as a hypothesis with a validation step.
-4. Apply the smallest safe fix that addresses the root cause.
-5. State any behavior changes explicitly — even minor ones.
-6. Run targeted validation proportional to the fix:
-   - Relevant lint, typecheck, tests, or build commands
-   - Manual checks when commands are unavailable
-7. Document regression risk and untested areas.
-8. Do not rewrite large areas without evidence supporting the scope.
-9. Do not mix unrelated refactors into the fix.
-10. Do not commit unless explicitly asked.
-
-## Expected Output
-
-- Problem summary
-- Evidence (command output, file path, line reference)
-- Root cause (or hypothesis with validation step)
-- Fix applied (files changed, what changed and why)
-- Validation performed (commands + results)
-- Regression risk
-- Suggested commit message

package/.codex/prompts/minimal-context-mode.md

@@ -1,55 +0,0 @@
-# Minimal Context Mode
-
-## Purpose
-
-Activate input-budget discipline for the current task. Read only task-relevant files, use targeted search before reading, and stop when enough evidence is found.
-
-This prompt reduces INPUT tokens. Use alongside `token-economy-mode.md` for output discipline.
-
-## Input vs Output Tokens
-
-| Token type | What it is | How to reduce |
-|---|---|---|
-| **Input** | Files, history, context sent TO the model | This prompt (`minimal-context-mode`) |
-| **Output** | Model response verbosity | `token-economy-mode.md` |
-
-High input tokens (90k–164k per call) come from:
-- Reading entire directories or large files
-- Broad glob patterns matching many files
-- Including prior conversation history
-- Passing full contents to subagents
-
-## Instructions For Codex
-
-1. State what you are looking for before reading.
-2. Use `grep` or `glob` to narrow to 3–7 files max.
-3. Read only the most relevant files.
-4. Stop and summarize findings after each batch.
-5. Request confirmation before reading beyond 7 files.
-6. For audit tasks, define scope first — do not read everything.
-7. Send compact summaries to subagents, not full file contents.
-8. Exclude unrelated prior conversation context.
-9. Stop when evidence is sufficient for the current task.
-
-## Input Budget Rules
-
-| Scenario | Limit |
-|---|---|
-| Default task (implement, fix, review) | 3–7 files per read batch |
-| Scoped audit | Define scope first, then sample strategically |
-| Subagent handoff | Summary only — no full contents |
-
-## What to do vs not do
-
-Do:
-- `grep` for patterns before reading
-- `glob` for file lists before reading
-- Read 3–7 files, then summarize
-- Stop after enough evidence
-
-Do not:
-- `glob **/*.md` and read all matches
-- Read large files end-to-end
-- Pass full file contents to subagents
-- Include prior conversation history
-- Read files without a specific target

package/.codex/prompts/orchestrate-next.md

@@ -1,33 +0,0 @@
-# Orchestrate Next Step
-
-## Purpose
-
-Progress the workflow one gate at a time using the deterministic handoff chain from `harness/workflows/multi-agent-handoff.md`.
-
-This prompt does not implement code. It inspects the current step, checks gate criteria, and recommends the next agent with a handoff contract.
-
-## Instructions For Codex
-
-1. Read the relevant context:
-   - `AGENTS.md`
-   - `harness/workflows/multi-agent-handoff.md` (gates A, B, C, D)
-   - `harness/handoffs/HANDOFF.template.md`
-   - Current step outputs and validation evidence
-2. Identify current step in the chain: `planner -> implementer -> reviewer -> validator -> release-manager`.
-3. Classify which gate applies to the current transition.
-4. Check entry criteria for that gate against current evidence.
-5. If all entry criteria are met and no blocking conditions exist, output `Gate: Pass` and recommend the next agent.
-6. If criteria are missing or blocking conditions apply, output `Gate: Blocked`, state the smallest safe fix, and return control to the previous agent.
-7. For `Pass`: assemble a handoff packet using the contract fields from `HANDOFF.template.md` (objective, scope, files in/out, constraints, validation, risks, stop conditions, expected output).
-8. For `Blocked`: list missing criteria and the recommended fix action with file/command paths.
-9. Do not skip gate order unless the user explicitly requests a proportional flow for trivial changes.
-10. Preserve branch gate, no-regression rules, and evidence requirements.
-
-## Expected Output
-
-- Current step and active agent
-- Gate being evaluated (A/B/C/D)
-- Gate result (`Pass` or `Blocked`)
-- Blocking reason and fix request (when `Blocked`)
-- Next agent to run (when `Pass`)
-- Handoff contract summary (objective, scope, constraints, risks, validation required, expected output)

package/.codex/prompts/plan-from-requirement.md

@@ -1,37 +0,0 @@
-# Plan From Requirement
-
-## Purpose
-
-Convert a user request or rough idea into a requirement, functional specification, technical plan, PR breakdown, and optional execution handoff.
-
-Stop before implementation.
-
-## Instructions For Codex
-
-1. Read the relevant context from:
-   - `AGENTS.md`
-   - `harness/workflows/requirement-to-pr.md`
-   - `schemas/`
-   - `templates/`
-2. Inspect existing project files only as needed to understand current patterns and constraints.
-3. Ask at most 2 blocking questions when the work cannot be planned safely.
-4. If a safe plan can be created, state assumptions instead of asking non-blocking questions.
-5. Keep the plan framework-agnostic unless the target project context requires stack-specific details.
-6. Produce small, reviewable PRs.
-7. Identify scope boundaries, no-regression expectations, risks, trade-offs, and validation needs.
-8. Recommend the next PR to implement.
-9. For multi-step/cross-functional work, recommend the likely specialist owner using `AGENTS.md` delegation rules.
-10. Include an execution handoff only when there is enough context for a separate implementer to start safely.
-11. Do not edit files or implement code.
-
-## Expected Output
-
-- Summary
-- Assumptions
-- Requirement
-- Functional specification
-- Technical plan
-- PR breakdown
-- Recommended next PR
-- Validation plan
-- Open questions

package/.codex/prompts/review-implementation.md

@@ -1,33 +0,0 @@
-# Review Implementation
-
-## Purpose
-
-Review the current implementation or diff before merge.
-
-## Instructions For Codex
-
-1. Act as a critical reviewer.
-2. Inspect the current diff and relevant surrounding files.
-3. Compare the changes against the requirement, specification, technical plan, PR breakdown, or handoff when present.
-4. Classify findings as `High`, `Medium`, or `Low`.
-5. Require evidence for every finding, including file paths, line references, command output, or concrete diff behavior.
-6. Check for:
-   - no-regression risk
-   - scope creep
-   - validation gaps
-   - documentation drift
-   - test gaps
-   - broken Markdown or structured data when relevant
-7. Avoid nitpicks unless they affect correctness, maintainability, workflow safety, or future validation.
-8. Do not modify files unless explicitly asked.
-
-## Expected Output
-
-- Verdict
-- Findings by severity
-- Scope check
-- Regression risk
-- Validation gaps
-- Required fixes before merge
-- Optional improvements
-- Effort: AI elapsed ~Xm | Senior dev estimate ~Ym

package/.codex/prompts/roadmap-audit.md

@@ -1,22 +0,0 @@
-# Roadmap Audit
-
-## Purpose
-
-Run a compact technical roadmap audit and return evidence-based findings.
-
-## Instructions For Codex
-
-1. Confirm audit scope and read only the required files.
-2. Summarize current roadmap status and active next step.
-3. Report findings using severity (`High`/`Medium`/`Low`) and type (`Confirmed issue`/`Hypothesis`/`Observation`).
-4. Require evidence for each finding (file path + section/line when available).
-5. Recommend the smallest safe next PR.
-6. Avoid edits unless explicitly requested.
-
-## Expected Output
-
-- Current state summary
-- Findings table (severity, type, evidence, problem, risk, action)
-- Recommended next PR (scope + files)
-- Validation commands
-- Open questions (only if blocking)

package/.codex/prompts/specs/create-spec-from-requirement.md

@@ -1,26 +0,0 @@
-# Create Spec From Requirement
-
-## Outcome
-
-Draft a clear, testable functional specification from an approved requirement.
-
-## Use
-
-Use `templates/SPEC.template.md` and keep output implementation-ready for planning, not coding.
-
-## Constraints
-
-- Do not implement code.
-- Preserve existing behavior unless change is explicit in requirement.
-- Ask only blocking questions (max 2).
-- Keep scope and out-of-scope explicit.
-
-## Required output
-
-- Spec draft following `templates/SPEC.template.md`
-- Assumptions and open questions
-- Readiness status: `Ready for technical plan` | `Needs clarification` | `Too broad` | `Blocked`
-
-## Evidence
-
-Report files inspected and why they were needed.

package/.codex/prompts/specs/review-spec.md

@@ -1,29 +0,0 @@
-# Review Spec
-
-## Outcome
-
-Decide if a spec is ready for technical planning with explicit evidence.
-
-## Use
-
-Review against:
-
-- `templates/SPEC.template.md`
-- `checklists/spec-readiness-checklist.md`
-
-## Constraints
-
-- Do not implement.
-- Do not expand scope silently.
-- Preserve no-regression expectation.
-
-## Required output
-
-- Decision: `Ready` | `Needs clarification` | `Too broad` | `Blocked`
-- Findings by severity (`High`/`Medium`/`Low`)
-- Missing sections or unclear criteria
-- Smallest safe fixes
-
-## Evidence
-
-Include file references for each finding.

package/.codex/prompts/specs/spec-to-pr-breakdown.md

@@ -1,23 +0,0 @@
-# Spec To PR Breakdown
-
-## Outcome
-
-Split an approved spec into small, reviewable PRs with validation and evidence per PR.
-
-## Constraints
-
-- Do not implement.
-- Keep one objective per PR.
-- Keep behavior changes explicit and isolated.
-- Avoid unrelated refactors.
-
-## Required output
-
-- Ordered PR list (PR1, PR2, ...)
-- Per PR: objective, scope, out-of-scope, risks, validation commands
-- Recommended first PR
-- Handoff-ready notes for implementer
-
-## Evidence
-
-Reference the source spec sections used for each PR decision.

package/.codex/prompts/specs/spec-to-technical-plan.md

@@ -1,28 +0,0 @@
-# Spec To Technical Plan
-
-## Outcome
-
-Convert an approved spec into a technical plan safe for incremental PR execution.
-
-## Use
-
-Start from the final spec and generate technical planning output only.
-
-## Constraints
-
-- Do not implement.
-- Keep architecture proportional (`docs/architecture-policy.md`).
-- Keep design-pattern usage justified (`docs/design-patterns-policy.md`).
-- Keep no-regression and validation explicit.
-
-## Required output
-
-- Technical approach summary
-- Risks and trade-offs
-- Validation strategy
-- Proposed sequencing for PR breakdown
-- Open questions (only blockers)
-
-## Evidence
-
-List source spec and files referenced for constraints.

package/.codex/prompts/start-project.md

@@ -1,29 +0,0 @@
-# Start Project (Default: Autopilot)
-
-Use this entrypoint when opening this repository.
-
-## Routing policy
-
-Default to `orchestrator` behavior.
-
-Only switch when needed:
-
-- Use `discovery` behavior if the request is vague or missing scope/constraints.
-- Use `prompt-engineer` behavior if the request is mainly about prompts, commands, skills, routing, or instruction quality.
-- Use `planner` behavior when the user explicitly asks for planning-only output without execution/delegation.
-
-## Required startup output
-
-1. `Selected route: <orchestrator|planner|discovery|prompt-engineer>` with one-line reason.
-2. Scope assumptions (in-scope / out-of-scope).
-3. First safe next step.
-4. Validation intent (what evidence will be produced).
-
-## Constraints
-
-- Follow `AGENTS.md` as the primary operational contract.
-- For multi-step or cross-functional work, use orchestrator-style routing from `AGENTS.md` (`Agent delegation and orchestration`).
-- Map task type to specialist owner before delegating and include a handoff contract when delegation happens.
-- Avoid overdelegation: do not delegate trivial one-file edits; keep routing to one owner + one reviewer unless cross-functional.
-- Keep no-regression, small-scope, and evidence-based validation rules explicit.
-- Ask at most two blocking questions when critical context is missing.

package/.codex/prompts/token-economy-mode.md

@@ -1,48 +0,0 @@
-# Token Economy Mode
-
-## Purpose
-
-Activate compact output behavior for current task while preserving technical accuracy, validation evidence, severity, and acceptance criteria.
-
-## Instructions For Codex
-
-1. Read:
-   - `AGENTS.md`
-   - `.agents/skills/token-economy/SKILL.md`
-2. Ask user for mode when missing: `compact`, `terse`, `audit`, or `handoff`.
-3. Keep commands, file paths, and statuses exact.
-4. Keep no-regression and validation rules explicit.
-5. Avoid broad repository scans unless explicitly requested.
-6. Do not modify workflow behavior; only reduce response verbosity.
-
-## Output contracts
-
-### Implementation
-
-- Scope
-- Files changed
-- Validation commands and results
-- Risks
-- Acceptance status
-
-### Audit
-
-- Findings table only: Severity | Evidence | Impact | Required fix
-- Validation gaps
-- Final recommendation
-
-### Bugfix
-
-- Root cause
-- Fix applied
-- Files changed
-- Validation commands and results
-- Regression risks
-
-### Handoff
-
-- Summary
-- Changed files
-- Validations
-- Risks
-- Next action

package/.codex/prompts/validate-work.md

@@ -1,28 +0,0 @@
-# Validate Work
-
-## Purpose
-
-Validate the repository or current PR before commit or merge.
-
-## Instructions For Codex
-
-1. Inspect `package.json` for available validation scripts.
-2. Run available validation commands that are appropriate for the current change.
-3. Check Markdown validation when Markdown files changed.
-4. Check JSON parsing for `schemas/` when schemas exist or changed.
-5. Check Git status and the current diff.
-6. Summarize pass or fail with evidence.
-7. Identify blocking issues and non-blocking warnings.
-8. Avoid modifying files unless explicitly asked.
-9. Do not commit unless explicitly asked.
-
-## Expected Output
-
-- Validation status
-- Commands run
-- Results
-- Files changed
-- Blocking issues
-- Non-blocking warnings
-- Merge recommendation
-

package/checklists/change-spec-readiness-checklist.md

@@ -1,34 +0,0 @@
-# Change Spec Readiness Checklist
-
-Use this checklist before implementation starts.
-
-## Clarity and scope
-
-- [ ] Objective is clear and measurable.
-- [ ] Problem is explicit.
-- [ ] Scope and out-of-scope are explicit.
-- [ ] Assumptions are explicit and labeled.
-- [ ] Open questions are resolved or marked as blockers.
-
-## Behavior and design
-
-- [ ] Requirements are testable.
-- [ ] Scenarios cover main flow and key edge cases.
-- [ ] Technical design is lightweight and sufficient for implementation.
-- [ ] Constraints and integration points are explicit.
-
-## Delivery readiness
-
-- [ ] Task breakdown is small, ordered, and reviewable.
-- [ ] Validation plan includes real commands/checks.
-- [ ] Expected evidence is explicit.
-- [ ] Risks include mitigation notes.
-
-## Decision
-
-Mark one:
-
-- [ ] Ready for implementation handoff
-- [ ] Needs clarification
-- [ ] Too broad (split into smaller changes)
-- [ ] Blocked by missing context/decision