plugin captain · Claude Code · v0.20.1

Как работи КапитанаHow the Captain works

Една сесия на Claude Code командва екип от фонови агенти. Капитана не пише код. Той разделя работата, пуска агентите паралелно, праща всичко на ревю и пита собственика само за важното.One Claude Code session commands a crew of background agents. The Captain („Капитана“) writes no code. It splits the work, runs the agents in parallel, sends everything to review and asks the owner only about what matters.

Не пише код самWrites no code itselfHook спира всяка редакция на код, build или тест от Капитана.A hook blocks every code edit, build or test by the Captain.
Паралелни агентиParallel agentsВсяка задача без зависимост тръгва веднага, обикновено в свой git worktree.Every task with no dependency starts at once, usually in its own git worktree.
Ревю преди pushReview before pushCodex чете всеки diff. Писателят не ревюира сам себе си.Codex reads every diff. A writer never reviews its own work.
Рисковото чакаRisky actions waitMerge в main, force push, deploy, prod: само със „да“ от собственика.Merge to main, force push, deploy, prod: only with the owner's yes.
МостикътThe bridge

Кой с кого говориWho talks to whom

Капитана стои в средата. Задачи излизат към агентите. Обратно идва само кратък отчет и път към файл с детайлите.The Captain sits in the middle. Tasks go out to the agents. Only a short report and a path to a file with the details come back.

СобственикOwner продукт и обхватproduct and scope „да“ за рисковотоyes for risky actions /captain + задача/captain + task въпрос + препоръкаasks, recommends guard.py: без код, build, commitguard.py: no code, build, commit КапитанаCaptain main session разделя плана на задачиsplits the plan into tasks пуска агентитеlaunches the agents прилага прага на ревютоapplies the review threshold прави mergeruns the merges дневник: run.md, decisions.mdlog: run.md, decisions.md Runner Sonnet bootstrap, build, тестове, cleanupbootstrap, build, tests, cleanup ПисателиWriters Opus / Sonnet код, обикновено в свой worktreecode, usually in its own worktree Codex gpt-6-astra ревю на spec и код, read-onlyreviews specs and code, read-only Панел 3amigos3amigos panel 3 гласа3 votes Codex + Opus + Fable решаватCodex + Opus + Fable decide задача + frametask + frame задачаtask diff сложно решениеhard decision findings обратно към Капитана:back to the Captain: един отчет, ≤ 8 реда + пътone report, ≤ 8 lines + path queue.md · опашка за собственикаqueue.md · the owner's queue merge в main, force push, триене, deploy, prod, външен записmerge to main, force push, deletes, deploy, prod, external writes чака „да“waits for yes
Капитана само координира. Писателите пишат, runner пуска build и тестове, Codex ревюира, а панелът 3amigos решава сложните въпроси. Всичко рисково влиза в опашката и чака собственика.The Captain only coordinates. Writers write, the runner runs builds and tests, Codex reviews, and the 3amigos panel settles the hard questions. Everything risky goes into the queue and waits for the owner.
Пътят на една задачаThe life of a task

От плана до pushFrom plan to push

Всяка задача минава през едни и същи седем стъпки. Номерата тук са реалният ред.Every task goes through the same seven steps. The numbers are the real order.

  1. КапитанаCaptain

    Разделя плана на най-малките задачиSplits the plan into the smallest tasks

    Всяка задача трябва да мине ревю сама. За всяка Капитана записва кои файлове пипа (Touches) и след коя задача тръгва (After).Each task must pass a review on its own. For each one the Captain records the files it touches (Touches) and the task it waits for (After).

  2. ПисателиWriters

    Пуска всички свободни задачи наведнъжLaunches every free task at once

    Няма горна граница на писателите. Общ файл не е причина за сериен ред. Сериен ред остава за резултат, който spec-ът не фиксира, едни и същи редове или логика, lockfile, migration и общ тестов ресурс.There is no cap on writers. A shared file is no reason for serial work. Serial order stays for an output the spec does not fix, the same lines or logic, a lockfile, a migration and a shared test resource.

  3. Codex

    Друг модел ревюира всеки diffAnother model reviews every diff

    Codex е ревюърът по подразбиране, read-only и без web. Ако Codex го няма или удари лимит, ревюира нов Opus агент. Никога самият писател.Codex is the default reviewer, read-only and with no web. If Codex is missing or hits its limit, a fresh Opus agent reviews. Never the writer itself.

  4. Писателят + КапитанаWriter + Captain

    Триаж: FIX NOW, ACCEPT или TODOTriage: FIX NOW, ACCEPT or TODO

    Писателят проверява всяка забележка срещу кода. Капитана прилага прага механично: кръг 1 оправя всеки потвърден дефект, от кръг 2 само реален и достижим. До 3 повторни ревюта.The writer checks every finding against the code. The Captain applies the threshold mechanically: round 1 fixes every confirmed defect, from round 2 only a real, reachable one. At most 3 re-reviews.

  5. Runner

    Merge, после тест на групатаMerge, then the group test

    Капитана прави merge на прегледания branch в този feature branch. Писателите не пускат тестове: runner тества групата веднъж, след последния merge. Червен тест е FIX NOW за писателя.The Captain merges the reviewed branch into the feature branch. Writers run no tests: a runner tests the group once, after its last merge. A red test is FIX NOW for the writer.

  6. Капитана · push gateCaptain · push gate

    Push само с ревю и зелен тестPush only with review and a green test

    Push минава само ако всеки commit след последния push има ревю и групата е зелена. Commit-ите до base SHA, избран от собственика, са негови и не се ревюират. Към main или master: само с /captain merge от собственика.A push goes through only if every commit since the last push has a review and the group is green. Commits up to a base SHA the owner chose are the owner's and need no review. To main or master: only with /captain merge from the owner.

  7. КапитанаCaptain

    Край на runEnd of the run

    Агент обновява TODO и docs. Runner чисти само тези worktree директории, които този run е създал. Капитана пише краен отчет на езика на собственика, със списък „Остава:“ и следващата стъпка.An agent updates TODO and docs. A runner removes only the worktrees this run created. The Captain writes the end report in the owner's language, with a Remaining: list and the next step.

ПисателWriter commit в worktreecommit in a worktree diff РевюReview Codex, read-only findings ТриажTriage писателят проверяваthe writer checks FIX NOW → същият писател · до 3 повторни ревютаFIX NOW → the same writer · at most 3 re-reviews чистоclean Merge + тестMerge + test на групатаof the group ACCEPT: без промяна, с причинаACCEPT: no change, with a reason TODO: за следваща сесия, с доказателствоTODO: for a later session, with evidence
Забележките се връщат към същия писател, защото той вече знае кода. След кръг 1 повечето нови забележки са дефекти на предишната поправка, затова прагът от кръг 2 нататък е по-висок.Findings go back to the same writer, because it already knows the code. After round 1 most new findings are defects of the previous fix, so the bar is higher from round 2 on.
ЕкипажътThe crew

Четири вида агенти, всеки за своята работаFour agent types, each for its own job

Opus преценява, ревюира и решава. Sonnet върши механичната работа и простия код. Изборът е правило, не вкус.Opus judges, reviews and decides. Sonnet does the mechanical work and the simple code. The choice is a rule, not taste.

captain:runner
Sonnet · effort medium

Bootstrap, branch, worktree, build, тестове на група, скриптове, cleanup. Пуска Codex ревюто и чака резултата.Bootstrap, branch, worktree, build, group tests, scripts, cleanup. Runs the Codex review and waits for it.

Защо: работата е механична. Runner никога не пише продуктов код и не тълкува причината за грешка.Why: the work is mechanical. A runner never writes product code and never interprets the cause of a failure.

captain:light-coder
Sonnet · effort high

Пише код само когато задачата мине леките 6 въпроса. Ако му трябва файл извън списъка или решение, връща ESCALATE.Writes code only when the task passes the 6 light questions. If it needs a file outside its list or a decision, it returns ESCALATE.

Защо: Sonnet излиза извън обхвата при неясна работа. Затова получава само ясни задачи.Why: Sonnet drifts out of scope on vague work. So it gets only clear tasks.

captain:worker
Opus · effort medium

Писателят по подразбиране. Също ревюър, когато Codex липсва, и глас в консенсус.The default writer. Also the reviewer when Codex is missing, and a voter in consensus.

Защо: повечето задачи имат поне едно решение, което трябва да се прецени.Why: most tasks hold at least one decision that needs judgement.

captain:deep
Opus · effort high

Само за много сложна spec или реализация, критични действия и пълен консенсус.Only for a very complex spec or implementation, critical actions and full consensus.

Защо: по-високият effort струва време. Използва се там, където грешката е скъпа.Why: higher effort costs time. It is used where a mistake is expensive.

Леките 6 въпроса: кога код може да пише SonnetThe 6 light questions: when Sonnet may write code

  • КЛ1KL1Команда решава „готово“: тест, lint или падащ тест за поправяне.A command decides "done": a test, a lint, or a failing test to make pass.
  • КЛ2KL2Файловете са известни отпред: до около 5, в един модул или слой.The files are known up front: about 5 at most, in one module or layer.
  • КЛ3KL3Промяната следва pattern, който вече има в това repo и е назован в prompt.The change follows a pattern that already exists in the repo, named in the prompt.
  • КЛ4KL4Няма отворено решение: имена, поведение и данни са дадени.No open decision: names, behaviour and data shape are given.
  • КЛ5KL5Няма рисков механизъм: concurrency, locks, timeouts, retries, hardware, auth или security, migrations, триене на данни.No risky mechanism: concurrency, locks, timeouts, retries, hardware, auth or security, migrations, data deletion.
  • КЛ6KL6Не е bug fix, или причината за този bug е известна.Not a bug fix, or the bug's root cause is known.
Шест пъти „да“ → captain:light-coder. Едно „не“ → captain:worker.Six yes → captain:light-coder. One no → captain:worker.
Skills и инструментиSkills and tools

Какво ползва Капитана и защоWhat the Captain uses, and why

Капитана не прави всичко сам. Той ползва няколко skill и външни инструменти. Всеки има една работа.The Captain does not do everything itself. It uses several skills and external tools. Each one has one job.

КаквоWhatКаква работа вършиIts jobЗащо е тамWhy it is there
captain:captainskill Самите правила: 21 правила R1–R21 и референции за prompts, ревю, време, опашка, handoff.The rules themselves: 21 rules R1–R21 and references for prompts, review, time, the queue and handoff. Всяко правило има ред „Why“ с реалния инцидент, от който е дошло.Every rule has a "Why" line with the real incident it came from.
captain:captain-setupskill Открива codex, agy и msg-notify. Пита как да известява и кога да мълчи. Пише config.json и notify.sh.Detects codex, agy and msg-notify. Asks how to notify and when to stay quiet. Writes config.json and notify.sh. Всеки човек има свой телефон, свои тихи часове и свои инструменти.Every person has their own phone, quiet hours and tools.
Codex CLIвъншен инструментexternal tool Ревюърът по подразбиране за spec и код: gpt-6-astra, read-only, без web. Също глас в панела.The default reviewer for specs and code: gpt-6-astra, read-only, no web. Also a voter in the panel. Втори модел от друго семейство хваща това, което писателят не вижда. Без web, защото едно ревю висеше 27 минути в документация.A second model from another family catches what the writer misses. No web, because one review hung for 27 minutes in documentation.
3amigos:3amigosskill Панел от трима независими гласа: Codex, Opus и Fable. Runner брои гласовете с tally.py и мнозинството решава. Липсващ глас се заменя с Fable. Без мнозинство печели по-безопасният вариант.A panel of three independent voters: Codex, Opus and Fable. A runner counts the votes with tally.py and the majority decides. A missing voter is replaced by Fable. With no majority the safer option wins. Сложните и архитектурните решения не зависят от един модел. Когато собственикът е away, панелът отговаря и на продуктовите въпроси.Hard and architectural decisions do not depend on one model. When the owner is away, the panel also answers product questions.
Fable · agyмодел · външен инструментmodel · external tool Чернови на spec, консултации и гласове. agy само ако е включен в config.Spec drafts, consultation and votes. agy only when the config enables it. Добри за идеи и гласуване. Никога не ревюират код.Good for ideas and votes. They never review code.
msg-notifyskill Пинг на телефона, когато Капитана чака решение или отчетът е готов.A phone ping when the Captain waits for a decision or the report is ready. Пингът следва настройките: по избор само когато собственикът не е пипал лаптопа. Въпросът винаги е и в чата.The ping follows the settings: optionally only when the owner has been away from the laptop. The question is always in the chat too.
utils:new-session-tabskill При handoff отваря нов terminal tab с нова сесия, която продължава същия run.At a handoff, opens a new terminal tab with a new session that continues the same run. Всяка стъпка препрочита целия контекст. При голям контекст една дълга сесия е най-скъпата част от целия run.Every turn re-reads the whole context. With a large context, one long session is the most expensive part of the run.
project-memoryplugin При включен project-memory уроците от run стават memory файлове в .agent-memory/. Агентите пишат само чернови, Капитана пише файла, Opus агент го проверява.With project-memory on, lessons from a run become memory files in .agent-memory/. Agents write only drafts, the Captain writes the file, an Opus agent checks it. Всяка следваща сесия чете паметта като правило. Грешен ред струва повече от липсващ.Every later session reads the memory as a rule. A wrong line costs more than a missing one.
ПредпазителиGuardrails

Правилата се пазят от код, не от добра воляCode keeps the rules, not good will

Три hook скрипта и един одит следят Капитана. Опашката държи всичко, което не може да се върне назад.Three hooks and one audit watch the Captain. The queue holds everything that cannot be undone.

guard.py

  • Отказва на Капитана редакция на код, build, тест и install. Commit само в merge flow.Denies the Captain code edits, builds, tests and installs. Commits only in the merge flow.
  • Merge само в captain/* branch или в потвърдения base branch.Merges only into a captain/* branch or the confirmed base branch.
  • main или master само с /captain merge, написано от собственика.main or master only with /captain merge typed by the owner.

handoff_at_boundary.py · kickoff_on_clear.py

  • При 250 000 tokens контекст (по подразбиране) спира веднъж следващия писател и иска handoff.At 250,000 tokens of context (the default) it holds the next writer once and asks for a handoff.
  • Handoff става само между задачи, никога по средата на операция.A handoff happens only between tasks, never mid-operation.
  • След /clear новата сесия получава своя kickoff и продължава като същия Капитан.After /clear the new session gets its kickoff and continues as the same Captain.

Проверка на 15 минутиA check every 15 minutes

  • Cron таймер, докато работи поне един агент.A cron timer while at least one agent runs.
  • Пише точно един ред статус, никога отчет.It prints exactly one status line, never a report.
  • След run audit-main.py може да провери transcript на сесията. Чист е само exit 0.After a run audit-main.py can check the session transcript. Only exit 0 is clean.

queue.md · опашкатаqueue.md · the queue

  • Push или merge в main без грант, force push, пренаписване на чужда история.Push or merge to main without a grant, force push, rewriting others' history.
  • Триене на branch, tag или worktree, които този run не е създал.Deleting a branch, tag or worktree this run did not create.
  • Deploy, production, общи бази, външен запис. Изключение: dev target, потвърден в config, след ревю.Deploy, production, shared databases, external writes. Exception: a dev target confirmed in the config, after review.
  • Консенсусът никога не отключва нещо от опашката.Consensus never unlocks anything in the queue.
Режими и командиModes and commands

С теб или без теб, с време или безWith you or without you, with a time box or without

Present

Собственикът е тук. Продуктовите въпроси отиват при него един по един, всеки с препоръка. Ако има време, препоръката идва от панела 3amigos.The owner is here. Product questions go to the owner one at a time, each with a recommendation. When time allows, the recommendation comes from the 3amigos panel.

Away

Собственикът го няма. Панелът 3amigos решава продуктовите въпроси. Всяко решение влиза в decisions.md. Рисковото пак чака в опашката.The owner is away. The 3amigos panel settles product questions. Every decision goes into decisions.md. Risky actions still wait in the queue.

ВремеTime

Без време по подразбиране. Ако собственикът каже „за 1 час“, има box: краен срок 1,3 × box и до 3 удължения по +30% само за отворена работа.No time box by default. If the owner says "for 1 hour", there is a box: a hard end at 1.3 × the box and up to 3 extensions of +30%, for open work only.

статус · status · Минаха 42 от 120 минути (+36 толеранс); готови 7 от 12 задачи (58%); ЗД3 тече (12/35 мин).42 of 120 minutes gone (+36 tolerance); 7 of 12 tasks done (58%); ZD3 running (12/35 min).
/captainСтарт, собственикът е тук, без време.Start, the owner is here, no time box.
/captain 1h awayСтарт за 1 час, собственикът го няма.Start for 1 hour, the owner is away.
/captain merge <branch>Позволява merge и push в този branch.Allows merge and push into that branch.
/captain resumeНова сесия продължава същия run от handoff файла.A new session continues the same run from the handoff file.
/captain offСпира режима на Капитана.Turns captain mode off.
Защо е такаWhy it works this way

Всяко правило идва от реален runEvery rule comes from a real run

Числата са от записани сесии. Правилото вдясно от всяко число е отговорът.The numbers come from recorded sessions. The rule under each number is the answer.

4 от 94 of 9

сесии, в които координаторът сам вършеше работата.sessions in which the coordinator did the work itself.

→ guard hook спира всеки опит.→ a guard hook blocks every attempt.
23 от 4123 of 41

забележки след кръг 1 бяха дефекти на предишната поправка.findings after round 1 were defects of the previous fix.

→ по-висок праг от кръг 2, до 3 повторни ревюта.→ a higher bar from round 2, at most 3 re-reviews.
466

съобщения от агенти за 15 run.agent messages in 15 runs.

→ един отчет, до 8 реда, детайлите във файл.→ one report, at most 8 lines, details in a file.
27 мин27 min

агент стоеше блокиран и никой не забеляза.an agent sat stalled and nobody noticed.

→ проверка на всеки 15 минути.→ a check every 15 minutes.
86 мин86 min

отворени въпроси задържаха таймера.open questions held the clock.

→ питай само за продукт и обхват, първо пусни работата.→ ask only about product and scope, start the work first.
ИнсталиранеInstall

Пусни Капитана при себе сиRun the Captain yourself

Четири стъпки в Claude Code. Пълните инструкции са в публичното репо.Four steps in Claude Code. The full instructions are in the public repository.

  1. Добави marketplace-аAdd the marketplace

    /plugin marketplace add mentorano/ai-marketplace-mentorano

  2. Инсталирай plugin-итеInstall the plugins

    /plugin install captain@ai-marketplace-mentorano
/plugin install 3amigos@ai-marketplace-mentorano
/plugin install utils@ai-marketplace-mentorano

    3amigos е за решенията с консенсус, utils е за handoff в нов tab. И двата са по избор.3amigos runs the consensus decisions, utils opens the handoff tab. Both are optional.

  3. Настрой веднъжSet up once

    /captain:captain-setup

    Пита как да те известява и кога да мълчи. Открива Codex CLI, ако е инсталиран. Без Codex ревюира Opus.Asks how to notify you and when to stay quiet. Detects the Codex CLI if it is installed. Without Codex, Opus reviews.

  4. Стартирай runStart a run

    /captain
/captain 1h away

    Първото е с теб, без време. Второто е за 1 час, докато те няма.The first runs with you, no time box. The second runs for 1 hour while you are away.

Инструкции за инсталиранеInstall instructions Описание на captain в READMEThe captain section of the README Публичното репоThe public repository