convez.ai
InicialPluginScore · de 0 a 100

Hive orchestration for Claude Code — model cascade, external memory, self-evolving skills. Native primitives only, subscription-safe.

Instalação

$npx convez-ai Black-coffe/vulyk

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
2
Acompanhando
0
Saúde
71%
Último commit
há 4 dias
Versão
v0.53.0
Issues abertas
4
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.


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 the strongest model. Plans, decomposes, integrates. Never reads source code directly.
  • Leads — Opus-class subagents for architecture decisions and adversarial review.
  • Workers — Sonnet-class subagents that implement and test individual stories. This is where 70–80 % of tokens are spent — at roughly a fraction of top-model cost.
  • Drones — Haiku-class subagents for reconnaissance, documentation updates, and memory upkeep.

The result: more parallel agents, larger codebases, dramatically less token burn on your 5-hour and weekly limits — with quality protected by an Opus "bookend" (plan and review on the strong model, execute on the efficient one).

Why VULYK exists

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

VULYK answers all three 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.

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.

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

/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 Haiku 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                                          # Workers implement stories on Sonnet, in parallel
/vulyk-review                                         # Adversarial Opus review gate before merge

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:

CasteAgentModelJobReads source?
👑 Queen(main session) + queen-plannertop model¹ / opusDecompose goals, integrate results, own the roadmapNever — consumes scout reports & memory only
🛡 Leadlead-architectopusDesign decisions, ADRs, tradeoff analysisTargeted excerpts only
🛡 Leadlead-reviewopusAdversarial review gate: correctness, security, invariantsDiffs + tests
🐝 Workerworker-codesonnetImplement exactly one storyScoped slice via map
🐝 Workerworker-testsonnetWrite/repair tests for one storyScoped slice
🔍 Dronedrone-scouthaikuRecon: files, symbols, structure → map-format reportYes — that's the point
🔍 Dronedrone-docshaikuUpdate wiki & map notes after changesDiffs
🔍 DronelibrarianhaikuMemory consolidation & garbage collectionMemory files only

¹ The top model is whatever your plan currently makes economical. Set once in CLAUDE.md (TOP_MODEL). As of June 2026 that's claude-fable-5 while it is included in subscription plans, falling back to claude-opus-4-8 afterwards — one line to change, the rest of the hive is model-agnostic.

The routing matrix

Routing happens before any work starts. The Queen classifies every request into a tier (the matrix lives in CLAUDE.md, so it is enforced on every prompt):

TierSignalWho worksCost shape
0Trivial, single file, obviousMain session directlyminimal
1One module, clear task1 × worker-code (+ scout)cheap
2Feature within a module2–4 workers, architect consultedplan is expensive, body is cheap
3Cross-cutting, multi-moduleFull pipeline: plan → fan-out → reviewbookend
4Architecture / migration / 200k+ LOC touchedTier 3 + adversarial review + max effortdeliberately expensive

Bookend rule: spend top-model tokens at the two points where they change everything downstream — planning and final review. Everything in between runs on Sonnet and Haiku.

Command reference

CommandWhat it does
/vulyk-bootstrapInterview → tailored constitution, pruned roster, initial map & wiki seed
/vulyk-plan <goal>Queen mode: scouts recon, plan + story files written to docs/specs/, tier assigned, approval requested
/vulyk-build [story]Execute approved stories with cascade-routed workers, parallel where independent
/vulyk-review [scope]Adversarial lead-review pass; blocks on critical findings
/vulyk-map [path](Re)build the codebase map for a path using Haiku scout batches
/vulyk-evolveWeekly self-evolution: mine learnings & usage stats → propose config diffs as a reviewable changeset
/vulyk-gcMemory garbage collection: consolidate learnings, prune stale map entries, archive dead skills
/vulyk-statusOpen stories, memory freshness, skill usage stats, budget posture

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 matrix, protocols   (< 150 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/    raw session learnings (hook-captured) → 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.
  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

HookEventEffect
session-start-brief.shSessionStartInjects memory freshness + pending-learnings line into context
session-end-learnings.shSessionEndCaptures a structured learnings stub (optional Haiku auto-distill with VULYK_AUTOLEARN=1)
skill-usage-counter.shPostToolUse (Skill)Increments per-skill counters → fuel for skill-gardener
context-guard.shPreCompactSnapshots memory & task state before compaction

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

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); 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 · Architecture · Model cascade · Memory system · Self-evolution · Command reference · Hooks reference · FAQ

Roadmap

  • Deterministic pipelines on the Claude Code Workflows API once it stabilizes (example shape in .claude/workflows/)
  • Plugin-marketplace packaging (/plugin install vulyk)
  • Worktree fan-out preset for issue-driven parallelism
  • Public eval harness: cascade vs. single-model baselines on open tasks

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


Ver o original no GitHub

Bom para

Relacionados