English · Русский
Plan a feature with your agent in the evening. Accept a green pull request in the morning.
Twenty-four skills for working as a
product engineer (in
Russian): an engineer whose work ends not at the merge but at whether users
solved their problem. You stop driving an agent step by step. You decide what
to build and what counts as working; the agents plan it with you, write the
code without you and report in plain words. They work with Claude Code, Codex, Pi, Prime Agent, omp and any agent that reads
SKILL.md, and with the tracker your project already uses.
- Whole features built while you are away. Before you leave,
take-taskbrings every decision the run will need, with recommendations and a time estimate — one question at a time, or as one list, as your project chose. Then it builds the feature on its own branch: parallel workers, tests first where you agreed, an independent review (by another model where one is available), every red check fixed. It stops only for a real fork — architecture, an expensive mistake, behaviour beyond the spec — and reaches you with a ready decision. - One pull request to accept. It says what users can now do, how to try it yourself, every decision taken without you, what review found and what is not done. Merging is your acceptance; the agent closes the tasks and cleans up.
- Something you can open early, and then again. A breakdown starts with the thinnest path through every layer the outcome touches, run on the real input the product will meet, and each stage after it widens that path — about one working day of agent time each, ending in something you can open, rather than one long build shown to you at the end. Waiting on a check that costs more than the change is treated as the defect to fix first, and a stage that slips is re-cut instead of carried on.
- Always know where you stand. Ask "what next?" or "where are we?" at any
moment:
ask-shady2kreads the project, the tracker and the git history and gives the product's picture, progress, what is stuck and the ways forward with their consequences, with one recommendation. It changes nothing, and it also writes your standup. - A backlog that stays a queue. Checks, not good intentions: a commit without its task, or a change that breaks the backlog, is rejected before it lands. A bug you mention is filed at once but does not jump the queue: each version has a budget for new bugs, and anything beyond it waits for your decision, never the agent's.
- Decisions, not documents. You are never asked to read a spec to approve it. A question comes already worked: what was looked at, the options with their cost, the agent's recommendation and the strongest case against it, in your language and your project's own names. How questions reach you is your project's setting: one at a time, or several in one message — the default is one at a time. No task numbers, no internal statuses, no progress chatter while a run is healthy.
- Specs that say what the system does now. Documents live in
docs/beside the code, kept by capability; accepted work is merged into them, so they never turn into a pile of old plans. - Estimates from your own history, in agent time, measured on this project, with what they rest on and a word when work outgrows them. A time an agent tells you is the same measurement: doubt it and you are shown the basis, not handed a smaller guess.
- Any session picks the work up. Everything agreed is in the repository, not
in the chat, and
handoffkeeps what only the conversation knew. - A thinking partner, not a questionnaire. In any conversation that weighs a choice the agent brings its own position and argues it, looks at it from several sides, names the risks and gives way only to a reason; it brings the established standard or practice before anything home-grown. A conversation may end with nothing written, and nothing is left behind.
- Fits what you already have. Your tracker stays yours; Superpowers, Spec Kit or OpenSpec documents are mapped in place. Setup proves every check really fires before it calls the installation done.
What it does not promise. A green backlog is not evidence that the code works. The checks enforce the backlog's shape, commit links and the document lifecycle; they do not prove behaviour, truthful test evidence or that the right scope was chosen. That is what review and your acceptance are for.
It fits when agents write most of the code and you want to own the result, not the keystrokes:
- A product engineer or a solo developer with a product. You decide what to build and what counts as working, and want whole features built while you do something else, not a pair programmer to steer line by line.
- A small team sharing one repository and tracker. Setup asks whether the process is for you alone or for everyone; the checks then hold every contributor, human or agent, to the same queue and commit links.
- A project that lives for months. The set pays off where a backlog, specs and decisions pile up: it keeps the queue usable, the documents true to the code and the reasons for decisions findable.
- An existing project with a neglected tracker. Setup tidies the queue with you step by step and reversibly, and the checks keep it from rotting again.
- Several agents or machines at once. Everything agreed lives in the repository and the tracker, so a Claude Code session, a Codex worker and an omp pane on another machine read the same state.
What it is for: planning a feature in conversation and getting it built unattended to one green pull request; knowing where the project stands after a break; keeping bugs and ideas from hijacking the current work; estimates and time figures measured on your own project.
It does not fit, or costs more than it gives:
- A one-off script, a prototype for an afternoon or a throwaway repository. Setup alone takes a session or more; for work that never sees a second week, a plain agent is faster.
- Work you want to drive step by step. The set is built for handing a feature over and accepting the result. If you prefer to watch and approve every edit, its preflight, stages and reports are overhead.
- A team with a heavyweight process it must keep. It fits beside your tracker, but it brings its own rules (milestones with a bug budget, commits that name their task, specs kept by capability). Where a mandated process already governs those, the two will fight.
- Proof that the code is correct. The checks enforce the shape of the backlog, commit links and the document lifecycle. They do not prove the behaviour; review and your acceptance do.
- A project with no git repository or no way to run its checks. The gate, hooks and CI checks need git and Node.js; without them the set is only instructions.
The set works the same in every agent below. Install it once, open a new session in your project's main checkout and start setup; after that, just ask "what next?".
| agent | install | start setup |
|---|---|---|
| Claude Code | claude plugin marketplace add shady2k/skillsclaude plugin install shady2k-skills@shady2k --scope project |
/shady2k-skills:setup-shady2k-skills |
| Codex | codex plugin marketplace add shady2k/skillscodex plugin add shady2k-skills@shady2k |
$shady2k-skills:setup-shady2k-skills |
| omp | omp plugin marketplace add shady2k/skillsomp plugin install shady2k-skills@shady2k |
/skill:setup-shady2k-skills |
| Pi | pi install git:github.com/shady2k/skills |
/skill:setup-shady2k-skills |
| Prime Agent | prime-agent package install git:github.com/shady2k/skills |
/skill:setup-shady2k-skills |
Asking in words ("set up shady2k-skills here") works as well. Any other agent
that reads SKILL.md can use the skills directly. Scopes, updates and the
details for each agent are in Installation and updates.
Setup takes from under an hour for a new project to a few sessions for a large
neglected backlog: see What setup takes.
- What you get
- Who it is for
- Quick start
- How a day with it looks
- How your work changes
- Skills
- Installation and updates
- Why it exists
- How the flow works inside
- Time accounting
- What the checks enforce
- Documents: direction, current state and changes
- Changelog
- Credits
- Development
In the evening, planning. Open the agent in the project's main folder and just talk: "what next?" or "I have an idea". Talking changes nothing; if it leads nowhere, close the session and nothing is left behind. When something is worth keeping, the agent moves into a separate working copy by itself, so your main branch stays clean. You shape the idea, the spec and the stages together. Before you leave, the agent brings every decision the work will need as one list with recommendations, and says roughly how long the run will take and when to expect the pull request. You answer, say "run", and go.
While you are away. The agent builds the whole feature on its own branch. Small gaps it decides itself and writes down; a real fork stops that part of the work and reaches you with a ready decision to make.
The next day, acceptance. A green pull request says what was built, how to try it yourself and what the agent decided without you. You try it; merging is your acceptance, and the agent closes the tasks and cleans up.
You stop driving the agent step by step and start working as a product engineer whose code agents write: you own what gets built and what counts as working, down to whether users got what they needed; they plan with you, build without you, and report in plain words. The repository, not the chat, holds everything agreed, so any session can pick the work up.
| step | what you do | what the agents do | skills | how much of you |
|---|---|---|---|---|
| Start from nothing (an empty folder) | pick where to look, choose the idea, tell the key journeys of your users | generate and challenge ideas, check the market and the domain; nothing is written yet | brainstorming, define-product, to-research, to-prototype |
a few conversations |
| Keep it | agree to create the repository and the tracker | create them, connect the checks, write down the vision | setup-shady2k-skills |
once, under an hour for an empty project |
| Or join an existing project | agree what is current, what waits and what was abandoned | read the code, the tracker and the history; clean up the queue reversibly | setup-shady2k-skills, groom-backlog |
once, from half an hour to a few sessions for a neglected backlog |
| Agree the next version (the first one is the MVP) | accept or change the outcomes, what is out, and how many new bugs it may absorb; cut the MVP | propose the charter from the vision and what is done | to-milestone |
one conversation per version |
| Decide the architecture | choose between options shown with their consequences | show the parts, the options and what each costs; record the decisions | brainstorming, model-domain |
when a hard-to-reverse choice comes up |
| Plan a feature | settle the behaviour and the open decisions; answer the preflight once | write the spec with checkable scenarios, decide how the system will do it where the shape changes, split it into stages and tasks, collect every decision the run will need into one list with recommendations and a time estimate | to-spec, to-design, to-stages, take-task |
an evening conversation |
| The run | nothing; you are away | build the whole feature on its own branch with parallel workers, tests first where agreed, independent review (by another model where one is available), fix every red check; stop only for a real fork (architecture, expensive mistakes, behaviour beyond the spec) and reach you with a ready decision | take-task, diagnose-bug |
only if a fork comes up |
| Acceptance | try it the way the pull request says; merging is your acceptance | a green pull request: what users can now do, how to check it yourself, every decision taken without you, what review found, what is not done | take-task |
the time it takes to try it |
| Close | nothing | update the current specs from the accepted work, close the tasks, remove branches and checkouts | close-out |
none |
| Release | nothing, unless a release step cannot be undone or its check fails | starts on your word: version, release notes in what users can do, migrations with their reverse, rollout by environment with the check after each step | ship-release |
one yes, before anything one-way runs |
Between those: ask-shady2k tells you where the project stands and what to do
next whenever you come back; handoff keeps the thread when a session ends;
check-upkeep reads what the product runs after what ages quietly, and
handle-incident waits for the day the running product lets it down. After a
release, the hypotheses whose beliefs it tested wait on their measures; when
one comes due, define-product reads the measure against the threshold the
hypothesis recorded, and the next to-milestone plans from the results.
ask-shady2k answers the question you will ask most often: where are we, and
what now? It reads the project, the tracker when there is one and the git
history, then gives the product's picture, progress, the current state, risks
and the ways forward with their consequences, and recommends one action by
name. It is read-only, so running it costs nothing but a moment and never
changes anything.
Run it at the start of a session, after a break, after a stage is accepted,
when you open a project you have not seen in a while, and whenever you are not
sure what comes next. Ask "what next?" for a short answer, or "where are we?"
for the full picture. Skip it only when you already know the exact task
(take-task) or just want to think something through (brainstorming).
A bug you mention is filed at once in the right place and does not jump the queue: the current version has a budget for new bugs, and anything beyond it waits for your decision, never for the agent's. A bug found mid-run that blocks the merge is fixed by the run itself. An idea you want kept goes to a separate lane with a review date, not into the work; one only discussed stays in the conversation. If you start talking while a run is going, the run does not stop: your conversation happens in a separate session, and what it decides is written where the run will read it.
You do not create branches or name them, merge a pull request for every change of plan, re-explain the context to a new session, remember issue numbers, chase a stuck agent, or keep a document in step with the code by hand. Checks, not good intentions, keep the tracker honest: a commit without its task or a change that breaks the backlog is rejected before it lands, and once the document check is installed, so is a feature whose spec is not ready.
Twenty-four skills. You can start any of them by command or just by asking in
words; when the agent recommends one and you agree, it starts it itself. The
first group starts only on your request or agreement; the agent starts the
second group on its own when the work calls for it.
In Claude Code the plugin prefixes them: /shady2k-skills:ask-shady2k.
| skill | what it does | when to use it |
|---|---|---|
| ask-shady2k | Reads the project and tells you where it stands, how far it has come, what is stuck and which ways forward exist, with one recommendation and each way's time measured with its basis; or, for the team's daily sync, what was done over a period, what got in the way, the questions for others and whether the work fits by a date. It sends a change of the system's shape through a recorded design before a breakdown, and recommends stages that begin with the thin path on real input. Product changes landing with no run open for them — recent commits, open branches — are said in one line, with the run they should be under as the recommendation; it changes nothing. | At the start of a session, after a break, in an unfamiliar project, whenever you are unsure what comes next, before a standup. |
| setup-shady2k-skills | Connects the project's tracker — one copy per machine, outside the code branches and in step with every machine, with the synchronization that keeps it so installed and started — cleans its queue with you, proposes settings as one profile, proves the checks work and, in a product repository, writes the product's kinds registry, with the kinds' link declarations. Rerunning it after 0.49.0 rewrites the judgement records a live charter or an admitted change carries, in your presence, and exports the journeys of your vision so a judgement can name them. Rerunning it for 0.131.0 records where a feature's agreement with you is written, and lists the features already under way once, with your agreement, so the rule judges only what starts after that. Rerunning it for 0.133.0 upgrades the recording hooks it installed in your checkouts without touching your own hook commands, and for 0.134.0 keeps a failed recording honest: a recording that timed out at commit time is redone with exactly the state the tracker had at that commit — a change made seconds before it included — and, when that state cannot be proved, refused with the ways out named. Rerunning it for 0.135.0 connects a clone that can read the tracker's remote and cannot push to it — it keeps its hooks, its pointer and its reads, and is told once that it cannot publish — and stops connect, naming the ref and the failed fetch, instead of presenting an empty store when the remote's store could not be fetched. Rerunning it for 0.136.0 makes a commit on a large tracker cost what the commit changed: hundreds of recordings no longer make it read every recorded state, so it stays fast and small instead of taking minutes and over a gigabyte, and stopping the sync no longer reports that the store's history was rewritten. Rerunning it for 0.137.0 stops a merge that would pass two recordings of one revision when a commit one of them names is not in the store, naming that commit instead of keeping one side's recording, and still merges a recording whose commit is here and holds no state file. Rerunning it for 0.139.0 makes the gate refuse a breakdown whose stage still open ends nowhere you can open, and a feature whose work started with no line saying where its design is recorded, or that this change needed none; it writes that line where the design is already recorded and lists, with your agreement, the features already under way that cannot honestly acquire it. Rerunning it for 0.141.0 asks once how your work should reach your main line — who merges it, when a change becomes visible, what a demo can show — with one recommendation and the facts it rests on, records your answer with the values it derives, and says in one line where one of your own rules stops part of a practice while changing no protection, hook or queue setting; a project that keeps what it does today answers once and its runs do not change. Rerunning it for 0.144.0 asks once for the project's target architecture — the principles of how the system is to work, each with what one does because of it and the decision that established it — showing a draft taken from your decisions, the vision and the code, and does not finish until you confirm it, correct it by name, or answer that there are no principles. | Once per project, and again when a skill says the installation is out of date. |
| to-milestone | Agrees what the next version delivers, what is left out and how many new bugs it can absorb. Each outcome names the vision journeys and principles it serves, and the charter's acceptance carries another model's judgement of what it serves and breaks, each entry naming an id the vision declares and quoting a passage of the charter. | When the current version is done, or a project has no agreed next step. |
| refine-practices | Reads how the work has gone since the last retrospective and judges the active practices first: the classes of error that came back, each put to you with a recommended practice to add or retire, and the practices that caught nothing in the period with what each costs, to retire or loosen — the ones guarding an expensive failure, such as publication, permissions or data loss, kept whatever the period held. Put to you as your project's setting for open questions says. | At the end of a milestone, when about five features have closed without one, or whenever you want to look back. |
| take-task | Before you leave, gathers every decision a planned feature will need, in one list or one question at a time as your project chose; then builds the whole feature without you up to its landing as your project records it - one pull request per feature, or one landing per stage, whichever your project chose, and it keeps the practice the run began under - deciding small gaps itself, stopping only for decisions that need you and telling you what the run's own overhead is costing. An item whose change is already on the main line is closed rather than counted as remaining or built again. It never reaches green by making a check easier to pass, and every worker's brief names the check loop its task waits on, which cuts a check that costs more than the edit it judges Every date stands beside a forecast the run script computes from the measured pace over the tasks that cover it, a duration it tells you is that same measurement with its basis, and every worker's brief carries what its task serves, whom it serves and where you see it. It starts only on the agreement on record — the direction and then the plan, in your words, with the design recorded and the feature saying where, or the reason this change needed none — and refuses to start without one, and a stage is not accepted while a second way into a capability the project already reaches stays open beside the one its decisions put there. It is also the skill that starts when you ask for building through other agents — dispatching workers, taking their results in, having another model review them — because that is a run, and its review and building rules hold from the first dispatch. Every worker's brief also carries the project's target architecture whole, and review and acceptance judge the work against it: where the code departs from a principle, the code is fixed rather than the principle rewritten. | When a feature is planned and you want it built while you are away, or when you ask the agent to build by handing the work to other agents. |
| handoff | Keeps the work's state in the tracker and leaves what only this conversation knows where a fresh session will look, saying which effects already reached outside rather than leaving a status to be trusted. | Before you stop, or when a session gets too long. |
| ship-release | Carries merged, accepted work to its users: version by the project's scheme, release notes in what users can do, migrations with their reverse, rollout by environment with a check after each step and the rollback named before any step runs; a step already taken is read from the system that holds it, never run twice after a stop. | When a feature's pull request is merged and the project's users get it later than the merge. |
| handle-incident | Restores a product failing in use — each move read from the system that holds it, so a session taking over does not undo what is already undone — then finds the cause through diagnose-bug, then holds a blameless review whose actions are filed as work. |
When a product runs for users and they report it is down or broken. |
| report-to-shady2k | Sends a problem or idea about these skills to their author as a GitHub issue, anonymized and shown to you word for word first. | When a skill confused you, did something wrong, or is missing something. |
Available to you directly as well. The agent starting one does not authorize unrelated changes, new scope or publishing anything.
| skill | what it does | when to use it |
|---|---|---|
| brainstorming | Thinks an idea through with you: offers its own ideas and counterexamples, argues its own position from several sides with the risks, brings the established practice first, and gives way only to a reason. Nothing has to come out of it. A principle you state about how the product must work is written into your vision or decision record at once, in your words, and a proposal that adds or replaces a mechanism carries what the code already does for that job. | "Let's discuss", "what if", an open product decision. |
| define-product | Talks your idea through with you in plain words, one plain question at a time unless your project chose several in one message, and writes what an engineer needs to start: what you said, what you believe and how to test it, what a user does, what they must be able to see, and what is still unknown. Your key journeys and principles each get a stable id, and every milestone outcome names the ones it serves. | When you have an idea but no requirements, or before a product's first feature. |
| to-research | Answers a question from primary sources, with citations. | When a decision depends on facts nobody has checked. |
| to-prototype | Builds a small throwaway experiment that answers one design question. | When arguing takes longer than trying. |
| to-spec | Writes down what exactly is being built, as the user will see it, with scenarios that will be checked; short or full by what the change touches, not by the writer's own sense of its size. A constraint it states is a requirement with a check, and an uncovered one is refused. A spec that proposes a mechanism names what already does that job and whether it extends or replaces it. Its criteria come from what the outcome needs: sameness with a reference or with the mechanism being replaced is a criterion only where you chose it in so many words, recorded. | Before building something whose behaviour is not yet agreed. |
| to-design | Decides how the system will meet an outcome before it is built: the product goal confirmed with you first, the drivers traced to it with each constraint's source, at least two options from named patterns and established practice, the inventory of what already does the job — entry points, modules, stores, commands, workers — and the prior art read from primary sources, how existing products, libraries and standards solve the same problem with what each costs and leaves out, both laid out before any option and carried into the direction you confirm, the direction confirmed with you before the long write, a recorded decision with what was rejected and assumed, review by another model that checks the goal before the details, and the scenarios that become checks. It leaves the feature saying where the design is recorded, or why this change needed none. The design lists its constraints with a check each — a limit of scale is proved only on a fixture at least that size — names the vision principles of its area, and its acceptance carries another model's judgement of what it serves and breaks, each entry naming an id the vision declares and quoting a passage of the design record. A decision that sets how the system as a whole is to work also sets a principle: its consequence is read back to you for confirmation and the architecture document's solution strategy is updated in the same change. | When a change introduces or changes a building block, an interface, ownership of state, a runtime interaction, an external dependency or an interface surface. |
| to-stages | Splits a feature into stages, checkpoints that are each checked before the next builds on them, and tasks small enough for one agent. The first stage you can see is the thinnest path through every layer the outcome touches, run on the real input the product will meet, and each later stage widens that path; a stage is about one working day of agent time and ends in something you can open — a stage still open is judged by that, not only the first one — and the gate refuses a breakdown that ends otherwise. A change of the system's shape is designed first, and the breakdown waits for that design to be recorded, whoever called it, and for the feature to say where that record is — or that this change needed none and why. A stage or task names the outcomes it serves, since the forecast is computed over the exact tasks covering them. The breakdown is shown to you and recorded in your words before anything is published, a replacement carries the old mechanism's retirement inside the same feature unless you say otherwise, and a project decision the breakdown would contradict comes to you instead of being built. An order between two stages that are not broken down yet sits on the waiting stage until it has tasks, and moves onto them then. | When planning a feature before it runs. |
| diagnose-bug | Finds the cause of a bug with evidence: reproduces it, tests hypotheses one at a time, refuses a fix that passes by weakening the check that caught it, and treats a gate that refuses honest work as code to diagnose. | When a bug did not yield to a quick look. |
| model-domain | Keeps the glossary — domain terms and the names of the system's own parts — and records of hard-to-reverse decisions, writing a record that sets how the system as a whole is to work beside the principle it sets in the architecture's solution strategy, with the consequence you confirmed. | When words start meaning different things, when a part had to be explained instead of named, or when a decision needs its reason kept. |
| describe-repository | Describes one code repository the product spans for its wiki: the repository's intended model with its evidence, the architecture page, the capabilities found in the code as requirements and use cases marked derived from code, and the decisions found in the code or its ADRs, each linked to the model elements it shapes. | After a code repository is connected to the product, or when asked to describe one. |
| write-intended-model | Writes or checks a repository's intended model — the YAML architecture model in the repository's model folder, with its review report — elements, interfaces and relations, each evidenced at a commit and a blob, in three levels with a worked example, and renders its views. | When a repository needs its intended model written, reviewed or updated; describe-repository starts it. |
| to-backlog | Files new work, bugs and ideas in the right place, without pushing them to the front; a filing is shared with everyone as soon as it is made. | When something new turns up in the middle of other work. |
| close-out | Records accepted work — merges the change into the current specs, then closes its tasks, and closes a bug or a task that waits for no stage on the merge that delivered it — keeping the records proportionate to the task, one acceptance record for a small change, and preserves pending work where a fresh session picks it up, an effect that already left the checkout read from the system that holds it rather than repeated. | After a feature's landing is merged, one pull request per feature where that is how you land, or when work is stopped or handed over. |
| groom-backlog | Cleans up the queue reversibly with you: what is current, what waits, what was abandoned. | When the tracker has become a dump, and during setup. |
| check-upkeep | Reads the project for what ages quietly — outdated dependencies and their breaking changes, known vulnerabilities in what it ships, expiring certificates and keys, deprecated platform features, checks failing or slowing — and files what it finds in the right lane. Finds nothing? It says so in one line. | When the project should have a look after what runs it, or on its scheduled upkeep pass. |
Choose your agent: Claude Code · Codex · Pi · Prime Agent · omp · Other agents / standalone skills.
If you use more than one of these agents, install the plugin separately in each. Within one agent, use either the plugin or standalone skill files (including development symlinks), not both: otherwise the same skills appear twice.
First choose who gets the skills. Claude Code installs a plugin at one of three scopes:
| scope | who gets it | where it is recorded | choose it when |
|---|---|---|---|
| project | this repository and all its worktrees, for whoever opens it | the project's shared settings, committed | the usual choice: you want the skills in this repository, including every worktree |
| user | you, in every repository | your own settings | you want the skills everywhere you work |
| local | you, in this one folder only | a settings file that is not committed | trying it in one folder first |
Install project from the main checkout, not from inside a worktree: then
every worktree of the repository loads it (Claude Code 2.1.200 or later). An
install made inside a worktree covers only that worktree, so each new one
starts without the skills or on an old version. Others who open the repository
see that it uses the plugin and install it once themselves. In a terminal, from
the main checkout:
claude plugin marketplace add shady2k/skills
claude plugin install shady2k-skills@shady2k --scope project # or --scope userInside Claude Code, /plugin marketplace add shady2k/skills and then
/plugin install shady2k-skills@shady2k do the same and ask for the scope.
To replace installations made inside worktrees, install from the main checkout
as above, then remove each worktree's own. claude plugin list shows where each
one was made. In each such worktree, with the scope it was installed at:
claude plugin uninstall shady2k-skills@shady2k --scope local # or --scope projectTwo catches:
- An installation in a worktree that no longer exists stays in Claude Code's list. Recreate the empty folder, run the uninstall there, then delete the folder.
- Uninstalling at
projectscope inside a worktree rewrites the repository's shared.claude/settings.jsonthere. Restore it afterwards withgit checkout -- .claude/settings.json, so the repository keeps declaring the plugin for everyone.
Start a new Claude Code session in the target project, then run setup. Set aside time for it: see What setup takes.
/shady2k-skills:setup-shady2k-skills
Invoke other plugin skills the same way, for example
/shady2k-skills:take-task.
Inside Claude Code:
/plugin marketplace update shady2k
/plugin update shady2k-skills@shady2k
An update applies to the scope you installed at: once for project (from the
main checkout) or user, per folder for local. Restart running sessions after
installing or updating: a session sees the skills it started with.
Start a new session. If a skill then says the project's installation is out of
date, run /shady2k-skills:setup-shady2k-skills there; most updates need no setup.
Run these commands in your terminal (verified with Codex CLI 0.154.0):
codex plugin marketplace add shady2k/skills
codex plugin add shady2k-skills@shady2kStart a new Codex session in the target project, then run setup in the chat. Set aside time for it: see What setup takes.
$shady2k-skills:setup-shady2k-skills
Invoke other plugin skills the same way, for example
$shady2k-skills:take-task.
In your terminal:
codex plugin marketplace upgrade shady2k
codex plugin add shady2k-skills@shady2kStart a new session. If a skill then says the project's installation is out of
date, run $shady2k-skills:setup-shady2k-skills there; most updates need no setup.
See Codex installation details for local checkouts, compatibility notes and isolated installation tests.
Run these commands in your terminal (verified with omp 18.1.17):
omp plugin marketplace add shady2k/skills
omp plugin install shady2k-skills@shady2kThis installs for you in every repository (--scope user, the default), which
is what the set needs: omp's project scope is kept per checkout, so each
worktree would start without the skills or on an old version. omp can also
load plugins from Claude Code's own list, if you turned that on; install
through omp anyway, so that its updates reach you.
Start a new omp session in the target project, then run setup in the chat. Set aside time for it: see What setup takes.
/skill:setup-shady2k-skills
Invoke other skills the same way, for example /skill:take-task.
In your terminal:
omp plugin marketplace update shady2k
omp plugin upgrade shady2k-skills@shady2kStart a new session. If a skill then says the project's installation is out of
date, run /skill:setup-shady2k-skills there; most updates need no setup.
See omp installation details for local checkouts and isolated installation tests.
Install the full package, including all twenty-four skills and Jev's MCP server
(verified with @earendil-works/pi-coding-agent 1.0.0):
pi install git:github.com/shady2k/skillsThe default personal install covers all projects and worktrees. Node 22.19.0 or
later must be on PATH. Jev still requires the project's consent and existing
credential setup; installing the package does not grant either or call a model.
Start Pi in your project, then run setup in the chat. Set aside time for it: see What setup takes.
/skill:setup-shady2k-skills
In your terminal:
pi update --extensionsStart a new session. If a skill then says the project's installation is out of
date, run /skill:setup-shady2k-skills there; most updates need no setup.
See Pi installation details for local checkouts, verification, project scope and hosts without the native MCP registration API.
Install all twenty-four skills as a personal package, available in every project (verified with Prime Agent 0.9.8 and 0.10.0):
prime-agent package install git:github.com/shady2k/skillsPrime loads the skills but cannot register Jev from a package extension. If you want Jev too, connect it once through Prime's native MCP support:
prime-agent mcp add jev -- node "$HOME/.prime/agent/git/github.com/shady2k/skills/mcp/jev-server.mjs"Jev still needs the project's consent and its existing credential setup; package installation does neither.
Start Prime Agent in your project, then run setup in the chat. Set aside time for it: see What setup takes.
/skill:setup-shady2k-skills
In your terminal:
prime-agent package updateStart a new session. If a skill then says the project's installation is out of
date, run /skill:setup-shady2k-skills there; most updates need no setup.
Updating Prime Agent itself (prime-agent update) keeps the package. If the
skills are missing afterwards, check that prime-agent package list shows
git:github.com/shady2k/skills, and if it does not, run the install command
again. See Prime Agent compatibility
for local checkouts, project scope and the limits of automatic Jev support.
Use the universal installer if your agent reads SKILL.md files. This is also
an alternative to the plugin for Claude Code and Codex, not an extra step.
npx skills@latest add shady2k/skillsSelect your agent and install the complete set, including the installer.
Run setup-shady2k-skills in your agent's skill syntax: standalone Claude Code
uses /setup-shady2k-skills; standalone Codex uses $setup-shady2k-skills.
Individually installed folders remain self-contained, but a workflow that needs
another skill must have that skill installed too. When switching installation
methods, inspect and remove only the previous installation of this set;
preserve any locally edited skill files.
In your terminal:
npx skills updateStart a new session. Run setup again only when a skill says the installation is out of date.
If the repository works this way for the whole team, its agent doc says so and gives the install line. In Claude Code the plugin's source is already known once you trust the folder; install the plugin once, then run setup, which only connects your clone (a few minutes). Without the plugin you can still commit: the hooks tell you in plain words what a commit is missing.
The first setup is not a five-minute step. It reads the project, connects or chooses a tracker, goes through the existing queue with you, agrees the working settings and then proves that every check really fires: it plants a violation, watches the hook reject it and undoes it. The agent does the work, but it needs you for the decisions: which work is current, what waits, what was abandoned, which settings to change.
Setup shows its progress as six steps, telling you at each one where it is, what comes next, whether it needs you, and a rough time estimate with its reason:
- Look around: reads the project and tracker. No input from you.
- Tidy the queue: agrees with you what is current, waits or was abandoned. Needs you; the long step on a large backlog.
- Agree the settings: first, whether the process is for you alone or for everyone in the repository; then one recommended profile to accept or adjust, and an explicit question about which language documents, tasks, commit messages and code comments are written in (English recommended), whether this project's text may be sent to Jev, a fast decision model (below), and how the questions you must answer reach you: one at a time (recommended) or several in one message. Needs you once.
- Connect the checks: hooks, CI and the tracker adapter. No input from you.
- Prove it works: makes the checks fire on planted problems. No input from you.
- Finish: lands the installation; may ask your approval to merge it.
How long depends on the project. A new project with an empty tracker usually fits into one session. An existing project with a large, neglected backlog can take several: the cleanup is agreed with you step by step and is reversible, and nothing is deleted in bulk. The document check is often its own stage after setup; work does not wait for it.
A rerun after an update is shorter: earlier answers are kept, and only new settings and the proofs are redone.
Jev, if you want it. Setup asks each project whether its text may be sent
to Jev, TypeSafe's decision model, and where its key
is. With it, an agent hands over batches of judgements it would otherwise
read its way through: which of hundreds of issues a new one duplicates, which
of many failures share a cause, which work a long transcript or log belongs
to. Measured on this repository's own history, it attributed 25 of 26 sessions
to the right one of 81 issues in under a second each, for about a cent in
total. The agent sees it as a tool in its list and hands it the file a search
or a run wrote, not text it has already read, with a few questions at once:
yes or no, one of given answers, or a place on a scale. Its answer is taken
only where it is sure, and how sure is your choice per project (0.9 unless you
change it, with the version of Jev it was measured on); the rest the agent
reads itself. Secrets are removed, and hosts, issue ids and the people the
repository knows replaced, before anything is sent; this goes by shape, so a
name nobody recorded or a secret with no recognisable form can still get
through. The key stays on your machine, never in the project, and no project
can name its own place for it. Write
$XDG_CONFIG_HOME/shady2k-skills/jev.json
(~/.config/shady2k-skills/jev.json by default) holding one of three
forms: {"key": {"env": "MY_JEV_KEY"}} (the name of an environment
variable), {"key": {"file": "/path/to/key"}}, or
{"key": {"command": ["program", "args"]}}, whose output is the key.
That file wins while it exists, and one that is broken is reported by
its own path. With no such file, Jev uses JEV_API_KEY from the
environment of the process that runs its server — the harness that
starts it, not only your shell — and the connection must be restarted
after that environment changes (in Claude Code, /mcp). No key value
is ever printed, and node jev.mjs status says which source was used. The text
goes through OpenRouter to TypeSafe, or to TypeSafe directly, and TypeSafe
keeps it unless you have a zero-retention agreement
with it. Without consent or a key nothing changes. How accurate it is on your
project is measured when you ask.
Every setup invocation rechecks the entire installation, including one whose version matches. It selects and initializes a tracker if needed, snapshots and cleans an existing queue with you, preserves valid prior choices, verifies adapters and execution commands, proves local/CI hooks and lands the result. New settings are presented as one recommended profile: what each controls, why it is recommended and the consequences of changing it. Accept the profile or change only named entries. Explanations match your role (product engineer by default); only material unresolved decisions need separate questions. Existing answers and delegated routine choices are not needlessly asked again.
The repository's installation is what landed: the checks, the shared settings and the integration doc. Setup lands it with one merge and commits nothing after it; a failed or unfinished attempt stays on its branch. Your plugin, hooks and runtime are yours and never committed. Before changing anything, a skill compares your plugin's setup version with the repository's: equal means work on (connecting your clone first if needed, a few minutes); newer means the repository's installation needs updating through setup; older means you update your plugin. Most plugin updates change no setup version and need nothing. This is a first-use guard and an update instruction, not a claim that every harness runs an automatic update hook.
I built this set for my own project, which agents build, out of the problems I ran into there.
- Light skills oblige nothing. A skill can be invoked at any moment or never, and when nobody invokes it no process is followed. Heavier frameworks did not fix that; they only made each step more expensive.
- The tracker became a dump. Most open issues were marked ready, and most of those "in progress" had not been touched for days. A status that is false almost every time is not a status, and a queue where nearly everything is ready cannot tell anyone what to do next.
- Work planned too far ahead went stale. Many epics were created in advance and lost their point before their turn came. Epics did not fit a session and ran for days.
- Findings jumped the queue. Bugs and architectural gaps found mid-feature were put at the front and pushed the feature out by weeks.
- Names, not identifiers. A person does not remember issue numbers; agents kept talking as if they did.
- Losing the thread. After a break, or in an unfamiliar project, nobody could say at a glance what the product already does, how far the milestone has come, what is stuck and what the sensible next step is. The tracker holds the facts but not that picture.
So I keep the skills light and put the obligations in checks: a gate that fails on a broken backlog, commits that must name their task, documents that must be ready before work starts. The details and the history of each decision are in docs/design.md.
"Let's imagine" or "just discuss" starts brainstorming, not a setup interview.
The agent contributes ideas, explores other perspectives and tests assumptions.
It understands your reasoning before independently agreeing or disagreeing.
Discussion and read-only research may end without a decision, file or task.
Scratch experiments do not become production work automatically.
Setup establishes the tracker and a usable queue; a milestone charter sets the
current scope. take-task then chooses the stages a piece of work passes, by
the life cycle's tailoring: size, uncertainty and risk decide, and each skipped
or narrowed stage says its reason. The shortest path is the default, so a
trivial, understood change is the change plus its check, a small feature is a
short spec and one stage, and uncertain work adds discussion, research or a
prototype, then the spec; a design decision comes after the spec where the
change changes the system's shape; then the stages. TDD is a separate project
choice.
A stage finishes something observable with its own DONE WHEN and is accepted before the next stage builds on it; a task, not a stage, is sized for one session. Independent tasks, stages and features may execute in parallel. Dependencies name required results or conflicts, never list order or hierarchy.
Workers run static checks and related tests, including affected neighbouring behaviour. In TDD mode they work red → green → local refactor; in test-after mode checks follow implementation. Workers preserve returned results as submitted, with their revision/location and evidence. The coordinator integrates each result and records it as implemented, making it available to dependants in the same stage. It is not yet closed. Across stages, prerequisites wait for acceptance.
The assembled stage receives full checks, scoped mutation testing and final
review, preferably by another model. Corrections receive fresh verification.
close-out synchronizes the accepted change into current capability specs and
closes the tasks and stage only with evidence for the accepted revision. A
handoff preserves implemented work, unfinished acceptance and pending publication.
Past the merge, ship-release takes the change to its users — narrow to the
merge where that is what reaching them means here — then operation and upkeep
belong to handle-incident and check-upkeep, and validation after release is
reading the measures the hypotheses waited on.
Every commit belongs to existing leaf tasks, including documentation, research, prototypes and setup. The commit-message hook and CI enforce links; the separate backlog gate enforces structure.
What for. Three things. Estimates: a run promises its result from how long similar work took on this project, not from a model's sense of time, which runs short, or from a developer's hours, the wrong yardstick for an agent. Your attention: it is the scarce resource, so the figures show how much of your time a feature cost and how often you had to step in, and whether runs get cheaper, faster and need you less. Overruns: a run past the time its result was promised for is found and reported, not assumed to be still running.
What is measured. Every minute of a session's clock goes to exactly one bucket, so the buckets always add up to the clock:
| bucket | what it is |
|---|---|
| model | the model generating |
| tools | tools running: edits, tests, builds, the shell |
| coordination | the rest of an agent's turn: hooks, permission prompts, waiting on a worker or subagent it started (whose own minutes are counted in its own session) |
| you answering | the gap before your message, or a question waiting on you, up to 10 minutes |
| you away | the same, past 10 minutes |
| nobody | gaps that no message of yours ended |
The same minutes are split by phase of the work (orienting, exploring, planning, building, debugging, wrapping up, setup, and unattributed where nothing in the record says what for) and by kind: writing code, reading, tests, builds, CI, git, delegating. Cost, tokens and lines changed are added where the agent records them.
How. Nothing extra is logged while you work. The figures are read from the session transcripts the agents already keep on your machine: Claude Code, Codex, omp, Pi and Prime Agent. Each number is either read from what the agent recorded or measured from its timestamps, and says which. What an agent does not record (Codex keeps no cost) is unknown, never zero. The only judgement is the 10-minute line between answering and being away, and it can be moved. A session belongs to the project by its git repository, including worktrees and working copies since deleted.
The history is kept on the items in your tracker, not on a machine, so every
machine and session reads the same. When a session takes an item, it posts a
claim; when it stops, a receipt with what it spent, by phase and by who spent
it. A feature run adds its forecast by phase at the start and a summary at the
end: the forecast against the work, and how long the work occupied, parallel
sessions counted once. After the feature closes, close-out takes the run's
retrospective from that record — the largest overruns against the forecast by
phase become findings — and asks you nothing about how the run went. A session
whose transcript is on
another machine makes the figure "at least this, incomplete"; one no machine
has stays unknown, with the reason. The records carry numbers, the agent's
name and a one-line note, not the conversation.
Where you see it. Ask ask-shady2k: where the time went, how past runs
went, how long work really takes here, what was done since yesterday. A run's
preflight quotes its estimate with what it rests on. The scripts beside
take-task give the raw figures: ledger.mjs time and sessions for this
machine's sessions, runs.mjs time, pace and report for the records in
the tracker.
Ask ask-shady2k for your statistics ("stats", "what did the day look like")
and it prints the picture as drawn: ledger.mjs stats shows one day as
twenty-four hour rows, each hour a stacked bar by kind of activity with the
day's totals by phase and by kind; the week, the month and all time come as a
heat map of agent-hours a day with the headlines — the busiest day, the
longest single stretch of work, sessions, cost, hours by agent and, where the
records name them, by model. Colour on a terminal, plain text on paper,
--json for other tools.
What it is not. Not a timesheet of you: your time away is in no estimate, and the line between answering and away is there to keep it out. The figures go nowhere but your own tracker. Only where the project agreed to Jev, a transcript that never names its task may be sent to it, masked, to ask whose work it was.
| check | rejects |
|---|---|
off-milestone-open |
live work outside the current milestone |
finding-budget |
admitted findings beyond the explicit budget |
idea-in-queue, idea-blocks-work |
ideas offered as work or blocking it |
blocked-by-deferred |
live work waiting for deferred work |
stale-hold |
active work unheld or apparently abandoned |
merged-but-open |
live work a commit already on the main line names — reported with that commit, so landed work is closed rather than counted |
epic-without-criterion |
a live feature/stage without a meaningful DONE WHEN marker |
area-label, label-vocabulary |
missing/multiple areas or unknown labels |
parent-cycle, dependency-cycle |
cycles in hierarchy or live prerequisites |
nonleaf-dependency |
a blocking edge a container carries instead of a task — an order may sit on a stage that has no tasks yet, and moves onto them with them |
started-without-agreement |
a feature whose work has started before its direction and then its plan were agreed by the owner, recorded in their words and checked in that order |
implemented-without-evidence |
implemented work without recorded integration and local-check evidence |
submitted-without-evidence |
submitted work without a durable result and local-check evidence |
stale-edge (warning) |
absent or long-untouched prerequisites needing review |
orphaned-outcome |
an outcome of the current charter that no live or closed stage serves |
unobservable-first-stage |
a feature's first stage that shows a person nothing where the feature says they see it, beyond one declared prefactoring stage |
check-commits.mjs |
unlinked commits or links to absent issues/containers, and code changed for a task whose understanding is not admitted |
check-docs.mjs |
unfinished required fields, missing scenarios/task links, conflicting or stale deltas, missing coverage, stale/missing receipts and unsynchronized current requirements, a change record with no place of observation, and a screen whose named mockup is not in the tree |
check-present.mjs |
a path the agent doc, glossary, architecture or current specs name that the change removed, or a link it broke; older dead paths, code no document mentions and documents left behind are reported |
check-product.mjs |
a product document, practice record, spec or change record out of form, a placeholder where an open question belongs, an id the set's own documents name that does not exist, a link to a document that is not there, a requirement that names code and a quote that is not where it says it is; prose the set does not write is not searched for ids |
The backlog strength is chosen at setup: block-new blocks introduced errors
and reports old debt, block blocks every error, report only reports policy
violations. Invalid input fails in all modes. Commit links are mandatory
independently of that choice. Project adapters parse messages and select commit
ranges; setup must prove those parts as well as the shipped checks. Document
readiness/acceptance checks are also mandatory independently of backlog strength.
They consume deterministic exports, a separately selected policy and verified
runner/approval receipts. The checker does not authenticate those inputs itself.
The checks do not prove behavioural correctness, truthful test evidence, semantic task relevance or that the right scope was chosen. Session sizing, next-milestone decomposition and understandable titles are still instructions, not executable checks.
Everything lives in docs/ beside the code, in Markdown, so a behaviour change
and its spec travel in one pull request. For a new repository, begin with the
vision, the first milestone and one useful change; the rest appears when needed:
docs/vision.md # audience, problem, key journeys, success signal, exclusions
docs/roadmap.md # or a section of the vision
docs/glossary.md # domain terms and the names of the system's own parts
docs/milestones/<milestone>.md # agreed scope; the first one is the MVP
docs/system/architecture.md # arc42 sections as needed, the target architecture in its solution strategy, C4 diagrams in Mermaid
docs/system/capabilities/<name>.md # current behaviour by capability, requirements in EARS
docs/changes/<change>/change.md # a feature's proposed requirement changes
docs/changes/<change>/design.md # optional technical design
docs/decisions/NNNN-<slug>.md # decision records (MADR)
docs/explorations/ # optional retained research
Specs are kept by capability, not by feature: they always say what the system does now, and a feature's changes are merged into them at acceptance. Diagrams are Mermaid blocks, which GitHub, GitLab and Gitea render as they are; never drawn with characters. Where a customer requires a ТЗ or a test programme by Russian standards (ГОСТ 34.602-2020, ЕСПД), the agent drafts it from these documents on request, asks for what they do not hold (the parties, dates, financing), and leaves its formal approval to the contract; it is never a second copy kept by hand. The templates follow established practice: ISO/IEC/IEEE 29148, arc42 and C4, MADR, EARS, OpenSpec.
These are defaults, not required paths. Setup maps existing documents in place, including projects using Superpowers, Spec Kit or OpenSpec. It does not uninstall them, move their files or create a rival task list. Choose one workflow owner and one canonical source per artifact. An old plan is intent, not proof of current behaviour. Baseline only the legacy capabilities being changed, then grow coverage through accepted work. Independent changes do not acquire blanket dependencies.
The document contract and templates define four checkpoints: product intent, feature readiness, stage evidence and current-spec synchronization. The project adapter parses its chosen document format deterministically; there is no universal Markdown importer. Protected CI can block merges; blocking direct tracker closure requires an actual transition guard. A local hook or prose instruction is not a tamper-proof boundary.
-
0.145.0 reads the target architecture from the architecture document your project already keeps, with nothing new to set. The strategy is found in the one document your configuration already lists among the documents that describe the present — or in
docs/system/architecture.mdwhere you listed none — so the place is named once, by the project's own document structure, and every brief carries the same list as before. Where two of your documents hold a solution strategy, the purpose command stops and names both instead of choosing one for you. Everyone who updates runs setup once, because the installed check changed and setup drops the setting that used to name the document. -
0.144.0 keeps the architecture you decided in front of every piece of work. How you said the system is to work — each principle with the consequence it has in practice, what one does because of it and what nobody does — now stands in the architecture document's solution strategy, apart from the sections that describe what exists today. Every worker's brief carries that list whole, not a summary and not the part somebody thought applied, and review and acceptance judge the work against it. Where the code has drifted from a principle the code is fixed; no principle is rewritten to describe the drift, and a principle changes only when you decide it does. A principle you decide is read back to you as its consequence, so a misunderstanding shows up at the decision rather than weeks later in the code. Where your project records no such list, setup asks once — showing a draft taken from your decisions, the vision and the code — and does not finish until you confirm it, correct it by name, or say there are no principles; a feature run in such a project asks the same before it leaves you. Everyone who updates runs setup once.
-
0.143.0 makes the set say one thing about a landing nobody read first. Where your checks were the only gate in front of a change that broke your main line, it is still reverted first and repaired by a second landing; where your own approval stood in front of it, the repair is judged like any other change and the revert is yours to ask for. The rule now reads the same whether you land a whole feature as one pull request, one change at a time, or the day's work as it is made, and the same where a check is red. A run also removes the checkouts and branches it created at its last landing, not its first, so the stages still to land keep what they need. No installation has to be redone.
-
0.142.0 holds building that is handed to other agents to a run's rules. When you ask the agent to build by coordinating other agents — dispatching workers, taking their results in, asking another model to review — that is a run:
take-taskstarts for it, on your word as before, and its review and building rules apply from the first dispatch instead of only when a feature was formally taken. The review converges the same way wherever another model is asked: one full review, then approval with comments, then a blocking fix verified on its own change and no second round.ask-shady2ksays in one line when product changes are landing with no run open for them, and recommends the run that work should be under. Two rules behind such work are sharper: a machine check of a rule is scoped by the property it guards rather than by the folder it was written for, and is proved by catching a violation planted outside that place, so moved code stays judged; and where acceptance is judged on sample input, at least one sample is input the builders never worked against, or the acceptance says it is not independent. Nothing in your installation changes: no setup rerun. -
0.141.0 lets you choose how work reaches your main line, and lands it that way. Setup now asks one question it used to answer by looking: one pull request per feature that you merge, a branch per change merged as soon as its checks pass, or trunk-based, where the day's work lands the day it is made. It recommends one, says what the recommendation rests on — who works in the repository, whether a review gates the main line, how you release, what the checks cost — and says what each practice costs you. A run then lands as your answer says it does — one pull request per feature, a landing per change, or the day's work landing the day it is made — and every rule in the set follows your answer instead of assuming one. A project that keeps what it does today answers once and nothing about its runs changes; a project that was never asked keeps one pull request per feature, exactly as before. Where one of your own rules stops part of a practice — a protected branch, a required approval, a merge queue — setup names the rule, offers the nearest practice your rule allows, records your answer with the constraint named, and changes no protection, hook or queue setting. A run keeps the practice it began under, and a run picked up later says in one line when your record has moved since. Everyone who updates runs setup once, in every project: the question is asked there, and a project that answers it nothing else about its work changes.
-
0.140.0 prepares how work reaches your main line, without changing how anything lands today. The set's rules stop stating one way of landing as if it were every project's: they now say this project's way of landing, and one new reference holds that way in its own words — how work goes, who merges, what you see and when, what it costs, what it suits, and how hard it is to leave. For you, nothing changes yet: a feature still arrives as one pull request you merge, setup asks no new question, and no installation needs redoing. The next version offers the choice, with a recommendation and what each option costs.
-
0.139.0 binds what a gate can check of working in increments. A breakdown is judged stage by stage now: every stage still open ends in something you can open, its DONE WHEN naming a place your feature already says you reach the outcome in, with the single preparatory stage still allowed — once, and only before the first stage that reaches you — and a stage you have already closed left alone as history. A stage that shows nothing after the first one that did is the breakdown to re-cut, not an accepted plan. A plan also stops arriving before its design: the feature says where the design is recorded, or that this change needed none and why, and a feature whose work started without that line is refused. Both read what a line says, never whether the record behind it is any good: that answer stays with you and with the review. Rerunning setup adds the line where the design is already recorded, and lists with your agreement the features already under way that cannot honestly acquire it.
-
0.138.0 makes work advance in increments, so something is openable early and keeps being openable. A breakdown now starts with the thinnest path through every layer the outcome touches, run on the real input the product will meet - a fixture shows the path is joined, the real input shows it runs - and every later stage widens that path instead of finishing one layer across before the next begins. A stage has a size: about one working day of agent time, cut at the breakdown and not lengthened afterwards, and each one ends in something you can open. Before the options,
to-designreads how existing products, libraries and standards solve the same problem, from primary sources, and a mechanism written here says what the existing one fails on; a change of the system's shape is designed before it is broken down, andto-stagessends it back there until that design is recorded, whoever called it. A check loop that costs more than the work it guards becomes the next work:take-taskputs the loop in every worker's brief, a long run on real input is first tried on the smallest real sample with its duration projected from that sample and a stop bound set before it starts, and you hear about the waiting without asking. A stage past its forecast by half, or with its end moved twice, is re-cut into something you can see rather than carried on, and matching an old mechanism is no longer an acceptance criterion unless you chose it. -
0.137.0 keeps a merge honest when a recording names a store commit this store does not hold. Two different recording files that both name a commit are compared by the trees of the commits they name, and a commit this store does not hold - a store ref rewritten outside the mechanism - answers "no files", exactly as a commit that holds no state file does. Two recordings whose commits were both absent were therefore read as one state, and the merge went through with only one side's recording. Now a comparison that read no commit proves nothing: the merge stops and names the commit this store does not hold, as it did before 0.136.0. A recording whose commit IS here and holds no state file is still merged rather than refused, two different states for one revision still refuse with the sentence they refused with before, and the merge stays as cheap as 0.136.0 made it - one commit on a store of 500 recordings still reads two states, in the same time and memory as one on a store of 50. Projects using the off-branch tracker rerun setup to get it.
-
0.136.0 makes a commit on a large tracker cost what the commit changed. A tracker store that has recorded a few hundred revisions used to spend most of a core for minutes and hold over a gigabyte on every commit - 2:28 of CPU and a 1.49 GB peak on a store of 4,625 items with 216 recordings, growing by one recording per commit - because the merge read every recorded state whole, on both sides, whether or not it had changed. Now it reads the two sides' listings once, compares two recordings by the trees of the commits they name, and reads a state only where the two sides really differ: one commit on a store of 500 recordings read two states, in the same time and the same memory as one on a store of 50. Two different states for one revision still refuse, with the sentence they refused with before. Projects using the off-branch tracker rerun setup to get it.
A read that was killed is no longer taken for a file the commit does not hold. A
git showthat fails - killed when a supervisor stopped the sync, or lost to memory - used to answer "the commit does not hold this file", so a stopped watcher reported that the store's history had been rewritten, and a merge could write a state missing a file. A failed read is now asked of the commit's tree (only a tree without the path is an absent file) and is retried once before it is named as a failed read; a stop that interrupts a read ends as a stop, with nothing committed and the next start continuing. The sentence a clone without write rights is told now says what happens: the write stays here, and the next push that lands - a sync, or any later run - carries it. -
0.135.0 connects a clone that can read the tracker's remote and cannot push to it: it keeps its hooks, its pointer and its reads, and says in one sentence that it cannot publish. A store the remote already holds but this clone could not fetch now stops connect, naming the ref, instead of appearing empty. Projects using the off-branch tracker rerun setup to get it.
A clone without write rights - an anonymous clone, a read-only deploy key, a copy on a machine that has no rights - is the ordinary case this mechanism got wrong in three ways. Now:
- a failed fetch is never an empty tracker: the store's own ref is fetched
with a bound that fits a large store, and the fetch's result is read. A ref
the remote holds that this clone could not fetch stops connect, which names
the ref and the failed fetch and writes nothing - no ref, no worktree, no
config. Only a remote that answers without the ref gets a new store, and a
repository with no remote still gets its first store.
--offlinewith the ref absent here is refused rather than guessed: it could only choose between a first store and a store it could not fetch; - a refused write is a refusal: a push is classified by what the remote
did, not by its words. Text about the network alone is an unreachable remote;
text that may be about rights -
terminal prompts disabled, an HTTPS 403,Could not read from remote repository, a key marked read only,No anonymous write access- is settled by one bounded read, because a remote that answers its reads and refuses the write is refusing. A clone that cannot publish is told once and never promised that a later attempt publishes; - the connection does not depend on a push: connect takes the machine's
ordinal, points the checkouts, installs the record hooks and writes its
config before it publishes anything. A refusal leaves a complete connection
and exits 0; any other push failure still fails, after those local steps. In
a read-only clone a commit's record step keeps its recording here, the
watcher stays up and says the sentence once rather than per tick, and
statussays the clone cannot publish.
- a failed fetch is never an empty tracker: the store's own ref is fetched
with a bound that fits a large store, and the fetch's result is read. A ref
the remote holds that this clone could not fetch stops connect, which names
the ref and the failed fetch and writes nothing - no ref, no worktree, no
config. Only a remote that answers without the ref gets a new store, and a
repository with no remote still gets its first store.
-
0.134.0 redoes a recording that timed out at commit time with exactly the state the tracker had at that commit, a change made seconds before it included, and refuses the redo with the ways out named when that state cannot be proved. Projects using the off-branch tracker rerun setup to get it.
The marker added in 0.133.0 kept the store commit read when the hook started, and that commit is the last published state. A tracker write the watcher had not exported yet - younger than its five-second bound, or held back while the store was busy - was in no commit at all. Closing a task and committing at once is exactly that sequence, so the redo recorded the state from before the close as that revision's permanent history: the gate reads a recording with
--at, and the baseline underblock-newcompares against it. Now:- an export keeps what it proved: the watcher's publish, and a publish run by hand, store the database's own change signal - read just before they read the database - beside the store commit they made from it, in the machine's own state beside the store. That pair is the machine's proof of which state its store head is; a commit that changes the head without a signal of its own drops it, a flush the tracker refused proves nothing and drops it too, so a stale pair or an unproved one can never read as proof;
- a timed-out marker names a commit only while that proof stands: when the signal standing now is the paired one and the paired commit is the head, the marker keeps it, and the redo is byte-exact, as in 0.133.0. When it is not - a write the watcher had not exported, a pair an older release never wrote, a head another command moved on, or a recipe that declares no signal - the marker keeps no commit and the push and the retry name the ways out instead of passing a later state off as that revision's;
- an export that came too late is refused, not guessed: only an export whose proof was on disk before the hook looked at the database can say what the state was. One written afterwards could hold a tracker write made after the commit, so the marker keeps no commit, and the ways out are named instead. The hook does not wait for such an export: waiting would trade the proof for a few seconds.
-
0.133.0 makes rerunning setup really upgrade the recording hooks your checkouts run, and keeps a recording that timed out at commit time honest: it is redone with the tracker state that revision had, never a later one. Projects using the off-branch tracker rerun setup to get it. Thanks to avlokhturov, whose pull request #59 found all three defects and carried the first fixes for two of them.
The 0.132.0 notes said rerunning setup rewrites the record hooks; it did not. A hook installed before that release already carried its marker, and reconnect skipped it, so every commit kept running the old recording command without the bounded hook behavior. The timeout the release added then undid itself wrongly: the command the push named recorded the tracker as it stood when you ran it, under the old revision, and a recording is the one history that revision will ever have - the gate reads it with
--at, and the baseline underblock-newcompares against it. Now:- rerunning setup upgrades the hooks it generated: the exact old command, directly after its own marker, is brought up to date where it stands. Your own commands in that hook, the bytes around the generated line and a hook your project keeps in its tree are not touched, and running setup again changes nothing;
- a timed-out recording is redone exactly: when a hook gives up on the store, the marker it leaves also keeps the store commit holding the state that revision had. The push names that state and the command that restores it, and the redo records exactly that commit, so tracker writes made after the commit never become that revision's history;
- a timeout that saved no state is refused, with the way out named: a marker written by 0.132.0 keeps no state, so a retry refuses instead of passing today's tracker off as that revision's, and says what to do - make a new commit (or amend one) so its hook records a fresh revision, or sync when another machine already recorded it;
- the candidate-size proof waits for the candidate: it measures after the import boundary instead of between directory creation and sparse checkout, which is what made it fail on main on 1 November.
-
0.132.0 makes an idle tracker watcher cost almost nothing and stop making your commits wait, and makes a recording that timed out at commit time say so at your push. Projects rerun setup to get it.
The watcher exported the whole store and held its lock once a second even when nothing had changed. On a store of a few thousand items that is a busy CPU core, and every record a commit's hook started queued behind that lock: some hit the lock timeout, the hook swallowed the failure, and the next push refused the revision as one that was never recorded, which names the wrong cause. Now:
- an idle watcher does no work: the tracker's own change signal — for br,
the database, its write-ahead log and the shared-memory index beside them —
is read without the store lock, and a tick whose signal has not moved since
the last export takes neither the lock nor the export. While nothing changes
the poll backs off from one second to five, and a
recordstarted meanwhile gets the store at once; - a change is still published within the bounds you set: the signal is taken before each export, so a write that lands while the export runs is caught on the next tick rather than skipped;
- a hook's record never fails silently: it asks for the store a few times within about half a minute, and if it still cannot write it marks that revision in the machine's own state, never in your tree. The push that finds no recording now says the recording timed out at commit time and names the command that redoes it, and a later successful record removes the marker.
- an idle watcher does no work: the tracker's own change signal — for br,
the database, its write-ahead log and the shared-memory index beside them —
is read without the store lock, and a tick whose signal has not moved since
the last export takes neither the lock nor the export. While nothing changes
the poll backs off from one second to five, and a
-
0.131.0 stops a second implementation of something the project already has from being planned, built and accepted beside the one its decisions named, and stops autonomous work from starting on a plan nobody saw. From real use.
One run planned a new implementation with the old one's removal written out of scope, built it beside the path the project's decisions named, and had it accepted on its own description; both paths then stayed reachable, and the one nobody needed was the one that failed under load. Another took a short "yes" to a summary as consent to the stages, criteria and scope that followed it, none of which the owner had been shown. Now:
- before planning, what already does the job is what you read: a proposal that adds or replaces a mechanism carries the inventory of the entry points, modules, stores, commands, workers and pipelines the project has for it — what exists, what it extends, what it replaces — and a proposal with no inventory is not put to you;
- at decomposition, a replacement carries the old one's retirement inside the same feature, as a wide refactor already did; "removing the old one is out of scope" is your recorded decision, never a line the breakdown writes for itself. The project's standing decisions are read before the breakdown, and one it would contradict is put to you instead of built;
- at acceptance, the stage review searches the revision for every way that job is reached and reads the change against the recorded decisions: a second entry point, store, worker or pipeline beside the one a decision put there, or a retirement the plan promised and the revision does not carry, blocks acceptance. Where the stack can see it, one way in becomes one of the project's own checks;
- a run starts on an agreement about what you were shown: the direction, then the plan — the stages, what each makes true, their DONE WHEN and their order — each recorded on the feature with when you gave it and your own words. A yes to a summary authorizes nothing the summary did not contain, and the preflight refuses to start without that record;
- the gate refuses work started without it (
started-without-agreement). A line whose time does not parse, quotes nothing you said, or still holds a placeholder counts as none. A task that waits for no stage and a trivial change need no record, and a feature already under way when a project adopts the rule is listed once in the config, as work in flight is listed when time records arrive, so the rule judges what starts after that; - an order between two stages that are not broken down yet is now an edge
the tracker keeps, on the waiting stage;
nonleaf-dependencyrefuses it again the moment that stage has a task, which is where the order moved to. The ready list sees the order instead of a comment nobody reads.
Projects rerun setup once: the installed gate carries the new rule and the widened one, the project's integration records where the two agreement lines are written, and setup lists the features already under way so they are not an error on the day the rules arrive.
-
0.130.0 stops an agent from halting in front of a gate that refuses honest work, and stops one added check from disowning the results that came before it. From real use (#54).
A feature added a capability and two check ids, and every required result was recorded as passed on the final revision. The document gate refused anyway: a change that adds a check changes the policy its results are judged under, so every result was disowned, including those of checks whose definitions had not moved, and no record could pass. The run saw three ways out — edit the gate, close red, bypass the hook — all of them forbidden, and stopped. Now:
- a result stands for its own check's definition and for the settings that apply to every check, not for the whole list: adding a check asks for that check's result and leaves the others standing, a change to one check asks again for that check alone, and only a change to a setting that applies to every check asks for everything again. Results recorded before this version keep working while the policy has not moved, and are replaced one by one as the checks run again;
- the protocol says the gate — its hooks, the wrapper around the checks, the policy and the settings — was written into your project by setup, by an agent. A gate that refuses an honest record with nothing left to do is a defect in your project's code: a run diagnoses it, fixes it as a change of its own, with a case for the record it refused and a case for a record that really is missing something, and pushes the blocked work again. Where the wrapper is protected from the author, the fix comes to you as a ready decision: you decide it, the run does not;
- two refusals now say their likely cause: a change that adds a requirement the change is judged from already holds (the commit that added it is probably not counted as this change's), and documents brought to the change's end before closure (run the close phase, or keep current at the baseline until then).
Projects rerun setup once, so their installed checkers carry the narrower result binding and the new rule.
-
0.129.0 makes a change to a large tracker store cost what the change costs, not what the store holds. From real use (#52).
On a store of about 4,500 items kept off the branches, one comment took about 9 s to publish, and with several agents writing at once the sync service ran the machine out of memory twice in five minutes. Every merge, every sync that brought a change and every claim rebuilt the tracker's whole database from its state file, and the per-item merge read every item of three copies of the state. On a store that size the rebuild also ran into the fixed 20 s limit on a tracker command and was killed with no output. Now:
- a sync where only one machine changed the tracker merges nothing: your store takes the other side as it is, and the database takes in only the items that changed;
- a claim or a status change works on a copy of the live database instead of rebuilding one;
- the merge reads only the items the two sides disagree on;
- the whole database is still rebuilt where it has to be: an item deleted, most of the store changed at once, or a change br's own partial import would skip (an item whose update time did not move forward, which is what a comment renumbered by the merge or an edit from a machine whose clock runs behind looks like). Whatever br is given is checked against what it exported, and a mismatch is rebuilt rather than kept;
- the tracker's workflow policy (
.beads/policy.yaml: custom statuses and what entering one requires) travels with the store like its settings, so a project no longer carries it by hand; - a tracker command's time limit is yours to set (
--recipe-timeout, recorded when a machine connects; 120 s by default instead of 20 s).
Measured on that size of store on one machine: a comment published where the other machine had only connected went from 19 s to under 1 s; taking it in on the other machine from 17 s to 11 s; a claim from 35 s to 12 s. br itself still spends about 7 s and a few hundred megabytes on any import, however small, which only br can change. A project that runs the off-branch layout reruns setup to refresh its installed copy; no other project is asked to.
-
0.128.0 converts the tracker recordings earlier versions wrote, and stops reading them again on every command. From real use (#49).
A recording written by 0.121.0 held the whole state of the tracker, copied from the store's own working tree. That copy carries a file the project's git ignores — a tracker's database mirror — which no commit ever holds, and it can lack a file the commits do hold. 0.127.0 compared the two as equal sets of files, so no commit could ever match and it kept every one of the reporter's 1 110 recordings, converting none, and each later record, sync or publish read them all again. The comparison now counts only the files a store commit can hold, decided by the store's own git; a file the commit holds and the recording did not print no longer blocks the match, and what the recording did print must still be equal byte for byte. Your old recordings become references to the commits that hold their state, and the space their copies took comes back; what
export --atand your gate's baseline read at a revision is the same tracker data as before (the ignored file is no longer printed).A recording that still cannot be converted is now kept with its reason, in its own words: which state file differs from which commit and by how much, which file it prints that no commit holds, or what the file is instead of a recording.
statusgroups them by cause with a count and one example each and names the file that lists every one of them, the line after a repair names the top cause, and the same goes for the other refusals that used to state a verdict without saying what happened.And a pass that converts nothing is not repeated: what it can depend on — the recordings, the states the store's history holds, the project's ignore rules, the rule's own version — is remembered in the machine's folder, so a store whose recordings no commit can hold costs one read instead of one per command.
-
0.127.0 finishes the tracker repair on a store of any size, and stops a watch from restarting itself. Both from real use (#49).
The repair 0.126.0 shipped read every old per-revision copy into memory before converting any of them, so on the store that reported it — 1 106 copies of a few megabytes each, about 6 GB — the first command after the update died of the heap within three seconds and converted nothing, and the next one did the same. The watch, the commit hook and the merge hook all run that command, so landing the update would have stopped the tracker from publishing at all. A copy is now read one at a time, converted, written and dropped, so the conversion needs as much memory as one state, whatever the store holds, and it commits what it converted every hundred recordings: a run that is killed keeps its progress, and the next run finishes it. The repair of 0.126.0 now completes on a store of thousands of old copies; you delete nothing by hand.
A watch installed with 0.121.0 restarted about every twenty seconds — 510 times in six hours under one supervisor — with "the store is locked by pid ", where N was the watch's own pid, and it kept publishing between restarts. Its two rounds no longer wait for a lock their own process holds: they queue inside the process, and the store's lock is asked for only by a process that holds nothing, so a round that cannot take it is another command's and is skipped instead of ending the watch (a supervisor restarts an ended watch, which is the loop). A watch that restarts like that stops after this update; if you saw those lines in a log, they are history.
Setup now names every file a project copies and runs, not only the ones it named before: the helper that reads a command's values (
argv.mjs) and the one that opens a path only after asking whether it is a regular file (regular-file.mjs) are listed beside the checks, beside the mechanism, and beside the recipe, which imports the first of them from one folder up. A connect command that lists every file a hook reads, and tests that copy a fixed list, get the list right from setup's own text. A new check in the project's own test run follows every import of every file setup installs and fails when setup leaves one out, so the list cannot drift again.Projects rerun setup (0.57.0) to take the repaired mechanism and the named helpers.
-
0.126.0 stops your tracker's store from filling the disk. Two repairs from real use (#45).
The first, and the one that lost work: a write to the tracker that is killed while it prepares — a hook that times out, a session that ends, a machine short of memory — used to leave its working copy behind for good, because the only cleanup was a step that a killed process never reaches. In one project four such copies held 35 GB, the disk reached 98%, and the write that then failed was a commit's tracker state. The next tracker command, or asking how things stand, now finds what a dead run left — the copy, its registration in git, its result file — and removes it; a run that is still alive is never touched, and an outcome nobody has confirmed yet is kept, because someone must reconcile it. The copy itself is now only what a write needs: the tracker's committed state and the little of its local configuration the recipe declares, never the tracker's own backups or the history of earlier revisions, so a copy is kilobytes instead of gigabytes. And the report you get from the sync step now says how much the machine's tracker folder and the store take, and how many leftovers it found, so a leak shows up before the disk does.
The second: the store grew on every commit. Each code revision kept a full copy of the tracker's state — about 1 000 files of 6 MB in one project, 5 GB against 10 MB of items — and the tracker's own database backups piled up inside the store with nothing bounding them (9 553 of them, 5.5 GB, in eleven days). A revision now records a reference to the store commit that holds its state: one line instead of a copy, read back with exactly the same bytes by everything that asks for the state at a revision, including the baseline your checks read. Two different recordings of one revision still refuse exactly when they did, and the store's history is append-only, so a reference is never left pointing at nothing. The tracker's own backups are pruned after a successful import, keeping the few most recent.
Rerunning setup frees what an older version left: the dead copies, their git registrations and their result files go, old per-revision copies become references to the state they recorded (verified byte for byte; a copy no store commit holds is kept and reported, never guessed), and the piled-up backups beyond the bound are removed. It happens by itself, once, on the first command after the update; nothing to delete by hand. What the old copies took in the project's history stays there — history is never rewritten — so it is the working folder and the store that shrink, not the repository's past.
Projects rerun setup (0.56.0) to take the repaired mechanism and the repair of their own installation.
-
0.125.0 closes work whose change already landed. A bug or a task that waits for no stage — one filed on its own, or one hanging directly under its feature — is now closed by whoever merges its change, in that same step, with the merge revision and the checks the merge ran. Those shapes had no legal way to end: they could not be recorded as handed in, because that state promises an acceptance, and no stage was going to accept them, so they stayed open after their fix was already in the main line, were counted as remaining work and were handed to a worker a second time. A leaf inside a stage keeps the path it had: handed in, merged, and closed when its stage is accepted.
The backlog check gains a rule for what that left behind:
merged-but-openreports an open or held item that a commit already on the main line names, with that commit.take-tasknow reads the main line for such a commit before it offers an item to a worker,ask-shady2kbefore it reports what remains, and a coordinator does the same before it counts or dispatches: work that already landed is reported as landed and not closed, and closed, never counted as remaining or built again.A project that already has items in that state sees them by itself: once its tracker export carries the main line's commits, the next gate run lists each open item with the commit that landed it. Projects rerun setup (0.55.0) to add that list to the adapter and take the new rules.
-
0.123.0 keeps the tracker in step and never leaves a check waiting. Three repairs from real use (#42, #43).
The first: the watcher that keeps a project's tracker in step with every machine no longer stops on its own lock. It waited for a lock its own process was holding, reached the deadline and exited, and the supervisor restarted it into the same wait — hundreds of restarts in a few hours, and no tracker update meanwhile. Its publishing and syncing now queue on each other inside the process, and a round that meets another command's lock is skipped and said once in its log instead of ending the watcher. A command you run by hand still waits for the lock and then tells you which process holds the store.
The second, and the one that lost work: a tracker that refused to flush its database was read as having nothing to export, so the next merge and rebuild dropped a comment the tracker had already accepted. Now the recipe says what each refusal means. The harmless one — a store that has not imported the remote's state yet — is said and the state files stand. Every other refusal, including one the recipe does not recognize, has the database exported to a side file and merged into the state files per item before anything is fast-forwarded, so a write the tracker accepted survives. When that cannot be done the sync stops and says what is at risk rather than continuing.
The third: the product-documents check no longer waits for ever on a registry that is not a regular file. A folder walk takes only regular files, and a
docs/kinds.yamlthat is a named pipe, a socket or a device is a finding that names it, so the check exits at once instead of opening it. The same guard now stands before every path a check or the tracker mechanism reads from the command line or a folder walk.Projects rerun setup (0.53.0) to take the repaired mechanism, recipe and checks.
-
0.122.0 refuses an option that was given no value, and measures the time of a session you started in your working-copies folder. Two repairs from outside contributors (@avlokhturov), landed with their commits kept (#33, #28).
The first: an option of the backlog check that takes a value — the rules to run, the config, the baseline, the strength, the ages snapshots, the code revision, the task whose purpose is printed — used to take whatever word followed it, including an empty one. An unset variable in your own command was enough:
--baseline-config "$CFG"withCFGunset judged your baseline by today's rules and answered green, and--ages-from "$SNAP"quietly dropped the ages check. Every valued option now reads its value the same way, in the check and in its helper commands: a missing, empty, blank or option-shaped value stops the run, exits 2 and names the option, so no check can go missing without saying so. A bare-still means standard input where a command offers it.The second: when you start a session in the folder that holds your project's working copies — the folder named after the project, which is not itself a Git checkout — the receipts of that session were written as of unknown time, because the check could not place its transcript. That folder is now attributed to the project, so the session's real time is measured. A transcript that is present but belongs to no repository the project owns is refused (
TRANSCRIPT_UNMAPPED), and one whose identity cannot be read at all is refused too (TRANSCRIPT_UNREADABLE); neither can be closed as unknown time or dated from another record, because neither is an absent transcript. Only a transcript that is really gone follows the unknown-time rule as before.Projects rerun setup (0.52.0) to take the repaired checks.
-
0.121.0 answers a time you question with its basis. A duration or a date an agent says to you now comes from the same measurement a document's forecast uses: the pace of finished work in your project, with how many comparable pieces of work it rests on and the range between them. The old habit was a padded round figure, and, when you objected, a smaller figure with no more basis than the first. Now a figure you doubt is shown with what it rests on, or recomputed from it, and it changes only on new evidence — a narrower scope, a measurement the agent had missed — with that evidence named. Too little history is said plainly, with the nearest comparable work it measured and its time, or with no number at all. The same holds wherever a time reaches you: before a run starts, while a milestone is agreed, in a breakdown, in the queue cleanup, in a standup report and in the next step a skill offers. A dispute about a figure is not an order to change what is done next, and a reorder is put as its own decision. Nothing a project installs changed, so no project needs to rerun setup.
-
0.120.0 stops the product-documents check from guessing. Once a project keeps its first practice record, the check reads every Markdown file under
docs/, and it used to treat any word shaped like an id as a reference to a document — so a decision record naming a standard that merely shares that shape was refused, and nothing said how to write a word that is not a reference. Now the set's own documents — product documents, practice records, specs and change records — keep every id they name checked, exactly as before, and prose the set does not write, such as decision records and guides, is never searched for ids: there a reference is a link to the document's own file, and a link to a file that is not there is still refused. A refusal now says what to do: a word that only looks like an id goes in a code span, and in prose outside the set's own documents a reference is written as a link. No list of exempt names was added, so a new standard name is never a special case. Projects rerun setup (0.51.0) to take the check. -
0.119.0 lets your project choose how decisions reach you. The set was inconsistent: some skills asked one question at a time, others sent everything as one list, and nothing let you pick. A question whose answer the work waits for now arrives the way your project's settings say — one at a time, the default, or several in one message — and the skills that used to state their own habit follow that one setting instead. What does not change: every question still comes worked, with the recommendation, the alternatives and what waits on it; before you leave on a feature run, every decision the run will need is still collected — one after another or together, each with its recommendation — so nothing waits for a stop; and a summary you accept whole or correct by item, such as an approval or the settings profile, still arrives as one message. Setup proposes the setting in its profile, saying what changes in your words: only how many questions one message carries. Projects rerun setup (0.50.0), which asks once for a project that has no answer yet and keeps the one it finds.
-
0.118.0 makes a boundary judgement's quotes checkable without a model. A judgement record — the different model's answer, at a charter's or a design's acceptance, to which journeys and principles the document serves and which it breaks — no longer accepts a free sentence as its evidence. Each entry names one of the vision's journeys or principles by id, and quotes a passage copied out of the document it judges; the gate looks for that passage in the same text the record is bound to, forgiving only where the line breaks, and refuses an id the vision does not declare, a quote the document does not contain, and a quote too short to locate anything — a word, a bare id or a line of markers. A document edited after the record was given still voids it. You see this as one edit to a record you already have, and as an honest answer to "where does it say that?". Projects rerun setup (0.49.0), which rewrites the judgement records a live charter or an admitted change carries, in the owner's presence.
-
0.117.0 makes three things the set had only asked for in words into refusals, each turned on by the value it reads. A design record now lists its constraints — its limits, invariants and "never"s — in one closed section, each with an id, each a requirement with a check; a constraint that names a size is proved only by a check whose fixture declares at least that size, so a build cannot pass on a fixture smaller than the limit the design states; and the review that admits a change answers whether the build matched the design, with a "no" or a missing answer stopping admission. What the owner says now reaches whoever does the work: the vision keeps his journeys and principles with stable ids, every milestone outcome names in a
Serves:line the ones it serves, a design names the principles of its area and carries each as a constraint, a different model's judgement record answers at charter and design acceptance which of them the document serves and which it breaks, with quotes, and a new command prints for one task the vision items it serves in their current wording, whom it serves and where a person sees it, for the brief handed to the worker. A date a charter or a feature promises is no longer taken on trust: it stands beside the record the run script computes from the measured pace over the exact task set covering the outcomes it serves, and a record whose task set has changed is refused — while a project with too little history has its date accepted with the warning the record carries. Projects rerun setup (0.48.0), which adds ids to the current vision and charter without changing their text, records the principles the owner has already stated, and proposes the new switches,requireDesignMatchamong them. -
0.116.0 refuses two things the set had only asked for in words. Code for planned work can no longer be committed before its understanding is written down and admitted: a commit that changes a path your config marks as code, for a task whose change record is not admitted, is refused — whoever dispatched the work — and that record must now say where a person reaches the outcome and how they walk there, with a mockup file that exists in the tree where the place is a screen. And a milestone can no longer lose its person's path: an outcome of the current charter that no live or closed stage serves is refused, and so is a feature whose first stage shows a person nothing where the feature said they would see it, with one declared prefactoring stage allowed. A standalone bug or chore stays cheap: a criterion on the task itself is enough. Projects rerun setup (0.47.0): it adds a stable id in front of each outcome of the current charter without changing its text, and asks for the list of paths that are code. The two backlog rules follow your gate's strength: under
block-newwhat already existed is printed as debt and only new work is refused. The commit rule stays off until the config names the paths that are code, and a change record already admitted for work in flight gains the new section before its next gate run. -
0.115.0 stops three refusals that were about the machine or the branch rather than the work. A push is no longer refused because the remote holds refs your clone never fetched: a ref whose commit is not in your clone bounds nothing there and is skipped. A time record one session forgot no longer stops everyone's commits when this machine can still recover it: the commit hook recovers and posts the receipt before the gate judges, so only time no machine can recover stays an error, and a live session's span is left alone. And a refusal that read a value from your config now says so: it judged by this checkout's config, and if the value was changed on the main line, bringing the branch up to date is what clears it. Projects rerun setup (0.46.0) so their hooks recover before they judge and their push check skips refs it cannot read.
-
0.114.0 stops two concurrent tracker commands from stopping with a false "inspect the lock" error when the other command is only between its lock steps, and stops the tracker leaving a diagnostic file behind for every write it settles. A diagnostic stays only where a person must reconcile an unknown outcome.
-
0.113.0 lets targeted fix verification block newly introduced or exposed regressions without restarting full review for unrelated nits. Resumed external effects count as done only after identity and the requested result match.
-
0.112.0 keeps unrelated tracker writes when recording a code revision races with publishing or a lost push acknowledgement. Recordings are isolated until accepted and preserve the captured revision state across retries.
-
0.111.0 stops detached descendants of bounded commands on macOS as well as Linux. The native process snapshot is limited to one second; discovering descendants in their own groups requires permission to list processes.
-
0.110.0 keeps unrelated local tracker writes when conditional claims or transitions race with publishing. Pending conditions use isolated snapshots; lost push acknowledgements are reconciled or reported as unknown. Store locks publish complete ownership and never evict a live process by timestamp alone. Tracker sync also handles macOS physical-path aliases consistently.
-
0.109.0 gives shared reviewer policy, model/engine locations and worked decision material one authoring owner, linked from the steps that use them. Checkout requirements and approval boundaries stay the same. Published skills remain ready to install; template assembly and freshness checks run only in development and CI.
-
0.108.0 adds four rules and the skill text that carries them. A check no longer changes to reach green: a test, an assertion, an expected value, a skip mark, a silenced warning, a type or lint suppression or a lowered threshold may change only where the requirement it encodes changed, and the change says which one; anything else that makes a check easier to pass is a finding the review blocks on, and a bug fix that passes by weakening the check that caught it is not a fix. An action that reaches outside the checkout — a push, a pull request, a published version, a release, a migration, a deploy, a message, an item created or closed — is read from the system that holds it before it is taken, so a run that stops and resumes cannot publish, release or file the same thing twice, and a refusal that says it is already there is read as done. Depth is read off the change rather than off the word of the agent that made it: which stages run, how full the spec is, whether the design step is owed, how deep the review goes and which choices stop for you come from what the diff touches and from the project's settings, and where only judgement can decide, someone other than the author reads it and the deeper size wins. And a retrospective now looks the other way too: it lists the practices that caught nothing over the period, with what each costs, and proposes retiring or loosening the ones whose reason no longer holds — while keeping those that guard a rare but expensive failure, such as publication, permissions, data loss or security.
-
0.107.3 says and proves what connect does when a project keeps its own hooks folder inside the repository, tracked by design and shared by every clone: where every hook the layout needs already carries the marker line for its step, connect accepts the folder as it is and writes nothing into it, so that project connects on every clone and rerun; a hook that is missing or lacks its marker is refused by name, with the line to add. The rule itself did not change in this release — 0.107.2 already accepted such a folder — but nothing said so and no proof covered a tracked folder. Setup's own text now says it, and the proofs check a tracked folder byte for byte.
-
0.107.2 fixes five gaps a project met in use after moving its tracker off the code branches. The store is named after the main checkout of the machine, not the checkout a command happened to run in, so every linked worktree of one machine reaches the one store instead of making a store of its own. A remote that answers is reachable even where its
HEADnames a branch that does not exist, so a bare remote created while the project pushesmainno longer reads as unreachable. Where a project points its hooks at a folder inside the repository, connect refuses and prints the line to add to the project's own hook, instead of writing this machine's state path into a tracked folder; every command the mechanism runs runs without git's own hook environment (GIT_DIR,GIT_INDEX_FILE,GIT_WORK_TREEand the rest of it), so the record step a commit starts reads and writes the store and not the code checkout it came from; and a revision that is already recorded is success, said as such, where it used to be reported as a failure. The tracker's own settings travel with the items, so a setting such as exclusive claims survives the move and a second machine's connect instead of quietly becoming the tracker's default. A tracker folder that a checkout of a branch from before the move leaves where the pointer belongs is relinked — by connect, and by the step installed for a checkout — while a folder that really holds a tracker is refused and named. The installed layout files change, so a project that chose this layout reruns setup to refresh its copy and reports the version it carries; the setup version does not rise, because nothing a project must configure changed. -
0.107.1 refuses a registry's link field that carries the name of one of the generic fields every document carries —
id,kind,status,links, in any spelling — at the field's own line, as the published contract now refuses it. Setup names the line instead of reading the field as the kind's own, and no file setup installs changed. -
0.107.0 ships the off-branch tracker instead of only describing it. Setup already said what a tracker kept outside the code branches owes — one store per machine, published within seconds of a change, merged per item on a short timer, a claim that lands once, the state of each code revision recorded under its own name, and a supervisor that survives a reboot — and installed nothing, so a project choosing that layout was left to build it. It now installs the means: a tracker-neutral mechanism (one store per machine as a detached worktree of a ref that is not a branch and not a tag, a publish debounced by seconds, a sync on a short timer, a per-item merge that records the value it overwrote, a claim and a status change that count only once they are on the remote, a recording per revision, a lock so two of its own commands never race, and a systemd user unit that can be kept after a reboot), the recipe for the tracker this repository keeps (beads_rust,
br: where its store lives, how a checkout is pointed at it, how records keep one id on every machine, and how the merge records what it overwrote), and proofs that run the whole thing with two simulated machines. A project on another tracker is offered nothing of that tracker's: the mechanism is installed with the project's own declarations for its tracker, or setup says plainly that the project must supply them. Two machines claiming the same item inside the same seconds can both believe they hold it; after the next sync every machine shows one holder, so the second session learns at its next read that the item is not its. macOS supervision is described, not shipped. Two simulated machines prove it, in the set's own checks: one local remote, two clones, two stores, and every rule broken once on a copy to show a case catch it. The layout needs no setup rerun, and a project that chose it is told when its copy is behind: the mechanism reports the version it was installed from, and setup compares the copy with the shipped file on every run. The one thing it does not promise is a claim that waits for the other machine: two machines claiming one item inside the same seconds can both believe they hold it, and after the next sync every machine shows one holder, so the second session learns at its next read that the item is not its. A tracker kept on the branches is unaffected, and no file this setup already installs changed. -
0.106.0 gives a product's wiki its repositories' descriptions and puts the product's own kinds registry in the product. Two new skills,
describe-repositoryandwrite-intended-model, moved into the set: one describes a code repository the product spans — its intended model with evidence at a commit and a blob, the architecture page, the capabilities found in the code as requirements and use cases marked derived from code, and the decisions the code or its ADRs show — the other writes, reviews or updates a repository's intended model itself, with a worked example. Both name the engine they run the model check with the way the product's installation names it, and still write every file where no engine is installed. Setup in a product repository — and only there — now writes its kinds registry,docs/kinds.yamlunder the documents, carryingcontract: 1: every kind with the wiki's word for it, its id prefix (one to four capitals, unique among the kinds — every kind of the set carries one now), its folder, its stage, the hint a person mid-stage reads, the statuses its documents may carry, and its links — each link the field's name, the names of the kinds its targets may be, the backlink's word, whether it is required and how many it takes (one or many) — the registry the wiki reads alone for its groups, stages and links. Setup never resets one that stands. Templates are overridable per product: the product's own template at itstemplates/product/goes first, the copies installed at.shady2k/templates/come next, the set's shipped defaults last. The set's CI checks out and runs nothing but the set — the registry conformance reads the set's own pinned copies of the published schema and of the contract's registry cases with the set's own code, so no repository depends on another. A registry without itscontract: 1line is refused, as the wiki's own check refuses it. A project that is not a product repository needs nothing from this release, and no project is asked to rerun setup. -
0.105.0 takes the tracker out of your branches and keeps every machine in step. A product repository's tracker now lives in one place per machine, outside the code branches, so a branch or a merge never carries it and never lands another run's state on the main line. It publishes itself to the shared remote within seconds of a change and picks up the other machines' state on a short timer, so your agents everywhere see one picture, and a task claimed twice is won once: the second claim is refused, re-read and takes other work. Setup installs this layout and starts its background synchronization; a project that keeps the tracker on its branches still can, now told what that costs, and an existing project moves without losing a record. A run also stops hiding what it costs you: when bookkeeping, repeated review rounds or a stuck command take a noticeable share of a run, the agent says so unasked, with a counted figure and what would cut it. And a small change writes one acceptance record naming its checks and its review instead of one record per step, with the records riding with the work's own landing rather than arriving as commits of their own.
-
0.104.0 keeps a design on the right footing. A review now asks first whether the design serves the work's goal and the decisions you gave, and only then whether it holds together; a design that misses the goal, or whose goal you never confirmed, comes back to you instead of going through rounds of fixes.
to-designconfirms the goal and the chosen direction with you before it writes the long record. A number carried over from a replaced approach is worked out again or marked as inherited; a value put to you comes with what it controls, and a list of bare values you nodded through is kept as the agent's recommendation, not as your decision. Every constraint names where it comes from, and a limit of the machine the agent works on is told to you as a consequence, never quietly designed around. When an action is blocked, the agent says what it stops and asks you to allow it, never to run it yourself. -
0.103.0 makes the agent a sparring partner. In any conversation that weighs a choice it brings its own position and argues it, walks it and yours from several viewpoints, names each risk with how it would show, puts the alternative in its strongest form, and gives way only to an argument it can state. Before proposing anything it looks for the established standard, protocol or current practice of the field's leaders, checks the proposal against KISS, YAGNI, DRY and SOLID, and names what it found, since you may not know it exists. A design is traced to the work's goal.
-
0.102.0 starts work from its goal. Before work is specified or run, the agent establishes what it is for and for whom, what matters most when something must give, the main path and the sign it succeeded for its users, finding what is already written first and bringing the rest to you as one batch with recommendations.
-
0.101.0 looks back at the work instead of asking you about it.
close-outno longer puts its four questions to you after a feature: the engineer does not yet know how the work turned out, and they were never answered. It reads the run's own record instead, files the largest overruns against the forecast as findings, and asks you nothing. The retrospective over a series of features is now a skill of its own,refine-practices:to-milestoneoffers it first when a milestone ends,ask-shady2koffers it once about five features have closed in a project that plans no milestones, and it can be started any time on request. It gathers the signals without judging them — the forecast against what the work spent, the findings and their lanes, reopened items, review findings, your corrections and the loops repeated in the transcripts — judges the project's active practices, and turns a class of error, seen in two different features and never told as its cases, into the strongest fix that can hold it: the cause removed, a check that catches the class, or a written practice. A practice is a record of its own underdocs/practices/with the idPRA-…, its own template and its own place in the document check, plus one line in the agent doc; one over the soft budget is proposed together with a candidate to retire, and a retired one keeps its record and its reason. Everything is put to you as one batch, each item with a recommendation. This release raises the setup version: projects rerun setup once. An installed plugin updates by version. -
0.100.0 carries the work the rest of the set ends at — the merge — to the people who use the product. Release is a new
ship-releaseskill, started only when you ask: version by the project's scheme, release notes gathered from the accepted work instead of the diff, migrations that name their reverse before they run, rollout by environment, narrowest first, with a check after every step and the rollback decided before any of it goes out. What broke in running has a newhandle-incidentskill: restore first, then the cause throughdiagnose-bug, then a blameless review whose actions land as tracked work.check-upkeepis the recurring look after what your product runs on — outdated dependencies and their breaking changes, known vulnerabilities in what it ships, expiring certificates and keys, deprecated platform features, checks gone red or slow — filed where it belongs, and a project with nothing outdated hears that in one line. A release also marks which product hypotheses now wait on their measure, anddefine-productreads that measure when it comes due, records confirmed, refuted or inconclusive against the threshold the hypothesis wrote, and brings a refuted one to you as news; planning the next milestone withto-milestonestarts from the results. Observability is now part of the design: what is logged, measured and alerted on comes from the quality scenarios the feature is built from, each alert with its runbook, and where the product has users, an alert is held to a service level — an objective, its measure, and what is owed once the error budget is spent. -
0.99.0 decides how the system will meet a plan before building it. A new
to-designskill, between the spec and the stages: it gathers the scenarios the result is judged by, takes inventory of the building blocks and patterns that already exist, compares at least two options against them, records the choice with what was rejected and assumed, and has another model review the design before code. Every scenario a machine can judge becomes a check the stages carry. A new protocol reference holds the life cycle of a piece of work: what must hold before each next stage and which skill carries it — with release, operations and post-release validation named as stages the set has no skill for yet. Tailoring is the rule: the stages a piece of work passes are chosen by its scale, uncertainty, risk and project, so a trivial change is still just the change and its check, while the router now offers live work its next stage — design before building where the shape changes, none for a small bug with the reason said, release for merged work whose users have not received it yet. Work that follows a reference is accepted by comparison: reference and result side by side with every difference fixed or taken as a departure with its reason, evidence that could show the failure it rules out, and the yes asked after the owner's own look. -
0.98.1 counts the time spent shaping a product idea with
define-productas planning in the statistics; it was showing as time of no known phase. -
0.98.0 shows you your work in one picture.
ledger.mjs statslays a day out by the hour: twenty-four rows, each an hour as a stacked bar by kind of activity — developing, testing, reading, reviewing and delegating, git and CI, talking, you answering, waiting — with the hour's agent-hours and how many sessions were working at once; the day's totals follow, by phase and by kind, with sessions, cost, and hours and cost by agent and, where the records name them, by model. The week, the month and all time come as a heat map of agent-hours a day, with the busiest day and the longest single stretch of work among the headlines.ask-shady2kruns it and shows it as printed when you ask for statistics or for how your day went. Colour reads on dark and light terminals; plain text without one, and--jsonfor other tools. -
0.97.0 watches the run so you do not have to. Before you leave, setup asks how you want to be notified while away — nothing, the harness's own notification, or a command you already use — and proves that channel once with a real test message; the channel and its token stay on your machine, not in the project, whose config records only that pushes are on. While a run is in flight, progress is pushed to you at every point that changes the picture and as a digest on the cadence the preflight set, with percent done and how that stands against your target date; ask for it any time and
ask-shady2kreads the same figure: earned value, tasks and stages done, the recorded time and its shares, the stage in flight, what is ahead with forecast ends, and a burn-up; the sync report gains the delivery metrics the set's records can honestly carry, and says plainly that deployment frequency and time to restore are not in them. Long commands (tests, checks, builds) now run through the set's own runner, whose deadline comes from what the same command took here before, so a hung command stops itself at that bound instead of holding a run for a night. The claim of a run started in another session is written by the session that started it, and time recorded with no claim is named in the records rather than lost as "unattributed". Two pieces of independent work start together by default; serialising them is a reason said to you. A mutation receipt the gate did not get is reported as "not made", never counted as passed, and never blocks acceptance: survivors are filed tasks. This release raises the setup version: projects rerun setup once. An installed plugin updates by version. -
0.96.0 separates a run's forecast from the date the owner is waiting on, and stops a slow background check from holding up the work. When you plan a feature you are asked once, in the preflight, whether it serves a date you set from outside the project — a demo, a release, someone waiting. That date is recorded with who set it and why, and the agent's own forecast is checked against it before you leave and at every stage stop, so a forecast that will pass your date reaches you before the date arrives, with the two things you can still choose: move the date, or take named items out of scope; a lighter check is never a third option the run helps itself to. When a run misses its own forecast, you hear what took longer and a new, measured estimate. A run also stops spending its time in sequence: a step now holds up the work only when the next step needs its result, and everything else starts as soon as its input exists and runs in parallel. Mutation testing moved off that path: it runs once, when a stage's work is collected, beside the review, instead of by each worker and again after every fix — a surviving mutant is filed as a missing test (taken first in the feature when the risk is data, access or money), and the run never reports a mutation check that did not finish as passed. Milestone charters can carry a target date with who set it and why; a standup report answers the forecast against that date and says plainly when they disagree.
-
0.95.0 answers for a run started in another session. When your session hands a feature to a coordinator elsewhere and stays with you, supervising that run is its job, not a pause between jobs: before the run starts it records a deadline for it and tells you what is being waited for — by what it gives the product and why now — and when the result is due, said as a time you can hold it to. Anything that moves that time — a session that died and was replaced, a step that overran, work sent back for rework — reaches you with the new time and why. Past the deadline it finds out what went wrong instead of waiting longer. "Nothing to show yet" without a when is no longer a status, and a question like "where does it stand" gets a summary like any other: what is being done and why, the decisions taken, the risks and the cost in time, not a list of steps done.
-
0.94.0 stops three parts of the set from being wired to a fixed list of agent tools. A worker that runs inside its coordinator's session — an in-process subagent, which some agents give their parent's session id — no longer ends the coordinator's time record: its claim is refused with the reason, and its effort stays inside the coordinator's span. The reviewer is now what it is, a reviewer on a different model that can be reached from this agent, reached by a subagent with a model override, an external agent CLI or an API; setup proves the chosen way with one real call and records the way and the model, so a way that stops working is repaired with you told, not silently replaced by the same model. And the agent-specific reading of session transcripts now sits behind one adapter per agent inside the run script, so an agent this copy cannot read is told plainly ("unsupported here: what is missing") instead of being counted with the times no machine knows,
node ledger.mjs adapterssays what this copy reads and what each agent cannot do, the install and connect commands for every supported agent live in one list, and a worker in a session of its own records its own leaf while one in its coordinator's session records nothing. Projects rerun setup once, so the reviewer is proved and the install lines are written. -
0.93.0 A finished feature no longer leaves its working copies behind. Each task the run gave its own checkout and branch to is cleared away once its work is merged, what the worker wrote to the tracker there is carried over, and its time is recorded — in that order, because a claim is harder to recover once its working copy is gone. A checkout still holding unmerged work stays, and the run's report names it with why; what the run did not create it never removes, merged or not. Asking where the project stands now lists such leftovers as cleanup you can approve.
-
0.92.0 makes Jev work when its key is only in an environment variable. Jev read its key only through a file on your machine, and setup pointed at that file without saying where it is or what it holds. Now the file is read first, as before, and one that is there but broken still stops and names its own path; when there is no such file, the variable
JEV_API_KEYin the environment of the process that runs the Jev server is used. Where neither is there, the message gives the file's exact path with one example of its JSON, the variable to set instead, and says that the variable must reach the server's own process — not only your shell — and that the MCP connection is restarted after it changes (in Claude Code,/mcp). No key value appears in any error, status line or log,node jev.mjs statussays which source it used, and a project still cannot name where its key is. Setup and the installation docs now give the path, the three forms the file's JSON takes and the variable. -
0.91.0 teaches setup about a product's own repository and the code repositories it spans. Setup now asks the program what the folder it stands in is before it does anything, and answers for three cases. In a product repository it keeps the product's tracker, and the places its documents live come from that repository's layout instead of a question. In a code repository under the product's
repos/it installs no tracker of its own and cleans no queue: the product keeps the one tracker, this repository's commits name that product's tasks, the commit check resolves them there through the relative path../..and never an absolute one, and its agent doc points at the product's integration, while the backlog gate stays in the product repository; setup there needs the product repository set up first, and says so instead of guessing. The program also enters a code repository in the manifest (repo add, committed on its own, cloning nothing) and says what any folder is (where). Setup 0.41.0 is why every project reruns setup once; a folder that is neither a product repository nor one of its code repositories keeps the installation it had. -
0.90.0 A product's knowledge — its documents, its intended model, its team's own skills, its prototypes and the list of code repositories it spans — now lives in a git repository of its own, apart from the product's code, and the set owns that repository's whole lifecycle as a program that runs without an agent, so a person with no agent can start a product too. The program creates the draft from an idea: a folder under the products home the caller names, a manifest whose id never changes, the constitution, the empty folders, and a code-repository folder that its git ignores; it reads the repository back later and refuses one it cannot use, naming the file, the line and what is wrong. Naming the product later happens in place, keeping its id and its relative links; a remote is added only when the person decides to, and it never pushes; the code repositories the manifest declares are cloned, and an existing checkout is reported and left untouched, never replaced. The documents a product wiki serves stay in the forms the set already checks, and skills create and change a product repository only through this program, so the same rules hold whether a person or an agent starts the product.
-
0.89.0 adds
define-product, for a person who has an idea and no requirements. It talks the idea through in plain words, one question at a time with an example answer to react to, and turns doubts into beliefs to test rather than requirements. With the person's agreement it keeps their words as the record, and writes the product's documents behind the scenes, each quoting the lines it came from. It stops when an engineer could start the first feature, and says what is still missing instead of guessing it.to-specnow links a spec's requirement to the product requirement it serves, never restating it, and treats behaviour no product requirement holds as a gap for the owner. -
0.88.0 gives a product its own documents, written in fixed forms and checked on every commit: the records of conversations the quotes come from, hypotheses with their test and threshold, user stories, use cases, product requirements, open questions, and prototypes with their results. They are the level above the specs: a product requirement says what a user can observe and names no part of the system, and a spec's requirement names the product requirement it serves. A new check refuses a document out of form, a placeholder where an open question belongs, an id that does not exist, a requirement that names code and a quote that is not where it says it is, each with its file and line. A complete example product and one broken copy per rule ship with it, for tools that read these documents. Projects rerun setup once, to connect the new check; a project with no product documents is not affected by it.
-
0.87.0 counts the work of Prime Agent subagents. A Prime Agent coordinator runs its workers as subagents, and their transcripts sit among the parent session's files, where the run script never looked; so a worker's claim and receipt were refused as "not on this machine", the worker typed its record by hand, and the damaged record refused every commit until it was voided. Now subagent transcripts are found at any depth, their cost stays counted once, in the parent's record, and when the script cannot print a record the agent stops and says so instead of typing one (#25).
-
0.86.0 stops a damaged or wrong time record from blocking every commit. A tracker that can only add comments could not delete a record, and the gate's fix asked for exactly that, so a hand-typed record, or a correction to a receipt with a wrong value, refused every commit until you stepped in. Now such a record is voided: the run script writes a record that names it, and from then on nothing counts it. A correction is a void, then the right record, and the agent does both without stopping the run. Voiding a receipt opens its span again, so time cannot disappear quietly; a void that names nothing is only a warning. Projects rerun setup once, so that the tracker's proof includes voiding a record.
-
0.85.0 lets a feature run with several stages go on without forcing anything. An accepted stage now unblocks the next stage of the same feature as soon as its accepted work is in that stage's checkout, while the stage itself stays open until the pull request is merged and the work is closed out; before, the next stage could start only if the accepted one was closed early, before the merge. Between different features, work still waits for the other feature to close. Projects rerun setup once, so that the tracker's claim and ready operations follow the new rule.
-
0.84.0 adds working rules adopted from DietrichGebert/ponytail. Before writing code, an agent takes the first option that does the whole job: nothing where the task does not need it, what the project already has, the standard library or the platform, an installed dependency, and only then the least new code; no dependency is added for a few lines, and checks, data-loss handling, security and accessibility are never what is cut. A stage's review follows a changed function to every caller, including code the change does not touch, checks what breaks under the load the project expects, and reports a problem only with a concrete case that shows it. Findings that reach you are numbered and each says what the code does, what goes wrong, the fix and what happens if it is left.
-
0.83.0 counts the time of sessions run in Pi and Prime Agent, as it does for Claude Code, Codex and omp: the model, the tools, your answers and your absences, cost and tokens, by phase of the work. A question Pi puts to you is your time, not a tool's. Prime's Python cells are read by what they run, and its subagents' cost is counted in the session that started them. A claim made from Pi finds its own session; from Prime or omp, name it.
-
0.82.0 treats CI time as a budget a feature run shares. Before its first push a run learns what one CI run costs and what your account has left, and puts the number of runs it needs into its forecast; a run working in parallel counts every pull request and worker against that one budget, queues runs when they would not fit, and tells you about a shortfall before spending it. A CI run whose jobs were cancelled, skipped or never picked up is now reported as having no result, never as green; its cause is looked for in the run and your account's limits before anyone else is blamed, and it is not restarted until that cause is gone. Fixes for earlier failures on the main line that run the same suite share one pull request.
-
0.81.0 adds four working rules adopted from JetBrains/thinkrail's pull-request workflow. A reviewer's comment is judged before it is applied: the whole pull request is read again, each comment is applied, pushed back with its reason (shown to you first) or asked about, and every thread is answered after the fix is pushed, naming the commit. A passing check stays valid while what it covers is unchanged, so a rebase reruns only what it actually affected. A pull request's state that is not yet known is never reported as good: no checks yet is not "no CI", a draft is never "ready to merge". And what a milestone's charter puts out is an outcome that milestone does not deliver, not a ban on the code around it.
-
0.80.1 lets Prime Agent 0.9.8 start normally with the same package: on hosts without Pi's MCP registration API, the Jev extension does not abort the TUI. The sixteen skills install with one command; Jev remains an optional separate native MCP connection in Prime. Adds a real Prime TUI smoke test and direct Prime installation instructions.
-
0.80.0 adds Pi package discovery for all sixteen skills and session-scoped registration of the bundled Jev MCP server, preserving existing Claude Code, Codex and omp installs. Pi 1.0.0 is verified; Prime 0.9.8 loads the skills and needs separate native MCP setup. No credentials, project consent or periodic work are added.
-
0.79.0 promises a feature run's time from the work in it, not from how long past runs lasted on the clock. The measured pace printed the clock of past runs beside their working time as if the two were one range, and a run of a few hours' work was promised in a day and a half: the clock holds nights, waits for your merge and stretches nobody drove. The clock is now printed apart, marked as no forecast and with the share of it nobody worked; a promise adds your absence only where the work needs you meanwhile, and one far longer than its work says what fills the difference. The proposed forecast by phase no longer puts most of a run under "unattributed".
-
0.78.0 lets the agent ask Jev all it can answer, and lets you decide how sure it must be. Its tool took one question of the pick-one kind; Jev also answers yes or no and places things on a scale, several questions about one text at the price of one, so a failing log is now asked at once whether it failed, where, and how badly. How sure an answer must be to be used was fixed at 0.9, a number measured once on one version of Jev: it is now a project setting, beside the version it holds for, and a replay on your project's history shows what each threshold would take off the agent and how often it would be right. A new version of Jev is not taken up until you choose it. In Claude Code the tool is now allowed by the rule
mcp__plugin_shady2k-skills_jev. -
0.77.1 declares Jev's tool server in the plugin's manifest instead of a file at the repository's root, where Claude Code also took it for the repository's own server and reported it failing in every session there.
-
0.77.0 gives the agents Jev as a tool they see, where a project agreed to it. Over three days of feature runs no agent asked it anything: it reached them as a paragraph to recall and a command to assemble, and neither the coordinators nor the workers did. Now Claude Code, Codex and omp list it among their tools; the agent names the file a search or a run wrote and gets back what Jev was sure of and the few lines left for it to read, without reading the pile first. In Claude Code, allow the tool once in your own settings, or every call waits for your approval; setup offers it.
-
0.76.0 brings an open decision from a stopped run with its mechanism. A run's note used to reach you as options without the scenario behind them, and each question you asked was the first time the agent read the code. Now the code is read before the message, by a background reader where it is long; what the note claims is checked there or marked as unconfirmed; and when no role is recorded, the agent looks at how you have worked on the project before falling back to the default.
-
0.75.0 brings a decision waiting on you already worked out. An orientation used to hand you an acceptance as reading: a document section, a test file, review comments, costed as your reading time. Now the message itself says what you are approving: what it claims, where it stops, what stays open and what yes unblocks. Files are named only for someone who wants to check.
-
0.74.0 gets Jev used where it pays, where a project agreed to it. A feature run used to make no call to it at all: when to use it was written down only in a file the agents never opened, and no step of a run named it. Now the coordinating agent checks at the start whether Jev is available, and the steps where a run meets piles of material name it: many failures after a merge, surviving mutations, a review's findings, a long log. What Jev is best at is explained in terms of the work instead of only by examples: the same question asked of many items, with its answers known in advance, where each item has to be read for meaning; the agent reads only what Jev is unsure of. Jev's answer now counts as sure from 0.9 instead of 0.95, so the agent has less left to read itself.
-
0.73.0 writes for someone who was not there: a word counts as known to you only if you used it or were told what it means, so terms the agent picked up while investigating are explained or replaced, and a message you read after a break (a return, the plan before a run, a run's report) opens with what the matter is and why it is up now. The plan before a run opens with what the feature gives users.
-
0.72.0 supports omp as a third agent beside Claude Code and Codex: it installs the plugin as it is, and its updates now reach you too, because the catalog carries the plugin's version, which omp's upgrade of every plugin and its startup check go by. Setup recommends omp's
userscope, the one every worktree sees. -
0.71.0 tells the workers of a feature run about Jev, where the project agreed to it: each worker's instructions now carry how to call it and when to trust it, so a worker can hand it a batch (which search hits are real uses, which failing tests share a cause, a long test log) and read only what Jev is unsure of. Before, only the coordinating agent knew Jev was there, and that agent rarely has such batches.
-
0.70.0 lets Jev help the time records, where a project agreed to it: a session whose working copy is gone and whose conversation never names the task it was recorded on can now be placed on that task when Jev is sure it worked on it, and the receipt says so. A session Jev is unsure of, or would place on two tasks, is named for the agent to read instead. Without Jev everything works as before: only a conversation that names the task places it.
-
0.69.0 stops refusing a push that brings nothing new: a version tag, or a new branch, on a commit the remote already holds now passes with "nothing to check", instead of being refused as if the check could not read its input and leaving only a way around the hook. A push with new commits is checked as before. Projects rerun setup (0.37.0) so their hooks and CI count a push's new commits this way.
-
0.68.0 adds Jev, a fast decision model, as an option each project agrees to or not at setup: the agent may hand it batches of judgements over material it would otherwise read in full (long logs, transcripts, many issues), takes its answer only where it is sure and reads the rest itself. Everything sent is masked first: secrets removed, people, hosts and issue ids replaced. How accurate it is on your project is measured when you ask. Projects rerun setup (0.36.0) to answer the new question.
-
0.67.0 stops refusing a push that carries two finished pieces of work: each is judged where it was finished, not at the last commit, so work done in a row leaves the machine without anything being checked less strictly. Projects rerun setup (0.35.0) so their push check follows. Decisions about how the checks themselves judge work are no longer put to you; you hear what is held back and until when, and are asked only if something would be checked less strictly. A task whose title is in the set's own words is named by what it means for your work.
-
0.66.0 notices when the documents agents act on stop matching the code: a pull request that removes or moves a path the agent doc, glossary, architecture or current specs name, or breaks a link in them, is refused until the document is fixed in it, whoever opened it. Older drift is reported and filed as debt rather than fixed inside unrelated work, with the code no document mentions and the documents left behind while files came and went. Projects rerun setup once to name those documents.
-
0.65.1 asks your decisions in terms of the product: each option says what will be built or proven, what stays open and for how long, not which task or stage the work goes to. When a feature stays open after a close, the report starts with what you still cannot rely on.
-
0.65.0 stops the document check from re-running your tests over edits they never read: each check can say what it does not read (the docs, Markdown), and its result then stands until something it does read changes. A change that has landed and closed is no longer judged again because a later commit mentions its task. Projects rerun setup once.
-
0.64.1 keeps task numbers out of what you read: work is named by what it is, and a number appears only where you have to find, type or approve it yourself.
-
0.64.0 takes a run's time from its coordinator, which waits while its workers work: the coordinator's claim on the feature covers every task its workers hand in. A worker's own time is an optional detail of effort; a worker in another harness writes nothing and nothing is recovered for it, and a worker whose time is unknown no longer makes the run incomplete. This replaces 0.63.0's claim written for every worker at handover. Projects rerun setup once.
-
0.63.0 counts the time of workers running in omp, as it does for Claude Code and Codex. Where no machine has a session's record at all, the work is closed with its time unknown and the reason, instead of blocking the check or being filled in by hand, and reports say the figure is at least this. A coordinator writes a worker's claim at the moment it hands the task over, whatever the worker runs in. Projects rerun setup once.
-
0.62.0 recovers the time of work whose session ran in a working copy that was since removed: its transcript is found by the task it names. A problem found during setup is filed beside the setup task instead of under it, so the setup can still be accepted. And an earlier session that has stopped is no longer reported as one waiting for your answer: the agent takes its work over.
-
0.61.0 makes the time check bind only work begun after time records came into a project. Rerunning setup lists the work that was already in flight then, and where the transcript of the session that took an item is on the machine, it writes that session's claim at the start the transcript shows, marked recovered, and then its time. Work in flight is no longer an error that blocks the upgrade. Projects rerun setup once.
-
0.60.0 keeps everything about how the work went in the tracker, on the item it is about, and nothing on a machine: a session's claim carries the forecast by phase and the promised time, and when it stops working on the item a script writes what it spent, by phase and by who spent it, measured from its transcript. Stops, decisions, the feature's summary (forecast against work, time occupied), your verdict and handoff notes for work with no feature are records there too, so every machine and session reads the same history. The backlog check finds time that was never written, and reports say "at least" while any is open. Projects rerun setup once.
-
0.59.1 keeps a feature run from starting CI before its pull request is ready: a stage's full checks run on the agent's machine, the pull request stays in progress while review fixes are merged, and CI runs once when everything is in. A red CI job is reproduced locally before any fix is pushed.
-
0.59.0 keeps work that keeps the set itself working (its checks, hooks and the CI wiring that decides which checks a change owes) out of your milestone's finding budget: it belongs to the setup, as does a red check blocking the setup's own pull request, so you are no longer asked a budget question about it. The checks' messages also lose the counts left over from the cases that prompted them. Projects rerun setup once.
-
0.58.0 keeps each rule the skills follow as one general practice, named and written once, instead of a retelling of the case that prompted it: overlapping rules are merged, a skill points to the rule rather than repeating it, and nothing an agent did before is lost in the merge. It also stops a tracker kept inside the repository from carrying one branch's task states into another: setup now asks where the tracker lives when work runs on several branches at once, recommends keeping it outside the branches, and the checks read it from there. Projects rerun setup once.
-
0.57.3 puts one principle behind every conclusion that reaches you: it goes only as far as the evidence behind it, and one not yet checked comes to you as a guess with what would settle it, rather than as a fact.
-
0.57.2 stops a test the agent wrote from being reported as someone else's bug before it is checked against how your system really runs: until then it reaches you as a guess with the missing check named, nothing is proposed to file with another project on it, and a decision that rests on a single earlier measurement says so.
-
0.57.1 looks for your earlier answer before asking you anything: the whole feature's tasks, closed work, decision records and past sessions are searched first, a decision found is acted on and written down with where it came from, and a question that does reach you says where the search looked.
-
0.57.0 connects a fresh clone of your repository with one command instead of a list of manual steps, makes every local guard refuse a commit when it cannot find what it checks against, lets a task start as soon as the task it waits for is built within the same stage even where the tracker blocks it, and stops closing a task from invalidating check results that nothing in it touched. Projects rerun setup once.
-
0.56.0 gives every worker the bar the review will apply before it starts (no silent fallback on a missing input, stable output, tests that fail when the behaviour breaks, a mutation run on changed files), has workers commit only their own files, and keeps a charter from answering an open question of yours silently: each such answer is shown first and needs your yes.
-
0.55.0 stops the document check from demanding a signed record for merely filing a task: a commit owes a record for work it delivers, and an empty record written only to get past a check counts as going around it. Projects rerun setup once, so their check is proved on both sides.
-
0.54.0 gives, from
ask-shady2k, a report for the team's daily sync over the period you name: what was done, what got in the way, the questions for others and whether the work fits by a date such as the sprint's end. -
0.53.0 says how the product's code is shaped: one way in per capability, outside dependencies behind interfaces the logic owns, screens built from shared components and tokens, tests that survive a refactoring, and log records that name their module and trace.
-
0.52.1 brings each design decision with a worked example of what it decides, one per decision when several come together; a report about the skills keeps your product's design out of it.
-
0.52.0 makes a started agent session answer to the one that started it: its report lands whole in a known place, it counts as finished only once stopped, it can be resumed, and its starter ends it.
-
0.51.1 makes the time ledger report only measured facts: every session adds up to its clock, what a record lacks is unknown rather than zero, and one run's sessions cannot be counted by another.
-
0.51.0 keeps what describes the present true: a change that makes the agent doc, glossary, specs or architecture wrong fixes them in the same pull request; a question for you that blocks nothing is kept for you instead of stopping a run.
-
0.50.0 adds the path from an empty folder, with not even an idea, to the first feature (discovery, a pressure test, the vision with key journeys, the MVP, the architecture, a walking skeleton), and checks the document templates against established practice: arc42 and C4, MADR, EARS, Mermaid diagrams, and a ТЗ by ГОСТ drafted on request. Projects rerun setup once for the new templates.
-
0.49.0 splits the protocol into a core and topic references that skills cite instead of restating.
-
0.48.3 opens a design question with the parts it touches and their boundaries, and looks names up in the glossary before using them.
-
0.48.2 ends a worker's session once its result is merged instead of leaving it running.
-
0.48.1 puts time under the phase of the work actually done, not under whichever skill spoke first.
-
0.48.0 reads the project's hours from what the harness measured instead of guessing from gaps between messages, across all sessions, workers and subagents.
-
0.47.0 takes every approval a run will need in the preflight, before you leave, and names it in your words.
-
0.46.0 keeps a decision or condition you give on record, so no later session recommends what you already refused.
-
0.45.0 fixes a red check the merge waits on as part of the work, without charging it to the milestone's finding budget.
-
0.44.0 never recommends work just because it is ready: work whose ground is being replaced waits for it.
-
0.43.0 leaves a decision with whoever made it: an unanswered question is not your answer, and the agent's own recommendation is not your ban.
-
0.42.0 checks a reading's edges before calling it a fact: when it starts, when it stops and what else happened then.
-
0.41.0 puts the substance in every request for your approval, never a reference to a report you did not get.
-
0.40.0 does not reopen a decision you gave because a later analysis looks better.
-
0.39.0 reads the neighbouring work that would replace a piece's ground before building on it.
-
0.38.0 talks about your project with its own names for its parts instead of renaming them into everyday words.
-
0.37.0 reads and instruments a red check instead of rerunning it in the hope it turns green.
-
0.36.0 never asks for a separate merge just for tracker records or notes; they ride with the work.
-
0.35.0 opens a session with the state of the work in flight and asks how long you have, so you need not ask what is going on.
-
0.34.1 repairs the preflight's estimate item, which 0.34.0 had split in two.
-
0.34.0 keeps a branch waiting on its checks untouched, so other work does not restart them.
-
0.33.1 brings everything that reaches you already worked: options, costs, evidence, a recommendation and the case against it.
-
0.33.0 treats your time as the scarce one: runs parallelize, fill waits with useful work and do not stop for decisions you already left with them.
-
0.32.0 makes adopting the checks pay for itself at setup rather than at the first push, and has every refusal say what green looks like. Projects rerun setup once.
-
0.31.0 notices a run that stopped in silence: each run says when its result is due, and past that time the silence is reported.
-
0.30.1 bounds out-of-sight work by its estimate; overrunning it is a defect to find, not a reason to wait longer.
-
0.30.0 carries measured time on the work itself in the tracker, so any machine or session can estimate from it, and silence is no longer read as progress.
-
0.29.1 leaves nothing of value only in the session: edits, findings and decisions are committed, filed or noted before it ends.
-
0.29.0 hands a finding that does not fit the milestone's budget to you to decide, instead of parking it to make the checks pass.
-
0.28.0 has you see an outcome working before it is accepted; green tests alone do not prove a feature can be reached.
-
0.27.1 works out what a refusing check will demand at preflight, not at the push.
-
0.27.0 satisfies a refusing check instead of bypassing it.
-
0.26.1 has
handoffpropose lessons that outlive the session for the project's agent doc, only when there are some. -
0.26.0 measures runs instead of guessing:
take-taskkeeps a run journal outside the repository, estimates from the pace it measures, andclose-outasks the owner once how each run went (taken as is, questions it need not have asked, decisions it should have, corrections), with owner attention and cost counted from the session transcripts. Memory and code indexes are leads to confirm, and lessons that outlive a feature go to the project's agent doc. -
0.25.0 keeps a handoff out of the repository and out of temporary files: the work's state stays in the tracker, and what only the conversation knows goes on the feature, or to the user's state directory, where
ask-shady2kreads it. -
0.24.4 answers each question with the cheapest check that can: a local unit test before an end-to-end run, this machine before CI, one test before the suite.
-
0.24.3 reads what starts CI from the repository itself: unfinished work starts no expensive run, and ready work starts it once, by whatever means that repository offers (a draft pull request, holding the push, a label).
-
0.24.1 treats CI and end-to-end runs as expensive: tests run from the one failing test outward, a CI failure is reproduced and instrumented locally, and the branch is pushed once when everything local is green.
-
0.24.0 never pushes a guessed fix for CI to judge: a failure seen only in CI first gets what makes it explain itself. Waiting on CI is quiet until a result matters, and estimates are in agent time (the work plus the waits), said again once when the work outgrows them.
-
0.23.0 publishes everything described below from 0.21.0 on: those releases were pushed but their version number never rose, so no installed plugin updated. Bumps now go through a script that fails if the number does not rise.
-
0.22.0 treats every red check as the run's own to fix, never "someone else's", and asks that failures explain themselves: clear test output, CI causes on the first screen, log levels and trace ids by project conventions.
-
0.21.0 separates talking from building: the agent opens a working copy only when something is kept, lands plans with as few merges as possible, and starts each feature on its own branch without you.
-
0.20.0 starts a skill when you ask in words or agree, instead of asking you to type its command; runs are sized to how long your branches may live, and every option carries a rough duration.
-
0.19.0 runs a whole feature without you: plan it together, answer one batch of questions, leave, and come back to one pull request that says what was built, how to try it and what the agent decided alone.
-
0.18.0 asks whether the process is for you alone or the whole team, and tells contributors how to get the plugin.
-
0.17.0 keeps installation state out of the repository: setup lands with one merge, and each contributor's plugin and hooks stay their own.
-
0.16.0 stops asking for setup after every update: only a change that needs the installation redone does.
-
0.15.0 never asks you to read documents: the agent tells you the substance, its decisions and assumptions, risks, other views and what review found, in plain words, and your approval covers what you were shown.
-
0.14.0 assigns tasks to the agent doing them, not to you, and every step ends with the next action, recommending a handoff or compaction in time.
-
0.13.0 adds a light "records" level for the document gate, recommended without protected CI, scopes required checks by what a change touches, and stops setup from rerunning full suites that were already proved.
-
0.12.0 separates languages: the agent talks in yours, and files are written in the project's artifact language, asked at setup (English by default).
-
0.11.0 adds
report-to-shady2kfor anonymized reports and ideas. -
0.10.0 no longer holds setup and work until the document gate is wired: it becomes its own stage, and documents are checked by reading meanwhile.
-
0.9.0 turns
ask-shady2kinto a read-only orientation: the project's picture, progress and ways forward with consequences, also before setup. -
0.8.0 adds open-ended dialogue, living-document templates and a portable document gate. Its fixture and CLI tests do not replace project adapter/CI proof or demonstrate conversational quality; live rollout remains a separate validation.
-
0.7.2 replaces per-setting interviews with role-aware recommendations across the set; consequential decisions and explicit authorization remain required.
-
0.7.0 revises execution and setup. Fixtures and package checks run locally; the new complete workflow still needs validation in real projects. Earlier installation runs informed the protections around proof, isolated staging and landing. Harness-specific automatic update/session hooks are not shipped.
The original shape and work-skill ideas come from mattpocock/skills, MIT: license. They are rewritten here around this set's tracker protocol.
The 0.8 document lifecycle draws on OpenSpec (current specs versus deltas), Spec Kit (scenarios and traceability), and Superpowers (proportional design and evidence before completion). Templates and checks here are original implementations, not bundled copies of those tools.
npm test # backlog/commit/document fixtures, CLI and package invariants
npm run test:mutation # deliberately break checks and observe failures
npm run protocol # synchronize folder-local protocol copies
scripts/link-skills.sh # link into local skill directoriesAGENTS.md defines layout, invocation, portability and versioning. Role-aware dialogue evaluation cases are in test/dialogue-scenarios.md; automated package checks do not establish conversational quality.
Authoring templates and the development build: guide.