2026-05-27 · Locked design

V2 Claude-Code-Style Redesign

Consolidated architecture spec. 44 numbered decisions across 12 sections. Captures the 2026-05-27 grilling-session conversation that re-baselined V2 against the collapsed architecture and Karpathy's LLM Wiki pattern.

claude/coe-filesystem-backbone-TYD7Tdocs/superpowers/specs/2026-05-27-v2-claude-code-style-redesign.md

§ 1 · The redesign in one paragraph

V2 is the next-generation migration from collapsed, not from V1-original. The shape, milestones, gates, state machine, and review UX are already locked in 08-milestone-architecture.md. What V2 changes is the substrate: collapsed's brittle JSONB tables are replaced with markdown files in a per-course git repo, stored in Supabase Storage. Specialized agent TypeScript classes are replaced with one Task primitive + N markdown prompts (the Claude-Code-style harness). The Knowledge Base becomes a per-teacher LLM Wiki (Karpathy 2026-04-04) that compounds across courses. V2 has since cut over on the default branch; this page preserves the historical design rationale behind that migration.

§ 2 · Why this redesign

Force A

Pre-grilling spec mistook the baseline

Conflated V1-original (42 agents, 12 HITL) with Collapsed (8 agents). Then overshot the simplification by deleting the Evaluator in commit 0e0703d on the rationale that “Claude Code uses one LLM”. Both wrong.

Force B

JSONB substrate breaks continuously

Operator-confirmed pain: workflow_node_states + spec_files coordination breaks too often. Schema drift, opaque diffs, RLS complexity, debugging difficulty. Filesystem substrate eliminates these by construction.

Force C

Locked milestone architecture supplies the shape

08-milestone-architecture.md already defines milestones, gates, lifecycle, and 3-zone UI. V2's job is to implement that shape on a new substrate — not redesign it.

§ 3 · Decisions locked (44 total, cross-referenced D1–D44)

§ 3.1Substrate & storage

5 decisions

V2 baselines on collapsed (not V1-original). Collapsed's 8-agent contract is what V2 reimplements.

Git-as-substrate. Every workspace is a real git repo. Commits encode every action; git log is the audit trail.

Workspace location: Supabase Storage. Per-teacher bucket; per-course repo as a directory. No external git hosting.

Workspace identity: per-course repo, multi-repo dashboard per teacher. New course = new git repo.

Pure-workspace projection. During pre-publish, all state lives in workspace markdown + git. Supabase only stores published rows.

§ 3.2Milestone shape

5 decisions

5 milestones: M1 Strategy/Outline → M2 Structure → M3 Skeleton → M4 Substance → Publish. Matches 08-milestone-architecture.md.

Per-artifact finalize within milestone; strict gate between milestones (modulo parent-gated cascade).

4-state lifecycle: draft → approved → finalized → published. State in frontmatter; transitions are commits.

Parent-gated cascade with auto-dispatch. Finalized parent auto-triggers children's sub-agents.

D10

Strict mirror dispatch. M2 unit-1 declaring N module subsections → M3 dispatches exactly N module sub-agents.

§ 3.3Dispatch & sub-agent topology

6 decisions

D11

Pipelined-sequential dispatch within-parent siblings. Next sibling reads prior sibling's committed output.

D12

Trigger threshold: APPROVED. Teacher endorsed but not yet finalized. Maximum overlap, low token-burn risk.

D13

Cross-parent siblings parallelize. M3 modules across different units can fan out concurrently.

D14

Per-module / per-lesson sub-agents with bound tools. writeFile scoped to a single target file.

D15

Orchestrator is LLM-driven at every dispatch boundary. Reads state, decides dispatch | block | ask_teacher.

D16

Hybrid async execution. Orchestrator inline (2-5s); sub-agents async via worker queue (30-60s+).

§ 3.4Agent layer (the architectural collapse)

4 decisions

D17

Prompts-as-agents pattern. Specialization lives in markdown prompts and product skills; tool-using workers run through ToolLoopAgent sessions.

D18

Hybrid prompt lookup (Z): workspace-first, system fallback. Per-course overrides available.

D19

Canonical prompt inventory: ~30 markdown files covering generators, gates, orchestration, chat, KB, review, resources, visuals.

D20

Stays deterministic (no prompt): linter, publish Formatter, file primitives, git operations, level_summary manifest section.

§ 3.5Review system

5 decisions

D21

Universal review system (existing) is the V2 surface. Only projection layer changes: project from workspace, not Supabase.

D22

Edit vs Review duality. Edit = direct write. Review = markdown proposal record with digest-checked linear apply; no automatic repair action.

D23

Comments: one file per comment, folder per artifact. Each comment IS its own git commit; author = comment author.

D24

Superseded by ADR 0013/0023: reviewed edits do not trigger an in-loop judge or revision path. Findings remain report-only until teacher review and Publish.

D25

Review proposals use base digests and linear snapshots. Course-shape follow-up comes from discovery-first readiness reports, not a hard-coded descendant cascade.

§ 3.6Workflow / git mechanics

3 decisions

D26

Linear snapshot strategy: generations and accepted review proposals write to one history. Review conflicts use base-digest checks, not git merge.

D27

Commit granularity (α): per-sub-agent-completion. Each sub-agent's full output is one commit.

D28

Authorship convention: short tags — teacher@<email>, agent:<role>, orchestrator, judge:<context>.

§ 3.7Milestone manifests

3 decisions

D29

Semantic readiness evidence lives in report artifacts and topology declarations, not milestone summary files.

D30

Report writers are advisory. TypeScript projects evidence but does not own curriculum-quality prose.

D31

Resolved questions remain comments/chat context for explicit review actions, not a generated workflow summary layer.

§ 3.8Chat surface

4 decisions

D32

Chat organization follows teacher/context review surfaces rather than numbered milestone files.

D33

Chat format: frontmatter per turn. author, timestamp, optional tool_calls, optional context:{artifact,sha,comment}.

D34

Cross-surface context: porting, not moving. Review-panel 'let's talk about this' opens chat with context-band frontmatter.

D35

Chat resolution (z): hybrid LLM-drafted + teacher-confirmed. Two commits: judge:resolution-summarizer drafts; teacher@<email> confirms.

§ 3.9Knowledge Base (LLM Wiki)

5 decisions

D36

KB substrate: per-teacher KB repo (separate from per-course repos). Cross-course accumulation within a teacher.

D37

KB integration pattern: Task-based query. Course sub-agents invoke Task with kb/context-researcher.md.

D38

KB follows Karpathy's LLM Wiki: kb/AGENTS.md (schema) + kb/index.md (catalog) + kb/pages/ (mutable core) + kb/sources/ (immutable raw).

D39

KB linter (kb/linter.md) runs periodically. Surfaces contradictions, stale claims, orphan pages, missing concepts.

D40

File-back affordance. Chat dock footer 'File as KB page' button converts resolved chat segment into kb/pages/<slug>.md.

§ 3.10Workspace UI

4 decisions

D41

Three-zone workspace (per 08-milestone-architecture.md §3). Left rail · Middle content area · Right rail (Progress + Review tabs).

D42

Left sidebar — three stacked sections: Agents (prompts) · Curriculum (finalized∪published tree) · Knowledge Base (tiered S/A/B).

D43

Chat dock (3 fields): header (context band) · chat input · footer (Resolve / Continue / Clear context / File as KB page).

D44

Progress tab preserved. Only data source changes — projects from workspace + git log + worker queue state.

§ 10 · Build order — from V2-P1 today to the locked vision

Current state

V2-P1 at commit 0e0703d ·~10% of the locked vision

Generator + Linter + HITL gate + deterministic Formatter producing unit shells.

Direction correction

Wave 1 of 7

Land the spec + 5 ADRs
Revert 0e0703d — restore the Evaluator as gate prompts (ADR 0007)
Extend invokeSubAgent for prompt-loading with workspace + system fallback
Stand up curriculum-agents/prompts/ skeleton

Workspace state machine

Wave 2 of 7

Implement 4-state lifecycle (frontmatter + contract linter rules)
Build parent-gated cascade dispatcher (M1→M2 only first)
Report-only Strategy/Structure/Substance quality evidence
Topology/readiness projection without gate files

Milestone build-out

Wave 3 of 7

M1 prompts + flow (intake.md MarkdownContract, chat/m1.md, pedagogy, outline)
M2 prompts + flow (pipelined-sequential per-unit)
M3 prompts + flow (parallel cross-unit, sequential within-unit, unit-closure gates)
M4 prompts + flow (per-lesson + per-assignment, closure gates)

Review system integration

Wave 4 of 7

Swap review-panel projection from Supabase to workspace files
Comment storage (one-file-per-comment, git-commit-as-authorship)
Edit vs Review duality (button wiring, review proposal records, accept-on-apply)
Digest-checked linear review-proposal apply with report-only readiness follow-up

KB integration

Wave 5 of 7

Per-teacher KB repo bootstrap
kb/AGENTS.md, kb/index.md, frontmatter conventions
5 KB prompts (librarian, context-researcher, field-researcher, relevance-judge, linter)
Wire course sub-agents to Task-invoke kb/context-researcher.md
Add 'File as KB page' chat dock footer button + flow

Next.js wiring (V2-P2)

Wave 6 of 7

Workspace-mount infrastructure (Supabase Storage + server-side git)
Async worker queue integration
Left sidebar restructure (3 stacked sections per D42)
Per-course repo dashboard

Cutover (V2-P6)

Wave 7 of 7

Final integration testing
Default-branch swap — collapsed retires, V2 becomes production

§ 11 · Open questions deferred to implementation time

Q-OPEN-1

Worker queue medium (Inngest / Vercel Background Functions / Supabase Edge / pg-boss). Decided at R6.

Q-OPEN-2

Per-workspace prompt-override semantics — file-presence (total) vs layered inheritance. Decided at R1 first override case.

Q-OPEN-3

Orchestrator finalize-detection — server-action only (no git hooks). Confirmed at R2.

Q-OPEN-4

AD_HOC card reviewability rules — which workspace paths can spawn review cards. Decided at R4.

Q-OPEN-5

Autonomous-mode LLM-judge trigger conditions (#1125 cross-family swap). Deferred until autonomous trust re-introduced post-cutover.

Supersedes

2026-05-26-v2-filesystem-backbone-design.md

Pre-grilling V2 spec. Marked SUPERSEDED at top. ADR 0007 reverts its 0e0703d simplification.

src/v2/ at commit 0e0703d

Structurally incomplete against this spec. V2-P1 today implements ~10% of the locked vision.

ADR Index

The five load-bearing ADRs (0004–0008) with full context, alternatives, and consequences.

Visualise

Flow & Dependency Maps

Milestone state machine, dispatch flow, linear review apply, KB structure.

Provenance

Decision Journey

The 18-round grilling session that produced this spec, captured as a narrative.

Back to design index

V2 Claude-Code-Style Redesign

claude/coe-filesystem-backbone-TYD7Tdocs/superpowers/specs/2026-05-27-v2-claude-code-style-redesign.md