@massu/core 0.1.2 → 0.4.1

package/commands/massu-docs.md

@@ -0,0 +1,364 @@
+---
+name: massu-docs
+description: Documentation sync protocol ensuring docs align with code changes and features
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-docs
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9 enforced.
+
+# Massu Docs: Documentation Sync Protocol
+
+## Objective
+
+Ensure **documentation accuracy** by auditing documentation content against current codebase features, CLI elements, and workflows. Keep help articles, CLAUDE.md, and API docs in sync with code changes.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Code is truth** - Docs must match actual behavior
+- **Feature parity** - Every user feature needs docs
+- **Terminology sync** - Same labels in CLI output and docs
+- **Version awareness** - Document breaking changes
+- **No assumptions** - Verify features exist before documenting
+
+---
+
+## ZERO-GAP AUDIT LOOP
+
+**Documentation sync does NOT complete until a SINGLE COMPLETE AUDIT finds ZERO discrepancies.**
+
+### The Rule
+
+```
+DOCS AUDIT LOOP:
+  1. Run ALL documentation checks (features, terminology, API)
+  2. Count discrepancies found
+  3. IF discrepancies > 0:
+       - Fix ALL discrepancies
+       - Re-run ENTIRE audit from Step 1
+  4. IF discrepancies == 0:
+       - DOCS IN SYNC
+```
+
+**Partial re-checks are NOT valid. The ENTIRE docs audit must pass in a SINGLE run.**
+
+---
+
+## DOCUMENTATION LOCATIONS
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| CLAUDE.md | `.claude/CLAUDE.md` | AI assistant context and project rules |
+| Config docs | `massu.config.yaml` comments | Config schema documentation |
+| README | `packages/core/README.md` | Public-facing package docs |
+| Website docs | `website/` (if applicable) | User-facing documentation site |
+| Command files | `.claude/commands/*.md` | Workflow command documentation |
+| Plans | `docs/plans/*.md` | Implementation plans and specs |
+
+---
+
+## AUDIT SECTION 1: FEATURE INVENTORY
+
+### 1.1 List All MCP Tools (User-Facing Features)
+```bash
+# Find all tool definitions
+grep -rn "name:" packages/core/src/tools.ts packages/core/src/*-tools.ts packages/core/src/*.ts 2>/dev/null \
+  | grep -E "name:\s*[\`'\"]" \
+  | grep -v "__tests__" \
+  | head -40
+
+# Count tools
+grep -c "name:" packages/core/src/tools.ts 2>/dev/null
+```
+
+### 1.2 Feature Matrix
+```markdown
+### Feature Inventory
+
+| Feature/Tool | Module | Documented in README | Documented in CLAUDE.md | Status |
+|-------------|--------|---------------------|------------------------|--------|
+| [tool] | [module] | YES/NO | YES/NO | OK/NEEDS DOC |
+```
+
+### 1.3 Find Undocumented Features
+Compare tools found in codebase against README documentation.
+
+---
+
+## AUDIT SECTION 2: CLI/TOOL OUTPUT SYNC
+
+### 2.1 Extract Tool Output Strings
+```bash
+# Find tool output text
+grep -rn "text:" packages/core/src/ --include="*.ts" | grep -v "__tests__" | head -30
+
+# Find error messages
+grep -rn "Error\|error\|Invalid\|invalid" packages/core/src/ --include="*.ts" | grep -v "__tests__" | head -20
+```
+
+### 2.2 Terminology Matrix
+```markdown
+### Tool Output Terminology Audit
+
+| Tool | Output String | Docs String | Match | Status |
+|------|--------------|-------------|-------|--------|
+| [tool] | [code] | [docs] | YES/NO | OK/FIX |
+```
+
+---
+
+## AUDIT SECTION 3: WORKFLOW DOCUMENTATION
+
+### 3.1 Identify User Workflows
+```bash
+# Find all command files (these define workflows)
+ls .claude/commands/massu-*.md | wc -l
+
+# Find workflow references in CLAUDE.md
+grep "massu-" .claude/CLAUDE.md | head -30
+```
+
+### 3.2 Workflow Matrix
+```markdown
+### Workflow Documentation
+
+| Workflow | Command File | In CLAUDE.md | Steps Match | Status |
+|----------|-------------|--------------|-------------|--------|
+| Implementation | massu-loop.md | YES | YES/NO | OK/UPDATE |
+| Commit | massu-commit.md | YES | YES/NO | OK/UPDATE |
+```
+
+### 3.3 Verify Command Table in CLAUDE.md
+
+Compare the Workflow Commands tables in CLAUDE.md against actual command files:
+```bash
+# Count commands in CLAUDE.md table
+grep -c "massu-" .claude/CLAUDE.md
+
+# Count actual command files
+ls .claude/commands/massu-*.md | wc -l
+```
+
+**CRITICAL**: Every command file MUST be listed in the CLAUDE.md Workflow Commands tables.
+
+---
+
+## AUDIT SECTION 4: API/CONFIG DOCUMENTATION
+
+### 4.1 Config Schema Documentation
+```bash
+# Check massu.config.yaml has comments explaining fields
+grep -c "#" massu.config.yaml
+
+# Check config.ts documents the schema
+grep -c "description\|comment\|//" packages/core/src/config.ts
+```
+
+### 4.2 API Documentation
+```bash
+# Check if tool inputSchema has descriptions for all properties
+grep -rn "description:" packages/core/src/ --include="*.ts" | grep -v "__tests__" | wc -l
+```
+
+### 4.3 Config Documentation Matrix
+```markdown
+### Config Documentation
+
+| Config Key | Documented in YAML | Documented in README | Type Correct | Status |
+|-----------|-------------------|---------------------|--------------|--------|
+| [key] | YES/NO | YES/NO | YES/NO | OK/FIX |
+```
+
+---
+
+## AUDIT SECTION 5: README ACCURACY
+
+### 5.1 Check README Contents
+```bash
+# Read public README
+cat packages/core/README.md 2>/dev/null | head -50
+
+# Check if README mentions all key features
+grep -c "tool\|hook\|config\|install\|usage" packages/core/README.md 2>/dev/null
+```
+
+### 5.2 README Sections Checklist
+```markdown
+### README Completeness
+
+| Section | Present | Accurate | Status |
+|---------|---------|----------|--------|
+| Installation | YES/NO | YES/NO | OK/FIX |
+| Configuration | YES/NO | YES/NO | OK/FIX |
+| Usage | YES/NO | YES/NO | OK/FIX |
+| Tools Reference | YES/NO | YES/NO | OK/FIX |
+| Contributing | YES/NO | YES/NO | OK/FIX |
+```
+
+---
+
+## AUDIT SECTION 6: DEVELOPER DOCS SYNC
+
+### 6.1 CLAUDE.md Accuracy
+```bash
+# Check if CLAUDE.md file locations match actual
+grep "packages/core/src/" .claude/CLAUDE.md | while read line; do
+  path=$(echo "$line" | grep -oP 'packages/core/src/[a-zA-Z0-9_./-]+')
+  if [ -n "$path" ]; then
+    [ -f "$path" ] && echo "OK: $path" || echo "MISSING: $path"
+  fi
+done
+
+# Verify tool module inventory matches actual files
+grep -c "\.ts" .claude/CLAUDE.md
+```
+
+### 6.2 Build & Test Commands Accuracy
+```bash
+# Verify each documented build command works
+npm run build --dry-run 2>/dev/null
+npm test --help 2>/dev/null
+```
+
+### 6.3 Developer Docs Matrix
+```markdown
+### Developer Documentation
+
+| Doc | Last Updated | Accurate | Status |
+|-----|--------------|----------|--------|
+| CLAUDE.md | [date] | YES/NO | OK/UPDATE |
+| massu.config.yaml | [date] | YES/NO | OK/UPDATE |
+| README.md | [date] | YES/NO | OK/UPDATE |
+```
+
+---
+
+## SYNC PROCESS
+
+### When Code Changes
+
+1. **Identify impact**
+   - What feature/tool changed?
+   - What CLI output changed?
+   - What workflows changed?
+
+2. **Find related docs**
+   - Search README for feature mentions
+   - Search CLAUDE.md for related rules
+   - Search command files for related references
+
+3. **Update docs**
+   - Change terminology if labels changed
+   - Update steps if workflow changed
+   - Update examples if API changed
+   - Update CLAUDE.md tables if commands added/removed
+
+4. **Verify sync**
+   - Re-read updated docs
+   - Compare against actual behavior
+   - Run documented commands to verify accuracy
+
+---
+
+## DOCS SYNC REPORT FORMAT
+
+```markdown
+## MASSU DOCS SYNC REPORT
+
+### Summary
+- **Date**: [timestamp]
+- **Scope**: Full sync / [specific area]
+- **Features Audited**: [N]
+- **Issues Found**: [N]
+
+### Feature Coverage
+| Status | Count |
+|--------|-------|
+| Documented | N |
+| Undocumented | N |
+| Outdated | N |
+
+### Terminology Sync
+| Status | Count |
+|--------|-------|
+| Matching | N |
+| Mismatched | N |
+
+### Issues Found
+| Priority | Issue | Location | Fix |
+|----------|-------|----------|-----|
+| HIGH | [issue] | [loc] | [fix] |
+
+### Updates Applied
+- [Update 1]
+- [Update 2]
+
+### Recommendations
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+**DOCS STATUS: IN SYNC / NEEDS UPDATE / CRITICAL**
+```
+
+---
+
+## SESSION STATE UPDATE
+
+After sync, update `session-state/CURRENT.md`:
+
+```markdown
+## DOCS SYNC SESSION
+
+### Audit
+- **Date**: [timestamp]
+- **Scope**: Full / [specific area]
+
+### Findings
+- Undocumented features: [N]
+- Outdated docs: [N]
+- Terminology mismatches: [N]
+
+### Updates Applied
+[List or "None - audit only"]
+
+### Status
+- README: IN SYNC / NEEDS UPDATE
+- CLAUDE.md: IN SYNC / NEEDS UPDATE
+- Config docs: IN SYNC / NEEDS UPDATE
+```
+
+---
+
+## QUICK COMMANDS
+
+```bash
+# List all MCP tools (potential doc topics)
+grep -rn "name:" packages/core/src/tools.ts | head -20
+
+# Check CLAUDE.md freshness
+ls -la .claude/CLAUDE.md
+
+# List command files
+ls -la .claude/commands/massu-*.md | wc -l
+
+# Search docs for term
+grep -rn "[search term]" packages/core/README.md .claude/CLAUDE.md 2>/dev/null
+```
+
+---
+
+## START NOW
+
+1. Run Section 1: Feature Inventory
+2. Run Section 2: CLI/Tool Output Sync
+3. Run Section 3: Workflow Documentation
+4. Run Section 4: API/Config Documentation
+5. Run Section 5: README Accuracy
+6. Run Section 6: Developer Docs Sync
+7. Apply necessary updates
+8. Produce Docs Sync Report
+9. Update session state
+
+**Remember: Documentation is a product. Outdated docs = broken product.**

package/commands/massu-estimate.md

@@ -0,0 +1,313 @@
+---
+name: massu-estimate
+description: Effort estimation with complexity scoring, codebase impact analysis, and historical comparison
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+name: massu-estimate
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
+
+# CS Estimate: Effort Estimation
+
+## Objective
+
+Analyze a feature or change request, score its complexity across multiple dimensions, measure codebase impact, compare against historical work, and produce a structured effort estimate. This is READ-ONLY — no source code is modified.
+
+**Usage**: `/massu-estimate [description of the feature or change]`
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- Do NOT modify any files
+- All estimates MUST be based on actual codebase data — no guessing
+- FIX ALL ISSUES ENCOUNTERED (CR-9) — if blockers are found during analysis, flag them
+- Express uncertainty explicitly — ranges are more honest than point estimates
+- Every complexity factor MUST be justified with a concrete codebase observation
+
+---
+
+## STEP 1: REQUIREMENT ANALYSIS
+
+Parse and clarify the request from `$ARGUMENTS`.
+
+### 1a. Identify Change Type
+
+```markdown
+### Change Classification
+
+| Dimension | Assessment |
+|-----------|-----------|
+| Type | [new feature / enhancement / bug fix / refactor / infrastructure] |
+| Scope | [MCP tool / website / config / testing / documentation / multi-area] |
+| Public API change? | YES/NO — [what changes] |
+| Database change? | YES/NO — [what changes] |
+| Config change? | YES/NO — [what changes] |
+| New dependencies? | YES/NO — [what needed] |
+```
+
+### 1b. Decompose into Sub-Tasks
+
+Break the request into concrete deliverables:
+
+```markdown
+### Sub-Task Breakdown
+
+| # | Sub-Task | Type |
+|---|----------|------|
+| 1 | [task] | [implementation/test/config/docs] |
+| 2 | [task] | [implementation/test/config/docs] |
+| ... | | |
+```
+
+---
+
+## STEP 2: CODEBASE IMPACT ANALYSIS
+
+Determine what the change will touch.
+
+### 2a. Files That Will Be Modified
+
+```bash
+# Search for related code to the requested feature
+grep -rn "$ARGUMENTS" packages/core/src/ --include="*.ts" | head -20
+grep -rn "$ARGUMENTS" website/src/ --include="*.ts" --include="*.tsx" | head -20
+```
+
+### 2b. Tool Registration Impact (if adding MCP tools)
+
+```bash
+# Count existing tools for baseline
+grep -c "name:" packages/core/src/tools.ts 2>/dev/null
+
+# Check if tool registration pattern is stable
+grep -n "getToolDefinitions\|handleToolCall" packages/core/src/tools.ts | head -10
+```
+
+### 2c. Database Schema Impact
+
+```bash
+# If changes require schema: check existing tables
+grep -rn "CREATE TABLE" website/supabase/migrations/*.sql 2>/dev/null | tail -10
+grep -rn "CREATE TABLE\|ALTER TABLE" packages/core/src/memory-db.ts 2>/dev/null | head -10
+```
+
+### 2d. Config Impact
+
+```bash
+# Current config structure
+cat massu.config.yaml 2>/dev/null | head -30
+
+# Config interface
+grep -A 30 "interface.*Config\|type.*Config" packages/core/src/config.ts 2>/dev/null | head -40
+```
+
+### 2e. Blast Radius Estimate
+
+```bash
+# How many files import from core modules that would change
+grep -rn "from.*tools\|from.*server\|from.*config" packages/core/src/ --include="*.ts" | wc -l
+```
+
+```markdown
+### Impact Matrix
+
+| Area | Impact | Files Affected | Notes |
+|------|--------|---------------|-------|
+| MCP tools | [NONE/LOW/MED/HIGH] | [N] | [details] |
+| Website | [NONE/LOW/MED/HIGH] | [N] | [details] |
+| Database | [NONE/LOW/MED/HIGH] | [N] | [details] |
+| Config | [NONE/LOW/MED/HIGH] | [N] | [details] |
+| Tests | [NONE/LOW/MED/HIGH] | [N] | [details] |
+| Total affected files | | [N] | |
+```
+
+---
+
+## STEP 3: COMPLEXITY SCORING
+
+Score complexity across 6 dimensions. Each dimension is 1-5 (1=trivial, 5=very complex).
+
+### Scoring Rubric
+
+| Score | Definition |
+|-------|-----------|
+| 1 | Trivial — copy-paste pattern, well-understood domain, no surprises |
+| 2 | Simple — small change, existing pattern to follow |
+| 3 | Moderate — some novel logic, a few unknowns |
+| 4 | Complex — non-trivial logic, cross-cutting concerns, or significant unknowns |
+| 5 | Very complex — research required, high risk, many unknowns |
+
+### 3a. Technical Complexity
+
+```bash
+# How novel is this relative to existing patterns?
+# Read the most similar existing implementation for comparison
+ls packages/core/src/*.ts | head -10
+```
+
+Score: [1-5] — Justification: [based on similarity to existing patterns]
+
+### 3b. Integration Complexity
+
+```bash
+# How many systems does this touch?
+# Check all integration points
+grep -rn "import.*from" packages/core/src/tools.ts | wc -l
+```
+
+Score: [1-5] — Justification: [number of integration points]
+
+### 3c. Testing Complexity
+
+```bash
+# Existing test patterns for reference
+ls packages/core/src/__tests__/ 2>/dev/null
+wc -l packages/core/src/__tests__/*.test.ts 2>/dev/null | sort -rn | head -5
+```
+
+Score: [1-5] — Justification: [test scope required]
+
+### 3d. Risk Complexity
+
+```bash
+# Are there known blockers or failure modes?
+cat .claude/session-state/CURRENT.md 2>/dev/null | grep -i "failed\|blocked\|issue" | head -10
+```
+
+Score: [1-5] — Justification: [known risks identified]
+
+### 3e. Documentation Complexity
+
+Score: [1-5] — Justification: [scope of docs required: JSDoc / README / API ref / config schema]
+
+### 3f. Verification Complexity
+
+```bash
+# How many VR- gates apply?
+# Count applicable: VR-TEST, VR-TYPE, VR-TOOL-REG, VR-HOOK-BUILD, VR-PATTERN, VR-BLAST-RADIUS
+```
+
+Score: [1-5] — Justification: [N applicable verification gates]
+
+```markdown
+### Complexity Scorecard
+
+| Dimension | Score (1-5) | Weight | Weighted Score | Justification |
+|-----------|-------------|--------|----------------|---------------|
+| Technical | [N] | 2x | [N] | [reason] |
+| Integration | [N] | 1.5x | [N] | [reason] |
+| Testing | [N] | 1.5x | [N] | [reason] |
+| Risk | [N] | 2x | [N] | [reason] |
+| Documentation | [N] | 1x | [N] | [reason] |
+| Verification | [N] | 1x | [N] | [reason] |
+| **Total weighted score** | | | **[N]/50** | |
+
+**Complexity Tier**: TRIVIAL (≤10) / SMALL (11-20) / MEDIUM (21-30) / LARGE (31-40) / EXTRA LARGE (>40)
+```
+
+---
+
+## STEP 4: HISTORICAL COMPARISON
+
+Compare against completed work for calibration.
+
+### 4a. Recent Similar Work
+
+```bash
+# Commits of similar type/scope
+git log -30 --format="%H %s" 2>/dev/null | grep -i "feat\|add\|implement" | head -15
+```
+
+### 4b. Time Proxy: Commit Count
+
+```bash
+# How many commits did similar features take?
+# Look at feat commits and their diff stats
+git log -20 --stat --format="%s" 2>/dev/null | grep -A 5 "^feat"
+```
+
+```markdown
+### Historical Comparison
+
+| Similar Past Work | Commit Count | Complexity Score | Actual Outcome |
+|-------------------|-------------|-----------------|----------------|
+| [commit subject] | [N] | [estimated] | [result if known] |
+```
+
+---
+
+## STEP 5: ESTIMATE GENERATION
+
+Produce the final estimate.
+
+```markdown
+### EFFORT ESTIMATE
+
+**Request**: [description from $ARGUMENTS]
+**Complexity Tier**: [TRIVIAL/SMALL/MEDIUM/LARGE/EXTRA LARGE]
+**Complexity Score**: [N]/50
+
+### Sub-Task Estimates
+
+| # | Sub-Task | Complexity | Estimate | Notes |
+|---|----------|-----------|----------|-------|
+| 1 | [task] | [1-5] | [S/M/L] | [key assumption] |
+| 2 | [task] | [1-5] | [S/M/L] | [key assumption] |
+
+**S** = Small (< 1 session)  |  **M** = Medium (1-3 sessions)  |  **L** = Large (3+ sessions, consider plan)
+
+### Total Estimate
+
+| Scenario | Reasoning |
+|----------|-----------|
+| Optimistic | [N] sessions — [if assumptions hold and no blockers] |
+| Realistic | [N] sessions — [expected with normal iteration] |
+| Pessimistic | [N] sessions — [if integration complexity materializes] |
+
+### Recommendation
+
+**Approach**: [implement directly / create-plan first / spike required]
+
+**Rationale**: [why this approach given the complexity score]
+
+### Key Assumptions
+
+1. [assumption 1 — what must be true for estimate to hold]
+2. [assumption 2]
+3. [assumption 3]
+
+### Risk Flags
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| [risk] | HIGH/MED/LOW | HIGH/MED/LOW | [mitigation] |
+```
+
+---
+
+## COMPLETION REPORT
+
+```markdown
+## CS ESTIMATE COMPLETE
+
+### Request Analyzed
+- **Feature**: [description]
+- **Complexity Tier**: [tier]
+- **Weighted Score**: [N]/50
+
+### Estimate Summary
+- **Optimistic**: [N] sessions
+- **Realistic**: [N] sessions
+- **Pessimistic**: [N] sessions
+
+### Files Analyzed
+| File | Purpose |
+|------|---------|
+| [file] | [why read] |
+
+### Suggested Next Step
+- Score < 20 (Small): `/massu-hotfix` or direct implementation
+- Score 21-30 (Medium): Direct implementation with `/massu-loop`
+- Score 31+ (Large): Create plan first with `/massu-create-plan`
+```