maestro-flow 0.1.0

package/.codex/skills/maestro-plan/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: maestro-plan
+description: Exploration-driven planning via CSV wave pipeline. Wave 1 runs parallel codebase exploration agents, Wave 2 synthesizes explorations into plan.json + TASK-*.json. Replaces maestro-plan command.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--auto] [--dir <path>] [--gaps] [--spec SPEC-xxx] [--collab]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm exploration angles, skip interactive clarification (P2), use defaults for complexity detection.
+
+# Maestro Plan (CSV Wave)
+
+## Usage
+
+```bash
+$maestro-plan "3"
+$maestro-plan -y "3 --auto"
+$maestro-plan -c 4 "3 --spec SPEC-001"
+$maestro-plan "3 --gaps"
+$maestro-plan "3 --dir .workflow/scratch/quick-nav-fix"
+$maestro-plan --continue "plan-phase3-20260318"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4)
+- `--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) + `plan.json` + `.task/TASK-*.json`
+
+---
+
+## Overview
+
+Wave-based planning using `spawn_agents_on_csv`. Wave 1 explores codebase context in parallel across multiple angles, Wave 2 consumes all exploration findings to generate a verified execution plan.
+
+**Core workflow**: Resolve Phase -> Determine Explorations -> Parallel Exploration -> Sequential Planning -> Check + Confirm
+
+```
++---------------------------------------------------------------------------+
+|                    PLAN CSV WAVE WORKFLOW                                  |
++---------------------------------------------------------------------------+
+|                                                                           |
+|  Phase 1: Phase Resolution -> CSV                                         |
+|     +-- Resolve phase directory from arguments (or --dir)                 |
+|     +-- Load context.md, index.json, spec-ref, codebase docs             |
+|     +-- Check for upstream analysis (conclusions.json)                    |
+|     +-- If --gaps: load gaps from issues/verification/uat                 |
+|     +-- Determine exploration angles (architecture, implementation, etc.) |
+|     +-- Generate tasks.csv with one row per exploration + planning row    |
+|     +-- User validates exploration breakdown (skip if -y)                 |
+|                                                                           |
+|  Phase 2: Wave Execution Engine                                           |
+|     +-- Wave 1: Codebase Exploration (parallel)                           |
+|     |   +-- Each agent explores one angle of the codebase                 |
+|     |   +-- Agent reads files, discovers patterns, maps dependencies      |
+|     |   +-- Discoveries shared via board (patterns, conventions, risks)   |
+|     |   +-- Results: findings per exploration angle                       |
+|     +-- Wave 2: Plan Generation (sequential)                              |
+|     |   +-- Single planning agent consumes all exploration findings       |
+|     |   +-- Generates plan.json with waves, dependencies, estimates       |
+|     |   +-- Generates .task/TASK-*.json for each task                     |
+|     |   +-- Applies Deep Work Rules (read_first, convergence.criteria)    |
+|     |   +-- Results: plan.json path + task count                          |
+|     +-- discoveries.ndjson shared across all waves (append-only)          |
+|                                                                           |
+|  Phase 3: Plan Checking + Confirmation                                    |
+|     +-- Validate plan quality (coverage, feasibility, deps, criteria)     |
+|     +-- Revision loop (max 3 rounds) if critical issues found             |
+|     +-- Update index.json with plan metadata                              |
+|     +-- Display plan summary + options (execute/modify/view)              |
+|                                                                           |
++---------------------------------------------------------------------------+
+```
+
+---
+
+## CSV Schema
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,exploration_focus,deps,context_from,wave,status,findings,error
+"E1","Architecture Exploration","Explore how the target feature fits into existing architecture. Map module boundaries, dependency graph, and integration points. Identify existing patterns that should be followed.","architecture","","","1","","",""
+"E2","Implementation Exploration","Explore implementation patterns: libraries in use, coding conventions, error handling patterns, type definitions. Find 3+ similar features as reference.","implementation","","","1","","",""
+"E3","Integration Exploration","Explore integration points: what existing code needs modification, API contracts, shared state, event flows. Map all touch points.","integration","","","1","","",""
+"E4","Risk Exploration","Explore risks: what could go wrong, backward compatibility concerns, performance implications, security surface changes, test coverage gaps.","risk","","","1","","",""
+"P1","Plan Generation","Consume all exploration findings. Decompose phase goal into concrete tasks with waves, dependencies, convergence criteria. Generate plan.json + TASK-*.json files following Deep Work Rules.","planning","E1;E2;E3;E4","E1;E2;E3;E4","2","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier: `E{N}` for explorations (wave 1), `P1` for planning (wave 2) |
+| `title` | Input | Short exploration or planning title |
+| `description` | Input | Detailed exploration/planning instructions |
+| `exploration_focus` | Input | Focus area: architecture/implementation/integration/risk/planning |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `wave` | Computed | Wave number (1 = exploration, 2 = plan generation) |
+| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
+| `findings` | Output | Key findings summary (max 500 chars) |
+| `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 planning report | Created in Phase 3 |
+| `plan.json` | Execution plan (in phase directory) | Created by wave 2 agent |
+| `.task/TASK-*.json` | Individual task definitions (in phase directory) | Created by wave 2 agent |
+
+---
+
+## Session Structure
+
+```
+.workflow/.csv-wave/plan-{phase}-{date}/
++-- tasks.csv
++-- results.csv
++-- discoveries.ndjson
++-- context.md
++-- 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]) : 4
+
+// Parse plan-specific flags
+const autoMode = $ARGUMENTS.includes('--auto')
+const gapsMode = $ARGUMENTS.includes('--gaps')
+const dirMatch = $ARGUMENTS.match(/--dir\s+(\S+)/)
+const specMatch = $ARGUMENTS.match(/--spec\s+(SPEC-\S+)/)
+const collabMode = $ARGUMENTS.includes('--collab')
+
+// Clean phase text
+const phaseArg = $ARGUMENTS
+  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--auto|--gaps|--parallel|--collab|--dir\s+\S+|--spec\s+\S+/g, '')
+  .trim()
+
+const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
+const sessionId = dirMatch
+  ? `plan-${dirMatch[1].split('/').pop()}-${dateStr}`
+  : `plan-phase${phaseArg}-${dateStr}`
+const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+
+Bash(`mkdir -p ${sessionFolder}`)
+```
+
+---
+
+### Phase 1: Phase Resolution -> CSV
+
+**Objective**: Resolve phase, load context, determine exploration angles, generate tasks.csv.
+
+**Decomposition Rules**:
+
+1. **Phase resolution**:
+
+| Condition | Action |
+|-----------|--------|
+| `--dir <path>` provided | Use path directly, set SCRATCH_MODE = true |
+| Number argument | Resolve `.workflow/phases/{NN}-*/` |
+| Slug argument | Resolve `.workflow/phases/*-{slug}/` |
+
+2. **Context loading**:
+   - Read `{PHASE_DIR}/context.md` (user decisions from analyze)
+   - Read `{PHASE_DIR}/index.json` (phase metadata, success criteria)
+   - Read spec-ref if `--spec` flag or index.json has spec_ref
+   - Read `.workflow/codebase/doc-index.json` if exists
+   - Read `{PHASE_DIR}/design-ref/MASTER.md` if exists (UI design reference)
+   - Load project specs via `maestro spec load --category planning`
+
+3. **Upstream analysis check**:
+   - If `{PHASE_DIR}/conclusions.json` exists and has content: reuse as exploration context, skip wave 1
+   - If `{PHASE_DIR}/explorations.json` exists: load as additional context
+
+4. **Gap mode** (if `--gaps`):
+   - Load gaps from `.workflow/issues/issues.jsonl` (primary), `verification.json` (fallback), `uat.md` (additional)
+   - Enrich with debug diagnosis from `{PHASE_DIR}/.debug/*/understanding.md`
+   - Skip wave 1 exploration, generate gap-fix tasks directly in wave 2
+
+5. **Exploration angle determination** (skip if --gaps or upstream analysis loaded):
+
+| Angle | Focus | When Included |
+|-------|-------|---------------|
+| architecture | Module boundaries, dependency graph, integration points | Always |
+| implementation | Coding patterns, libraries, conventions, similar features | Always |
+| integration | Existing code modifications, API contracts, shared state | When phase touches existing modules |
+| risk | Backward compatibility, performance, security, test gaps | When phase is complex or critical |
+
+6. **CSV generation**: Exploration rows (wave 1) + one planning row (wave 2).
+
+**Wave computation**: Simple 2-wave -- all exploration tasks = wave 1, planning task = wave 2.
+
+**User validation**: Display exploration breakdown (skip if AUTO_YES or `--auto`).
+
+---
+
+### Phase 2: Wave Execution Engine
+
+**Objective**: Explore codebase then generate plan via spawn_agents_on_csv.
+
+#### Wave 1: Codebase Exploration (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: buildExplorationInstruction(sessionFolder, phaseDir),
+  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" },
+      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: Plan Generation (Sequential)
+
+1. Read master `tasks.csv`
+2. Filter rows where `wave == 2` AND `status == pending`
+3. Build `prev_context` from wave 1 findings:
+   ```
+   [E1: Architecture Exploration] Module boundaries: auth/ is self-contained, shared/ has...
+   [E2: Implementation Exploration] Patterns found: Result type for errors, zod for validation...
+   [E3: Integration Exploration] Touch points: routes/index.ts needs new route, middleware/auth.ts...
+   [E4: Risk Exploration] Risks: No test coverage for auth refresh flow, potential breaking change...
+   ```
+4. Write `wave-2.csv` with `prev_context` column
+5. Execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-2.csv`,
+  id_column: "id",
+  instruction: buildPlanningInstruction(sessionFolder, phaseDir, {
+    contextMd, indexJson, specRef, docIndex, designRef, gapsContext
+  }),
+  max_concurrency: 1,  // Sequential — single planning agent
+  max_runtime_seconds: 900,
+  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
+  output_schema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      status: { type: "string", enum: ["completed", "failed"] },
+      findings: { type: "string" },
+      error: { type: "string" }
+    },
+    required: ["id", "status", "findings"]
+  }
+})
+```
+
+6. Merge results into master `tasks.csv`
+7. Delete `wave-2.csv`
+
+**Planning agent responsibilities** (embedded in instruction):
+- Decompose phase goal into concrete tasks (TASK-001, TASK-002, ...)
+- Determine dependencies and group into execution waves
+- Apply Deep Work Rules:
+  - Every task has `read_first[]` with file being modified + source of truth files
+  - Every task has `convergence.criteria[]` with grep-verifiable conditions
+  - Every `action` has concrete values (never "align X with Y")
+  - Every `implementation` step has specific values
+- Write `plan.json` to `{PHASE_DIR}/plan.json`
+- Write `.task/TASK-{NNN}.json` files to `{PHASE_DIR}/.task/`
+- If `--gaps`: create fix tasks from gap context, link to issues
+- If `--collab`: pre-allocate ID ranges for parallel planners
+
+---
+
+### Phase 3: Plan Checking + Confirmation
+
+**Objective**: Validate plan quality, revise if needed, present to user.
+
+1. **Plan checking** (inline, not a separate wave):
+   - Read generated `plan.json` + all `.task/TASK-*.json`
+   - Validate dimensions:
+
+| Check | Criteria |
+|-------|----------|
+| Requirements coverage | Every success_criterion maps to at least one task |
+| Feasibility | Referenced files exist or can be created |
+| Dependency correctness | No circular deps, deps exist, wave ordering valid |
+| Convergence criteria quality | Grep-verifiable, no subjective language |
+| read_first completeness | Every task has read_first[] with modified file |
+| Action concreteness | No vague "align X with Y" |
+| Wave structure | Parallel tasks have no conflicting file modifications |
+
+2. **Revision loop** (max 3 rounds): If critical issues found, regenerate affected tasks.
+
+3. **Export results**:
+   - Export `results.csv` from master `tasks.csv`
+   - Generate `context.md`:
+
+```markdown
+# Plan Report -- Phase {phase}
+
+## Summary
+- Phase: {phase_name}
+- Tasks: {task_count} in {wave_count} waves
+- Complexity: {complexity}
+- Explorations: {exploration_count} angles explored
+
+## Exploration Findings
+
+### {angle}: {title}
+{findings}
+
+## Plan Overview
+- Approach: {plan.approach}
+- Task IDs: {task_ids}
+- Waves: {wave_structure}
+
+## Next Steps
+{suggested actions}
+```
+
+4. **Update index.json**:
+   ```json
+   {
+     "status": "planning",
+     "plan": {
+       "task_ids": ["TASK-001", "TASK-002"],
+       "task_count": N,
+       "complexity": "moderate",
+       "waves": [[...], [...]]
+     },
+     "updated_at": "<ISO>"
+   }
+   ```
+
+5. **Issue linking** (if --gaps): Update issues in `issues.jsonl` with status `planned`, link to TASK IDs.
+
+6. **Display summary + options** (skip options if AUTO_YES):
+   ```
+   === PLAN READY ===
+   Phase: {phase_name}
+   Tasks: {task_count} tasks in {wave_count} waves
+   Check: {checker_status}
+
+   Plan: {phase_dir}/plan.json
+   Tasks: {phase_dir}/.task/TASK-*.json
+
+   Next steps:
+     Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
+     Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
+   ```
+
+---
+
+## 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 |
+|------|-----------|-------------|-------------|
+| `existing_pattern` | `data.name` | `{name, file, description, usage}` | Existing feature pattern to follow |
+| `dependency_map` | `data.module` | `{module, imports[], exports[], dependents[]}` | Module dependency mapping |
+| `risk_factor` | `data.risk` | `{risk, severity, mitigation, affected_files[]}` | Identified risk |
+| `test_command` | `data.command` | `{command, scope, framework}` | Test execution command |
+
+### Protocol
+
+1. **Read** `{session_folder}/discoveries.ndjson` before own exploration
+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":"existing_pattern","data":{"name":"Result error handling","file":"src/utils/result.ts","description":"All functions return Result<T,E> instead of throwing","usage":"Used in auth, payments, validation modules"}}' >> {session_folder}/discoveries.ndjson
+```
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Phase argument required | Abort with error: "Phase argument required" |
+| Phase directory not found | Abort with error: "Phase {N} not found. Run init first." |
+| --gaps requires gaps source | Abort with error: "--gaps requires issues.jsonl, verification.json, or uat.md" |
+| No context.md found | Warn, proceed with exploration only |
+| Exploration agent timeout | Mark as failed, continue with available explorations |
+| Planning agent fails | Retry once with simplified context, then abort |
+| Plan produces invalid JSON | Retry once, then abort with error details |
+| Plan-checker exceeds 3 rounds | Accept plan with warnings, note in index.json |
+| 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 exploration agents failed, planning agent proceeds with available context
+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/maestro-quick/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: maestro-quick
+description: Fast-track single task execution with workflow guarantees — analyze, plan, execute in one pass
+argument-hint: "\"task description\" [--discuss] [--full]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+## Auto Mode
+
+Quick tasks default to minimal interaction. `--discuss` adds a decision extraction step. `--full` adds plan-checking and post-execution verification.
+
+# Maestro Quick (Single Agent)
+
+## Usage
+
+```bash
+$maestro-quick "add rate limiting to /api/auth endpoints"
+$maestro-quick "refactor user service to use repository pattern" --discuss
+$maestro-quick "fix memory leak in WebSocket handler" --full
+$maestro-quick "add dark mode toggle to settings page" --discuss --full
+```
+
+**Flags**:
+- `--discuss`: Decision extraction before planning (Locked/Free/Deferred classification)
+- `--full`: Enable plan-checking (max 2 iterations) and post-execution verification
+
+**Output**: `.workflow/scratch/{slug}/` with plan.json, execution results, optional verification
+
+---
+
+## Overview
+
+Shortened pipeline for well-understood tasks. Creates a scratch directory, runs quick analysis, generates a plan, executes tasks, and optionally verifies results. Single agent, sequential flow — no CSV waves needed.
+
+**Pipeline**: `[discuss] → analyze-q → plan → execute → [verify]`
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract from arguments:
+- `--discuss` flag
+- `--full` flag
+- Remaining text as task description (required — E001 if empty)
+
+### Step 2: Load Project Context
+
+```bash
+cat .workflow/state.json 2>/dev/null
+cat .workflow/project.md 2>/dev/null
+```
+
+If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
+
+### Step 3: Create Scratch Directory
+
+Generate slug from task description (lowercase, hyphens, max 40 chars).
+
+```bash
+mkdir -p .workflow/scratch/{slug}
+```
+
+Write `config.json` with task metadata:
+```json
+{
+  "task": "<description>",
+  "flags": { "discuss": false, "full": false },
+  "created_at": "<ISO timestamp>",
+  "status": "active"
+}
+```
+
+### Step 4: Discussion Phase (if --discuss)
+
+**Only when `--discuss` is set.**
+
+Analyze the task for gray areas and ambiguities:
+1. Identify decision points in the task
+2. Classify each as: **Locked** (clear from context), **Free** (implementation choice), **Deferred** (need user input)
+3. For Deferred items: ask user for decisions
+4. Write `context.md` to scratch directory with all decisions
+
+### Step 5: Quick Analysis
+
+Rapid codebase exploration focused on the task:
+1. Search for related files using Grep/Glob
+2. Identify existing patterns to follow
+3. Map dependencies and integration points
+4. Write analysis findings to `context.md` (append if --discuss created it)
+
+### Step 6: Generate Plan
+
+Create `plan.json` in scratch directory:
+- Decompose task into subtasks (typically 1-5 for quick tasks)
+- Each task has: id, title, description, scope, convergence_criteria, files
+- Assign single wave (sequential execution)
+
+**If `--full`**: Present plan for review, allow up to 2 revision iterations.
+
+### Step 7: Execute Tasks
+
+For each task in plan.json (sequential):
+1. Read task definition
+2. Implement changes following existing patterns
+3. Run any specified verification commands
+4. Write task summary with files_modified, status
+
+Update plan.json task statuses as completed.
+
+### Step 8: Verification (if --full)
+
+**Only when `--full` is set.**
+
+Run convergence criteria checks:
+```bash
+# For each task, verify convergence_criteria via grep/test commands
+```
+
+If gaps found (W001): attempt single fix iteration, then report remaining gaps.
+
+### Step 9: Commit and Report
+
+```bash
+git add -A
+git commit -m "quick: {slug} - {short description}"
+```
+
+Update `.workflow/state.json` scratch task entry (if state.json exists).
+
+```
+=== QUICK TASK COMPLETE ===
+Task:    {description}
+Scratch: .workflow/scratch/{slug}/
+Status:  {completed|completed-with-gaps}
+
+Tasks: {completed}/{total}
+Files modified: {count}
+
+{if --full}
+Verification: {PASS|GAPS}
+{endif}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Task description required | Ask user for description |
+| E002 | error | Scratch directory creation failed | Check permissions |
+| W001 | warning | Verification found minor gaps | Report gaps, continue |
+
+---
+
+## Core Rules
+
+1. **Speed over ceremony** — minimal overhead, get to implementation fast
+2. **Follow existing patterns** — grep for 3+ similar implementations before writing new code
+3. **Atomic commits** — one commit per quick task, descriptive message
+4. **Scratch isolation** — all metadata stays in .workflow/scratch/{slug}/
+5. **Works without init** — quick tasks function even without full .workflow/ setup