PhanesLight

One command turns a repository into a wired, multi-agent development environment for Claude Code.

You install a single Markdown file as your /phaneslight command. Running it surveys your project and builds the rest inside your repository: five sub-agents, enforcement hooks, a documentation tree and a script library.

It is not install-once-and-forget. Re-run it whenever the project moves and it surveys again, upgrades the agents, and fills in what is missing. The team grows with your codebase instead of rotting beside it.

Your situation	What to use
New project, or one with no PhanesLight yet	/phaneslight
A project on an older PhanesLight or Phanes	/phaneslightupgrade

Run both on Opus 5 at high effort. They build and maintain the whole setup, so they are the runs worth spending on. The team they install is designed for Sonnet 5, which is what keeps a Max 5x plan viable.

Contents · What it does · The five agents · Which model for which run · How to use · Core principles · Starting from zero · How to install · Upgrading · Companion tools · Version · License

---

What it does

Checks itself, then your project. The run compares its own version against the published one and offers the upgrade if you are behind. It installs four MCP servers (context7 for library docs, deepwiki for dependency answers, semble for code search, serena for symbol navigation) and only four, because every tool schema costs context in every session. A failed install becomes a TODO and the run continues. It asks your consent once and remembers your answer.

Reads the repository to work out its purpose, language, build system and module boundaries, ignoring vendored dependencies and demo content.

Builds the memory your agents work against:

• documentation/ for session summaries, plans, architecture snapshots and a curated API registry. Every folder gets a generated _index.md, so agents find things by descending indexes instead of reading the tree.
• tests/ with unit/, integration/, e2e/, fixtures/, helpers/.
• .phaneslight/scripts/, the library that owns every mechanical rule. On both platforms as of v3.8.0.
• .claude/settings.json hooks that enforce rules at the harness layer: one blocking guard that denies an unstamped new file, one advisory check that runs size and documentation audits on every write. Prompts forget under context pressure. Hooks cannot.

Sorts every task into a tier. T1 is a single-file fix, T2 a feature inside one module, T3 cross-module. Each loads different context, but disclosure is universal: even a T1 fix is named in a report. A task that outgrows its tier stops and asks.

Writes a bootstrap summary recording the install, module list, roster and any deferred TODOs.

Restart your Claude Code session after the first run. Hooks are read at session start, so they arm on the next one.

---

The five agents

Always the same five, named by model tier. Domain expertise is injected per task rather than baked into an agent file, so the always-on context cost stays fixed as your project grows.

Agent	Model	What it is for
<slug>-orchestrator	Opus 5	Authors, applies and dispatches. The main executor.
<slug>-reviewer	Fable 5.1	HIGH and CRIT findings, plus the plan review at launch. Writes plans, never code.
<slug>-worker	Sonnet 5	The default tier for authored code, inside a dispatched scope.
<slug>-mechanic	Haiku 4.5	Mechanical non-code transforms, doc indexing, fetch-and-digest retrieval.
<slug>-closure	Sonnet 5	Independent re-derivation at every close. Its output is a flag, never a fix.

The expensive tier stays affordable because it is rare: the orchestrator handles MED itself, and only an undeferred HIGH or CRIT reaches Fable.

Only two agents can spawn, the orchestrator and the reviewer. That is what bounds the system to three levels.

                                  YOU
                                   │
                     a task, or a plan of steps
                                   ▼
   ╭─────────────────────────────────────────────────────────────────╮
   │ <slug>-orchestrator                                       opus  │
   │ the only agent that both decides and applies                    │
   │ writes anywhere · spawns all four · holds the run's context     │
   ╰──┬──────────────┬───────────────┬───────────────────┬───────────╯
      │ a composed   │ a composed    │ a HIGH or CRIT    │ "this step is
      │ brief: scope,│ brief: fetch  │ it chose not      │  applied.
      │ conventions, │ this, digest  │ to defer          │  verify it"
      │ acceptance   │ it            │                   │
      ▼              ▼               ▼                   ▼
 ╭──────────╮  ╭───────────╮  ╭─────────────╮  ╭────────────────────╮
 │ -worker  │  │ -mechanic │  │  -reviewer  │  │      -closure      │
 │  sonnet  │  │   haiku   │  │    fable    │  │       sonnet       │
 ├──────────┤  ├───────────┤  ├─────────────┤  ├────────────────────┤
 │ authored │  │ mechanical│  │ plans the   │  │ re-derives from    │
 │ code,    │  │ transforms│  │ fix and     │  │ source: registry,  │
 │ inside   │  │ and bulky │  │ hands it    │  │ api-diff, and it   │
 │ its own  │  │ retrieval │  │ back        │  │ re-runs the build  │
 │ scope    │  │           │  │             │  │ and tests itself   │
 ├──────────┤  ├───────────┤  ├─────────────┤  ├────────────────────┤
 │ writes   │  │ writes NO │  │ writes      │  │ writes no code,    │
 │ in scope │  │ code, ever│  │ PLANS only  │  │ ever               │
 ╰────┬─────╯  ╰─────┬─────╯  ╰─────