bigpowers 2.72.1 → 2.73.1

package/scripts/targets.yaml

@@ -0,0 +1,202 @@
+# story: e37s05
+registry_version: "1"
+generated_by: bigpowers
+
+targets:
+  - id: cursor
+    name: Cursor
+    tier: default_on
+    skill:
+      adapter: cursor
+      output: .cursor/rules
+    context:
+      adapter: cursor
+      mode: symlink
+      file: CLAUDE.md
+    contracts:
+      - cursor_rules_nonempty
+      - symlink_claude_md
+
+  - id: gemini
+    name: Gemini CLI
+    tier: default_on
+    skill:
+      adapter: gemini
+      output: .gemini/extensions/bigpowers
+    context:
+      adapter: gemini
+      mode: symlink
+      file: GEMINI.md
+    contracts:
+      - gemini_ext_exists
+
+  - id: pi
+    name: pi Agent
+    tier: default_on
+    skill:
+      adapter: pi
+      output: .pi/skills
+    context:
+      adapter: pi
+      mode: symlink
+      file: CLAUDE.md
+    contracts:
+      - pi_skills_nonempty
+
+  - id: cline
+    name: Cline
+    tier: default_on
+    skill: null
+    context:
+      adapter: cline
+      mode: native
+    contracts:
+      - agents_md_exists
+
+  - id: aider
+    name: Aider
+    tier: opt_in
+    skill: null
+    context:
+      adapter: aider
+      mode: config-bridge
+      bridge_file: .aider.conf.yml
+      bridge_key: read
+    contracts:
+      - aider_bridge
+
+  # Wave A (e37s09) — Goose native AGENTS.md; agy proprietary beta
+  - id: goose
+    name: Goose (Block OSS)
+    tier: default_on
+    skill: null
+    context:
+      adapter: goose
+      mode: native
+    contracts:
+      - agents_md_exists
+
+  - id: agy
+    name: Antigravity agy (proprietary beta)
+    tier: opt_in
+    skill: null
+    context:
+      adapter: agy
+      mode: symlink
+      file: CLAUDE.md
+    contracts:
+      - symlink_claude_md
+
+  # Wave B (e37s10) — skills-dir adapters
+  - id: zed
+    name: Zed
+    tier: opt_in
+    skill:
+      adapter: zed
+      output: ~/.config/zed/assistant
+    context:
+      adapter: zed
+      mode: copy
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists
+
+  - id: omp
+    name: Open Multi-Process
+    tier: opt_in
+    skill:
+      adapter: omp
+      output: .omp/skills
+    context:
+      adapter: omp
+      mode: symlink
+      file: CLAUDE.md
+    contracts:
+      - symlink_claude_md
+
+  - id: hermes
+    name: Hermes Agent
+    tier: opt_in
+    skill:
+      adapter: hermes
+      output: .hermes/skills
+    context:
+      adapter: hermes
+      mode: config-bridge
+      bridge_file: .hermes/config.yaml
+      bridge_key: instructions
+    contracts:
+      - agents_md_exists
+
+  # Wave C (e37s11)
+  - id: qwen
+    name: Qwen (Alibaba)
+    tier: opt_in
+    skill: null
+    context:
+      adapter: qwen
+      mode: symlink
+      file: QWEN.md
+    contracts:
+      - agents_md_exists
+
+  - id: kilocode
+    name: Kilocode
+    tier: opt_in
+    skill:
+      adapter: kilocode
+      output: .kilocode/rules
+    context:
+      adapter: kilocode
+      mode: copy
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists
+
+  # Wave D (e37s12)
+  - id: continue
+    name: Continue
+    tier: opt_in
+    skill:
+      adapter: continue
+      output: .continue/rules
+    context:
+      adapter: continue
+      mode: copy
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists
+
+  # Wave E (e37s13) — optional low-priority
+  - id: iflow
+    name: iFlow
+    tier: optional
+    skill: null
+    context:
+      adapter: iflow
+      mode: symlink
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists
+
+  - id: vibe
+    name: Vibe
+    tier: optional
+    skill: null
+    context:
+      adapter: vibe
+      mode: symlink
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists
+
+  - id: shai
+    name: Shai
+    tier: optional
+    skill: null
+    context:
+      adapter: shai
+      mode: symlink
+      file: AGENTS.md
+    contracts:
+      - agents_md_exists

package/scripts/test-adapters.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# story: e37s05
+# scenario: SC-e37s05-P1-02
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGETS_FILE="$SCRIPT_DIR/targets.yaml"
+DRY_RUN=0
+FILTER=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    -*) echo "test-adapters: unknown flag $arg" >&2; exit 2 ;;
+    *) FILTER="$arg" ;;
+  esac
+done
+
+command -v yq >/dev/null || { echo "test-adapters: yq required" >&2; exit 1; }
+bash "$SCRIPT_DIR/validate-targets-yaml.sh" >/dev/null
+
+PASS=0
+FAIL=0
+TMPDIR=""
+
+cleanup() { [[ -n "$TMPDIR" && -d "$TMPDIR" ]] && rm -rf "$TMPDIR"; }
+trap cleanup EXIT
+
+pass() { echo "  PASS $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL $1"; FAIL=$((FAIL + 1)); }
+
+test_adapter() {
+  local id="$1"
+  local adapter_file="$SCRIPT_DIR/adapters/${id}.sh"
+
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    echo "would test: $id"
+    return 0
+  fi
+
+  [[ -f "$adapter_file" ]] || { fail "$id: adapter missing"; return; }
+  pass "$id: exists"
+
+  # shellcheck source=/dev/null
+  source "$adapter_file" 2>/dev/null && pass "$id: sourceable" || { fail "$id: source error"; return; }
+
+  local has_skill has_context mode
+  has_skill=$(yq -r ".targets[] | select(.id==\"$id\") | .skill != null" "$TARGETS_FILE")
+  has_context=$(yq -r ".targets[] | select(.id==\"$id\") | .context != null" "$TARGETS_FILE")
+  mode=$(yq -r ".targets[] | select(.id==\"$id\") | .context.mode // \"\"" "$TARGETS_FILE")
+
+  if [[ "$has_skill" == "true" ]]; then
+    declare -f render_skill >/dev/null 2>&1 && pass "$id: render_skill defined" || fail "$id: render_skill missing"
+  fi
+
+  if [[ "$has_context" == "true" && "$mode" != "native" ]]; then
+    declare -f wire_context >/dev/null 2>&1 && pass "$id: wire_context defined" || fail "$id: wire_context missing"
+
+    TMPDIR=$(mktemp -d)
+    cp "$SCRIPT_DIR/../docs/templates/AGENTS.md" "$TMPDIR/AGENTS.md" 2>/dev/null || echo "# test" > "$TMPDIR/AGENTS.md"
+    (
+      cd "$TMPDIR"
+      # shellcheck source=/dev/null
+      source "$adapter_file"
+      wire_context 2>/dev/null || true
+      wire_context 2>/dev/null && pass "$id: idempotent wire_context" || fail "$id: wire_context failed"
+    )
+  fi
+}
+
+if [[ -n "$FILTER" ]]; then
+  test_adapter "$FILTER"
+else
+  while IFS= read -r adapter; do
+    [[ -n "$adapter" ]] && test_adapter "$adapter"
+  done < <(yq -r '.targets[] | (.skill.adapter // .context.adapter)' "$TARGETS_FILE" | sort -u)
+fi
+
+echo "test-adapters: $PASS passed, $FAIL failed"
+[[ "$FAIL" -eq 0 ]] || exit 1

package/scripts/test-trace-strict.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# test-trace-strict.sh — strict mode must not block unimplemented P0 stories
+#
+# Covers BUG-2026-07-06T205700:
+#   - todo/planned/backlog P0 stories with 0 links do not fail --strict
+#   - done P0 stories with 0 links still fail --strict
+#
+# Usage: bash scripts/test-trace-strict.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+TRACE_ENGINE="$REPO_ROOT/scripts/lib/trace-stories.py"
+FAILURES=0
+
+pass() { echo -e "${GREEN}PASS${NC} $1"; }
+fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+
+run_strict() {
+  local root="$1"
+  local matrix_json
+  local trace_md
+  local okf_dir
+  matrix_json=$(mktemp)
+  trace_md=$(mktemp)
+  okf_dir=$(mktemp -d)
+  set +e
+  local output
+  output=$($PYTHON "$TRACE_ENGINE" "$root" "$matrix_json" "$trace_md" "$okf_dir" 1 "" 2>&1)
+  local exit_code=$?
+  set -e
+  rm -f "$matrix_json" "$trace_md"
+  rm -rf "$okf_dir"
+  printf '%s\n' "$output"
+  return "$exit_code"
+}
+
+write_fixture() {
+  local root="$1"
+  local done_story="${2:-}"
+
+  mkdir -p "$root/specs/epics/e99-test"
+  cat >"$root/specs/release-plan.yaml" <<'EOF'
+release:
+  version: "1.0.0"
+  codename: "Strict Test"
+  status: "proposed"
+epics:
+  - id: e99
+    title: "Strict Test Epic"
+    wsjf: 5.0
+    bcps: 51
+    mode: capsule
+    status: proposed
+    capsule_dir: epics/e99-test
+EOF
+
+  {
+    echo "stories:"
+    for i in $(seq 1 51); do
+      sid=$(printf 'e99s%02d' "$i")
+      printf '  - id: %s\n    title: "Story %d"\n    bcp: 1\n' "$sid" "$i"
+    done
+  } >"$root/specs/epics/e99-test/epic.yaml"
+
+  {
+    echo "development_status:"
+    for i in $(seq 1 51); do
+      sid=$(printf 'e99s%02d' "$i")
+      if [[ -n "$done_story" && "$sid" == "$done_story" ]]; then
+        echo "  $sid: done"
+      else
+        echo "  $sid: todo"
+      fi
+    done
+  } >"$root/specs/execution-status.yaml"
+}
+
+echo "=== trace-strict: integration (real repo) ==="
+set +e
+bash "$REPO_ROOT/scripts/trace-stories.sh" --strict --json >/dev/null 2>&1
+repo_exit=$?
+set -e
+if [[ $repo_exit -eq 0 ]]; then
+  pass "trace-stories.sh --strict exits 0 on repo"
+else
+  fail "trace-stories.sh --strict exits $repo_exit on repo (expected 0)"
+fi
+
+echo ""
+echo "=== trace-strict: fixture — all todo P0, 0 links ==="
+FIXTURE_ROOT=$(mktemp -d)
+trap 'rm -rf "$FIXTURE_ROOT"' EXIT
+write_fixture "$FIXTURE_ROOT"
+set +e
+todo_output=$(run_strict "$FIXTURE_ROOT")
+todo_exit=$?
+set -e
+if [[ $todo_exit -eq 0 ]]; then
+  pass "strict passes when P0 stories are todo with 0 links"
+else
+  fail "strict exits $todo_exit on all-todo fixture (expected 0)"
+  echo "$todo_output"
+fi
+
+echo ""
+echo "=== trace-strict: fixture — done P0 with 0 links ==="
+write_fixture "$FIXTURE_ROOT" "e99s01"
+set +e
+done_output=$(run_strict "$FIXTURE_ROOT")
+done_exit=$?
+set -e
+if [[ $done_exit -eq 2 ]] && grep -q "P0 stories with 0% coverage" <<<"$done_output"; then
+  pass "strict fails when a done P0 story has 0 links"
+else
+  fail "strict exits $done_exit on done-dark fixture (expected 2 with P0 message)"
+  echo "$done_output"
+fi
+
+echo ""
+if [[ $FAILURES -eq 0 ]]; then
+  echo "test-trace-strict: PASS"
+  exit 0
+fi
+echo "test-trace-strict: FAIL ($FAILURES failure(s))"
+exit 1

package/scripts/validate-targets-yaml.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# story: e37s05
+# scenario: SC-e37s05-P1-01
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGETS_FILE="${1:-$SCRIPT_DIR/targets.yaml}"
+
+if ! command -v yq >/dev/null 2>&1; then
+  echo "validate-targets-yaml: yq required — brew install yq" >&2
+  exit 1
+fi
+
+[[ -f "$TARGETS_FILE" ]] || { echo "validate-targets-yaml: missing $TARGETS_FILE" >&2; exit 1; }
+
+version=$(yq -r '.registry_version // ""' "$TARGETS_FILE")
+[[ -n "$version" && "$version" != "null" ]] || { echo "validate-targets-yaml: registry_version required" >&2; exit 1; }
+
+count=$(yq '.targets | length' "$TARGETS_FILE")
+[[ "$count" -ge 5 ]] || { echo "validate-targets-yaml: need >= 5 targets, got $count" >&2; exit 1; }
+
+valid_tiers=" default_on opt_in optional "
+valid_modes=" native symlink copy config-bridge "
+
+while IFS= read -r row; do
+  id=$(echo "$row" | yq -r '.id // ""')
+  name=$(echo "$row" | yq -r '.name // ""')
+  tier=$(echo "$row" | yq -r '.tier // ""')
+  skill_null=$(echo "$row" | yq -r '.skill == null')
+  context_null=$(echo "$row" | yq -r '.context == null')
+
+  [[ -n "$id" ]] || { echo "validate-targets-yaml: target missing id" >&2; exit 1; }
+  [[ -n "$name" ]] || { echo "validate-targets-yaml: $id missing name" >&2; exit 1; }
+  [[ "$valid_tiers" == *" $tier "* ]] || { echo "validate-targets-yaml: $id invalid tier: $tier" >&2; exit 1; }
+  [[ "$skill_null" == "false" || "$context_null" == "false" ]] || {
+    echo "validate-targets-yaml: $id needs skill or context" >&2; exit 1
+  }
+
+  if [[ "$skill_null" == "false" ]]; then
+    adapter=$(echo "$row" | yq -r '.skill.adapter // ""')
+    [[ -n "$adapter" ]] || { echo "validate-targets-yaml: $id skill.adapter required" >&2; exit 1; }
+    adapter_file="$SCRIPT_DIR/adapters/${adapter}.sh"
+    [[ -f "$adapter_file" ]] || { echo "validate-targets-yaml: missing adapter $adapter_file" >&2; exit 1; }
+  fi
+
+  if [[ "$context_null" == "false" ]]; then
+    mode=$(echo "$row" | yq -r '.context.mode // ""')
+    adapter=$(echo "$row" | yq -r '.context.adapter // ""')
+    [[ "$valid_modes" == *" $mode "* ]] || { echo "validate-targets-yaml: $id invalid context.mode: $mode" >&2; exit 1; }
+    [[ -n "$adapter" ]] || { echo "validate-targets-yaml: $id context.adapter required" >&2; exit 1; }
+    adapter_file="$SCRIPT_DIR/adapters/${adapter}.sh"
+    [[ -f "$adapter_file" ]] || { echo "validate-targets-yaml: missing context adapter $adapter_file" >&2; exit 1; }
+    if [[ "$mode" == "symlink" || "$mode" == "copy" ]]; then
+      file=$(echo "$row" | yq -r '.context.file // ""')
+      [[ -n "$file" ]] || { echo "validate-targets-yaml: $id context.file required for $mode" >&2; exit 1; }
+    fi
+    if [[ "$mode" == "config-bridge" ]]; then
+      bf=$(echo "$row" | yq -r '.context.bridge_file // ""')
+      bk=$(echo "$row" | yq -r '.context.bridge_key // ""')
+      [[ -n "$bf" && -n "$bk" ]] || { echo "validate-targets-yaml: $id bridge_file/key required" >&2; exit 1; }
+    fi
+  fi
+done < <(yq -o=json '.targets[]' "$TARGETS_FILE" | jq -c '.')
+
+# Unique ids
+dup=$(yq -r '.targets[].id' "$TARGETS_FILE" | sort | uniq -d)
+[[ -z "$dup" ]] || { echo "validate-targets-yaml: duplicate ids: $dup" >&2; exit 1; }
+
+echo "validate-targets-yaml: PASS ($count targets)"

package/scripts/verify-install.sh

@@ -1,10 +1,54 @@
 #!/usr/bin/env bash
-# story: e47s04
-# verify-install.sh — manual assertion harness for install + seed wiring
+# story: e47s04 e37s02 e37s04 e37s08
+# verify-install.sh — manual assertion harness for install + seed wiring + Reach matrix
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 resolve_repo_root
 
+MATRIX_MODE=0
+FULL_MATRIX=0
+for arg in "$@"; do
+  case "$arg" in
+    --matrix) MATRIX_MODE=1 ;;
+    --full) FULL_MATRIX=1 ;;
+  esac
+done
+
+if [[ "$MATRIX_MODE" -eq 1 ]]; then
+  source "$(dirname "${BASH_SOURCE[0]}")/lib/target-contracts.sh"
+  command -v yq >/dev/null || { echo "verify-install: yq required for --matrix" >&2; exit 1; }
+  cd "$REPO_ROOT"
+  PASS=0
+  FAIL=0
+  while IFS= read -r row; do
+    id=$(echo "$row" | yq -r '.id')
+    tier=$(echo "$row" | yq -r '.tier')
+    [[ "$tier" == "optional" && "$FULL_MATRIX" -eq 0 ]] && continue
+    if [[ "$tier" == "opt_in" ]]; then
+      echo "${id}: SKIP (opt_in)"
+      continue
+    fi
+    contracts=$(echo "$row" | yq -r '.contracts // [] | .[]' 2>/dev/null || true)
+    target_pass=1
+    while IFS= read -r contract; do
+      [[ -z "$contract" ]] && continue
+      result=$(run_contract "$id" "$contract" 2>&1 | head -1)
+      echo "$result"
+      [[ "$result" == FAIL* ]] && target_pass=0
+    done <<< "$contracts"
+    if [[ "$target_pass" -eq 1 ]]; then
+      echo "${id}: PASS"
+      PASS=$((PASS + 1))
+    else
+      echo "${id}: FAIL"
+      FAIL=$((FAIL + 1))
+    fi
+  done < <(yq -o=json '.targets[]' "$REPO_ROOT/scripts/targets.yaml" | jq -c '.')
+  echo "verify-install --matrix: $PASS passed, $FAIL failed"
+  [[ "$FAIL" -eq 0 && "$PASS" -gt 0 ]] || exit 1
+  exit 0
+fi
+
 PASS=0
 FAIL=0
 TMPDIR=""
@@ -27,16 +71,45 @@ echo "$DRY_OUT" | grep -q 'Gemini CLI →' && pass "install includes Gemini CLI"
 echo "$DRY_OUT" | grep -q 'Cursor →' && pass "install includes Cursor" || fail "install missing Cursor"
 
 for tool in "Claude Code" "pi"; do
-  # Find the skills count in the tool's section (between this tool header and next section)
   section=$(echo "$DRY_OUT" | sed -n "/${tool} →/,/^$/p")
   count=$(echo "$section" | grep -o '[0-9]\+ skills installed' | grep -o '[0-9]\+' || echo "0")
   [[ "$count" -gt 0 ]] && pass "${tool}: $count skills" || fail "${tool}: 0 skills"
 done
 
+echo ""
+echo "=== AGENTS.md spine (e37s04) ==="
+[[ -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && pass "Reach template exists" || fail "Reach template missing"
+grep -q 'Preflight' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Preflight" || fail "template: missing Preflight"
+grep -qi 'cline\|aider\|opencode' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: multi-agent preamble" || fail "template: missing OSS targets"
+grep -q '## Test' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Test section" || fail "template: missing Test"
+grep -q '## Lint' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Lint section" || fail "template: missing Lint"
+grep -q '## Build' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Build section" || fail "template: missing Build"
+
+echo ""
+echo "=== Cline native AGENTS.md (e37s02) ==="
+[[ -f "$REPO_ROOT/AGENTS.md" || -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && pass "Cline: AGENTS.md present (native reader)" || fail "Cline: AGENTS.md missing"
+grep -qi 'cline' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && pass "using-bigpowers: Cline section" || fail "using-bigpowers: missing Cline"
+
+echo ""
+echo "=== Aider bridge (e37s03) ==="
+grep -qi 'aider' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "seed-conventions: Aider wiring" || fail "seed-conventions: missing Aider"
+grep -qi 'Aider-AI' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && pass "using-bigpowers: Aider-AI upstream" || fail "using-bigpowers: missing Aider-AI"
+
+echo ""
+echo "=== Optional Codex wave (e37s04) ==="
+if grep -qi 'codex' "$REPO_ROOT/skills/seed-conventions/SKILL.md" 2>/dev/null; then
+  grep -qi 'config.toml' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "Codex: REFERENCE config.toml" || fail "Codex: missing config.toml"
+  echo "$DRY_OUT" | grep -qi 'codex' && pass "Codex: install --dry-run mentions codex" || fail "Codex: install missing codex"
+else
+  pass "Codex: wave absent — assertions skipped"
+fi
+
 echo ""
 echo "=== seed-conventions local wiring ==="
 grep -qi 'local tool wiring' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: local tool wiring" || fail "SKILL.md: missing local tool wiring"
 grep -qi 'opencode.json' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: opencode.json" || fail "REFERENCE.md: missing opencode.json"
+grep -qi 'AGENTS.md' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: AGENTS.md spine" || fail "SKILL.md: missing AGENTS.md"
+grep -qi 'symlink' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: CLAUDE.md symlink" || fail "SKILL.md: missing symlink"
 grep -qi 'cursor/rules' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: Cursor symlink" || fail "REFERENCE.md: missing Cursor symlink"
 
 OPENCODE_JSON=$(sed -n '/```json/,/```/p' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" | grep -v '```' || true)

package/skills/seed-conventions/REFERENCE.md

@@ -1,12 +1,24 @@
-# story: e51s02
+# story: e51s02 e37s01 e37s03 e37s14
 # Seed Conventions — Reference Templates
 
-## Agent config template (CLAUDE.md / GEMINI.md / AGENTS.md)
+## AGENTS.md spine (Reach Template — e37s01)
+
+Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template).
+Do not invent structure ad hoc — the template includes multi-agent preamble, Preflight, Test/Lint/Build sections.
+
+When local tool wiring is opted in:
+1. Copy Reach Template → project root `AGENTS.md`, fill interview placeholders
+2. `ln -sf AGENTS.md CLAUDE.md` (or content copy on Windows when symlink fails)
+3. Write `opencode.json` with `"instructions": ["AGENTS.md"]`
+
+When user **opts out** of local tool wiring, do not emit AGENTS.md spine artifacts.
+
+## Agent config template (legacy — prefer AGENTS.md spine)
 
 All three files use the same structure — only the header differs:
-- `CLAUDE.md` → `# [Project Name] — Claude Code`
+- `CLAUDE.md` → `# [Project Name] — Claude Code` (or symlink to AGENTS.md)
 - `GEMINI.md` → `# [Project Name] — Gemini CLI`
-- `AGENTS.md` → `# [Project Name] — OpenCode`
+- `AGENTS.md` → `# [Project Name] — AI Agents` (Reach Template header)
 
 ```markdown
 # [Project Name] — [Agent]
@@ -55,10 +67,33 @@ Stack: [language, framework, runtime]
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "instructions": [".cursor/rules/*.mdc"]
+  "instructions": ["AGENTS.md"]
 }
 ```
 
+## Aider — `.aider.conf.yml` bridge (e37s03)
+
+When Aider wiring is opted in:
+
+```yaml
+read: AGENTS.md
+```
+
+Upstream: [Aider-AI/aider](https://github.com/Aider-AI/aider) (not paul-gauthier/aider).
+
+## Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14)
+
+Source: https://developers.openai.com/codex/guides/agents-md
+
+Codex is instruction-file-only — no slash skills. When Codex wiring is opted in:
+
+```toml
+# .codex/config.toml
+instructions = ["AGENTS.md"]
+```
+
+Use AGENTS.md header `# [Project Name] — AI Agents` (shared with OpenCode/Cline). Single AGENTS.md serves dual-tool projects.
+
 ## CONVENTIONS.md
 
 Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.

package/skills/seed-conventions/SKILL.md

@@ -32,13 +32,16 @@ Ask the user these questions (one at a time, wait for each answer):
 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
-8. **Local tool wiring (optional)** — "Wire bigpowers skills for project-local tools that global install can't reach? (Cursor + OpenCode only)" If yes, generate the local wiring artifacts described in [REFERENCE.md](REFERENCE.md) §Local tool wiring. If no, skip — the standard seed output is unchanged.
+8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in).
 
 ## Generate files
 
 After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
-- `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` — from the agent-config template
-- `opencode.json` — from the opencode template
+- `AGENTS.md` — from `docs/templates/AGENTS.md` Reach Template (canonical spine source)
+- `CLAUDE.md` — symlink to `AGENTS.md` (copy fallback on Windows when symlink fails)
+- `GEMINI.md` — symlink to `AGENTS.md` when Gemini wiring opted in
+- `opencode.json` — with `"instructions": ["AGENTS.md"]` when OpenCode opted in
+- `.aider.conf.yml` — with `read: AGENTS.md` when Aider opted in
 - `CONVENTIONS.md` — bigpowers standard template + project defensive code categories
 
 ### `specs/` directory

package/skills/using-bigpowers/SKILL.md

@@ -19,9 +19,9 @@ npm install -g bigpowers       # global install
 bigpowers setup                # sync skills + link to your tools
 ```
 
-From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.
+From source: `git clone` → `bash scripts/install.sh`. Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers).
 
-Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers)
+**Reach tools:** **Cline** — native AGENTS.md reader (no extension). **Aider** — opt-in `.aider.conf.yml` with `read: AGENTS.md` ([Aider-AI/aider](https://github.com/Aider-AI/aider)). **Codex CLI** — optional `.codex/config.toml` via seed-conventions; global `~/.codex/AGENTS.md` from install.sh.
 
 ## What bigpowers is