maestro-companion

<purpose>
Side-car utility for any task: load knowledge context (before), record structured entries (note),
promote insights to spec/knowhow (after), or route to next command (route).
</purpose>

<context>
$ARGUMENTS — mode + optional flags.

**Mode detection priority:**
1. Explicit `before` / `note` / `after` / `route`
2. Intent text that is not a mode keyword → `route`
3. No arguments → auto-detect (`git status` has changes → `after`, else → `before`)

**Flags:**
- `--task <description>` — Current task description (for targeted knowledge loading and doc title)
- `--type <task_type>` — Task type for field template selection (see task types below)
- `--category <cat>` — Spec category filter: coding / arch / test / review / debug / learning / ui

**Task types** (determines which recording sections are active):

| Type | Description | Key sections |
|------|-------------|--------------|
| `implement` | Feature development, code writing | working_files, dependencies, decisions, tests_affected |
| `debug` | Bug investigation, root cause analysis | symptoms, hypotheses, evidence, root_cause, fix_applied |
| `analyze` | Code/architecture/performance analysis | scope, findings, risks, recommendations |
| `design` | Architecture/UI/API design | constraints, alternatives, trade_offs, chosen_approach |
| `plan` | Task decomposition, roadmap planning | goals, breakdown, estimates, dependencies |
| `review` | Code review, PR review | files_reviewed, findings, severity_counts, verdict |
| `test` | Test writing, UAT, coverage expansion | coverage_before, coverage_after, gaps, test_files |
| `refactor` | Code restructuring, tech debt | affected_modules, before_after, breaking_changes |
| `learn` | Codebase exploration, knowledge building | questions, answers, mental_model, references |
| `general` | Default / unclassified | (all universal sections) |

Auto-detection: if `--type` not provided, infer from `--task` description keywords.

**Companion document:**
- Path: `.workflow/.scratchpad/companion-{YYYYMMDD-HHmmss}.md`
- Active doc tracking: `.workflow/.scratchpad/.companion-active` (stores path of current companion doc)
- Format: YAML frontmatter (rich metadata) + typed sections + timestamped entries
</context>

<state_machine>

<states>
S_PARSE    — Parse arguments, detect mode, resolve task type
S_BEFORE   — Load knowledge context, create companion doc with typed template
S_NOTE     — Append structured entry to active companion doc
S_AFTER    — Review companion doc, populate outcome, promote entries, suggest next steps
S_ROUTE    — Skill routing via maestro-next
</states>

<transitions>

S_PARSE:
  → S_BEFORE   WHEN: mode == "before" OR (no args AND no uncommitted changes)
  → S_NOTE     WHEN: mode == "note"
  → S_AFTER    WHEN: mode == "after" OR (no args AND has uncommitted changes)
  → S_ROUTE    WHEN: mode == "route" OR intent text present

</transitions>

</state_machine>

<execution>

## S_BEFORE — Knowledge Loading + Companion Doc Creation

Execute in order, skip unavailable steps:

### 1. Load specs

```bash
# With --category: load by category
maestro load --type spec --category <cat>

# With --task: load by keyword extracted from task description
maestro load --type spec --keyword <extracted_keyword>

# No flags: load coding (most universal)
maestro load --type spec --category coding
```

Display loaded rules summary (entry count + key rule names).

### 2. Browse knowhow index

```bash
# List recent knowhow entries
maestro knowhow list --store workflow

# With --task: search relevant entries
maestro search --type knowhow "<task_keyword>"
```

Display available knowhow entries (ID + title). Hint: `maestro load --type knowhow --id <id>` for details.

### 3. Check codebase index

```bash
ls .workflow/codebase/doc-index.json
```

- Exists → display "Codebase docs ready, last updated: {timestamp}"
- Missing → suggest `/manage-codebase-rebuild`
- Stale (>7 days) → suggest `/quality-sync`

### 4. Create companion document

Create `.workflow/.scratchpad/` if needed. Resolve task type from `--type` flag or infer from `--task` keywords.

Write companion doc with the full field template:

```markdown
---
# === Identity ===
task: "{task_description or 'Untitled task'}"
task_type: "{resolved type: implement|debug|analyze|design|plan|review|test|refactor|learn|general}"
created: "{ISO timestamp}"
status: active

# === Context Loaded ===
specs_loaded: "{category or 'coding'}"
specs_count: {N}
knowhow_searched: "{keyword or 'none'}"
knowhow_available: {M}
codebase_index: "{ready|missing|stale}"
branch: "{current git branch}"
phase: "{current phase from state.json or 'none'}"
milestone: "{current milestone from state.json or 'none'}"

# === Scope ===
working_files: []
dependencies: []
related_artifacts: []

# === Outcome (populated by after mode) ===
outcome: ""
files_changed: []
promoted_specs: 0
promoted_knowhow: 0
follow_up: []
completed: ""
---

# Companion Doc — {task_description}

> `/maestro-companion note "<content>"` — add entries
> `/maestro-companion after` — review, promote, close

## Context

{Type-specific context section — see templates below}

## Entries

## Summary
```

**Type-specific context templates** (written into `## Context`):

**implement:**
```markdown
### Working Files
| File | Role | Status |
|------|------|--------|

### Dependencies
- (modules, APIs, or services this task depends on)

### Decisions
| # | Decision | Rationale | Alternatives Considered |
|---|----------|-----------|------------------------|

### Tests Affected
- (test files that need creation or update)
```

**debug:**
```markdown
### Symptoms
- (observable behavior vs expected behavior)

### Hypotheses
| # | Hypothesis | Status | Evidence |
|---|-----------|--------|----------|

### Evidence Trail
| Time | Source | Type | Finding |
|------|--------|------|---------|

### Root Cause
- (populated when identified)

### Fix Applied
- (description of fix, files changed)
```

**analyze:**
```markdown
### Scope
- (wh