Roadmap / epic: build coact (COMPLETE + REALIZE)

[thorwhalen]

coact build roadmap (COACT_SPEC §10 build order).

coact owns two transforms the ecosystem lacks: COMPLETE (.claude/skills/ → .claude/agents/ definitions) and REALIZE (definition → running agent). It is glue over skill (foundation), aw (runtime substrate), py2mcp (tool exposure) — see misc/docs/REUSE.md and misc/docs/DECISIONS.md.

Milestones (each independently shippable):

• Reuse audit (REUSE.md) + decisions log (DECISIONS.md) #2 — Reuse audit (REUSE.md) + decisions log (DECISIONS.md)
• Core SSOT: AgentDefinition + AgentPlan + ReturnContract (base.py) #3 — Core SSOT: AgentDefinition + AgentPlan + ReturnContract (base.py)
• Emitter registry: claude-agents-md + sdk-agent-dict (emit.py) #4 — Emitter registry: claude-agents-md + sdk-agent-dict (emit.py)
• coact: frontmatter convention + validator (frontmatter.py) #5 — coact: frontmatter convention + validator (frontmatter.py)
• COMPLETE (mechanical) + policy + plan_completion (complete.py, policy.py) #6 — COMPLETE (mechanical) + policy + plan_completion
• REALIZE host backend + realization registry (realize.py) #7 — REALIZE host backend + realization registry
• REALIZE sdk backend: aw.AgenticStep-compatible RunnableAgent (realize.py) #8 — REALIZE sdk backend: aw.AgenticStep-compatible RunnableAgent
• Persona & return-contract synthesis, LLM-optional (synthesis.py, llm.py) #9 — Persona & return-contract synthesis, LLM-optional
• REALIZE mcp backend via py2mcp (realize.py) #10 — REALIZE mcp backend via py2mcp
• Analysis utilities: diff, estimate, inventory, back (analysis.py) #11 — Analysis utilities: diff, estimate, inventory, back
• CLI (argh) + curated __init__ exports + layered README (__main__.py, __init__.py, README.md) #12 — CLI (argh) + curated init exports + layered README

Grouped into PRs: A #2–#5 (foundation: docs, SSOT, emitters, frontmatter) · B #6 (COMPLETE+policy) · C #7–#8 (REALIZE host+sdk) · D #9–#10 (synthesis + mcp) · E #11–#12 (analysis + CLI/README).

Cross-repo (non-breaking) enhancements: aw (split extraction/rendering in translators), py2mcp (mk_mcp_from_refs).

[thorwhalen]

✅ Build complete. All milestones shipped and merged to `main`.

PR	Milestone	Issues
#14	Foundation — AgentDefinition SSOT, emitters, `coact:` frontmatter+validator, AgentStore	#2–#5
#15	COMPLETE — skill→agent (mechanical, no-LLM), policy, plan_completion	#6
#16	REALIZE host + sdk (aw.AgenticStep-compatible)	#7, #8
#17	Synthesis (LLM-optional) + mcp backend	#9, #10
#18	Analysis (diff/estimate/inventory/back) + CLI + README	#11, #12
#19	Fixes from an adversarial-review pass (11 confirmed findings)	—

Ecosystem coordination (separate repos): thorwhalen/aw#4 (split extraction/rendering → reused by coact's crewai/openai-tools emitters), i2mint/py2mcp#2 (mk_mcp_from_refs + import_object → used by coact's mcp backend), thorwhalen/skill#2 (filed: preserve namespaced frontmatter — coact doesn't depend on it).

State: 78 tests + 35 doctests + ruff green. 4 emit targets (claude-agents-md, sdk-agent-dict, crewai, openai-tools), 3 realize backends (host, sdk, mcp). No SDK/LLM import on any mechanical path. Reuse boundary documented in misc/docs/REUSE.md; decisions in misc/docs/DECISIONS.md.