# CLAUDE.md This file orients Claude Code when working in this repository. Read this first, then follow the pointers below — do not start writing code before reading `docs/development-plan.md` and the current Unit's coverage references in `docs/sdd/`. ## What this is **graphlemon** is a Level 5 autonomous "lights-out software factory": a two-layer Organizer Agent architecture (Org Graph = fixed Planner→Coder→Validator; Work Graph = dynamic per-task execution graph) that drives real software development end-to-end, backed entirely by Claude Code ACP (`claude -p` non-interactive calls) — there is no Hermes CLI execution backend in this project (decision, 2026-07-29, see `docs/sdd/05-实施约束与依赖.md` §5.3). The authoritative spec is `docs/sdd/` (00-06 + `docs/sdd/sdd-mvcp-contract.json`), generated via the MVCP (Model/View/Controller/Process) methodology from `docs/graphlemon_architecture.md`. **Do not treat `graphlemon_architecture.md` as the spec to implement against** — it's the PRD- equivalent input that produced the SDD. When they conflict, the SDD wins (it's newer and more detailed); if a conflict looks unresolved, stop and ask rather than picking one silently. ## Where to start 1. Read `docs/development-plan.md` — Phase → Sub-phase → Unit breakdown (`docs/sdd/unit_matrix.json` is the machine-readable mirror). Work is organized as Development Units, each classified Value Path / Risk Gate / Enabler, each with explicit `depends_on` and a `done` criterion that references a specific REQ in `docs/sdd/06-验收与测试锚点.md`. 2. The critical path starts at **U-001** (01-M schema) → U-002 → U-004 → ... Follow `development-plan.md` §3 "关键路径" — do not skip ahead to later Units even if they look more interesting; most have real `depends_on` edges. 3. **U-004 (A-2 assumption) is the next unvalidated risk on the critical path.** A-1 (dynamic workflow programmatic invocation) was already spike-validated (`spikes/a1-dynamic-workflows/`, confirmed 2026-07-29). A-2 (Hermes profile SOUL.md/AGENTS.md migrating cleanly into `.claude/agents/*.md` without major rewrites) is not yet tested. Validate it early with a minimal spike (per `development-plan.md`'s explicit recommendation) rather than discovering problems after U-010/U-011 are fully built on top of it. ## Commands No build, lint, or test tooling exists yet — the repo is pre-scaffolding (PH0, no commits made yet). `supervisor/isolation/` has no test suite of its own (that's U-036); `docs/` and `spikes/` aren't packages. The one real executable entry point today: ```bash # A-1 spike: verify Claude Code dynamic workflows can be invoked headlessly (already validated, # kept here for re-running / reference — see spikes/a1-dynamic-workflows/RESULTS.md) ./spikes/a1-dynamic-workflows/run-spike.sh /path/to/some/git/repo ``` Once U-002/U-003 scaffold `src/`, tests run via stdlib `unittest` only (see Testing below) — there is no repo convention yet for a single-test invocation beyond the standard `python3 -m unittest path.to.test_module.TestClass.test_method`; don't invent a different pattern. ## Hard constraints (do not relitigate these — they're settled decisions) - **Execution backend**: Claude Code ACP only (`claude -p ... --output-format json --json-schema --permission-mode auto`, no `--bare`, no `--dangerously-skip-permissions`). See 05 §5.3, §5.3.1, §5.4. - **Implementation language**: graphlemon's own backend/frontend/Deploy Supervisor are **pure stdlib Python** — no Flask/FastAPI/Express/Node.js, no npm build step. This mirrors the predecessor project graphloop's convention. See 05 §5.7. (This constraint is on graphlemon's own implementation only — it does NOT apply to the code graphlemon generates for target projects, which follows whatever stack that target project uses.) - **Testing**: stdlib `unittest` only, no pytest/fixtures. Mock the `subprocess`/`claude -p` boundary in normal tests; real end-to-end tests that actually shell out to `claude` should be gated behind an explicit env var and skipped by default (mirror graphloop's `RUN_REAL_AGENT_E2E=1` pattern) — this project doesn't have that harness yet, build it as part of the relevant Unit rather than improvising a different pattern per test file. - **Isolation**: parallel coding nodes must use `git_worktree_ref`. If `target_folder_path` is graphlemon's own repo (self-hosting/self-modification, PH5 only), worktree is **unconditionally mandatory** even for serial single-node changes — see 05 §5.8. ## Two things named "Supervisor" — do not confuse them 1. **"Supervisor（调度子 Agent）"** — an in-process monitoring node inside the Coder Work Graph (architecture doc, existing concept). Watches Work Node execution, triggers reflection/ rescheduling. Part of the Graph Engine itself. 2. **"Deploy Supervisor"** — an independent OS process, entirely outside the Graph Engine, that handles blue-green deployment and automatic rollback when graphlemon modifies its own code (PH5 only). See `docs/supervisor-auto-rollback-design.md` for the full design and the disambiguation note at the top of that file. These are unrelated components that happen to share a root word in casual English. Identifiers for #2 are always prefixed `c_deploy_supervisor_*` / `deploy_health_signal` — never abbreviate to just "supervisor" in code or docs. ## PH5 (Deploy Supervisor / self-hosting) is not in scope yet `docs/development-plan.md` PH5 (Units U-034~U-043) depends on PH4 closing first — self-modification safety only makes sense once the base system has passed full regression. Don't build any of U-034~U-043 before PH0-PH4 are done, even though the design (`docs/supervisor-auto-rollback-design.md`) and its four reusable isolation modules (`supervisor/isolation/`) are already staged. Those modules were adapted from graphloop and have had exactly one manual smoke test — they still need a real `unittest` suite (U-036) before anyone should trust them in a real rollback path. ## Prior art worth reading, not worth copying wholesale `/Users/yibo/Documents/lemonAI/graphloop` is an earlier, unmaintained attempt at this same architecture — substantially implemented (two-layer graph, isolated workspace, change manifest, selective apply, fan-in/fan-out, real Claude-based Planner/Worker/Reviewer agents) but its own Phase 10 self-evolution attempt stalled with concrete documented failures (a worker writing files outside its isolated workspace, a 300s timeout, a stale-PID recovery incident). Its `CLAUDE.md` is worth reading for architecture patterns; its `hermes_watchdog.py`/`phase10_controller.py` are worth reading for the "fail-closed, deterministic, never-auto-restart" supervision philosophy (graphlemon's Deploy Supervisor deliberately extends this into auto-rollback rather than just auto-halt — see `docs/supervisor-design-comparison.md` for why). Do not import graphloop code directly; anything worth reusing has already been copied and adapted into this repo (`supervisor/isolation/`). ## Repo layout (as of PH0, before scaffolding exists) - `docs/` — architecture, SDD, development plan (see above) - `docs/wireframes/` — static no-build HTML prototypes for the PH3 console views (`v_*.html`), referenced per-page from `docs/sdd/02-V-界面与交互.md` §2.1-2.13 — implementation starting point once PH3 begins, DOM/class names map 1:1 to that doc's field lists. - `supervisor/isolation/` — staged utility library (isolate/diff/apply), not yet wired to anything - `spikes/` — one-off validation spikes (currently just A-1) - `src/` (created by U-001) — graphlemon's own backend source (schema, then U-007+ HTTP/WebSocket server). **Not the same `src/` a target project already has in its own repo** — a target project's `src/` is its own pre-existing source tree; graphlemon does not create or restructure it (see 05-实施约束与依赖.md §5.7 and architecture doc §13.2 — U-002 only creates `.graphlemon/` inside a target project, corrected 2026-07-31 after finding development-plan.md's U-002 line had cited the wrong architecture section). - Everything else (`.claude/agents/`, `skills/`, `runs/`, per-target-project scaffolding) gets created by U-002/U-003 — it doesn't exist yet, and that's expected at this stage.