AGENTS.md git:20261006.5f5e13fA

Immutable. This exact content never changes and is served at /api/v1/blob/1fc20e9800ae6489.

# AI Agent Guidelines - superpowers-plus

> **Generated by**: [golden-agents](https://github.com/bordenet/golden-agents) v1.4.0 (progressive)
> **Last Updated**: 2026-04-12
> **Languages**: shell,javascript
> **Type**: cli-tools

Minimal core with on-demand module loading. Templates at: `$HOME/.golden-agents/templates/`
<!-- GOLDEN:self-manage:start -->
## ⚠️ Before ANY Task
1. Load `.ai-guidance/invariants.md` — contains critical rules
2. After editing ANY guidance file, check: `wc -l AGENTS.md .ai-guidance/*.md 2>/dev/null`
   - `AGENTS.md` >150 lines → refactor into `.ai-guidance/`
   - Any `.ai-guidance/*.md` >250 lines → split into sub-directory
<!-- GOLDEN:self-manage:end -->
<!-- GOLDEN:framework:start -->

---

## Quality Gates (MANDATORY)

Before ANY commit:
1. **Lint**: `shellcheck *.sh`
2. **Build**: `bash -n *.sh`
3. **Test**: `bats test/`

**Order matters.** Lint → Build → Test. Never skip steps.

---

## Communication Rules

- **No flattery** - Skip "Great question!" or "Excellent point!"
- **No hype** - Avoid "revolutionary", "game-changing", "seamless"
- **Evidence-based** - Cite sources or qualify as opinion
- **Direct** - State facts without embellishment

**Banned phrases**: production-grade, world-class, leverage, utilize, incredibly, extremely, Happy to help!

---

## 🚨 Progressive Module Loading

**STOP and load the relevant module BEFORE these actions:**

### Language Modules (🔴 Required)
- 🔴 **BEFORE writing ANY `.sh` file or bash code block**: Read `$HOME/.golden-agents/templates/languages/shell.md`
- 🔴 **BEFORE writing ANY `.js`, `.ts`, `.jsx`, `.tsx` file**: Read `$HOME/.golden-agents/templates/languages/javascript.md`

### Workflow Modules (🔴 Required)
- 🔴 **BEFORE any commit, PR, push, or merge**: Read `$HOME/.golden-agents/templates/workflows/security.md`
- 🔴 **WHEN tests fail OR after 2+ failed fix attempts**: Read `$HOME/.golden-agents/templates/workflows/testing.md`
- 🔴 **WHEN build fails OR lint errors appear**: Read `$HOME/.golden-agents/templates/workflows/build-hygiene.md`
- 🟡 **BEFORE deploying to any environment**: Read `$HOME/.golden-agents/templates/workflows/deployment.md`
- 🟡 **WHEN conversation exceeds 50 exchanges**: Read `$HOME/.golden-agents/templates/workflows/context-management.md`

### Project type guidance:
- Read `$HOME/.golden-agents/templates/project-types/cli-tools.md`

### Optional: Superpowers integration

Two parallel, mutually exclusive skill ecosystems exist. At the **START of every conversation**, detect which THIS machine uses and bootstrap accordingly:

- **superpowers-plus**: Run the js bootstrap:
  ```bash
  node ~/.codex/superpowers-augment/superpowers-augment.js bootstrap
  ```

This loads available skills into the environment. To load a specific skill manually (plus only):
```bash
node ~/.codex/superpowers-augment/superpowers-augment.js use-skill SKILL_NAME
```

<!-- GOLDEN:framework:end -->
---

## Project-Specific Guidelines

### 🔴 Dev Repo Path
ALL work MUST happen in this repository (the directory containing this AGENTS.md). Never edit installed copies (`~/.codex/`). If unsure of the path, run `git rev-parse --show-toplevel`.

### Quality Gates (sp+-specific)
- **Full test surface**: `./tools/test-all.sh` runs shellcheck + harsh-review + bats + node test/*. `tools/ci-bats-discovery.sh` is CI's suite discovery, policy lint, and runner. The framework block above lists `bats test/` for parity with golden-agents conventions, but the actual suite is larger. Use `--fast` for a node+bats-only inner loop; CI must run the full suite.
- Run `./tools/harsh-review.sh` (subset of `test-all.sh`) before any commit; install hooks: `./tools/install-hooks.sh`
- `commit-msg` hook: auto-converts smart quotes, em dashes, arrows, etc. to ASCII; rejects any remaining non-ASCII. If a commit is rejected, edit the message to use ASCII equivalents. It also warns (never blocks) when a message line narrates the review process, such as a tool name next to passed, round or findings (`tools/commit-msg-jargon.py`). Requires `python3` in PATH (hook exits 1 with an explicit error if missing).
- Review gates are enforced at **pre-push**: code → `code-review-battery`, design docs → PHR, `skills/*.md` and AGENTS-family files → `llm-skill-review`. A sentinel covers the reviewed *content*: it stays valid across amends/rebases until a file in that gate's scope changes (`tools/lib/sentinel-scope.sh`). The pre-commit sentinel check is off for this repo (`REQUIRE_CODE_REVIEW_SENTINEL=false` in `.agent-gates`). The PHR-trigger file list comes from `tools/md-files-changed.sh` — the single source of truth for the regex and exclusions.
- **Sentinel**: `tools/run-battery.sh [--verdict PASS|PASS_WITH_NITS] [--staged]` is the ONLY permitted way to write `.code-review-cleared`. Writing it directly is a critical policy violation. With `--staged`, the sentinel records `tree:<sha>` and the post-commit hook promotes it to the new HEAD SHA, eliminating the stage→battery→commit→battery double-run. The post-commit hook also carries `.code-review-cleared`, `.phr-cleared`, and `.llm-skill-review-cleared` forward across any commit whose tree is provably unchanged from a passing sentinel's recorded SHA — this covers a clean promotion merge (e.g. `dev → main`, tree-identical to the branch merged in) so promoting already-reviewed content doesn't force a fresh review just because the merge commit has a new SHA.
- **Pre-push runs `test-all.sh --fast` automatically** (Gate 1 of 8). Before spending that runtime, use read-only `tools/push-readiness.sh [--json]` to list sentinel blockers without consuming them; pass `--destination <branch>` for a non-same-name refspec such as `HEAD:main`. Gate 6 requires `.llm-skill-review-cleared` for `skills/*.md` changes; it supersedes (not supplements) the code-review and PHR gates for that file class specifically. Gate 7 is a per-commit LOC advisory (warn-only by default; see `tools/pre-push-loc-gate.sh`'s own header for `LOC_GATE_MODE=block` opt-in).
- **Gate 8** blocks a branch missing commits its target already has. Target is `dev`; `main` for `dev`, `promote/*` and sync branches (`sync/*`, `*/sync-*`); `main` itself has no target; `hotfix/`, `release/`, `backport/`, `tagged-release/` are exempt. It fetches first, fails open offline or on a shallow clone, and prints the command to catch up: `git merge` for a `main` target, `git rebase` otherwise (`DIVERGENCE_GATE=off` skips it).
- **Before dispatching any review sub-agent, run `tools/review.sh route <path> [<path> ...]` first** — it wraps `tools/which-gate.sh` and prints one block per artifact class (skill name, sentinel file, and runner), with a separate block for each gate when paths span multiple classes. Never pick the review dispatcher from memory — the three review skills' own "Wrong skill?" prose banners only fire *after* the wrong skill is loaded, which is after the dispatch decision was already wrong; `tools/review.sh` fires before any skill loads. On non-zero exit (router missing, extraction failure, or unmatched artifact), stop and consult the gate bullets above rather than picking from memory.
- **Writing a bats fixture that does its own `git init`/`git -C <tmpdir>` work?** `test/setup_suite.bash` (bats-core auto-loads it once, before any test forks) already centrally `unset`s `GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX` for every `bats test/` invocation — no per-file repetition needed. It exists because a leaked `GIT_DIR` (from an unrelated git experiment in the same shell) once silently redirected a fixture's own `git -C <tmpdir> init/commit` onto the real repo, corrupting `.git/config`. See `test/setup_suite.bash` for the full incident writeup.
- **Writing a NEW hook or gate that invokes nested git directly (not a bats fixture)?** `tools/pre-push`'s own `unset` of the same four vars (near its top) exists for a separate, still-live vector: git auto-sets `GIT_DIR` for hook subprocesses under a linked worktree, which silently overrides `-C`/cwd discovery for any nested git command the hook runs — sanitize the same four vars before your own nested git calls.
- **Fixture-only fixup after a full review already passed?** Try `tools/try-sentinel-fast-forward.sh --code-review` (or `--phr`) before re-running the full battery/PHR. It only succeeds when every changed file is a registered mechanically-regenerated fixture (`tools/lib/fast-forward-registry.sh`) AND each file is proven byte-for-byte reproducible by its own generator — the tool deletes each matched file, re-runs its generator, and requires the exact file to reappear unchanged, so a registry entry that doesn't actually cover a given file is caught rather than silently trusted. Falls back to "run the full review" on any failure (exit 1 for a proven mismatch or non-ancestor SHA; exit 2 for a usage/precondition error like a dirty tree or missing sentinel).
- ❌ NEVER emit "ready to push", "let me commit", "about to merge", "committing", or "pushing to" without first scanning for required-skill triggers

### TODO Tools
- `todo-crud.sh` — task CRUD (handles preflight, locking, backup)
- `todo-preflight.sh --create-if-missing` — init only
- `todo-maintenance.sh` — housekeeping

Full protocol: `use-skill todo-management`

### Skill File Structure
```
skills/{domain}/{skill-name}/
├── skill.md        # REQUIRED: YAML frontmatter + triggers
├── examples.md     # OPTIONAL
└── reference.md    # OPTIONAL
```

### 🔴 Git Workflow — GitHub First, Always

**Remote in this clone:**
- `origin` = GitHub (bordenet/superpowers-plus) — **sole source of truth**

**ALL changes go to GitHub (`origin`) via PR.**

2-Tier promotion (all on GitHub `origin`):
1. Feature branch → push to `origin`, open PR into `origin/dev`
2. `dev → main`: explicit human instruction + batch review approval

There is no `staging` branch (retired October 2026; it only passed content through to `main`).

A promotion PR carries content already reviewed on its source branch — it is
not new feature work. Once the human instruction and batch review approval
are given, open the PR and merge on green required checks. Do not re-run brainstorming, debate, or the full feature-development
skill chain against a promotion diff solely because a skill-router match
fired; those are for design decisions, and a promotion merge has none.

After any release to `main`, open a sync PR (merge commit) to bring promotion history back to `dev`:
`git checkout -b chore/sync-dev-with-main origin/main && git push origin chore/sync-dev-with-main`
Then open PR `chore/sync-dev-with-main → dev`. Squash promotions leave SHAs on `main` that never reach `dev` without this.

- ❌ NEVER commit directly to `dev` or `main`
- ❌ NEVER branch features from `main`
- Emergency hotfixes: branch `hotfix/<name>` from `main`, PR into `main`, cherry-pick back to `dev`
- Authorization expires after context compaction or sub-agent handoff — human must restate
- Known issue — promotion PR stuck on `BEHIND` despite all checks green: see `.ai-guidance/promotion-strict-behind-runbook.md` for confirmed non-fixes and the mitigation (the underlying GitHub-side root cause is itself unconfirmed — the runbook's own "Known gaps" section says so). The mitigation temporarily disables the target branch's required-status-checks `strict` flag (the 4 required checks themselves stay enforced) — that is its own sensitive action and needs its own fresh authorization, never bundled with the promotion approval itself. Enforced by `tools/claude-hooks/pre-tool-use-red-autonomy.sh`, which blocks `tools/promotion-strict-toggle.sh disable` until the current session contains the phrase "approve strict-disable" (a prior push/promotion approval does not count).

## Claude Code guardrails

Claude Code lifecycle hooks (red-autonomy, skill router, context ferry, git identity, and others) installed into `~/.claude/hooks/` and registered in `~/.claude/settings.json` by `setup/install-claude-guardrails.sh`; for self-debug guidance use the `systematic-debugging` skill (`/sp-systematic-debugging`). `install.sh` reports hook parity (installed vs. shipped) after every run; `uninstall.sh` removes the hooks and their registrations.

**Environment variables** (add to your local `~/.codex/.env`):

| Variable | Default | Purpose |
|----------|---------|---------|
| `SUPERPOWERS_CLAUDE_GUARDRAILS` | `1` | Kill switch — installs the guardrail hooks; set `0` to opt out |
| `CLAUDE_HOOKS_BYPASS` | `0` | Per-hook bypass for ops escape hatch (PR-1+) |
| `AUGMENT_PARITY_OFF` | `0` | Parity-mode toggle for cross-tool validation (PR-2+) |

**Baseline capture** (non-regression check):
```bash
bash scripts/capture-augment-baseline.sh           # overwrite baseline
bash scripts/capture-augment-baseline.sh --check   # detect drift since baseline
```
Baseline file: `tests/fixtures/augment-baseline-pre-claude-guardrails.json`