Plan 3: Job & phase scaffold + KB foundation

[Ryfter]

Summary

Plan 3 of the coding-agent-orchestrator vision. Adds a persistent job lifecycle with phase tracking, lesson capture, a two-layer knowledge base, and a read-only Jobs panel on the Plan 2 dashboard. Foundation only — no multi-model dispatch yet (that's Plan 4+).

• 7 new slash commands: /job-start, /job-status, /job-list, /job-phase, /job-resume, /job-lesson, /consolidate-lessons
• Hook + OTel parser now tag every journal line with job: + phase: when a job is active (backward-compatible — Plan 1/2 lines still parse and still emit untagged when no job is active)
• New ~/.claude/jobs/<id>/ and ~/.claude/knowledge/{universal,projects/<id>}/ directory structure
• Plan 1's model-routing.md migrated into knowledge/universal/routing.md
• Dashboard: new Jobs panel + drill-in route /jobs/<id> with per-phase cost breakdown
• 21 commits, 5 PS1 test suites + 56 pytest tests all green

What this branch contains

Layer	What changed
PowerShell	New scripts/job-lib.ps1 (shared lib), new scripts/consolidate-lessons.ps1, extensions to scripts/hooks/log-tool-call.ps1, scripts/parse-otel.ps1, scripts/bootstrap.ps1
Slash commands	7 new .md files under commands/
Python (dashboard)	New dashboard/readers/jobs.py, dashboard/routers/jobs.py, two new templates, extensions to dashboard/readers/journal.py, dashboard/models/events.py, dashboard/main.py, CSS additions
Docs	Design spec, implementation plan, handoff notes
Tests	23 new PS1 assertions across 3 test scripts; 13 new pytest cases across 4 test files

Architectural decisions (and why)

• Approach C (Claude Code IS the orchestrator, job files are persistence) was chosen over Approach A (slash-commands only, no persistence) and Approach B (Python state-machine daemon). B was rejected as overengineered duplication of what Claude Code already does well. Job files are designed so a daemon could pick them up later if needed.
• State file at `~/.claude/current-job.json` instead of session env vars — slash-command subprocesses cannot mutate the parent process's env, so a file is the only reliable cross-process signal.
• Four phases (`research`, `design`, `code.sprint-N`, `review`) instead of seven. An earlier seven-phase model (brainstorm.brain-dump → refine → research → alternatives → sanity-check → design → design-check) was rejected as too granular. Inner activities live INSIDE phases as dispatch patterns; analytics granularity at four phases is sufficient.
• Two-layer knowledge base (universal + per-project) requested explicitly by Kevin. Per-project KB is identified by git-remote slug, with a cwd-folder fallback.
• CLI-first fleet philosophy (deferred to Plan 4): we wrap CLIs (claude, codex, antigravity, gh copilot, opencode, ollama) rather than direct APIs. APIs may be added in Plan 4 as fleet expansions.
• Backward compatibility is non-negotiable. Existing Plan 1/2 journal lines still parse correctly. The hook still works when no job is active. All Plan 2 dashboard tests still pass.

What's deliberately deferred

Capability	Lands in
Fleet config + multi-machine local Ollama	Plan 4
Research ensemble + 6-Hats / LLM Council primitives	Plan 5
Decompose + parallel-worktree code phase	Plan 6
Claude + Codex pair review on diff	Plan 7
Cockpit interactivity (new-job form, phase buttons, minimizable cards, drill-into-live-commands)	Plan 7
End-of-job analytics debrief (token-by-phase, model breakdown)	Plan 7
Embedding-based KB retrieval, auto-injection at job/phase start	Plan 8
Two concurrent jobs in one Claude Code session	future (v1 limitation, single state file = single active job)

Known follow-ups (not blocking)

• `dashboard/templates/job_detail.html` uses a JS `setTimeout(location.reload, 30000)` for drill-in polling. Plan 7 will replace with proper htmx-partial polling on a 5s/30s split.
• Brief renders as `

  `, not Markdown. Plan 7 enhancement.

• `'abandoned'` job status is in the manifest schema but no command sets it. Plan 7.
• `parse-otel.ps1` and `/consolidate-routing` still default to the old `~/.claude/model-routing.md` path (which is renamed to `.migrated` by bootstrap). Cosmetic — both still work post-migration.

Test plan

Run all tests after merging:

```powershell
pwsh -NoProfile -File scripts/test-job-lib.ps1
pwsh -NoProfile -File scripts/test-jobs.ps1
pwsh -NoProfile -File scripts/test-hook.ps1
pwsh -NoProfile -File scripts/test-otel-parser.ps1
pwsh -NoProfile -File scripts/test-consolidate-lessons.ps1
python -m pytest dashboard/tests/ -v
```

All should be green (verified on the branch).

Manual smoke (from a Claude Code session in the repo):

• `/job-start "smoke test plan 3"` creates the job folder + state file
• Any subsequent tool call appears in `~/.claude/model-routing-log.md` with `| job:j-… | phase:research` trailing tags
• Dashboard Jobs panel shows the new job within 30s
• Drill-in view at `/jobs/` renders brief, phase timeline, cost, lessons
• `/job-lesson knowledge "smoke test note"` appears in drill-in
• `/job-phase next` flips to `design` atomically (manifest + state + phase-log)
• `/job-phase done` clears state file
• `/consolidate-lessons` writes the lesson to `~/.claude/knowledge/projects/coding-agent-orchestrator/topics/general.md`

Documents to read for context

1. `docs/superpowers/specs/2026-05-26-plan3-job-scaffold-design.md` — full design with rationale
2. `docs/superpowers/plans/2026-05-26-plan3-job-scaffold.md` — 19-task implementation plan
3. `docs/superpowers/notes/plan3-handoff.md` — start here if you're picking this up cold — 30-second picture, key contracts, decisions, what's deferred, how to verify, hints for Plan 4

Bootstrap migration note

Existing Plan 1/2 users: running `scripts/bootstrap.ps1` after this merges will migrate `/.claude/model-routing.md` into `/.claude/knowledge/universal/routing.md` and leave a `.migrated` sentinel so re-runs are idempotent. The deploy of new slash commands + lib scripts is also idempotent. Safe to re-run.

🤖 Generated with Claude Code

[Ryfter]

Execution log

For the record of how this branch was built (relevant if you're auditing the process, not just the result):

Process

1. Brainstorming (superpowers:brainstorming skill) — 8 clarifying-question exchanges over architecture, phase model, KB layout, lesson taxonomy.
2. Spec written to docs/superpowers/specs/2026-05-26-plan3-job-scaffold-design.md and committed (503 lines).
3. Plan written (superpowers:writing-plans skill) to docs/superpowers/plans/2026-05-26-plan3-job-scaffold.md — 19 bite-sized tasks, ~3,200 lines, with exact code per step.
4. Execution (superpowers:subagent-driven-development skill, sonnet for all subagents): 19 sequential implementer subagents on this branch, each producing a focused commit. Tasks 12+13 deliberately ship in a chained pair (Task 12's imports fail until Task 13 adds LessonEntry).
5. Review streamlining: Task 1 went through the full implementer → spec-reviewer → code-quality-reviewer flow (caught 2 Important + 1 Minor; fixed inline). For subsequent tasks I dropped per-task spec + code reviewers and did one comprehensive final review at the end (sonnet, ~76 tool uses) given the plan's prescriptiveness. The final reviewer caught 2 Important + 6 Minor cross-cutting issues; the Important ones plus one Minor were fixed in a follow-up commit (6a0f9f5).

What the final review caught

• Important — bootstrap migration idempotency: Step 6's Copy-WithPrompt was resurrecting ~/.claude/model-routing.md after Step 5d's migration moved it. Fix: skip Step 6 when the .migrated sentinel exists.
• Important — /job-lesson --scope was parsed but ignored: scope wasn't persisted in lessons.md, so /consolidate-lessons always re-derived it from the category default. Fix: extended lessons.md line format from ts | cat | "text" to ts | cat | scope | "text"; consolidator + dashboard reader tolerate both formats for backward compat.
• Minor — drill-in view had no auto-refresh: added a JS setTimeout(location.reload, 30000). Plan 7 will replace with proper htmx polling.

Five Minor issues were accepted as known-deferred: brief rendered as <pre> not Markdown (Plan 7), 'abandoned' status unused (Plan 7), ConvertTo-JobSlug uses 5 tokens not 4 (deliberate — plan's own test cases required 5), test-jobs.ps1 done-transition cosmetic (done → done in phase-log), parse-otel.ps1//consolidate-routing still default to legacy model-routing.md path (cosmetic — migration sentinel handles it).

TDD discipline

Every task followed red → green → commit:

1. Write failing test
2. Run, confirm failure with predicted error message
3. Implement minimal code
4. Run, confirm pass
5. Commit

This is reflected in the linear commit history — 19 implementation commits (one per plan task) + 1 quality-fix commit on Task 1 + 1 post-review-fix commit + 1 README commit + 1 handoff-doc commit = 21 commits total.

Documentation chain (for cold pickup)

README.md → docs/superpowers/specs/2026-05-26-plan3-job-scaffold-design.md (full design with rationale) → docs/superpowers/plans/2026-05-26-plan3-job-scaffold.md (19-task plan with exact code) → docs/superpowers/notes/plan3-handoff.md (30-second orientation + key contracts + Plan 4 starter hints).

Plan 4 (fleet config + multi-machine Ollama) is the next slice and unblocks the actual multi-model dispatch in Plans 5-7.