compound-workflow 0.1.1

package/src/.agents/commands/workflow/review-v2.md

@@ -0,0 +1,148 @@
+---
+name: review-v2
+invocation: workflow:review-v2
+description: Experimental PR/branch review with interactive snippet walkthrough (output-only; no publishing)
+argument-hint: "[PR number, GitHub URL, branch name, or 'current']"
+---
+
+# /workflow:review-v2
+
+Experimental code review flow focused on **interactive, snippet-by-snippet walkthrough** and **collected, consolidated comments**.
+
+Guardrails (unless explicitly requested):
+
+- Do not modify code or documents
+- Do not create commits
+- Do not push branches
+- Do not create pull requests
+- Do not publish GitHub PR reviews (output-only)
+
+## Inputs
+
+- Target: `$ARGUMENTS`
+  - PR number / GitHub URL (if `gh` is available)
+  - branch name
+  - `current` (current branch)
+
+If empty, default to `current`.
+
+## Execution Workflow
+
+### Phase 0: Resolve Repo Defaults (ALWAYS FIRST)
+
+1. Read `AGENTS.md` and locate the "Repo Config Block" YAML.
+2. Resolve:
+   - `default_branch` (fallback: `main`, then `master`)
+   - `lint_command` (optional; only run if configured)
+
+State what you resolved or assumed.
+
+### Phase 1: Determine Target + Checkout Strategy
+
+Parse `$ARGUMENTS` to resolve:
+
+- `target_type`: `pr | branch | current`
+- `base_branch`
+- `head_branch`
+- (if PR) `pr_number`, `pr_title`, `pr_url`
+
+Resolution rules:
+
+- If `$ARGUMENTS` contains `/pull/`: treat as PR URL.
+  - Extract the PR number and run:
+    - `gh pr view <number> --json headRefName,baseRefName,number,title,url`
+- If `$ARGUMENTS` is only digits: treat as PR number.
+  - Run:
+    - `gh pr view <number> --json headRefName,baseRefName,number,title,url`
+- Else if `$ARGUMENTS == "current"` (or empty): review current branch.
+- Else: treat `$ARGUMENTS` as a branch name; `base_branch = default_branch`.
+
+Checkout strategy:
+
+- Prefer reviewing the **currently checked-out** branch.
+- If the user explicitly targeted a PR/branch that differs from current checkout:
+  - Prefer an isolated worktree for review via `skill: git-worktree` (recommended).
+  - If you cannot/should not switch branches, fall back to `gh pr diff <number>` (PR only) plus local diffing where possible.
+
+### Phase 2: Gather the Diff + Surface Area
+
+1. Determine changed files using (in order):
+   - `@{upstream}...HEAD` when upstream exists
+   - `origin/${base_branch}...HEAD`
+   - `HEAD~1..HEAD`
+2. Run:
+   - `git diff origin/${base_branch}...HEAD --stat`
+   - `git diff origin/${base_branch}...HEAD`
+3. If PR and `gh` is available, also run:
+   - `gh pr diff <number>`
+
+Summarize surface area (changed files, hot paths, risk notes).
+
+### Phase 3: Load Local Conventions
+
+1. Read repo root `AGENTS.md` (already done in Phase 0) for workflow defaults and constraints.
+2. Look for `CLAUDE.md` files:
+   - at repo root
+   - in directories containing modified files
+3. Read any found `CLAUDE.md` files and summarize the applicable conventions you will enforce in this review.
+
+### Phase 4: Interactive Snippet-by-Snippet Walkthrough (V2 Core)
+
+Instead of dumping the full review at once, walk the user through the diff **snippet by snippet**.
+
+Rules:
+
+1. Organize snippets by concern (not file order), usually:
+   - foundational types/interfaces/config
+   - shared helpers/modules
+   - core logic changes
+   - integration edges (I/O, DB, network, auth)
+   - tests + docs
+2. Number each snippet (e.g. `Snippet 3/12`) so the user knows progress.
+3. For each snippet, present:
+   - a minimal diff/code block (only the essential lines)
+   - plain-language explanation (what/why)
+   - what’s good
+   - what’s concerning (specific issue → consequence)
+4. After each snippet, STOP and ask for input:
+   - user comment/note → store it as a collected review comment and confirm you noted it
+   - user question → answer, then continue
+   - user says `next` / `move on` → proceed
+
+Collected comment format (maintain internally as you go):
+
+- `path:line` (approx is fine until final consolidation)
+- severity: `Critical | Important | Suggestion | Nitpick`
+- comment: rewrite user notes into clear, actionable language
+
+### Phase 5: Common Review Patterns to Watch For
+
+Pay special attention to:
+
+- Consistency (constants vs hardcodes, patterns across similar files, loose return types like `any[]`)
+- Architecture (duplication, half-wired integrations, silently removed behavior)
+- Naming & types (misleading names, unexplained config values)
+- LLM/agent code (tool success vs orchestrator blocks, missing prompt updates, duplicated context, confusing injected messages)
+- Maintenance (hardcoded registries that should be co-located)
+
+### Phase 6: Consolidate (Output-Only)
+
+After all snippets, present the **full collected comment list**, organized by severity:
+
+1. Critical / Important (must address before merge)
+2. Suggestions (non-blocking improvements)
+3. Nitpicks (minor consistency/style)
+
+For each comment include:
+
+- file + line reference (best-effort)
+- description
+- suggested fix (when applicable)
+
+Then output:
+
+- Summary (1–3 sentences)
+- Verdict: `Ship it | Needs changes | Needs discussion`
+
+Do **not** publish to GitHub in V2. If the user wants publishing later, that is a separate command/experiment.
+

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

@@ -0,0 +1,110 @@
+---
+name: review
+invocation: workflow:review
+description: Review a PR/branch/diff with structured findings. Does not implement fixes unless explicitly requested.
+argument-hint: "[PR number, GitHub URL, branch name, or 'current']"
+---
+
+# /workflow:review
+
+Run a structured, evidence-based **code** review. This command produces findings and recommendations; it does not implement fixes by default.
+
+**If the user provides a document path** (e.g. a plan or spec): redirect to the `technical-review` skill for technical correctness (no edits), and/or the `document-review` skill to refine the document. This command does not review documents.
+
+Guardrails (unless explicitly requested):
+
+- Do not modify code or documents
+- Do not create commits
+- Do not push branches
+- Do not create pull requests
+
+## Inputs
+
+- Target: `$ARGUMENTS`
+  - PR number / GitHub URL (if `gh` is available)
+  - branch name
+  - `current` (current branch)
+
+If empty, default to `current`.
+
+## Execution Workflow
+
+### Phase 0: Resolve Repo Defaults (ALWAYS FIRST)
+
+1. Read `AGENTS.md` and look for the "Repo Config Block" YAML.
+2. Resolve:
+   - `default_branch` (fallback: `main`, then `master`)
+   - `lint_command` (used in Phase 3)
+
+State what you resolved or assumed.
+
+### Phase 1: Determine Target + Checkout Strategy
+
+1. Determine target type from `$ARGUMENTS`: PR/URL, branch name, or `current`.
+2. If reviewing a PR and `gh` is available:
+   - Fetch title/body/files via `gh pr view --json`
+   - Checkout the branch (direct checkout or via worktree)
+3. If target is a branch (not current):
+   - Ensure you are on the correct branch, or offer a worktree via `skill: git-worktree`
+4. If you are not on the target branch and user requested that target, offer a worktree via `skill: git-worktree`.
+
+Prefer reviewing the currently checked-out branch. Only switch branches or create worktrees when the user explicitly requests a different target.
+
+Protected artifacts:
+
+- Never suggest deleting or ignoring `docs/plans/` or `docs/solutions/`.
+
+### Phase 2: Compute Review Surface Area
+
+1. Determine changed files using (in order):
+   - `@{upstream}...HEAD` when upstream exists
+   - `origin/${default_branch}...HEAD`
+   - `HEAD~1..HEAD`
+2. Summarize surface area (which files, high-risk areas).
+3. Infer risk tier for conditional passes:
+   - If the branch/PR references a plan file (e.g. in description or linked in changes), and that plan has `fidelity`/`confidence`, use them to decide review depth (high fidelity or low confidence => more scrutiny, more conditional passes).
+   - Otherwise infer from scope and domain (security/auth/payments/data migration/infra => higher).
+
+### Phase 3: Parallel Passes
+
+**Always run (in parallel when possible):**
+
+- `Task learnings-researcher(<target context>)` (related prior solutions)
+- `Task lint(<changed files context>)` only if `lint_command` is configured in the Repo Config Block
+
+**Conditional passes** (run when they apply):
+
+- If this is a bug report/fix and reproduction steps are available: `Task bug-reproduction-validator(<report>)`
+- If changes touch existing behavior and risk is medium/high: `Task git-history-analyzer(<target context>)`
+- If changes depend on framework/library behavior and version constraints: `Task framework-docs-researcher(<topic>)`
+
+Then perform the main review synthesis across:
+
+- change summary (surface area, high-risk files)
+- correctness
+- tests/verification adequacy
+- risk and failure modes
+- operational considerations (monitoring, rollback)
+- readability/maintainability
+
+### Phase 4: Synthesis + Verdict
+
+Provide:
+
+- Review recommendation: `pass | pass-with-notes | fail`
+- Top risks (1–5 bullets)
+- Findings list:
+  - severity (`critical | high | medium | low`)
+  - evidence (file references or commands/output)
+  - recommended action (concise)
+- What ran vs skipped (selected agents/passes)
+
+### Phase 5: Handoff Options
+
+Recommend next action:
+
+- **Implement fixes:** `/workflow:work` with the relevant plan (or branch) to address findings
+- **Track follow-ups:** use the `file-todos` skill to convert findings into `todos/` items (only if user requests tracked follow-ups)
+- **Capture learning:** if a systemic learning emerged, suggest `/workflow:compound`
+
+Optional: If user requests tracked follow-ups, convert findings into `todos/` items using the `file-todos` skill.

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

@@ -0,0 +1,54 @@
+---
+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)]"
+---
+
+# /workflow:triage
+
+Turn `todos/*-pending-*.md` items into an 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/`
+- Optional: a specific todo file path or issue id
+
+## Preconditions
+
+- `todos/` directory exists (create it if missing)
+- `file-todos` skill is available (template + conventions)
+
+## Workflow
+
+1. Identify the target set:
+   - all `todos/*-pending-*.md`, or
+   - the requested todo
+2. For each pending todo:
+   - read Problem Statement + Findings + Proposed Solutions
+   - fill **Recommended Action** (make it executable)
+   - set `priority` (`p1|p2|p3`)
+   - set `dependencies` (issue_ids)
+   - ensure Acceptance Criteria is testable
+   - add/update tags for searchability
+   - **When multiple todos have `tags: [discussion]`:** (1) List a **concise numbered summary** of the discussion points. (2) Walk through **each point one by one**; for each, discuss and align with the user before approving or deferring; only then move on. Do not resolve all discussion points in one turn.
+   - **If the todo has `tags: [discussion]`:** Recommended Action must state the concrete decision task (what info is needed, who decides, done-when). Approve only when the outcome is a clear, executable decision task; otherwise defer.
+   - **If the todo has `tags: [spike]`:** Recommended Action must include a timebox and deliverable (e.g. "2–4h spike; deliver: options + recommendation + next build todos"). Set `dependencies` so that any build todos that depend on this spike's outcome list this todo's `issue_id`; when approving, ensure dependent build todos remain blocked until the spike is complete (they depend on the spike's `issue_id`). Approve only when the spike scope and deliverable are clear; otherwise defer.
+3. Decision:
+   - **approve now** -> rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready`
+   - **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`.
+4. Output:
+   - list approved `ready` todos (unblocked first)
+   - list remaining pending todos
+   - list deferred todos (parked for reference; not in executable queue)
+   - list blocked todos with missing dependencies
+5. Next step suggestion:
+   - run `/workflow:work <plan-path>` to execute ready items
+
+## Guardrails
+
+- Do not modify code.
+- Do not create commits/push/PRs.
+- Prefer explicit dependencies over implicit ordering.