@kensaurus/skills 0.0.0-stage → 2.0.0

package/mcp/README.md

@@ -0,0 +1,266 @@
+# MCP Server Configuration
+
+Model Context Protocol (MCP) servers extend Cursor's AI with external tools and services.
+
+## Templates
+
+| File | Description |
+|------|-------------|
+| `mcp.json.template` | **Essential** — Firecrawl (authenticated) + Context7 + Supabase. Prefer Cursor plugins for Context7 / Supabase / Sentry / Stripe when those are already connected. |
+| `mcp-full.json.template` | **Full suite** — optional extras: Playwright MCP fallback, Chrome DevTools, AWS, GitHub, Postgres, Redis, Slack, Notion, Memory |
+
+Copy your preferred template:
+
+```bash
+# Essential (recommended to start)
+cp mcp/mcp.json.template ~/.cursor/mcp.json
+
+# Full suite (pick what you need)
+cp mcp/mcp-full.json.template ~/.cursor/mcp.json
+```
+
+Then set `FIRECRAWL_API_KEY`, `CONTEXT7_API_KEY`, and `SUPABASE_ACCESS_TOKEN` in the environment (Cursor interpolates `${env:NAME}`). Do not paste live keys into `mcp.json`. Prefer Cursor's `envFile` pointing at a chmod-restricted file such as `~/.cursor/mcp.env`.
+
+Claude Code live config (`~/.claude.json`) uses `${NAME}` (no `env:` prefix). Never put `${env:…}` inside Claude `settings.json` `env` — that block is real environment values. `claude mcp list` reads `~/.claude.json`, not an `mcpServers` block in `settings.json`.
+
+---
+
+## Server Reference
+
+### Tier 1: Essential (defaults)
+
+| Server | API Key? | What it Does |
+|--------|----------|-------------|
+| **Firecrawl** | Yes | Web scraping for research ([firecrawl.dev](https://firecrawl.dev)). Keep authenticated. Set `FIRECRAWL_NO_SEARCH_FEEDBACK=1` and `FIRECRAWL_NO_ENDPOINT_FEEDBACK=1` to skip unused feedback tools. |
+| **Context7** | Yes (API key) | Live library documentation. Skip this stdio server if the Context7 Cursor plugin is already connected. |
+| **Supabase** | Yes | Direct DB access, auth, storage, migrations. Skip if the Supabase Cursor plugin is already connected. |
+
+**Not in the default template:** Playwright MCP (skills use **headed `playwright-cli`**, not the MCP). Reasoning depth is set with effort (`/effort`, or a skill's `effort:` frontmatter), not with a reasoning server — see ADR-0009.
+
+Chrome DevTools MCP is in the full template — attach to Chrome with `--remote-debugging-port=9222` (see below).
+
+### Tier 2: Development servers
+
+| Server | API Key? | What it Does |
+|--------|----------|-------------|
+| **GitHub** | Yes (PAT) | Repos, issues, PRs, code search, reviews |
+| **GitHub Official** | Yes (PAT) | Official Go-based server (Docker, more features) |
+| **Chrome DevTools** | No* | Attach to running Chrome for console checks, screenshots |
+| **Postgres** | Yes (conn) | Direct PostgreSQL queries, schema inspection |
+| **Memory** | No | Persistent memory across sessions |
+
+### Tier 3: Cloud & Infrastructure
+
+| Server | API Key? | What it Does |
+|--------|----------|-------------|
+| **AWS Lambda** | Yes (profile) | Lambda functions, deployments, logs |
+| **AWS S3** | Yes (profile) | Bucket management, file operations |
+| **AWS CloudWatch** | Yes (profile) | Log queries, metrics, alarms |
+| **Redis** | Yes (URL) | Key-value store operations |
+
+### Tier 4: Productivity
+
+| Server | API Key? | What it Does |
+|--------|----------|-------------|
+| **Slack** | Yes (bot) | Read/send messages, manage channels |
+| **Notion** | Yes | Search/manage pages, databases |
+
+---
+
+## Setup Guides
+
+### GitHub MCP Server
+
+The most useful addition after the essentials. Two options:
+
+**Option A: npm-based (simpler)**
+```json
+{
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+    }
+  }
+}
+```
+
+**Option B: Official Docker-based (more features)**
+```json
+{
+  "github-official": {
+    "command": "docker",
+    "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+    "env": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+    }
+  }
+}
+```
+
+**Get a token:** [github.com/settings/tokens](https://github.com/settings/tokens) → Fine-grained → Permissions: Repository (Contents, Issues, PRs, Admin), User (Read-only)
+
+**What you can do:**
+- "Search for all open issues labeled `bug` in my repo"
+- "Create a PR from current branch with a summary"
+- "What changed in the last 5 commits?"
+- "Review PR #42 for security issues"
+
+---
+
+### AWS MCP Servers
+
+Requires AWS CLI configured with credentials (`aws configure`).
+
+```bash
+# Install Python-based AWS MCP servers
+pip install uvx  # or use pipx
+```
+
+```json
+{
+  "aws-lambda": {
+    "command": "uvx",
+    "args": ["awslabs.lambda-tool-mcp-server@2.1.1"],
+    "env": {
+      "AWS_PROFILE": "default",
+      "AWS_REGION": "ap-northeast-1"
+    }
+  }
+}
+```
+
+**What you can do:**
+- "List all Lambda functions in my account"
+- "Check CloudWatch logs for errors in the last hour"
+- "Upload this file to my S3 bucket"
+- "What's the invocation count for my API function?"
+
+---
+
+### Playwright — use the CLI, not the MCP
+
+> **The skills in this repo drive browsers with `playwright-cli`, not the Playwright MCP.**
+> The MCP serves one browser per server and a persistent profile can only be locked by one
+> process at a time, so parallel agents collide over tabs and profile locks. The CLI gives every
+> agent an isolated browser via `-s=<session>` and costs far fewer tokens (no tool schemas or
+> accessibility trees loaded into context).
+
+No MCP entry required. Install nothing globally — the skills invoke it through `npx`:
+
+```bash
+PW="npx --yes @playwright/cli@latest"
+$PW -s=agent1 open --headed http://localhost:3000
+$PW -s=agent2 open --headed https://example.com   # separate browser, zero conflict
+$PW list                                          # see every session
+$PW close-all                                     # tear down
+```
+
+See `skills/protocol-browser-anti-stall/` for the full protocol, the
+[MCP→CLI command map](../skills/protocol-browser-anti-stall/references/mcp-to-cli-map.md), and
+persistent-login setup (including the Google sign-in workaround).
+
+**Optional fallback** — if you specifically need the MCP, run it isolated so parallel servers
+don't fight over one profile (you lose saved logins):
+
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["-y", "@playwright/mcp@0.0.81", "--isolated"]
+  }
+}
+```
+
+Pinned versions: see [VERSIONS.md](VERSIONS.md) and [pinned-versions.json](pinned-versions.json). CI fails on `@latest` drift.
+
+**What you can do:**
+- "Open localhost:3000 and take a screenshot"
+- "Fill in the login form and submit"
+- "Check if the dashboard loads correctly"
+- "Run accessibility checks on the signup page"
+
+No need to launch Chrome separately (unlike Chrome DevTools MCP).
+
+---
+
+### Chrome DevTools MCP
+
+Requires Chrome running with remote debugging:
+
+```bash
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+Or use the shell alias:
+```bash
+source ~/skills/shell-aliases/cursor-helpers.sh
+cursor-dev  # Opens Chrome + Cursor together
+```
+
+---
+
+### Memory MCP Server
+
+Persistent memory that survives across sessions:
+
+```json
+{
+  "memory": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-memory"]
+  }
+}
+```
+
+**What you can do:**
+- AI remembers architecture decisions from past conversations
+- Stores user preferences and project context
+- Recalls past debugging sessions and solutions
+
+---
+
+## Recommended Configurations
+
+### Solo Developer (Web App)
+```
+firecrawl + context7-or-plugin + supabase-or-plugin + github (optional)
+```
+Browser QA: `playwright-cli`, not Playwright MCP.
+
+### Team / Full-Stack
+```
+All of above + postgres + memory + slack
+```
+
+### AWS Cloud Development
+```
+firecrawl + context7 + aws-lambda + aws-s3 + aws-cloudwatch + github
+```
+
+### Content / Product
+```
+firecrawl + context7 + github + notion + slack + memory
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Server not starting | Check `npx` is available: `which npx` |
+| "Bad credentials" | Regenerate token, check permissions |
+| Chrome DevTools fails | Ensure Chrome running with `--remote-debugging-port=9222` |
+| AWS servers fail | Run `aws sts get-caller-identity` to verify credentials |
+| Slow startup | Remove servers you don't use (each spawns a process) |
+
+**Performance tip:** Only enable servers you actively use. Each server is a background process. The essential three (Firecrawl + Context7 + Supabase) is a good baseline; add others as needed.

package/mcp/VERSIONS.md

@@ -0,0 +1,41 @@
+# MCP pinned versions
+
+Single source of truth: [`pinned-versions.json`](pinned-versions.json). Templates (`mcp.json.template`, `mcp-full.json.template`, repo `.mcp.json`) must match.
+
+**Last verified:** 2026-09-17
+
+## npm packages (npx -y)
+
+| Package | Pin | Notes |
+|---------|-----|-------|
+| `@modelcontextprotocol/server-github` | 2025.4.8 | full template only |
+| `@modelcontextprotocol/server-postgres` | 0.6.2 | |
+| `@modelcontextprotocol/server-redis` | 2025.4.25 | |
+| `@modelcontextprotocol/server-slack` | 2025.4.25 | |
+| `@modelcontextprotocol/server-memory` | 2026.8.31 | |
+| `@upstash/context7-mcp` | 4.1.1 | |
+| `firecrawl-mcp` | 3.24.0 | |
+| `chrome-devtools-mcp` | 1.9.0 | Requires Chrome `--remote-debugging-port=9222` |
+| `@supabase/mcp-server-supabase` | 0.12.0 | |
+| `@playwright/mcp` | 0.0.81 | |
+| `@notionhq/notion-mcp-server` | 2.5.1 | |
+
+## PyPI packages (uvx)
+
+| Template key | Package | Pin | Notes |
+|--------------|---------|-----|-------|
+| `aws-lambda` | `awslabs.lambda-tool-mcp-server` | 2.1.1 | Replaces yanked `lambda-mcp-server` |
+| `aws-s3` | `awslabs.aws-api-mcp-server` | 1.5.5 | S3/CLI via AWS API MCP (no standalone `s3-mcp-server` on PyPI) |
+| `aws-cloudwatch` | `awslabs.cloudwatch-mcp-server` | 0.2.1 | Replaces deprecated `cloudwatch-logs-mcp-server` |
+
+## Bump procedure
+
+1. Check registry: `npm view <pkg> version` or [PyPI](https://pypi.org/)
+2. Update `pinned-versions.json`
+3. Sync `mcp.json.template`, `mcp-full.json.template`, `.mcp.json`, and examples in this README
+4. Run `node scripts/check-mcp-pins.mjs`
+5. Note the bump in root `CHANGELOG.md`
+
+## CI
+
+`npm test` runs `scripts/check-mcp-pins.mjs` — commits with `@latest` or drifted pins fail.

package/mcp/mcp-full.json.template

@@ -0,0 +1,124 @@
+{
+  "mcpServers": {
+
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@4.1.1", "--api-key", "${env:CONTEXT7_API_KEY}"]
+    },
+
+    "firecrawl": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp@3.24.0"],
+      "env": {
+        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}",
+        "FIRECRAWL_NO_SEARCH_FEEDBACK": "1",
+        "FIRECRAWL_NO_ENDPOINT_FEEDBACK": "1"
+      }
+    },
+
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github@2025.4.8"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server-supabase@0.12.0", "--project-ref", "${env:SUPABASE_PROJECT_REF}"],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "${env:SUPABASE_ACCESS_TOKEN}"
+      }
+    },
+
+    "chrome-devtools-mcp": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@1.9.0", "--browser-url=http://127.0.0.1:9222"]
+    },
+
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.81", "--viewport-size", "1280x800", "--save-session", "--output-dir", ".playwright-mcp"]
+    },
+
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres@0.6.2"],
+      "env": {
+        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@host:5432/dbname"
+      }
+    },
+
+    "github-official": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+
+    "aws-lambda": {
+      "command": "uvx",
+      "args": ["awslabs.lambda-tool-mcp-server@2.1.1"],
+      "env": {
+        "AWS_PROFILE": "default",
+        "AWS_REGION": "ap-northeast-1",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    },
+
+    "aws-s3": {
+      "command": "uvx",
+      "args": ["awslabs.aws-api-mcp-server@1.5.5"],
+      "env": {
+        "AWS_PROFILE": "default",
+        "AWS_REGION": "ap-northeast-1",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    },
+
+    "aws-cloudwatch": {
+      "command": "uvx",
+      "args": ["awslabs.cloudwatch-mcp-server@0.2.1"],
+      "env": {
+        "AWS_PROFILE": "default",
+        "AWS_REGION": "ap-northeast-1",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    },
+
+    "redis": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-redis@2025.4.25"],
+      "env": {
+        "REDIS_URL": "redis://localhost:6379"
+      }
+    },
+
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack@2025.4.25"],
+      "env": {
+        "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN"
+      }
+    },
+
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@notionhq/notion-mcp-server@2.5.1"],
+      "env": {
+        "NOTION_API_KEY": "YOUR_NOTION_API_KEY"
+      }
+    },
+
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory@2026.8.31"]
+    }
+  }
+}

package/mcp/mcp.json.template

@@ -0,0 +1,29 @@
+{
+  "mcpServers": {
+    "firecrawl": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp@3.24.0"],
+      "env": {
+        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}",
+        "FIRECRAWL_NO_SEARCH_FEEDBACK": "1",
+        "FIRECRAWL_NO_ENDPOINT_FEEDBACK": "1"
+      }
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@4.1.1", "--api-key", "${env:CONTEXT7_API_KEY}"]
+    },
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@0.12.0",
+        "--project-ref",
+        "${env:SUPABASE_PROJECT_REF}"
+      ],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "${env:SUPABASE_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

package/mcp/pinned-versions.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Pinned MCP server versions for npx/uvx templates. Bump here, then sync mcp/*.template, .mcp.json, and mcp/README.md. Verified 2026-09-17.",
+  "npm": {
+    "@modelcontextprotocol/server-github": "2025.4.8",
+    "@modelcontextprotocol/server-postgres": "0.6.2",
+    "@modelcontextprotocol/server-redis": "2025.4.25",
+    "@modelcontextprotocol/server-slack": "2025.4.25",
+    "@modelcontextprotocol/server-memory": "2026.8.31",
+    "@upstash/context7-mcp": "4.1.1",
+    "firecrawl-mcp": "3.24.0",
+    "chrome-devtools-mcp": "1.9.0",
+    "@supabase/mcp-server-supabase": "0.12.0",
+    "@playwright/mcp": "0.0.81",
+    "@notionhq/notion-mcp-server": "2.5.1"
+  },
+  "pypi_uvx": {
+    "awslabs.lambda-tool-mcp-server": "2.1.1",
+    "awslabs.aws-api-mcp-server": "1.5.5",
+    "awslabs.cloudwatch-mcp-server": "0.2.1"
+  },
+  "notes": {
+    "aws-s3": "aws-s3 key uses awslabs.aws-api-mcp-server (S3 via AWS CLI). Legacy awslabs.s3-mcp-server is not on PyPI.",
+    "aws-lambda": "awslabs.lambda-mcp-server is yanked; use awslabs.lambda-tool-mcp-server.",
+    "aws-cloudwatch": "awslabs.cloudwatch-logs-mcp-server is deprecated; use awslabs.cloudwatch-mcp-server."
+  }
+}

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@kensaurus/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "You say the job; the playbook runs. 158 agent skills, 63 slash commands, 6 subagents, and MCP templates for Claude Code, Cursor, Codex CLI, and Gemini CLI. Tuned for React / Next.js / Supabase; works on most stacks.",
+  "type": "module",
+  "bin": {
+    "kenji": "bin/kenji.js"
+  },
+  "scripts": {
+    "install:cursor": "node bin/install.mjs",
+    "install:auto": "node bin/install.mjs --auto",
+    "install:claude": "node bin/install.mjs --claude",
+    "install:codex": "node bin/install.mjs --codex",
+    "install:gemini": "node bin/install.mjs --gemini",
+    "install:all": "node bin/install.mjs --all",
+    "install:cursor:clean": "node bin/install.mjs --clean",
+    "install:cursor:dry": "node bin/install.mjs --dry-run",
+    "verify:install": "node bin/install.mjs --verify",
+    "install:cursor:clean:dry": "node bin/install.mjs --clean --dry-run",
+    "install:cursor:link": "node bin/install.mjs --link",
+    "install:cursor:restore": "node bin/install.mjs --restore",
+    "check:skills": "node scripts/check-skill-count.mjs",
+    "fix:skills": "node scripts/check-skill-count.mjs --fix",
+    "gen:skill-index": "node scripts/generate-skill-index.mjs --write",
+    "check:skill-index": "node scripts/generate-skill-index.mjs --check",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "scan:secrets": "node scripts/scan-secrets.mjs --self-test",
+    "check:mcp-pins": "node scripts/check-mcp-pins.mjs",
+    "check:skill-refs": "node scripts/check-skill-refs.mjs --self-test && node scripts/check-skill-refs.mjs",
+    "check:docs-facts": "node scripts/check-docs-facts.mjs",
+    "check:md-structure": "node scripts/check-md-structure.mjs --self-test && node scripts/check-md-structure.mjs",
+    "check:dead-code": "npx -y knip@6.36.0 --max-issues 0 --treat-config-hints-as-errors",
+    "check:dead-code:prod": "npx -y knip@6.36.0 --production --max-issues 0",
+    "test:install": "node scripts/test-install.mjs",
+    "test:completion-gate": "node scripts/test-completion-gate.mjs",
+    "test": "node scripts/validate-skills.mjs && node scripts/check-skill-count.mjs && node scripts/generate-skill-index.mjs --check && node scripts/scan-secrets.mjs --self-test && node scripts/check-mcp-pins.mjs && node scripts/check-docs-facts.mjs && node scripts/check-skill-refs.mjs --self-test && node scripts/check-skill-refs.mjs && node scripts/check-md-structure.mjs --self-test && node scripts/check-md-structure.mjs && node scripts/test-completion-gate.mjs && node scripts/test-install.mjs && npm run -s check:dead-code && npm run -s check:dead-code:prod"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "skills-sh",
+    "vibe-coding",
+    "mcp",
+    "nextjs",
+    "supabase",
+    "react",
+    "typescript",
+    "ai-agents",
+    "llm-tools"
+  ],
+  "files": [
+    "skills/",
+    "skills-cursor/",
+    "commands/",
+    "commands-portable/",
+    "agents/",
+    "rules/",
+    "hooks/",
+    "mcp/",
+    "install.sh",
+    "bin/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "llms.txt",
+    "docs/screenshots/",
+    "SECURITY.md",
+    "assets/",
+    "skills.sh.json",
+    ".cursor-plugin/",
+    ".claude-plugin/",
+    ".mcp.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kensaurus/skills.git"
+  },
+  "homepage": "https://github.com/kensaurus/skills#readme",
+  "bugs": {
+    "url": "https://github.com/kensaurus/skills/issues"
+  },
+  "author": "kensaurus",
+  "license": "MIT"
+}

package/rules/approved-plan-execution.mdc

@@ -0,0 +1,65 @@
+---
+description: >-
+  Guard execution of an approved plan or burndown: forbid reward hacking and
+  feature deletion; require checkpoints, context discipline, safe terminal
+  use, and fresh verification. Applies to approved plan-*.md,
+  complete-everything, and burndown-full runs, whatever model runs them.
+alwaysApply: false
+paths:
+  - "**/plan-*.md"
+  - "**/plans/**"
+---
+
+# Approved-Plan Execution Adapter
+
+You are executing an **already-approved plan** (a `plan-*.md` audit/burndown authored and reviewed at high effort). Your job is faithful, verifiable *implementation* — not re-planning or inventing unrelated scope. When `complete-everything` is explicitly active, its connected closure set (planned + previously parked + discovered blast-radius work) is part of the approved scope. When `burndown-full` is active, repo-wide search determines mechanical scope. These rules guard the failure modes of plan execution — passing the check instead of the intent, quietly widening or narrowing scope, deleting behavior to get green — and bind every change at every effort level.
+
+## 1. Anti-reward-hacking (highest priority)
+Satisfy the **intent**, never just the check. Forbidden:
+- Hardcoding expected outputs, asserting trivialities, or narrowing a test so it cannot fail.
+- Deleting, skipping, or `.only`-ing a failing test to get green.
+- Silencing errors with `@ts-ignore`, `eslint-disable`, broad `try/catch`, or `any` instead of fixing the cause.
+- Stubbing/mocking the very thing under test.
+- Reconstructing or faking data from caches, snapshots, fixtures, or bytecode to appear correct.
+
+A green suite is necessary, not sufficient. In your trace, state why the change is correct — not just that checks pass.
+
+## 2. Anti-feature-deletion
+- Never delete or "simplify away" working code, features, routes, props, handlers, or states to pass checks or reduce scope. If something seems removable, leave it and note it for review.
+- When replacing an implementation, preserve the existing public API, behavior, and output unless the approved plan explicitly says otherwise.
+
+## 3. Small, checkpointed units
+- Implement one burndown item (or one tight group) at a time. Do not execute the whole plan in a single unattended rollout.
+- After each unit: run the relevant tests / typecheck / lint and confirm green.
+- **Default mode:** stop at the plan's phase boundaries for review; do not auto-advance.
+- **Explicit closure mode:** when the user invokes `complete-everything` or `burndown-full`, a phase boundary is an audit checkpoint, not a permission stop. Persist state, report meaningful progress, and auto-advance until the closure set is empty or a real human gate below is reached.
+- **How a closure-mode turn ends:** when the closure set is empty or a STOP condition below is met — not with a progress report while items remain open, not with a question the plan or repo already answers, not with an offer to continue ("want me to keep going?"), and not at a phase boundary. Before ending your turn, re-read your last paragraph: if it promises, offers, or asks, the turn is not over.
+- If a tool call fails or a step dead-ends, fix that step before continuing — never paper over it and push on.
+- Edit surgically: change the lines the item needs; do not rewrite files wholesale.
+- Pre-existing bugs outside the approved scope go in the trace as follow-ups, not into the diff. Add tests only where the plan asks for them or the repo already keeps tests for that surface; scratch checks stay out of the repo.
+
+## 4. Context discipline
+- Work per-surface / per-module; load only the files the current unit needs. Context is large and compaction exists, so do not drop items or wrap up early to save room.
+- For wide work, build the inventory/checklist first, then iterate through it in batches.
+
+## 5. Terminal caution
+- Re-read any shell command before running. For anything destructive (migrations, `rm`, force-push, prod-pointed scripts, DB writes), prefer a dry-run/preview and pause for confirmation. Never run a state-mutating command unless it is in the approved plan.
+- Schema DDL, RPCs, edge functions, policies, or buckets explicitly required by the approved plan are not optional follow-ups. With the target environment confirmed, deploy and verify them under `full-stack-ship-discipline`; do not pause solely because the implementation uses a migration.
+
+## 6. Verify-before-trust
+- Before each change, state in one line: what behavior must stay identical here — then confirm it does.
+- Surface assumptions; if the plan is ambiguous for this item and the repo does not resolve it, treat it as a STOP condition below — otherwise decide and record the assumption in the trace.
+- Leave a short trace per change (what / why / what was verified) so a human can audit the rollout.
+
+## 7. Follow the plan's conventions
+- The target repo is inconsistent by assumption (that's why it was audited). Treat the design-system spec / canonical patterns defined in the plan as the convention — don't invent a new per-file style.
+
+## STOP and ask the human if:
+- A real data/contract/endpoint/target is unknown (don't fabricate a substitute).
+- A fix would change public behavior/API/output not covered by the approved plan.
+- A change touches auth behavior, RLS semantics, secrets/rotation, payments, destructive production-data mutation, or an unconfirmed migration target (when the human clears it, execute at high effort and have a fresh-context reviewer check the diff before merge).
+- Do **not** stop merely because an approved feature requires non-destructive schema DDL on a confirmed target; deploy and verify it under `full-stack-ship-discipline`.
+- The only way to pass is a shortcut that doesn't satisfy the real intent.
+- Tests would need to be deleted, skipped, or weakened to pass.
+
+When unsure, research before acting (`/research`).