compound-workflow 1.8.0 → 1.9.0

package/README.md

@@ -1,111 +1,103 @@
-## Compound Workflow
+# Compound Workflow
 
-Compound Workflow is a portable, command-first system for shipping software with less ambiguity and stronger verification.
-It follows a simple cycle: **clarify -> plan -> execute -> verify -> capture**.
+A portable, command-first system for shipping software with less ambiguity and stronger verification.
 
-Use it when you want repeatable delivery without ad-hoc process drift.
+Inspired by [Compound Engineering](https://every.to/guides/compound-engineering) — the idea that small, consistent improvements compound over time into significantly better outcomes. Applied here: every piece of work follows the same cycle, every decision is captured, and every session makes the next one faster.
 
-Inspired by [Compound Engineering](https://every.to/guides/compound-engineering) (Every).
+---
 
-Best fit when you need:
+## What it does
 
-- Clear intent and acceptance criteria before coding
-- Structured execution with explicit review gates
-- A repeatable process that captures reusable learnings
+Compound Workflow gives your AI agent a structured process for turning a request into validated, documented output. Instead of ad-hoc conversations, you get a repeatable cycle:
 
-## Workflow
+**Clarify → Plan → Execute → Verify → Capture**
 
-The workflow turns a request into validated output and reusable team knowledge.
+Each step has an explicit gate. Work doesn't move forward until the previous step is done. Learnings are captured so the next similar problem takes minutes, not hours.
 
-```mermaid
-flowchart LR
-  A["brainstorm"] --> B["plan"] --> C["work (includes triage)"] --> D["review"] --> E["capture"] --> F["metrics"]
-```
+---
 
 ## Get Started
 
-**1. Install the package**
-
 ```bash
 npm install compound-workflow
 ```
 
-**2. Automatic setup**
-
-The package’s `postinstall` script runs and configures your repo: `AGENTS.md`, standard directories, and OpenCode wiring. No separate npx step is needed.
-
-**3. If lifecycle scripts were skipped**
+Postinstall runs automatically and sets up your repo: `AGENTS.md`, standard directories, and OpenCode wiring.
 
-If your package manager didn’t run postinstall, run once:
+If your package manager skipped the lifecycle script, or after updating the package:
 
 ```bash
 npx compound-workflow install
 ```
 
-Restart Cursor after install; enable third-party plugins in Settings if skills/commands don't appear.
+---
 
-**4. After updating the package**
+## The Workflow
 
-To get the latest commands and wiring (e.g. after `npm update compound-workflow` or a new release), run install again so your project’s `opencode.json` is refreshed:
-
-```bash
-npx compound-workflow install
+```
+brainstorm → plan → work → review → compound → metrics
 ```
 
-**What gets configured**
+### `/workflow:brainstorm`
+Clarify what to build before any planning starts. The agent asks structured questions, surfaces ambiguities, and produces a brief that confirms intent and constraints. Nothing gets designed until the "what" is agreed.
 
-- Workflow template in `AGENTS.md`
-- Standard workspace directories (plans, todos, docs)
-- `opencode.json` managed entries pointing at `node_modules/compound-workflow/src/.agents/*`
+### `/workflow:plan`
+Turn the brief into an executable plan. Declares fidelity level (Low / Medium / High), confidence, solution scope, and open questions. Cites local code references and prior solutions. No code is written here.
 
-## Breaking Change (2.0.0)
+### `/workflow:work`
+Execute the approved plan. The agent derives todo contracts, isolates work in a git worktree, applies the standards gate, runs triage, delegates to subagents, and collects verified output. Evidence is required before any todo moves to complete.
 
-2.0.0 removes all legacy compatibility pathways (`/setup`, `/sync`, runtime mirror copies, and Cursor sync fallbacks).
-See migration notes in [docs/migrations/2026-03-03-v2-native-cutover.md](docs/migrations/2026-03-03-v2-native-cutover.md).
+### `/workflow:review`
+Independent quality check before the work is considered done. Runs in a separate pass from the implementer. Emits a clear pass / fail with standards compliance noted. Required for code and config changes.
 
-## Critical Path
+### `/workflow:compound`
+Capture what was learned. Writes a structured solution doc to `docs/solutions/` with searchable YAML frontmatter. The first time you solve a problem takes research — document it and the next occurrence takes minutes.
 
-After install, use this default sequence:
+### `/metrics` and `/assess`
+Log session outcomes and spot trends. `/metrics` records a single session. `/assess` rolls up recent entries and proposes concrete improvements to commands, skills, or config.
 
-1. `/workflow:brainstorm` for requirements clarity
-2. `/workflow:plan` for implementation design
-3. `/workflow:work` to execute against the approved plan (includes automatic triage)
-4. `/workflow:review` to validate quality before completion
-5. `/workflow:compound` to capture reusable learnings
+---
 
-Optional:
+## Optional Commands
 
-- `/workflow:triage` for manual backlog curation before or during execution
-- `/metrics` and `/assess` for process improvement
+**`/workflow:triage`** — Manually curate and prioritise a backlog before execution. `/workflow:work` runs triage automatically, but this gives you explicit control when the queue is complex.
 
-## Commands (Quick Map)
+**`/workflow:tech-review`** — Technical correctness check on a plan before build. Use when the approach needs a second opinion before committing to implementation.
 
-Core flow: `/workflow:brainstorm` -> `/workflow:plan` -> `/workflow:work` -> `/workflow:review` -> `/workflow:compound` -> `/metrics` (optional `/assess` for rollups).
+**`/test-browser`** — Browser-level validation of affected routes. Useful for UI changes where automated tests aren't enough.
 
-| Command                | Purpose                                                                                                      | Related skills                                                                   | Related agents                                                                                                                                                                         |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/install`             | Configure workflow files and runtime wiring in the repo                                                      | install CLI (no workflow skill routing)                                          | none                                                                                                                                                                                   |
-| `/workflow:brainstorm` | Clarify what to build through structured discussion                                                          | `brainstorming` (primary), `document-review` (optional refinement)               | `repo-research-analyst`                                                                                                                                                                |
-| `/workflow:plan`       | Convert intent into an executable plan with fidelity/confidence                                              | state-orchestration skill when needed (for example `xstate-actor-orchestration`) | `repo-research-analyst`, `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher`, `git-history-analyzer`, `spec-flow-analyzer`, `planning-technical-reviewer` |
-| `/workflow:triage`     | Manual queue curation for complex/multi-item backlogs (optional; `/workflow:work` runs triage automatically) | `file-todos`                                                                     | none                                                                                                                                                                                   |
-| `/workflow:work`       | Execute plan/todos with quality gates and validation evidence                                                | `git-worktree`, `file-todos`, `standards`, state-orchestration skill when needed | `repo-research-analyst`, `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher`, `git-history-analyzer`                                                      |
-| `/workflow:review`     | Perform independent quality review before completion                                                         | `git-worktree` (for non-current targets), `standards`                            | `learnings-researcher`, `lint`, `bug-reproduction-validator`, `git-history-analyzer`, `framework-docs-researcher`, `agent-native-reviewer`                                             |
-| `/workflow:compound`   | Capture reusable implementation learnings in `docs/solutions/`                                               | `compound-docs` (primary), `document-review` (optional)                          | `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher`                                                                                                       |
-| `/metrics`             | Log session outcomes and improvement actions                                                                 | `process-metrics`, `file-todos` (optional for follow-ups)                        | none                                                                                                                                                                                   |
-| `/assess`              | Aggregate metrics trends and propose process improvements                                                    | `file-todos` (for approved follow-up actions)                                    | none                                                                                                                                                                                   |
-| `/test-browser`        | Validate affected routes with browser-level checks                                                           | `agent-browser`, `git-worktree` (optional branch isolation)                      | none                                                                                                                                                                                   |
+**`/install`** — Re-run setup. Safe to run again after updating the package or adding a new harness.
 
-Canonical command docs: [src/.agents/commands/](src/.agents/commands/)
+---
 
-## Learn More
+## How it's structured
+
+Skills and agents are the internals. Commands are the public API — stable entry points that compose the right skills for each phase.
+
+| Layer | What it is |
+| --- | --- |
+| **Commands** (`src/commands/`) | What you invoke. Orchestrate the workflow steps. |
+| **Skills** (`src/skills/`) | Focused capabilities loaded by commands when needed. |
+| **Agents** (`src/agents/`) | Specialised subagents for research, review, and analysis. |
+| **AGENTS.md** | Project config: repo settings, harness list, skill index. |
+
+On install, files are copied into whichever harness directories are present in your project (`.agents/`, `.cursor/`, `.claude/`). No symlinks, no generated manifests.
 
-- Workflow principles: [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md)
-- Project command and policy index: [src/AGENTS.md](src/AGENTS.md)
-- Command definitions: [src/.agents/commands/](src/.agents/commands/)
+---
 
-If docs conflict: follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then command docs.
+## Guardrails
 
-Guardrails:
+- **Independent review policy:** code/config changes require `/workflow:review` before workflow completion. Docs-only changes are exempt.
+- **Standards baseline policy:** `/workflow:work` and `/workflow:review` both apply the standards baseline. Violations block completion.
+- **No ad-hoc artifacts** — output goes to `docs/plans`, `docs/solutions`, `todos`, or `docs/metrics`. Nothing else.
+
+If docs conflict: follow `docs/principles/workflow-baseline-principles.md`, then `AGENTS.md`, then command docs, then skill docs.
+
+---
+
+## Learn More
 
-- Independent review policy: code/config changes require `/workflow:review` before workflow completion (docs-only changes are exempt).
-- Standards baseline policy: code/config changes must pass the standards baseline gate in `/workflow:work` and `/workflow:review`.
+- [Workflow principles](docs/principles/workflow-baseline-principles.md)
+- [AGENTS.md](src/AGENTS.md) — command index, repo config, skill routing
+- [Commands](src/commands/) — full command specs
+- [Skills](src/skills/) — skill docs and templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {
@@ -12,16 +12,10 @@
   },
   "files": [
     "src",
-    "scripts",
-    ".cursor-plugin",
-    ".claude-plugin"
+    "scripts"
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "prepublishOnly": "npm run generate:artifacts",
-    "generate:artifacts": "node scripts/generate-platform-artifacts.mjs",
-    "check:artifacts": "node scripts/generate-platform-artifacts.mjs --check",
-    "check:version-parity": "node scripts/check-version-parity.mjs",
     "check:pack-readme": "node scripts/check-pack-readme.mjs",
     "test:install": "node --test tests/install-cli.test.mjs"
   },

package/scripts/check-pack-readme.mjs

@@ -31,9 +31,6 @@ try {
 
 const files = Array.isArray(report) && report[0]?.files ? report[0].files : [];
 const hasRootReadme = files.some((file) => /^readme(?:\.[^/]+)?$/i.test(file.path));
-const hasGeneratedManifest = files.some((file) => file.path === "src/generated/opencode.managed.json");
-const hasCursorPlugin = files.some((file) => file.path === ".cursor-plugin/plugin.json");
-const hasClaudePlugin = files.some((file) => file.path === ".claude-plugin/plugin.json");
 
 if (!hasRootReadme) {
   console.error("Package guard failed: root README is missing from the packed tarball.");
@@ -41,16 +38,4 @@ if (!hasRootReadme) {
   process.exit(1);
 }
 
-if (!hasGeneratedManifest) {
-  console.error("Package guard failed: src/generated/opencode.managed.json is missing from the packed tarball.");
-  console.error("Ensure 'src' is in package.json 'files' and the file is committed or generated before publish.");
-  process.exit(1);
-}
-
-if (!hasCursorPlugin || !hasClaudePlugin) {
-  console.error("Package guard failed: .cursor-plugin/plugin.json and .claude-plugin/plugin.json must be in the packed tarball.");
-  console.error("Ensure '.cursor-plugin' and '.claude-plugin' are in package.json 'files'.");
-  process.exit(1);
-}
-
-console.log("Package guard passed: root README, opencode.managed.json, and plugin manifests are present in npm pack output.");
+console.log("Package guard passed: root README is present in npm pack output.");

package/scripts/check-workflow-contracts.mjs

@@ -58,126 +58,116 @@ const requiredChecks = [
     description: "README standards baseline guardrail",
   },
   {
-    file: "src/.agents/commands/workflow-plan.md",
+    file: "src/commands/workflow-plan.md",
     pattern: "Contract precedence:",
     description: "plan command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow-triage.md",
+    file: "src/commands/workflow-triage.md",
     pattern: "Contract precedence:",
     description: "triage command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow-triage.md",
+    file: "src/commands/workflow-triage.md",
     pattern: "independently runnable",
     description: "triage command explicitly standalone while work auto-runs triage",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern: "Contract precedence:",
     description: "work command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow-plan.md",
+    file: "src/commands/workflow-plan.md",
     pattern: "Start `/workflow:work`",
     description: "plan command default next-step routes to work",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "HARD GATE - WORKTREE FIRST",
-    description: "worktree hard-gate wording in work command",
+    file: "src/commands/workflow-work.md",
+    pattern: "Environment Setup (Hard Gate)",
+    description: "worktree hard-gate section in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "required prompt/create gate",
-    description: "mandatory worktree decision prompt/create gate in work command",
+    file: "src/commands/workflow-work.md",
+    pattern: "Opt-out requires explicit user confirmation.",
+    description: "worktree decision requires explicit opt-out in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "Do not infer or assume an answer when the user has not answered.",
-    description: "worktree decision cannot be silently assumed",
+    file: "src/commands/workflow-work.md",
+    pattern: "Yes / No — explicit opt-out required",
+    description: "worktree decision prompt is explicit yes/no in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern:
       "No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.",
     description: "pre-gate write/command prohibition in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "workflow_complete: false (pending /workflow:review current)",
-    description: "implementation-complete pending-review status in work command",
+    file: "src/commands/workflow-work.md",
+    pattern: "gate_status: passed",
+    description: "gate_status must be recorded before proceeding in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "Standards Compliance Gate (REQUIRED for code/config changes)",
-    description: "required standards gate in work command",
-  },
-  {
-    file: "src/.agents/commands/workflow-work.md",
-    pattern: "This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).",
-    description: "standards gate ordering with worktree gate",
-  },
-  {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "Contract precedence:",
     description: "review command precedence note",
   },
   {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "Independent Reviewer Pass (REQUIRED)",
     description: "required independent reviewer pass in review command",
   },
   {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "review_independence_mode: independent|degraded",
     description: "explicit review independence mode in review command",
   },
   {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "what was skipped and why",
     description: "review skipped-pass disclosure requirement",
   },
   {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "standards_compliance: pass|pass-with-notes|fail",
     description: "review standards compliance output field",
   },
   {
-    file: "src/.agents/commands/workflow-review.md",
+    file: "src/commands/workflow-review.md",
     pattern: "standards `MUST` violations => blocking finding and review recommendation `fail`",
     description: "review must-violation fail criteria",
   },
   {
-    file: "src/.agents/skills/standards/SKILL.md",
-    pattern: "## Mandatory Baseline (Declarative, Immutable, Maintainable)",
-    description: "standards mandatory baseline section",
+    file: "src/skills/standards/SKILL.md",
+    pattern: "## Mandatory Gates",
+    description: "standards mandatory gates section",
   },
   {
-    file: "src/.agents/skills/standards/SKILL.md",
-    pattern: "### MUST NOT",
-    description: "standards must-not checklist",
+    file: "src/skills/standards/SKILL.md",
+    pattern: "pass|fail",
+    description: "standards gates are pass/fail",
   },
 ];
 
 const forbiddenChecks = [
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern: "## When to Use Reviewer Agents",
     description: "legacy optional reviewer section in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern: "**Don't use by default.**",
     description: "legacy skip-by-default reviewer wording in work command",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern: "skip specialist reviewers by default",
     description: "legacy skip-by-default specialist reviewer wording",
   },
   {
-    file: "src/.agents/commands/workflow-work.md",
+    file: "src/commands/workflow-work.md",
     pattern: "Follow project coding standards (see AGENTS.md)",
     description: "legacy advisory-only coding standards wording in work command",
   },