@phuc1403/musketeer 0.8.0 → 0.10.0

package/template/.claude/skills/code-review/references/edge-case-scouting.md

@@ -0,0 +1,119 @@
+---
+name: edge-case-scouting
+description: Use after implementation, before code review to proactively find edge cases, side effects, and potential issues via scout skill - catches problems code-reviewer might miss
+---
+
+# Edge Case Scouting
+
+Proactive detection of edge cases, side effects, and potential issues before code review.
+
+## Purpose
+
+Code reviews catch obvious issues but miss subtle side effects. Scout detects:
+- Files affected by changes reviewer might not check
+- Data flow paths that could break
+- Boundary conditions and error paths
+- Integration issues across modules
+
+## When to Use
+
+**Mandatory:** Multi-file features, shared utility refactors, complex bug fixes
+**Optional:** Single-file changes, docs, config
+
+## Process
+
+### 1. Identify Changed Files
+```bash
+git diff --name-only HEAD~1
+```
+
+### 2. Dispatch an Explore Subagent
+```
+Scout edge cases for the changes under review.
+
+Changed: {files from git diff}
+
+Find:
+1. Files importing/depending on changed modules
+2. Data flow paths through modified functions
+3. Error handling paths not tested
+4. Boundary conditions (null, empty, max)
+5. Race conditions in async code
+6. State management side effects
+```
+
+### 3. Analyze & Act
+
+| Finding | Action |
+|---------|--------|
+| Affected file not in scope | Add to review |
+| Data flow risk | Verify or add test |
+| Edge case | Add test or verify |
+| Missing test | Add before review |
+
+### 4. Document for Review
+```
+Scout findings:
+- {issues found}
+- Verified: {what checked}
+- Addressed: {what fixed}
+- Needs review: {remaining}
+```
+
+## Scout Prompts
+
+**Feature:**
+```
+Scout edge cases for {feature}.
+Changed: {files}
+Find: consumers, error states, untested inputs, performance, compatibility
+```
+
+**Bug fix:**
+```
+Scout side effects of fix in {file}.
+Bug: {description}, Fix: {approach}
+Find: other paths using logic, dependent features, similar bugs
+```
+
+**Refactor:**
+```
+Scout breaking changes in {module}.
+Before: {old}, After: {new}
+Find: importers, behavior diffs, removed functionality
+```
+
+## What Scout Catches
+
+| Issue | Why Missed | Scout Detects |
+|-------|------------|---------------|
+| Indirect deps | Not in diff | Traces imports |
+| Race conditions | Hard static review | Analyzes flow |
+| State mutations | Hidden side effects | Tracks data |
+| Missing null checks | Assumed safe | Boundary analysis |
+| Integration breaks | Out of scope | Cross-module search |
+
+## Red Flags
+
+- Shared utility changed but only one caller tested
+- Error path leads to unhandled rejection
+- State modified in place without notification
+- Breaking change without migration
+
+## Example
+
+```
+1. Done: Add cache to UserService.getUser()
+2. Diff: src/services/user-service.ts
+3. Scout: "edge cases for caching in getUser()"
+4. Report:
+   - ProfileComponent expects fresh data on edit
+   - AdminPanel loops getUser() (memory risk)
+   - No cache clear on updateUser()
+5. Fix: Add invalidation, maxSize
+6. Document for code-reviewer
+```
+
+## Bottom Line
+
+Scout before review. Don't trust "simple changes" - scout them anyway.

package/template/.claude/skills/code-review/references/input-mode-resolution.md

@@ -0,0 +1,135 @@
+---
+name: input-mode-resolution
+description: How to parse code-review arguments and resolve PR number, commit hash, pending changes, or default context into a reviewable diff
+---
+
+# Input Mode Resolution
+
+Resolve `/code-review` arguments into a diff for the review pipeline.
+
+## Auto-Detection Rules
+
+Parse arguments left-to-right. First match wins.
+
+| Pattern | Mode | Example |
+|---------|------|---------|
+| `#\d+` | PR | `#123`, `#45` |
+| GitHub PR URL | PR | `https://github.com/org/repo/pull/123` |
+| `[0-9a-f]{7,40}` | Commit | `abc1234`, full SHA |
+| `--pending` | Pending | explicit flag |
+| `codebase` | Codebase | existing mode |
+| *(none + context)* | Default | recent changes |
+| *(none + no context)* | Prompt | ask user via `AskUserQuestion` |
+
+## Resolution Commands
+
+### PR Mode
+
+```bash
+# Extract PR number from argument
+PR_NUM=$(echo "$ARG" | grep -oE '[0-9]+$')
+
+# Fetch PR metadata
+gh pr view "$PR_NUM" --json title,body,files,additions,deletions,baseRefName,headRefName
+
+# Get the diff
+gh pr diff "$PR_NUM"
+
+# Get changed file list
+gh pr diff "$PR_NUM" --name-only
+```
+
+**Context passed to reviewers:**
+- PR title and description (intent)
+- Base branch (what it merges into)
+- Full diff
+- Changed file list for scout
+
+### Commit Mode
+
+```bash
+# Validate commit exists
+git cat-file -t "$COMMIT_HASH"
+
+# Get commit metadata
+git log -1 --format="%H%n%s%n%b" "$COMMIT_HASH"
+
+# Get the diff
+git show "$COMMIT_HASH" --stat
+git show "$COMMIT_HASH" -- # full diff
+
+# Changed files
+git show "$COMMIT_HASH" --name-only --format=""
+```
+
+**Context passed to reviewers:**
+- Commit message (intent)
+- Parent commit (what it changed from)
+- Full diff
+- Changed file list for scout
+
+### Pending Mode
+
+```bash
+# Staged changes
+git diff --cached
+
+# Unstaged changes
+git diff
+
+# Combined (staged + unstaged vs HEAD)
+git diff HEAD
+
+# Changed files
+git diff HEAD --name-only
+
+# Status overview
+git status --short
+```
+
+**Context passed to reviewers:**
+- No commit message yet — ask user for brief intent description
+- Combined diff (staged + unstaged)
+- Changed file list for scout
+
+### Default Mode
+
+Use recent changes already in conversation context. If no changes apparent, fall back to Prompt mode.
+
+### Prompt Mode
+
+When no arguments and no recent context, use `AskUserQuestion`:
+- Header: "Review Target"
+- Question: "What would you like to review?"
+- Options: Pending changes, Enter PR number, Enter commit hash, Full codebase scan, Parallel codebase audit
+
+For PR/commit options, follow up with second `AskUserQuestion` to get the number/hash.
+
+### Codebase Mode
+
+Codebase modes bypass diff resolution — they scan the full codebase instead.
+- `codebase` → hand off to `references/codebase-scan-workflow.md`
+- `codebase parallel` → hand off to `references/parallel-review-workflow.md`
+
+Both workflows include code quality review and final verification.
+
+## Pipeline Handoff
+
+After resolving the diff, pass to the review pipeline:
+
+```
+Resolved diff
+  ├─ Changed files → Edge case scout
+  ├─ Full diff → Stage 1 (Spec compliance, if plan exists)
+  ├─ Full diff → Stage 2 (Code quality review)
+  └─ Findings → Fix accepted issues and verify
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| PR not found | `gh pr view` fails → report "PR #N not found in this repo" |
+| Commit not found | `git cat-file` fails → report "Commit not found — is it pushed?" |
+| No pending changes | `git diff HEAD` empty → report "No pending changes to review" |
+| Ambiguous input | Could be PR or commit → prefer PR (more common), note assumption |

package/template/.claude/skills/code-review/references/parallel-review-workflow.md

@@ -0,0 +1,76 @@
+# Parallel Review Workflow
+
+**Ultrathink** to exhaustively list ALL potential edge cases, then dispatch parallel `code-reviewer` agents to verify: <scope>$ARGUMENTS</scope>
+
+**IMPORTANT:** Activate needed skills. Ensure token efficiency. Sacrifice grammar for concision.
+
+## Workflow
+
+### 1. Ultrathink Edge Cases
+
+Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
+- Read any project overview docs the repo has, for context
+- Dispatch an `Explore` subagent to find relevant files
+- **Think exhaustively** about what could go wrong:
+  - Null/undefined scenarios
+  - Boundary conditions (off-by-one, empty, max values)
+  - Error handling gaps
+  - Race conditions, async edge cases
+  - Input validation holes
+  - Trust-boundary defects
+  - Resource leaks
+  - Untested code paths
+
+**Output format:**
+```markdown
+## Edge Cases Identified
+
+### Category: [scope-area]
+1. [edge case description] → files: [file1, file2]
+```
+
+### 2. Categorize & Assign
+
+Group edge cases by similar scope for parallel verification:
+- Each category → one `code-reviewer` agent
+- Max 6 categories (merge small ones)
+- Each reviewer gets specific edge cases to VERIFY, not discover
+
+### 3. Parallel Verification
+
+Launch N `code-reviewer` subagents simultaneously:
+- Pass: category name, list of edge cases, relevant files
+- Task: **VERIFY** if each edge case is properly handled in code
+- Report: which edge cases are handled vs unhandled
+
+### 4. Aggregate Results
+
+```markdown
+## Edge Case Verification Report
+
+### Summary
+- Total edge cases: X
+- Handled: Y
+- Unhandled: Z
+- Partial: W
+
+### Unhandled Edge Cases (Need Fix)
+| # | Edge Case | File | Status |
+|---|-----------|------|--------|
+```
+
+### 5. Verification Review
+
+After aggregation, verify accepted findings against the full scope:
+- Re-check aggregated findings and unhandled edge cases
+- Confirm each blocking issue has a concrete file/line and reproduction path
+- Classify findings as Accept / Reject / Defer
+
+### 6. Auto-Fix Pipeline
+
+**IF** unhandled/partial edge cases found:
+- Ask: "Found N unhandled edge cases. Fix them now? [Y/n]" — on yes, fix by category, re-verify each
+
+### 7. Final Report
+- Summary of verification
+- Ask: "Commit? [Y/n]" → use `git-manager`

package/template/.claude/skills/code-review/references/requesting-code-review.md

@@ -0,0 +1,116 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer subagent to review implementation against plan or requirements before proceeding
+---
+
+# Requesting Code Review
+
+Dispatch code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Scout first, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**0. Scout edge cases first (NEW):**
+```
+Before dispatching code-reviewer, dispatch an `Explore` subagent to find:
+- Files affected by changes (not just modified files)
+- Data flow paths that could break
+- Edge cases and boundary conditions
+- Potential side effects
+
+See: references/edge-case-scouting.md
+```
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from <path/to/plan.md>
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/template/.claude/skills/code-review/references/spec-compliance-review.md

@@ -0,0 +1,43 @@
+---
+name: spec-compliance-review
+description: First-pass review checking implementation matches spec/plan requirements before quality review
+---
+
+# Spec Compliance Review
+
+## Purpose
+
+Verify implementation matches what was requested BEFORE evaluating code quality.
+Well-written code that doesn't match requirements is still wrong.
+
+## When to Use
+
+- After implementing features from a plan
+- Before code quality review pass
+- When plan/spec exists for the work being reviewed
+
+## Process
+
+1. **Load spec/plan** — Read the plan.md or phase file that defined this work
+2. **List requirements** — Extract every requirement, acceptance criterion
+3. **Check each requirement** against actual implementation:
+   - Present? → PASS
+   - Missing? → MISSING (must fix before quality review)
+   - Extra (not in spec)? → EXTRA (flag for removal unless justified)
+4. **Verdict:**
+   - All requirements met, no unjustified extras → PASS → proceed to quality review
+   - Missing requirements → FAIL → implementer fixes → re-review
+   - Unjustified extras → WARN → discuss with user
+
+## Checklist Template
+
+| # | Requirement | Status | Notes |
+|---|-------------|--------|-------|
+| 1 | [from spec] | PASS/MISSING/EXTRA | [evidence] |
+
+## Red Flags
+
+- Skipping spec review because "code looks good"
+- Accepting extra features without spec justification
+- Treating spec review as optional
+- Reviewing code quality before confirming spec compliance

package/template/.claude/skills/code-review/references/task-management-reviews.md

@@ -0,0 +1,140 @@
+# Review Task Management Patterns
+
+Track review pipeline execution via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList).
+
+## When to Create Tasks
+
+| Review Scope | Tasks? | Rationale |
+|--------------|--------|-----------|
+| Single-file fix | No | Scout + review + done, overhead not worth it |
+| Multi-file feature (3+ files) | Yes | Track scout → review → fix → verify chain |
+| Parallel reviewers (2+ scopes) | Yes | Coordinate independent reviews |
+| Review cycle with Critical fixes | Yes | Dependencies between fix → re-verify |
+
+**3-Task Rule:** Skip task creation when review pipeline has <3 meaningful steps.
+
+## Review Pipeline as Tasks
+
+```
+TaskCreate: "Scout edge cases"         → pending
+TaskCreate: "Review implementation"    → pending, blockedBy: [scout]
+TaskCreate: "Fix critical issues"      → pending, blockedBy: [review]
+TaskCreate: "Verify fixes pass"        → pending, blockedBy: [fix]
+```
+
+Dependency chain auto-unblocks: scout → review → fix → verify.
+
+## Task Schemas
+
+### Scout Task
+
+```
+TaskCreate(
+  subject: "Scout edge cases for {feature}",
+  activeForm: "Scouting edge cases",
+  description: "Identify affected files, data flows, boundary conditions. Changed: {files}",
+  metadata: { reviewStage: "scout", feature: "{feature}",
+              changedFiles: "src/auth.ts,src/middleware.ts",
+              priority: "P2", effort: "3m" }
+)
+```
+
+### Review Task
+
+```
+TaskCreate(
+  subject: "Review {feature} implementation",
+  activeForm: "Reviewing {feature}",
+  description: "Code-reviewer subagent reviews {BASE_SHA}..{HEAD_SHA}. Plan: {plan_ref}",
+  metadata: { reviewStage: "review", feature: "{feature}",
+              baseSha: "{BASE_SHA}", headSha: "{HEAD_SHA}",
+              priority: "P1", effort: "10m" },
+  addBlockedBy: ["{scout-task-id}"]
+)
+```
+
+### Fix Task (created after review finds issues)
+
+```
+TaskCreate(
+  subject: "Fix {severity} issues from review",
+  activeForm: "Fixing {severity} review issues",
+  description: "Address: {issue_list}",
+  metadata: { reviewStage: "fix", severity: "critical",
+              issueCount: 3, priority: "P1", effort: "15m" },
+  addBlockedBy: ["{review-task-id}"]
+)
+```
+
+### Verify Task
+
+```
+TaskCreate(
+  subject: "Verify fixes pass tests and build",
+  activeForm: "Verifying fixes",
+  description: "Run test suite, build, confirm 0 failures. Evidence before claims.",
+  metadata: { reviewStage: "verify", priority: "P1", effort: "5m" },
+  addBlockedBy: ["{fix-task-id}"]
+)
+```
+
+## Parallel Review Coordination
+
+For multi-scope reviews (e.g., backend + frontend changed independently):
+
+```
+// Create scoped review tasks — no blockedBy between them
+TaskCreate(subject: "Review backend auth changes",
+  metadata: { reviewStage: "review", scope: "src/api/,src/middleware/",
+              agentIndex: 1, totalAgents: 2, priority: "P1" })
+
+TaskCreate(subject: "Review frontend auth UI",
+  metadata: { reviewStage: "review", scope: "src/components/auth/",
+              agentIndex: 2, totalAgents: 2, priority: "P1" })
+
+// Both run simultaneously via separate code-reviewer subagents
+// Fix task blocks on BOTH completing:
+TaskCreate(subject: "Fix all review issues",
+  addBlockedBy: ["{backend-review-id}", "{frontend-review-id}"])
+```
+
+## Task Lifecycle
+
+```
+Scout:    pending → in_progress → completed (scout report returned)
+Review:   pending → in_progress → completed (reviewer findings returned)
+Fix:      pending → in_progress → completed (all Critical/Important fixed)
+Verify:   pending → in_progress → completed (tests pass, build clean)
+```
+
+### Handling Re-Reviews
+
+When fixes introduce new issues → create new review cycle:
+
+```
+TaskCreate(subject: "Re-review after fixes",
+  addBlockedBy: ["{fix-task-id}"],
+  metadata: { reviewStage: "review", cycle: 2, priority: "P1" })
+```
+
+Limit to 3 cycles. If still failing after cycle 3 → escalate to user.
+
+## Integration with Planning Tasks
+
+Review tasks are **separate from** cook/planning phase tasks.
+
+**When cook spawns review:**
+1. Cook completes implementation phase → creates review pipeline tasks
+2. Review pipeline executes (scout → review → fix → verify)
+3. All review tasks complete → cook marks phase as reviewed
+4. Cook proceeds to next phase
+
+Review tasks reference the phase but don't block it directly — the orchestrator manages handoff.
+
+## Quality Check
+
+After pipeline registration: `Registered [N] review tasks (scout → review → fix → verify chain)`
+
+## Error Handling
+
+If `TaskCreate` fails: log warning, fall back to sequential review without task tracking. Review pipeline functions identically — tasks add visibility, not functionality.