marchwarden/CLAUDE.md

Marchwarden — Project Context

What This Is

A network of agentic research specialists (MCP servers) coordinated by a principal investigator (PI) agent. Educational project learning agents, MCP, and agent composition.

Current Project State

Phase	Phase 1 complete, Phase 2 next
Last worked on	2026-04-08
Last commit	7088f45 — Merge PR #7: M1.4 MCP server
Branch	main (clean)
Tests	81 passing
Blocking issues	None

Key Files

File	Purpose
researchers/web/models.py	Research Contract v1 Pydantic models (9 types)
researchers/web/tools.py	Tavily search + URL fetch with content hashing
researchers/web/trace.py	JSONL trace logger
researchers/web/agent.py	WebResearcher — inner agentic loop
researchers/web/server.py	FastMCP server wrapping the researcher
cli/main.py	CLI shim (not yet implemented)

Architecture

• Researcher = MCP server exposing research(question) -> ResearchResult
• ResearchResult = answer + citations (with raw_excerpt) + categorized gaps + discovery_events + open_questions + confidence + confidence_factors + cost_metadata + trace_id
• Agent loop = Claude tool-use loop (plan→search→fetch→iterate) + synthesis step
• Trace = JSONL audit log per research call at ~/.marchwarden/traces/

Conventions

• API keys live in ~/secrets (not .env)
• Wiki is at docs/wiki/ (local git clone, not MCP — wiki MCP is buggy)
• All merges via Forgejo API (claude-code user can't merge via MCP)
• One branch per concern, merge via PR, delete branch after

Session Log

Session	Date	Summary
1	2026-04-08	Project creation, naming, contract design, Phase 0 + Phase 1 complete (81 tests)

What's Next

Phase 2: CLI Shim

1. M2.1 — marchwarden ask "question" command (Click CLI, pretty-print)
2. M2.2 — marchwarden replay <trace_id> command
3. M2.3 — First smoke test: "What are ideal crops for a garden in Utah?"