compound-workflow 1.8.0 → 1.9.0

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/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-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
 

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

@@ -94,22 +94,6 @@ Refine the idea through collaborative dialogue using **AskQuestion**:
 **Skip option:** If the feature description is already detailed, offer:
 "Your description is clear. Should I proceed with research, or would you like to refine it further?"
 
-### 0.5. State-Orchestration Fit Check (Decision in planning)
-
-Before finalizing architecture, decide whether to load an appropriate
-state-orchestration skill (see Skill Index in AGENTS.md; e.g.
-`xstate-actor-orchestration` when the stack uses that approach).
-
-Load one when complexity exceeds simple local state, especially for:
-
-- UI flows where a React container should orchestrate context/state and
-  compose presentational components
-- Backend/internal workflows with hidden state complexity, lifecycle
-  management, retries/timeouts/cancellation, or actor coordination
-- Cases where more than one boolean/flag currently controls flow
-
-If not selected, document why simpler state management is sufficient.
-
 ## Main Tasks
 
 ### 1. Local Research (Always Runs - Parallel)
@@ -123,11 +107,13 @@ Run these agents **in parallel** to gather local context:
 - Task repo-research-analyst(feature_description)
 - Task learnings-researcher(feature_description)
 
+Also read the Skill Index from `AGENTS.md` directly — capture which skills are available and their trigger conditions. This will be used to annotate plan tasks with relevant skills in Step 1.6.
+
 **What to look for:**
 
 - **Repo research:** existing patterns, AGENTS.md guidance, technology familiarity, pattern consistency
-- Also consider repo-level guidance files such as `AGENTS.md`.
 - **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
+- **Skill Index:** available skills, their purpose, and when to apply them
 
 These findings inform the next step.
 
@@ -250,6 +236,7 @@ After all research steps complete, consolidate findings:
 - Note external documentation URLs and best practices (if external research was done)
 - List related issues or PRs discovered
 - Capture AGENTS.md conventions
+- **Annotate skill assignments:** for each planned implementation phase or task, identify the relevant skills from the Skill Index. Record these as `required_skills` per phase/task — they will be embedded in the plan and consumed by `/workflow:work` when delegating to subagents.
 
 **Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
 
@@ -261,7 +248,9 @@ Run flow/gap analysis to surface missing requirements before locking structure:
 - **Medium fidelity:** recommended
 - **High fidelity:** required
 
-When running: Task spec-flow-analyzer(feature_description, research_findings). Then incorporate identified gaps and edge cases into the upcoming issue structure and acceptance criteria.
+**Step 1 — Dispatch subagent:** Task spec-flow-analyzer(feature_description, research_findings)
+
+**Step 2 — Parent review:** Once findings are returned, assess whether gaps and edge cases are adequately surfaced. If coverage is insufficient or a critical flow was missed, re-dispatch with refined context before locking structure. Incorporate confirmed gaps into the upcoming issue structure and acceptance criteria.
 
 ### 2. Issue Planning & Structure
 
@@ -333,13 +322,6 @@ Placement:
 - Add a dedicated section in the plan body: `## Agentic Access & Validation Contract`.
 - Reference this section from implementation phases/todos so `/workflow:work` can enforce it directly.
 
-### 3. Incorporate SpecFlow (if Step 1.7 ran)
-
-If SpecFlow was run in Step 1.7:
-
-- [ ] Review SpecFlow analysis results
-- [ ] Ensure any identified gaps or edge cases are reflected in the issue structure and acceptance criteria
-
 ### 3.5. Discussion Points & Spike Candidates
 
 When you declared Open questions in Step 1.5 (other than "none"), and/or when risky-work spike evaluation requires spikes, the plan file MUST include one or both sections below with checkboxes so `/workflow:work` and `file-todos` can create pending todos for triage:
@@ -467,6 +449,13 @@ solution_scope: [partial_fix|full_remediation|migration]
   - lint: [command or "ask once if not configured"]
   - typecheck: [command or "ask once if not configured"]
 
+## Implementation Tasks
+
+- [ ] Task: [description]
+  - required_skills: [skill1, skill2]
+- [ ] Task: [description]
+  - required_skills: [skill1]
+
 ## References
 
 - Related issue: #[issue_number]
@@ -557,6 +546,13 @@ solution_scope: [partial_fix|full_remediation|migration]
 
 [What to monitor; how to test and validate]
 
+## Implementation Tasks
+
+- [ ] Task: [description]
+  - required_skills: [skill1, skill2]
+- [ ] Task: [description]
+  - required_skills: [skill1]
+
 ## Agentic Access & Validation Contract
 
 - Access Preconditions: [services/fixtures/env needed]
@@ -636,18 +632,21 @@ solution_scope: [partial_fix|full_remediation|migration]
 #### Phase 1: [Foundation]
 
 - Tasks and deliverables
+- required_skills: [skill1, skill2]
 - Success criteria
 - Estimated effort
 
 #### Phase 2: [Core Implementation]
 
 - Tasks and deliverables
+- required_skills: [skill1, skill2]
 - Success criteria
 - Estimated effort
 
 #### Phase 3: [Polish & Optimization]
 
 - Tasks and deliverables
+- required_skills: [skill1]
 - Success criteria
 - Estimated effort
 
@@ -793,14 +792,6 @@ Apply best practices for clarity and actionability, making the issue easy to sca
 </details>
 ````
 
-**AI-Era Considerations:**
-
-- [ ] Account for accelerated development with AI pair programming
-- [ ] Include prompts or instructions that worked well during research
-- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
-- [ ] Emphasize comprehensive testing given rapid implementation
-- [ ] Document any AI-generated code that needs human review
-
 ### 6. Final Review & Submission
 
 **Pre-submission Checklist:**