compound-workflow 1.8.0 → 1.9.1

package/src/AGENTS.md

@@ -1,18 +1,9 @@
 # Agent Operating Principles
 
-This `.agents` workspace is portable and command-first.
-
-## Contents
+<!-- Default template. Structural source of truth: src/skills/setup-agents/SKILL.md Phase 4.
+     When changing sections here, keep that template in sync (and vice versa). -->
 
-- Canonical Workflow
-- Non-negotiables (Structure Integrity)
-- Planning Fidelity Model
-- Routing Rules
-- Repo Configuration (Optional)
-- Directory Layout
-- Implemented Components (Current Scope)
-- Skill Index (When to Use What)
-- Reference Standards Policy (Anti-Skill-Sprawl)
+This `.agents` workspace is portable and command-first.
 
 ## Core Principles
 
@@ -22,122 +13,69 @@ This `.agents` workspace is portable and command-first.
 4. Selection must be deterministic and visible: always state which skills/agents were selected and why.
 5. Brainstorm and plan do not write code.
 
-## Canonical Workflow
-
-1. `/workflow:brainstorm` -> clarify what to build
-2. `/workflow:plan` -> define how to build it
-3. `/workflow:work` -> implement (includes triage gate for todo readiness/prioritization)
-4. `/workflow:review` -> validate quality
-5. `/workflow:compound` -> capture durable learnings
+## Contract Precedence
 
-Optional manual steps:
+If workflow documents conflict, resolve in this order:
 
-- `/workflow:triage` -> explicitly curate/prioritize backlog items before execution when needed
-- `/workflow:tech-review` -> run technical review on a plan (technical correctness before build); optional plan path
+1. `docs/principles/workflow-baseline-principles.md`
+2. This file — non-negotiables and repo config
+3. Workflow command specs
+4. Skill docs
 
-Continuous improvement:
+## Canonical Workflow
 
-- `/metrics` -> log + assess a session and suggest improvements
-- `/assess` -> aggregate daily metrics (weekly/monthly) and propose improvements
+1. `/workflow:brainstorm` — clarify what to build
+2. `/workflow:plan` — define how to build it
+3. `/workflow:work` — implement (includes triage gate)
+4. `/workflow:review` — validate quality
+5. `/workflow:compound` — capture durable learnings
 
-Onboarding:
+Optional:
 
-- `/install` -> one action: writes opencode.json, merges AGENTS.md, creates dirs, preserves Repo Config Block (run `npx compound-workflow install` in the project)
+- `/workflow:triage` — manually curate/prioritize queue before execution
+- `/workflow:tech-review` — technical correctness check on a plan before build
 
-This workspace currently implements `brainstorm`, `plan`, `triage`, `work`, `review`, `tech-review`, `compound`, and optional QA utilities.
+Continuous improvement:
 
-Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, `/workflow:tech-review`, etc.). This template does not ship aliases.
+- `/metrics` — log + assess a session
+- `/assess` — aggregate metrics and propose improvements
 
-## Contract Precedence
-
-If workflow documents conflict, resolve them in this order:
+Onboarding:
 
-1. `docs/principles/workflow-baseline-principles.md`
-2. This file (`src/AGENTS.md`) non-negotiables and repo config
-3. Workflow command specs (`src/.agents/commands/workflow-*.md`)
-4. Skill docs (`src/.agents/skills/*/SKILL.md`)
+- `/install` — one action: copies agents/skills/commands, writes opencode.json, merges AGENTS.md, creates docs/todo dirs (run `npx compound-workflow install` in the project)
 
 ## Non-negotiables (Structure Integrity)
 
 - **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
 - **Brainstorm = WHAT, Plan = HOW.** `/workflow:plan` must not re-litigate decisions already captured in `docs/brainstorms/`.
-- **Local grounding is mandatory.** Every plan must cite at least 1–3 internal file path/line refs (existing patterns) and any relevant `docs/solutions/**` learnings.
-- **Fidelity + confidence are required declarations** in every plan file: always output the Fidelity/Confidence/Research-mode block; the chosen template must include the required sections for that fidelity (Low/Medium/High).
-- **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus explicit completion expectation and non-goals so `/workflow:work` can enforce intent.
-- **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
-- **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands. `/workflow:review` must do the same for non-current PR/branch targets before analysis.
-- **Triage before execution is mandatory.** `/workflow:work` must run a triage pass before executing todos to prioritize the queue and validate dependencies/ready state for the current plan. `/workflow:triage` remains available as an explicit manual command.
-- **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
-- **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
-- **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`, plus independence evidence and skipped-pass disclosure.
-- **Standards baseline is mandatory for code/config changes.** `/workflow:work` and `/workflow:review` must apply `skill: standards` as a hard gate for declarative flow, immutable transforms, and maintainability boundaries.
-- **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
-- **Blockers change todo state immediately.** Blocked work must move from `ready` back to `pending` with `tags: [blocker]` and an options+recommendation decision record.
-- **Quality gates are enforced with ask-once fallback.** If `lint_command` or `typecheck_command` is missing, ask once per run and continue only when commands are provided and pass.
-- **Skills are invoked only by trigger.** `document-review` only when user selects "Review and refine" (or explicit request); guardrail skills (PII/financial/audit/data) only when the feature touches that domain.
+- **Local grounding is mandatory.** Every plan must cite at least 1–3 internal file path/line refs and any relevant `docs/solutions/**` learnings.
+- **Fidelity + confidence are required declarations** in every plan file.
+- **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus completion expectation and non-goals.
+- **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands.
+- **Triage before execution is mandatory.** `/workflow:work` must run a triage pass before executing todos.
+- **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`.
+- **Standards baseline is mandatory for code/config changes.** `/workflow:work` and `/workflow:review` must apply `skill: standards` as a hard gate.
+- **Todo completion requires evidence.** A todo may move to `complete` only after success criteria and quality gate evidence are recorded.
 - **No ad-hoc artifacts outside canonical outputs** (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
-- **Plan file is the artifact.** Post-generation options are actions on the artifact; they do not change the workflow shape.
-- **Tighten over expand.** Resolve ambiguity, standardize naming, enforce sections—avoid adding new process steps unless they reduce rework.
 
 ## Planning Fidelity Model
 
-`/workflow:plan` must always declare:
-
-- `Fidelity selected`: `Low | Medium | High`
-- `Confidence`: `High | Medium | Low`
-- `solution_scope`: `partial_fix | full_remediation | migration`
-- Why this fidelity (2-4 reasons)
-- Research mode used (`local only` or `local + external`)
-- Open questions (if any)
-
-### Selection Rules
-
-- If any high-risk trigger exists, select `High`.
-- If signals are mixed or unclear, default to `Medium`.
-- Otherwise select `Low`.
+`/workflow:plan` must always declare: `Fidelity`, `Confidence`, `solution_scope`, rationale, research mode, and open questions.
 
-High-risk triggers include: security, payments, privacy, data migration/backfills, production infra/deployment, or hard rollback.
+- **Low** — problem, constraints, acceptance criteria, implementation outline, verification checklist.
+- **Medium** — all Low + alternatives/tradeoffs, dependency/risk table, rollout notes, observability/test notes.
+- **High** — all Medium + failure modes, rollback plan, deployment gates, migration/data safety checks, expanded test matrix.
 
-### Required Output by Fidelity
-
-- `Low`: problem, constraints, acceptance criteria, implementation outline, verification checklist.
-- `Medium`: all Low + alternatives/tradeoffs, dependency/risk table, rollout notes, observability/test notes.
-- `High`: all Medium + failure modes, rollback plan, deployment gates, migration/data safety checks, expanded test matrix.
+Select `High` if any high-risk trigger exists (security, payments, privacy, data migration, production infra). Default to `Medium` for mixed signals. Otherwise `Low`.
 
 ## Routing Rules
 
-- **Capability-first in commands:** Core workflow command docs should name capabilities (problem shape), not specific libraries. Concrete skill resolution comes from the Skill Index.
-- **Centralized skill routing:** Add new domain/reference skill routing in this file (Skill Index + rules) rather than hard-coding per-skill logic into each workflow command, except for rare high-criticality cases.
-- **Default skill selection order:** (1) safety/guardrail standards when applicable, (2) domain architecture/reference skills, (3) workflow execution skills. Choose the minimal set that covers the problem.
-- **Explain selection:** When selecting skills, state which skills were selected and why.
-- Prefer existing project patterns before introducing new ones.
-- Always run local repo + institutional learnings research first for planning.
-- Run external best-practice/framework research based on fidelity and risk.
-- For medium/high fidelity plans that touch existing behavior, consider `git-history-analyzer` to understand why the current code is the way it is.
-- Use generic fallback behavior if domain-specific skills are unavailable.
-
-## Repo Configuration (Optional)
-
-To keep this `.agents` bundle portable, prefer configuring repo-specific commands and defaults in this file.
-
-Suggested keys (examples):
-
-- `default_branch: main`
-- `dev_server_url: http://localhost:3000`
-- `test_command: npm test`
-- `test_fast_command: npm test -- --watch=false --runInBand`
-- `lint_command: npm run lint`
-- `typecheck_command: npm run typecheck`
-- `format_command: npm run format`
-- `project_tracker: github` (or `linear`)
-- `worktree_dir: .worktrees` (optional; where worktrees are created)
-- `worktree_copy_files: [...]` (optional; env/config files to copy into new worktrees; non-overwriting)
-- `worktree_install_command: <cmd>` (optional; deps install command to run in new worktrees)
-- `worktree_bootstrap_notes: [...]` (optional; prerequisites per worktree: system deps/services/tooling; documented only)
+- **Centralized skill routing:** Add new domain/reference skill routing in this file (Skill Index) rather than per-command.
+- **Default selection order:** (1) safety/guardrail standards, (2) domain architecture/reference skills, (3) workflow execution skills. Minimal set that covers the problem.
+- **Explain selection:** Always state which skills were selected and why.
+- Run local repo + institutional learnings research first for planning. External research based on fidelity and risk.
 
-### Repo Config Block (Optional)
-
-If you want commands to read these values deterministically, add a small YAML block under this section:
+## Repo Config Block
 
 ```yaml
 default_branch: main
@@ -149,101 +87,30 @@ typecheck_command: npm run typecheck
 format_command: npm run format
 project_tracker: github
 worktree_dir: .worktrees
+worktree_install_command: npm ci
 worktree_copy_files:
   - .env
   - .env.local
-worktree_install_command: npm ci
-worktree_bootstrap_notes:
-  - Ensure required system deps are installed (e.g. via brew/apt)
-  - Ensure local services are running (e.g. postgres/redis)
-  - If using direnv: run `direnv allow`
+harnesses: []
 ```
 
-## Directory Layout
-
-- Commands: `.agents/commands/*.md` and `.agents/commands/workflow-*.md` (workflow namespace)
-- Skills: `.agents/skills/*/SKILL.md`
-- Skills may optionally include tool-specific agent metadata under `.agents/skills/*/agents/` (for example `openai.yaml`) when required by that skill's validator/runtime.
-- References: `.agents/references/**`
-- Agents: `.agents/agents/**/*.md`
-
-**Single source of truth (declarative):** Commands and agents are discovered from the registry and `generate-platform-artifacts`; skills are discovered by scanning `skills/` for `*/SKILL.md`. Add or remove files/dirs, then run install—no other registration. See install-cli header comment for the full pipeline.
-
-## Implemented Components (Current Scope)
-
-- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:tech-review`, `workflow:compound` (under `.agents/commands/` as `workflow-*.md`), plus `test-browser`, `metrics`, `assess`, `install` (root commands)
-- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `capture-skill`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`, `presentation-composability`
-- Agents:
-  - `repo-research-analyst`
-  - `learnings-researcher`
-  - `git-history-analyzer`
-  - `best-practices-researcher`
-  - `framework-docs-researcher`
-  - `spec-flow-analyzer`
-  - `lint`
-  - `bug-reproduction-validator`
-  - `agent-native-reviewer`
-  - `planning-technical-reviewer`
-
-## Skill Index (When to Use What)
-
-Skills fall into two buckets:
-
-1. Workflow skills: invoked by commands to do work (e.g. `/workflow:review`, `/workflow:compound`).
-2. Reference standards: enforce design/build guardrails when the work touches security, privacy, money, or multi-tenant data.
-
-Use reference standards proactively during `/workflow:plan`, `/workflow:work`, and PR review.
+## Skill Index
 
-## Reference Standards Policy (Anti-Skill-Sprawl)
-
-To keep this workspace usable and portable, reference standards are intentionally limited.
-
-Rules:
-
-- Cap: MAX 12 reference standards skills under `.agents/skills/`.
-- Promotion: create a new reference standard skill only if it meets at least 2 criteria:
-  - introduces MUST/MUST NOT rules that change build decisions
-  - includes required schema/contracts/checklists that can be enforced in review
-  - has operational failure modes/runbooks
-  - applies across multiple features (not one-off project trivia)
-  - prevents a high-cost incident if followed
-- Overlap: each domain has a single "owner" skill; overlapping material MUST be added to the owner skill (as a new section) or demoted to a non-skill reference doc.
-- References location: non-skill references live in `.agents/references/` (this repo: `src/.agents/references/`) and are linked from `src/AGENTS.md` or the owning skill.
-
-Owner skills:
-
-- `data-foundations`: multi-tenant boundaries (views/functions), RLS, grants/revokes, tenant context.
-- `pii-protection-prisma`: PII placement, envelope encryption, key rotation, logging restrictions.
-- `financial-workflow-integrity`: idempotency, concurrency, webhooks, approvals for money-adjacent workflows.
-- `audit-traceability`: append-only audit logs, actor attribution, correlation IDs, privileged access audit.
-
-Maintenance:
-
-- If a reference standard becomes mostly examples/links, demote it into `.agents/references/` (this repo: `src/.agents/references/`) and keep the skill as the enforceable rules/checklists only.
-
-### Workflow skills
-
-| Skill | Use when |
-| --- | --- |
-| `brainstorming` | You need structured idea exploration and clarification without writing code. |
-| `document-review` | You need to review a document/spec and extract issues, gaps, and concrete next actions. |
-| `technical-review` | A plan or feature approach has passed document review and must be checked for technical correctness before build. |
-| `compound-docs` (alias: `compound_doc`) | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
-| `capture-skill` | You want to capture conversation learnings as a reusable skill, while defaulting to project-overlay refinement and avoiding implicit edits to repo-provided base skills. |
-| `file-todos` | You need a file-backed todo workflow for iterative multi-step changes. |
-| `agent-browser` | You need to inspect available agents/skills and route deterministically. |
-| `git-worktree` | You need isolated parallel work (review/feature) using git worktrees. |
-| `process-metrics` | You want to log and assess session performance and process improvements. |
-| `react-ddd-mvc-frontend` | You need React frontend architecture guidance (DDD + MVC hybrid) during planning or review to enforce feature structure, layer boundaries, composable pure components, container/controller responsibilities, and maintainable patterns. |
-| `xstate-actor-orchestration` | You are evaluating complexity and need explicit state orchestration: React container-as-orchestrator for UI flows, or actor/state-machine orchestration for backend/internal workflows (especially multi-step async branching, retries/timeouts/cancellation, receptionist/child-actor coordination, or boolean-flag sprawl). |
-| `standards` | You need Altai coding standards for implementation and refactoring, including domain entity patterns, XState conventions, type usage, and feature code organization. |
-| `presentation-composability` | You are creating or refactoring presentation components in tapesv3 and need folder-per-component structure with barrel exports and styles separation. |
-
-### Reference standards (guardrails)
+<!-- Default rows — reflects skills shipped with this package. Run /setup-agents to regenerate from installed skills. -->
 
 | Skill | Use when |
 | --- | --- |
-| `data-foundations` | You are designing multi-tenant schema/access boundaries (views/functions, RLS, grants/revokes). |
-| `pii-protection-prisma` | You store/process PII and need table separation + envelope encryption + rotation + logging rules. |
-| `financial-workflow-integrity` | A workflow has money/regulatory outcomes and must be correct under retries/concurrency/webhooks/approvals. |
-| `audit-traceability` | You need append-only auditing with actor attribution + correlation IDs without leaking PII. |
+| `brainstorming` | Exploring intent and approaches before planning. |
+| `document-review` | Reviewing a document/spec for issues, gaps, and next actions. |
+| `technical-review` | Checking a plan for technical correctness before build. |
+| `compound-docs` | Capturing a solved problem as durable institutional knowledge. |
+| `capture-skill` | Saving conversation learnings as a reusable skill. |
+| `file-todos` | Managing a file-backed todo workflow for iterative multi-step changes. |
+| `git-worktree` | Isolated parallel work using Git worktrees. |
+| `process-metrics` | Logging and assessing session performance. |
+| `setup-agents` | Creating or updating AGENTS.md for a project. |
+| `agent-browser` | Inspecting available agents/skills and routing deterministically. |
+| `data-foundations` | Designing multi-tenant schema/access boundaries (RLS, grants). |
+| `pii-protection-prisma` | Storing or processing PII. |
+| `financial-workflow-integrity` | Workflows with money or regulatory outcomes. |
+| `audit-traceability` | Append-only auditing with actor attribution. |

package/src/{.agents/agents → agents}/research/best-practices-researcher.md

@@ -31,7 +31,7 @@ Before going online, check if curated knowledge already exists in skills:
 
 1. **Discover Available Skills**:
 
-   - Use Glob to find all SKILL.md files in this repo first: `.agents/skills/**/SKILL.md` and `**/**/SKILL.md`
+   - Resolve the skills directory from `harnesses` in AGENTS.md Repo Config — use the first listed harness that has a `skills/` subdirectory. Use Glob to find all SKILL.md files there, plus `**/**/SKILL.md` as a fallback.
    - Optionally check any user/global skill locations supported by your runtime
    - Read the skill descriptions to understand what each covers
 
@@ -42,7 +42,7 @@ Before going online, check if curated knowledge already exists in skills:
     - Work isolation → `git-worktree`
     - Browser QA (optional) → `agent-browser`
 
-    If a skill is not present in this repo's `.agents/skills/`, treat it as unavailable.
+    If a skill is not present in the detected skills directory, treat it as unavailable.
 
 3. **Extract Patterns from Skills**:
 

package/src/{.agents/commands → commands}/assess.md

@@ -34,9 +34,9 @@ This command is the feedback loop that improves the `.agents` system over time.
    - Trend call: quality up/down and speed up/down (simple narrative)
 4. Propose actions:
    - Each action should target a component:
-     - command (`.agents/commands/*.md`)
-     - skill (`.agents/skills/**/SKILL.md`)
-     - agent (`.agents/agents/**/*.md`)
+     - command (commands directory of the current harness — resolve from `harnesses` in AGENTS.md Repo Config)
+     - skill (skills directory of the current harness — resolve from `harnesses` in AGENTS.md Repo Config)
+     - agent (agents directory of the current harness — resolve from `harnesses` in AGENTS.md Repo Config)
      - repo config (`AGENTS.md` keys)
    - Provide the smallest change that would move the metric.
 5. Materialize actions:
@@ -56,5 +56,5 @@ This command is the feedback loop that improves the `.agents` system over time.
 
 ## Guardrails
 
-- Do not modify code or `.agents` components automatically.
+- Do not modify code or harness components automatically.
 - Only create todos and summary docs.

package/src/commands/install.md

@@ -0,0 +1,43 @@
+---
+name: install
+invocation: install
+description: Install compound-workflow in this project — copies agents/skills/commands, writes opencode.json, merges AGENTS.md, and creates docs/todo dirs.
+argument-hint: "[--dry-run] [--root <path>]"
+---
+
+# /install
+
+Install or update compound-workflow in this project with **one action**.
+
+## When to use
+
+- First-time setup in a repository.
+- After updating `compound-workflow` to refresh agents, skills, commands, and AGENTS.md template content.
+
+## Prerequisites
+
+- The project must have `compound-workflow` installed: `npm install compound-workflow`.
+
+## Instructions for the agent
+
+Run in the workspace root (or user-provided root):
+
+```bash
+npx compound-workflow install
+npx compound-workflow install --root /path/to/project
+npx compound-workflow install --dry-run
+```
+
+- `--dry-run`: Print planned changes only; no writes.
+- `--root <path>`: Target project directory (default: current directory).
+
+## What install does
+
+1. Copies agents (flat) to `.claude/agents/` for Claude Code discovery.
+2. Copies agents, skills, and commands to `.cursor/agents/`, `.cursor/skills/`, `.cursor/commands/` for Cursor discovery.
+3. Copies agents, skills, and commands to `.agents/agents/`, `.agents/skills/`, `.agents/commands/` for OpenCode and general use.
+4. Writes/merges `opencode.json` pointing commands and agents at `.agents/`.
+5. Creates/merges `AGENTS.md` using the package template while preserving an existing Repo Config Block.
+6. Creates missing directories: `docs/brainstorms`, `docs/plans`, `docs/solutions`, `docs/metrics/daily|weekly|monthly`, `todos`.
+
+Stale files from previous installs are pruned automatically on each run.

package/src/{.agents/commands → commands}/metrics.md

@@ -32,7 +32,7 @@ It creates or appends to one file under `docs/metrics/daily/`.
    - file: `docs/metrics/daily/YYYY-MM-DD.md`
    - if it exists, append a new "Session" block
 4. Use the template from `process-metrics` skill:
-   - `.agents/skills/process-metrics/assets/daily-template.md`
+   - `process-metrics/assets/daily-template.md` within the skills directory of the current harness (resolve from `harnesses` in AGENTS.md Repo Config)
 5. Ask for the minimum missing fields:
    - workflow (`brainstorm|plan|work|triage|review|compound|test-browser|other`)
    - outcome (`success|partial|failed`)

package/src/{.agents/commands → commands}/test-browser.md

@@ -97,7 +97,7 @@ If installation fails, inform the user and stop.
 
 Before starting tests, ask user if they want to watch the browser:
 
-Use AskQuestion with:
+Use AskUserQuestion with:
 - Question: "Do you want to watch the browser tests run?"
 - Options:
   1. **Headed (watch)** - Opens visible browser window so you can see tests run
@@ -154,7 +154,7 @@ git diff --name-only "origin/${default_branch}"...HEAD
 
 </determine_scope>
 
-### 3. Map Files to Routes
+### 4. Map Files to Routes
 
 <file_to_route_mapping>
 
@@ -175,7 +175,7 @@ Build a list of URLs to test based on the mapping.
 
 </file_to_route_mapping>
 
-### 4. Verify Server is Running
+### 5. Verify Server is Running
 
 <check_server>
 
@@ -200,7 +200,7 @@ Then run `/test-browser` again.
 
 </check_server>
 
-### 5. Test Each Affected Page
+### 6. Test Each Affected Page
 
 <test_pages>
 
@@ -239,7 +239,7 @@ agent-browser screenshot --full page-name-full.png  # Full page
 
 </test_pages>
 
-### 6. Human Verification (When Required)
+### 7. Human Verification (When Required)
 
 <human_verification>
 
@@ -253,7 +253,7 @@ Pause for human input when testing touches:
 | SMS | "Verify you received the SMS code" |
 | External APIs | "Confirm the [service] integration is working" |
 
-Use AskQuestion:
+Use AskUserQuestion:
 ```markdown
 **Human Verification Needed**
 
@@ -268,7 +268,7 @@ Did it work correctly?
 
 </human_verification>
 
-### 7. Handle Failures
+### 8. Handle Failures
 
 <failure_handling>
 
@@ -307,7 +307,7 @@ When a test fails:
 
 </failure_handling>
 
-### 8. Test Summary
+### 9. Test Summary
 
 <test_summary>
 

package/src/commands/workflow-agents.md

@@ -0,0 +1,101 @@
+---
+name: agents
+invocation: workflow:agents
+description: Review and update AGENTS.md to keep skills and agents accurate, consistent, and aligned to current workflow needs
+---
+
+# /workflow:agents
+
+## Purpose
+
+Maintain `AGENTS.md` as the single source of truth for:
+
+- skills
+- agents
+- capability routing
+
+This command reviews the registry and updates it in place.
+
+---
+
+## Modes
+
+### Default (review + update)
+
+/workflow:agents
+
+#### Behaviour
+
+1. Locate registry:
+
+   - src/AGENTS.md
+   - fallback: AGENTS.md
+
+2. Read entire file
+
+3. Review:
+
+   - skills (clarity, overlap, gaps)
+   - agents (scope, supported skills, duplication)
+   - structure (consistency)
+
+4. Fix:
+
+   - tighten vague skills
+   - remove or merge duplicates
+   - add missing capabilities ONLY if:
+     - a clear responsibility exists in the current workflow
+     - no existing skill covers it
+   - align agents to skills
+   - mark outdated entries as deprecated
+   - resolve any ambiguity or overlap during this run
+
+5. Update AGENTS.md
+
+6. Output summary
+
+---
+
+### Validate (no changes)
+
+/workflow:agents validate
+
+#### Behaviour
+
+- read registry
+- report:
+  - overlaps
+  - missing skills
+  - inconsistent structure
+- do NOT update file
+
+---
+
+## Rules
+
+- No step-by-step prompts
+- No partial updates
+- Prefer refinement over expansion
+- Avoid broad/general-purpose skills
+- Keep responsibilities explicit
+- Do not modify other files
+- Do not introduce new skills unless clearly justified by workflow gaps
+- Do not leave unresolved overlaps or unclear definitions
+
+---
+
+## Output
+
+## Registry Update Summary
+
+- Registry: <path>
+
+## Changes
+
+- <refinements>
+- <additions>
+- <deprecations>
+
+## Notes
+
+- <observations>

package/src/{.agents/commands → commands}/workflow-brainstorm.md

@@ -58,7 +58,7 @@ description.
 - Constrained, well-defined scope
 
 **If requirements are already clear:**\
-Use **AskQuestion** to suggest:
+Use **AskUserQuestion** to suggest:
 
 > "Your requirements seem detailed enough to proceed directly to
 > planning. Should I run `/workflow:plan` instead, or would you like to
@@ -97,9 +97,9 @@ Also consider any repo-level guidance files such as `AGENTS.md`.
 
 Engage in collaborative dialogue rather than a rapid question loop.
 
-**Critical (non-negotiable):** Default response shape is **synthesize + discussion prompts + assumptions**. Multiple-choice / AskQuestion only for handoffs (Phase 0, Phase 4) or a single blocking question when the user is stuck.
+**Critical (non-negotiable):** Default response shape is **synthesize + discussion prompts + assumptions**. Multiple-choice / AskUserQuestion only for handoffs (Phase 0, Phase 4) or a single blocking question when the user is stuck.
 
-**Enforcement rule:** Do **not** use AskQuestion during exploration until **after** at least one full dialogue iteration (Synthesize + discussion prompts + Capture). AskQuestion is only for handoffs or when one focused multiple-choice truly unblocks.
+**Enforcement rule:** Do **not** use AskUserQuestion during exploration until **after** at least one full dialogue iteration (Synthesize + discussion prompts + Capture). AskUserQuestion is only for handoffs or when one focused multiple-choice truly unblocks.
 
 **Default cadence (per iteration):**
 
@@ -191,7 +191,7 @@ For each approach, provide:
 Lead with your recommendation and explain why. Apply YAGNI --- prefer
 simpler solutions.
 
-Use **AskQuestion** to confirm preferred direction if needed.
+Use **AskUserQuestion** to confirm preferred direction if needed.
 
 ---
 
@@ -224,7 +224,7 @@ If Open Questions exist:
 
 ### Phase 4: Handoff
 
-Use **AskQuestion** to present next steps:
+Use **AskUserQuestion** to present next steps:
 
 **Question:**
 "Brainstorm captured. What would you like to do next?"

package/src/{.agents/commands → commands}/workflow-compound.md

@@ -68,7 +68,7 @@ Execute the capture by following the **`compound-docs` skill**: gather context,
 
 ### 4. Optional review after capture
 
-User may optionally run `document-review` on the created doc. If the repo has domain guardrail skills that match the doc's problem type/component and those skills exist under `.agents/skills/`, they may be invoked only when the user requests deeper review; do not name or assume skills that are not present.
+User may optionally run `document-review` on the created doc. If the repo has domain guardrail skills that match the doc's problem type/component and those skills exist in the skills directory of the current harness (resolve from `harnesses` in AGENTS.md Repo Config), they may be invoked only when the user requests deeper review; do not name or assume skills that are not present.
 
 ## Preconditions