compound-workflow 1.2.0 → 1.3.0

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"1.2.0","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"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{"name":"compound-workflow","version":"1.3.0","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"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}

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

@@ -1,19 +1,19 @@
 ---
 name: triage
 invocation: workflow:triage
-description: Triage pending todo files into an executable ready queue (priority, dependencies, recommended action)
-argument-hint: "[optional: todo path, issue id, or 'pending' (default)]"
+description: Triage and prioritize todo files into an executable ready queue (priority, dependencies, recommended action)
+argument-hint: "[optional: todo path, issue id, status filter ('pending'|'ready'|'active')]"
 ---
 
 # /workflow:triage
 
-Turn `todos/*-pending-*.md` items into an executable queue.
+Turn todo items into a prioritized executable queue.
 
 This command does not implement fixes. It approves and organizes work so `/workflow:work` can execute without ambiguity.
 
 ## Inputs
 
-- Default: triage all pending todos under `todos/`
+- Default: triage all active todos under `todos/` (`pending` + `ready`)
 - Optional: a specific todo file path or issue id
 
 ## Preconditions
@@ -24,9 +24,9 @@ This command does not implement fixes. It approves and organizes work so `/workf
 ## Workflow
 
 1. Identify the target set:
-   - all `todos/*-pending-*.md`, or
+   - all active todos (`todos/*-pending-*.md` + `todos/*-ready-*.md`), or
    - the requested todo
-2. For each pending todo:
+2. For each target todo:
    - read Problem Statement + Findings + Proposed Solutions
    - fill **Recommended Action** (make it executable)
    - set `priority` (`p1|p2|p3`)
@@ -45,8 +45,9 @@ This command does not implement fixes. It approves and organizes work so `/workf
    - **Blocking spikes first:** If a spike unblocks downstream build todos, prioritize approving that spike before its dependents. Do not approve dependent build todos as executable ahead of unresolved blocking spikes.
    - **Parallel spike readiness:** If multiple spike todos are independent (no dependency edges between them), they may be approved together for parallel execution.
 3. Decision:
-   - **approve now** -> rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready` (only when Acceptance Criteria and Agentic Execution Contract are executable)
-   - **defer** -> rename `*-pending-*` -> `*-deferred-*` and set frontmatter `status: deferred` (keep priority, typically `p3`). Ensure Recommended Action, Findings, and Work Log have enough context for future reference. Deferred items are not executed until re-triaged to `ready`.
+   - **approve now** -> if pending, rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready`; if already ready, keep `status: ready` and update priority/dependencies as needed
+   - **defer** -> rename `*-pending-*` or `*-ready-*` -> `*-deferred-*` and set frontmatter `status: deferred` (keep priority, typically `p3`). Ensure Recommended Action, Findings, and Work Log have enough context for future reference. Deferred items are not executed until re-triaged to `ready`.
+   - **needs rework** -> when a `ready` todo is not executable, rename `*-ready-*` -> `*-pending-*`, set `status: pending`, and record what is missing before re-approval.
    - **blocked follow-up** -> when work returns a blocked todo, keep it as `pending` (rename from `*-ready-*` when needed), add `tags: [blocker]`, and require blocker options + recommendation in Work Log before re-approval.
 4. Output:
    - list approved `ready` todos (blocking spikes first, then other unblocked items)

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

@@ -221,8 +221,9 @@ The input must be a plan file path.
 
    After creating todos:
 
-   - If any todos are `pending`, stop and offer `/workflow:triage` to approve and prioritize before execution.
-   - If all todos are `ready`, proceed to Phase 2.
+   - Run `/workflow:triage` before any implementation work to approve/prioritize the queue for this plan.
+   - Do not proceed to Phase 2 until triage completes and execution order is explicit.
+   - If triage leaves no unblocked `ready` todos, stop and report pending/deferred/blocked items.
 
 ### Phase 2: Execute
 
@@ -249,7 +250,7 @@ The input must be a plan file path.
 
    - If no unblocked `ready` todos remain:
      - summarize remaining `pending`, `deferred` (parked for reference), and blocked items
-     - recommend running `/workflow:triage` for pending items
+     - require re-running `/workflow:triage` for pending/blocked prioritization
      - stop (do not invent work)
 
    For each task in priority order:

package/src/.agents/skills/capture-skill/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: capture-skill
+description: Capture learnings, patterns, or workflows from the current conversation into a new or existing skill. Use when the user wants to save what was learned, discovered, or built during a conversation as a reusable skill for future sessions.
+---
+
+# Capture Skill from Conversation
+
+This skill extracts reusable knowledge from the current conversation and stores it as a skill.
+
+## Default Policy
+
+`capture-skill` uses an overlay model by default:
+
+- Treat existing repo-provided skills as immutable unless the user explicitly asks to edit a specific one.
+- Store project-specific refinements in a project overlay skill (for example, `.agents/skills/project-standards/`).
+- Only modify an existing skill when the user clearly says to do so (for example, "update skill X").
+- Promote overlay content into base skills only as an explicit, deliberate follow-up action.
+
+## When to Use
+
+- The user says "capture this as a skill" or "save this for next time"
+- A reusable workflow, pattern, or piece of domain knowledge emerged
+- The user wants to refine project standards based on this conversation
+- The conversation revealed non-obvious steps, gotchas, or best practices worth preserving
+
+## Capture Process
+
+### Phase 1: Identify What to Capture
+
+Prioritize broad, reusable patterns over one-off implementation details.
+
+Look for:
+
+1. High-level principles and standards
+2. Multi-step workflows discovered through trial and error
+3. Domain constraints that are not obvious
+4. Gotchas and reliable fixes
+5. Decision rationale that establishes a repeatable rule
+
+Summarize the planned capture and confirm with the user before writing.
+
+### Phase 2: Check Related Skills and Consolidate
+
+Before creating a new skill:
+
+1. List existing skills in personal and project locations.
+2. Find related skill scopes.
+3. Decide: consolidate into existing skill, extend an existing skill section, or create a new skill.
+
+Consolidate when content overlaps domain, trigger conditions, or workflow usage.
+
+### Phase 3: Choose Destination
+
+If not already specified:
+
+1. Decide whether this is a new skill or an update.
+2. For new captures, decide storage:
+   - Personal skill directory for cross-project behavior
+   - Project skill directory for project-specific behavior
+3. Apply the default policy:
+   - Prefer project overlay skills for refinements
+   - Do not mutate repo-provided skills by default
+
+### Phase 4: Draft Skill Content
+
+For new skills:
+
+1. Use a descriptive kebab-case name (max 64 chars)
+2. Write a precise description with WHAT + WHEN
+3. Distill into actionable instructions
+4. Add compact examples
+5. Include scripts/assets only when needed
+
+For updates:
+
+1. Read existing `SKILL.md`
+2. Integrate into the best section
+3. Avoid duplication
+4. Keep structure and voice consistent
+
+### Phase 5: Distill for Reuse
+
+Guidelines:
+
+1. Lead with general principles
+2. Generalize from specific files/functions
+3. Explain why the pattern exists
+4. Include only context the agent would not infer
+5. Keep content concise and maintainable (`SKILL.md` under 500 lines)
+
+Do not:
+
+- Store conversation artifacts
+- Overfit to single-file fixes
+- Repeat obvious model knowledge
+- Include excessive implementation trivia
+
+### Phase 6: Write and Verify
+
+If consolidating:
+
+1. Merge into the chosen home skill
+2. Keep sections clear and non-overlapping
+3. Remove obsolete duplicate skills
+4. Update name/description if scope broadened
+
+If creating/updating:
+
+1. Write `SKILL.md`
+2. Verify trigger description accuracy
+3. Verify no duplicate scope across skills
+4. Confirm captured content with the user
+
+## Consolidation Rules
+
+- Prefer fewer, broader, discoverable skills over many narrow duplicates.
+- Group frequently co-used patterns into one skill with clear sections.
+- If overlap is discovered after creation, consolidate immediately.
+
+## Edge Cases
+
+- Multiple unrelated learnings: split into separate skills.
+- Tiny single-rule capture: recommend a rule file instead of a skill.
+- Major rewrite needed: ask whether to restructure or supersede.
+- User asks to evolve standards safely: keep changes in project overlay unless explicit promotion is requested.

package/src/AGENTS.md

@@ -26,13 +26,10 @@ This `.agents` workspace is portable and command-first.
 
 1. `/workflow:brainstorm` -> clarify what to build
 2. `/workflow:plan` -> define how to build it
-3. `/workflow:work` -> implement
-4. `/workflow:review` -> validate quality
-5. `/workflow:compound` -> capture durable learnings
-
-Supporting command:
-
-- `/workflow:triage` -> approve and prioritize pending todos
+3. `/workflow:triage` -> approve and prioritize the todo queue before execution
+4. `/workflow:work` -> implement
+5. `/workflow:review` -> validate quality
+6. `/workflow:compound` -> capture durable learnings
 
 Continuous improvement:
 
@@ -56,6 +53,7 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 - **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus explicit completion expectation and non-goals so `/workflow:work` can enforce intent.
 - **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
 - **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands. `/workflow:review` must do the same for non-current PR/branch targets before analysis.
+- **Triage before execution is mandatory.** `/workflow:work` must not execute todos until a `/workflow:triage` pass has prioritized the queue and validated dependencies/ready state for the current plan.
 - **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
 - **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
 - **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
@@ -157,7 +155,7 @@ worktree_bootstrap_notes:
 ## Implemented Components (Current Scope)
 
 - Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:work`, `workflow:triage`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
-- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `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`
+- 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`
   - `learnings-researcher`
@@ -213,6 +211,7 @@ Maintenance:
 | `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` (alias: `compound_doc`) | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
+| `capture-skill` | You want to capture conversation learnings as a reusable skill, while defaulting to project-overlay refinement and avoiding implicit edits to repo-provided base skills. |
 | `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. |