phanes

# Phanes **Phanes** is a bootstrap prompt for [Claude Code](https://claude.com/claude-code) that turns an empty (or chaotic) repository into a fully-wired, opinionated, multi-agent development environment in one command. It is not a tool you install once and forget. It is a *re-runnable specification*: each time you invoke `/phanes`, it re-surveys the project, upgrades existing sub-agents, fills in missing infrastructure, and increments a hidden run counter. The result is an agentic ecosystem that evolves with the codebase rather than rotting alongside it. **Everything in one file.** The entire system is one Markdown file (`phanes.md`); every script, hook, agent, and document it relies on is generated by the run itself, inside your repository. **Which file do you need?** | Your situation | Use | | --- | --- | | Fresh project, or a project with **no** Phanes yet | **`phanes.md`** → `/phanes` for the full bootstrap. Re-running it also keeps a current-version install upgraded in place. | | Project already carrying an **older** Phanes (e.g., a v1 install) | **`PhanesUpdateExperimental.md`** → `/phanesupdate` for version migration. ⚠️ **EXPERIMENTAL, and effectively irreversible once the migration branch is merged; a full backup is mandatory (see "Migrating an older install" below).** It first refreshes your installed `/phanes` command from this repository so you migrate onto the newest spec, then upgrades the project's entire Phanes structure (agents, scripts, hooks, workflows, documentation tree) behind a strict, generated, per-item-verified checklist. Accumulated knowledge (session summaries, tier 2 annotations, snapshots) is preserved and indexed, never rewritten. | **Contents** - [What it does](#what-it-does) - [How to use](#how-to-use) - [Core principles enforced by Phanes](#core-principles-enforced-by-phanes) - [For inexperienced users: step-by-step from zero](#for-inexperienced-users-step-by-step-from-zero) - [How to install](#how-to-install) - [Migrating an older install (⚠️ experimental)](#migrating-an-older-install-experimental) - [Companion tools](#companion-tools) - [Version](#version) · [License](#license) · [Contributing](#contributing) --- ## What it does When you run `/phanes` in a repo for the first time, the prompt drives Claude Code through a strict, multi-phase setup: 1. **Pre-flight.** Installs the three MCP servers it benefits from: `context7` (live library documentation on demand), `deepwiki` (digest answers about external GitHub dependencies, so agents never pull dependency source into context), and, on the first run, `serena` (symbol-level code navigation) via `uv`, which it also installs if missing. These are enhancements, not hard dependencies; a failed install is logged as a TODO and the run continues degraded rather than halting. Exactly three, deliberately: MCP tool schemas cost context every session, so every generated agent carries a usage rubric stating when each server saves tokens and when to make no MCP call at all. Platform is detected first: bash on POSIX, PowerShell on Windows. 2. **Repository comprehension.** Reads the README, source tree, configs, and CI to infer the project's *true* purpose, primary language, build system, and module boundaries. Extraneous directories (vendored deps, example packs, demo content) are filtered out. 3. **Project memory infrastructure.** Scaffolds the substrate every sub-agent operates against: - `documentation/`: session summaries, plans, dated architecture snapshots, and a two-tier API registry (tier 1 generated, tier 2 curated annotations). Every folder carries a **generated `_index.md`**, so agents locate knowledge by descending indexes (a few hundred tokens) instead of scanning trees. Files respect a 500-line soft ceiling and are split-with-index when they outgrow it. - `tests/`: `unit/`, `integration/`, `e2e/`, `fixtures/`, `helpers/` with a verbatim README and the same `phanes new-file` header-stamp discipline as `src/`. - `.phanes/scripts/`: a script library that owns *all* mechanical rules, from file creation with header stamps and line-of-code checks to doc-ceiling audits (`doc-check`), index regeneration (`doc-index`), registry regeneration, API diffs, and module listing. - **`.claude/settings.json` hooks**: mechanical rules enforced at the harness layer. A blocking PreToolUse guard denies creation of unstamped new files, and an advisory PostToolUse check runs size and documentation audits on every write. Prompts forget under context pressure; hooks cannot. - `.phanes/config.json`: confirmed module list, language, build system, hook prefs. 4. **Tiered workflow definition.** Every task is triaged into T1 (single-file quick fix), T2 (single-module feature), or T3 (cross-cutting). 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 the diff; only review depth and documentation weight scale with tier. Promotion mid-task requires halting and asking the orchestrator. 5. **Sub-agent roster generation.** 6–10 deeply-scoped, world-class personas written to `.claude/agents/*.md`, each assigned a model by a dated rubric that is re-validated on every update run: - **Architect/Designer**, the *sole writer* of tier 2 registry and architecture snapshots. - **api-monitor**, the *sole writer* of tier 1 registry; it runs after every structural change. - **Critic agents**, producing numbered, ID-tagged audit reports. - **Patch-Author**, which turns the synthesized, 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-perspective outputs into one unified plan. - Plus Analyzer, Planner, Validator, Optimizer, Integrator, Monitor, and Cleaner variants tuned to your specific stack. - **Scouts** are not roster agents: specialists spawn them ad hoc as *read-only* subagents that fetch and digest bulky one-time context (module surveys, test logs, registry sweeps), governed by a strict cost guard so a spawn always pays for itself in preserved specialist context. 6. **Workflow codification.** `.claude/workflows/` YAML is the single source of truth for chaining; every chain terminates Synthesizer (parallel work only) → Critic → `api-monitor` (T2/T3) → primary, so the artifact that gets applied is always the artifact that was audited. `CLAUDE.md` (project root and module roots only) is updated so the primary agent knows how to triage, delegate, navigate documentation by index, and review. 7. **Bootstrap session summary.** `documentation/session-summaries/SS00001_phanes-bootstrap_<date>.md` records the install, the confirmed module list, the agent roster, and any deferred TODOs. > **After the first run: restart your Claude Code session.** Hook configuration is snapshotted at session start, so the enforcement hooks arm on the *next* session. Phanes reminds you of this verbatim at the end of the run. Re-runs detect the existing install via the `.claude/.phanes` marker and upgrade in place: agents, workflows, scripts, hooks, and READMEs are evaluated against the latest version of `phanes.md` and refreshed where they have drifted. Installations created by v1 are detected and routed to the experimental updater (see [Migrating an older install](#migrating-an-older-install-experimental)). ## How to use ### First run Type `/phanes` in your project. It scans the repository and sets up the entire agentic team and documentation structure around it. Two things make the first run land well: - **Give it something to read.** On an empty or brand-new repository, create at least a `plan.md` describing what you want to build. Phanes reads it to understand the project's purpose and shapes the whole setup (agents, workflows, module layout) around the project you actually intend to build, not around an empty folder. - **Steer it, if you like.** Anything you type right after the command is treated as directives and takes priority over the defaults, so you can inject your individual needs into the setup: `/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). ### Re-running `/phanes`: when, and how often Think of `/phanes` as *refreshing Claude's knowledge of your project*: every run re-surveys the codebase and brings the agent team, workflows, and 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** *(a good soft strategy, not a rule)*: write your implementation plan (say, for a new module), then run `/phanes` and inject the plan. Injecting simply means prompting the plan's contents (or its path) right after the command. Phanes updates the agents and workflows, creating new ones where needed, so the team is tuned to execute exactly that plan flawlessly when you start. - **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 *large* implementation plans; smaller ones usually don't 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 (LOC limits, header stamps, registry edits, API diffs, doc ceilings) lives in `.phanes/scripts/`; the two settings.json hooks make the critical ones unskippable. Mechanical rules in prompts get forgotten under context pressure; scripts don't forget; hooks can't be forgotten. - **Single-writer per artifact.** Every registry tier, snapshot, and summary has exactly one writing agent, and so does every generated `_index.md` (`phanes doc-index` is their sole writer). Many readers, one writer. - **No direct code modification by sub-agents, at any tier.** Coding agents emit a report containing a proposed diff; a Critic reviews it; the Executor applies it. Review depth scales with tier; its presence is never waived. The primary Claude Code agent does not edit code directly either; it orchestrates. - **Context injection over context inheritance.** Sub-agents receive only the slice of context their tier permits, and pull bulky material through read-only scout digests instead of loading it raw. Pollution from sibling tasks is structurally impossible. - **Index-first documentation navigation.** No agent bulk-reads `documentation/`: indexes are descended, targets loaded, nothing else. --- ## For inexperienced users: step-by-step from zero Never used Claude before? This takes you from no account to a running Phanes install. Experienced Claude Code users can skip straight to ["How to install"](#how-to-install) below. ### Step 1: Create a Claude account Go to [claude.ai](https://claude.ai) and sign up (email or 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 (planner, coder, critic, executor, monitor), and each consumes usage. **The Pro plan will not suffice**; its limits are exhausted after a few chains. You need one of: - **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 → Plan at claude.ai. - **Claude API (pay per token)**: create an account at [console.anthropic.com](https://console.anthropic.com), add credits, and be aware that multi-agent orchestration uses substantially more tokens than single-chat usage; costs scale with how hard you drive it. (Check current pricing on the official pages; plans and limits change.) ### Step 3: Install Claude Code **macOS / Linux:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows (PowerShell):** ```powershell irm https://claude.ai/install.ps1 | iex ``` (Alternative: `npm install -g @anthropic-ai/claude-code` if you already use Node.js 18+.) Also make sure `git` is installed ([git-scm.com](https://git-scm.com)); Phanes requires it. Verify 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're paying per token via the API. ### Step 5: Install Phanes Continue with ["How to install"](#how-to-install) directly below. It's two commands. --- ## How to install Phanes is a single Markdown file (`phanes.md`), so installation just means putting it where Claude Code can invoke it as a slash command. ### Prerequisites - [Claude Code](https://claude.com/claude-code) installed and authenticated. - `git`, plus whichever language toolchain your project actually uses. - **Windows: PowerShell** (5.1 or newer, 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` (for the `serena` MCP server). The Phase 0 pre-flight will install it for you if missing. ### Install as a user-level slash command (recommended) This makes `/phanes` available in every repo you open. **Linux / macOS:** ```bash mkdir -p ~/.claude/commands curl -L https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md \ -o ~/.claude/commands/phanes.md ``` **Windows (PowerShell):** ```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 repo and want it tracked in version control: ```bash 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 ``` Optional arguments are forwarded through `$ARGUMENTS` and prioritized 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, will pause to confirm a few choices (module boundaries, hook install), and ends by asking you to restart the session so the enforcement hooks arm. Subsequent runs are faster; only diffs are written. ### What gets created on first run ``` documentation/ # session summaries, plans, snapshots, registries; every folder indexed by a generated _index.md tests/ # unit, integration, e2e, fixtures, helpers .phanes/ # scripts (new-file, regen-registry, api-diff, loc-check, doc-check, doc-index, hook-*) and config .claude/agents/ # generated sub-agent definitions (6-10, deeply scoped) .claude/workflows/ # codified multi-agent workflows (YAML, the single source of truth for chaining) .claude/settings.json # merged hook entries: hook-stamp-guard (blocking) + hook-size-check (advisory) .claude/template/ # report.md template used by every sub-agent .claude/.phanes # run counter & install-state marker (hidden) CLAUDE.md # root: primary-agent mandates; module roots: folder-specific guidance CLAUDE.local.md # live register of projects in motion (gitignored by convention) ``` `.claude/`, `.phanes/`, and other runtime artifacts are excluded by the default `.gitignore` shipped with this repo. Adjust to taste in your own project. --- ## Migrating an older install (EXPERIMENTAL) > ⚠️ **PhanesUpdate is experimental. It has not been validated against real-world installations; treat a migration as effectively irreversible once the migration branch is merged.** Before running it: commit or stash everything, push your repository to a remote (or take a full copy of the project folder), and proceed only on a project you can restore from that backup. The prompt refuses to start until you acknowledge this. If a project already carries a pre-v2.0 Phanes installation, install the updater alongside `/phanes`: **Linux / macOS:** ```bash curl -L https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpdateExperimental.md \ -o ~/.claude/commands/phanesupdate.md ``` **Windows (PowerShell):** ```powershell Invoke-WebRequest ` -Uri https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpdateExperimental.md ` -OutFile "$env:USERPROFILE\.claude\commands\phanesupdate.md" ``` Then **back up your project**, open it, and run `/phanesupdate`. It self-updates your `/phanes` command from this repository, fingerprints the installed version, and migrates the structure on a dedicated branch behind a generated, evidence-verified checklist, preserving your accumulated knowledge (tier 2 annotations, session summaries, snapshots) byte-for-byte. Superseded artifacts are archived, never deleted. You review and merge the branch yourself: **verify it thoroughly before merging, because the merge is the point of no return**. --- ## Companion tools - **[Charon](https://github.com/Aloim/charon)** finds dead code, unused files, unused dependencies, and duplicated code, then writes an evidence-backed audit report without touching anything. It is a standalone `/charon` command that works in any repository; in a Phanes-managed project it additionally cooperates with the structures Phanes builds: the report is filed into the documentation tree, open items land in the session summary, and dead exported APIs are proposed as registry annotations so the agent team stops routing new work onto them. Recommended before large refactors and after big migrations, since stale code is context poison for agents. --- ## Version Current: **v2.1** (2026-07-10). See the version stamp at the top of `phanes.md`. Full release history: [`Changelog.md`](Changelog.md). The previous published version is preserved verbatim in [`older version/phanes.md`](older%20version/phanes.md). --- ## License Phanes is released under the **Creative Commons Attribution-NonCommercial 4.0 International** license (see [`LICENSE`](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. Substantive changes to `phanes.md` should explain *which class of failure mode* the change closes: Phanes is a defensive document, and every clause is load-bearing.