agent-deck-contributor

# agent-deck contributor

This skill is the contributor-side mirror of agent-deck's PR gate. The repo's intake
check (`.github/workflows/pr-intake.yml`), its field contract (`.github/INTAKE.md`),
and the maintainer's four-lens review machine are one spec read from the receiving
side; this skill is the same spec read from the sending side. An agent that follows
it passes intake on the first try and scores well on all four review lenses:
**correctness, security, fit, and intent**.

One principle before anything else: every field the gate requires is trivial for a
legitimate human+agent pair and impossible for intent-less slop. The one thing that
cannot be faked is a real human's ask. So the very first thing you capture, before
any code, is **what your human actually asked for, in their words**. Keep the quote.
It goes in the PR body verbatim.

## Script path resolution

This skill ships `scripts/self-check.sh`. Resolve it from the skill's own base
directory (shown when the skill loads), not the project root:

```bash
SKILL_DIR="/path/shown/in/base-directory-line"   # e.g. <repo>/.github/skills/agent-deck-contributor
"$SKILL_DIR/scripts/self-check.sh" pr-body.md
```

When working inside an agent-deck clone the path is
`.github/skills/agent-deck-contributor/scripts/self-check.sh`.

## Phase 1 — Claim and understand the issue

1. **Capture the human ask first.** Write down, verbatim, what your human asked for
   (one sentence is enough). If you are working from an issue with no direct human
   instruction, quote the issue author's problem statement instead. This becomes the
   `## What actually bothered you` section. Intake fails a PR whose intent section is
   empty; it never fails an honest one-liner.
2. **Reproduce before you touch code.** For bugs: build agent-deck, reproduce the
   reported behavior, and save the capture (terminal output, log lines). The review
   machine's intent lens asks "did the submitter supply real observed behavior, not
   just claims?" — your reproduction is that evidence. If you cannot reproduce
   reliably, say so honestly: "can't reproduce reliably, happens when ..." passes;
   silence does not.
3. **Comment on the issue to claim it** before starting, so the maintainer's fleet
   can tell you if someone (human or agent) is already on it.
4. **Check scope before committing effort:**
   - Features go to a Discussion first; feature PRs that arrive as surprises take
     longer, not shorter.
   - agent-deck holds a lean-scope line: no net-new tool adapters or bolt-on UIs
     without demonstrated demand. If your idea adds a new integration surface, open
     a Discussion and get a yes before writing it.
   - Anticipated diff over ~3000 added lines? Link an issue or Discussion agreeing
     the shape first, or the gate flags it `needs-discussion`.
   - You may have at most 5 open PRs on the repo at a time.
   - Security issues go through the private advisory route in `SECURITY.md`, never
     a public issue or PR.

## Phase 2 — Implement to the bar

1. **One problem per PR, scoped diff.** No unrelated churn, no drive-by refactors,
   no formatting sweeps of untouched files. The fit lens flags diffs over ~400
   changed lines as oversized; if your change is genuinely bigger, say in the PR
   body what could split out and why it didn't.
2. **Match the codebase style.** Read the surrounding package before writing. Go
   code: standard library first, existing helpers over new ones, table-driven tests
   like the neighbors have.
3. **Write a test that FAILS without your change.** This is the centerpiece of the
   correctness lens: the reviewer reverts your non-test hunks and re-runs your
   tests — a test that still passes proves nothing. Write the test first, watch it
   fail, then make it pass. `scripts/self-check.sh` automates this revert-check
   locally.
4. **Every changed hunk should be exercised by some test.** The correctness lens
   spot-checks changed-lines coverage and names untested hunks as flags.
5. **Run the exact CI sandbox invocation.** agent-deck tests must never run against
   a real home directory (they can destroy live user data), and CI runs them
   sandboxed. Use precisely:

   ```bash
   HOME=$(mktemp -d) XDG_CONFIG_HOME= XDG_DATA_HOME= XDG_CACHE_HOME= go test ./...
   ```

6. **Format and vet before every push:**

   ```bash
   gofmt -w $(git diff --name-only origin/main -- '*.go')
   go vet ./...
   ```

   Lint CI treats formatting as a failure; the 2-second local pass saves a CI
   round-trip.
7. **Never touch `CHANGELOG.md`** — entries are added at landing time.
8. **Hot paths need timing evidence.** If you touch `list`, `status`,
   `session output`, startup, or the tmux layer, include simple before/after timing
   (even `time agent-deck list` runs) in the Evidence section.
9. **Avoid the tripwires** (details in `references/security-self-scan.md`):
   - New or bumped dependencies from a community PR are an automatic
     extra-scrutiny stop. If the fix truly needs a new module, justify it in the PR
     body (why this module, why it's canonical, where it's used) and expect a
     human gate. Never add a `replace` directive or a `GOPROXY` override.
   - Anything under `.github/` never auto-merges; it always waits for the
     maintainer personally. Keep workflow changes out of unrelated PRs.
   - No `curl | bash`, no downloaded-and-executed tooling, no new outbound network
     calls in production paths, no exec of shell-interpolated strings, no
     world-writable file modes, no `InsecureSkipVerify`.

## Phase 3 — Self-verify against the gate BEFORE opening

Draft your PR body into a file (start from `references/pr-body-template.md`), then
run the pre-open gate from the repo root:

```bash
.github/skills/agent-deck-contributor/scripts/self-check.sh pr-body.md
```

It mirrors, check for check, what the repo-side gate and review machine will do:
gofmt/vet/build, sandboxed tests, the revert-check, diff-size and forbidden-path
checks, the hidd