compound-workflow 0.1.1 → 0.1.3

package/.cursor-plugin/plugin.json

@@ -1,12 +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" },
-  "skills": "src/.agents/skills",
-  "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/your-org/compound-workflow"},"agents":"src/.agents/agents","commands":"src/.agents/commands"}

package/README.md

@@ -143,6 +143,12 @@ 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.
+
+---
+
 ## 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.

package/package.json

@@ -1,22 +1 @@
-{
-  "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"
-  }
-}
+{"name":"compound-workflow","version":"0.1.3","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"}}

package/scripts/install-cli.mjs

@@ -175,6 +175,39 @@ function readJsonMaybe(fileAbs) {
   return JSON.parse(stripJsonc(raw));
 }
 
+const SKILLS_SYMLINK_PATH = ".agents/compound-workflow-skills";
+
+function ensureSkillsSymlink(targetRoot, dryRun) {
+  const agentsDir = path.join(targetRoot, ".agents");
+  const linkPath = path.join(agentsDir, "compound-workflow-skills");
+  const targetRel = path.join("..", "node_modules", "compound-workflow", "src", ".agents", "skills");
+
+  if (dryRun) {
+    console.log("[dry-run] Would create", SKILLS_SYMLINK_PATH, "symlink");
+    return;
+  }
+
+  if (!fs.existsSync(agentsDir)) fs.mkdirSync(agentsDir, { 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", SKILLS_SYMLINK_PATH, "-> package skills");
+  }
+}
+
 function writeOpenCodeJson(targetRoot, dryRun) {
   const opencodeAbs = path.join(targetRoot, "opencode.json");
   const existing = readJsonMaybe(opencodeAbs) ?? {};
@@ -182,9 +215,8 @@ function writeOpenCodeJson(targetRoot, dryRun) {
 
   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);
+  if (!next.skills.paths.includes(SKILLS_SYMLINK_PATH)) next.skills.paths.unshift(SKILLS_SYMLINK_PATH);
   next.command = ensureObject(next.command);
   next.agent = ensureObject(next.agent);
 
@@ -300,6 +332,7 @@ function main() {
   console.log("Package root:", packageRoot);
 
   writeOpenCodeJson(targetRoot, args.dryRun);
+  ensureSkillsSymlink(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. |