compound-workflow 0.1.2 → 0.1.4

package/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
   "author": { "name": "Compound Workflow" },
   "keywords": ["workflow", "planning", "agents", "skills", "commands"],
   "license": "MIT",
-  "repository": "https://github.com/your-org/compound-workflow",
+  "repository": "https://github.com/cjerochim/compound-workflow",
   "commands": "./src/.agents/commands",
   "agents": "./src/.agents/agents",
   "skills": "./src/.agents/skills"

package/.cursor-plugin/plugin.json

@@ -1 +1 @@
-{"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"},"agents":"src/.agents/agents","commands":"src/.agents/commands"}
+{"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/cjerochim/compound-workflow"},"agents":"src/.agents/agents","commands":"src/.agents/commands"}

package/README.md

@@ -8,24 +8,28 @@ It reduces delivery failures from **unclear intent**, **weak verification**, and
 
 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.
+Runtime assets live in `src/.agents/` and `src/AGENTS.md`. Supports **Cursor**, **Claude**, and **OpenCode** via one Install action per project.
 
 ---
 
 ## Get started
 
-**One action:** In your project (with compound-workflow as a dependency), run **Install**—either the `/install` command in Cursor/Claude or:
+**1. Add the package and run Install** (in the project where you want the workflow):
 
 ```bash
 npm install compound-workflow
 npx compound-workflow install
 ```
 
-Optional: `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder).
+**2. Choose how you use it:**
 
-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:** If your project already has a `.cursor` directory, Install will create a symlink at `.cursor/skills/compound-workflow` so Cursor discovers the workflow skills. No plugin needed for skills. For full commands and agents, use the plugin from this repo (see repo docs for loading a local plugin).
+- **OpenCode:** Install writes `opencode.json` and a symlink at `.agents/compound-workflow-skills`; OpenCode loads from the package. Run `/install` or `npx compound-workflow install` in the project.
+- **Claude:** Add the compound-workflow plugin from this repo. In any repo, run `/install` or the CLI above.
 
-**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.
+**What Install does:** Merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs (`docs/`, `todos/`), writes `opencode.json` (for OpenCode), and—if the project has a `.cursor` directory—creates a symlink at `.cursor/skills/compound-workflow` so Cursor picks up skills. All paths reference `node_modules/compound-workflow`; no file copying.
+
+**CLI options:** `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder).
 
 **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.
 
@@ -35,8 +39,10 @@ To update to a new release, see [Updating compound-workflow](#updating-compound-
 
 ## 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.
+- **Cursor (plugin):** If you load the plugin from this repo, pull latest and reload the plugin in Cursor.
+- **Cursor (npm + .cursor):** Run `npm update compound-workflow`, then run **Install** again (`npx compound-workflow install`) to refresh the `.cursor/skills/compound-workflow` symlink and AGENTS.md.
+- **OpenCode / npm:** Run `npm update compound-workflow` (or bump the version in `package.json` and `npm install`), then run **Install** again. This refreshes `opencode.json`, merges the latest `AGENTS.md` template, and ensures dirs exist; Repo Config Block is preserved.
+- **Claude (plugin):** Update via the editor’s plugin; if from repo, pull latest and reload.
 
 ---
 
@@ -97,7 +103,7 @@ flowchart LR
 
 ## 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).
+**Onboarding:** `/install` — one action: merges AGENTS.md, creates dirs, preserves Repo Config Block; writes opencode.json (OpenCode) and, if present, symlinks into `.cursor/skills/` (Cursor). 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.
 
@@ -145,7 +151,9 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 ## Troubleshooting
 
-**Skills not showing?** Cursor discovers skills from the default `skills/` directory at the plugin root. OpenCode discovers them via the `.agents/compound-workflow-skills` symlink that Install creates (and `opencode.json` `skills.paths`). Run Install from the project root (`npx compound-workflow install`). If skills still don’t appear, check your Cursor/OpenCode version and any `permission.skill` settings that might hide or deny them.
+**Skills not showing in Cursor?** Cursor discovers skills from (1) the plugin’s `skills/` directory when you load the plugin from this repo, or (2) the project’s `.cursor/skills/` when you use npm: ensure the project has a `.cursor` directory and run `npx compound-workflow install`—Install creates a symlink at `.cursor/skills/compound-workflow`. If skills still don’t appear, check Cursor Settings → Rules and any `permission.skill` settings.
+
+**Skills not showing in OpenCode?** OpenCode uses the `.agents/compound-workflow-skills` symlink and `opencode.json` `skills.paths`. Run Install from the project root (`npx compound-workflow install`).
 
 ---
 

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"0.1.2","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","skills"],"engines":{"node":">=18"}}
+{"name":"compound-workflow","version":"0.1.4","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"engines":{"node":">=18"}}

package/scripts/install-cli.mjs

@@ -208,6 +208,42 @@ function ensureSkillsSymlink(targetRoot, dryRun) {
   }
 }
 
+const CURSOR_SKILLS_LINK = ".cursor/skills/compound-workflow";
+
+function ensureCursorSkills(targetRoot, dryRun) {
+  const cursorDir = path.join(targetRoot, ".cursor");
+  if (!fs.existsSync(cursorDir)) return;
+
+  const skillsDir = path.join(cursorDir, "skills");
+  const linkPath = path.join(skillsDir, "compound-workflow");
+  const targetRel = path.join("..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills");
+
+  if (dryRun) {
+    console.log("[dry-run] Would create", CURSOR_SKILLS_LINK, "symlink (Cursor detected)");
+    return;
+  }
+
+  if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
+
+  let needCreate = true;
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) {
+      fs.realpathSync(linkPath);
+      needCreate = false;
+    }
+  } catch (_) {}
+
+  if (needCreate) {
+    try {
+      fs.unlinkSync(linkPath);
+    } catch (_) {}
+    const type = process.platform === "win32" ? "dir" : "dir";
+    fs.symlinkSync(targetRel, linkPath, type);
+    console.log("Created", CURSOR_SKILLS_LINK, "-> package skills (Cursor)");
+  }
+}
+
 function writeOpenCodeJson(targetRoot, dryRun) {
   const opencodeAbs = path.join(targetRoot, "opencode.json");
   const existing = readJsonMaybe(opencodeAbs) ?? {};
@@ -333,6 +369,7 @@ function main() {
 
   writeOpenCodeJson(targetRoot, args.dryRun);
   ensureSkillsSymlink(targetRoot, args.dryRun);
+  ensureCursorSkills(targetRoot, args.dryRun);
   writeAgentsMd(targetRoot, args.dryRun);
   ensureDirs(targetRoot, args.dryRun);
 

package/src/.agents/commands/workflow/compound.md

@@ -1,13 +1,13 @@
 ---
 name: compound
 invocation: workflow:compound
-description: Document a recently solved problem into docs/solutions/ to compound institutional knowledge
-argument-hint: "[optional: brief context about the fix]"
+description: Document a durable learning (solved problem or implementation insight) into docs/solutions/ to compound institutional knowledge
+argument-hint: "[optional: brief context about the fix or insight]"
 ---
 
 # /workflow:compound
 
-Capture a solved problem while context is fresh.
+Capture a durable learning (solved problem or implementation insight) while context is fresh.
 
 ## Purpose
 
@@ -45,7 +45,8 @@ After the primary solution doc is written, optional post-capture actions (by exp
 
 ### 1. Preconditions (required)
 
-- Confirm the problem is solved, verified working, and non-trivial.
+- **Solved problem:** Confirm the problem is solved, verified working, and non-trivial.
+- **Implementation insight:** For feature work, confirm implementation is complete and there is a reusable learning or pattern to capture (no "problem solved" requirement for this path).
 - If critical context is missing, ask targeted questions and wait. Then **invoke the `compound-docs` skill** (it defines required fields, validation gates, and template).
 
 ### 2. Optional enrichment (before write)
@@ -68,23 +69,24 @@ User may optionally run `document-review` on the created doc. If the repo has do
 ## Preconditions
 
 <preconditions enforcement="advisory">
-  <check condition="problem_solved">
-    Problem has been solved (not in-progress)
+  <check condition="problem_solved_or_insight">
+    For solved problems: problem has been solved (not in-progress). For implementation insights: implementation complete and there is a reusable learning to capture.
   </check>
   <check condition="solution_verified">
-    Solution has been verified working
+    Solution or approach has been verified working (or for insights: pattern is clear and reusable)
   </check>
   <check condition="non_trivial">
-    Non-trivial problem (not simple typo or obvious error)
+    Non-trivial (not simple typo or obvious error; for insights: worth documenting for future reuse)
   </check>
 </preconditions>
 
 ## What It Captures
 
-- **Problem symptom**: Exact error messages, observable behavior
+- **Problem symptom** (solved problems): Exact error messages, observable behavior
 - **Investigation steps tried**: What didn't work and why
 - **Root cause analysis**: Technical explanation
 - **Working solution**: Step-by-step fix with code examples
+- **Implementation insights**: Patterns, gotchas, or reusable approaches from feature work (e.g. framework usage, redirect patterns)
 - **Prevention strategies**: How to avoid in future
 - **Cross-references**: Links to related issues and docs
 

package/src/.agents/skills/compound-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compound-docs
-description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
+description: Capture solved problems and implementation insights as categorized documentation with YAML frontmatter for fast lookup
 disable-model-invocation: true
 allowed-tools:
   - Read # Parse conversation context
@@ -8,17 +8,17 @@ allowed-tools:
   - Bash # Create directories
   - Grep # Search existing docs
 preconditions:
-  - Problem has been solved (not in-progress)
-  - Solution has been verified working
+  - For solved problems: problem has been solved (not in-progress). For implementation insights: implementation complete and there is a reusable learning to capture.
+  - Solution or approach has been verified working (or for insights: pattern is clear and reusable)
 ---
 
 # compound-docs Skill
 
-**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
+**Purpose:** Document solved problems and implementation insights (learnings from feature work) to build searchable institutional knowledge with category-based organization (enum-validated problem types).
 
 ## Overview
 
-This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions.
+This skill captures durable learnings in two equally valid forms: (1) problem solutions (bugs, investigations, spike outcomes) and (2) implementation insights (patterns, gotchas, or reusable approaches from feature work). Both produce one structured solution doc per capture.
 
 **Organization:** Primary capture writes one solution doc per problem in its symptom category directory (e.g., `docs/solutions/performance-issues/2026-02-19-email-processing-n-plus-one-in-brief-generation.md`). Files use YAML frontmatter for metadata and searchability.
 
@@ -41,20 +41,19 @@ Post-capture actions (by explicit user choice) may update other references (e.g.
 - "problem solved"
 - "that did it"
 
-**OR manual:** `/workflow:compound` command
+**OR manual:** `/workflow:compound` command (valid after feature work when there is a reusable pattern or learning to document)
 
-**Non-trivial problems only:**
+**Non-trivial only:**
 
-- Multiple investigation attempts needed
-- Tricky debugging that took time
-- Non-obvious solution
-- Future sessions would benefit
+- **Solved problems:** Multiple investigation attempts needed; tricky debugging; non-obvious solution; future sessions would benefit
+- **Implementation insights:** Pattern or learning from feature work worth reusing (e.g. framework usage, redirect guards)
 
 **Skip documentation for:**
 
 - Simple typos
 - Obvious syntax errors
 - Trivial fixes immediately corrected
+- Only when there is nothing non-trivial to document (do not skip solely because the work was a "planned feature" rather than a bug fix)
 </step>
 
 <step number="2" required="true" depends_on="1">
@@ -64,12 +63,12 @@ Extract from conversation history:
 
 **Required information:**
 
-- **Module name**: Which module or component had the problem
-- **Symptom**: Observable error/behavior (exact error messages)
-- **Investigation attempts**: What didn't work and why
-- **Root cause**: Technical explanation of actual problem
-- **Solution**: What fixed it (code/config changes)
-- **Prevention**: How to avoid in future
+- **Module name**: Which module or component (or feature area for insights)
+- **Symptom** (solved problems): Observable error/behavior (exact error messages). **For implementation insights:** treat as "what we needed to achieve" or "what we learned" (context).
+- **Investigation attempts**: What didn't work and why (optional for implementation insights)
+- **Root cause**: Technical explanation (or for insights: why this approach/pattern applies)
+- **Solution**: What fixed it (code/config changes); **for insights:** approach/pattern and when to reuse
+- **Prevention**: How to avoid in future (or for insights: when to apply this pattern)
 
 **Environment details (as applicable):**
 

package/src/.agents/skills/compound-docs/assets/resolution-template.md

@@ -16,6 +16,8 @@ severity: [critical|high|medium|low]
 tags: [keyword1, keyword2, keyword3]  # include "spike" when this doc originated from a spike
 ---
 
+<!-- For implementation insights (feature learnings): treat "Symptoms" as "What we needed / context", "What Didn't Work" as optional (use "Direct solution" or omit), and "Solution" as the pattern/approach and when to reuse. -->
+
 # Troubleshooting: [Clear Problem Title]
 
 ## Problem
@@ -33,7 +35,7 @@ tags: [keyword1, keyword2, keyword3]  # include "spike" when this doc originated
 - [Observable symptom 2 - error messages, visual issues, unexpected behavior]
 - [Continue as needed - be specific]
 
-## What Didn't Work
+## What Didn't Work (optional for implementation insights)
 
 **Attempted Solution 1:** [Description of what was tried]
 - **Why it failed:** [Technical reason this didn't solve the problem]

package/src/.agents/skills/compound-docs/references/yaml-schema.md

@@ -8,7 +8,7 @@ If present, `.agents/skills/compound-docs/schema.project.yaml` acts as an option
 
 - **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
 - **date** (string): ISO 8601 date (YYYY-MM-DD)
-- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
+- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]. Use `best_practice`, `developer_experience`, or `workflow_issue` for implementation insights (patterns from feature work).
 - **component** (string): Free text. Prefer stable slugs like [backend, frontend, database, infra, ci, auth, api, docs, tooling]
 - **symptoms** (array): 1-5 specific observable symptoms
 - **root_cause** (string): Free text. Describe the actual cause (not a symptom). Prefer stable slugs when possible.

package/src/AGENTS.md

@@ -197,7 +197,7 @@ Maintenance:
 | `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` | A non-trivial problem is solved and should be captured as durable institutional knowledge. |
+| `compound-docs` | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
 | `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. |