@ecology91/skills 0.1.0

package/skills/engineering/setup-agent-skills/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: setup-agent-skills
+description: Sets up an `## Agent skills` block in AGENTS.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub, GitLab, Beads, local markdown, or custom), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `to-qa`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
+disable-model-invocation: true
+---
+
+# Setup Agent Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker** — where issues live (GitHub, GitLab, Beads, local markdown, and custom workflows are supported)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `.beads/` — is Beads already initialized for local issue tracking?
+- `bd --help` or `command -v bd` — is the Beads CLI available?
+- `.sandcastle/` — does existing Sandcastle prompt/config scaffolding mention Beads commands such as `bd ready --json`?
+- If `.sandcastle/` exists, inspect prompts for stale RALPH anti-patterns: planner analyzing dependencies from `bd ready`, implementer saying "fill your context window", implementer preloading full recent commits, implementer fetching issue context itself instead of using provided task context, merge prompt running tests after each branch, or merge prompt closing all listed issues instead of only merge-eligible issues.
+- `AGENTS.md` at the repo root — does it exist? Is there already an `## Agent skills` section?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+
+Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, and `to-prd` read from and write to it. `/to-qa` reads parent and completed child work from it, then writes QA checks to QA To Do instead of mutating tracker issues. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub and Beads/Sandcastle workflows. If a `git remote` points at GitHub, propose GitHub. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. If `.beads/` exists or Sandcastle/RALPH conventions are present, propose Beads. Otherwise (or if the user prefers), offer:
+
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Beads** — issues live in `.beads/` and are managed with the `bd` CLI; this is the most explicit option for Sandcastle/RALPH parent-child issue workflows
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+For `/to-qa`, make sure the chosen issue tracker documentation explains how to fetch completed child work for a parent issue. Beads and local markdown templates include this by default. GitHub, GitLab, and custom trackers need a repo-specific parent/child convention if the user wants `/to-qa` to work there.
+
+If stale `.sandcastle/` prompt anti-patterns are present, warn that RALPH prompts should be updated before running autonomous work. Current Sandcastle loops should pass compact `bd ready` output to the planner, load task context once before implementer launch, use completion signals for merge eligibility, and run verification at the right level rather than repeatedly per branch.
+
+**Section B — Triage label vocabulary.**
+
+> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
+
+**Section C — Domain docs.**
+
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+
+Confirm the layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to `AGENTS.md`
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `AGENTS.md` exists, edit it.
+- If it does not exist, create `AGENTS.md`.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-beads.md](./issue-tracker-beads.md) — Beads issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/skills/engineering/setup-agent-skills/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/skills/engineering/setup-agent-skills/issue-tracker-beads.md

@@ -0,0 +1,54 @@
+# Issue tracker: Beads
+
+Issues and PRDs for this repo live in `.beads/`. Use the `bd` CLI for all operations. `.beads/` must be committed/tracked in git for opencode/Sandcastle worktree sandboxes to see it; untracked local Beads state will not appear in worktrees.
+
+## Conventions
+
+- **Issue IDs**: Beads IDs are strings like `bd-a1b2` or hierarchical IDs, never numeric issue numbers. If another skill says `#42`, issue number, or numeric issue reference, use the Beads string ID instead; if only a number is supplied, ask for or search for the Beads ID.
+- **Create an issue**: `bd create "Title" --body-file - -t task -p 2 -l needs-triage --json`. Pipe multiline bodies through stdin or a body file, for example `bd create "Title" --body-file - -t task -p 2 -l needs-triage --json < body.md`. `--stdin` is an alias for `--body-file -`.
+- **Create a child issue**: `bd create "Title" --body-file - --parent <parent-id> -t task -p 2 -l ready-for-agent --json`.
+- **Create a human-gated child issue**: `bd create "Title" --body-file - --parent <parent-id> -t task -p 2 -l ready-for-human --json`.
+- **Issue type**: `-t, --type` accepts `bug|feature|task|epic|chore|decision`; default is `task`.
+- **Priority**: `-p 2` is Beads' default medium priority. `0` / `P0` is highest; `4` / `P4` is lowest. Sandcastle uses `bd ready --json` for actionable work and does not parse priority itself.
+- **Labels**: `-l, --labels` accepts comma-separated labels, for example `-l needs-triage,bug`.
+- **Read an issue**: `bd show <ID> --json` and `bd comments <ID> --json`.
+- **List actionable work**: `bd ready --json` returns unblocked work that is ready to pick up.
+- **Query children for QA**: `bd list --parent <parent-id> --status all --json --limit 0` returns the full parent-scoped child set.
+- **List open work**: `bd list --status open --json` returns open issues, including blocked issues; don't use it as a substitute for `bd ready --json`.
+- **Add a dependency**: `bd dep add <blocked-issue-id> <blocking-issue-id> --type blocks`. The blocking issue is the second positional argument. `--blocked-by` is also accepted, but prefer the positional form.
+- **Comment on an issue**: `bd comments add <ID> "..." --json`. For multiline agent briefs or triage notes, use `bd comments add <ID> -f notes.md --json` or a safely quoted multiline shell string.
+- **Apply / remove labels**: `bd label add <ID> <label>` / `bd label remove <ID> <label>`
+- **Claim work**: `bd update <ID> --claim --json` when a workflow asks an agent to claim an issue.
+- **Close**: `bd close <ID> --reason "..." --json`
+
+## When a skill says "publish to the issue tracker"
+
+Create a Beads issue with `bd create "Title" --body-file - -t task -p 2 -l needs-triage --json`, passing the markdown body on stdin or from a body file.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `bd show <ID> --json` and `bd comments <ID> --json`.
+
+## When the triage skill asks for incoming work
+
+Run `bd list --status open --json`, then inspect relevant issues with `bd show <ID> --json` and `bd comments <ID> --json`. Queue helpers: `bd list --status open --no-labels --json`, `bd list --status open --label needs-triage --json`, and `bd list --status open --label needs-info --json`.
+
+For large parent-scoped triage, fetch the full child set up front with `bd list --parent <parent-id> --status all --json --limit 0`. Do not use `bd children <parent-id> --json` for exhaustive automation because it can hide matches behind the default limit and does not accept `--limit`. Apply label changes in batches where possible, then add generated comments in small chunks of 5 to 10 issues to avoid command timeouts and duplicate comments.
+
+Derive triage buckets from labels and comments:
+
+- **Unlabeled**: open issues with no triage-role label.
+- **Needs triage**: issues labeled `needs-triage`.
+- **Needs info**: issues labeled `needs-info`; read comments to see what information was requested and whether the reporter has answered.
+
+Process oldest first when timestamp fields are present. For triage transitions, remove existing state-role labels before adding the new mapped triage label. Use `bd label add <ID> <label>`, `bd label remove <ID> <label>`, and `bd comments add <ID> -f notes.md --json` to record transitions. Category labels `bug` and `enhancement` are literal Beads labels unless the repo documents another mapping.
+
+## When `/to-qa` needs completed child work
+
+Fetch the full child set with `bd list --parent <parent-id> --status all --json --limit 0`.
+
+Include only child issues whose status is closed, completed, or done according to this repo's Beads vocabulary. Exclude open, blocked, or incomplete children and report them as warnings.
+
+For each included child, read `bd show <child-id> --json` and `bd comments <child-id> --json`.
+
+Do not mutate Beads issues during `/to-qa`.

package/skills/engineering/setup-agent-skills/issue-tracker-github.md

@@ -0,0 +1,33 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## `/to-qa` support
+
+This template does not define a default completed-child query for `/to-qa`. If this repo uses GitHub Issues with `/to-qa`, extend `docs/agents/issue-tracker.md` with:
+
+- how parent issues link to child issues,
+- how completed child work is identified,
+- which issue states/labels count as completed,
+- which command fetches the full child set.
+
+Do not mutate GitHub issues during `/to-qa`.

package/skills/engineering/setup-agent-skills/issue-tracker-gitlab.md

@@ -0,0 +1,34 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## `/to-qa` support
+
+This template does not define a default completed-child query for `/to-qa`. If this repo uses GitLab Issues with `/to-qa`, extend `docs/agents/issue-tracker.md` with:
+
+- how parent issues link to child issues,
+- how completed child work is identified,
+- which issue states/labels count as completed,
+- which command fetches the full child set.
+
+Do not mutate GitLab issues during `/to-qa`.

package/skills/engineering/setup-agent-skills/issue-tracker-local.md

@@ -0,0 +1,27 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## When `/to-qa` needs completed child work
+
+For a parent path or feature directory, read structured child issue files under `.scratch/<feature-slug>/issues/`.
+
+Include only files whose `Status:` line is `closed`, `completed`, or `done`. Treat missing or unknown status as incomplete and report it as a warning.
+
+Use the issue file path as the source issue ID/evidence. Do not create, rename, edit, close, or delete `.scratch` files during `/to-qa`.

package/skills/engineering/setup-agent-skills/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in these skills | Label in our tracker | Meaning                                  |
+| --------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/skills/engineering/setup-coding-quality-checks/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: setup-coding-quality-checks
+description: Onboards a repo for local-only development by installing and documenting strict Coding Quality Checks that make AI-agent coding safer and more correct. Use when the user wants to set up or strengthen local formatters, linters, typechecks, tests, security scanners, build checks that already exist, or git hooks for a greenfield or brownfield repo.
+---
+
+# Setup Coding Quality Checks
+
+Set up a local correctness environment where AI agents can work safely. Keep scope tight: formatter, linter, typecheck, tests, security scanners when warranted, git hooks, and existing build checks only. Do not turn this into a broad validation framework.
+
+## Principles
+
+- Use **Coding Quality Checks** as the umbrella term.
+- Explore before asking. If repo evidence answers a question, use it.
+- Ask one decision at a time, with a recommended answer.
+- Prefer strict correctness over convenience; brownfield repos may fail immediately.
+- Do not auto-format or lint-autofix source without separate confirmation.
+- Do not invent build steps or aggregate commands. Preserve repo terminology.
+- Sub-agents may discover and draft plans; the main agent owns decisions, confirmation, and edits.
+
+## 1. Discover
+
+Inspect before asking. Use sub-agents freely when useful; give each a radically different angle: stack discovery, existing tooling, security/hook risks, or greenfield planning clues.
+
+Look for repo instructions (`AGENTS.md`, `.cursor/rules`, copilot instructions), Sandcastle docs (`.sandcastle/**/*.md`), package manifests, lockfiles, existing configs/scripts, tests, source layout, and existing CI files. Use CI as evidence, but ask before editing it.
+
+For Beads, inspect `.beads/` and use read-only `bd` commands when available. Use issues for stack clues and acceptance criteria; never mutate Beads unless separately asked.
+
+For greenfield repos, inspect README, PRDs, roadmap, Beads issues, package manifests, and planning docs before asking the user for the intended stack.
+
+For transcripts, search only repo-local notes such as `.opencode/`, `.aider*`, `.continue/`, `transcripts/`, `chat.md`, `SESSION.md`, or `notes/`. Treat transcript evidence as weak and use it only for quality-check clues.
+
+Evidence order: current user instruction; agent/repo docs and Sandcastle prompts; scripts/configs/manifests/lockfiles; Beads acceptance criteria; CI files; transcripts; source layout; ecosystem defaults.
+
+Stop and ask if package-manager signals conflict. Never create a second lockfile family.
+
+## 2. Interview
+
+Present only relevant findings, then walk the user through decisions in this order. Skip irrelevant categories.
+
+1. Local-only meaning: ask whether installs/scanner network access are allowed for this repo.
+2. Formatter: recommend one formatter matching repo convention; add check-mode scripts; do not format files automatically.
+3. Linter: recommend strict correctness linting that does not fight the formatter; add fix scripts only as explicit commands; do not autofix automatically.
+4. Typecheck: recommend strict practical settings; warn brownfield repos about blast radius.
+5. Tests: recommend local test tooling; if no tests exist, ask whether to add a minimal runner proof, no test files, or real starter tests.
+6. Existing build checks: only discuss if the repo already has a meaningful build/package/compile command; no fake builds.
+7. Security scanners: ask when warranted. Secret scanning is conditional opt-in for real credential risk. Dependency audits are opt-in when package-manager/lockfile evidence supports them. Call out network or telemetry.
+8. Git hooks: recommend strict fast pre-commit hooks and keep slower checks separate unless the user accepts slow hooks.
+9. Extra static-style checks: ask before including every extra, even when evidence suggests one.
+10. Repo docs: recommend `docs/agents/coding-quality-checks.md` plus optional `AGENTS.md` agent block.
+11. CI: if CI exists, ask whether to update it; default to no CI edits unless the user opts in.
+
+For command naming, preserve repo lingo. If Sandcastle docs name exact commands like `npm run typecheck` and `npm run test`, preserve them as agent-facing commands. If no local lingo exists, ask before creating a fallback aggregate such as `check`.
+
+## 3. Confirm
+
+Before installing or editing, show this exact confirmation shape:
+
+```text
+I will set up local Coding Quality Checks with:
+Package manager: <pm or none>
+Tools/dev dependencies: <list>
+Files expected to change: <list>
+Scripts/commands added or changed: <list>
+Git hooks: <exact behavior or none>
+Security scanners: <local/offline/networked/none>
+CI edits: <yes/no>
+Auto-format/autofix source writes: none unless separately confirmed
+
+Proceed with these exact changes?
+```
+
+Stop if target files are dirty and conflict with planned edits, package-manager detection is ambiguous, a scanner violates the chosen local-only meaning, or an existing config cannot be merged safely.
+
+## 4. Implement
+
+After confirmation, make minimal, idempotent edits. Prefer existing config files and script conventions. Follow existing version pinning style. Never delete or replace existing configs unless explicitly approved.
+
+Allowed after confirmation: package/tool configs, dev dependencies and lockfile updates, agreed scripts, agreed hook-manager config, `docs/agents/coding-quality-checks.md`, and optional agent instruction block.
+
+Forbidden without separate confirmation: repo-wide formatting, lint autofix, generated-code rewrites, runtime dependency changes, CI edits unless opted in, and Beads mutations.
+
+## 5. Document
+
+Write `docs/agents/coding-quality-checks.md` with exact commands, what each command proves, known brownfield failures, and what agents should run before commits. If updating `AGENTS.md`, keep the block short and point to the doc.

package/skills/engineering/tdd/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/skills/engineering/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/skills/engineering/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup