bigpowers 1.0.0

package/scripts/install.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# install.sh — global symlink install for bigpowers skills
+#
+# Supported tools:
+#   Claude Code  → ~/.claude/skills/<name>/ (one symlink per skill)
+#   Gemini CLI   → ~/.gemini/extensions/bigpowers/ (one dir symlink)
+#   Cursor       → ~/.cursor/rules/ (one dir symlink; per-project note printed)
+#   OpenCode     → instructions printed (no standard global path)
+#
+# Usage:
+#   ./scripts/install.sh              # install
+#   ./scripts/install.sh --dry-run   # show what would be linked
+#   ./scripts/install.sh --uninstall # remove all managed symlinks
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+DRY_RUN=false
+UNINSTALL=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run)   DRY_RUN=true ;;
+    --uninstall) UNINSTALL=true ;;
+    *) echo "Unknown flag: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+run() {
+  if $DRY_RUN; then
+    echo "  [dry-run] $*"
+  else
+    "$@"
+  fi
+}
+
+link() {
+  local src="$1" dst="$2"
+  local dst_dir; dst_dir="$(dirname "$dst")"
+  run mkdir -p "$dst_dir"
+  run ln -sfn "$src" "$dst"
+  echo "  linked: $dst → $src"
+}
+
+unlink_if_managed() {
+  local dst="$1" src_prefix="$2"
+  if [[ -L "$dst" ]]; then
+    local target; target="$(readlink "$dst")"
+    if [[ "$target" == "$src_prefix"* ]]; then
+      run rm "$dst"
+      echo "  removed: $dst"
+    fi
+  fi
+}
+
+# ── Claude Code ───────────────────────────────────────────────────────────────
+
+CLAUDE_CONFIG_DIR="$HOME/.claude"
+CLAUDE_SKILLS_DIR="$CLAUDE_CONFIG_DIR/skills"
+CLAUDE_HOOKS_DIR="$CLAUDE_CONFIG_DIR/hooks"
+CLAUDE_SETTINGS="$CLAUDE_CONFIG_DIR/settings.json"
+
+install_claude() {
+  echo ""
+  echo "Claude Code → $CLAUDE_SKILLS_DIR/"
+  local count=0
+  for skill_dir in "$REPO_ROOT"/*/; do
+    [[ -f "$skill_dir/SKILL.md" ]] || continue
+    local name; name="$(basename "$skill_dir")"
+    link "$skill_dir" "$CLAUDE_SKILLS_DIR/$name"
+    count=$((count + 1))
+  done
+  echo "  $count skills installed"
+
+  echo "Claude Code Hooks → $CLAUDE_HOOKS_DIR/"
+  link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/session-start" "$CLAUDE_HOOKS_DIR/session-start"
+  link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/run-hook.cmd" "$CLAUDE_HOOKS_DIR/run-hook.cmd"
+  link "$REPO_ROOT/guard-git/scripts/block-dangerous-git.sh" "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh"
+  link "$REPO_ROOT/guard-git/scripts/lib" "$CLAUDE_HOOKS_DIR/lib"
+
+  if [[ -f "$CLAUDE_SETTINGS" ]]; then
+    echo "  Configuring global hooks in $CLAUDE_SETTINGS..."
+    # Robustly add hooks to settings.json if not already present
+    if command -v jq >/dev/null; then
+      local tmp; tmp=$(mktemp)
+      cat "$CLAUDE_SETTINGS" | jq '
+        .hooks.SessionStart += [{"matcher":"startup|clear|compact","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/run-hook.cmd"'\" session-start","async":false}]}] |
+        .hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/block-dangerous-git.sh"'\""}]}] |
+        # deduplicate
+        .hooks.SessionStart |= unique |
+        .hooks.PreToolUse |= unique
+      ' > "$tmp" && run mv "$tmp" "$CLAUDE_SETTINGS"
+    else
+      echo "  WARNING: jq not found. Manual setup required in $CLAUDE_SETTINGS"
+    fi
+  fi
+}
+
+uninstall_claude() {
+  echo ""
+  echo "Claude Code → removing management from $CLAUDE_CONFIG_DIR/"
+  if [[ -d "$CLAUDE_SKILLS_DIR" ]]; then
+    for dst in "$CLAUDE_SKILLS_DIR"/*/; do
+      [[ -L "${dst%/}" ]] || continue
+      unlink_if_managed "${dst%/}" "$REPO_ROOT/"
+    done
+  fi
+  if [[ -d "$CLAUDE_HOOKS_DIR" ]]; then
+    unlink_if_managed "$CLAUDE_HOOKS_DIR/session-start" "$REPO_ROOT/"
+    unlink_if_managed "$CLAUDE_HOOKS_DIR/run-hook.cmd" "$REPO_ROOT/"
+    unlink_if_managed "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh" "$REPO_ROOT/"
+    unlink_if_managed "$CLAUDE_HOOKS_DIR/lib" "$REPO_ROOT/"
+  fi
+}
+
+# ── Gemini CLI ────────────────────────────────────────────────────────────────
+
+GEMINI_CONFIG_DIR="$HOME/.gemini"
+GEMINI_EXT_SRC="$REPO_ROOT/.gemini/extensions/bigpowers"
+GEMINI_EXT_DST="$GEMINI_CONFIG_DIR/extensions/bigpowers"
+GEMINI_HOOKS_DIR="$GEMINI_CONFIG_DIR/hooks"
+GEMINI_SETTINGS="$GEMINI_CONFIG_DIR/settings.json"
+
+install_gemini() {
+  echo ""
+  echo "Gemini CLI → $GEMINI_EXT_DST"
+  if [[ ! -d "$GEMINI_EXT_SRC" ]]; then
+    echo "  WARNING: $GEMINI_EXT_SRC not found — run sync-skills.sh first"
+    return
+  fi
+  link "$GEMINI_EXT_SRC" "$GEMINI_EXT_DST"
+
+  echo "Gemini CLI Hooks → $GEMINI_HOOKS_DIR/"
+  link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/session-start" "$GEMINI_HOOKS_DIR/session-start"
+  link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/run-hook.cmd" "$GEMINI_HOOKS_DIR/run-hook.cmd"
+  link "$REPO_ROOT/guard-git/scripts/block-dangerous-git.sh" "$GEMINI_HOOKS_DIR/block-dangerous-git.sh"
+  link "$REPO_ROOT/guard-git/scripts/lib" "$GEMINI_HOOKS_DIR/lib"
+
+  if [[ -f "$GEMINI_SETTINGS" ]]; then
+    echo "  Configuring global hooks in $GEMINI_SETTINGS..."
+    if command -v jq >/dev/null; then
+      local tmp; tmp=$(mktemp)
+      cat "$GEMINI_SETTINGS" | jq '
+        .hooks.SessionStart += [{"matcher":"startup|clear|compact","hooks":[{"type":"command","command":"\"'"$GEMINI_HOOKS_DIR/run-hook.cmd"'\" session-start","async":false}]}] |
+        .hooks.BeforeTool += [{"matcher":"run_shell_command","hooks":[{"name":"git-guardrails","type":"command","command":"GIT_GUARDRAILS_MODE=gemini \"'"$GEMINI_HOOKS_DIR/block-dangerous-git.sh"'\""}]}] |
+        # deduplicate
+        .hooks.SessionStart |= unique |
+        .hooks.BeforeTool |= unique
+      ' > "$tmp" && run mv "$tmp" "$GEMINI_SETTINGS"
+    else
+      echo "  WARNING: jq not found. Manual setup required in $GEMINI_SETTINGS"
+    fi
+  fi
+}
+
+uninstall_gemini() {
+  echo ""
+  echo "Gemini CLI → removing management from $GEMINI_CONFIG_DIR/"
+  unlink_if_managed "$GEMINI_EXT_DST" "$REPO_ROOT/"
+  if [[ -d "$GEMINI_HOOKS_DIR" ]]; then
+    unlink_if_managed "$GEMINI_HOOKS_DIR/session-start" "$REPO_ROOT/"
+    unlink_if_managed "$GEMINI_HOOKS_DIR/run-hook.cmd" "$REPO_ROOT/"
+    unlink_if_managed "$GEMINI_HOOKS_DIR/block-dangerous-git.sh" "$REPO_ROOT/"
+    unlink_if_managed "$GEMINI_HOOKS_DIR/lib" "$REPO_ROOT/"
+  fi
+}
+
+# ── Cursor ────────────────────────────────────────────────────────────────────
+
+CURSOR_RULES_SRC="$REPO_ROOT/.cursor/rules"
+CURSOR_RULES_DST="$HOME/.cursor/rules"
+
+install_cursor() {
+  echo ""
+  echo "Cursor → $CURSOR_RULES_DST"
+  if [[ ! -d "$CURSOR_RULES_SRC" ]]; then
+    echo "  WARNING: $CURSOR_RULES_SRC not found — run sync-skills.sh first"
+    return
+  fi
+  link "$CURSOR_RULES_SRC" "$CURSOR_RULES_DST"
+  echo ""
+  echo "  NOTE: Cursor does not scan ~/.cursor/rules/ globally."
+  echo "  For per-project access, run in your project root:"
+  echo "    ln -sfn $CURSOR_RULES_SRC .cursor/rules"
+}
+
+uninstall_cursor() {
+  echo ""
+  echo "Cursor → removing $CURSOR_RULES_DST"
+  unlink_if_managed "$CURSOR_RULES_DST" "$REPO_ROOT/"
+}
+
+# ── OpenCode ──────────────────────────────────────────────────────────────────
+
+install_opencode() {
+  local opencode_config="$REPO_ROOT/opencode.json"
+  if [[ ! -f "$opencode_config" ]]; then
+    echo "Creating opencode.json..."
+    {
+      echo "{"
+      echo "  \"\$schema\": \"https://opencode.ai/config.json\","
+      echo "  \"instructions\": [\".cursor/rules/*.mdc\"]"
+      echo "}"
+    } > "$opencode_config"
+  else
+    echo "opencode.json already exists, skipping."
+  fi
+}
+
+print_opencode_instructions() {
+  echo ""
+  echo "OpenCode — integration active:"
+  echo "  - opencode.json created (points to .cursor/rules/*.mdc)"
+  echo "  - Add AGENTS.md for project-specific rules if needed"
+}
+
+# ── main ──────────────────────────────────────────────────────────────────────
+
+echo "bigpowers install.sh — REPO: $REPO_ROOT"
+$DRY_RUN && echo "(dry-run mode — no changes written)"
+$UNINSTALL && echo "(uninstall mode)"
+
+if $UNINSTALL; then
+  uninstall_claude
+  uninstall_gemini
+  uninstall_cursor
+  echo ""
+  echo "bigpowers uninstalled."
+else
+  install_claude
+  install_gemini
+  install_cursor
+  install_opencode
+  print_opencode_instructions
+  echo ""
+  echo "bigpowers installed. Future updates:"
+  echo "  git pull && ./scripts/sync-skills.sh"
+fi

package/scripts/project-survey.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# project-survey.sh — automated project status for session-start hooks
+
+set -euo pipefail
+
+# 1. Gather file existence info
+has_conventions=$([[ -f "CONVENTIONS.md" ]] && echo "true" || echo "false")
+has_claude=$([[ -f "CLAUDE.md" ]] && echo "true" || echo "false")
+has_specs=$([[ -d "specs" ]] && echo "true" || echo "false")
+
+# 2. Scan specs/
+specs_files=""
+if [[ "$has_specs" == "true" ]]; then
+  specs_files=$(ls specs/*.md 2>/dev/null | xargs -n1 basename | tr '\n' ',' | sed 's/,$//')
+fi
+
+# 3. Git state
+current_branch=$(git branch --show-current 2>/dev/null || echo "not-a-repo")
+git_status=$(git status --short 2>/dev/null | head -n 5 | tr '\n' ' ' | sed 's/"/\\"/g')
+recent_logs=$(git log --oneline -3 2>/dev/null | tr '\n' ' ' | sed 's/"/\\"/g')
+
+# 4. Phase mapping logic (simplified for script)
+phase="Discover"
+if [[ -f "specs/PLAN.md" ]]; then
+  phase="Execute"
+elif [[ -f "specs/TASKS.md" ]]; then
+  phase="Plan"
+elif [[ -f "specs/SCOPE.md" ]]; then
+  phase="Design"
+elif [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
+  phase="Initiate"
+fi
+
+if [[ -f "specs/DIAGNOSIS.md" ]]; then
+  phase="Bug"
+fi
+
+# 5. Output concise text for context injection
+cat <<EOF
+[PROJECT SURVEY]
+Phase: $phase
+Branch: $current_branch
+Files: CONVENTIONS=$has_conventions, CLAUDE=$has_claude, SPECS=$has_specs
+Specs Found: $specs_files
+Git Status: $git_status
+Recent Logs: $recent_logs
+
+Welcome to Bigpowers. I have analyzed the project state. 
+You are currently in the '$phase' phase on the '$current_branch' branch.
+EOF
+
+if [[ -f "specs/PLAN.md" ]]; then
+  echo "Current PLAN.md found. I am ready to implement the next step."
+fi

package/scripts/sync-skills.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# sync-skills.sh — generate Cursor and Gemini CLI artifacts from SKILL.md source files
+# Run this after adding or updating any skill. Symlinks carry changes through automatically.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CURSOR_RULES="$REPO_ROOT/.cursor/rules"
+GEMINI_EXT_DIR="$REPO_ROOT/.gemini/extensions/bigpowers"
+GEMINI_SKILLS="$GEMINI_EXT_DIR/skills"
+GEMINI_COMMANDS="$GEMINI_EXT_DIR/commands"
+GEMINI_MANIFEST="$GEMINI_EXT_DIR/gemini-extension.json"
+
+mkdir -p "$CURSOR_RULES" "$GEMINI_SKILLS" "$GEMINI_COMMANDS"
+
+# Clear old artifacts to ensure a clean sync
+rm -rf "${GEMINI_SKILLS:?}"/*
+rm -rf "${GEMINI_COMMANDS:?}"/*
+
+# We'll collect metadata for the manifest if needed, 
+# though skills/commands are auto-discovered.
+# Manifest is still good for extension-level name/version.
+
+skill_count=0
+
+for skill_dir in "$REPO_ROOT"/*/; do
+  skill_md="$skill_dir/SKILL.md"
+  [[ -f "$skill_md" ]] || continue
+
+  # Extract name and description from YAML frontmatter
+  name=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$skill_md" | sed 's/^name:[[:space:]]*//')
+  description=$(awk '/^---/{f++} f==1 && /^description:/{p=1} p && !/^---/{print} f==2{exit}' "$skill_md" \
+    | sed 's/^description:[[:space:]]*//' \
+    | tr -d '\n' \
+    | sed 's/[[:space:]]\+/ /g')
+
+  [[ -z "$name" ]] && continue
+
+  # Build concatenated content: SKILL.md body + all other *.md files alphabetically
+  # Strip frontmatter from SKILL.md (content between second --- and EOF)
+  body=$(awk '/^---/{f++; next} f>=2{print}' "$skill_md")
+
+  for extra_md in $(find "$skill_dir" -maxdepth 1 -name "*.md" ! -name "SKILL.md" | sort); do
+    body="$body"$'\n\n'"---"$'\n\n'"$(cat "$extra_md")"
+  done
+
+  # Strip disable-model-invocation lines
+  body=$(echo "$body" | grep -v 'disable-model-invocation')
+
+  # 1. Write .cursor/rules/<name>.mdc
+  cursor_file="$CURSOR_RULES/$name.mdc"
+  {
+    echo "---"
+    echo "description: \"$description\""
+    echo "alwaysApply: false"
+    echo "---"
+    echo ""
+    echo "$body"
+  } > "$cursor_file"
+
+  # 2. Write Gemini Agent Skill: .gemini/extensions/bigpowers/skills/<name>/SKILL.md
+  mkdir -p "$GEMINI_SKILLS/$name"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: \"$description\""
+    echo "---"
+    echo ""
+    echo "$body"
+  } > "$GEMINI_SKILLS/$name/SKILL.md"
+
+  # 3. Write Gemini Slash Command: .gemini/extensions/bigpowers/commands/<name>.toml
+  # We use a dedicated prompt file to keep the TOML clean
+  mkdir -p "$GEMINI_COMMANDS/prompts"
+  prompt_file="commands/prompts/$name.md"
+  echo "$body" > "$GEMINI_EXT_DIR/$prompt_file"
+  
+  # Escape double quotes and backslashes for TOML
+  description_toml=$(echo "$description" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  
+  {
+    echo "description = \"$description_toml\""
+    echo "prompt = \"@{$prompt_file}\""
+  } > "$GEMINI_COMMANDS/$name.toml"
+
+  skill_count=$((skill_count + 1))
+done
+
+# Assemble final gemini-extension.json
+pkg_version=$(grep '"version":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
+pkg_desc=$(grep '"description":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
+
+jq -n --arg name "bigpowers" \
+      --arg version "$pkg_version" \
+      --arg desc "$skill_count+ $pkg_desc" \
+      '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
+
+# 4. Write OpenCode configuration: opencode.json
+{
+  echo "{"
+  echo "  \"\$schema\": \"https://opencode.ai/config.json\","
+  echo "  \"instructions\": [\".cursor/rules/*.mdc\"]"
+  echo "}"
+} > "$REPO_ROOT/opencode.json"
+
+echo "sync-skills: $skill_count skills synced"
+echo "  → .cursor/rules/ ($skill_count .mdc files)"
+echo "  → .gemini/extensions/bigpowers/skills/ (Agent Skills)"
+echo "  → .gemini/extensions/bigpowers/commands/ (Slash Commands)"
+echo "  → .gemini/extensions/bigpowers/gemini-extension.json"
+echo "  → opencode.json"

package/seed-conventions/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: seed-conventions
+description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory. Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.
+---
+
+# Seed Conventions
+
+Bootstrap a new project with the AI agent conventions it needs. Run this once at the start of a greenfield project.
+
+## What this creates
+
+- `CLAUDE.md` — Claude Code session config (project-specific)
+- `CONVENTIONS.md` — shared rules for all AI agents
+- `specs/` — the specs directory where all planning output will live
+- `AGENTS.md` — for OpenCode and other agents (optional)
+- `GEMINI.md` — for Gemini CLI (optional)
+
+## Interview
+
+Ask the user these questions (one at a time, wait for each answer):
+
+1. **Project name and one-sentence description** — "What is this project? One sentence."
+
+2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
+
+3. **Commands** — "What commands do you use for: run, test, build, lint? I'll document them so agents know how to verify their work."
+
+4. **Architecture** — "Describe the key modules and their relationships in 1–2 sentences. What are the main moving parts?"
+
+5. **Conventions** — "Any naming conventions, file organization rules, or patterns that every contributor (human or agent) must follow?"
+
+6. **Never-do list** — "What are the hard stops? Things an agent must never touch or do in this project?"
+
+7. **Defensive code categories** — "Which of these apply to your project? (Rate limit / Retry with backoff / Circuit breaker / Timeout / Graceful degradation)"
+
+## Generate files
+
+After the interview, generate:
+
+### `CLAUDE.md`
+
+```markdown
+# [Project Name] — Claude Code
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+```
+
+### `GEMINI.md`
+
+```markdown
+# [Project Name] — Gemini CLI
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+```
+
+### `AGENTS.md`
+
+```markdown
+# [Project Name] — OpenCode
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+```
+
+### `opencode.json`
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".cursor/rules/*.mdc"]
+}
+```
+
+### `CONVENTIONS.md`
+
+Use the standard bigpowers CONVENTIONS.md template, filling in the project-specific defensive code categories from the interview.
+
+### `specs/` directory
+
+```bash
+mkdir -p specs
+echo "# Specs\n\nAll planning documents for this project." > specs/README.md
+```
+
+### Verify
+
+- [ ] CLAUDE.md exists and is populated
+- [ ] CONVENTIONS.md exists and includes specs/ output convention
+- [ ] specs/ directory exists
+- [ ] Confirm with user: "Does CLAUDE.md accurately describe your project?"

package/session-state/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: session-state
+description: Track implementation decisions and progress in specs/STATE.md to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
+---
+
+# Session State
+
+Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
+
+## Goal
+
+Maintain a single source of truth for the *current* state of the work in `specs/STATE.md`. This file acts as the project's short-term memory, complementing the long-term memory of `specs/CONTEXT.md` and the task-specific instructions in `specs/PLAN.md`.
+## Workflow
+
+### 1. Initialize (Session Start)
+
+If `specs/STATE.md` does not exist, or if starting a new major phase:
+
+- [ ] Read `specs/PLAN.md` and `specs/SCOPE.md`.
+- [ ] Get git metadata: `git branch --show-current` and `git rev-parse HEAD`.
+- [ ] Create `specs/STATE.md` with the current milestone, git metadata, pending tasks, and any active decisions.
+
+### 2. Load (Context Refresh)
+
+When starting a new session or after a significant context flush:
+
+- [ ] Read `specs/STATE.md` to understand where the previous agent left off.
+- [ ] Verify the current state matches the actual codebase (run `git branch` and `git diff`).
+- [ ] Surface any discrepancies between recorded git hash and current hash.
+
+### 3. Update (Decision Point/Milestone)
+
+Whenever a significant decision is made or a milestone is reached:
+
+- [ ] Update git metadata if the branch or hash has changed.
+- [ ] Update the `Active Decisions` section with the rationale for the choice.
+- [ ] Mark completed tasks as done.
+- [ ] Add new pending tasks discovered during implementation.
+- [ ] Record any "Open Questions" that need user clarification.
+
+## File Format: specs/STATE.md
+
+```markdown
+# Session State: [Feature Name]
+
+## Current Milestone
+[What is being worked on right now]
+
+## Git Metadata
+- **Branch**: [branch-name]
+- **Hash**: [commit-hash]
+
+## Pending Tasks
+...
+```
+- [ ] Task 2
+
+## Active Decisions
+- **Decision Name**: [Rationale and impact]
+
+## Open Questions
+- [Question for the user]
+```
+
+## Anti-Patterns
+
+- **Duplicate Plan**: Don't just copy `specs/PLAN.md`. The plan is the *intended* path; the state is the *actual* progress and the deviations from that path.
+- **Stale State**: Forgetting to update `specs/STATE.md` after a major refactor or decision.
+- **Verbose History**: Keep it focused on the *current* state. Use git history for the past.