vulyk

---

Vulyk (Ukrainian: вулик) means beehive. A hive does not send the queen to gather pollen. It routes every job to the cheapest unit that can do it well, keeps shared memory outside any single bee, and continuously adapts the colony to the season. VULYK applies the same economics to AI-assisted software development:

• Queen — your main Claude Code session, on Opus on every plan. Plans; builds Tier 1–2 work herself; at Tier 3–4 decomposes, dispatches and integrates.
• Leads — lead-review, one fresh-context reviewer per council round (Opus; at Tier 4 the gate model beside a second reviewer), and lead-architect for design decisions. The gate model is the strongest one your plan carries: Fable on Max, Opus on Pro, resolved from the account, not remembered.
• Workers — Sonnet subagents that implement one story each at Tier 3–4, in parallel waves, and close it themselves. The family that builds never judges.
• Drones — cheap subagents (Sonnet at low effort for recon and docs, Opus for memory upkeep and the coverage check).

Routing names families, never versions: every alias brings the newest model, and a floor (fable 5.1 · opus 5.5 · sonnet 5.5 · haiku 5.5) is checked before and after each session so nothing silently runs older.

The result: more parallel agents, larger codebases, and — the point of the whole exercise — a strong model that stays inside the task it was given. Every story names the files it may touch, and a deterministic gate reports the ones it touched anyway.

Why VULYK exists

Four failure modes show up in every serious Claude Code setup:

1. Token burn. Running every task on the top model exhausts session and weekly limits long before the work is done. Routing is the single biggest cost lever in Claude Code — most setups never touch it.
2. Large codebases make agents dumber. Past ~100k LOC, stuffing context windows stops working. A 1M-token window is a trap, not a solution: quality degrades while costs explode. The fix is external memory — maps, wikis, and pointer indexes the agent consults instead of re-reading the world.
3. Static configs rot. Skills, rules, and agent prompts written in week one are stale by week six. Without a feedback loop, your setup never learns from its own mistakes.
4. Gates go stale where nobody looks. A check runs, reports green, and then the thing it checked moves — a repair story is cut, a file list changes, the pack grows — and nothing re-runs it. The green is still on the record, now describing work that never shipped. This is not a bug in any gate; each one did its job at the moment it was asked. It is the gap between a check ran and a check ran against this, and it is invisible precisely because the artifact looks finished. VULYK hit it twice in one day of real use: an acceptance verdict recorded against a six-story pack that shipped with nine, and a repair round dispatched against a collision check nobody re-ran. Both were caught by reading the artifact afterwards, which is not a mechanism.

VULYK answers all four with one coherent system: a complexity-routing matrix that picks the model tier before work starts, a memory plane (pointer index → codebase map → LLM wiki → learnings) that lives in git instead of in the context window, and an evolution cycle (/vulyk-evolve) that turns session learnings into reviewable pull requests against your own configuration — skills are born, updated, and retired with full git audit history. Against the fourth it holds one rule, made deterministic rather than remembered: when the pack moves, whatever judged it is re-run. Every acceptance verdict records a fingerprint of the stories it judged, acceptance-log.sh --check answers CURRENT / STALE / NO VERDICT RECORDED before a merge is proposed, and a repair round re-runs the story gate instead of intersecting file lists by hand.

Built on native primitives only

VULYK uses only official Claude Code mechanisms: subagents, slash commands, skills, hooks, rules, and (optionally) Agent Teams. No SDK harness, no proxy, no third-party runtime. That means:

• ✅ Fully compatible with Pro / Max subscription plans under Anthropic's third-party tooling policy (effective April 4, 2026) — every API call is made by the official Claude Code client.
• ✅ Survives ecosystem policy changes — there is nothing here that can be cut off.
• ✅ Zero installation beyond copying files into your repo.

How VULYK compares

Approach	Model usage	Memory at scale	Learns over time	Runtime dependency
Single top model, one session	Everything on the strongest model — burns limits fastest	Context window only — degrades past ~100k LOC	No	None
SDK / proxy orchestrators	Programmable, but routing is your code to write	Whatever you build	Whatever you build	Custom runtime — breaks when the ecosystem shifts; often outside subscription policy
Generic subagent prompts	Mixed; tiering is ad-hoc and easy to drift	Usually none	No	None
VULYK	Routing-matrix cascade: queen/leads/workers/drones by tier, enforced in config	Git-based external memory plane (index → map → wiki → learnings)	Yes — /vulyk-evolve proposes config diffs as reviewable PRs	None — native Claude Code primitives only, subscription-safe

When VULYK is overkill: a small repo (< ~20k LOC), a one-off script, or a throwaway prototype. The cascade earns its keep when token limits, codebase size, or config drift actually hurt — typically a real, growing codebase you return to week after week.

Quickstart

Option A — new project from template

# Use this repository as a GitHub template (button above), then:
cd your-new-project
claude
> /vulyk-bootstrap

Option B — add to an existing project

git clone https://github.com/Black-coffe/vulyk /tmp/vulyk
/tmp/vulyk/install.sh /path/to/your/project
cd /path/to/your/project
claude
> /vulyk-bootstrap

Upgrading an existing install

git -C /tmp/vulyk pull
/tmp/vulyk/install.sh /path/to/your/project --upgrade   # add --check to preview

--upgrade replaces changed framework-owned files (agents, commands, hooks, templates, scripts), removes retired ones you never edited, and touches nothing of yours — not your constitution, memory, specs, ADRs or wiki. The installed version is stamped in .claude/vulyk-version. When the constitution changed, the upgrade prints the size difference and the command that replaces it — install.sh /path/to/your/project --upgrade --constitution replace — which carries your Profile and Commands blocks over and keeps the old file as <name>.pre-0.18.md. Upgrading from 0.17 or earlier, the replace is what brings the smaller constitution into every agent that loads it.

/vulyk-bootstrap runs a short interview (stack, size, conventions, risk tolerance, token budget), then tailors the constitution, prunes the agent roster, builds an initial codebase map with scout drones, and seeds the wiki. From that point on you work through three commands:

/vulyk-plan  "add OAuth login with refresh tokens"   # Queen plans, scouts recon, stories written
/vulyk-build                                          # Tier 1-2: the Queen builds; Tier 3-4: workers in parallel waves
/vulyk-ship                                           # after a green council: merge locally, print the publish command

Tip: enable Anthropic's experimental Agent Teams for collaborative Tier 3–4 work: echo "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1" >> ~/.claude/.env

The model cascade

Every subagent declares its model in YAML frontmatter — the cascade is enforced by configuration, not willpower:

Caste	Agent	Model	Job	Reads source?
👑 Queen	(main session) + queen-planner	opus; a Tier 4 queen-planner gets TOP_MODEL	Plan; build Tier 1–2 herself; at Tier 3–4 decompose, dispatch and integrate	Tier 1–2: the story's files; Tier 3–4: scout reports and memory
🛡 Lead	lead-architect	TOP_MODEL	Design decisions, ADRs, tradeoff analysis	Targeted excerpts only
🛡 Lead	lead-review	opus at Tier 1–3; TOP_MODEL at Tier 4	The reviewer seat of every round: the brief's asks and correctness; BLOCK only on an anchored finding	The round's diff
🛡 Lead	second reviewer, Tier 4	a different model: opus beside Fable, sonnet beside Opus on Pro	Recall complement — an ensemble, not a duplicate	The round's diff
🐝 Worker	worker-code	sonnet (the story's model:) · effort medium	Tier 3–4: implement exactly one story and close it	Scoped slice via map
🐝 Worker	worker-test	sonnet (the story's model:) · effort medium	Tier 3–4: write or repair the tests of one story and close it	Scoped slice
🔍 Drone	drone-scout	sonnet · effort low	Recon: files, symbols, structure → map-format report	Yes — that's the point
🔍 Drone	drone-docs	sonnet · effort low	Update wiki & map notes after changes	Diffs
🔍 Drone	drone-horizon	sonnet · effort medium	Tier 2–4 on new ground: one lens (altitude, depth, range) → at most three proposals with cost, an outside check and dated sources; three run in parallel, the Queen cuts, the owner picks	A few files, only to check a proposal fits; the brief and the web are data
🔍 Drone	librarian	opus · effort low	Memory consolidation & garbage collection	Memory files only
🔍 Drone	drone-coverage	opus · effort medium	Plan-time coverage check: brief vs plan, blind to the stories	Never — brief + plan only
⚖️ Council	council-opus / council-haiku	opus · effort medium / opus (it judges; the name is the angle) — Tier 3–4 only; haiku only when the Profile's Client path is filled	Blind verdict on the brief's ## Asks, from a reduced worktree — intent & edge cases / black-box client path	Only what a client would see — never the stories
⚖️ Council	cycle-clerk	haiku · effort low (Haiku 5.5 and up, since 0.26.0; sonnet before)	The Workflow driver's only shell access — one cycle.sh advance per agent boundary, no logic of its own	Never
🛡 Lead	any story's second attempt	TOP_MODEL	A story a Sonnet worker missed is retried on the gate model: Fable on Max, Opus on Pro and API — always a different family (ADR-015)	Scoped slice

The gate model follows the plan. TOP_MODEL = auto in the constitution, and scripts/top-model.sh reads the account profile Claude Code keeps in ~/.claude.json: Max 5x / 20x and premium seats resolve to fable, which those plans carry at no extra cost up to half the weekly limit; Pro, standard seats and API keys resolve to opus — on those, every Fable token bills to usage credits on top of the subscription. A SessionStart hook announces the result, and /vulyk-plan, /vulyk-build, /vulyk-review and the Workflow driver pass it as the dispatch model: to the Tier 4 review, lead-architect, a Tier 4 queen-planner and a missed story's retry; lead-review below Tier 4 runs on its frontmatter opus (changed in 0.18.0, ADR-013). --apply pins the Queen's own session to opus: since v0.16.0 she orchestrates on Opus on every plan. The gate agent files keep opus as their floor because frontmatter cannot be conditional and must be right on every plan. Pin an alias in place of auto to overrule the plan. Why not the native best alias: it resolves to Fable wherever it is available, and on Pro it is available — for credits. docs/model-cascade.md has the table and the rejected alternatives.

The ladder (v0.20, ADR-015). Four families, cut by kind of work. The family that builds never judges; the one recorded gap is the Tier 4 second reviewer on Pro and API, which is Sonnet beside an Opus gate.

• Fable = the gate, TOP_MODEL: the Tier 4 review, lead-architect, the Tier 4 planner and retries. Fable on Max, Opus on Pro.
• Opus = judgment: the Queen, the planner, lead-review at Tier 1–3, council-opus, the black-box seat, drone-coverage and librarian.
• Sonnet = execution: the workers (a story's default model:), drone-scout, drone-docs and drone-horizon.
• Haiku = mechanical: only the clerk, and only at or above the floor (Haiku 5.5, since 0.26.0).

On Sonnet 5.5 launch day (2026-09-28), Anthropic's own table had Sonnet 5.5 ahead of Opus 5.5 on Terminal-Bench (70.6% against 66.4%) and behind it on the hardest coding and reasoning, at half the price per token. docs/model-cascade.md has the numbers and what would reverse the cut.

Three profiles (v0.30, ADR-020). The ladder above is the sonnet-builds profile, the default. opus-builds ("Opus writes, Fable judges") has Opus write, Fable plan big tasks and judge all code, and Haiku take routine stories. economy uses no Fable: Sonnet writes, Haiku takes routine stories, Opus judges. The choice is one word in one file per machine that upgrades never touch. Run /vulyk-models (or say "change model distribution", "model profile", «поменяй распределение моделей») to choose; it can be changed any time.

Aliases, and a floor under them. fable, opus, sonnet and haiku resolve to the newest model in each family, so a new generation arrives without an edit. An alias is not a guarantee: on Bedrock, Google Cloud and Foundry it resolves lower, six env vars can remap it, and the alias table ships inside Claude Code (2.1.292 still ran haiku as Haiku 4.5; 2.1.293 runs 5.5). So VULYK keeps a floor, one line in scripts/lib.sh (fable 5.1 · opus 5.5 · sonnet 5.5 · haiku 5.5, the haiku line marked cc>=2.1.293). bash scripts/top-model.sh --floor checks env, settings, provider, frontmatter and the running Claude Code's version before the fact. The telemetry code model_below_floor records any transcript that actually ran below it. Pin a full ID only to freeze behaviour deliberately.

Effort is set per agent. Since Claude Code 2.1.280, effort: in agent frontmatter overrides the session level. In July 2026 it was silently ignored; both results were measured. Drones and the clerk run at low, workers and the intent seat at medium (on Sonnet that is Anthropic's advice for well-specified agentic coding), the planner and the reviewer at high. A top-level effort level in settings.json does not apply to Opus 5.5, so VULYK sets none. docs/model-cascade.md has the numbers and the escalation table.

The routing matrix

Routing happens before any work starts — and the first question is not the tier but the deliverable: a request whose answer is a document (an audit, a monitoring report, "make me a spec") is study work and ends at report.md, never in stories (ADR-008). Only code gets a tier (the matrix lives in CLAUDE.md, so it is enforced on every prompt):

Tier	Signal	Who works	Council per round
0	Trivial, single file, obvious	The Queen directly, no paperwork	none
1	One module, clear task	The Queen, solo — no driver, no clerk	one lead-review; 1 round
2	Feature within a module	The Queen, solo, in a fresh session after the plan is approved	one lead-review; 2 rounds
3	Cross-cutting, multi-module	Workers in waves through the Workflow driver	council-opus + lead-review (+ council-haiku with a Client path); 3 rounds
4	Architecture / migration / 200k+ LOC touched	Tier 3 + lead-architect	as Tier 3, the review folded from two reviewers on different models; 3 rounds

One agent below Tier 3 (changed in 0.18.0, ADR-013). A token audit over 1,844 sessions found a median task dispatching 67 subagents, 43 of them clerks, with spend split into near-equal thirds between the Queen, the workers and the review machinery. Separate agents for planning, building and reviewing a one-module change cost more coordinating than working, so below Tier 3 one session builds and one fresh-context reviewer judges. Bookend rule: the top model is spent where it changes everything downstream — the Tier 4 plan and review, design, and a missed story's retry.

The build discipline

Since v0.5.0, the middle of the pipeline — where the tokens are spent and where parallel agents historically eat each other's work — runs under rules absorbed from Autopilot (MIT, © Nick Vels), re-grounded in VULYK's deterministic-gates philosophy:

• Waves. Every story carries wave: and blocked_by: frontmatter. One wave = one message, all its workers genuinely concurrent. Stories in a wave must declare disjoint ## Files — scripts/wave-check.sh verifies that (plus blocker order and dangling references) before anything is dispatched. Zero tokens, zero model: two concurrent workers on one file silently overwrite each other, and this is the check that makes it impossible to miss.
• One story, one commit. Whoever built a story — the Queen at Tier 1–2, the worker at Tier 3–4 — closes it with cycle.sh close-story: scope gate → the story's quiet verification, run once, under a 540 s timeout → its own commit. That gives every story a rollback point, and it fixes the scope metric itself — the diff being measured is now exactly that story's, not the pileup of everything before it.
• Bounded returns. A worker's final message is a ≤25-line report (STATUS / FILES / TESTS / INTERFACES / CONCERNS / BLOCKERS) — never a diff, never raw test output. Worker returns live in the Queen's context until the end of the run; this contract is what keeps a 12-story build from drowning the one context that is never refreshed.
• Repair with a ceiling. NEEDS_CONTEXT means the story was defective — fix the plan, not the worker. A worker that misses its story gets one retry on the gate model; a second miss stops the run, and the story goes blocked and back to planning. A RED council round becomes one repair story, written mechanically by cycle.sh repair from the RED asks and the anchored findings — no planner in between.
• The Queen's hands stay off Tier 3–4 story code (Law 5). From the moment a Tier 3–4 story file exists, every edit to its files travels through a worker. Below Tier 3 the Queen builds herself. Descoping mid-build is recorded in ## Descoped, never silent.
• The cycle closes with a council, and the human stops twice at the start: the grill, then the plan. The pipeline is the six-stage loop in docs/cycle.md - spec, plan, code, tests, council, ship - and a stage is closed by its confirmation on disk: brief.md, **Approved:** (the default; **Briefed:** for --go and Tier 1), **Branch:**, council.jsonl, **Shipped:**. /vulyk-plan grills once - a single round, recommended options first, closing into the brief's ## Asks - then shows the plan and waits for one word; nothing is built on a plan the owner has not read (ADR-008). From there the build lives on its own branch, and the council judges only those asks: one fresh-context lead-review at every tier, joined at Tier 3–4 by blind seats (intent and edge cases; the black-box client path where one exists) working from a worktree that cannot see the stories. The verdict is computed by a model-free script, not read off a person's look, and it converges: green seats carry into the next round, and the reviewer re-reads only what changed. /vulyk-ship refuses without a current, GREEN verdict the same way /vulyk-build refuses without a briefed plan, and what it publishes is pressed by a human, never by an agent.
• The request survives verbatim. Every Tier 2+ spec starts with brief.md — the human's words as a blockquote, passed through redact.sh, never paraphrased. Stories quote their ## Requirements from it word-for-word, contracts between concurrent stories are pinned in plan.md at plan time, and scripts/trace-check.sh walks the chain both ways before approval: a story that cannot produce its quote is invented work; a brief line nobody quotes is a requirement about to be dropped. Deterministic, model-free, free.

What changed with Opus 5 is the reason for the bookend, not its shape. The binding problem is no longer that a frontier model is unaffordable — it is that a frontier model does more than it was asked. Anthropic's system card attributes the dip in coding scores at high effort to the model making more changes than the task required. The cascade now earns its keep by holding scope; the savings are a side effect.

Command reference

Command	What it does
/vulyk-bootstrap	Interview → tailored constitution, pruned roster, initial map & wiki seed
/vulyk-plan <goal> [--go] [--study]	Queen mode: deliverable named first (a document ends at report.md), capped recon, a one-round grill (recommended options first, silence safe) closes into the brief's ## Asks, plan + story files written to docs/specs/, then the plan shown for one word of approval; --go builds straight through
/vulyk-build [slug]	Build the plan to a council verdict. Tier 1–2 solo: the Queen builds each story and steps cycle.sh advance, one lead-review per round. Tier 3–4: the Workflow driver runs parallel workers on disjoint files, wave by wave, one commit per story, a missed story retried on the gate model
/vulyk-review [slug]	One council round on demand: lead-review ∥ the tier's blind seats (council-opus, and council-haiku with a Client path, at Tier 3–4), judged by cycle.sh from evidenced reports - RED routes to /vulyk-build as a repair story
/vulyk-pause <slug>	Hand the working tree back to you at any point the loop is running
/vulyk-resume <slug>	Clear the pause and relaunch the driver fresh - never a replayed run
/vulyk-ship [slug]	Stage 06: refuses without a current, GREEN council verdict, then version + CHANGELOG, a local merge, the publish command printed for a human to press, recorded - and the next circle's draft handed over
/vulyk-map [path]	(Re)build the codebase map for a path using parallel scout batches
/vulyk-evolve	Weekly self-evolution: mine learnings, usage stats and the week's token spend → propose config diffs as a reviewable changeset
/vulyk-gc	Memory garbage collection: consolidate learnings, prune stale map entries, archive dead skills
/vulyk-handoff	Save an enriched session handoff to .claude/handoff/ before /clear or a restart — the next session resumes from it automatically
/vulyk-status	Council numbers, token spend per spec (scripts/token-report.py), open stories, memory freshness, skill usage stats, budget posture
/vulyk-update [version]	Show what a newer release would replace or remove, ask, then upgrade the framework files — never your memory or specs; the constitution only when you choose --constitution replace

Full details: docs/command-reference.md

The memory plane

Nothing important lives only in a context window. VULYK keeps five layers in git:

CLAUDE.md            constitution: laws, routing, models, Profile, Commands   (~7 KB, < 120 lines, always loaded)
.claude/rules/       path-scoped rules, loaded only where relevant
memory/memory.md     pointer index (≤ 60 lines, always loaded) → links to everything below
memory/map/          one file per module: purpose, entry points, key types, gotchas, last-verified
docs/wiki/           LLM wiki: one note per domain/invariant, densely linked, Obsidian-compatible
memory/learnings/    session learnings, written when something was worth keeping → fuel for /vulyk-evolve

Two protocols make this safe at scale: memory is a hint, not truth (agents verify pointers against real code before acting), and only the librarian consolidates (workers append, one drone merges — no concurrent-write races). Hooks snapshot state before every context compaction, so nothing is lost to /compact.

Deep dive: docs/memory-system.md

Self-evolution

/vulyk-evolve closes the loop most setups leave open:

1. Harvest — insight-harvester reads memory/learnings/* and your /insights output; skill-gardener reads per-skill usage counters collected by a hook; scripts/token-report.py prints the week's spend per spec.
2. Diagnose — top friction patterns, unused skills (archive candidates), repeated manual patterns (new-skill candidates).
3. Propose — a changeset against .claude/ itself: diffs to rules, agents, skills, plus a CHANGELOG entry justifying each change.
4. Human gate — nothing self-applies. You review the changeset like any PR.
5. Retire — archived skills move to .claude/skills/_graveyard/ with date and reason. History is never lost.

Each cycle is a ratchet: the colony clicks forward and never slips back.

Hooks

Hook	Event	Effect
session-start-brief.sh	SessionStart	Injects memory freshness, and a maintenance due line when gc, evolve or a map refresh is due - the Queen runs them herself
top-model-brief.sh	SessionStart	Announces the gate model the plan resolved to (fable on Max, opus on Pro), the Tier 4 pairing, and whether your session is pinned to opus — reads only, never writes
anomaly-scan.sh	SessionEnd	Runs the anomaly detectors once per session into memory/stats/anomalies.jsonl — local, silent, fail-open (docs/telemetry.md)
skill-usage-counter.sh	PostToolUse (Skill)	Increments per-skill counters → fuel for skill-gardener
context-guard.sh	PreCompact	Snapshots memory & task state before compaction
vulyk-update-check.sh	SessionStart	Compares .claude/vulyk-version against the newest tag on the origin (once a day, cached) and asks the model to raise an upgrade with you — never to apply one
handoff.sh → handoff.py	Stop, UserPromptSubmit, PreCompact, SessionEnd, SessionStart	Context-budget guard + session handoff: measures real context size from the transcript, warns at thresholds, dumps session state to .claude/handoff/ on /clear/exit/compaction, restores it (≤ 4 000 characters) in the session that follows a /clear or a compaction

Claude Code hooks receive no token counter — handoff.py recovers it from the transcript JSONL (message.usage of the last non-sidechain assistant entry), which is what makes proactive warnings and pre-/clear dumps possible at all. The same entry's timestamp gives the age of the prompt cache, so the warning also tells you how long checkpointing stays cheap: re-reading the conversation is a cache hit inside the TTL and a full-price re-prefill after it. Needs Python 3 on PATH; fails open without it. Details: docs/hooks-reference.md

A sample scripts/git-hooks/post-merge flags the map as stale after merges so /vulyk-status reminds you to re-map.

What is measured, and what is not

Most agent frameworks — this one included, until now — ship claims nobody checked. Here is the honest split.

Measured on this repository. Where effort actually applies (the session always; agent frontmatter ignored in July 2026, honoured since Claude Code 2.1.280) and what each level costs in output tokens. The numbers and the method are in docs/model-cascade.md.

Measured across hives: what VULYK costs. The token audit read 1,844 sessions of v0.17.0: a median task processed 84.9M raw tokens (13.5M weighted) and dispatched 67 subagents, 43 of them clerks; 23% of all spend was the instruction bundle every subagent re-read; extra council rounds took 29.5% of the spend of the tasks that had them; 56% of driver runs stopped before a verdict. Above 500 changed lines, VULYK tasks cost 2.2–2.3× the weighted tokens of comparable work without it (a weak sample, ±30%). v0.18.0 is the answer (ADR-013); its expected saving of 40–55% on a median task is an estimate until python scripts/token-report.py <project> has measured specs built on it. The totalTokens a Workflow run prints is not spend: it sums each agent's final context.

Measured from now on, by scripts/scope-check.sh. Two numbers per story, appended to memory/stats/scope.jsonl: how many files the story declared, and how many files the diff touched that it never named. Deterministic, no model involved, zero tokens. cycle.sh close-story runs it on every story. The second number is what keeps the first honest — a story that lists half the repository scores a perfect zero and is caught by its own declaration count. Since v0.5.0 the build commits per story, so each measurement covers exactly one story's diff instead of the pileup of everything before it.

Checked before every dispatch, by scripts/wave-check.sh. File collisions between concurrently-dispatched stories, blocker ordering, dangling blocked_by references — the defects that silently destroy parallel work — plus, since v0.8.0, declared paths that do not exist in the tree and stories whose verification command cannot fail for the files they touch. Same currency: deterministic, model-free, free.

Checked before every approval, by scripts/trace-check.sh. Backward: every ## Requirements quote in every story must appear verbatim in the spec's brief.md (or its recorded plan deltas) — a quote found nowhere is an invented or paraphrased requirement, and a story with no quotes is speculative work. Forward: brief lines no story quotes are listed for the human, who alone decides "that's context, not a requirement". Same currency again: deterministic, model-free, free.

Recorded by scripts/acceptance-log.sh — the pre-council path, still live for any spec recorded before v0.12.0's council replaced it. The verdict of drone-acceptance — which read the human's brief and the repository, never the plan or the stories — next to what the stories claimed about themselves, appended to memory/stats/acceptance.jsonl. The number worth having is the disagreement: every story done while the blind gate did not accept. It is the only series in this framework capable of contradicting the framework's own account of itself. It starts empty on a fresh install; the first real entries are in, and what they showed is below. Each entry names the commit and a fingerprint of the pack it judged, because a verdict is about the stories that existed when the drone ran — let review carve out repair stories afterwards and the old verdict is about work that never shipped. acceptance-log.sh --check <spec-dir> answers whether the newest verdict still describes the spec: CURRENT, STALE, or NO VERDICT RECORDED. Read drift for what it is — evidence about delivery, never about proof. The two are independent: on the first real run the blind gate accepted a pack lead-review then blocked twice, and both were right.

Not measured. Whether the cascade beats an all-Opus baseline on output quality. Whether the memory plane beats simply letting a 1M-token window read the repository. Whether moving recon off Haiku helped or just cost more. Whether /vulyk-evolve improves anything — it has never been run against real data, which is why it is being rebuilt around the scope metric rather than shipped as-is.

Claims of the form "N× cheaper" or "near-parity quality" have been removed from this README. They may well be true; nobody here has measured them. When scope.jsonl and acceptance.jsonl have data from real projects, this section gets numbers instead of prose.

Anomaly telemetry — opt-in, anonymized, never automatic

VULYK logs anomalies locally (memory/stats/anomalies.jsonl) to improve VULYK itself, and can contribute an anonymized weekly bundle back to this project if you opt in. Off by default. A bundle row has exactly 10 keys — v code value threshold vulyk tier model agent week hive — codes and numbers only: code is one of context_high agent_prefix_high agent_empty council_rounds_high stage_long driver_refused driver_relaunched scope_breach sessionend_llm (bash scripts/telemetry.sh enum), agent is a framework agent name from a fixed list shipped in scripts/telemetry.sh (bash scripts/telemetry.sh agents) - any other agent is reported as other. Never included: file paths, story/spec slugs, dispatch names, emails, free text, or file contents.

The installer asks once — Enable telemetry? [y/N], default off — and the Telemetry row in your CLAUDE.md Profile table holds the answer. With it on, /vulyk-evolve prints the exact command to send the week's bundle (a local commit, or gh pr create) — it never runs it; you push the PR into telemetry/inbox/ yourself. Weekly, /vulyk-evolve in the VULYK repo runs scripts/telemetry.sh inbox: the merged bundles are distilled into per-week, per-code counts that land in that run's CHANGELOG entry, and the emptied week directories are staged for deletion in the same changeset — which a maintainer reviews and commits, so the improvements ship with the next release. Full contract: docs/telemetry.md.

FAQ

Does this work on a Pro/Max subscription? Yes — that is the design constraint. Everything runs inside the official Claude Code client. (Running many parallel sessions still consumes your limits faster; the cascade exists precisely to keep that affordable.)

Do I need Agent Teams? No. Default orchestration uses subagent fan-out from the main session. Agent Teams (experimental flag) adds peer-to-peer coordination for Tier 3–4 collaborative work.

Can subagents spawn subagents? No — a deliberate Claude Code constraint. VULYK's design respects it: all fan-out happens from the Queen (main session) or, at Tier 3–4, the Workflow driver; leads and workers are single-purpose.

My repo already has a CLAUDE.md. install.sh never overwrites it — it writes CLAUDE.vulyk.md and prints a one-line @import to add.

Is this affiliated with Anthropic? No. VULYK is an independent open-source project. Claude and Claude Code are trademarks of Anthropic, PBC.

Documentation

Getting started · The cycle · Architecture · The gates · Model cascade · Token economy · Memory system · Self-evolution · Command reference · Hooks reference · FAQ

Roadmap — the road to 1.0.0

VULYK is absorbing the best of Autopilot — the discipline that a user's request survives, verbatim and traceable, from idea to running code. The full 40-agent analysis behind this plan lives in docs/specs/autopilot-merge/. Each minor is battle-tested on real projects before the next ships:

• v0.5.0 — parallel build made safe. Waves, per-story commits, bounded worker returns, repair ceiling, wave-check.sh, install.sh --upgrade.
• v0.6.0 — secrets & claims hygiene. Redaction piped into learnings/handoff writers, irreversible-action rule in every Bash-holding agent, every doc claim re-verified on the current client.
• v0.7.0 — traceability spine. Verbatim brief.md per spec, requirement quotes in stories, deterministic trace-check.sh (forward + backward), briefing question discipline.
• v0.8.0 — independence gates. Blind coverage check (brief + plan only) before approval; blind acceptance (brief + running repo only) after build — the checker that can disagree with the framework's own account of itself, its verdict recorded in acceptance.jsonl. Plus three deterministic checks the v0.7.0 battle tests earned: declared paths must resolve, a story's verification must be able to fail, and a flaky surface may name its repeat count.
• v0.8.1–v0.8.3 — what the v0.8.x battle test cost. Both of its questions are answered, and each one found a defect rather than confirming a design. The acceptance verdict now records a fingerprint of the pack it judged, because it had recorded a clean result for a six-story pack that shipped with nine. The blind gate's cannot-run branch no longer calls a library unrunnable — given a genuinely library-only spec it wrote a caller and exercised it, and was better than its own instructions. The self-update check ships alongside: a hive that notices a newer version of itself and asks.
• v0.9.0 — memory hardening. The gates reference: what each gate structurally cannot see, and when it stops being true. A ## Profile block every caste starts from, whose last row states which configurations actually exist — the thing a reviewer needs before it can demand a guarantee. ADR harvest from ## Plan deltas on the review PASS path, proposed-only and forbidden from inventing options nobody weighed. And drone-docs moved off the worker's account onto the diff, with a verify-before-write checklist.
• v0.9.1 — optional instruments. scripts/state.sh derives .claude/state.json from story frontmatter and nothing else. Gitignored on purpose: a derived artifact committed beside its source is a second account of the same fact, which is failure mode four built by hand. Statuses outside the convention are counted as unrecognised, never as todo — the first real run reported a repository's older specs as 0-of-28 done, and a view that miscounts quietly is worse than no view.
• v0.9.2 — the 1.0.0 bar is counted, not recalled. scripts/release-check.sh counts criterion (1) instead of remembering it: a spec counts only when all three deterministic series exist for it — a brief.md for trace-check to walk, a scope.jsonl entry, and an acceptance verdict whose pack fingerprint still matches the spec as it stands. On its first run against a real repository the true figure was 0 of 10, against an estimate of five. Two of the four records could not even be joined — a story file's story: key against the basename scope-check.sh was invoked with — so the first version of the meter reported scope: no for a repository holding thirty-seven scope entries. A silent no from a meter is the same defect class as a silent green from a gate.
• v0.9.3 — what the first real acceptance sitting found in its own machinery. Three specs through the blind gate in one sitting, three defects, none of them in the code under test. drift could not fire on a spec whose stories predate the status convention: a status outside todo|in-progress|done|blocked is neither done nor not-done, so a fully merged twelve-story spec scored done: 0, the comparison never held, and the record said the reassuring false — the one metric built to contradict the hive, switched off by a spelling. It now records "unknown" with the count and the reason. The milestone-ledger exception leaked the framework's own account into the blind gate — disclosed by the drone itself, which then re-verified independently; /vulyk-review now prefers the ## Profile block and hands over a ledger by naming the section, not the file. And concurrent acceptance gates collide on fixed test ports, which reads exactly like a defect in the code under test.
• v0.9.4 — the ignore rules finally reach installed projects. VULYK writes handoffs, snapshots, an update-check cache, a derived state view and its own settings backup into your repository, and .gitignore is in no tree the installer copies, because it is the project's file and must never be replaced. So every install committed whatever the framework left lying around, or did not, by luck. Noticed when .claude/state.json turned up untracked in a real project one release after v0.9.1 declared it gitignored — true of this repository, and of nowhere else. ensure_gitignore appends only the missing entries, in a marked block, idempotently. Same doctrine as the v0.8.0 hook wiring: a rule that does not reach existing installs is a rule the framework only believes about itself.
• v0.10.0 — the top model follows the plan. Fable 5.1 shipped, and whether it should plan is a question about the subscription, not the model: Max carries it inside the weekly limit, Pro bills every token to credits. scripts/top-model.sh reads the plan off the account profile Claude Code already caches locally — never the credentials — and resolves fable or opus; a SessionStart brief announces it, the plan and review commands pass it as the dispatch model: for the three top castes, and --apply pins the Queen's own session. TOP_MODEL = auto in the constitution; an alias in its place overrules the plan. Synthetic profiles for every plan shape run in CI.
• v0.9.5 — the dry run stops writing. install.sh --check created seven directories in the target: one unguarded mkdir -p seeded the memory/ and docs/ trees whether or not the run was meant to touch anything, so the command offered to someone who only wants to see what VULYK would do to their repository was the command that quietly changed it. Found by @chizhseo in PR #1 while writing an installer smoke test — invisible to reading the code, obvious to anyone who checked the result. It survived nine releases because nothing here ran the installer and then looked at what it had done: the very gap this framework spends its gates on, at home. Verified by result — dry run against an empty target leaves 0 objects, a real install still produces the full hive.
• v0.11.0 — the cycle closes with a person. The pipeline had four of the six stages a delivery loop needs and stopped at merge: no branch per spec, no named walk down the client's path, no stage where the owner looks, no publish, no next circle. Now the cycle is named, each stage has a confirmation artifact on disk, and the two that were missing are the two an agent cannot take - the owner's own look (scripts/human-check.sh, pinned to the commit; /vulyk-ship refuses without it) and the publish (/vulyk-ship prints it, a human presses it, ship-check.sh --record writes it down). ship-check.sh reads all six confirmations at once and says which stage is open, deterministically and for free.
• v0.20.0 — Sonnet executes, Opus judges, and nothing runs below the floor. Sonnet 5.5 shipped, and the ladder was re-cut by kind of work rather than by budget: the workers, the scout, the docs drone and the clerk moved to Sonnet; everything that plans or judges stays on Opus; Fable keeps the Tier 4 gate. The family that builds never judges, and a missed story's retry now climbs to a different family on every plan. Routing names families only. A floor in scripts/lib.sh is checked before a session (top-model.sh --floor: env, settings, provider, frontmatter) and after it (telemetry model_below_floor, read off the model each transcript actually ran on) — because on Bedrock, Google Cloud and Foundry the sonnet alias still resolves to 4.5 (ADR-015).
• v0.21.0 / v0.21.1 — maintenance runs itself. /vulyk-gc, /vulyk-evolve and /vulyk-map had never run in this repo: 36 of 41 learnings were empty stubs and no evolve branch had ever existed. The SessionStart brief now names what is due, and the Queen runs it through the Skill tool once the owner's task is done; evolve keeps a hypothesis ledger whose verdicts are read from git (merged = accepted, deleted unmerged = rejected), so a rejected idea returns only with newer evidence. 0.21.1 let the ship gate pass the hook-written skill counter — maintenance itself dirties it — and made tests/cycle.test.sh able to fail again: its piped checks had lost every failure in a subshell and exited 0.
• 1.0.0 when: ten real Tier 2–4 specs with clean scope/trace/acceptance series (3 of 10, counted by scripts/release-check.sh rather than recalled — this one closes by using the framework, not by building it), --upgrade proven across two minors (done, four), zero unverified claims in the docs (audited 2026-08-18), zero known silent-loss paths (two closed 2026-08-18: the acceptance note reaching git unredacted, and a repair round dispatched against a stale collision check).
• After 1.0.0: plugin-marketplace packaging, worktree fan-out preset, public eval harness.

Contributing

PRs welcome — see CONTRIBUTING.md. The most valuable contributions right now: real-world routing-matrix tuning, memory-plane patterns from 200k+ LOC repos, and /vulyk-evolve heuristics.

License

MIT © 2026 VULYK contributors

---