Setup Workflow Skills
Reconciles a repo against the following desired state:
| # |
Goal |
Check |
| 1 |
AGENTS.md exists with 4 prescribed blocks (Before exploring, Issue tracker, Glossary vocabulary, Flag ADRs), contiguous and verbatim |
File present, block matches canonical |
| 2 |
docs/glossary.md exists |
File present |
| 3 |
docs/adr/ directory exists |
Dir present |
| 4 |
docs/issue-tracker.md content matches canonical |
File present, exact match |
| 5 |
bd CLI installed |
command -v bd succeeds |
| 6 |
Beads project initialised |
bd list succeeds |
| 7 |
Beads config: no hooks, stealth mode, .beads/ in .git/info/exclude |
Config correct, exclude entry present |
| 8 |
Prescribed skills are available: break-issue, grill-with-docs, handoff, improve-codebase-architecture, prototype, setup-workflow-skills, tdd, write-a-skill, write-issue, zoom-out |
Each skill has an entry in skills-lock.json AND a directory under .agents/skills/<skill>/ with SKILL.md |
The fix is always plan-then-execute: detect all deviations, report them, get user confirmation, then apply.
Process
1. Explore
Check each goal against the current repo state:
- Goal 1: Read instructions.md for canonical content. Read
AGENTS.md (if it exists). Find the contiguous block from ## Before exploring, read these through end of ## Flag ADR conflicts. Compare exact string match.
- Goals 2-3: Check file/dir existence.
- Goal 4: Read
docs/issue-tracker.md (if it exists) and compare full content against issue-tracker.md.
- Goal 5:
command -v bd
- Goal 6:
bd list (or bd --version / equivalent non-mutating command)
- Goal 7: Check for hooks config (beads.config.json or
.beads/ hooks), check stealth flag, check .git/info/exclude for .beads/issues.jsonl.
- Goal 8: For each prescribed skill, check
skills-lock.json for an entry keyed by the skill name, and check .agents/skills/<skill>/SKILL.md exists. Prescribed skills: break-issue, grill-with-docs, handoff, improve-codebase-architecture, prototype, setup-workflow-skills, tdd, write-a-skill, write-issue, zoom-out.
2. Report
Present a summary:
Found [n]/8 goals satisfied.
Deviations:
- [Goal 1] ...
- [Goal 3] ...
...
3. Confirm
Show the planned fixes. Wait for user approval before applying.
4. Fix
Goal 1 (AGENTS.md):
- If the prescribed block is missing or drifted, replace the entire contiguous range (
## Before exploring, read these through end of ## Flag ADR conflicts) with canonical content from instructions.md. Preserve everything outside that range.
- If
AGENTS.md doesn't exist, create it with the canonical content.
Goal 2 (glossary): Create docs/glossary.md with a stub if missing. Never overwrite existing content.
Goal 3 (adr): Create docs/adr/ if missing.
Goal 4 (issue tracker): Write/overwrite docs/issue-tracker.md with canonical content from issue-tracker.md.
Goal 5 (CLI): If bd not found:
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Goal 6 (init): If project not initialised:
bd init --stealth --non-interactive
Goal 7 (config):
- Ensure no beads hooks are configured (check
beads.config.json or .beads/).
- Ensure
.beads/issues.jsonl is listed in .git/info/exclude. Append if missing.
Goal 8 (prescribed skills):
For each missing skill:
npx skills add kehwar/skills --skill <skillname> -y
If npx skills is not available, flag it as requiring manual setup.
5. Done
Report which fixes were applied. Note any goals that couldn't be auto-fixed.
1---2name: setup-workflow-skills3description: Detects and fixes deviations from the prescribed repo workflow configuration — AGENTS.md, docs layout, and Beads issue tracking.4---56# Setup Workflow Skills78Reconciles a repo against the following **desired state**:910| # | Goal | Check |11|---|------|-------|12| 1 | `AGENTS.md` exists with 4 prescribed blocks (Before exploring, Issue tracker, Glossary vocabulary, Flag ADRs), contiguous and verbatim | File present, block matches canonical |13| 2 | `docs/glossary.md` exists | File present |14| 3 | `docs/adr/` directory exists | Dir present |15| 4 | `docs/issue-tracker.md` content matches canonical | File present, exact match |16| 5 | `bd` CLI installed | `command -v bd` succeeds |17| 6 | Beads project initialised | `bd list` succeeds |18| 7 | Beads config: no hooks, stealth mode, `.beads/` in `.git/info/exclude` | Config correct, exclude entry present |19| 8 | Prescribed skills are available: `break-issue`, `grill-with-docs`, `handoff`, `improve-codebase-architecture`, `prototype`, `setup-workflow-skills`, `tdd`, `write-a-skill`, `write-issue`, `zoom-out` | Each skill has an entry in `skills-lock.json` AND a directory under `.agents/skills/<skill>/` with `SKILL.md` |2021The fix is always **plan-then-execute**: detect all deviations, report them, get user confirmation, then apply.2223## Process2425### 1. Explore2627Check each goal against the current repo state:2829- **Goal 1**: Read [instructions.md](./instructions.md) for canonical content. Read `AGENTS.md` (if it exists). Find the contiguous block from `## Before exploring, read these` through end of `## Flag ADR conflicts`. Compare exact string match.30- **Goals 2-3**: Check file/dir existence.31- **Goal 4**: Read `docs/issue-tracker.md` (if it exists) and compare full content against [issue-tracker.md](./issue-tracker.md).32- **Goal 5**: `command -v bd`33- **Goal 6**: `bd list` (or `bd --version` / equivalent non-mutating command)34- **Goal 7**: Check for hooks config (beads.config.json or `.beads/` hooks), check stealth flag, check `.git/info/exclude` for `.beads/issues.jsonl`.35- **Goal 8**: For each prescribed skill, check `skills-lock.json` for an entry keyed by the skill name, and check `.agents/skills/<skill>/SKILL.md` exists. Prescribed skills: `break-issue`, `grill-with-docs`, `handoff`, `improve-codebase-architecture`, `prototype`, `setup-workflow-skills`, `tdd`, `write-a-skill`, `write-issue`, `zoom-out`.3637### 2. Report3839Present a summary:4041```42Found [n]/8 goals satisfied.4344Deviations:45- [Goal 1] ...46- [Goal 3] ...47...48```4950### 3. Confirm5152Show the planned fixes. Wait for user approval before applying.5354### 4. Fix5556**Goal 1 (AGENTS.md):**57- If the prescribed block is missing or drifted, replace the entire contiguous range (`## Before exploring, read these` through end of `## Flag ADR conflicts`) with canonical content from [instructions.md](./instructions.md). Preserve everything outside that range.58- If `AGENTS.md` doesn't exist, create it with the canonical content.5960**Goal 2 (glossary):** Create `docs/glossary.md` with a stub if missing. Never overwrite existing content.6162**Goal 3 (adr):** Create `docs/adr/` if missing.6364**Goal 4 (issue tracker):** Write/overwrite `docs/issue-tracker.md` with canonical content from [issue-tracker.md](./issue-tracker.md).6566**Goal 5 (CLI):** If `bd` not found:67```bash68curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash69```7071**Goal 6 (init):** If project not initialised:72```bash73bd init --stealth --non-interactive74```7576**Goal 7 (config):**77- Ensure no beads hooks are configured (check `beads.config.json` or `.beads/`).78- Ensure `.beads/issues.jsonl` is listed in `.git/info/exclude`. Append if missing.7980**Goal 8 (prescribed skills):**81For each missing skill:82```bash83npx skills add kehwar/skills --skill <skillname> -y84```8586If `npx skills` is not available, flag it as requiring manual setup.8788### 5. Done8990Report which fixes were applied. Note any goals that couldn't be auto-fixed.
kehwar