claude-code-superpowers

Teaches Claude Code's concurrency model: isConcurrencySafe() for parallel tool execution, AbortController propagation for cancellation, Promise.all() for parallel initialization, and the StreamingToolExecutor for concurrent progress streams. Use this when writing tools that could benefit from parallel execution, need to respect cancellation, or must stream partial results. Read-only tools that don't declare concurrency safety are needlessly serialized.

Teaches how to create a new Claude Code tool using the buildTool() factory from src/Tool.ts. Use this whenever adding a new capability to Claude Code — buildTool is the only correct entry point. It fills in safe defaults for isConcurrencySafe, isReadOnly, isDestructive, checkPermissions, and userFacingName so you only implement what your tool actually needs.

Use when extracting an engineering pattern from a codebase and packaging it as a skill for an AI assistant. Triggered when: converting a recurring code pattern into a SKILL.md, wanting your AI to apply a specific pattern automatically, or validating whether an existing skill is good enough to ship. Covers structure, the real-code requirement, the two-layer generic/specific design, and six quality tests.

Teaches Claude Code's core domain model: Tool, Message, Task, ToolUseContext, AppState, and Command — the six concepts every part of the system is built around. Use this before writing any new tool, command, or feature that touches the conversation loop. Essential for understanding how Claude's capability system is structured and why the abstractions exist.

Teaches Claude Code's error philosophy: tool call() throws typed errors, the framework catches them and formats them for the LLM as structured tool result content, and custom error types carry structured context at system boundaries. Use this whenever writing a tool, utility function, or service that can fail. The distinction between "errors the LLM should see" and "errors that crash the session" is the core insight.

Teaches Claude Code's startup and runtime performance patterns: lazySchema() for deferred Zod parsing, feature() flags for build-time dead code elimination, memoize() for expensive repeated computations, parallel initialization with Promise.all(), and profileCheckpoint() for tracking load times. Use this whenever writing code that runs at startup, on every turn, or in a hot loop. Startup latency is Claude Code's most user-visible performance metric.

Teaches Claude Code's module organization: tools/ for capabilities, commands/ for user-facing slash commands, services/ for business logic, state/ for AppState, utils/ for pure utilities, hooks/ for React state, and components/ for TUI rendering. Use this when deciding where to put new code or when tracing an unfamiliar behavior to its source. The division is by responsibility boundary, not by feature.

Teaches Claude Code's naming system: Tool files are [Name]Tool.ts[x], commands use kebab-case, types are PascalCase, functions start with verbs in camelCase, booleans use is/has prefixes, constants use UPPER_SNAKE_CASE, and event handlers use on[Event]. Use this when naming new files, types, functions, or variables to match the existing codebase style. Consistent naming is how contributors find code without searching.

Teaches Claude Code's logging and instrumentation conventions: logForDebugging for local structured debug output, logEvent for telemetry analytics events (with PII-safe metadata types), profileCheckpoint() for startup timing, token cost tracking via cost-tracker.ts, and the distinction between diagnostic logs (never shown to users) and tool result content (shown to the LLM). Use this when adding logging, tracking performance, or deciding what to instrument in a new tool or service.

Teaches Claude Code's multi-layered permission system: permission modes (default/bypass/auto), the checkPermissions method on tool definitions, per-tool rules, and how Zod validation gates permission checking. Use this whenever adding a tool that performs side effects, writing permission rules for settings, or understanding why a tool call was denied. Especially important for tools that touch the file system, shell, or network.

Teaches Claude Code's Skill and Command system: how slash commands (/commit, /plan) are defined as PromptCommand or LocalCommand, how skills are loaded from .claude/skills/ or bundled registry, and the inline vs. fork execution modes. Use this when creating new slash commands, writing SKILL.md files, or understanding how user-defined skills extend the conversation. The execution mode ('inline' vs 'fork') determines whether the skill shares or isolates the conversation history.

Use when reading or writing shared application state from a tool, task, or service. Triggered when: accessing state outside a React component, updating a field in a shared state store, writing a helper that modifies task or session state, or understanding why direct mutation causes stale UI or race conditions.

Teaches what Claude Code owns vs. what it delegates: the Claude API for LLM inference, MCP servers for dynamic tool/resource extension, the file system via sandboxed paths, the shell via BashTool with permission checking, and Git via execFile wrappers. Use this when adding integrations or deciding where a new capability should live — whether inside the tool system or in a new MCP server.

Teaches Claude Code's Task system: background work spawned from tools or commands, typed by TaskType (local_bash, local_agent, remote_agent, in_process_teammate, local_workflow), tracked in AppState.tasks, with disk-backed output files and a lifecycle of pending→running→(completed|failed|killed). Use this when a tool needs to spawn long-running work without blocking the conversation loop, or when building features that monitor background operations.

Teaches the complete pattern for defining a Claude Code Tool: schema-first design with Zod, the buildTool factory for safe defaults, checkPermissions for side-effect gates, progress callbacks for streaming, and returning { data: T } from call(). Use this whenever adding a new tool to Claude Code or when modifying how an existing tool handles input, permissions, or output. The pattern is the same whether the tool reads files, executes bash, or spawns subagents.

Teaches Claude Code's type design: discriminated unions for output data shapes, Zod schemas as the single source of truth for tool inputs, DeepImmutable for AppState, and z.infer<> to derive TypeScript types from schemas. Use this when designing new types, adding AppState fields, or defining tool input schemas. The core discipline: define shape once, derive all other representations from it.