compound-workflow 1.2.0 → 1.3.1

package/README.md

@@ -48,11 +48,11 @@ To update to a new release, see [Updating compound-workflow](#updating-compound-
 
 ## Workflow at a glance
 
-Clarify what to build → plan how (fidelity + confidence) → execute via todos → triage and review → capture learnings → log and assess.
+Clarify what to build -> plan how (fidelity + confidence) -> triage todos -> execute -> review -> capture learnings -> log and assess.
 
 ```mermaid
 flowchart LR
-  A["brainstorm"] --> B["plan"] --> C["work"] --> D["triage"] --> E["review"] --> F["capture"] --> G["metrics"]
+  A["brainstorm"] --> B["plan"] --> C["triage"] --> D["work"] --> E["review"] --> F["capture"] --> G["metrics"]
 ```
 
 ---
@@ -63,8 +63,8 @@ flowchart LR
 |------|--------|---------|---------------|
 | Clarify what to build | Dialogue only; no code | `/workflow:brainstorm [topic]` | `docs/brainstorms/` |
 | Define how (fidelity + confidence) | Plan only; no code; include agentic access + validation contract | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
-| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
 | Ready the queue | Priority/dependencies + executable agentic contract checks for pending todos | `/workflow:triage` | — |
+| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
 | Validate quality | Evidence-based review + agentic executability checks; 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 |
@@ -77,13 +77,15 @@ flowchart LR
 
 **Intent:** Plan only; no code; fidelity + confidence; include an agentic access + validation contract. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
 
-#### 3. Execute (work)
+#### 3. Ready the queue (triage)
 
-**Intent:** File-based todos; risk-tier testing; success-criteria evidence + quality gates before completion; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
+**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
 
-#### 4. Ready the queue (triage)
+#### 4. Execute (work)
 
-**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
+**Intent:** File-based todos; risk-tier testing; success-criteria evidence + quality gates before completion; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
+
+`/workflow:work` must not run until `/workflow:triage` has approved executable ready todos.
 
 #### 5. Validate quality (review)
 

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.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/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/plan.md

@@ -861,13 +861,15 @@ Examples:
 
 After writing the plan file, use **AskQuestion** to present these options:
 
+Do not route directly from plan generation to `/workflow:work`.
+
 **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. What would you like to do next?"
 
 **Options:**
 
 1. **Open plan in editor** - Open the plan file for review
 2. **Review and refine** - Improve the document through structured self-review
-3. **Start `/workflow:work`** - Begin implementing this plan locally
+3. **Start `/workflow:triage`** - Triage todos derived from this plan before execution
 4. **Create Issue** - Create issue in project tracker (GitHub/Linear)
 5. **Other** - Adjust the plan
 
@@ -880,13 +882,14 @@ Based on selection:
 
 - **Open plan in editor** → Open the plan file in the editor (navigate to `docs/plans/<plan_filename>.md`)
 - **Review and refine** → Load `document-review` skill.
+- **Start `/workflow:triage`** → Ensure plan todos exist (create via `file-todos` if needed), then run `/workflow:triage` to approve priority/dependencies and the executable ready queue.
 - **Technical review** → Load `technical-review` skill; then if user agrees to changes, load `document-review` to update the plan.
 - **Create Issue** → See "Issue Creation" section below
 - **Other** → Accept free text for rework or specific changes
 
 **Note:** Only if `/deepen-plan` exists in this repo and the user has enabled it (e.g., ultrathink), you may run `/deepen-plan` after plan creation for extra depth; it is optional, not required.
 
-Loop back to options after changes until user selects `/workflow:work` or ends the session.
+Loop back to options after changes until user selects `/workflow:triage` or ends the session.
 
 ## Issue Creation
 
@@ -928,6 +931,6 @@ When user selects "Create Issue", detect their project tracker from repo guidanc
 
 5. **After creation:**
    - Display the issue URL
-   - Ask if they want to proceed to `/workflow:work`
+   - Ask if they want to proceed to `/workflow:triage`
 
 NEVER CODE! Just research and write the plan.

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

@@ -1,19 +1,20 @@
 ---
 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.
+Output of this command is the only executable queue for `/workflow:work`.
 
 ## 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 +25,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 +46,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

@@ -91,6 +91,12 @@ The input must be a plan file path.
 
 1.6. **Agentic Access + Validation Preflight (HARD GATE)**
 
+   Contract checksum (MUST all be true before implementation):
+
+   - triage completed for this plan
+   - isolation gate recorded (`worktree_decision`, context, `gate_status: passed`)
+   - blocking spikes execute before dependent build todos
+
    Before any implementation commands:
 
    - Verify each `ready` todo has an executable Agentic Execution Contract:
@@ -221,8 +227,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 +256,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:
 
@@ -43,7 +40,7 @@ Onboarding:
 
 - `/install` -> one action: writes opencode.json, merges AGENTS.md, creates dirs, preserves Repo Config Block (run `npx compound-workflow install` in the project)
 
-This workspace currently implements `brainstorm`, `plan`, `work`, `review`, `compound`, and optional QA utilities.
+This workspace currently implements `brainstorm`, `plan`, `triage`, `work`, `review`, `compound`, and optional QA utilities.
 
 Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, etc.). This template does not ship aliases.
 
@@ -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.
@@ -156,8 +154,8 @@ 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`
+- 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)
+- 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. |