ADR · Proposed (2026-05-27 grilling session)

Prompts-as-agents: one Task primitive + N markdown prompts

Date

2026-05-27

Deciders

pdg (HITL during the 2026-05-27 grilling)

Companion design

docs/superpowers/specs/2026-05-27-v2-claude-code-style-redesign.md § 3.4

Context

Collapsed's library-course-generation.yaml defines 8 specialized agents, each with a TypeScript handler. Specialization lives in TS code — adding a new capability requires a new TS file + handler + tests.

The historical locked milestone architecture named several evaluation contexts. Under the collapsed pattern this implied one Evaluator with many modes or several specialized Evaluators, keeping specialization in TypeScript. ADR 0013/0023 later retired that in-loop shape.

The grilling-session question — 'what would Claude Code do?' — surfaced a fourth option that escapes the pattern entirely.

Decision

Adopt the prompts-as-agents pattern: exactly ONE TypeScript agent primitive (invokeSubAgent) + N markdown prompt files.

D17 — One Task primitive (invokeSubAgent) loads prompts + bound tools + optional Zod schema, dispatches via invokeAgent.
D18 — Hybrid prompt lookup (Z): workspace-first override, system fallback. System defaults serve 80% of cases.
D19 — Canonical prompt inventory of ~30 files: generators (M1-M4), gates (8 named), orchestration (5), chat (3), KB (5), review (2), resources/visuals (later).
D20 — Stays deterministic (no prompt): linter, publish Formatter, file primitives, git operations, level_summary manifest section.

Why this is what Claude Code actually does

Claude Code has no 'Evaluator agent.' It has the Task tool, which spawns sub-agents with their own context windows. Skills like /code-review, /security-review, /verify, /diagnose are markdown files in ~/.claude/skills/ — invoked, they become the sub-agent's role prompt.

Same pattern Anthropic's 'Building effective agents' post advocates (orchestrator + workers), and Google Antigravity 2.0 documents (persistent isolated environments). V2 adopts this convergent pattern explicitly.

The architectural collapse

Layer	Collapsed	V2 with prompts-as-agents
TypeScript agent files	8 (5 LLM + 3 KB agents)	1 (invokeSubAgent)
Markdown prompts	Embedded in TS handlers	~30 markdown files
Adding a capability	New TS file + handler + manifest + test	Write one markdown file
Teacher visibility	None	All prompts readable + per-workspace overrideable

Consequences

Positive

• Architectural collapse: 8 TS agents → 1 TS file + ~30 markdown files.
• Teacher visibility — advanced teachers can read and edit the prompts driving their course.
• Iteration speed: prompt change = markdown edit, no deploy.
• Test surface shrinks — test the one Task primitive thoroughly, integration tests exercise representative prompts.

Negative

• Prompt sprawl risk; mitigated by subfolders + the left-rail Agents section as navigation tree.
• No type safety across prompt/caller boundary — runtime Zod errors at boundaries.
• Prompt version control via git, no semver.
• Lookup overhead per dispatch (negligible vs LLM latency; caching deferred until hot).

Neutral

• All 8 collapsed agents have prompt-file analogs — direct migration path.

Migration / execution

1.Wave R1: extend invoke-subagent.ts with prompt-loader + bound-tool factory + Zod dispatch.
2.Stand up curriculum-agents/prompts/ system-default tree with stub headers for each prompt in D19.
3.Wire existing M1-M4 generator stubs to load from prompts directory.
4.Subsequent waves (R2-R5) populate prompt bodies in dependency order.

Open questions

Per-workspace override semantics — total override (current) vs layered inheritance. Defer to first override case.
Caching strategy — when prompt-reload-per-dispatch becomes a bottleneck, introduce LRU cache.
Prompt observability — telemetry for 'which prompt produced this output' — defer to V2-P2.

← Previous

0004 · V2 architecture baseline: next-generation from collapsed, git substrate, no JSONB during generation

0006 · LLM Wiki pattern for the Knowledge Base (per-teacher repo)

ADR index

Context

The grilling-session question — 'what would Claude Code do?' — surfaced a fourth option that escapes the pattern entirely.

Decision

Adopt the prompts-as-agents pattern: exactly ONE TypeScript agent primitive (invokeSubAgent) + N markdown prompt files.

D17 — One Task primitive (invokeSubAgent) loads prompts + bound tools + optional Zod schema, dispatches via invokeAgent.

D18 — Hybrid prompt lookup (Z): workspace-first override, system fallback. System defaults serve 80% of cases.

D19 — Canonical prompt inventory of ~30 files: generators (M1-M4), gates (8 named), orchestration (5), chat (3), KB (5), review (2), resources/visuals (later).

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

Why this is what Claude Code actually does

The architectural collapse

Layer	Collapsed	V2 with prompts-as-agents
TypeScript agent files	8 (5 LLM + 3 KB agents)	1 (invokeSubAgent)
Markdown prompts	Embedded in TS handlers	~30 markdown files
Adding a capability	New TS file + handler + manifest + test	Write one markdown file
Teacher visibility	None	All prompts readable + per-workspace overrideable

Consequences

Positive

• Architectural collapse: 8 TS agents → 1 TS file + ~30 markdown files.
• Teacher visibility — advanced teachers can read and edit the prompts driving their course.
• Iteration speed: prompt change = markdown edit, no deploy.
• Test surface shrinks — test the one Task primitive thoroughly, integration tests exercise representative prompts.

Negative

• Prompt sprawl risk; mitigated by subfolders + the left-rail Agents section as navigation tree.
• No type safety across prompt/caller boundary — runtime Zod errors at boundaries.
• Prompt version control via git, no semver.
• Lookup overhead per dispatch (negligible vs LLM latency; caching deferred until hot).

Neutral

• All 8 collapsed agents have prompt-file analogs — direct migration path.

Migration / execution

1.Wave R1: extend invoke-subagent.ts with prompt-loader + bound-tool factory + Zod dispatch.

2.Stand up curriculum-agents/prompts/ system-default tree with stub headers for each prompt in D19.

3.Wire existing M1-M4 generator stubs to load from prompts directory.

4.Subsequent waves (R2-R5) populate prompt bodies in dependency order.

Open questions

Per-workspace override semantics — total override (current) vs layered inheritance. Defer to first override case.

Caching strategy — when prompt-reload-per-dispatch becomes a bottleneck, introduce LRU cache.

Prompt observability — telemetry for 'which prompt produced this output' — defer to V2-P2.