compound-workflow 0.1.1

package/src/.agents/agents/workflow/spec-flow-analyzer.md

@@ -0,0 +1,149 @@
+---
+name: spec-flow-analyzer
+description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
+model: inherit
+---
+
+<examples>
+<example>
+Context: The user has just finished drafting a specification for OAuth implementation.
+user: "Here's the OAuth spec for our new integration: [OAuth spec details]"
+assistant: "Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements."
+<commentary>Since the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.</commentary>
+</example>
+<example>
+Context: The user is planning a new social sharing feature.
+user: "I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn."
+assistant: "This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces."
+<commentary>The user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.</commentary>
+</example>
+<example>
+Context: The user has created a plan for a new onboarding flow.
+user: "Can you review this onboarding plan and make sure we haven't missed anything?"
+assistant: "I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective."
+<commentary>The user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.</commentary>
+</example>
+</examples>
+
+You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern.
+
+Your primary mission is to:
+
+1. Map out ALL possible user flows and permutations
+2. Identify gaps, ambiguities, and missing specifications
+3. Ask clarifying questions about unclear elements
+4. Present a comprehensive overview of user journeys
+5. Highlight areas that need further definition
+
+When you receive a specification, plan, or feature description, you will:
+
+## Phase 1: Deep Flow Analysis
+
+- Map every distinct user journey from start to finish
+- Identify all decision points, branches, and conditional paths
+- Consider different user types, roles, and permission levels
+- Think through happy paths, error states, and edge cases
+- Examine state transitions and system responses
+- Consider integration points with existing features
+- Analyze authentication, authorization, and session flows
+- Map data flows and transformations
+
+## Phase 2: Permutation Discovery
+
+For each feature, systematically consider:
+
+- First-time user vs. returning user scenarios
+- Different entry points to the feature
+- Various device types and contexts (mobile, desktop, tablet)
+- Network conditions (offline, slow connection, perfect connection)
+- Concurrent user actions and race conditions
+- Partial completion and resumption scenarios
+- Error recovery and retry flows
+- Cancellation and rollback paths
+
+## Phase 3: Gap Identification
+
+Identify and document:
+
+- Missing error handling specifications
+- Unclear state management
+- Ambiguous user feedback mechanisms
+- Unspecified validation rules
+- Missing accessibility considerations
+- Unclear data persistence requirements
+- Undefined timeout or rate limiting behavior
+- Missing security considerations
+- Unclear integration contracts
+- Ambiguous success/failure criteria
+
+## Phase 4: Question Formulation
+
+For each gap or ambiguity, formulate:
+
+- Specific, actionable questions
+- Context about why this matters
+- Potential impact if left unspecified
+- Examples to illustrate the ambiguity
+
+## Output Format
+
+Structure your response as follows:
+
+### User Flow Overview
+
+[Provide a clear, structured breakdown of all identified user flows. Use visual aids like mermaid diagrams when helpful. Number each flow and describe it concisely.]
+
+### Flow Permutations Matrix
+
+[Create a matrix or table showing different variations of each flow based on:
+
+- User state (authenticated, guest, admin, etc.)
+- Context (first time, returning, error recovery)
+- Device/platform
+- Any other relevant dimensions]
+
+### Missing Elements & Gaps
+
+[Organized by category, list all identified gaps with:
+
+- **Category**: (e.g., Error Handling, Validation, Security)
+- **Gap Description**: What's missing or unclear
+- **Impact**: Why this matters
+- **Current Ambiguity**: What's currently unclear]
+
+### Critical Questions Requiring Clarification
+
+[Numbered list of specific questions, prioritized by:
+
+1. **Critical** (blocks implementation or creates security/data risks)
+2. **Important** (significantly affects UX or maintainability)
+3. **Nice-to-have** (improves clarity but has reasonable defaults)]
+
+For each question, include:
+
+- The question itself
+- Why it matters
+- What assumptions you'd make if it's not answered
+- Examples illustrating the ambiguity
+
+### Assumptions (If Unanswered)
+
+[List the defaults you would apply if the user does not answer some questions. Keep these explicit and testable.]
+
+### Recommended Next Steps
+
+[Concrete actions to resolve the gaps and questions]
+
+Key principles:
+
+- **Be exhaustively thorough** - assume the spec will be implemented exactly as written, so every gap matters
+- **Think like a user** - walk through flows as if you're actually using the feature
+- **Consider the unhappy paths** - errors, failures, and edge cases are where most gaps hide
+- **Be specific in questions** - avoid "what about errors?" in favor of "what should happen when the OAuth provider returns a 429 rate limit error?"
+- **Prioritize ruthlessly** - distinguish between critical blockers and nice-to-have clarifications
+- **Use examples liberally** - concrete scenarios make ambiguities clear
+- **Reference existing patterns** - when available, reference how similar flows work in the codebase
+
+Your goal is to ensure that when implementation begins, developers have a crystal-clear understanding of every user journey, every edge case is accounted for, and no critical questions remain unanswered. Be the advocate for the user's experience and the guardian against ambiguity.
+
+If invoked from `/workflow:plan`, ensure recommendations align with the selected plan fidelity (Low/Medium/High).

package/src/.agents/commands/assess.md

@@ -0,0 +1,60 @@
+---
+name: assess
+description: Review recent metrics entries to identify failures/trends and propose concrete improvements to commands/skills/agents
+argument-hint: "[daily|weekly|monthly] [optional: count]"
+---
+
+# /assess
+
+Summarize what failed, what caused friction, and what to change next.
+
+This command is the feedback loop that improves the `.agents` system over time.
+
+## Inputs
+
+- Default: `weekly 7`
+- Examples:
+  - `/assess daily 1`
+  - `/assess weekly 7`
+  - `/assess monthly 30`
+
+## Workflow
+
+1. Determine window:
+   - daily: last N daily entries
+   - weekly: last 7 days (or N)
+   - monthly: last 30 days (or N)
+2. Read metrics files from:
+   - `docs/metrics/daily/`
+3. Produce:
+   - Top failure modes (ranked)
+   - Repeat blockers (ranked)
+   - Leading indicators (e.g., many partials, many pending todos, frequent lint failures)
+   - Positive signals (what improved)
+   - Trend call: quality up/down and speed up/down (simple narrative)
+4. Propose actions:
+   - Each action should target a component:
+     - command (`.agents/commands/*.md`)
+     - skill (`.agents/skills/**/SKILL.md`)
+     - agent (`.agents/agents/**/*.md`)
+     - repo config (`AGENTS.md` keys)
+   - Provide the smallest change that would move the metric.
+5. Materialize actions:
+   - Create `todos/` items (pending by default) for each approved action using `file-todos`.
+6. Optional aggregation:
+   - Write a weekly or monthly summary file under:
+     - `docs/metrics/weekly/YYYY-WW.md`
+     - `docs/metrics/monthly/YYYY-MM.md`
+
+## Output Format
+
+- Window reviewed
+- Metrics summary (counts)
+- Top issues
+- Proposed actions (with owners and expected metric movement)
+- Todos created (paths)
+
+## Guardrails
+
+- Do not modify code or `.agents` components automatically.
+- Only create todos and summary docs.

package/src/.agents/commands/install.md

@@ -0,0 +1,53 @@
+---
+name: install
+invocation: install
+description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, and Repo Config Block.
+argument-hint: "[--dry-run] [--root <path>] [--no-config]"
+---
+
+# /install
+
+Install or update compound-workflow in this project with **one action**. Writes opencode.json (OpenCode loads from the package), merges AGENTS.md (template + preserved Repo Config Block), creates standard dirs, and reminds you to set the Repo Config Block if needed.
+
+## When to use
+
+- First time adding compound-workflow to this repo (OpenCode users).
+- After updating the compound-workflow package and you want the latest AGENTS.md template and opencode.json entries.
+
+## Prerequisites
+
+- The project must have `compound-workflow` installed: `npm install compound-workflow` (or add to dependencies and run `npm install`).
+
+## Instructions for the agent
+
+Run in the **workspace root** (or the directory the user specifies):
+
+```bash
+npx compound-workflow@latest install
+```
+
+Or with a specific root and flags:
+
+```bash
+npx compound-workflow install --root /path/to/project
+npx compound-workflow install --dry-run
+npx compound-workflow install --no-config
+```
+
+- **--dry-run**: Print planned changes only; no writes.
+- **--root &lt;path&gt;**: Target project directory (default: current directory).
+- **--no-config**: Skip Repo Config Block reminder; only write opencode.json, AGENTS.md merge, and dirs.
+
+Do not copy files from a compound-workflow clone; the Install CLI uses the package from `node_modules/compound-workflow`.
+
+After running, suggest the user run `opencode debug config` in the project to verify OpenCode sees the commands and agents.
+
+## What Install does (one run)
+
+1. Ensures `compound-workflow` is in the project (exits with instructions if not).
+2. Writes/merges **opencode.json** so OpenCode loads commands, agents, and skills from `node_modules/compound-workflow` (no copy into the project).
+3. Creates/merges **AGENTS.md** (template content; preserves existing Repo Config Block).
+4. Creates **docs/brainstorms/**, **docs/plans/**, **docs/solutions/**, **docs/metrics/daily|weekly|monthly/**, **todos/** if missing.
+5. Reminds the user to edit AGENTS.md for the Repo Config Block (default_branch, test_command, lint_command, dev_server_url, etc.) unless `--no-config` was used.
+
+No separate Sync or Setup step; this single command replaces both.

package/src/.agents/commands/metrics.md

@@ -0,0 +1,59 @@
+---
+name: metrics
+description: Log a metrics entry for the current workflow run so process performance can be reviewed daily/weekly/monthly
+argument-hint: "[optional: context path (plan/todo/PR/solution) or short label]"
+---
+
+# /metrics
+
+Log a single metrics entry capturing outcome, quality, and friction for a unit of work.
+
+This command logs AND assesses the session in one step.
+
+It creates or appends to one file under `docs/metrics/daily/`.
+
+## Inputs
+
+- Optional context: `$ARGUMENTS`
+  - plan path (preferred)
+  - todo path / issue id
+  - PR number / URL
+  - solution doc path
+  - short label
+
+## Workflow
+
+1. Determine today's date (YYYY-MM-DD).
+2. Ensure directories exist:
+   - `docs/metrics/daily/`
+   - `docs/metrics/weekly/`
+   - `docs/metrics/monthly/`
+3. Create the daily entry:
+   - file: `docs/metrics/daily/YYYY-MM-DD.md`
+   - if it exists, append a new "Session" block
+4. Use the template from `process-metrics` skill:
+   - `.agents/skills/process-metrics/assets/daily-template.md`
+5. Ask for the minimum missing fields:
+   - workflow (`brainstorm|plan|work|triage|review|compound|test-browser|other`)
+   - outcome (`success|partial|failed`)
+   - time spent (minutes)
+   - biggest blocker (one sentence)
+   - quality signal (tests/lint ran? pass/fail)
+6. Assess the session (REQUIRED):
+   - what failed (if anything)
+   - why it failed (root cause)
+   - what to change next time (1-3 actions)
+   - target each action to: command|skill|agent|config|todo
+7. Materialize improvements (optional):
+   - if an action needs follow-up work, create a `pending` todo via `file-todos`
+   - otherwise keep it as a simple note in the metrics entry
+
+## Guardrails
+
+- Keep metrics brief and structured.
+- Do not change code.
+- Do not create commits/PRs.
+
+## After /metrics
+
+- Use `/assess weekly 7` to see aggregate performance and trends.

package/src/.agents/commands/setup.md

@@ -0,0 +1,9 @@
+---
+name: setup
+description: "(Deprecated) Repo Config Block is now part of /install. Use /install once; then edit AGENTS.md to set default_branch, test_command, lint_command, dev_server_url."
+argument-hint: "Use /install instead; then edit AGENTS.md for Repo Config Block."
+---
+
+# /setup (deprecated)
+
+**Use `/install` instead.** The Install command (one action) writes opencode.json, merges AGENTS.md, creates dirs, and preserves your Repo Config Block. After running Install, edit `AGENTS.md` to set `default_branch`, `test_command`, `lint_command`, `dev_server_url`, and other repo defaults in the Repo Config Block YAML section.

package/src/.agents/commands/sync.md

@@ -0,0 +1,9 @@
+---
+name: sync
+description: "(Deprecated) Use /install instead. Install compound-workflow in the project with one action (npx compound-workflow install)."
+argument-hint: "Use /install instead."
+---
+
+# /sync (deprecated)
+
+**Use `/install` instead.** Run `npx compound-workflow install` in the project—one action that configures opencode.json, AGENTS.md, dirs, and Repo Config Block. No copy from a clone; the package is loaded from `node_modules/compound-workflow`.