Yet another agentic workflow, nice!

A standardized, comprehensive workflow from idea to shipped software

One workflow carries every change from idea to shipped software: prepare the work, plan it, save it, execute it overnight, and verify it. Every issue follows the same steps, no matter who picks it up.

The workflow

The highly opinionated workflow.

  1. Refinement Scrum Team
  2. Sprint Planning Part 3 Scrum Team
  3. Sprint Developer
    Scrum events — when each step is used
    • Turn a rough idea or new issue into agreed work — a story, bug report, refactor, spike, or prototype.
    • Assess every story for a split.
    • What you get: an approved issue on GitHub, nothing left unstated.
    • Grill the design and agree on the approach before anyone writes code.
    • Choose how the change reaches users.
    • What you get: a reviewed plan, with every design decision and its reason recorded.
    • Write the plan, its decisions, and a concise plain-language summary with fitting diagrams into the GitHub issue.
    • Give open questions owners before implementation starts.
    • What you get: an issue marked ready for implementation.
    • Have the code written while you are away.
    • Run several ready issues one after another, each built separately.
    • Review the code and fix every finding — blocking and non-blocking alike.
    • Run your team's checks and fix what fails — up to 3 fix sessions.
    • What you get: working code on its own branch, all review feedback worked through, summarized in the morning.
    • Prove the change works: run your team's checks — skipped when the overnight pass still matches the code — then walk through the checks only a human can do.
    • What you get: a verified change, and a pull request when your project enabled it, ready for review.

Installation

  1. Install the package

  2. Run the install command

Skills & instructions

The pieces that make it work.

Skill tree Plan skills

/yaawn-prepare-plan

Get a new idea or an existing issue ready for planning. Asks which work item you have — story, refactor, spike, bug report, prototype, or other change — or infers it from the issue's labels, routes it to the matching writer, grills it with the type's dedicated grill, and saves it to GitHub after your approval. Every story gets a split assessment.

Refinement

/yaawn-create-plan

Turn a GitHub issue into a grilled implementation plan: discuss the design first, explore the codebase when needed, choose the rollout strategy — branch by abstraction with a feature flag, a feature flag only, or shipping directly — and record every decision.

Planning

/yaawn-save-plan

Write the plan into the issue: implementation steps, design decisions, open questions with owners, and a concise plain-language summary with a high-level diagram per visible structure. Offers to answer the open questions with you first. Marks the issue ready for implementation.

Planning

/yaawn-implement-plan

Execute the plan unattended, overnight — one issue or several in parallel, each in its own git worktree inside the project folder (yaawn-<issue>-<slug>, next to main/). Runs on the coding agent picked for the sessions during setup. Never commits or pushes.

Overnight

/yaawn-verify-executed-plan

The final gate: check every Definition of Done step from your project's shared checklist, run your verification commands, walk the manual checks with you, then open the pull request — when setup enabled it.

Verification
Other skills

/yaawn-write-user-story

Write and refine user stories: persona, Given/When/Then acceptance criteria, INVEST validation, and a value type. Produces words only — never code — and saves to GitHub after your approval.

Backlog

/yaawn-write-refactor

Write a refactor issue — goal, why now, what done means, and a value type — for a change users do not see. No persona, no Given/When/Then, and never code.

Backlog

/yaawn-write-spike

Write a spike — one sharp question, why it blocks, a timebox, and exit criteria. After the save, a human answers it; the overnight run never picks it up.

Backlog

/yaawn-write-bug-report

Write a bug report — summary, steps to reproduce in words, current and expected behavior, and environment. Describes the problem, never the solution.

Backlog

/yaawn-write-prototype

Write a prototype — a throwaway build of a feature idea to test with customers: goal, success criteria, and what will be built. It runs on a prototype/ branch that is never merged.

Backlog

/yaawn-write-other

Write an other change — work that matches none of the other types — with goal, why now, and what done means. Never code.

Backlog

/yaawn-grill-story

Stress-test a story — persona, acceptance criteria, INVEST, and value — in rounds of questions and push-back that come mainly from the persona's point of view, until you and the agent share an understanding and no assumption stays unstated.

Refinement

/yaawn-grill-refactor

Stress-test a refactor — goal, why now, what done means, and value — in rounds of questions, until you and the agent share an understanding of what improves and why now.

Refinement

/yaawn-grill-spike

Stress-test a spike — the question, why it blocks, the timebox, and exit criteria — until it is clear what must be found out and when the spike is done. Never answers the question itself.

Refinement

/yaawn-grill-bug-report

Stress-test a bug report — summary, steps to reproduce, current and expected behavior, and environment — until it is clear what goes wrong and how to reproduce it.

Refinement

/yaawn-grill-prototype

Stress-test a prototype — goal, success criteria, and what will be built — until it is clear what the experiment should teach and how its result is judged.

Refinement

/yaawn-grill-other

Stress-test an other change — goal, why now, and what done means — in rounds of questions, until no assumption stays unstated.

Refinement

/yaawn-grill-design

Stress-test the implementation design — architecture, data flow, interfaces, edge cases, security, and testing — logging every decision and adding settled terms to the project glossary. Proposes an ADR for each decision that is hard to reverse and writes it only after you confirm.

Planning

/yaawn-split-story

Split oversized stories into vertical, independently deployable slices with the SPIDER technique — created as standalone issues once you approve, linked with **Depends on:** where one slice needs another.

Refinement

/yaawn-extract-learnings

The prototype's last step, instead of verification: read the never-merged prototype/ branch, collect how customers reacted, summarize what was learned, and turn the learnings into a story after your approval — or close the issue when the prototype is rejected. Never opens a pull request.

Learning

/yaawn-owasp-security

A background security lens based on the OWASP Top 10:2025 — read silently when proposing designs, plans, or code, baking mitigations in autonomously and escalating only the risks it cannot resolve on its own.

Security

/yaawn-clean-code

Deep Clean Code rules from Robert C. Martin — naming, functions, classes, tests, SOLID — complementing the always-on instructions.

Code review
Agent personas

yaawn-developer.md

The default: delivers working, tested code in small, surgical changes, with security baked in and the definition of done in mind.

Everything else

yaawn-reviewer.md

Reviews like a staff engineer: flags only what matters, names file and line, proposes a concrete fix, and ranks findings by severity.

Reviews & audits

yaawn-product-owner.md

Starts from user value: prepares stories, bugs, refactors, spikes, and prototypes for your product's user roles, holds them to INVEST, and keeps code out of them.

Story work
Instructions & output styles

yaawn-clean-code.typescript.instructions.md

Clean Code principles for the codebase, applied to every TypeScript file — the lightweight summary the /yaawn-clean-code skill expands into its full reference.

Always-on instruction

yaawn-function-coupling.typescript.instructions.md

Keep methods independent: orchestrate every step of a flow from one method, so each step can change without touching the others. Call the steps in parallel, and reduce repeated arguments by passing shared data through the constructor or class members.

Always-on instruction

yaawn-declarative.instructions.md

Write code that states the desired outcome — the what — instead of narrating every step — the how: array methods over loops, SQL, JSX. Keeps step-by-step logic where it is clearer, and code review checks for it too.

Always-on instruction

yaawn-semantic-html.html.instructions.md

Always use semantic HTML elements — header, nav, main, section, button, label — instead of meaningless div and span wrappers. Accessibility, SEO, and resilience by default.

Always-on instruction

yaawn-html-css-js.html.instructions.md

Build new UI features in priority order: native HTML first, then HTML + CSS, and only then JavaScript/TypeScript. The simplest technology that solves the problem wins.

Always-on instruction

yaawn-vanilla-css.css.instructions.md

Hand-written vanilla CSS only — no preprocessors, no utility frameworks, no CSS-in-JS — with class names following the OOCSS or BEM pattern. Predictable, reusable, collision-free styles.

Always-on instruction

yaawn-accessibility.html.instructions.md

Accessible markup, area by area along the A11Y Project checklist — alternative text, one top-level heading, table header cells, labelled form inputs, captions, and a page language.

Always-on instruction

yaawn-accessibility.css.instructions.md

Accessible presentation along the A11Y Project checklist — sufficient color contrast, visible focus styles, reduced-motion support, reflow and zoom, and touch targets large enough to hit.

Always-on instruction

yaawn-accessibility.javascript.instructions.md

Accessible behavior along the A11Y Project checklist — keyboard-operable custom controls, focus management, accessible media controls, reduced motion, and safely rendered content. TypeScript projects get it too.

Always-on instruction

yaawn-open-source-first.instructions.md

Research whether a well-maintained open-source package already provides the feature before writing it from scratch. Reuse first, write second.

Always-on instruction

yaawn-personas.instructions.md

Picks the agent persona for every task under the hood — Reviewer for reviews, Product Owner for story work, Developer for everything else. You never have to choose.

Always-on instruction

yaawn-instructions

The Vibe bridge skill: Vibe never reads instruction files, so this skill makes it read yaawn's and the project's instructions and follow each one whose applyTo matches. Every other agent ignores it.

Vibe only

yaawn-eli5.instructions.md

The plain-language output style: short sentences, everyday words, no jargon. Plans and overnight summaries are written in it so anyone on the team can understand them.

Output style
Shared docs

yaawn-grilling.md

How every grill skill runs a session: an open grill that questions everything first, then a focused grill over the skill's checklist. Asks in rounds over the open frontier, looks up facts itself, leaves decisions to you, and ends only when no assumption stays unstated. Shared by all seven grill skills so they behave the same way. Reads the domain's ADRs before round one, and concept grills mark ADR-worthy decisions with [ADR].

Grilling

yaawn-adr.md

How grill sessions use Architecture Decision Records in .yaawn/adr/<domain>/: cite a settled decision instead of asking again, and ask whether to reverse it when an answer contradicts it — the record is updated in place, and its earlier wording stays in git history. Only /yaawn-grill-design writes ADRs, after you confirm. Without ADRs, grills run as before.

Grilling

yaawn-issue-writing.md

How every writer skill refines an existing issue and saves it: your approval first, the grill's decisions and open questions in the same save, the template's labels, and the body passed as a file. Shared by all six writer skills, so each keeps only its own fields.

Refinement

yaawn-worktrees.md

How overnight skills lay out git worktrees: a bare repository at the project root, the main copy at main/, and one worktree per issue inside the project folder — never next to it. Pre-flight refuses to launch until the project uses this layout.

Overnight

yaawn-glossary.md

yaawn's own glossary, shipped in .yaawn/ and overwritten on install — the vocabulary of the workflow itself (grill, ADR, slice, lane). Never holds project terms.

Shared

yaawn-project-glossary.md

Your project's domain vocabulary in .yaawn/ — every term that settles during a design grill is added here, in alphabetical order. Grill skills keep it current automatically.

Shared
Project config

yaawn-definition-of-done.md

Your project's shared checklist that /yaawn-verify-executed-plan walks through before opening a pull request. Edit it to match how your team defines done — every item must be checkable by a human or a command.

Verification

yaawn-verification-commands.md

The commands /yaawn-verify-executed-plan runs from the repo root, in order, stopping at the first failure. List the cheap checks first — lint, typecheck, unit tests — and e2e last.

Verification

roles/*.role.md

Your product's user roles in .yaawn/roles/, one file per role — the personas that story work starts from. Each file holds the role's name as its heading, a description, and its goals. /yaawn-write-user-story, /yaawn-grill-story, and /yaawn-split-story read every role file to keep personas consistent across issues; with no role files, stories are written for the Developer.

Backlog

Prerequisites

What you need before running the workflow.

Required tools

Node.js

Node.js 20.17+, 22.13+, or 23.5+ (includes npm). The installer ships compiled JS; skill scripts run via npx tsx.

caffeinate or systemd-inhibit (overnight only)

/yaawn-implement-plan keeps your computer awake with whichever is installed — caffeinate first, then systemd-inhibit. Preflight refuses to launch when neither is found.

Sign in to your agent

Setup asks which agents your team uses and which one runs the overnight sessions. Install and sign in to at least one:

GitHub CLI

Skills read and write issues through gh — authenticate once.

GitHub Copilot CLI

Mistral Vibe

Claude Code

Run claude once to sign in.

Repository labels

Missing labels are created automatically when an issue is created from a template or a skill adds one. Create them upfront only for consistent colors and descriptions.

Label Description Created by
Yaawn: Story New features delivering user value Issue templates
Yaawn: Bug Defects or incorrect behavior Issue templates
Yaawn: Refactor Technical improvements without behavior change Issue templates
Yaawn: Spike Research or investigation before implementation Issue templates
Yaawn: Prototype Throwaway experiments to test feature ideas with customers Issue templates
Yaawn: Other Work that matches none of the other types Issue templates
Yaawn: To Be Refined Applied to new issues by the templates Issue templates
Yaawn: Ready To Implement Plan saved and every open question answered /yaawn-save-plan
Yaawn: implementation-group-<n> Ready issues that can be implemented together /yaawn-implement-plan

Bare Git Repository and LLM Setup

The project root holds a bare .git with main/ worktree.

1. Clone bare into the project root

2. Check out main/

Start your sessions in main/. /yaawn-implement-plan creates each issue's worktree itself.

Every agent loads from two folders in the working copy: .agents/ — your skills and instructions, symlinked from here into each agent's tool folders — and .yaawn/ — yaawn's files, wired by the installer.

your-project/
├── .git/                 bare repository
├── main/                 working copy — agent files live here
│   ├── AGENTS.md project rules, read by every agent
│   ├── .agents/           your own skills & instructions
│   │   ├── skills/<n>/
│   │   └── instructions/*.instructions.md
│   ├── .yaawn/            yaawn's files — installed & linked by setup
│   │   ├── skills/yaawn-*/  instructions/  personas/  output-styles/
│   │   ├── yaawn-definition-of-done.md, yaawn-verification-commands.md, …
│   │   ├── yaawn-settings.json local only, gitignored
│   │   └── roles/  adr/  plans/
│   ├── .github/
│   │   ├── ISSUE_TEMPLATE/yaawn-*
│   │   ├── instructions/agents -> ../../.agents/instructions
│   │   ├── instructions/yaawn -> ../../.yaawn/instructions
│   │   └── skills -> ../.yaawn/skills
│   ├── .claude/
│   │   ├── CLAUDE.md @../AGENTS.md
│   │   ├── rules/agents -> ../../.agents/instructions
│   │   ├── rules/yaawn -> ../../.yaawn/instructions
│   │   ├── skills/<n> -> ../../.agents/skills/<n>
│   │   └── skills/yaawn-<n> -> ../../.yaawn/skills/yaawn-<n>
│   └── .vibe/
│       └── config.toml skill_paths = [".yaawn/skills"]
└── yaawn-<issue>-<slug>/ one worktree per issue (overnight)

Known Issues

What we are working on next.

  • Support Context.md files and scoping.
  • Include behavior driven development.
  • Add Codex support.
  • Make custom hooks more accessible and future proof.
  • Add configurable pre- and post-hooks for all steps of the workflow.
  • Support Claude Dynamic Workflows.
  • Migrate old files with new versions of the workflow.
  • Fix overnight handover to session.

Changelog

What changed in each release of the workflow package.

v0.10.0

2026-11-09 @yaawn/workflow

Features

  • All five workflow steps — prepare, create, save, implement and verify — now log their token usage, durations and peak context to a per-issue log, .yaawn/metrics/runs/yaawn-<issue>.jsonl, written in the issue's worktree and committed with its branch, so token usage and failures can be observed over time.
  • New npx @yaawn/workflow metrics command: an interactive terminal report with run statistics, every run, the token trend per issue with an up/down/flat verdict, peak context against the context limit (120,000 tokens, or contextLimitTokens in .yaawn/yaawn-settings.json), an issue picker, and per-issue details per step. Needs a terminal; the raw JSONL stays readable with jq.
  • The overnight run now also runs the project's verification commands on the final code — fixing what fails in up to 3 fix sessions — and leaves a record; /yaawn-verify-executed-plan skips the commands when that record passed on exactly this code, and stops when it failed on it.
  • Grilling sessions now run an open grill first — questioning everything — and only then work through the checklist over the open frontier.
  • New declarative programming instructions (yaawn-declarative.instructions.md).

Bug fixes

  • Verification no longer fingerprints .yaawn/metrics/ together with the code.
  • Plain-language (eli5) summaries no longer use analogies and print less.
  • The implementer now receives the acceptance criteria for testing.
Show older releases

v0.9.0

2026-11-03 @yaawn/workflow

Features

  • Setup is reordered around .yaawn/ as the single leading directory: skills, instructions, output styles, and config live there, and each coding agent you check pulls in what it can — Copilot gets .github/instructions/yaawn and .github/skills, Claude Code gets .claude/rules/yaawn plus one link per skill and output style, and Vibe gets .yaawn/skills in the skill_paths of .vibe/config.toml.
  • The setup now asks which coding agents your team uses — several can be checked — and, separately, which one runs the overnight sessions, since overnight runs can only use one.
  • yaawn no longer edits your own files: instead of writing into AGENTS.md or CLAUDE.md, it only creates links for the checked agents and removes the links of the unchecked ones.

v0.8.0

2026-11-01 @yaawn/workflow

Features

  • Every story now gets a split assessment: SPIDER runs in a subagent for every story — never gated on a size guess — and you decide whether to split it.
  • Pull request creation is now a setup choice: verification opens a pull request only when enabled in .yaawn/yaawn-settings.json — otherwise it tells you how to enable it.
  • New --debug flag for the overnight run: the lane result and the morning summary then report per-session and total token usage.
  • User roles now live in one file per role — .yaawn/roles/<role-name>.role.md, with the role name in the # heading and its goals in ## Goals — instead of the single .yaawn/yaawn-user-roles.md.
  • A contradicted ADR is now reversed in place — same file and number, fresh date — instead of being superseded by a new ADR.

Bug fixes

  • Removed redundant descriptions from the shipped files to save tokens.

v0.7.0

2026-10-31 @yaawn/workflow

Features

  • Grilling sessions now use Architecture Decision Records: a settled decision in .yaawn/adr/<domain>/ is cited instead of argued again, and /yaawn-grill-design proposes an ADR for each decision that is hard to reverse.
  • Non-blocking code review findings are now fixed automatically during the overnight run.
  • Pull requests now get a proper title.
  • Worktrees are cleaned up automatically after their pull requests are created.
  • The overnight run reports token usage in the morning summary.
  • Bulk rounds in grilling sessions offer a default "accept all" answer.
  • The installer now guides you more clearly step by step.

Bug fixes

  • The correct persona is now applied to each plan step.
  • Removed the default Definition of Done item and the default verification commands from the installer.
  • The verification skill no longer depends on the overnight run.

v0.6.0

2026-10-27 @yaawn/workflow

Features

  • Overnight sessions now run on Linux too: systemd-inhibit keeps the computer awake when caffeinate is not installed (macOS). yaawn uses whichever is available, caffeinate first.

Bug fixes

  • Fixed indentation of the overnight message text.

v0.5.1

2026-10-26 @yaawn/workflow

Features

  • The owl mascot now appears in the installer and in the overnight handover message.

Bug fixes

  • Fixed the owl message in the handover output.
  • The human readable plan summary now focuses on the implementation at the concept level.

v0.5.0

2026-10-24 @yaawn/workflow

Features

  • Plans can now be verified from the main branch, not just feature branches.

Bug fixes

  • Migrated interactive prompts to @clack/prompts.
  • Previously running agent sessions are killed before starting new ones.
  • Open questions are saved during prepare-plan.
  • Added missing type definitions.

v0.4.0

2026-10-23 @yaawn/workflow

Features

  • Improved grilling performance.
  • Delayed codebase exploration until the design discussion actually needs it.
  • Added prototyping: /yaawn-write-prototype and /yaawn-grill-prototype skills for throwaway experiments to test feature ideas with customers.

Bug fixes

  • Check open questions when saving a plan.
  • Website is now published with the package.
  • Prototypes run on a prototype/ branch that is never merged, and skip code review.
  • /yaawn-extract-learnings turns prototype results into a story after approval, or closes the issue when the prototype is rejected.

v0.3.1

2026-10-21 @yaawn/agent-skills

Other

  • Re-release of v0.3.0 — only the version number changed, no code differences. Published to fix a release that did not reach npm.

v0.3.0

2026-10-21 @yaawn/agent-skills

Features

  • Agent choice is saved locally per developer in .yaawn/yaawn-settings.json, kept out of git.
  • Save plan finds an existing plan in the issue.
  • Main branch is updated before implementation starts.

Bug fixes

  • Hardened the no-code rule for preparing work items.
  • Only lower-level headings are allowed in plans.

v0.2.1

2026-10-20 @yaawn/agent-skills

Bug fixes

  • Patch release: overnight runs now report progress and results back to the agent session more clearly during parallel execution, with new process and stage tracking.

v0.2.0

2026-10-20 @yaawn/agent-skills

Features

  • Improved story grilling.
  • Removed subissue logic.

v0.1.0

2026-10-20 @yaawn/agent-skills

Features

  • Dedicated grilling sessions per issue type — story, refactor, spike, bug report, and other change.
  • Bare-repo layout with worktrees inside the project folder.
  • Accessibility instructions for HTML, CSS, and JavaScript.
  • Website redesign with a hero feature list.
  • New rollout strategy option.
  • Broadened the prepare skill to handle different work item types.

Bug fixes

  • Fixed the worktree name pattern.

v0.0.12

2026-10-16 @yaawn/agent-skills

Features

  • 22 skills, 3 personas, 10 instructions, and an output style.
  • Parallel overnight execution with pull request creation from worktrees.
  • Implementation groups for batching related issues.
  • Agent selection: Mistral Vibe, Claude Code, or GitHub Copilot CLI.
  • /yaawn-prepare-plan turns ideas into approved work items.

Other

  • Initial public release.