maestro-flow 0.1.0

package/.codex/skills/quality-refactor/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: maestro-refactor
+description: Tech debt reduction with reflection-driven iteration. Analyze scope, plan refactoring, execute with test verification, reflect on strategy per round.
+argument-hint: "<phase|--dir path> [--max-iterations N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+# Refactor
+
+## Usage
+
+```bash
+$maestro-refactor "src/auth"                    # module path scope
+$maestro-refactor "authentication"              # feature area scope
+$maestro-refactor "all"                         # full codebase scan
+$maestro-refactor "src/api --max-iterations 5"  # limit iteration rounds
+$maestro-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume existing
+```
+
+**Flags**:
+- `<phase|scope>`: Module path, feature area, or "all"
+- `--dir path`: Resume existing refactor scratch directory
+- `--max-iterations N`: Max refactoring rounds (default: 3)
+
+**Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
+
+---
+
+## Overview
+
+Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
+
+---
+
+## Implementation
+
+### Step 1: Parse Scope
+
+1. Parse `$ARGUMENTS` for scope and flags
+2. If `--dir` provided: resume existing scratch directory (skip to Step 5)
+3. Scope types:
+   - Module path (e.g., "src/auth") -> scan that directory
+   - Feature area (e.g., "authentication") -> search for related files
+   - "all" -> full codebase scan
+4. If empty: prompt user via AskUserQuestion with options (Module path / Feature area / Full codebase)
+5. Detect `--max-iterations N` (default: 3)
+
+### Step 2: Create Scratch Directory
+
+```bash
+REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"
+mkdir -p "$REFACTOR_DIR/.task"
+mkdir -p "$REFACTOR_DIR/.summaries"
+```
+
+Write `index.json` with type "refactor", scope, status "active", plan/execution/reflection counters.
+
+### Step 3: Scope Analysis
+
+Load project specs if available (`maestro spec load --category execution`).
+
+Analyze scope for tech debt categories:
+
+| Category | What to Look For |
+|----------|-----------------|
+| Duplication | Repeated code blocks, copy-paste patterns |
+| Complexity | Long functions, deep nesting, high cyclomatic complexity |
+| Naming | Inconsistent naming, unclear identifiers |
+| Dependencies | Circular deps, tight coupling, god objects |
+| Dead code | Unused functions, unreachable branches |
+| Pattern violations | Inconsistent with project conventions |
+
+Present analysis summary table with category, count, severity.
+Confirm with user before proceeding.
+
+### Step 4: Plan Refactoring
+
+1. Write `plan.json` with scope, total_tasks, strategy ("incremental -- each task independently safe")
+2. For each identified issue, create `.task/TASK-{NNN}.json`:
+   - id, title, status (pending), type (refactor), category
+   - description, read_first files, files with action/target/change
+   - convergence.criteria (grep-verifiable), verification command
+   - implementation steps, risk level
+3. Order: high risk last, dependencies respected, quick wins first
+4. Update `index.json` plan fields
+5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
+
+### Step 5: Execute with Reflection
+
+Initialize `reflection-log.md` if not exists.
+
+For each task in order:
+
+**5a. Execute refactoring:**
+
+Spawn Agent for complex refactoring tasks:
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "Execute refactoring: {task title}",
+  prompt: "Implement refactoring as described. Read files in read_first, apply changes to target files. Follow convergence criteria exactly.",
+  run_in_background: false
+})
+```
+
+**5b. Run test suite:**
+```bash
+npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1
+```
+
+**5c. Record in reflection-log.md:**
+```markdown
+## Round {N}: {task title}
+
+- **Strategy:** {approach taken}
+- **Result:** {pass|fail}
+- **Tests:** {all pass | N failures}
+- **Adjustment:** {what to change next, or "none needed"}
+- **Files changed:** {list}
+```
+
+**5d. Handle test failures:**
+1. Revert the change
+2. Record failure + strategy adjustment in reflection-log.md
+3. Retry with adjusted strategy (max 2 retries per task)
+4. If still failing: mark task "blocked", continue to next
+
+**5e. Update state:**
+- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
+- `.summaries/TASK-{NNN}-summary.md` written
+- `index.json` execution and reflection fields updated
+
+### Step 6: Final Verification
+
+Run full test suite. Record final state in reflection-log.md:
+```markdown
+## Final Verification
+
+- **Tests:** {result}
+- **Tasks completed:** {N}/{total}
+- **Tasks blocked:** {N}
+- **Key learnings:** {patterns discovered}
+```
+
+### Step 7: Complete and Report
+
+Update `index.json`: status -> "completed", final execution/reflection counts.
+
+```
+## Refactoring Complete: {scope}
+
+| Metric | Value |
+|--------|-------|
+| Tasks completed | {N}/{total} |
+| Tasks blocked | {N} |
+| Reflection rounds | {N} |
+| Strategy adjustments | {N} |
+| Tests passing | {yes/no} |
+
+Key learnings:
+{from reflection-log.md}
+
+Artifacts:
+- Reflection log: {REFACTOR_DIR}/reflection-log.md
+- Task results: {REFACTOR_DIR}/.summaries/
+```
+
+If regressions: suggest Skill({ skill: "quality-debug" }).
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage | Note uncovered areas, proceed with extra caution |
+
+---
+
+## Core Rules
+
+- **Test after every change** -- zero regressions tolerated
+- **Revert on failure** -- never leave broken state
+- **Max 2 retries per task** with strategy adjustment
+- **Reflection-driven** -- every round records strategy, outcome, adjustment
+- **User approval required** before execution (Step 4)
+- **Quick wins first** -- order by risk (low first) and dependency
+- **Agent calls use `run_in_background: false`** for synchronous execution
+- **Incremental safety** -- each task is independently safe to apply or revert

package/.codex/skills/quality-review/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: maestro-review
+description: Tiered code review via CSV wave pipeline. Decomposes into 6 dimension agents running in parallel, with optional deep-dive aggregation wave. Replaces quality-review command.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--level quick|standard|deep] [--dimensions list]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validation, use defaults for level detection.
+
+# Maestro Review (CSV Wave)
+
+## Usage
+
+```bash
+$maestro-review "3"
+$maestro-review -c 6 "3 --level deep"
+$maestro-review -y "3 --dimensions security,performance"
+$maestro-review --continue "review-phase3-20260318"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 6)
+- `--continue`: Resume existing session
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + `review.json` (structured review output)
+
+---
+
+## Overview
+
+Wave-based multi-dimensional code review using `spawn_agents_on_csv`. Decomposes review into independent dimension agents (Wave 1), then aggregates findings into a unified report with verdict (Wave 2).
+
+**Core workflow**: Collect Files → Decompose Dimensions → Parallel Review → Aggregate + Verdict
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    CODE REVIEW CSV WAVE WORKFLOW                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  Phase 1: Phase Resolution → CSV                                         │
+│     ├─ Resolve phase directory from arguments                            │
+│     ├─ Collect changed files from task summaries                         │
+│     ├─ Auto-detect review level (quick/standard/deep)                    │
+│     ├─ Determine active dimensions                                       │
+│     ├─ Generate tasks.csv with one row per dimension                     │
+│     └─ User validates dimension breakdown (skip if -y)                   │
+│                                                                          │
+│  Phase 2: Wave Execution Engine                                          │
+│     ├─ Wave 1: Dimension Review (parallel)                               │
+│     │   ├─ Each dimension agent reviews all changed files                │
+│     │   ├─ Agent classifies findings by severity                         │
+│     │   ├─ Discoveries shared via board (patterns, conventions)          │
+│     │   └─ Results: severity_counts + top_issues per dimension           │
+│     ├─ Wave 2: Aggregation + Deep-Dive (if needed)                       │
+│     │   ├─ Aggregate all dimension findings                              │
+│     │   ├─ If criticals > 0 (standard) or always (deep): deep-dive      │
+│     │   ├─ Cross-dimension impact analysis                               │
+│     │   └─ Generate verdict: PASS / WARN / BLOCK                        │
+│     └─ discoveries.ndjson shared across all waves (append-only)          │
+│                                                                          │
+│  Phase 3: Results Aggregation                                            │
+│     ├─ Export results.csv + review.json                                  │
+│     ├─ Generate context.md with all findings                             │
+│     ├─ Auto-create issues for qualifying findings                        │
+│     ├─ Update phase index.json with review status                        │
+│     └─ Display summary with verdict + next steps                         │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## CSV Schema
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave,status,findings,severity_counts,top_issues,error
+"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1","","","","",""
+"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1","","","","",""
+"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1","","","","",""
+"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2","","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier (string) |
+| `title` | Input | Short task title |
+| `description` | Input | Detailed review instructions for this dimension |
+| `dimension` | Input | Review dimension: correctness/security/performance/architecture/maintainability/best-practices/aggregation |
+| `changed_files` | Input | Semicolon-separated file paths to review |
+| `project_specs` | Input | Relevant project specs/conventions context |
+| `review_level` | Input | quick/standard/deep — controls depth |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `wave` | Computed | Wave number (1 = dimension review, 2 = aggregation) |
+| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
+| `findings` | Output | Key review findings summary (max 500 chars) |
+| `severity_counts` | Output | JSON: `{"critical":N,"high":N,"medium":N,"low":N}` |
+| `top_issues` | Output | Top 5 issues with `[severity] description (file:line)` format |
+| `error` | Output | Error message if failed |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates `wave-{N}.csv` with extra `prev_context` column.
+
+---
+
+## Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `results.csv` | Final export of all task results | Created in Phase 3 |
+| `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
+| `context.md` | Human-readable review report | Created in Phase 3 |
+| `review.json` | Structured review output for downstream | Created in Phase 3 |
+
+---
+
+## Session Structure
+
+```
+.workflow/.csv-wave/review-{phase}-{date}/
+├── tasks.csv
+├── results.csv
+├── discoveries.ndjson
+├── context.md
+├── review.json
+└── wave-{N}.csv (temporary)
+```
+
+---
+
+## Implementation
+
+### Session Initialization
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse flags
+const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const continueMode = $ARGUMENTS.includes('--continue')
+const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
+const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 6
+
+// Parse review-specific flags
+const levelMatch = $ARGUMENTS.match(/--level\s+(quick|standard|deep)/)
+const dimsMatch = $ARGUMENTS.match(/--dimensions\s+([\w,]+)/)
+
+// Clean phase text
+const phaseArg = $ARGUMENTS
+  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--level\s+\w+|--dimensions\s+[\w,]+/g, '')
+  .trim()
+
+const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
+const sessionId = `review-phase${phaseArg}-${dateStr}`
+const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+
+Bash(`mkdir -p ${sessionFolder}`)
+```
+
+---
+
+### Phase 1: Phase Resolution → CSV
+
+**Objective**: Resolve phase, collect changed files, determine review level, generate tasks.csv.
+
+**Decomposition Rules**:
+
+1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+2. **File collection**: Read `.task/TASK-*.json` → collect all `files[].path` where action != "read"
+3. **Level detection**:
+
+| Condition | Level |
+|-----------|-------|
+| `--level` flag provided | Use explicit level |
+| ≤3 changed files | quick |
+| 4-19 changed files | standard |
+| ≥20 files OR phase marked critical | deep |
+
+4. **Dimension selection**:
+
+| Level | Dimensions |
+|-------|------------|
+| quick | correctness, security |
+| standard | correctness, security, performance, architecture, maintainability, best-practices |
+| deep | all 6 + forced deep-dive in aggregation |
+
+If `--dimensions` flag provided, override with explicit list.
+
+5. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
+
+6. **CSV generation**: One row per dimension + one aggregation row.
+
+**Wave computation**: Simple 2-wave — all dimension tasks = wave 1, aggregation = wave 2.
+
+**User validation**: Display task breakdown (skip if AUTO_YES).
+
+---
+
+### Phase 2: Wave Execution Engine
+
+**Objective**: Execute dimension reviews wave-by-wave via spawn_agents_on_csv.
+
+#### Wave 1: Dimension Reviews (Parallel)
+
+1. Read master `tasks.csv`
+2. Filter rows where `wave == 1` AND `status == pending`
+3. No prev_context needed (wave 1 has no predecessors)
+4. Write `wave-1.csv`
+5. Execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: buildReviewInstruction(sessionFolder),
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      status: { type: "string", enum: ["completed", "failed"] },
+      findings: { type: "string" },
+      severity_counts: { type: "string" },
+      top_issues: { type: "string" },
+      error: { type: "string" }
+    },
+    required: ["id", "status", "findings"]
+  }
+})
+```
+
+6. Read `wave-1-results.csv`, merge into master `tasks.csv`
+7. Delete `wave-1.csv`
+
+#### Wave 2: Aggregation + Deep-Dive
+
+1. Read master `tasks.csv`
+2. Filter rows where `wave == 2` AND `status == pending`
+3. Check deps — if all wave 1 tasks failed, skip aggregation
+4. Build `prev_context` from wave 1 findings:
+   ```
+   [Task 1: Correctness Review] Found 2 critical issues: null pointer in login handler...
+   [Task 2: Security Review] Found 1 high issue: SQL injection in query builder...
+   ...
+   ```
+5. Write `wave-2.csv` with `prev_context` column
+6. Execute `spawn_agents_on_csv` for aggregation agent
+7. Merge results into master `tasks.csv`
+8. Delete `wave-2.csv`
+
+---
+
+### Phase 3: Results Aggregation
+
+**Objective**: Generate final results and human-readable report.
+
+1. Read final master `tasks.csv`
+2. Export as `results.csv`
+3. Build `review.json`:
+
+```json
+{
+  "phase": "<phase>",
+  "level": "<level>",
+  "verdict": "PASS|WARN|BLOCK",
+  "severity_distribution": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+  "dimensions": [
+    { "dimension": "correctness", "status": "completed", "severity_counts": {...}, "top_issues": [...] }
+  ],
+  "deep_dive": { "performed": true/false, "iterations": N, "impact_analysis": "..." },
+  "issues_created": [],
+  "timestamp": "<ISO>"
+}
+```
+
+4. Generate `context.md`:
+
+```markdown
+# Code Review Report — Phase {phase}
+
+## Summary
+- Level: {level}
+- Files reviewed: {file_count}
+- Dimensions: {dimension_count}
+- Verdict: **{verdict}**
+
+## Severity Distribution
+| Severity | Count |
+|----------|-------|
+| Critical | {N} |
+| High     | {N} |
+| Medium   | {N} |
+| Low      | {N} |
+
+## Dimension Results
+### {dimension_name}
+{findings}
+
+**Top Issues:**
+{top_issues}
+
+## Deep-Dive Analysis
+{if performed: impact analysis results}
+
+## Issues Created
+{list of created issue IDs}
+```
+
+5. **Verdict determination**:
+
+| Condition | Verdict |
+|-----------|---------|
+| Any critical findings | BLOCK |
+| High findings > 3 | BLOCK |
+| Any high findings | WARN |
+| Medium findings > 5 | WARN |
+| Otherwise | PASS |
+
+6. **Issue creation**: Based on level thresholds:
+
+| Level | Create Issues For |
+|-------|------------------|
+| quick | critical only |
+| standard | critical + high |
+| deep | critical + high + medium |
+
+7. **Phase index update**: Update `.workflow/phases/{phase}/index.json` with review status.
+
+8. Display summary.
+
+---
+
+## Shared Discovery Board Protocol
+
+### Standard Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `code_pattern` | `data.name` | `{name, file, description}` | Reusable code pattern found |
+| `integration_point` | `data.file` | `{file, description, exports[]}` | Module connection point |
+| `convention` | singleton | `{naming, imports, formatting}` | Project code conventions |
+| `blocker` | `data.issue` | `{issue, severity, impact}` | Blocking issue found |
+| `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack info |
+
+### Domain Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `vulnerability` | `data.location` | `{location, type, severity, cwe}` | Security vulnerability |
+| `code_smell` | `data.location` | `{location, type, severity, description}` | Code quality issue |
+| `performance_hotspot` | `data.location` | `{location, type, impact}` | Performance issue |
+| `architecture_violation` | `data.location` | `{location, rule, description}` | Architecture rule violation |
+
+### Protocol
+
+1. **Read** `{session_folder}/discoveries.ndjson` before own review
+2. **Skip covered**: If discovery of same type + dedup key exists, skip
+3. **Write immediately**: Append findings as found
+4. **Append-only**: Never modify or delete
+5. **Deduplicate**: Check before writing
+
+```bash
+echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"src/auth/login.ts:42","type":"sql_injection","severity":"critical","cwe":"CWE-89"}}' >> {session_folder}/discoveries.ndjson
+```
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Phase directory not found | Abort with error: "Phase {N} not found" |
+| No task summaries found | Abort with error: "No execution results — run execute first" |
+| No changed files | Abort with error: "No changed files detected" |
+| Dimension agent timeout | Mark as failed, skip dependent aggregation if all failed |
+| Aggregation agent failed | Use wave 1 results directly, verdict based on raw counts |
+| CSV parse error | Validate format, show line number |
+| discoveries.ndjson corrupt | Ignore malformed lines |
+| Continue mode: no session found | List available sessions |
+
+---
+
+## Core Rules
+
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state
+4. **Context Propagation**: prev_context built from master CSV, not from memory
+5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
+6. **Skip on Failure**: If all dimension agents failed, skip aggregation
+7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+8. **DO NOT STOP**: Continuous execution until all waves complete

package/.codex/skills/quality-sync/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: maestro-sync
+description: Sync codebase docs after code changes -- traces git diff through component/feature/requirement layers
+argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Sync
+
+## Usage
+
+```bash
+$maestro-sync
+$maestro-sync "--since HEAD~5"
+$maestro-sync "--full"
+$maestro-sync "--dry-run"
+$maestro-sync "--since abc123 --dry-run"
+```
+
+**Flags**:
+- `--full` -- Complete resync of all tracked files (ignores git diff)
+- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
+- `--dry-run` -- Show what would be updated without writing
+
+---
+
+## Implementation
+
+### Step 1: Validate
+
+```bash
+test -d .workflow || exit 1  # E001: not initialized
+```
+
+### Step 2: Detect Changes
+
+If `--full`: skip diff, mark all tracked files as changed.
+
+Otherwise:
+1. Read last sync timestamp from `state.json` field `last_synced`
+2. If `--since` provided, use that as baseline
+3. Run `git diff --name-only {baseline} HEAD` to get changed files
+
+If no changes and not `--full`, report clean state (W001) and exit.
+
+### Step 3: Trace Impact Chain
+
+For each changed file, trace through `doc-index.json` impact layers:
+1. **File layer** -- Which doc entries reference this file directly
+2. **Component layer** -- Which components contain this file
+3. **Feature layer** -- Which features depend on affected components
+4. **Requirement layer** -- Which requirements trace to affected features
+
+Build the full set of affected documentation entries.
+
+### Step 4: Update Documentation
+
+If `--dry-run`: display affected entries and exit.
+
+For each affected entry:
+1. Re-read source files
+2. Regenerate the documentation section in `.workflow/codebase/`
+3. Update `doc-index.json` with new timestamp and content hash
+
+### Step 5: Update State
+
+Update `state.json`:
+- `last_synced: "{ISO timestamp}"`
+- `last_synced_commit: "{HEAD commit hash}"`
+
+Update affected `index.json` files in phase directories if task files were modified.
+
+Display summary:
+```
+=== SYNC COMPLETE ===
+Files changed: {N}
+Components affected: {C}
+Features affected: {F}
+Docs updated: {D}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
+| W001 | warning | No changes detected since last sync |