compound-workflow 1.4.6 → 1.5.0

package/scripts/postinstall.mjs

@@ -38,7 +38,10 @@ function shouldSkip(targetRoot) {
 }
 
 function run() {
-  const targetRoot = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : "";
+  let targetRoot = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : process.cwd();
+  if (!process.env.INIT_CWD) {
+    console.log("[compound-workflow] INIT_CWD not set; using process.cwd() as project root.");
+  }
   const skipReason = shouldSkip(targetRoot);
   if (skipReason) {
     console.log(`[compound-workflow] postinstall skipped (${skipReason})`);

package/src/.agents/commands/install.md

@@ -1,57 +1,45 @@
 ---
 name: install
 invocation: install
-description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, Repo Config Block, and optional Cursor wiring.
-argument-hint: "[all|--all] [--dry-run] [--root <path>] [--no-config] [--cursor]"
+description: Install compound-workflow in this project (native mode): writes opencode.json, merges AGENTS.md, and creates docs/todo dirs.
+argument-hint: "[--dry-run] [--root <path>] [--no-config]"
 ---
 
 # /install
 
-Install or update compound-workflow in this project with **one action**. Writes opencode.json (OpenCode loads from the package), merges AGENTS.md (template + preserved Repo Config Block), creates standard dirs, and reminds you to set the Repo Config Block if needed.
+Install or update compound-workflow in this project with **one action**.
 
 ## When to use
 
-- First time adding compound-workflow to this repo (OpenCode users).
-- After updating the compound-workflow package and you want the latest AGENTS.md template and opencode.json entries.
+- First-time setup in a repository.
+- After updating `compound-workflow` to refresh generated OpenCode command/agent mappings and AGENTS template content.
 
 ## Prerequisites
 
-- The project must have `compound-workflow` installed: `npm install compound-workflow` (or add to dependencies and run `npm install`).
+- The project must have `compound-workflow` installed: `npm install compound-workflow`.
 
 ## Instructions for the agent
 
-Run in the **workspace root** (or the directory the user specifies):
-
-```bash
-npx compound-workflow@latest install
-npx compound-workflow@latest install all
-```
-
-Or with a specific root and flags:
+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
 npx compound-workflow install --no-config
-npx compound-workflow install --cursor
 ```
 
-- **all / --all**: Full install shortcut; same as `--cursor` (creates `.cursor` if missing, then wires skills/agents/commands/references).
-- **--dry-run**: Print planned changes only; no writes.
-- **--root &lt;path&gt;**: Target project directory (default: current directory).
-- **--no-config**: Skip Repo Config Block reminder; only write opencode.json, AGENTS.md merge, and dirs.
-- **--cursor**: Force Cursor integration (create `.cursor` if missing, then wire skills/agents/commands/references).
-
-Do not copy files from a compound-workflow clone; the Install CLI uses the package from `node_modules/compound-workflow`.
+- `--dry-run`: Print planned changes only; no writes.
+- `--root <path>`: Target project directory (default: current directory).
+- `--no-config`: Skip Repo Config Block reminder; still writes opencode.json, AGENTS.md, and dirs.
 
-After running, suggest the user run `opencode debug config` in the project to verify OpenCode sees the commands and agents.
+After running, suggest `opencode debug config` in the project to verify OpenCode resolution.
 
-## What Install does (one run)
+## What Install does
 
-1. Ensures `compound-workflow` is in the project (exits with instructions if not).
-2. Writes/merges **opencode.json** so OpenCode loads commands, agents, and skills from `node_modules/compound-workflow` (no copy into the project).
-3. Creates/merges **AGENTS.md** (template content; preserves existing Repo Config Block).
-4. Creates **docs/brainstorms/**, **docs/plans/**, **docs/solutions/**, **docs/metrics/daily|weekly|monthly/**, **todos/** if missing.
-5. Reminds the user to edit AGENTS.md for the Repo Config Block (default_branch, test_command, lint_command, dev_server_url, etc.) unless `--no-config` was used.
+1. Ensures `compound-workflow` is installed in the project.
+2. Writes/merges `opencode.json` so OpenCode resolves commands/agents/skills directly from `node_modules/compound-workflow/src/.agents`.
+3. Creates/merges `AGENTS.md` using the package template while preserving an existing Repo Config Block.
+4. Creates missing directories: `docs/brainstorms`, `docs/plans`, `docs/solutions`, `docs/metrics/daily|weekly|monthly`, `todos`.
 
-No separate Sync or Setup step; this single command replaces both.
+No setup/sync compatibility paths are supported in this cutover.

package/src/AGENTS.md

@@ -168,7 +168,7 @@ worktree_bootstrap_notes:
 
 ## Implemented Components (Current Scope)
 
-- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
+- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), 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`
 - Agents:
   - `repo-research-analyst`

package/src/generated/opencode.managed.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "skillsPath": "node_modules/compound-workflow/src/.agents/skills",
+  "commandRoot": "node_modules/compound-workflow/src/.agents/commands",
+  "agentRoot": "node_modules/compound-workflow/src/.agents/agents",
+  "commands": [
+    {
+      "id": "assess",
+      "description": "Review recent metrics entries to identify failures/trends and propose concrete improvements to commands/skills/agents",
+      "rel": "assess.md"
+    },
+    {
+      "id": "install",
+      "description": "Install compound-workflow in this project (native mode): writes opencode.json, merges AGENTS.md, and creates docs/todo dirs.",
+      "rel": "install.md"
+    },
+    {
+      "id": "metrics",
+      "description": "Log a metrics entry for the current workflow run so process performance can be reviewed daily/weekly/monthly",
+      "rel": "metrics.md"
+    },
+    {
+      "id": "test-browser",
+      "description": "Run browser tests on pages affected by current PR or branch",
+      "rel": "test-browser.md"
+    },
+    {
+      "id": "workflow:brainstorm",
+      "description": "Explore requirements and approaches through collaborative dialogue before planning implementation",
+      "rel": "workflow/brainstorm.md"
+    },
+    {
+      "id": "workflow:compound",
+      "description": "Document a durable learning (solved problem or implementation insight) into docs/solutions/ to compound institutional knowledge",
+      "rel": "workflow/compound.md"
+    },
+    {
+      "id": "workflow:plan",
+      "description": "Transform feature descriptions into well-structured project plans using an explicit fidelity and confidence model",
+      "rel": "workflow/plan.md"
+    },
+    {
+      "id": "workflow:review",
+      "description": "Review a PR/branch/diff with structured findings. Does not implement fixes unless explicitly requested.",
+      "rel": "workflow/review.md"
+    },
+    {
+      "id": "workflow:triage",
+      "description": "Manual triage command to prioritize todo files into an executable ready queue (priority, dependencies, recommended action)",
+      "rel": "workflow/triage.md"
+    },
+    {
+      "id": "workflow:work",
+      "description": "Execute a plan file systematically (implementation + verification) without auto-shipping",
+      "rel": "workflow/work.md"
+    }
+  ],
+  "agents": [
+    {
+      "id": "agent-native-reviewer",
+      "description": "Reviews code to ensure agent-native parity — any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts.",
+      "rel": "review/agent-native-reviewer.md"
+    },
+    {
+      "id": "best-practices-researcher",
+      "description": "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance.",
+      "rel": "research/best-practices-researcher.md"
+    },
+    {
+      "id": "bug-reproduction-validator",
+      "description": "Systematically reproduces and validates bug reports to confirm whether reported behavior is an actual bug. Use when you receive a bug report or issue that needs verification.",
+      "rel": "workflow/bug-reproduction-validator.md"
+    },
+    {
+      "id": "framework-docs-researcher",
+      "description": "Gathers authoritative documentation for frameworks, libraries, and dependencies. Use when you need official docs, version constraints, breaking changes, or implementation patterns.",
+      "rel": "research/framework-docs-researcher.md"
+    },
+    {
+      "id": "git-history-analyzer",
+      "description": "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes.",
+      "rel": "research/git-history-analyzer.md"
+    },
+    {
+      "id": "learnings-researcher",
+      "description": "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes.",
+      "rel": "research/learnings-researcher.md"
+    },
+    {
+      "id": "lint",
+      "description": "Run repo-configured linting and code quality checks. Use when you need to lint/format or verify code quality.",
+      "rel": "workflow/lint.md"
+    },
+    {
+      "id": "planning-technical-reviewer",
+      "description": "Independent technical reviewer for brainstorm/plan outputs before execution.",
+      "rel": "review/planning-technical-reviewer.md"
+    },
+    {
+      "id": "repo-research-analyst",
+      "description": "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions.",
+      "rel": "research/repo-research-analyst.md"
+    },
+    {
+      "id": "spec-flow-analyzer",
+      "description": "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation.",
+      "rel": "workflow/spec-flow-analyzer.md"
+    }
+  ]
+}

package/scripts/sync-into-repo.sh

@@ -1,103 +0,0 @@
-#!/usr/bin/env bash
-# LEGACY: Prefer "npm install compound-workflow" + "npx compound-workflow install" in the project.
-# Copy src/.agents and src/AGENTS.md from this compound-workflow repo into a host repo.
-# Does not update opencode.json; run Install (npx compound-workflow install) in the project for that.
-set -e
-CLONE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-DRY_RUN=0
-FORCE=0
-TARGET=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/sync-into-repo.sh [--dry-run] [--force] [target_dir]
-
-Copies:
-  - src/.agents  -> <target_dir>/.agents
-  - src/AGENTS.md -> <target_dir>/AGENTS.md (only if missing)
-
-Notes:
-  - Replaces <target_dir>/.agents (prevents .agents/.agents nesting)
-  - Prints absolute paths before writing
-  - Refuses non-git targets unless --force
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --dry-run)
-      DRY_RUN=1
-      shift
-      ;;
-    --force)
-      FORCE=1
-      shift
-      ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [[ -z "$TARGET" ]]; then
-        TARGET="$1"
-        shift
-      else
-        echo "Error: unexpected argument: $1" >&2
-        usage >&2
-        exit 1
-      fi
-      ;;
-  esac
-done
-
-TARGET="${TARGET:-$(dirname "$CLONE_ROOT")}"
-if [[ ! -d "$CLONE_ROOT/src/.agents" || ! -f "$CLONE_ROOT/src/AGENTS.md" ]]; then
-  echo "Error: $CLONE_ROOT is not a compound-workflow clone (missing src/.agents or src/AGENTS.md)" >&2
-  exit 1
-fi
-if [[ ! -d "$TARGET" ]]; then
-  echo "Error: target is not a directory: $TARGET" >&2
-  exit 1
-fi
-TARGET_ABS="$(cd "$TARGET" && pwd)"
-# Host marker validation (escape hatch: --force)
-if [[ "$FORCE" -ne 1 && ! -d "$TARGET_ABS/.git" ]]; then
-  echo "Error: target does not look like a git repo (missing .git): $TARGET_ABS" >&2
-  echo "Hint: pass --force if you really want to sync into a non-git directory." >&2
-  exit 1
-fi
-# Refuse obvious template targets (escape hatch: --force)
-if [[ "$FORCE" -ne 1 && -d "$TARGET_ABS/src/.agents" && -f "$TARGET_ABS/src/AGENTS.md" ]]; then
-  echo "Error: target looks like a compound-workflow template repo (has src/.agents + src/AGENTS.md): $TARGET_ABS" >&2
-  echo "Refusing to sync into a template repo. Pass --force to override." >&2
-  exit 1
-fi
-# Avoid copying into our own src
-if [[ "$TARGET_ABS" == "$(cd "$CLONE_ROOT/src" 2>/dev/null && pwd)" ]] || [[ "$TARGET_ABS" == "$CLONE_ROOT/src" ]]; then
-  echo "Error: target must not be the clone's src directory" >&2
-  exit 1
-fi
-echo "Resolved target: $TARGET_ABS"
-echo "Planned writes:"
-echo "  - $TARGET_ABS/.agents (replace)"
-if [[ ! -f "$TARGET_ABS/AGENTS.md" ]]; then
-  echo "  - $TARGET_ABS/AGENTS.md (create)"
-else
-  echo "  - $TARGET_ABS/AGENTS.md (skip; already exists)"
-fi
-
-if [[ "$DRY_RUN" -eq 1 ]]; then
-  echo "Dry-run: no changes made."
-  exit 0
-fi
-
-echo "Copying into $TARGET_ABS ..."
-rm -rf "$TARGET_ABS/.agents"
-cp -R "$CLONE_ROOT/src/.agents" "$TARGET_ABS/.agents"
-if [[ ! -f "$TARGET_ABS/AGENTS.md" ]]; then
-  cp "$CLONE_ROOT/src/AGENTS.md" "$TARGET_ABS/AGENTS.md"
-else
-  echo "AGENTS.md already exists; skipped copy. Run Install (npx compound-workflow install) in the project to merge template with host AGENTS.md."
-fi
-  echo "Done. Run Install in the project (npx compound-workflow install) to configure opencode.json and AGENTS.md, or run /install in Cursor."

package/src/.agents/commands/setup.md

@@ -1,9 +0,0 @@
----
-name: setup
-description: "(Deprecated) Repo Config Block is now part of /install. Use /install once; then edit AGENTS.md to set default_branch, test_command, lint_command, dev_server_url."
-argument-hint: "Use /install instead; then edit AGENTS.md for Repo Config Block."
----
-
-# /setup (deprecated)
-
-**Use `/install` instead.** The Install command (one action) writes opencode.json, merges AGENTS.md, creates dirs, and preserves your Repo Config Block. After running Install, edit `AGENTS.md` to set `default_branch`, `test_command`, `lint_command`, `dev_server_url`, and other repo defaults in the Repo Config Block YAML section.

package/src/.agents/commands/sync.md

@@ -1,9 +0,0 @@
----
-name: sync
-description: "(Deprecated) Use /install instead. Install compound-workflow in the project with one action (npx compound-workflow install)."
-argument-hint: "Use /install instead."
----
-
-# /sync (deprecated)
-
-**Use `/install` instead.** Run `npx compound-workflow install` in the project—one action that configures opencode.json, AGENTS.md, dirs, and Repo Config Block. No copy from a clone; the package is loaded from `node_modules/compound-workflow`.

package/src/.agents/commands/workflow/review-v2.md

@@ -1,148 +0,0 @@
----
-name: review-v2
-invocation: workflow:review-v2
-description: Experimental PR/branch review with interactive snippet walkthrough (output-only; no publishing)
-argument-hint: "[PR number, GitHub URL, branch name, or 'current']"
----
-
-# /workflow:review-v2
-
-Experimental code review flow focused on **interactive, snippet-by-snippet walkthrough** and **collected, consolidated comments**.
-
-Guardrails (unless explicitly requested):
-
-- Do not modify code or documents
-- Do not create commits
-- Do not push branches
-- Do not create pull requests
-- Do not publish GitHub PR reviews (output-only)
-
-## Inputs
-
-- Target: `$ARGUMENTS`
-  - PR number / GitHub URL (if `gh` is available)
-  - branch name
-  - `current` (current branch)
-
-If empty, default to `current`.
-
-## Execution Workflow
-
-### Phase 0: Resolve Repo Defaults (ALWAYS FIRST)
-
-1. Read `AGENTS.md` and locate the "Repo Config Block" YAML.
-2. Resolve:
-   - `default_branch` (fallback: `main`, then `master`)
-   - `lint_command` (optional; only run if configured)
-
-State what you resolved or assumed.
-
-### Phase 1: Determine Target + Checkout Strategy
-
-Parse `$ARGUMENTS` to resolve:
-
-- `target_type`: `pr | branch | current`
-- `base_branch`
-- `head_branch`
-- (if PR) `pr_number`, `pr_title`, `pr_url`
-
-Resolution rules:
-
-- If `$ARGUMENTS` contains `/pull/`: treat as PR URL.
-  - Extract the PR number and run:
-    - `gh pr view <number> --json headRefName,baseRefName,number,title,url`
-- If `$ARGUMENTS` is only digits: treat as PR number.
-  - Run:
-    - `gh pr view <number> --json headRefName,baseRefName,number,title,url`
-- Else if `$ARGUMENTS == "current"` (or empty): review current branch.
-- Else: treat `$ARGUMENTS` as a branch name; `base_branch = default_branch`.
-
-Checkout strategy:
-
-- Prefer reviewing the **currently checked-out** branch.
-- If the user explicitly targeted a PR/branch that differs from current checkout:
-  - Prefer an isolated worktree for review via `skill: git-worktree` (recommended).
-  - If you cannot/should not switch branches, fall back to `gh pr diff <number>` (PR only) plus local diffing where possible.
-
-### Phase 2: Gather the Diff + Surface Area
-
-1. Determine changed files using (in order):
-   - `@{upstream}...HEAD` when upstream exists
-   - `origin/${base_branch}...HEAD`
-   - `HEAD~1..HEAD`
-2. Run:
-   - `git diff origin/${base_branch}...HEAD --stat`
-   - `git diff origin/${base_branch}...HEAD`
-3. If PR and `gh` is available, also run:
-   - `gh pr diff <number>`
-
-Summarize surface area (changed files, hot paths, risk notes).
-
-### Phase 3: Load Local Conventions
-
-1. Read repo root `AGENTS.md` (already done in Phase 0) for workflow defaults and constraints.
-2. Look for `CLAUDE.md` files:
-   - at repo root
-   - in directories containing modified files
-3. Read any found `CLAUDE.md` files and summarize the applicable conventions you will enforce in this review.
-
-### Phase 4: Interactive Snippet-by-Snippet Walkthrough (V2 Core)
-
-Instead of dumping the full review at once, walk the user through the diff **snippet by snippet**.
-
-Rules:
-
-1. Organize snippets by concern (not file order), usually:
-   - foundational types/interfaces/config
-   - shared helpers/modules
-   - core logic changes
-   - integration edges (I/O, DB, network, auth)
-   - tests + docs
-2. Number each snippet (e.g. `Snippet 3/12`) so the user knows progress.
-3. For each snippet, present:
-   - a minimal diff/code block (only the essential lines)
-   - plain-language explanation (what/why)
-   - what’s good
-   - what’s concerning (specific issue → consequence)
-4. After each snippet, STOP and ask for input:
-   - user comment/note → store it as a collected review comment and confirm you noted it
-   - user question → answer, then continue
-   - user says `next` / `move on` → proceed
-
-Collected comment format (maintain internally as you go):
-
-- `path:line` (approx is fine until final consolidation)
-- severity: `Critical | Important | Suggestion | Nitpick`
-- comment: rewrite user notes into clear, actionable language
-
-### Phase 5: Common Review Patterns to Watch For
-
-Pay special attention to:
-
-- Consistency (constants vs hardcodes, patterns across similar files, loose return types like `any[]`)
-- Architecture (duplication, half-wired integrations, silently removed behavior)
-- Naming & types (misleading names, unexplained config values)
-- LLM/agent code (tool success vs orchestrator blocks, missing prompt updates, duplicated context, confusing injected messages)
-- Maintenance (hardcoded registries that should be co-located)
-
-### Phase 6: Consolidate (Output-Only)
-
-After all snippets, present the **full collected comment list**, organized by severity:
-
-1. Critical / Important (must address before merge)
-2. Suggestions (non-blocking improvements)
-3. Nitpicks (minor consistency/style)
-
-For each comment include:
-
-- file + line reference (best-effort)
-- description
-- suggested fix (when applicable)
-
-Then output:
-
-- Summary (1–3 sentences)
-- Verdict: `Ship it | Needs changes | Needs discussion`
-
-Do **not** publish to GitHub in V2. If the user wants publishing later, that is a separate command/experiment.
-