Yarstack

Yarstack pirate coins

Yarstack is a plugin for Codex and Claude Code. It adds skills for investigating bugs, designing features, writing and testing code, reviewing changes, and delivering pull requests.

Each skill is a Markdown file that tells the agent what to inspect, what it may change, how to check the result, and when to stop. Name a skill in your prompt to use its instructions with your repository and available tools.

Get started · Examples · Skill catalog

Why use it?

• system-investigate traces the relevant code, tests, and available runtime

evidence before recommending a fix. It reports when the evidence does not support a conclusion.

• system-design starts with your requirements and current system. It adds a

component only when it can name the requirement that needs it.

• behavior-implement looks for existing code, standard-library solutions, and

native platform features before writing new code. It starts product changes with a failing test.

• phase-validate checks each acceptance criterion against the implementation

and test results. It identifies criteria that remain unverified.

• code-review checks suspected defects against the source before reporting

them as findings. Each finding must describe a concrete failure scenario.

You can read every skill's instructions before using it.

Get started

You need Codex or Claude Code with plugin support. Run the commands for the one you use in your terminal.

Codex

codex plugin marketplace add yarlson/yarstack
codex plugin add yarstack@yarstack

Start a new Codex thread after installation. See the Codex plugin command reference for host setup and command details.

Claude Code

claude plugin marketplace add yarlson/yarstack
claude plugin install yarstack@yarstack

Run /reload-plugins in Claude Code or start a new session. See Claude Code's plugin guide for installation options.

Try your first skill

Open a repository with local changes and ask your agent:

Use Yarstack's code-review skill to review my uncommitted changes.

The agent reads the changed code and its callers, then checks suspected bugs against the source. The report lists verified defects with file locations, failure scenarios, and suggested corrections. It separates those findings from concerns it could not verify and notes missing evidence. Reviews are read-only unless you authorize edits.

To use another skill, replace code-review with its name and describe the task. Include constraints such as the deadline or behavior that must stay unchanged.

Examples

Find out why a bug happens

Use Yarstack's system-investigate skill to find out why retried webhook
deliveries create duplicate invoices.

The agent checks whether retries cause duplicate invoices and recommends a fix if the evidence supports one. This skill does not edit code. Once you agree on the cause and fix, ask:

Use Yarstack's behavior-implement skill to fix the duplicate-invoice bug.
Add a regression test showing that retrying the same event creates one invoice.

For product behavior, behavior-implement starts with a failing test, implements the fix, and reruns the relevant checks. For tooling and infrastructure, use the existing validation commands first. Add dedicated tests when the remaining risk warrants them.

Design and implement a feature

Use Yarstack's system-design skill to design per-workspace usage limits for
our billing service. We have ten workspaces. One engineer will implement
this in two weeks.

The agent proposes a design within the current system. It explains which requirement each component satisfies and what would require a larger design. It describes how data moves through the system and records tradeoffs and work left out of scope.

When you accept the design, ask the agent to write a plan:

Use Yarstack's plan-create skill to turn the agreed design into a plan at
docs/usage-limits-plan.md, with ordered phases and acceptance checks.

Then work through one phase at a time:

Use Yarstack's phase-implement skill to implement phase 1 of docs/usage-limits-plan.md.
Use Yarstack's phase-validate skill to check phase 1 against the plan.
Use Yarstack's phase-review skill to review phase 1 for structural regressions.

Send one request at a time. After each step finishes, send the next one. Use architecture-refine if you still need to settle a design decision.

Use a phased plan when the work needs separate implementation steps. For a focused bug fix, start with behavior-implement.

Check a specific risk

For example, ask:

Use Yarstack's security-review skill to check tenant isolation in this branch.

Deliver a Jira issue

jira-issue-refine helps the agent define an issue's scope and acceptance criteria. When you authorize delivery, jira-issue-deliver implements the issue, validates the change, commits it, and pushes it to GitHub. It opens a pull request and fixes CI failures.

It finishes when the pull request is ready for review, its required checks pass, and requested automated review feedback is resolved. It does not merge, deploy, release, or change the Jira issue.

Without a Jira issue, plan-deliver does the same work from an approved plan in the conversation or a file. It re-reads the agent instruction files before the first edit.

For completed local changes, pr-draft publishes a draft pull request and monitors its CI checks. These workflows require authenticated access to the relevant services. You must authorize commits, pushes, and other external writes.

Optional engineering standards

Skills apply to individual tasks. You can also install the bundled engineering standards as global guidance. They tell the agent to stay within its authority, read the code before changing it, add as little as possible, preserve contracts, handle failure paths, and prove behavior with checks that can fail. They also cover safe state changes, trust boundaries, naming, comments, and technical writing. The directory's README links each rule to its sources and says which rules rest on measured evidence and which on judgment.

The plugin does not install these global instructions. To preview the exact text, clone this repository and run:

git clone https://github.com/yarlson/yarstack.git
cd yarstack
plugins/yarstack/scripts/install-engineering-standards.sh --print

If you want to use that text as your global agent guidance, run from the clone:

make install-system-prompt

The installer replaces the contents of ~/.codex/AGENTS.md, ~/.agents/AGENTS.md, and ~/.claude/CLAUDE.md. It first backs up files whose contents differ. It preserves symlinks and refuses to write through dangling ones. If a file already matches, it leaves it alone.

Repository instructions still take precedence. Your host's permissions control the agent's access. Asking for a review does not authorize edits or external writes.

Optional session memory with Yarbrain

Yarbrain is a separate plugin in the same marketplace. It stores session evidence and notes in a Markdown vault at a path you choose. You can recall those notes during later sessions.

Episode notes preserve what happened in a session. Other notes record the current understanding. You review proposed knowledge before adding it to those notes and approve proposed skills before activating them.

After adding the marketplace, install Yarbrain for your host:

codex plugin add yarbrain@yarstack

Or, for Claude Code:

claude plugin install yarbrain@yarstack

Start a new Codex thread or reload Claude Code's plugins, then ask:

Use Yarbrain's wiki-initialize skill to create my vault at <path>.

Initialization requires Python 3 and a vault path you choose. It preserves existing vault files. Use wiki-capture after a session to save evidence and propose notes or procedures. Use wiki-reconcile to compare those proposals with existing knowledge. Use wiki-recall to find relevant notes for your next task.

After you configure a vault, hooks load up to 12,000 characters from its index at session start. Other hooks queue session IDs and transcript paths for later capture. Hooks do not copy transcript bodies, call models or network services, or edit current notes. Capture and reconciliation happen when you invoke those skills. You can use Yarstack without installing Yarbrain.

Skill catalog

Each link opens the skill's instructions. They define what the agent may change, which checks it must run, and when it should stop.

In Claude Code, skills that delegate review or research work run it in the bundled yarstack:reviewer agent. It has no file-editing tools and cannot start other agents. Codex does not load agents from plugins, so in Codex these skills use Codex's own subagents.

<details> <summary><strong>Browse all Yarstack skills</strong></summary>

Investigate, design, and plan

Implement and verify

Review a change or a specific risk

Explain and document

Refine issues and deliver work

</details>

<details> <summary><strong>Browse Yarbrain skills</strong></summary>

</details>

Update

Refresh the marketplace and update the plugins you have installed.

Codex

codex plugin marketplace upgrade yarstack
codex plugin add yarstack@yarstack

If you also use Yarbrain, run codex plugin add yarbrain@yarstack. Start a new Codex thread to load the updated plugins.

Claude Code

claude plugin marketplace update yarstack
claude plugin update yarstack@yarstack

If you also use Yarbrain, run claude plugin update yarbrain@yarstack. Run /reload-plugins or restart Claude Code.

Work on Yarstack

Each plugin is self-contained under plugins/yarstack/ or plugins/yarbrain/. Codex and Claude Code use separate manifests and marketplace catalogs. See AGENTS.md for repository rules and SKILL_FORMAT.md for skill conventions.

Run the repository checks before submitting changes:

make validate

This runs the Yarbrain Python tests, plugin-scanner lint and plugin-scanner verify for both Codex packages, and claude plugin validate --strict for both Claude Code plugins and the marketplace. The command requires Python 3, pipx, and the Claude Code CLI; the Makefile pins the scanner version.

Report vulnerabilities privately as described in SECURITY.md.

MIT © 2026 Yar Kravtsov.