dshakes/compass

# Bootstrap agent config for a repository

Produce a `CLAUDE.md` and a symlinked/parallel `AGENTS.md` that are *grounded in
the real repo*, not generic boilerplate. A good config is the single highest-ROI
thing for agent productivity in a codebase — it pays for itself on the first task.

## Steps

1. **Detect the stack.** Run the helper to get a fast inventory:
   ```
   bash "${CLAUDE_SKILL_DIR}/detect-stack.sh" .
   ```
   It reports languages, package managers, build/test/lint commands, monorepo
   layout, and whether ADRs/CI exist.

# Harden — security sweep in five ordered steps

Run each command in sequence. Stop on a non-zero exit and fix the finding before
proceeding. All five must pass before the branch is considered hardened.

## Steps

### 1 · Secrets — `compass scan --staged`
Scan the staged diff for secrets at the commit boundary.

```
compass scan --staged
```

# Morning triage — the loop's discovery move

A loop has five moves: **discovery → handoff → verification → persistence → scheduling**
(see [docs/20-loops.md](../../docs/20-loops.md)). This skill is **discovery** — the move that
finds the work. Skip it and you have the "blind loop": automated *doing* but a human still
spends every morning deciding *what* to do. Discovery sets the ceiling on the whole loop —
surface work of no value and the other four moves serve nothing.

The point is to let the loop find its own work, then stop exactly where a human should decide.

## Read — the discovery inputs

Look at what changed since the last run (use `gh` and `git`; read-only):

# PR shepherd — the loop's handoff + verification moves, applied to PRs

A loop has five moves: **discovery → handoff → verification → persistence → scheduling**
(see [docs/20-loops.md](../../docs/20-loops.md)). `morning-triage` is discovery — it finds
work. This skill is what happens *after* a PR exists: no PR sits red waiting for a human to
diagnose a check that a machine can read. It shepherds each open PR to exactly one of three
outcomes: **merged** (gate satisfied + authority granted), **ready-to-merge** (reported), or
**inbox** (needs a human, with the diagnosis already written).

## Enumerate

`gh pr list --state open --json number,title,author,isDraft,isCrossRepository,headRefName,statusCheckRollup`

Skip drafts. **Fail closed on forks**: if `isCrossRepository` is true — or the field is

# Route work to the right specialist

The cloud SDLC classifies each PR (`sdlc-classify.yml`) and runs domain-specific
reviewers. This skill does the same locally: classify, then dispatch.

## Steps
1. **Classify** the task/diff into ONE primary domain (default `core` if mixed):
   | Domain | Signals | Route to |
   |---|---|---|
   | `ui` | frontend, styling, components, UX | `code-reviewer` + a design/a11y pass |
   | `api` | public API/SDK, contracts, schemas | `code-reviewer` + contract/back-compat focus |
   | `infra` | CI, deploy, IaC, migrations | `k8s-operator` / careful review of blast radius |
   | `docs` | docs/markdown only | `docs-writer` |
   | `core` | library / business logic | `code-reviewer` (+ `security-auditor` if it touches authz/inputs) |

# Systematic debugging

Fix the cause, not the symptom — and prove the cause before you touch code.

## The method

1. **Reproduce** — get a reliable, minimal repro (a failing test is ideal). No repro → no fix.
2. **Hypothesize** — one specific, falsifiable guess about the cause ("X is null because Y").
3. **Prove it** — instrument/log/inspect to confirm the hypothesis *before* editing. If the
   evidence contradicts it, form a new hypothesis. Don't guess-and-change.
4. **Minimal fix** — change the smallest thing that addresses the proven root cause.
5. **Verify** — re-run the repro; it passes. Run the surrounding tests; nothing regressed.
   (See `verification-before-completion`.)
6. **Guard** — add/extend a test that would have caught it, so it can't silently return.

# Using compass

compass is already wired into this environment. Before you work ad-hoc, check whether a
compass capability does it better — and safer.

## What you have (reach for these)

| Need | Reach for | How |
|---|---|---|
| Write/repair a repo's `CLAUDE.md`/`AGENTS.md` | **bootstrap-agent-config** skill | grounded in the actual repo |
| Security pass before shipping | **harden** skill · `compass scan` · `compass redteam` | secrets · injection · supply-chain |
| Pick the cheapest correct model | `compass route "<task>"` | haiku/sonnet/opus, eval-scored |
| Review/implement with the right specialist | **route** skill · `/review` · `/team-review` | domain-routed, not generic |
| Everyday commands | `/tdd /spec /ship /pr /adr /triage /scaffold /cost /onboard /sdlc` | saved workflows |

# Verification before completion

The highest-leverage habit and a compass hard line: **a claim is not proof.**

## The iron rule

I do not say "done", "fixed", "verified", or "passing" unless I ran the check and saw it
pass. If I could not run it, I label the result **UNVERIFIED** and say why. This binds
delegated work too: a subagent's "verified" is a claim — **I re-run the gate** on what it
returns.

## How to verify (pick what fits the change)

- Tests for the touched code: `go test` · `cargo test` · `pytest` · `npm/pnpm test` · `npx tsc`.

# Bootstrap agent config for a repository

Produce a `CLAUDE.md` and a symlinked/parallel `AGENTS.md` that are *grounded in
the real repo*, not generic boilerplate. A good config is the single highest-ROI
thing for agent productivity in a codebase — it pays for itself on the first task.

## Steps

1. **Detect the stack.** Run the helper to get a fast inventory:
   ```
   bash "${CLAUDE_SKILL_DIR}/detect-stack.sh" .
   ```
   It reports languages, package managers, build/test/lint commands, monorepo
   layout, and whether ADRs/CI exist.

# Harden — security sweep in five ordered steps

Run each command in sequence. Stop on a non-zero exit and fix the finding before
proceeding. All five must pass before the branch is considered hardened.

## Steps

### 1 · Secrets — `compass scan --staged`
Scan the staged diff for secrets at the commit boundary.

```
compass scan --staged
```

# Morning triage — the loop's discovery move

A loop has five moves: **discovery → handoff → verification → persistence → scheduling**
(see [docs/20-loops.md](../../docs/20-loops.md)). This skill is **discovery** — the move that
finds the work. Skip it and you have the "blind loop": automated *doing* but a human still
spends every morning deciding *what* to do. Discovery sets the ceiling on the whole loop —
surface work of no value and the other four moves serve nothing.

The point is to let the loop find its own work, then stop exactly where a human should decide.

## Read — the discovery inputs

Look at what changed since the last run (use `gh` and `git`; read-only):

# PR shepherd — the loop's handoff + verification moves, applied to PRs

A loop has five moves: **discovery → handoff → verification → persistence → scheduling**
(see [docs/20-loops.md](../../docs/20-loops.md)). `morning-triage` is discovery — it finds
work. This skill is what happens *after* a PR exists: no PR sits red waiting for a human to
diagnose a check that a machine can read. It shepherds each open PR to exactly one of three
outcomes: **merged** (gate satisfied + authority granted), **ready-to-merge** (reported), or
**inbox** (needs a human, with the diagnosis already written).

## Enumerate

`gh pr list --state open --json number,title,author,isDraft,isCrossRepository,headRefName,statusCheckRollup`

Skip drafts. **Fail closed on forks**: if `isCrossRepository` is true — or the field is

# Route work to the right specialist

The cloud SDLC classifies each PR (`sdlc-classify.yml`) and runs domain-specific
reviewers. This skill does the same locally: classify, then dispatch.

## Steps
1. **Classify** the task/diff into ONE primary domain (default `core` if mixed):
   | Domain | Signals | Route to |
   |---|---|---|
   | `ui` | frontend, styling, components, UX | `code-reviewer` + a design/a11y pass |
   | `api` | public API/SDK, contracts, schemas | `code-reviewer` + contract/back-compat focus |
   | `infra` | CI, deploy, IaC, migrations | `k8s-operator` / careful review of blast radius |
   | `docs` | docs/markdown only | `docs-writer` |
   | `core` | library / business logic | `code-reviewer` (+ `security-auditor` if it touches authz/inputs) |

# Systematic debugging

Fix the cause, not the symptom — and prove the cause before you touch code.

## The method

1. **Reproduce** — get a reliable, minimal repro (a failing test is ideal). No repro → no fix.
2. **Hypothesize** — one specific, falsifiable guess about the cause ("X is null because Y").
3. **Prove it** — instrument/log/inspect to confirm the hypothesis *before* editing. If the
   evidence contradicts it, form a new hypothesis. Don't guess-and-change.
4. **Minimal fix** — change the smallest thing that addresses the proven root cause.
5. **Verify** — re-run the repro; it passes. Run the surrounding tests; nothing regressed.
   (See `verification-before-completion`.)
6. **Guard** — add/extend a test that would have caught it, so it can't silently return.

# Using compass

compass is already wired into this environment. Before you work ad-hoc, check whether a
compass capability does it better — and safer.

## What you have (reach for these)

| Need | Reach for | How |
|---|---|---|
| Write/repair a repo's `CLAUDE.md`/`AGENTS.md` | **bootstrap-agent-config** skill | grounded in the actual repo |
| Security pass before shipping | **harden** skill · `compass scan` · `compass redteam` | secrets · injection · supply-chain |
| Pick the cheapest correct model | `compass route "<task>"` | haiku/sonnet/opus, eval-scored |
| Review/implement with the right specialist | **route** skill · `/review` · `/team-review` | domain-routed, not generic |
| Everyday commands | `/tdd /spec /ship /pr /adr /triage /scaffold /cost /onboard /sdlc` | saved workflows |

# Verification before completion

The highest-leverage habit and a compass hard line: **a claim is not proof.**

## The iron rule

I do not say "done", "fixed", "verified", or "passing" unless I ran the check and saw it
pass. If I could not run it, I label the result **UNVERIFIED** and say why. This binds
delegated work too: a subagent's "verified" is a claim — **I re-run the gate** on what it
returns.

## How to verify (pick what fits the change)

- Tests for the touched code: `go test` · `cargo test` · `pytest` · `npm/pnpm test` · `npx tsc`.