AI Agent Guidelines - superpowers-plus

Generated by: 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/

⚠️ 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

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:

  node ~/.codex/superpowers-augment/superpowers-augment.js bootstrap

This loads available skills into the environment. To load a specific skill manually (plus only):

node ~/.codex/superpowers-augment/superpowers-augment.js use-skill SKILL_NAME

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-dev-*); 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 unsets 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

Load .ai-guidance/todo-tools.md when using TODO tools.

Skill File Structure

Load .ai-guidance/skill-file-structure.md before editing skills.

🔴 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):

Baseline capture (non-regression check):

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