feat(coder): package skeleton + loop.py with DEFAULT_LOOP

[kovtcharov]

Summary

Phase 1 scaffolding for gaia-coder per docs/plans/coder-agent.mdx. Creates the package structure every follow-up task imports from — no runtime behaviour, no LLM calls, no network, no SQLite. Just the load-bearing shapes: her own base class, the editable 20-state ReAct loop, the CLI surface, and the three living documents the spec anchors on.

This is the trunk the two sibling branches (feature/gaia-coder-stores, feature/gaia-coder-mixins-1) rebase onto once it lands.

Threads

• Package skeleton (§3.1) — src/gaia/coder/ with sub-packages for prompts/, stores/, tools/, review/, introspect/, self_fix/, tests/, skills/. Every __init__.py is a stub pointing at the phase that fills it in. Matters because downstream tasks need stable import paths now without racing on who creates which directory.
• CLI stub (§3.1) — gaia-coder console script wired through setup.py. All 17 subcommands from the spec (daemon, status, ask, note, critical, inbox, feedback, promote, demote, trust, audit, spend, egress, introspect, skill, doctor, rag) print "<name>: not yet implemented" and exit 0. Matters so docs, tests, and muscle memory can start using the real surface immediately. Uses argparse (matching existing gaia CLI) rather than click, which is not a project dependency.
• State machine (§5.1, §15.3) — src/gaia/coder/loop.py with immutable Transition, State, Loop dataclasses and DEFAULT_LOOP containing all 20 states grouped into the seven stages. The self_review state carries the updated three-way transition (publish | debug | edit based on failure_is_complex) from §15.3 — shallow failures go straight back to edit, complex ones enter the dedicated debug sub-loop. Matters because a typo here silently regresses her review discipline.
• Base class (§5.1) — CoderAgent that does NOT inherit from gaia.agents.base.Agent. Product-agent assumptions (request-scoped, single LLM round-trip) do not match her daemon-scoped lifecycle with durable queues and editable control flow. Composition from the GAIA base is still allowed at use-site (@tool, AgentConsole, PathValidator). Matters so sibling tasks can from gaia.coder import CoderAgent today.
• Living documents (§4.6, §6.5) — GAIA.md (identity: principles, persona, Karpathy working-style rules), ARCHITECTURE.md (how she is composed), PROJECT_MAP.md (how the project she's building is composed), plus skills/catalog.toml seed. All short Phase-1 placeholders; real content lands in Phase 3/5. Matters because both docs are referenced from every system prompt — they need to exist on disk before the runner does.
• Introspection seed (§7.7) — introspect_state_machine() in loop.py returns a JSON snapshot + stateDiagram-v2 Mermaid render of the loop. The Phase 3 IntrospectionToolsMixin wraps this as the public @tool; keeping the implementation next to the loop it describes avoids duplication.

Deviations from spec

• Spec says "wired via click (already a project dep)" — click is not actually in setup.py or any extras. Switched to argparse to match the existing src/gaia/cli.py convention and avoid adding a dependency. The subcommand surface is unchanged.
• Spec suggests 4 commits; this PR has 3. Splitting loop.py across two commits (dataclasses in b, DEFAULT_LOOP + introspection helper in c) required temporarily deleting and re-adding content, which felt worse than a clean "state machine + base class" commit. Commits are: (1) scaffold + CLI, (2) loop.py + base.py + __init__.py re-exports, (3) tests.

Test plan

• pytest tests/coder/test_skeleton.py -xvs — 5/5 pass, including the guard against regressing self_review's three-way transition.
• python util/lint.py --black --isort --flake8 on the new files — all clean (project flake8 uses --max-line-length=88 with E501 ignored per util/lint.py).
• uv pip install -e . — succeeds; gaia-coder --help prints the 17-subcommand list; stub subcommands exit 0 (gaia-coder introspect, gaia-coder status, etc.).
• git diff feature/coding-agent...HEAD --stat — changes only under src/gaia/coder/, tests/coder/, and setup.py. No edits to src/gaia/agents/ or other existing modules.
• Existing gaia-code entry (legacy Next.js scaffolder) untouched per §1.

[github-actions]

Review — feat(coder): package skeleton + loop.py with DEFAULT_LOOP (#819)

Note: this PR is already merged. Posting a retrospective review so the follow-up sibling branches (feature/gaia-coder-stores, feature/gaia-coder-mixins-1) can pick up the threads.

Summary

Clean, well-scoped Phase 1 scaffolding. Introduces a new src/gaia/coder/ package that deliberately sits outside the src/gaia/agents/ product-agent ecosystem, adds a gaia-coder CLI stub whose 17 subcommands all exit 0, and pins the §15.3 loop shape (20 states, three-way self_review branch) with a real test. The single most important thing to know: every docstring, placeholder document, and the PR body itself cite docs/plans/coder-agent.mdx, but that file has never existed in the repo (git log --all -- docs/plans/coder-agent.mdx returns nothing). Readers following the breadcrumbs will hit dead ends until the spec is committed.

Issues

🟡 Important

Referenced spec docs/plans/coder-agent.mdx does not exist — in pr-diff.txt I count 19 references to docs/plans/coder-agent.mdx across __init__.py (src/gaia/coder/__init__.py:13), base.py (src/gaia/coder/base.py:15,58,67), cli.py (src/gaia/coder/cli.py:101), loop.py (src/gaia/coder/loop.py:6), and all three living documents (GAIA.md:5, ARCHITECTURE.md:3, PROJECT_MAP.md:3). ls docs/plans/ confirms every neighbour exists (agent-hub.mdx, autonomy-engine.mdx, skill-format.mdx, …) except coder-agent.mdx. Every §X.Y citation in the scaffolding currently points at vapour. Either land the spec in a follow-up PR referenced from here, or relax the docstrings to say "spec to land in a follow-up" so first-time readers aren't chasing a ghost.

docs/docs.json and docs/reference/cli.mdx not updated for the new gaia-coder console script — CLAUDE.md is unambiguous: "New CLI commands → update docs/reference/cli.mdx" and "New pages must be added to docs/docs.json navigation". The PR adds a new user-facing binary (setup.py:216 adds gaia-coder = gaia.coder.cli:main) but skips both docs touchpoints. Phase 1 is a reasonable time to defer this since every subcommand is a stub, but an explicit note in the PR body ("docs land with Phase 2 when subcommands do real work") would have made the deferral legible. Please capture in a follow-up issue so it isn't lost.

🟢 Minor

test_introspect_state_machine_returns_mermaid has a vestigial graph TD branch (tests/coder/test_skeleton.py:99). The assertion is:

assert "graph TD" in mermaid or "stateDiagram" in mermaid

but loop.py:_mermaid (line 118) only ever emits stateDiagram-v2. The or "graph TD" arm is dead. That's fine as forward-looking flexibility, but the docstring at test_skeleton.py:92–97 implies both dialects are "accepted" which misleads future readers into thinking the implementation sometimes produces graph TD. Either tighten the assertion or drop the "graph TD" half of the docstring:

def test_introspect_state_machine_returns_mermaid() -> None:
    """The introspection helper must return a Mermaid stateDiagram render.

    §7.7 specifies the tool renders both JSON and a Mermaid diagram for
    the EM's inspection. The current implementation uses
    ``stateDiagram-v2`` so the seven-stage grouping renders as nested
    blocks; this test pins that dialect.
    """
    from gaia.coder.loop import introspect_state_machine

    payload = introspect_state_machine()

    assert isinstance(payload, dict)
    assert "json" in payload
    assert "mermaid" in payload

    mermaid = payload["mermaid"]
    assert isinstance(mermaid, str)
    assert "stateDiagram" in mermaid, (
        f"Mermaid render should use the `stateDiagram` dialect; "
        f"got:\n{mermaid[:200]}"
    )

Optional[X] where X | None would be more idiomatic (src/gaia/coder/base.py:275,316, src/gaia/coder/loop.py:656,715,716). setup.py:219 pins python_requires=">=3.10", so PEP 604 union syntax is always available. The file already uses it in the CLI (cli.py:149 — argv: list[str] | None = None), so the inconsistency is within the PR itself. Not blocking — the repo has mixed usage — but worth normalising when the real bodies land.

gaia-coder not listed in the CLAUDE.md "Console Script Entry Points" table (repo-level CLAUDE.md, Project Structure section). That table lists gaia, gaia-mcp, gaia-code, gaia-emr but not the new binary. Adding it keeps the repo-level doc self-describing and prevents new contributors from asking "what's gaia-coder vs gaia-code?".

_build_parser's subcommands parameter type is Iterable[tuple[str, str]] but it's iterated only once (src/gaia/coder/cli.py:94). Harmless for the default call, but if a test ever passes a generator and then calls _build_parser a second time, the generator is exhausted. Narrow to Sequence[tuple[str, str]] to make re-iteration safe, or document the constraint.

Strengths

• Immutable graph modelling is correct for the stated use case. @dataclass(frozen=True) on Transition/State/Loop plus the "an edit means a diff to this file, not a runtime mutation API" comment (loop.py:43–46) is the right stance — any future runtime that tries to mutate the graph will fail loudly, which matches the §7.8 invariant that every merged edit bumps Loop.version.
• Test pins the load-bearing invariants, not implementation details. test_default_loop_has_20_states and test_self_review_has_three_transitions would both fail if someone silently regressed §15.3. That's high-signal coverage for a skeleton PR.
• The "not inheriting from gaia.agents.base.Agent" decision is justified in-place (base.py:5–12). The docstring names both what's different (daemon lifecycle, durable queues, editable graph) and what composition is still welcome (@tool, AgentConsole, PathValidator). Future readers won't have to go spelunking for the rationale.
• Fail-loudly is honoured where it matters. Loop.state_by_name (loop.py:159) raises KeyError with the known state list instead of returning None; identity_document (base.py:170) lets FileNotFoundError propagate with a docstring explaining why absence is a bug not a fallback. Matches repo CLAUDE.md.
• Scope discipline is clean. Only new files under src/gaia/coder/ + tests/coder/, plus the setup.py package/entry-point additions. No drive-by edits to src/gaia/agents/ or other modules.

Verdict

Approve with suggestions (retrospective — PR is already merged). No blocking issues. The missing docs/plans/coder-agent.mdx is the one thing that genuinely warrants a follow-up: land it (or retarget the references) before the next scaffolding PR, because every sibling branch will inherit the same broken-citation pattern otherwise.