Phanes

Phanes is a bootstrap prompt for Claude Code. In a single command it turns an empty or chaotic repository into a fully wired, opinionated, multi-agent development environment.

It is not something you install once and forget. Think of it as a living specification that you re-run. Each time you invoke /phanes, it surveys the project again, upgrades the existing sub-agents, fills in any missing infrastructure, and bumps a hidden run counter. The result is an agentic team that grows with your codebase instead of rotting beside it.

The prompt is one file. You install a single Markdown file, phanes.md, as your /phanes command. The scripts, hooks, agents, and documents it sets up are created inside your repository during the run. The scripts that do not depend on your project's language are fetched as tested templates from this repository, pinned to the prompt's own version, and everything else is generated. If the fetch cannot happen, the run generates the scripts as well, so an offline install is still complete.

Modular by design. The core stays that one file on purpose. Anything beyond bootstrapping ships as a separate companion tool. Each companion works on its own in any repository, with no Phanes install at all, and each one snaps into the structures Phanes builds the moment it lands in a Phanes-managed project.

Which file do you need?

Contents

• What it does
• How to use
• Core principles enforced by Phanes
• For inexperienced users: step-by-step from zero
• How to install
• Upgrading an older install
• Companion tools
• Recommended third-party enhancements
• Version · License · Contributing

What it does

The first time you run /phanes in a repository, the prompt walks Claude Code through a strict setup in several phases.

1. Pre-flight. Before anything else, the run checks itself. It fetches this repository's phanes.md and compares version stamps. If a newer version has shipped, it asks whether you want to upgrade: accept and it stops and routes you to /phanesupgrade, decline and it proceeds on the installed version.

It then installs the four MCP servers it benefits from:

• context7 for live library documentation, fetched on demand.
• deepwiki for digest answers about external GitHub dependencies, so agents never pull dependency source into their context.
• semble for hybrid code search, so an agent finds the exact snippet it needs instead of sweeping a whole module with grep and reading entire files.
• serena for symbol-level code navigation, installed on the first run. It runs through uv, which the pre-flight also installs if it is missing.

These servers are enhancements, not hard dependencies. If one fails to install, the run records a TODO and continues in a degraded mode. There are exactly four on purpose: every MCP tool schema costs context in every session, so each server has to earn its place by removing more context than its schema costs. Every generated agent carries a usage rubric saying when each server saves tokens and when to make no MCP call at all.

The pre-flight detects your platform (bash on POSIX, PowerShell on Windows), then runs a capability census of what you already have installed, probing each MCP server for actual reachability and authentication rather than mere configuration. On a first run it asks you once, as a single checklist, which of those capabilities Phanes may build policy around; the choice is saved, and later runs ask only about changes. Phanes only ever builds a mandate around a capability you selected and the census found reachable, and nothing you installed is ever changed or removed. It also ensures the official frontend-design skill is present (skills cost no context until invoked). Finally, each run keeps a progress ledger at .phanes/run-progress, so a session that dies or compacts mid-bootstrap resumes from the last completed phase.

2. Repository comprehension. Phanes reads the README, the source tree, the configs, and the CI to work out the project's real purpose, its primary language, its build system, and its module boundaries. Directories that are not part of the core product, such as vendored dependencies, example packs, and demo content, are filtered out.

3. Project memory infrastructure. Phanes scaffolds the substrate that every sub-agent works against:

• documentation/ holds session summaries, plans, dated architecture snapshots, and a curated API registry. That registry captures the things code search cannot see, such as deprecations, contracts beyond the type signatures, and anti-patterns. The generated API surface itself lives outside the tree as a machine baseline in .phanes/registry/. Every folder carries a generated _index.md, so agents find knowledge by descending indexes, which costs a few hundred tokens, instead of scanning the whole tree. Files respect a soft ceiling of 500 lines and are split into an indexed folder when they outgrow it.
• tests/ holds unit/, integration/, e2e/, fixtures/, and helpers/, with a verbatim README and the same phanes new-file header-stamp discipline that src/ uses.
• .phanes/scripts/ is a script library that owns every mechanical rule, from creating files with header stamps and checking line counts to auditing the documentation ceiling (doc-check), regenerating indexes (doc-index), measuring the root files that load every session against their character budget (register-check), regenerating the API baseline, diffing the API, and listing modules. The scripts that do not depend on your language are installed from tested templates fetched from this repository (pinned to the running version), and each one finds the project by walking up to .phanes/config.json and uses only paths relative to that root, so a hook can never be wired to the wrong tree.
• .claude/settings.json holds the hooks that enforce mechanical rules at the harness layer. A blocking PreToolUse guard denies creation of any unstamped new file, and an advisory PostToolUse check runs size and documentation audits on every write. Prompts forget under context pressure. Hooks cannot.
• .phanes/config.json records the confirmed module list, language, build system, and hook preferences.

4. Tiered workflow definition. Every task is sorted into one of three tiers: T1 for a single-file quick fix, T2 for a feature inside one module, and T3 for anything that cuts across modules. Each tier loads a different amount of context and engages a different chain of agents, but review is universal. Even a T1 fix gets a lightweight Critic pass on its diff. Only the depth of the review and the weight of the documentation scale with the tier. If a task outgrows its tier mid-flight, the agent must stop and ask the orchestrator to promote it.

5. Sub-agent roster generation. Phanes writes 6 to 10 deeply scoped, expert personas to .claude/agents/*.md. Each one is assigned a model by a dated rubric that is re-validated on every update run:

• Architect/Designer, the sole writer of the curated registry and the architecture snapshots.
• close-verifier, the independent close-time verifier and sole writer of the generated API baseline in .phanes/registry/. After every structural change it re-derives the baseline, re-runs the build check itself rather than trusting the coder's report, and confirms that what was applied matches what was approved. It stays a separate agent from the Architect on purpose, since a verifier that also authored the work is not an independent check.
• Critic agents, which produce numbered, ID-tagged audit reports.
• Patch-Author, which turns the approved plan into sequenced patch files but never applies them.
• Executor, which applies approved diffs only and uses phanes new-file for every new file.
• Synthesizer/Arbiter, which consolidates parallel perspectives into one unified plan.
• Plus Analyzer, Planner, Validator, Optimizer, Integrator, Monitor, and Cleaner variants tuned to your specific stack.
• Scouts are not part of the roster. Specialists spawn them on the fly as read-only subagents that fetch and digest bulky one-time context such as module surveys, test logs, and registry sweeps. A strict cost guard makes sure every spawn pays for itself in the specialist context it preserves.

6. Workflow codification. The YAML files in .claude/workflows/ are the single source of truth for how agents chain together. Every chain ends the same way: the Synthesizer runs for parallel work only, then the Critic, then close-verifier on T2 and T3 changes, then the primary agent. Because of that ordering, the artifact that gets applied is always the one that was audited. Phanes also updates CLAUDE.md, at the project root and at module roots only, so the primary agent knows how to triage, delegate, navigate the documentation by index, and review.

Visualized, that chain looks like this. Where the work enters depends on its shape: a single task is triaged and run directly, while a multi-step plan is handed to an ephemeral Orchestrator that walks the plan in small batches. A task's tier changes only how deep the review goes and how much documentation it produces, never whether the review happens:

                          what you asked for
                                  │
              ╭───────────────────┴────────────────────╮
              │                                        │
        a single task                          a multi-step plan
        (or a short plan,                      (5 or more steps)
         4 steps or fewer)                             │
              │                                        ▼
              │                             ╭──────────────────────╮
              │                             │  Orchestrator        │
              │                             │  ephemeral, one per  │
              │                             │  batch of 1 to 3     │
              │                             │  consecutive steps,  │
              │                             │  never across a      │
              │                             │  phase boundary      │
              │                             ╰──────────┬───────────╯
              │                                        │  per step in the batch
              ╰───────────────────┬────────────────────╯
                                  │
                                  ▼   triaged into a tier
            ╭─────────────────────────────────────────╮
            │ T1  one file      lightweight review    │
            │ T2  one module    full review           │
            │ T3  cross-module  full review + snapshot│
            ╰─────────────────────┬───────────────────╯
                                  │
                                  ▼   specialists: bounded fan-out, ≤ 5 parallel
                  Analyzer · Planner · Patch-Author · …   (tuned to your stack)
                                  │   each emits a report + proposed diff, never applies
                                  ▼
                            Synthesizer    consolidate parallel perspectives  *
                                  │
                                  ▼
                            Critic         two verdicts: spec compliance + quality
                                  │
                                  ▼
                            close-verifier regenerate API baseline  (T2 / T3 only)
                                  │
                                  ▼
                            Executor       apply the audited diff, and only that
                                  │
                                  ▼
                     back to the Orchestrator, which writes one session
                     summary per batch and returns a short JSON receipt **

        * Synthesizer runs for parallel work only. Because the chain always
          ends review-then-apply, the artifact applied is always the one audited.
       ** Orchestrated runs only. The receipt is all that crosses back into your
          main session, which is why a long plan can run for hours without the
          session filling up and compacting. Single tasks and short plans skip
          the Orchestrator entirely and return straight to you.

This is the shape Phanes is built for. The setup pays off most when you write a plan first, broken into numbered steps and grouped into phases, and then let the run work through it. Give each step a clear boundary and each phase a clear exit condition, hand the plan to Phanes, and the Orchestrator will size its own batches, route every step to the right tier, and keep the review chain intact from the first step to the last. A vague single sentence still works, it simply gives the machinery much less to hold onto.

7. Bootstrap session summary. Phanes writes documentation/session-summaries/SS00001_phanes-bootstrap_<date>.md, which records the install, the confirmed module list, the agent roster, and any TODOs that were deferred.

After the first run, restart your Claude Code session. Hook configuration is snapshotted when a session starts, so the enforcement hooks arm on the next session. Phanes reminds you of this verbatim at the end of the run.

When you run /phanes again, it detects the existing install through the .claude/.phanes marker and refreshes in place. Agents, workflows, scripts, hooks, and READMEs are all measured against the latest phanes.md and refreshed wherever they have drifted. If a newer Phanes has been published, the run stops first and asks whether you want to upgrade; accept and it routes you to /phanesupgrade (see Upgrading an older install), decline and the run proceeds on the installed version.

How to use

First run

Type /phanes in your project. It scans the repository and builds the whole agentic team and documentation structure around it. Three things make the first run land well.

• Start the session at high reasoning effort. Reasoning effort is set once, when the session launches, and it governs the primary session and every sub-agent it spawns in that session. Launch with claude --effort high (or export CLAUDE_CODE_EFFORT_LEVEL=high before starting), and use xhigh for design-heavy runs where you expect a lot of architecture work. high is the recommended default for Phanes, because the run spends most of its time on routing and structural judgment, where a cheap reasoning pass costs far more in rework than it saves. Set it at launch rather than mid-run: changing effort mid-session writes to your global settings and leaks into other projects and parallel sessions.
• Give it something to read, ideally a plan. On an empty or brand-new repository, create at least a plan.md that describes what you want to build. Phanes reads it to understand the project's purpose and shapes the entire setup, including the agents, the workflows, and the module layout, around the project you actually intend to build rather than around an empty folder. Best results come from a plan written as numbered steps grouped into phases, each step with a clear boundary and each phase with a clear exit condition. That is the shape the run is designed to consume, and it is what lets the Orchestrator batch the work cleanly once execution starts (see the diagram above).
• Steer it if you like. Anything you type right after the command is treated as a directive and takes priority over the defaults, so you can inject your own needs into the setup. For example: /phanes focus on the api/ module; skip pre-commit hook install.

When the run finishes, restart your Claude Code session so the enforcement hooks arm. Phanes reminds you to.

Re-running /phanes: when, and how often

Think of /phanes as refreshing Claude's knowledge of your project. Every run surveys the codebase again and brings the agent team, the workflows, and the registries back in line with reality.

• Early, small project: run it freely. Several times a day is fine. While the codebase is small a run costs little in tokens and context, and keeping the agent team current pays off constantly.
• Before an implementation plan. This is a good habit rather than a hard rule, and it is the highest-value run of them all. Write your plan first, say for a new module, as numbered steps grouped into phases, then run /phanes and inject it. Injecting simply means pasting the plan's contents, or its path, right after the command. Phanes updates the agents and workflows, and creates new ones where needed, so the team is tuned to execute exactly that plan when you start. Then hand the same plan to the run that executes it and let it work through the steps in order.
• Session bookends. Running it at the end of a workday, or first thing when you sit down, keeps the project context fresh before real work begins.
• Grown project: throttle down. Once the codebase is large, once or twice a day is plenty. Add a run right before a large plan. Smaller ones usually do not need one.

Core principles enforced by Phanes

• Procedure in scripts, judgment in prompts, and hooks at the harness layer. Any rule a script can enforce, such as line-count limits, header stamps, registry edits, API diffs, and documentation ceilings, lives in .phanes/scripts/. The two hooks in settings.json make the critical ones impossible to skip. Mechanical rules written into prompts get forgotten under context pressure. Scripts do not forget, and hooks cannot be skipped.
• Single writer per artifact. Every registry file, snapshot, and summary has exactly one writing agent, and so does every generated _index.md, whose sole writer is phanes doc-index. Many readers, one writer.
• No direct code changes by sub-agents, at any tier. A coding agent emits a report that contains a proposed diff, a Critic reviews it, and the Executor applies it. The depth of the review scales with the tier, but the review itself is never skipped. The primary Claude Code agent does not edit code directly either. It orchestrates. Every Critic review closes with two mandatory verdicts, one for spec compliance and one for quality, and a report that is missing either verdict is returned unread.
• No UI approval by prose. A UI proposal has to declare its target viewports and reference designs up front. After the change is applied, a designated visual verifier captures before and after screenshots and runs an explicit pass or fail checklist. "Looks good" is not evidence. When the capture tooling is missing or broken, the failure is diagnosed, remembered for later sessions, and the result is marked as visually unverified rather than passed silently.
• Context injection over context inheritance. A sub-agent receives only the slice of context that its tier allows, and it pulls bulky material through read-only scout digests instead of loading it raw. Pollution from a sibling task is structurally impossible.
• Bounded fan-out. No more than 5 sub-agents run at once, whatever the harness would allow. A genuinely wider sweep is handed to the harness's own large-scale orchestration by recommending it to you, never by an orchestrator quietly multiplying its own fan-out. Every session summary records the run's fan-out ledger.
• Compaction survival. Long sessions compact, and a summarized mandate is a forgotten mandate. A run keeps a phase-by-phase progress ledger on disk and resumes from it after a mid-flight death. A run that can no longer see the spec's exact text re-reads it from disk instead of executing a lossy summary of itself.
• Index-first documentation navigation. No agent ever bulk-reads documentation/. It descends the indexes, loads the target, and reads nothing else.

For inexperienced users: step-by-step from zero

Never used Claude before? This takes you from no account at all to a running Phanes install. Experienced Claude Code users can skip straight to How to install below.

Step 1: Create a Claude account

Go to claude.ai and sign up with an email or a Google account.

Step 2: Get a plan that can carry Phanes

Phanes is a multi-agent system. A single task can run chains of several Claude instances, such as a planner, a coder, a critic, an executor, and a monitor, and each of them uses part of your allowance. The Pro plan is not enough, since its limits run out after a few chains. You need one of these:

• Claude Max 5x, the workable entry point for lighter projects.
• Claude Max 20x, recommended, with comfortable headroom for real multi-agent work. Subscribe under Settings, then Plan, at claude.ai.
• Claude API, pay per token. Create an account at console.anthropic.com and add credits. Be aware that multi-agent orchestration uses far more tokens than ordinary chat, and the cost scales with how hard you drive it.

Check current pricing on the official pages, since plans and limits change.

Step 3: Install Claude Code

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

If you already use Node.js 18 or newer, you can instead run npm install -g @anthropic-ai/claude-code. Make sure git is installed too (git-scm.com), because Phanes requires it.

Verify the install with:

claude --version

Step 4: Sign in

Open a terminal in any project folder, run claude, and follow the login prompt, or type /login. Choose Claude account if you subscribed to Max, or Anthropic Console if you are paying per token through the API.

Step 5: Install Phanes

Continue with How to install directly below. It is two commands.

How to install

Phanes is a single Markdown file, phanes.md, so installing it just means putting it where Claude Code can run it as a slash command.

Prerequisites

• Claude Code, installed and authenticated.
• git, plus whichever language toolchain your project actually uses.
• On Windows, PowerShell (5.1 or newer, which ships with Windows). The Phase 0 pre-flight runs its install commands through PowerShell there. POSIX systems use any standard shell.
• Optional but strongly recommended: uv, which runs both the serena and semble MCP servers. The Phase 0 pre-flight installs it for you if it is missing.

Install as a user-level slash command (recommended)

This makes /phanes available in every repository you open.

Linux / macOS:

mkdir -p ~/.claude/commands
curl -L https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md \
  -o ~/.claude/commands/phanes.md

Windows (PowerShell):

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands" | Out-Null
Invoke-WebRequest `
  -Uri https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md `
  -OutFile "$env:USERPROFILE\.claude\commands\phanes.md"

Install per project (alternative)

If you only want Phanes inside one repository and want it tracked in version control:

mkdir -p .claude/commands
curl -L https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md \
  -o .claude/commands/phanes.md

Run it

Open the target repository in Claude Code, then type:

/phanes

Anything you add after the command is forwarded through $ARGUMENTS and takes priority over the default plan, so you can steer the run:

/phanes focus on the api/ module; skip pre-commit hook install

The first run takes several minutes. It pauses to confirm a few choices, such as module boundaries and hook install, and ends by asking you to restart the session so the enforcement hooks arm. Later runs are faster, since only the differences are written.

What gets created on the first run

your-repo/
├─ documentation/        # project memory, navigated by index, never bulk-read
│  ├─ _index.md          #   generated index (sole writer: phanes doc-index)
│  ├─ session-summaries/ #   SS0000N run records
│  ├─ plans/             #   dated implementation plans
│  ├─ snapshots/         #   dated architecture snapshots
│  └─ registry/          #   curated API registry (sole writer: Architect)
├─ tests/                # unit · integration · e2e · fixtures · helpers
├─ .phanes/              # scripts, config, and machine-owned state
│  ├─ scripts/           #   cli.js (cross-shell entry) · new-file · doc-index · loc/doc/register-check · hook-*
│  ├─ registry/          #   generated API baseline (sole writer: close-verifier)
│  ├─ config.json        #   confirmed modules · language · build system
│  └─ run-progress       #   phase ledger for crash / compaction resume
├─ .claude/              # harness wiring
│  ├─ agents/            #   6-10 deeply scoped expert personas
│  ├─ workflows/         #   YAML agent chains: the single source of truth
│  ├─ settings.json      #   stamp-guard (blocking) + size-check (advisory) hooks
│  ├─ template/          #   report.md used by every sub-agent
│  └─ .phanes            #   run counter + install-state marker (hidden)
├─ CLAUDE.md             # root: orchestration mandates; modules: local guidance
└─ CLAUDE.local.md       # live register of work in motion (35k/40k char budget)

The default .gitignore shipped with this repository excludes .claude/, .phanes/, and other runtime artifacts. Adjust it to taste in your own project.

Upgrading an older install

If a project already carries an older Phanes installation (any version), install the upgrader alongside /phanes:

Linux / macOS:

curl -L https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpgrade.md \
  -o ~/.claude/commands/phanesupgrade.md

Windows (PowerShell):

Invoke-WebRequest `
  -Uri https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpgrade.md `
  -OutFile "$env:USERPROFILE\.claude\commands\phanesupgrade.md"

Then open the project and run /phanesupgrade. It refreshes your /phanes command, detects the installed version, plans the jump from the changelog, and computes exactly what to archive, generate, and regenerate from the installed-artifact manifest. Everything runs on a dedicated phanes-upgrade-<date> branch behind an evidence-verified checklist. Your accumulated knowledge is preserved byte for byte, superseded artifacts are archived rather than deleted, and you review and merge the branch yourself. The only precondition is a clean git status.

You normally get here from /phanes itself: whenever a newer Phanes has shipped, the version check at the start of every run offers the upgrade and routes you here.

Companion tools

Phanes is built to stay modular. Rather than growing the core file, capabilities beyond bootstrapping ship as companion tools. Every companion is a full standalone tool that works on its own, in any repository, with no Phanes install. Each one is also built to cooperate with the structures Phanes generates, so together they form one ecosystem.

• Charon finds dead code, unused files, unused dependencies, and duplicated code, then writes an evidence-backed audit report without touching anything. Standalone /charon command for any repository; in a Phanes-managed project the report is filed into the documentation tree, open items land in the session summary, and dead exported APIs are proposed as registry annotations. Worth running before large refactors, since stale code is context poison for agents.
• Philia shares a Windows terminal in the browser for collaborative or remote vibecoding: a password-protected public link, shared terminal tabs, and a side chat, tunneled from your own PC with nothing for guests to install. Share a Phanes-managed project and everyone drives the same agent team together, while the host keeps a kill switch and a live indicator.
• Mosyn gives Claude Code agents a shared, disciplined project memory on decentralized storage (Walrus and SEAL): recall before acting, decision and failure logging, and schema-locked session distillation with an append-only audit trail. Alongside Phanes it hands the whole agent team one durable memory across sessions, machines, and teammates.
• Metis reads Claude Code's own run transcripts and reports whether your agent team actually used the tools and workflows it was told to, harvesting the short-lived subagent transcripts before the harness discards them. Standalone /metis command; in a Phanes-managed project the capability census detects it, and update runs have it verify past suggestions and file an adherence report the run acts on.

Recommended third-party enhancements

Phanes never installs these. The capability census discovers them only if you installed them yourself, and the matching rubric wires them into exactly the agents whose duties they serve, under least privilege and never as a hard dependency. All were verified as actively maintained on 2026-07-15, so re-check before adopting one. Code search is absent because Phanes installs semble itself; a rival code-index server is granted only where it beats semble for your stack, and then in its place, since one job should carry one schema tax.

• Shell-output compressors (for example RTK) run as a PreToolUse proxy that strips noise from build, test, and git output before it reaches any agent's context, while preserving errors and diffs in full. In measurements from July 2026 this removed about 89 percent of the noise on average. It helps every agent that runs shell commands and needs no Phanes wiring at all.
• Usage monitors (for example claude-hud and claude-monitor) show live context fill and rate-limit forecasting alongside long multi-agent runs. They are purely observational and cost no tokens, which makes them useful company for any Phanes bootstrap on a subscription plan.
• CLAUDE.md linters (for example cclint) validate the instruction files Phanes generates on the CI side, catching things like deprecated model identifiers, broken imports, and leaked keys.

Version

Current: v3.2.1 (2026-07-26). A small alignment release for the new Claude Opus 5 model. The Model & Effort rubric now names Opus 5 in place of Opus 4.8 at every Opus-tier assignment; the use cases behind those assignments are unchanged, so no installed project needs to be rebuilt. The README also gained a session-effort recommendation, and its workflow diagram now shows where the Orchestrator picks up a multi-step plan.

Beneath it: v3.2 added the top-anchored, delete-protected Pinned Directives block as the first content of every project's root CLAUDE.md, a procedure-precedence rule with a supersession-annotation pass, and the ephemeral Orchestrator that executes long plan runs in self-sized batches so the primary session stays slim enough to run across many phases without compacting; v3.1 gave Phanes its real upgrade path, routing version jumps to /phanesupgrade (plan from the changelog, exact file operations from an installed-artifact manifest, on a branch you merge yourself) and prefixing agents with the project slug; v3.0.1 corrected the reasoning-effort rubric and added the CLI-spawn bridge for per-agent effort; v3.0 added the capability consent layer, the close-verifier rename, and the cross-shell cli.js launcher. The full release history is in Changelog.md, and every superseded version is archived verbatim in older version/.

License

Phanes is released under the Creative Commons Attribution-NonCommercial 4.0 International license (see LICENSE).

You are free to use, share, and adapt Phanes for any non-commercial purpose with attribution. Commercial use is not granted by this license. For commercial licensing terms, contact the author directly.

Contributing

Issues and pull requests are welcome. A substantive change to phanes.md should explain which class of failure mode it closes, because Phanes is a defensive document and every clause is load-bearing.