Surveying the herd. Use when planning work by approaching goals and discovering blockers — emergent planning through action, not top-down decomposition

2026-03-293

yak-nightshift

mrdavidlaing/yakthang

The night crew. Unattended overnight session where Yakob works through a queue of well-defined yaks serially — shave, sniff-test, remediate if needed, push a PR — so the operator wakes up to reviewable PRs.

2026-03-293

yak-shaving-handbook

mrdavidlaing/yakthang

The shaver's field guide. The complete operating guide for shavers in the yakthang environment. Covers task lifecycle (yx show, start, shaver-message, done), message checking (yakob-message), heartbeat (via /loop), and notes for Yakob.

2026-03-293

yak-triage

mrdavidlaing/yakthang

Sorting the herd at the gate. Session start ritual for Yakob. Establishes the time window and WIP limit, surveys the yak map, and helps the operator decide what to tackle this session — before acceleration flow begins.

2026-03-293

yak-wrap

mrdavidlaing/yakthang

Closing the barn. End-of-session wrap-up for Yakob. Harvests done yaks into a worklog summary, prunes the map, and reorganizes remaining work for the next session. Can be called at any natural break point — not just end of day.

2026-03-293

yak-sniff-test

mrdavidlaing/yakthang

Does this yak smell right? Use when a shaver reports done and Yakob needs to verify the work matches the brief using a fresh, independent reviewer agent before accepting or pruning the yak.

2026-03-213

name	yak-adr
description	Architecture Decision Records. Create, manage, and cross-reference ADRs — no external CLI needed.
allowed-tools	Read, Write, Edit, Grep, Glob
argument-hint	<create\|supersede\|amend\|update-index\|list> [title or ADR number]

Architecture Decision Records

User instructions: $ARGUMENTS

Argument Routing

Parse $ARGUMENTS to determine which operation to perform:

create "Title" or just a title string — create a new ADR
supersede NNNN "New Title" — create a new ADR that supersedes #NNNN
amend NNNN "New Title" — create a new ADR that amends #NNNN
update-index — regenerate the README.md index table
list — show all existing ADRs and their statuses

If $ARGUMENTS is empty or unclear, ask the user what they want to do.

When to Write an ADR

Write an ADR when making decisions that:

Change the architecture or core design patterns
Introduce new dependencies or technologies
Affect multiple components or the public API
Have long-term maintenance implications
Future maintainers will ask "why did we do it this way?"

Not for: minor implementation details, bug fixes, refactoring, configuration changes.

If the user's request doesn't clearly warrant an ADR, mention this guidance before proceeding. Don't refuse — the user may have good reasons.

Conventions

Convention	Value
ADR location	`docs/adr/` relative to repository root
Filename format	`NNNN-kebab-case-title.md` (4-digit zero-padded)
Index file	`docs/adr/README.md` with markdown table
New ADR status	`proposed`
Date format	`YYYY-MM-DD`

Supported statuses: proposed, accepted, rejected, superseded, amended, deprecated

Process: Determine Next ADR Number

Use Glob to find existing ADR files: pattern docs/adr/[0-9][0-9][0-9][0-9]-*.md
If no files exist, the next number is 0001
Otherwise, extract the number from the last file (sorted), increment by 1, zero-pad to 4 digits

Process: Directory Bootstrap

Before any operation, check if docs/adr/ exists. If not:

Create docs/adr/ directory
Create docs/adr/README.md with the initial template (see Operation: Update Index for the full template)
Inform the user: "Created docs/adr/ directory and initial README.md"

Process: Convert Title to Kebab-Case

Lowercase all characters
Replace spaces and special characters with hyphens
Remove consecutive hyphens
Strip leading/trailing hyphens
Examples:
- "Adopt CQRS and Event Sourcing" → adopt-cqrs-and-event-sourcing
- "Keep main.rs Thin" → keep-main-rs-thin
- "UUID for Migration Events" → uuid-for-migration-events

ADR Template

When creating a new ADR, write the file with this exact structure:

# NNNN. Title of the Decision

Date: YYYY-MM-DD

## Status

proposed

## Context

[Describe the issue, forces at play, and what motivates this decision.
Include enough background that a reader unfamiliar with the project
can understand why this decision matters.]

## Decision

[State the decision clearly. Use active voice: "We will..." or
"Use X for Y because Z."]

### Relation to other ADRs

None.

## Consequences

### Benefits

[What becomes easier or better because of this decision.]

### Trade-offs

[What becomes harder or more constrained. Be honest.]

### Future considerations

[Open questions, things to watch for, conditions under which
this decision should be revisited.]

Operation: Create

Bootstrap the directory if needed (see Process: Directory Bootstrap)
Determine the next ADR number (see Process: Determine Next ADR Number)
Convert the title to kebab-case (see Process: Convert Title to Kebab-Case)
Create the file at docs/adr/NNNN-kebab-case-title.md using the ADR Template
Fill in:
- Title as NNNN. Title (preserving the user's original casing)
- Date as today's date
- Status as proposed
- If the user provided context about the decision, fill in Context, Decision, and Consequences sections with that content
- Otherwise, leave the placeholder text for the user to fill in
Update the index (see Operation: Update Index)

Report what was created:

Created: docs/adr/NNNN-kebab-case-title.md
Status: proposed

Next steps:
- Fill in Context, Decision, and Consequences (if not already done)
- Change status to "accepted" once the decision is agreed upon
- Commit the ADR with the related code changes

Operation: Supersede

When a new decision replaces an older one entirely:

Read the old ADR file (docs/adr/NNNN-*.md) to confirm it exists and get its title
Create the new ADR (follow Operation: Create steps 1–5)
In the new ADR's Status section, write: accepted (supersedes ADR NNNN)
In the new ADR's "Relation to other ADRs" subsection, explain what changed and why the old decision is being replaced
Update the old ADR's Status section to: superseded by ADR MMMM — Short Title of New ADR
- Do NOT change anything else in the old ADR
Update the index (see Operation: Update Index)

Report both files modified:

Created: docs/adr/MMMM-new-title.md (supersedes ADR NNNN)
Updated: docs/adr/NNNN-old-title.md → status: superseded

Both ADRs cross-reference each other.

Operation: Amend

When a new decision modifies (but does not replace) an older one:

Read the old ADR file (docs/adr/NNNN-*.md) to confirm it exists and get its title
Create the new ADR (follow Operation: Create steps 1–5)
In the new ADR's Status section, write: accepted (amends ADR NNNN)
In the new ADR's "Relation to other ADRs" subsection, explain what is being modified and why
Update the old ADR's Status section by appending on a new line: amended by ADR MMMM — Short Title of New ADR
- Keep the old ADR's existing status on its own line (e.g., accepted remains)
- Example result:
```
accepted
amended by ADR MMMM — Short Title of New ADR
```
- Do NOT change anything else in the old ADR
Update the index (see Operation: Update Index)

Report both files modified:

Created: docs/adr/MMMM-new-title.md (amends ADR NNNN)
Updated: docs/adr/NNNN-old-title.md → status: amended

Both ADRs cross-reference each other.

Operation: Update Index

Regenerate docs/adr/README.md from the current ADR files:

Find all ADR files matching docs/adr/[0-9][0-9][0-9][0-9]-*.md using Glob
For each file, extract:
- Number: first 4 digits of the filename
- Title: from the first # heading, stripping the NNNN. prefix
- Status: the first non-empty line after ## Status — use only the first word for the index table (e.g., superseded not superseded by ADR 0019 — Title)
Sort rows by ADR number ascending
Write docs/adr/README.md with this structure:

# Architecture Decision Records

ADRs document significant architectural and design decisions.

## Index

| # | Decision | Status |
|---|----------|--------|
| [NNNN](NNNN-filename.md) | Title | status |

## When to Write an ADR

Write an ADR when making decisions that:
- Change the architecture or core design patterns
- Introduce new dependencies or technologies
- Affect multiple components or the public API
- Have long-term maintenance implications
- Future maintainers will ask "why did we do it this way?"

Not for: minor implementation details, bug fixes, refactoring,
configuration changes.

Operation: List

Read docs/adr/README.md if it exists and display the Index table
If no README.md exists, scan for ADR files and display a summary table
If no ADR files exist, report: "No ADRs found in docs/adr/"

Quick Reference

Operation	Invocation	What it does
Create	`/yak-adr create "Title"`	New ADR with next sequential number
Supersede	`/yak-adr supersede 0015 "New approach"`	New ADR, marks old as superseded
Amend	`/yak-adr amend 0012 "Refinement"`	New ADR, marks old as amended
Update index	`/yak-adr update-index`	Regenerate README.md table
List	`/yak-adr list`	Show all ADRs and statuses

Status Lifecycle

Status	Meaning	How it's set
proposed	Under discussion, not yet accepted	Default for new ADRs
accepted	Decision is in effect	User manually changes from proposed
rejected	Considered but not adopted	User manually changes from proposed
superseded	Replaced by a newer ADR	Set by supersede operation
amended	Modified by a newer ADR (still partially in effect)	Set by amend operation
deprecated	No longer relevant but not replaced	User manually sets