compound-workflow 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "compound-workflow",
+  "owner": { "name": "Compound Workflow" },
+  "plugins": [
+    {
+      "name": "compound-workflow",
+      "source": ".",
+      "description": "Clarify → plan → execute → verify → capture workflow. Commands, skills, and agents for structured development."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "compound-workflow",
+  "version": "0.1.0",
+  "description": "Clarify → plan → execute → verify → capture workflow: commands, skills, and agents for Claude Code",
+  "author": { "name": "Compound Workflow" },
+  "keywords": ["workflow", "planning", "agents", "skills", "commands"],
+  "license": "MIT",
+  "repository": "https://github.com/your-org/compound-workflow",
+  "commands": "./src/.agents/commands",
+  "agents": "./src/.agents/agents",
+  "skills": "./src/.agents/skills"
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "compound-workflow",
+  "version": "0.1.0",
+  "description": "Clarify → plan → execute → verify → capture workflow: commands, skills, and agents for Cursor, Claude, and OpenCode",
+  "author": { "name": "Compound Workflow" },
+  "keywords": ["workflow", "cursor", "claude", "opencode", "agents", "planning"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/your-org/compound-workflow" },
+  "skills": "src/.agents/skills",
+  "agents": "src/.agents/agents",
+  "commands": "src/.agents/commands"
+}

package/README.md

@@ -0,0 +1,155 @@
+# Compound Workflow (.agents)
+
+A portable, command-first workflow: **clarify → plan → execute → verify → capture**. Commands are the public API; skills and agents are composable internals.
+
+It reduces delivery failures from **unclear intent**, **weak verification**, and **lost context**. Use it when you want structured cycles without ad-hoc tooling.
+
+*This template and README are continually refined during development.*
+
+Inspired by [Compound Engineering](https://every.to/guides/compound-engineering) (Every) — the AI-native philosophy that each unit of work should compound into the next.
+
+Runtime assets live in `src/.agents/` and `src/AGENTS.md`. **Cursor/Claude:** load via plugin. **OpenCode:** install the npm package and run Install once.
+
+---
+
+## Get started
+
+**One action:** In your project (with compound-workflow as a dependency), run **Install**—either the `/install` command in Cursor/Claude or:
+
+```bash
+npm install compound-workflow
+npx compound-workflow install
+```
+
+Optional: `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder).
+
+Install writes `opencode.json` (OpenCode loads from the package), merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs, and reminds you to set the Repo Config Block in `AGENTS.md` if needed. No copy; Cursor/Claude use the plugin; OpenCode reads from `node_modules/compound-workflow`.
+
+**Cursor / Claude:** Add the compound-workflow plugin (from this repo or marketplace). Then in any repo you can run `/install` or use the CLI above.
+
+**Legacy (clone inside repo):** If you cloned this repo inside a host repo and need to copy files without npm, use `./scripts/sync-into-repo.sh` (copy only; does not update opencode.json). Prefer the npm + Install flow above.
+
+To update to a new release, see [Updating compound-workflow](#updating-compound-workflow).
+
+---
+
+## Updating compound-workflow
+
+- **Cursor / Claude (plugin):** Update via the editor’s plugin/marketplace (check for updates or reinstall). If installed from repo, pull latest and reload the plugin. No per-project step; the plugin loads commands/skills from its installed source.
+- **OpenCode / npm:** Run `npm update compound-workflow` (or bump the version in `package.json` and `npm install`), then run **Install** again: `/install` or `npx compound-workflow install`. This refreshes `opencode.json`, merges the latest `AGENTS.md` template, and ensures dirs exist; Repo Config Block is preserved.
+
+---
+
+## Workflow at a glance
+
+Clarify what to build → plan how (fidelity + confidence) → execute via todos → triage and review → capture learnings → log and assess.
+
+```mermaid
+flowchart LR
+  A[brainstorm] --> B[plan] --> C[work] --> D[triage] --> E[review] --> F[compound] --> G[metrics]
+```
+
+---
+
+## Step-by-step: intent and commands
+
+| Step | Intent | Command | Output / note |
+|------|--------|---------|---------------|
+| Clarify what to build | Dialogue only; no code | `/workflow:brainstorm [topic]` | `docs/brainstorms/` |
+| Define how (fidelity + confidence) | Plan only; no code | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
+| Execute | File-based todos; risk-tier testing; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
+| Ready the queue | Priority and dependencies for pending todos | `/workflow:triage` | — |
+| Validate quality | Evidence-based review; no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
+| Capture learnings | One solution doc for future use | `/workflow:compound [context]` | `docs/solutions/` |
+| Log and improve | Session log + optional aggregate review | `/metrics` + `/assess weekly 7` (or monthly) | `docs/metrics/daily/`, weekly/monthly |
+
+#### 1. Clarify (brainstorm)
+
+**Intent:** Dialogue only; no code. **Command:** `/workflow:brainstorm [topic]`. **Output:** `docs/brainstorms/`.
+
+#### 2. Define how (plan)
+
+**Intent:** Plan only; no code; fidelity + confidence. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
+
+#### 3. Execute (work)
+
+**Intent:** File-based todos; risk-tier testing; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
+
+#### 4. Ready the queue (triage)
+
+**Intent:** Priority and dependencies for pending todos. **Command:** `/workflow:triage`. **Output:** —.
+
+#### 5. Validate quality (review)
+
+**Intent:** Evidence-based review; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
+
+#### 6. Capture learnings (compound)
+
+**Intent:** One solution doc for future use. **Command:** `/workflow:compound [context]`. **Output:** `docs/solutions/`.
+
+#### 7. Log and improve
+
+**Intent:** Session log + optional aggregate review. **Command:** `/metrics` + `/assess weekly 7` (or monthly). **Output:** `docs/metrics/daily/`, weekly/monthly.
+
+**Optional QA:** **`/test-browser [PR|branch|current]`** — Browser validation on affected pages via **agent-browser CLI only** (not MCP). Install: `npm install -g agent-browser` then `agent-browser install`. See [src/.agents/commands/test-browser.md](src/.agents/commands/test-browser.md).
+
+---
+
+## Command reference
+
+**Onboarding:** `/install` — one action: writes opencode.json, merges AGENTS.md, creates dirs, preserves Repo Config Block. Run `npx compound-workflow install` in the project (requires `npm install compound-workflow`). Re-run after `npm update compound-workflow` to refresh config; see [Updating compound-workflow](#updating-compound-workflow).
+
+**Core workflow:** See [Step-by-step](#step-by-step-intent-and-commands) above.
+
+**QA:** `/test-browser [PR|branch|current]` — browser checks on affected routes (agent-browser CLI only).
+
+**Improvement:** `/metrics [plan|todo|pr|solution|label]` — log session to `docs/metrics/daily/` and assess. `/assess [daily|weekly|monthly] [count]` — aggregate metrics and optional summary files.
+
+**Experimental:** `/workflow:review-v2 [PR|branch|current]` — interactive snippet review; output-only (no GitHub publish).
+
+Full detail: [src/AGENTS.md](src/AGENTS.md), [src/.agents/commands/](src/.agents/commands/).
+
+---
+
+## Artifacts
+
+- **Brainstorms:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
+- **Plans:** `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`
+- **Todos:** `todos/{id}-{status}-{priority}-{slug}.md`
+- **Solutions:** `docs/solutions/<category>/YYYY-MM-DD-<module-slug>-<symptom-slug>.md`
+- **Metrics:** `docs/metrics/daily/YYYY-MM-DD.md`, `docs/metrics/weekly/YYYY-WW.md`, `docs/metrics/monthly/YYYY-MM.md`
+
+---
+
+## How it works (internals)
+
+Commands are the public API. Skills and agents are invoked by commands; you don’t call them directly.
+
+- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`.
+- **Guardrail standards:** `data-foundations`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability` — applied when work touches multi-tenant data, PII, money, or audit.
+- **Agents:** Used by plan, review, and work for research, lint, and validation (e.g. `repo-research-analyst`, `learnings-researcher`, `git-history-analyzer`, `agent-native-reviewer`).
+
+Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.md).
+
+---
+
+## Guardrails
+
+- **No auto-ship:** `/workflow:work` and `/workflow:review` do not commit, push, or create PRs by default.
+
+- **Brainstorm and plan do not write code.** Output is documents only.
+
+- Add a separate shipping command if you want automated commit/PR and quality gates.
+
+---
+
+## Configuration and optional bits
+
+**Repo configuration:** Commands read a **Repo Config Block** (YAML) in `AGENTS.md` for `default_branch`, `dev_server_url`, `test_command`, etc. Run **`/install`** once; then edit `AGENTS.md` to set the Repo Config Block.
+
+**agent-browser:** `/test-browser` uses the agent-browser CLI only. Install: `npm install -g agent-browser` then `agent-browser install`. See [src/.agents/commands/test-browser.md](src/.agents/commands/test-browser.md).
+
+**Source of truth**
+
+- Workflows and commands: [src/.agents/](src/.agents/)
+- Principles and skill index: [src/AGENTS.md](src/AGENTS.md)

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "compound-workflow",
+  "version": "0.1.1",
+  "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/compound-workflow.git"
+  },
+  "bin": {
+    "compound-workflow": "scripts/install-cli.mjs"
+  },
+  "files": [
+    "src",
+    "scripts",
+    ".cursor-plugin",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install-cli.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * compound-workflow install
+ * One action: opencode.json (load from package) + AGENTS.md merge + dirs + Repo Config Block.
+ * Run from project: npx compound-workflow install [--root <dir>] [--dry-run] [--no-config]
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function usage(exitCode = 0) {
+  const msg = `
+Usage:
+  npx compound-workflow install [--root <projectDir>] [--dry-run] [--no-config]
+
+One action: writes opencode.json (loads from package), merges AGENTS.md, creates dirs,
+and prompts for Repo Config Block (unless --no-config).
+
+  --root <dir>   Project directory (default: cwd)
+  --dry-run      Print planned changes only
+  --no-config   Skip Repo Config Block prompt (only write opencode.json + AGENTS.md + dirs)
+`;
+  (exitCode === 0 ? console.log : console.error)(msg.trimStart());
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const out = { root: process.cwd(), dryRun: false, noConfig: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--no-config") out.noConfig = true;
+    else if (a === "--root") {
+      const v = argv[i + 1];
+      if (!v) usage(1);
+      out.root = v;
+      i++;
+    }     else if (a === "-h" || a === "--help") usage(0);
+    else if (a && a !== "install" && !a.startsWith("-")) usage(1);
+  }
+  return out;
+}
+
+function realpathSafe(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+const packageRoot = realpathSafe(path.join(__dirname, ".."));
+const packageAgents = path.join(packageRoot, "src", ".agents");
+const PKG_PREFIX = "node_modules/compound-workflow";
+
+function walkFiles(dirAbs, predicate) {
+  const out = [];
+  const stack = [dirAbs];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const p = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else if (e.isFile() && predicate(p)) out.push(p);
+    }
+  }
+  out.sort();
+  return out;
+}
+
+function parseFrontmatter(md) {
+  if (!md.startsWith("---\n") && !md.startsWith("---\r\n")) return {};
+  const end = md.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const block = md.slice(4, end + 1);
+  const out = {};
+  for (const line of block.split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)\s*$/);
+    if (!m) continue;
+    let v = (m[2] ?? "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+function discoverCommands(agentsRoot) {
+  const commandsDir = path.join(agentsRoot, "commands");
+  const files = walkFiles(commandsDir, (p) => p.endsWith(".md"));
+  const map = new Map();
+  for (const fileAbs of files) {
+    const rel = path.relative(packageRoot, fileAbs).replaceAll(path.sep, "/");
+    const md = fs.readFileSync(fileAbs, "utf8");
+    const fm = parseFrontmatter(md);
+    const id = (fm.invocation || fm.name || path.basename(fileAbs, ".md")).trim();
+    const description = (fm.description || id).trim();
+    if (!id) continue;
+    const pkgRel = `${PKG_PREFIX}/${rel}`;
+    map.set(id, { id, rel: pkgRel, description });
+  }
+  return map;
+}
+
+function discoverAgents(agentsRoot) {
+  const agentsDir = path.join(agentsRoot, "agents");
+  const files = walkFiles(agentsDir, (p) => p.endsWith(".md"));
+  const map = new Map();
+  for (const fileAbs of files) {
+    const rel = path.relative(packageRoot, fileAbs).replaceAll(path.sep, "/");
+    const md = fs.readFileSync(fileAbs, "utf8");
+    const fm = parseFrontmatter(md);
+    const id = (fm.name || path.basename(fileAbs, ".md")).trim();
+    const description = (fm.description || id).trim();
+    if (!id) continue;
+    const pkgRel = `${PKG_PREFIX}/${rel}`;
+    map.set(id, { id, rel: pkgRel, description });
+  }
+  return map;
+}
+
+function ensureObject(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+
+function stripJsonc(input) {
+  let out = "";
+  let i = 0;
+  let inStr = false,
+    strQuote = "",
+    escape = false;
+  while (i < input.length) {
+    const c = input[i];
+    const n = input[i + 1];
+    if (inStr) {
+      out += c;
+      if (escape) escape = false;
+      else if (c === "\\") escape = true;
+      else if (c === strQuote) inStr = false;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inStr = true;
+      strQuote = c;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && n === "/") {
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function readJsonMaybe(fileAbs) {
+  if (!fs.existsSync(fileAbs)) return null;
+  const raw = fs.readFileSync(fileAbs, "utf8");
+  return JSON.parse(stripJsonc(raw));
+}
+
+function writeOpenCodeJson(targetRoot, dryRun) {
+  const opencodeAbs = path.join(targetRoot, "opencode.json");
+  const existing = readJsonMaybe(opencodeAbs) ?? {};
+  const next = structuredClone(existing);
+
+  next.$schema = next.$schema || "https://opencode.ai/config.json";
+  next.skills = ensureObject(next.skills);
+  const skillsPath = `${PKG_PREFIX}/src/.agents/skills`;
+  if (!Array.isArray(next.skills.paths)) next.skills.paths = [];
+  if (!next.skills.paths.includes(skillsPath)) next.skills.paths.unshift(skillsPath);
+  next.command = ensureObject(next.command);
+  next.agent = ensureObject(next.agent);
+
+  const commands = discoverCommands(packageAgents);
+  const agents = discoverAgents(packageAgents);
+
+  for (const [id, cmd] of commands) {
+    next.command[id] = {
+      ...ensureObject(next.command[id]),
+      description: cmd.description,
+      agent: "build",
+      template: `@AGENTS.md\n@${cmd.rel}\nArguments: $ARGUMENTS\n`,
+    };
+  }
+  for (const [id, ag] of agents) {
+    next.agent[id] = {
+      ...ensureObject(next.agent[id]),
+      description: ag.description,
+      mode: "subagent",
+      prompt: `{file:${ag.rel}}`,
+      permission: { ...ensureObject(next.agent[id]?.permission), edit: "deny" },
+    };
+  }
+
+  const out = JSON.stringify(next, null, 2) + "\n";
+  if (dryRun) {
+    console.log("[dry-run] Would write opencode.json:", opencodeAbs);
+    return;
+  }
+  fs.writeFileSync(opencodeAbs, out, "utf8");
+  console.log("Wrote:", opencodeAbs);
+}
+
+function extractRepoConfigBlock(md) {
+  const match = md.match(/(### Repo Config Block[^\n]*\n)?\s*```yaml\n([\s\S]*?)```/);
+  if (!match) return { block: null, rest: md };
+  const full = match[0];
+  const block = match[2].trim();
+  const rest = md.replace(full, "").replace(/\n{3,}/g, "\n\n").trim();
+  return { block, rest };
+}
+
+function mergeAgentsMd(templateMd, existingMd) {
+  const { block: existingBlock, rest: existingRest } = existingMd
+    ? extractRepoConfigBlock(existingMd)
+    : { block: null, rest: "" };
+  const { block: _tplBlock, rest: templateRest } = extractRepoConfigBlock(templateMd);
+  let out = templateRest;
+  if (existingBlock) {
+    const repoSection =
+      "### Repo Config Block (Optional)\n\n```yaml\n" + existingBlock + "\n```\n";
+    if (!out.includes("### Repo Config Block")) {
+      out = out.replace("## Repo Configuration (Optional)", "## Repo Configuration (Optional)\n\n" + repoSection);
+    } else {
+      out = out.replace(/### Repo Config Block[^\n]*\n\s*```yaml\n[\s\S]*?```/, repoSection);
+    }
+  }
+  return out;
+}
+
+function writeAgentsMd(targetRoot, dryRun) {
+  const templatePath = path.join(packageRoot, "src", "AGENTS.md");
+  const targetPath = path.join(targetRoot, "AGENTS.md");
+  const templateMd = fs.readFileSync(templatePath, "utf8");
+  const existingMd = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;
+  const merged = mergeAgentsMd(templateMd, existingMd);
+  if (dryRun) {
+    console.log("[dry-run] Would write AGENTS.md:", targetPath);
+    return merged;
+  }
+  fs.writeFileSync(targetPath, merged, "utf8");
+  console.log("Wrote:", targetPath);
+  return merged;
+}
+
+const DIRS = [
+  "docs/brainstorms",
+  "docs/plans",
+  "docs/solutions",
+  "docs/metrics/daily",
+  "docs/metrics/weekly",
+  "docs/metrics/monthly",
+  "todos",
+];
+
+function ensureDirs(targetRoot, dryRun) {
+  for (const d of DIRS) {
+    const abs = path.join(targetRoot, d);
+    if (dryRun && !fs.existsSync(abs)) console.log("[dry-run] Would create:", d);
+    else if (!fs.existsSync(abs)) {
+      fs.mkdirSync(abs, { recursive: true });
+      console.log("Created:", d);
+    }
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const targetRoot = realpathSafe(args.root);
+
+  if (!fs.existsSync(packageAgents)) {
+    console.error("Error: package agents dir not found:", packageAgents);
+    process.exit(2);
+  }
+
+  const pkgInTarget = path.join(targetRoot, "node_modules", "compound-workflow");
+  if (!fs.existsSync(pkgInTarget) && !args.dryRun) {
+    console.error("Error: compound-workflow not found in project. Run: npm install compound-workflow");
+    process.exit(2);
+  }
+
+  console.log("Target root:", targetRoot);
+  console.log("Package root:", packageRoot);
+
+  writeOpenCodeJson(targetRoot, args.dryRun);
+  writeAgentsMd(targetRoot, args.dryRun);
+  ensureDirs(targetRoot, args.dryRun);
+
+  if (!args.noConfig && !args.dryRun && process.stdin.isTTY) {
+    console.log("\nRepo Config: edit AGENTS.md to set default_branch, test_command, lint_command, dev_server_url.");
+  }
+
+  console.log("\nDone. Run opencode debug config to verify.");
+}
+
+main();

package/scripts/sync-into-repo.sh

@@ -0,0 +1,103 @@
+#!/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."