roost

Spec-driven development that doesn't stop at the code.

roost takes a product idea all the way to production. It shapes the epic, builds it slice by slice with one coding-agent session per repo, reviews the whole epic, QAs it in a real browser, and walks you through the rollout one command at a time.

• The whole cycle, not just the build. Most spec-driven kits hand off once the code is written. roost carries on through review, close-out, release QA and the rollout.
• You make the calls. Agents do the work and stop at named checkpoints: the plan, each slice's findings, what's deferred, and each rollout gate. You run every rollout command yourself.
• Nothing lives only in a chat. Plans, kickoffs, carry-over and test results go in your tracker, so any run can be picked up where it left off.
• One agent per repo. An orchestrator session drives a worker session in each repo, in order, against your real local stack.
• Its behavior is tested. Eval cases check what the skills do, run with and without roost.

roost is a set of skills, not an agent: it hosts nothing and runs inside your coding agent. It's opinionated about how the work goes: test-first, small PRs on a stack, your decisions at named checkpoints, nothing left only in a chat, and a rollout runbook you run yourself. It's open about which tools you use: your tracker, test tool, repos, local stack, branching and deploy rules come from one team config file, and each tool plugs in through an adapter. Today roost runs fully in Claude Code with Jira, Xray and gh stack on GitHub. Other trackers, test tools, git hosts and coding agents are on the roadmap.

Brought to you by Beakpoint. Beakpoint built roost and uses it every day to build its own product. Winston, the bird at the top of this page, is Beakpoint's mascot.

A made-up session, sped up. Re-record it with VHS and gifsicle: vhs demo/roost.tape && gifsicle -b -O3 --colors 64 --lossy=30 demo/roost.gif.

What you need

roost runs fully today with:

• Claude Code, with a session open for each repo. Most skills also work in Cursor.
• A tracker: Jira, through the Atlassian MCP, or GitHub Issues, through the gh CLI.
• Tests: Xray test cases (Cucumber scenarios), or eval cases in the repo for a Claude Code plugin.
• GitHub, with the gh CLI, and its gh stack extension if you stack PRs.
• For an app: Playwright MCP, for checking prototypes and testing in a real browser, and a local stack you can start with a command (Aspire, Docker Compose or your own scripts). A plugin or a library needs neither.

Each skill needs only part of this; What each skill needs has the details. Not on Jira or GitHub? The roadmap shows what's coming.

Install

/plugin marketplace add Beakpoint-Insights/roost
/plugin install roost@roost

Skills are then available as roost:<skill>, for example roost:shape-epic.

Configure it for your team

Every skill reads one team config before it does anything. Run:

/roost:setup

It links your team's shared config if you have one, or asks about your tracker, repos, local stack, branching and deploy rules and writes one. examples/config.example.yml is a complete example, and skills/roost-config/references/config-schema.md says what every key means.

roost looks for the config in this order: a path you name, $ROOST_CONFIG, .roost/config.yml in the current repo, then ~/.claude/roost/config.yml. To work for more than one team on one machine, start each session with ROOST_CONFIG=<that team's config> claude: orchestrators run outside the repos, so they never see a repo's .roost/config.yml. They record the config they started with and stop if a resumed run loads a different one. Most teams keep one config in a private repo, next to any skills of their own, and link it into ~/.claude/roost/config.yml on each machine so git pull keeps everyone in step.

A machine that differs from the rest (its own database, other ports) keeps just those values in ~/.claude/roost/local/<team.name>.yml, which overrides that team's shared config on that machine only.

The config never holds secrets: it names where a secret comes from, never its value.

What's supported

Each supported tool has an adapter: notes in skills/roost-config/references/ that say how to do each operation in that tool. Adding a tracker or test tool means adding an adapter file and a row here. The work to support more tools is grouped in three milestones: Works without Jira, Works without gh stack and Works outside Claude Code.

From idea to release: the happy path

This is how one epic usually goes through roost. The example team has two repos in its config, a backend and a frontend, so it runs three Claude Code sessions on one machine, each with roost installed:

• the API session, opened in the backend repo;
• the UI session, opened in the frontend repo;
• the orchestrator, a third session opened anywhere. It never edits a repo; it sends the work to the other two and brings their results back to you.

A team with one repo has one worker session; a team with three has three. The made-up epic is PROJ-1234, "New customers can send data minutes after signing up".

1. Shape the epic

In any session:

/roost:shape-epic New customers should be able to send data within minutes of signing up.

shape-epic works through seven phases: problem, epic, design, slices, tests, build guide and handoff. It asks you about the problem first, and checks with you as each phase finishes. If your config has a roadmap, it asks whether the epic goes on it. At the end, PROJ-1234 has:

• a description with the problem, goals and scope;
• a prototype built from your design system;
• ordered stories, one per slice, each small enough to ship on its own;
• the tests for each story, in your test tool;
• a build guide and a tech lead prompt, attached to the epic.

2. Plan the build

In the orchestrator:

Build PROJ-1234.

build-epic starts without asking. The stories have no kickoff comments yet, so it plans first:

1. It sends the epic's tech lead prompt to the lead repo's session, which writes the implementation plan on a new gh stack.
2. You approve the plan, or ask for changes. The plan ends with Rollout needed: yes or no: yes when merging and deploying isn't enough on its own (a migration, a backfill, a feature flag, setup in an outside service).
3. The lead session posts a kickoff comment for each repo on each story, which the build runs from, and a Release order comment on the epic. If a rollout is needed, it also creates the epic's deploy ticket and runs write-runbook, so each stage of the runbook becomes a sub-task of that ticket, with the same number and name.

3. Build the slices

build-epic then builds each story in order with run-slice:

1. Each repo's session builds its part from its kickoff comment, in the config's order. The stack's owner starts the local stack between them, so a later repo builds against the earlier one's real work.
2. The session with the e2e suite checks the story's tests with verify-slice-tests, and every session runs /code-review on its stack.
3. Checkpoint: you get one list of test results and review findings, each with a recommendation (fix now, ticket for later, or skip), and you decide.
4. The sessions fix the "fix now" items test-first, and the e2e session tests the slice by hand in a real browser. Any bugs it finds come back to you the same way.
5. slice-handoff sorts what's left over into the next slice, before release, or later (you confirm the sorting), runs every test in the epic so far, and rewrites the next story's kickoff comments to match what was actually built.

Then the next story starts, with no need to ask. Each repo's part of each slice, and each bug fix, is its own PR on the epic's stack, and the Release order comment lists every PR in the order to merge. A migration added along the way goes on the deploy ticket too.

4. Get it ready to release

After the last slice, build-epic carries on:

1. The "before release" items are fixed (bugs through run-bug and bug-bash), and every test in the epic runs once more.
2. review-epic has every session review the whole epic against main, plus a security review of the server code, looking hardest at code no slice review saw. You decide each finding.
3. close-out-epic gives every open ticket a place: fixed before release, moved to a follow-up epic, or standalone. You confirm the places. Once the release ships, it checks production runs the epic and offers to draft its release note.
4. The e2e session runs release-qa: the full e2e run, exploratory testing, and a release call.

5. Ship

roost doesn't merge or deploy for you, but it runs the rollout with you. Ask "let's run the PROJ-1234 runbook together" and pair-runbook takes you through the deploy ticket's runbook one step at a time: it gives you the command and what to expect, you run it and paste the output, and it checks the result, fills in the run's record and closes the step's sub-task. It stops at each stage's gate for your go-ahead. Merging the stacks is one of the runbook's steps (stacked-prs helps with conflicts).

Where you come in

The skills start work without asking and stop only for your decisions:

• answering shape-epic's questions and approving the tech lead's plan;
• each slice's checkpoint, and each handoff's sorting;
• the review-epic findings and the close-out-epic places;
• each command of the rollout, which you run yourself, and each stage's gate;
• anything only you can do, such as unlocking commit signing or answering a permission prompt in one of the sessions. Those are listed first, under 🙋 Your turn.

At any point, ask the orchestrator "where are we on PROJ-1234?" for a status table. A bug found later, in this epic or anywhere else, goes to "fix PROJ-5678", which runs run-bug.

Skills

The skills are grouped by where they fit in the development cycle, in order.

0. Setup

1. Requirements and design

2. Test design

3. Engineering

4. Test automation and verification

5. Release and operations

What each skill needs

Every skill needs the team config. Install fails quietly if a skill's tools aren't there, so check this first. Two terms in the table:

• Tracker access: for Jira, the Atlassian MCP and a Jira API token (JIRA_EMAIL, JIRA_API_TOKEN), or else Playwright MCP with a signed-in Jira session; for GitHub Issues, the gh CLI, signed in.
• Test access: for Xray, XRAY_CLIENT_ID and XRAY_CLIENT_SECRET, or else Playwright MCP with a signed-in Jira session; for eval cases, claude plugin eval.

Your own skills

Skills that only make sense for your team (a roadmap in your company's format, a report for your board) belong in a private plugin of your own, next to your config. roost's skills can call them: for example, shape-epic asks the skill in roadmap.skill to put an epic on the roadmap.

Using roost in Cursor

Cursor reads skills in the same SKILL.md format from ~/.cursor/skills/. Clone this repo and link the skills there:

git clone https://github.com/Beakpoint-Insights/roost.git ~/src/roost
~/src/roost/scripts/link-skills.sh

The links point at your clone, so git pull in it updates the skills. To use another tool's folder, pass it: scripts/link-skills.sh ~/.agents/skills. To undo, run scripts/link-skills.sh --remove. Put your config at ~/.claude/roost/config.yml or set ROOST_CONFIG.

The skills were written for Claude Code. In Cursor, set up the same MCP servers (Atlassian for Jira, and Playwright) so their tool names match, then expect this:

Contributing

Contributions are welcome. CONTRIBUTING.md explains how to add a skill, open a PR, run the evals and write commit messages. Please follow the code of conduct, and report security issues privately, as SECURITY.md describes. Questions and ideas go in Discussions.

License

MIT