Goal: Replace the brainstorm server's vendored nodemodules with a single zero-dependency server.js using Node built-ins. Architecture: Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (http module), and file watching (fs.watch).
Goal: Add spec and plan document review loops to the brainstorming and writing-plans skills. Architecture: Create reviewer prompt templates in each skill directory.
--- name: writing-plans description: Use when you have a spec or requirements for a multi-step task, before touching code --- Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it.
NEVER: INSTEAD: Example: your human partner's rule: "External feedback - be skeptical, but check carefully" your human partner's rule: "You and reviewer both report to me. If we don't need this feature, don't add it." Push back when: How to push back: If you're uncomfortable pushing back out loud: Name that tension, then tell your partner about the issue you've seen.
Load this reference when: writing or changing tests, adding mocks, or adding cleanup/helper methods for tests. Two principles govern everything here: Strict TDD produces both naturally: a test written first and watched failing against real code has already proven it can fail, and only earns a mock when the real dependency proves slow or external.
LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
--- name: finishing-a-development-branch description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work --- Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up. Announce at start: "I'm using the finishing-a-development-branch skill to complete this work." Run the project's full test suite (npm test / cargo test / pytest / go test ./...).
Goal: Refactor visual brainstorming from blocking TUI feedback model to non-blocking "Browser Displays, Terminal Commands" architecture. Architecture: Browser becomes an interactive display; terminal stays the conversation channel.
--- name: using-git-worktrees description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback --- Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools.
Goal: Make using-git-worktrees, finishing-a-development-branch, and related skills work in the Codex App's sandboxed worktree environment without breaking existing behavior. Architecture: Read-only environment detection (git-dir vs git-common-dir) at the start of two skills.
Date: 2025-11-22 Author: Bot & Jesse Status: Design Complete, Awaiting Implementation Add full superpowers support for OpenCode.ai using a native OpenCode plugin architecture that shares core functionality with the existing Codex implementation. OpenCode.ai is a coding agent similar to Claude Code and Codex.
Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document describes the single generic dispatcher pattern used in hooks/run-hook.cmd.
--- name: systematic-debugging description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes --- Core principle: ALWAYS find root cause before attempting fixes. Violating the letter of this process is violating the spirit of debugging.
Date: 2026-06-10 Status: Draft for Drew review Fix the security and reliability gaps found in PR #1720's brainstorming visual companion without changing the companion's core workflow or adding runtime dependencies. The fixes must be test-first and must leave clear automated evidence for: The companion serves agent-generated local UI for a single brainstorming session.
Status: Approved design (brainstormed with Jesse 2026-07-15); implementation plan to follow. Objective: make the subagent-driven-development skill's review-fix loop convergent and autonomous, and make the document readable, without rewriting its eval-tuned language.
Status: Proposed (follow-up to the 2026-06-09 SDD review-dispatch work; separate PR per the one-problem-per-PR rule) Driver: Measured evidence (2026-06-10) that some negative instructions in skill prose backfire, while others work — and that the difference is predictable. Micro-tests on 2026-06-10 (opus, 5 reps per phrasing, programmatic scoring; harness described below) measured how guidance phrasing changes what a controller composes: |---|---|---| The doctrine (use this to
--- name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code --- Write the test first. Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
Goal: Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries. Architecture: Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped sessionStorage, and navigates to a bare / screen URL.
Goal: Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad. skills/requesting-code-review/ is deliberately untouched.
Date: 2026-02-19 Status: Approved Scope: lib/brainstorm-server/, skills/brainstorming/visual-companion.md, tests/brainstorm-server/ During visual brainstorming, Claude runs wait-for-feedback.sh as a background task and blocks on TaskOutput(block=true, timeout=600s). This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running.
Goal: Replace the brainstorm server's vendored nodemodules with a single zero-dependency server.js using Node built-ins. Architecture: Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (http module), and file watching (fs.watch).
Goal: Add spec and plan document review loops to the brainstorming and writing-plans skills. Architecture: Create reviewer prompt templates in each skill directory.
--- name: writing-plans description: Use when you have a spec or requirements for a multi-step task, before touching code --- Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it.
NEVER: INSTEAD: Example: your human partner's rule: "External feedback - be skeptical, but check carefully" your human partner's rule: "You and reviewer both report to me. If we don't need this feature, don't add it." Push back when: How to push back: If you're uncomfortable pushing back out loud: Name that tension, then tell your partner about the issue you've seen.
Load this reference when: writing or changing tests, adding mocks, or adding cleanup/helper methods for tests. Two principles govern everything here: Strict TDD produces both naturally: a test written first and watched failing against real code has already proven it can fail, and only earns a mock when the real dependency proves slow or external.
LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
--- name: finishing-a-development-branch description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work --- Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up. Announce at start: "I'm using the finishing-a-development-branch skill to complete this work." Run the project's full test suite (npm test / cargo test / pytest / go test ./...).
Goal: Refactor visual brainstorming from blocking TUI feedback model to non-blocking "Browser Displays, Terminal Commands" architecture. Architecture: Browser becomes an interactive display; terminal stays the conversation channel.
--- name: using-git-worktrees description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback --- Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools.
Goal: Make using-git-worktrees, finishing-a-development-branch, and related skills work in the Codex App's sandboxed worktree environment without breaking existing behavior. Architecture: Read-only environment detection (git-dir vs git-common-dir) at the start of two skills.
Date: 2025-11-22 Author: Bot & Jesse Status: Design Complete, Awaiting Implementation Add full superpowers support for OpenCode.ai using a native OpenCode plugin architecture that shares core functionality with the existing Codex implementation. OpenCode.ai is a coding agent similar to Claude Code and Codex.
Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document describes the single generic dispatcher pattern used in hooks/run-hook.cmd.
--- name: systematic-debugging description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes --- Core principle: ALWAYS find root cause before attempting fixes. Violating the letter of this process is violating the spirit of debugging.
Date: 2026-06-10 Status: Draft for Drew review Fix the security and reliability gaps found in PR #1720's brainstorming visual companion without changing the companion's core workflow or adding runtime dependencies. The fixes must be test-first and must leave clear automated evidence for: The companion serves agent-generated local UI for a single brainstorming session.
Status: Approved design (brainstormed with Jesse 2026-07-15); implementation plan to follow. Objective: make the subagent-driven-development skill's review-fix loop convergent and autonomous, and make the document readable, without rewriting its eval-tuned language.
Status: Proposed (follow-up to the 2026-06-09 SDD review-dispatch work; separate PR per the one-problem-per-PR rule) Driver: Measured evidence (2026-06-10) that some negative instructions in skill prose backfire, while others work — and that the difference is predictable. Micro-tests on 2026-06-10 (opus, 5 reps per phrasing, programmatic scoring; harness described below) measured how guidance phrasing changes what a controller composes: |---|---|---| The doctrine (use this to
--- name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code --- Write the test first. Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
Goal: Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries. Architecture: Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped sessionStorage, and navigates to a bare / screen URL.
Goal: Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad. skills/requesting-code-review/ is deliberately untouched.
Date: 2026-02-19 Status: Approved Scope: lib/brainstorm-server/, skills/brainstorming/visual-companion.md, tests/brainstorm-server/ During visual brainstorming, Claude runs wait-for-feedback.sh as a background task and blocks on TaskOutput(block=true, timeout=600s). This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running.