宜博 / lemongraph

CLAUDE.md 8.23 KB

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:

# 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 <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.