agy-superpowers 5.2.3 → 5.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.2.3",
+  "version": "5.2.4",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/rules/CLAUDE.md

@@ -0,0 +1,80 @@
+---
+trigger: always_on
+---
+
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+> **TL;DR — 4 rules to always follow:**
+> 1. **Think first** — State assumptions, ask when unclear, present tradeoffs before acting.
+> 2. **Simplicity** — Minimum code that solves the problem. If it could be 50 lines, don't write 200.
+> 3. **Surgical** — Touch only what the request requires. Don't improve adjacent code.
+> 4. **Verify** — Define success criteria upfront. Don't claim done without running the check.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/template/agent/rules/code-styles.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Code Styles
 
+> **Core rule:** ESM only (`import`/`export`), single quotes, semicolons always, camelCase vars, 2-space indent, zero npm dependencies, no TypeScript.
+
 <HARD-GATE>
 Before writing, modifying, or generating ANY code, you MUST read this file and strictly follow every rule defined below.
 If a section is empty, skip it — but never skip reading this file.
@@ -19,51 +21,48 @@ Delete the placeholder comments and replace them with your actual conventions.
 
 ## Naming Conventions
 
-<!-- Examples:
-- Variables: camelCase
-- Components: PascalCase
-- Files: kebab-case
-- Constants: UPPER_SNAKE_CASE
--->
+- Variables & functions: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Files & folders: `kebab-case`
+- No PascalCase (no classes/components in this project)
 
 ## File & Folder Structure
 
-<!-- Examples:
-- Feature-based folder structure
-- One component per file
-- Index files for barrel exports
--->
+- `bin/` — CLI entry points only
+- `scripts/` — build/utility scripts, not shipped
+- `template/` — files copied to user's `.agent/` on `init`
+- `.agent/` — agent rules, skills, workflows (not in `files[]`)
+- One responsibility per file; no barrel index files needed
 
 ## Formatting
 
-<!-- Examples:
 - Indentation: 2 spaces
-- Max line length: 100
-- Semicolons: always / never
-- Quotes: single / double
--->
+- Quotes: **single quotes** (`'`) everywhere
+- Semicolons: **always**
+- Max line length: 100 characters (soft limit)
+- Trailing commas: yes (ES2017+)
 
 ## Comments & Documentation
 
-<!-- Examples:
-- JSDoc for public functions
-- No obvious comments
-- TODO format: // TODO(username): description
--->
+- File path comment on line 2: `// bin/init.js`
+- Usage comment where non-obvious: `// Usage: ...`
+- No obvious comments ("increment i by 1")
+- No JSDoc unless the function is exported as a public API
 
 ## Patterns & Conventions
 
-<!-- Examples:
-- State management: Zustand
-- Error handling: try/catch with custom error classes
-- Async: async/await over .then()
-- Imports order: external → internal → types
--->
+- Module system: **ESM** (`import`/`export`) — `"type": "module"` in package.json
+- Async: `async/await` over `.then()`
+- Error handling: `console.error()` + `process.exit(1)` for CLI errors
+- File system: Node.js `fs` (sync preferred for CLI scripts — simple, no callback hell)
+- `__dirname` workaround for ESM: `path.dirname(fileURLToPath(import.meta.url))`
+- Imports order: Node built-ins → npm packages → local files
 
 ## Anti-Patterns (DO NOT)
 
-<!-- Examples:
-- No any type in TypeScript
-- No console.log in production code
-- No inline styles in React components
--->
+- No TypeScript — this project is plain JavaScript
+- No `require()` — ESM only
+- No `console.log` in production paths for errors — use `console.error()`
+- No dependencies in `package.json` — keep the CLI zero-dependency
+- No dynamic `import()` unless absolutely necessary
+- No `any` guesses — if path/logic is unclear, fail loudly with a message

package/template/agent/rules/debug-confirmation-policy.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Debug Confirmation Policy
 
+> **Core rule:** NEVER write fix code before presenting Root Cause + Evidence + Proposed Fix and getting explicit user confirmation.
+
 <HARD-GATE>
 When you identify a bug, error, test failure, or any code that needs fixing —
 whether the user asked you to fix it, or you discovered it yourself —

package/template/agent/rules/file-length-policy.md

@@ -15,6 +15,8 @@ This gate applies exclusively to `.agent/rules/` files.
 
 # File Length Policy
 
+> **Core rule:** Before writing to any `.agent/rules/` file, check its size. If adding content would exceed 12,000 characters total, create a new file instead.
+
 ## Hard Limit: 12,000 Characters Per File
 
 Every file in `.agent/rules/` has a **hard character limit of 12,000 characters**.

package/template/agent/rules/git-policy.md

@@ -1,5 +1,12 @@
+---
+description: Git write operations — check auto_commit before any git write command
+alwaysApply: true
+---
+
 # Git Policy
 
+> **Core rule:** Before ANY git write operation, read `.agent/config.yml` — if `auto_commit: false`, skip the operation and print "Skipping git operation (auto_commit: false)."
+
 <HARD-GATE>
 Before running ANY git write operation — git add, git commit, git push,
 git pull, git merge, git tag, git branch -d, git branch -D, git worktree remove,

package/template/agent/rules/language-matching.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Language Matching Policy
 
+> **Core rule:** Always respond in the same language the user writes in. Switch immediately when user switches. Code/commits/filenames stay in English.
+
 <HARD-GATE>
 You MUST respond in the same language the user is writing in.
 

package/template/agent/rules/scratch-scripts.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Scratch Scripts Policy
 
+> **Core rule:** NEVER use `/tmp/` — always use `.agent/tmp/` and set `Cwd` to workspace root. `/tmp/` causes `run_command` to hang forever.
+
 > **PRIORITY: CRITICAL** — Violating this rule causes commands to hang and freeze the conversation.
 
 ## The Rule

package/template/agent/rules/superpowers.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Superpowers Skills Integration
 
+> **Core rule:** Before any implementation/debugging/planning action, check if a skill applies and read its SKILL.md. Skip only for trivial factual questions with zero implementation.
+
 This workspace uses the **Superpowers** skills library located in `superpowers/skills/`.
 All skills are symlinked into `.agent/skills/` and are automatically available.
 
@@ -12,6 +14,8 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 **Before any response or action**, check if a relevant skill applies. If there's even a 1% chance a skill applies, read it via `view_file` on its `SKILL.md` and follow it exactly.
 
+**Exception (per CLAUDE.md §1):** Skip the skill check for trivial tasks — simple factual questions, one-line answers, or requests that clearly involve zero implementation (e.g., "what does X mean?", "how do I spell Y?"). If in doubt, check anyway.
+
 ## Available Skills
 
 ### Development Workflow

package/template/agent/skills/executing-plans/SKILL.md

@@ -76,3 +76,20 @@ After all tasks complete and verified:
 - **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
+
+---
+
+## Rules Checklist — Run Before Reporting Each Task Complete
+
+<HARD-GATE>
+Before marking any task as done and reporting to the user, verify all of these:
+
+- [ ] **Language** — Am I responding in the same language the user wrote in?
+- [ ] **Git ops** — Did I check `auto_commit` in `.agent/config.yml` before any git write operation?
+- [ ] **Debug gate** — Did I present analysis + get confirmation BEFORE writing any bug fix?
+- [ ] **Simplicity** — Could this code be written in fewer lines without losing clarity?
+- [ ] **Surgical** — Did I touch ONLY what the task required? No adjacent "improvements"?
+- [ ] **Evidence** — Am I about to claim success? Have I actually run the verification command?
+
+If any box is unchecked → fix it before reporting.
+</HARD-GATE>

package/template/agent/skills/systematic-debugging/SKILL.md

@@ -321,3 +321,19 @@ From debugging sessions:
 - Random fixes approach: 2-3 hours of thrashing
 - First-time fix rate: 95% vs 40%
 - New bugs introduced: Near zero vs common
+
+---
+
+## Rules Checklist — Run Before Reporting Fix Complete
+
+<HARD-GATE>
+After completing Phase 4, before telling the user the bug is fixed:
+
+- [ ] **Language** — Responding in the user's language?
+- [ ] **Debug gate** — Did I present Root Cause + Evidence + Proposed Fix and get confirmation BEFORE implementing? (debug-confirmation-policy)
+- [ ] **Git ops** — If I committed the fix: did I check `auto_commit` in `.agent/config.yml` first?
+- [ ] **Surgical** — Did I fix ONLY the root cause? No bundled refactoring or unrelated changes?
+- [ ] **Verification** — Have I actually run the test/command to confirm the fix works? Not just "should work now"?
+
+If any box is unchecked → go back and fix it before reporting.
+</HARD-GATE>

package/template/agent/skills/test-driven-development/SKILL.md

@@ -369,3 +369,19 @@ Otherwise → not TDD
 ```
 
 No exceptions without your human partner's permission.
+
+---
+
+## Behavioral Rules Checklist — Run Before Reporting Implementation Complete
+
+<HARD-GATE>
+After TDD cycle is done, before telling the user the feature is implemented:
+
+- [ ] **Language** — Responding in the user's language?
+- [ ] **Simplicity** — Is this the minimum code that satisfies the tests? No speculative features added?
+- [ ] **Surgical** — Did I touch only the files this feature requires? No unrelated refactoring?
+- [ ] **Git ops** — If committing: checked `auto_commit` in `.agent/config.yml` first?
+- [ ] **Evidence** — Did I actually run all tests and see them pass? Not just "they should pass"?
+
+If any box is unchecked → fix before reporting.
+</HARD-GATE>

package/template/agent/skills/verification-before-completion/SKILL.md

@@ -137,3 +137,25 @@ From 24 failure memories:
 Run the command. Read the output. THEN claim the result.
 
 This is non-negotiable.
+
+---
+
+## Behavioral Rules Final Check — The Last Gate Before Responding
+
+<HARD-GATE>
+This is the final checkpoint. Before sending your response to the user:
+
+**Technical verification (above):**
+- [ ] Ran the verification command — not "should pass", actual output seen
+- [ ] Exit code / test count / build result confirms the claim
+
+**Behavioral rules (don't forget these during implementation):**
+- [ ] **Language** — Response is in the user's language?
+- [ ] **Debug gate** — If this was a bug fix: did I get confirmation before implementing? (debug-confirmation-policy)
+- [ ] **Git ops** — Any git write op: checked `auto_commit` in `.agent/config.yml`?
+- [ ] **Simplicity** — No features beyond what was asked? No speculative abstractions?
+- [ ] **Surgical** — Changed only what was necessary? No "while I'm here" edits?
+
+All boxes checked? → Send response.
+Any box unchecked? → Fix it first.
+</HARD-GATE>

package/template/agent/skills/writing-plans/SKILL.md

@@ -155,3 +155,19 @@ After saving the plan, offer execution choice:
 **If Inline Execution chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
 - Batch execution with checkpoints for review
+
+---
+
+## Rules Checklist — Run Before Handing Off Plan
+
+<HARD-GATE>
+Before presenting the plan to the user or dispatching to executing agent:
+
+- [ ] **Language** — Plan explanation is in the user's language?
+- [ ] **No placeholders** — Zero TBD/TODO/"implement later" entries in the plan?
+- [ ] **YAGNI** — Every task maps to an explicit requirement? No speculative tasks?
+- [ ] **Git step in plan** — Each task's commit step says to check `auto_commit` in `.agent/config.yml`?
+- [ ] **Self-review done** — Ran the Self-Review section (spec coverage, placeholder scan, type consistency)?
+
+If any box is unchecked → fix plan before handing off.
+</HARD-GATE>