staksmith

A collection of skills and configs for AI coding agents.

staksmith is a curated set of agents, skills, commands, hooks, rules, and MCP configurations for Claude Code and compatible AI agent harnesses. It bundles workflows that have been refined through daily use building real software — test-driven development, code review, security scanning, planning, continuous learning, and more — so you can drop them into any project instead of rebuilding them from scratch.

Works across Claude Code, Cursor, Codex, and OpenCode.

staksmith is organized into independent components — install the whole thing or copy only the pieces you want.

Get up and running in a couple of minutes.

# Add the marketplace
/plugin marketplace add hackastak/staksmith

# Install the plugin
/plugin install staksmith@staksmith

⚠️ Important: Claude Code plugins cannot distribute rules automatically. Install them manually:

# Clone the repo first
git clone https://github.com/hackastak/staksmith.git
cd staksmith

# Install dependencies (pick your package manager)
npm install        # or: pnpm install | yarn install | bun install

# macOS/Linux
./install.sh typescript    # or python, golang, swift, php, cpp
# ./install.sh typescript python golang swift php
# ./install.sh --target cursor typescript

# Windows PowerShell
.\install.ps1 typescript   # or python, golang, swift, php, cpp
# .\install.ps1 typescript python golang swift php
# .\install.ps1 --target cursor typescript

install.sh / install.ps1 are thin wrappers around the staksmith CLI — you can call it directly and install by profile instead of by language:

npx staksmith typescript                          # same as ./install.sh typescript
npx staksmith install --profile developer --target claude
npx staksmith plan --profile core --target cursor # preview without writing
npx staksmith doctor                              # check for missing/drifted files

Profiles (core, developer, security, research, …) are defined in manifests/install-profiles.json.

For manual install instructions see the README in the rules/ folder.

# Try a command (plugin install uses the namespaced form)
/staksmith:plan "Add user authentication"

# Manual install (Option 2) uses the shorter form:
# /plan "Add user authentication"

# Check what's available
/plugin list staksmith@staksmith

✨ That's it! You now have access to 21 agents, 134 skills, and 51 commands.

staksmith supports Windows, macOS, and Linux, alongside integration across major IDEs and CLI harnesses (Cursor, OpenCode, Codex). All hooks and scripts are written in Node.js for maximum compatibility.

staksmith automatically detects your preferred package manager (npm, pnpm, yarn, or bun) in this priority order:

1. Environment variable: CLAUDE_PACKAGE_MANAGER
2. Project config: .claude/package-manager.json
3. package.json: packageManager field
4. Lock file: package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
5. Global config: ~/.claude/package-manager.json
6. Fallback: first available package manager

To set your preferred package manager:

# Via environment variable
export CLAUDE_PACKAGE_MANAGER=pnpm

# Via global config
node scripts/setup-package-manager.js --global pnpm

# Via project config
node scripts/setup-package-manager.js --project bun

# Detect current setting
node scripts/setup-package-manager.js --detect

Or use the /setup-pm command in Claude Code.

Tune hook strictness or disable specific hooks temporarily with environment variables:

# Hook strictness profile (default: standard)
export STAKSMITH_HOOK_PROFILE=standard   # minimal | standard | strict

# Comma-separated hook IDs to disable
export STAKSMITH_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

staksmith is a Claude Code plugin — install it directly or copy components manually.

staksmith/
|-- .claude-plugin/   # Plugin and marketplace manifests
|   |-- plugin.json         # Plugin metadata and component paths
|   |-- marketplace.json    # Marketplace catalog for /plugin marketplace add
|
|-- agents/           # Specialized subagents for delegation
|   |-- planner.md            # Feature implementation planning
|   |-- architect.md          # System design decisions
|   |-- tdd-guide.md          # Test-driven development
|   |-- code-reviewer.md      # Quality and security review
|   |-- security-reviewer.md  # Vulnerability analysis
|   |-- build-error-resolver.md
|   |-- e2e-runner.md         # Playwright E2E testing
|   |-- refactor-cleaner.md   # Dead code cleanup
|   |-- doc-updater.md        # Documentation sync
|   |-- docs-lookup.md        # Library/API documentation lookup
|   |-- chief-of-staff.md     # Multi-channel communication triage
|   |-- loop-operator.md      # Autonomous loop execution and monitoring
|   |-- harness-optimizer.md  # Harness config reliability/cost tuning
|   |-- python-reviewer.md    # Python code review
|   |-- go-reviewer.md        # Go code review
|   |-- rust-reviewer.md      # Rust code review
|   |-- cpp-reviewer.md       # C++ code review
|   |-- database-reviewer.md  # Database/Supabase review
|   |-- ...                   # plus go/rust/cpp build resolvers
|
|-- skills/           # Workflow definitions and domain knowledge
|   |-- coding-standards/      # Language best practices
|   |-- backend-patterns/      # API, database, caching patterns
|   |-- frontend-patterns/     # React, Next.js patterns
|   |-- tdd-workflow/          # TDD methodology
|   |-- code-review/           # Tiered review with the Fowler smell baseline
|   |-- security-review/       # Security checklist
|   |-- verification-loop/     # Continuous verification
|   |-- continuous-learning-v2/ # Auto-extract patterns from sessions
|   |-- to-spec/ to-tickets/ implement/  # Spec-to-build flow
|   |-- adr-standard/ domain-modeling/   # Decision records and glossaries
|   |-- django-* / laravel-*   # Framework patterns, security, TDD, verification
|   |-- python-* / golang-* / rust-* / cpp-* / swift-*  # Per-language patterns & testing
|   |-- deep-research/         # Multi-source, fact-checked research
|   |-- ...                    # engineering, research, writing, and product skills
|
|-- commands/         # Slash commands for quick execution
|   |-- plan.md               # /plan  - Implementation planning
|   |-- tdd.md                # /tdd   - Test-driven development
|   |-- e2e.md                # /e2e   - E2E test generation
|   |-- build-fix.md          # /build-fix - Fix build errors
|   |-- refactor-clean.md     # /refactor-clean - Dead code removal
|   |-- verify.md             # /verify - Run verification loop
|   |-- quality-gate.md       # /quality-gate - Pre-commit quality bar
|   |-- harness-audit.md      # /harness-audit - Audit harness config
|   |-- loop-start.md         # /loop-start - Autonomous loop runs
|   |-- setup-pm.md           # /setup-pm - Configure package manager
|   |-- ...                   # plus language reviews, multi-agent, and session commands
|
|-- rules/            # Always-follow guidelines (copy to ~/.claude/rules/)
|   |-- README.md             # Structure overview and installation guide
|   |-- common/               # Language-agnostic principles
|   |   |-- coding-style.md     # Immutability, file organization
|   |   |-- git-workflow.md     # Commit format, PR process
|   |   |-- testing.md          # TDD, coverage requirements
|   |   |-- performance.md      # Model selection, context management
|   |   |-- patterns.md         # Design patterns, skeleton projects
|   |   |-- hooks.md            # Hook architecture, TodoWrite
|   |   |-- agents.md           # When to delegate to subagents
|   |   |-- security.md         # Mandatory security checks
|   |-- typescript/           # TypeScript/JavaScript specific
|   |-- python/               # Python specific
|   |-- golang/               # Go specific
|   |-- swift/                # Swift specific
|   |-- php/                  # PHP specific
|   |-- cpp/                  # C++ specific
|
|-- hooks/            # Trigger-based automations
|   |-- README.md             # Hook documentation, recipes, and customization guide
|   |-- hooks.json            # All hooks config (PreToolUse, PostToolUse, Stop, etc.)
|
|-- scripts/          # Cross-platform Node.js scripts
|   |-- staksmith.js          # `staksmith` CLI entrypoint
|   |-- lib/                  # Shared utilities (file/path/system, package-manager detection)
|   |-- hooks/                # Hook implementations
|   |-- ci/                   # Catalog + agent/command/skill/rule/hook validators
|   |-- install-plan.js / install-apply.js / doctor.js / repair.js / uninstall.js
|   |-- setup-package-manager.js
|
|-- manifests/        # Selective-install profiles, modules, and components
|-- schemas/          # JSON Schemas for hooks, plugin, install manifests, state
|
|-- tests/            # Test suite for scripts, hooks, and platform configs
|
|-- contexts/         # Dynamic system prompt injection contexts
|   |-- dev.md                # Development mode context
|   |-- review.md             # Code review mode context
|   |-- research.md           # Research/exploration mode context
|
|-- examples/         # Example CLAUDE.md configs for real-world stacks
|-- docs/             # Architecture notes, command↔agent map, release notes
|-- plugins/          # Guide to Claude Code plugins and marketplaces
|
|-- mcp-configs/      # MCP server configurations
|   |-- mcp-servers.json      # GitHub, Supabase, Vercel, Railway, etc.

Generate Claude Code skills from your repository's git history without external services:

/skill-create                    # Analyze current repo
/skill-create --instincts        # Also generate instincts for continuous-learning

This analyzes your git history locally and generates SKILL.md files, instinct collections for continuous-learning, and pattern extraction from your commit history.

The instinct-based learning system captures your patterns over time:

/instinct-status        # Show learned instincts with confidence
/instinct-import <file> # Import instincts from others
/instinct-export        # Export your instincts for sharing
/evolve                 # Cluster related instincts into skills

See skills/continuous-learning-v2/ for full documentation.

Tune the harness itself and run long-lived autonomous work:

/harness-audit          # Audit hooks, MCPs, and settings for reliability and cost
/quality-gate           # Run the pre-commit quality bar
/model-route            # Pick the right model per task type
/loop-start             # Start an autonomous loop run
/loop-status            # Check loop progress and stalls
/skill-health           # Report on skill frontmatter and coverage

The staksmith CLI tracks what it installed, so it can verify and roll back:

npx staksmith list-installed --json   # What's installed in this context
npx staksmith doctor --target cursor  # Find missing or drifted managed files
npx staksmith repair --dry-run        # Preview restoring drifted files
npx staksmith uninstall --dry-run     # Preview removing managed files

A cross-platform, zero-dependency Claude Code status line — by default: directory, git branch, model, context %, 7-day usage, and lines changed — rendered from the data Claude Code pipes to a statusLine command:

~/Developer/staksmith  main  Opus  ctx:6% █░░░░░░░░░  7D:41% ████░░░░░░  +156/-23

Three more segments, pm (package manager), cost (session USD), and duration (session wall/API time), are available but off by default — enable them via the config below.

It is opt-in: installing the plugin does not touch your settings.json. Enable it with the /statusline command (or the script directly):

/statusline                                    # or:
node scripts/statusline-setup.js --install     # user scope (~/.claude/settings.json)
node scripts/statusline-setup.js --install --project   # this project only
node scripts/statusline-setup.js --status      # what's configured
node scripts/statusline-setup.js --uninstall   # remove it (leaves a statusLine you set alone)

Install is idempotent and never overwrites a statusLine you configured yourself without --force. Choose which segments show, and their order, highest precedence first:

# 1. Env var — comma/space-separated segment names
export STAKSMITH_STATUSLINE_SEGMENTS="model,context,cost"

# 2. ~/.claude/statusline.json  →  { "segments": ["directory", "branch", "model", "context"] }

# 3. Built-in default order

Segment names: directory, branch, pm, model, context, usage, cost, duration, activity.

Each segment is color-coded by default: the context meter grades green → amber → red as it fills, usage (7-day limit) is blue, and activity shows additions green / deletions red. Turn color off with the standard NO_COLOR env var, or STAKSMITH_STATUSLINE_COLOR=0.

Hooks, the installer, and the staksmith CLI are Node.js scripts:

node --version   # must be >= 18

staksmith relies on Claude Code's plugin and hook system. Use a current Claude Code release for the smoothest experience:

claude --version

⚠️ For contributors: Do NOT add a "hooks" field to .claude-plugin/plugin.json. This is enforced by a regression test.

Claude Code automatically loads hooks/hooks.json from any installed plugin by convention. Explicitly declaring it in plugin.json causes a duplicate detection error:

Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file

A regression test keeps this from being reintroduced.

The easiest way to use staksmith — install it as a Claude Code plugin:

# Add this repo as a marketplace
/plugin marketplace add hackastak/staksmith

# Install the plugin
/plugin install staksmith@staksmith

Or add directly to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "staksmith": {
      "source": {
        "source": "github",
        "repo": "hackastak/staksmith"
      }
    }
  },
  "enabledPlugins": {
    "staksmith@staksmith": true
  }
}

This gives you instant access to all commands, agents, skills, and hooks.

Note: The Claude Code plugin system does not support distributing rules via plugins (upstream limitation). Install rules manually:

# Clone the repo first
git clone https://github.com/hackastak/staksmith.git

# Option A: User-level rules (applies to all projects)
mkdir -p ~/.claude/rules
cp -r staksmith/rules/common/* ~/.claude/rules/
cp -r staksmith/rules/typescript/* ~/.claude/rules/   # pick your stack
cp -r staksmith/rules/python/* ~/.claude/rules/
cp -r staksmith/rules/golang/* ~/.claude/rules/
cp -r staksmith/rules/php/* ~/.claude/rules/

# Option B: Project-level rules (applies to current project only)
mkdir -p .claude/rules
cp -r staksmith/rules/common/* .claude/rules/
cp -r staksmith/rules/typescript/* .claude/rules/     # pick your stack

If you prefer manual control over what's installed:

# Clone the repo
git clone https://github.com/hackastak/staksmith.git

# Copy agents to your Claude config
cp staksmith/agents/*.md ~/.claude/agents/

# Copy rules (common + language-specific)
cp -r staksmith/rules/common/* ~/.claude/rules/
cp -r staksmith/rules/typescript/* ~/.claude/rules/   # pick your stack
cp -r staksmith/rules/python/* ~/.claude/rules/
cp -r staksmith/rules/golang/* ~/.claude/rules/
cp -r staksmith/rules/php/* ~/.claude/rules/

# Copy commands
cp staksmith/commands/*.md ~/.claude/commands/

# Copy skills (copy all, or just the ones you need)
cp -r staksmith/skills/* ~/.claude/skills/
# Or copy a single skill:
# cp -r staksmith/skills/search-first ~/.claude/skills/

Copy the hooks from hooks/hooks.json into your ~/.claude/settings.json.

Copy the MCP servers you want from mcp-configs/mcp-servers.json into your ~/.claude.json.

Important: Replace YOUR_*_HERE placeholders with your actual API keys.

Subagents handle delegated tasks with limited scope. Example:

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
---

You are a senior code reviewer...

Skills are workflow definitions invoked by commands or agents:

# TDD Workflow

1. Define interfaces first
2. Write failing tests (RED)
3. Implement minimal code (GREEN)
4. Refactor (IMPROVE)
5. Verify coverage thresholds

Hooks fire on tool events. Example — warn about console.log:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Rules are always-follow guidelines, organized into common/ (language-agnostic) plus language-specific directories:

rules/
  common/          # Universal principles (always install)
  typescript/      # TS/JS specific patterns and tools
  python/          # Python specific patterns and tools
  golang/          # Go specific patterns and tools
  swift/           # Swift specific patterns and tools
  php/             # PHP specific patterns and tools
  cpp/             # C++ specific patterns and tools

See rules/README.md for installation and structure details.

Not sure where to start? Use this quick reference:

See docs/COMMAND-AGENT-MAP.md for the full command ↔ agent mapping.

Starting a new feature:

/staksmith:plan "Add user authentication with OAuth"
                                              → planner creates implementation blueprint
/tdd                                          → tdd-guide enforces write-tests-first
/code-review                                  → code-reviewer checks your work

Fixing a bug:

/tdd                                          → tdd-guide: write a failing test that reproduces it
                                              → implement the fix, verify test passes
/code-review                                  → code-reviewer: catch regressions

Preparing for production:

/code-review                                  → security-reviewer: OWASP Top 10 audit
/e2e                                          → e2e-runner: critical user flow tests
/test-coverage                                → verify coverage thresholds
/quality-gate                                 → final pre-commit quality bar

/plugin list staksmith@staksmith

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude

// In your project's .claude/settings.json
{
  "disabledMcpServers": ["supabase", "railway", "vercel"]
}

# Just agents
cp staksmith/agents/*.md ~/.claude/agents/

# Just rules
cp -r staksmith/rules/common/* ~/.claude/rules/

staksmith includes a test suite for its scripts, hooks, and platform configs:

# Full CI check: validators (agents/commands/rules/skills/hooks/manifests),
# catalog count check, then the test suite
npm test

# Test suite only
node tests/run-all.js

# Run individual test files
node tests/hooks/hooks.test.js
node tests/scripts/install-plan.test.js
node tests/ci/validators.test.js

# Lint (ESLint + markdownlint)
npm run lint

# Coverage (80% lines/functions/branches/statements)
npm run coverage

The catalog validator (scripts/ci/catalog.js) checks that the agent/skill/command counts in this README and AGENTS.md match the repository. Update those numbers when you add or remove components.

Contributions are welcome and encouraged.

staksmith is meant to be a community resource. If you have:

• Useful agents or skills
• Clever hooks
• Better MCP configurations
• Improved rules

Please contribute! See CONTRIBUTING.md for guidelines.

• Language-specific skills (C#, Kotlin) — Go, Python, Rust, Swift, C++, and TypeScript already included
• Framework-specific configs (Rails, FastAPI, NestJS) — Django, Laravel already included
• DevOps agents (Kubernetes, Terraform, AWS, Docker)
• Testing strategies (different frameworks, visual regression)
• Domain-specific knowledge (ML, data engineering, mobile)

staksmith provides full Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's native format.

# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

# Windows PowerShell
.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

Cursor has more hook events than Claude Code. The .cursor/hooks/adapter.js module transforms Cursor's stdin JSON to Claude Code's format, letting the existing scripts/hooks/*.js be reused without duplication.

Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js
                                              (shared with Claude Code)

Key hooks:

• beforeShellExecution — blocks dev servers outside tmux, git push review
• afterFileEdit — auto-format + TypeScript check + console.log warning
• beforeSubmitPrompt — detects secrets (sk-, ghp_, AKIA patterns) in prompts
• beforeTabFileRead — blocks Tab from reading .env, .key, .pem files
• beforeMCPExecution / afterMCPExecution — MCP audit logging

Cursor rules use YAML frontmatter with description, globs, and alwaysApply:

---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

staksmith provides Codex support for both the macOS app and CLI, with a reference configuration, a Codex-specific AGENTS.md supplement, and shared skills.

# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected
codex

# Optional: copy the global-safe defaults to your home directory
cp .codex/config.toml ~/.codex/config.toml

Codex macOS app:

• Open this repository as your workspace.
• The root AGENTS.md is auto-detected.
• .codex/config.toml and .codex/agents/*.toml work best kept project-local.
• The reference .codex/config.toml intentionally does not pin model or model_provider, so Codex uses its own default unless you override it.

Skills at .agents/skills/ are auto-loaded by Codex and include TDD, security review, coding standards, frontend/backend patterns, E2E testing, API design, and verification loops.

Codex does not yet provide Claude-style hook execution parity. staksmith enforcement there is instruction-based via AGENTS.md, optional model_instructions_file overrides, and sandbox/approval settings.

Current Codex builds support experimental multi-agent workflows:

• Enable features.multi_agent = true in .codex/config.toml
• Define roles under [agents.<name>]
• Point each role at a file under .codex/agents/
• Use /agent in the CLI to inspect or steer child agents

staksmith ships sample role configs for an explorer (read-only evidence gathering), a reviewer (correctness, security, missing tests), and a docs_researcher (documentation and API verification).

staksmith provides full OpenCode support including plugins and hooks.

# Install OpenCode
npm install -g opencode

# Run in the repository root
opencode

The configuration is automatically detected from .opencode/opencode.json.

OpenCode's plugin system maps cleanly onto Claude Code's hooks, with additional events:

Additional OpenCode events: file.edited, file.watcher.updated, message.updated, lsp.client.diagnostics, tui.toast.show, and more.

• Migration Guide: .opencode/MIGRATION.md
• OpenCode Plugin README: .opencode/README.md
• Consolidated Rules: .opencode/instructions/INSTRUCTIONS.md

Some architectural decisions that make staksmith work across harnesses:

• AGENTS.md at the repo root is the universal cross-tool file (read by Claude Code, Cursor, Codex, and OpenCode).
• DRY adapter pattern lets Cursor reuse Claude Code's hook scripts without duplication.
• Skills format (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode.
• Codex's lack of hooks is compensated by AGENTS.md, optional model_instructions_file overrides, and sandbox permissions.

These configs are battle-tested across multiple production applications and refined through daily use building real software with Claude Code.

• inspired by zarazhangrui
• homunculus-inspired by humanplane

Claude Code usage can be expensive if you don't manage token consumption. These settings reduce costs without sacrificing much quality.

Add to ~/.claude/settings.json:

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Switch to Opus when you need deep architectural reasoning:

/model opus

The strategic-compact skill suggests /compact at logical breakpoints instead of relying on auto-compaction. See skills/strategic-compact/SKILL.md for the full decision guide.

When to compact:

• After research/exploration, before implementation
• After completing a milestone, before starting the next
• After debugging, before continuing feature work
• After a failed approach, before trying a new one

When NOT to compact:

• Mid-implementation (you'll lose variable names, file paths, partial state)

Critical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your context window.

• Keep under 10 MCPs enabled per project
• Keep under 80 tools active
• Use disabledMcpServers in project config to disable unused ones

These configs reflect one opinionated workflow. You should:

1. Start with what resonates
2. Modify for your stack
3. Remove what you don't use
4. Add your own patterns

• Repository: github.com/hackastak/staksmith
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md
• Troubleshooting: TROUBLESHOOTING.md
• Rules guide: rules/README.md
• Hooks guide: hooks/README.md
• Plugins & marketplaces: plugins/README.md
• Command ↔ agent map: docs/COMMAND-AGENT-MAP.md
• Token optimization: docs/token-optimization.md

The content of this repo is heavily influenced by the work of industry leaders like Matt Pocock, Affaan Mustafa, Andrej Karpathy, Boris Cherny, and Addy Osmani.

MIT — use freely, modify as needed, contribute back if you can.

Star this repo if it helps. Build something great.