create-claude-stack 1.0.0

package/template/agents/pm.md

@@ -0,0 +1,45 @@
+---
+name: pm
+description: Technical PM agent. Use for GSD phase planning, roadmap management, milestone tracking, and task decomposition. Routes all project work through GSD protocol.
+tools: Read, Write, Bash, Glob, Grep, TodoWrite
+---
+
+You are a technical project manager operating via the GSD protocol.
+
+## GSD Workflow
+
+All project work uses GSD. Always check project state first:
+
+```bash
+/gsd:progress
+/gsd:plan-phase
+/gsd:execute-phase
+```
+
+## Phase Planning
+
+1. `/gsd:discuss-phase` — gather context
+2. `/gsd:plan-phase` — create PLAN.md
+3. Review plan with user before executing
+4. `/gsd:execute-phase` — implement
+
+## Milestone Management
+
+- `/gsd:new-milestone` — start new milestone
+- `/gsd:audit-milestone` — audit before archiving
+- `/gsd:complete-milestone` — archive and prepare next
+
+## Task Decomposition
+
+Break work into GSD phases. Each phase:
+
+- Has a single clear goal
+- Produces verifiable output
+- Takes 1-4 hours of execution time
+- Has explicit success criteria
+
+## Context Preservation
+
+At natural stopping points: `/gsd:pause-work`
+
+Resuming: `/gsd:resume-work`

package/template/agents/researcher.md

@@ -0,0 +1,57 @@
+---
+name: researcher
+description: Research agent. Use for web research, library documentation, technology comparisons, deep codebase investigations, and finding authoritative information. Captures findings to Obsidian vault.
+tools: WebSearch, WebFetch, Bash, Read, Glob, Grep, Agent
+---
+
+You are a technical researcher. Your job is to thoroughly investigate a question and return a concise, well-sourced answer. Use your large context window freely — be deep in research, tight in output.
+
+## Principles
+
+1. **Be thorough** — Search multiple angles. Don't stop at the first result.
+2. **Be concise in output** — Your final answer should be tight. The parent agent doesn't want a novel.
+3. **Cite sources** — Include URLs, file paths, or line numbers for every claim.
+4. **Distinguish fact from inference** — Clearly mark when you're speculating vs. reporting what you found.
+
+## Research Strategy
+
+1. Start with context7 for library docs (`mcp__plugin_context7_context7__*`) — most accurate, version-specific
+2. Use WebSearch / Brave Search for current information
+3. Use WebFetch to read specific pages in full
+4. Use Glob/Grep to explore codebases
+5. Synthesize findings — do not dump raw search results
+
+## Process
+
+1. Break the question into sub-questions if needed
+2. Search the web, read files, grep codebases — whatever it takes
+3. Synthesize findings into a structured answer
+4. Write output to the file path provided in your prompt (if given), otherwise return inline
+
+## Output Format
+
+```
+## Answer
+Direct answer to the question (1-3 sentences).
+
+## Key Findings
+- Finding 1 (source: URL or file:line)
+- Finding 2 (source: URL or file:line)
+
+## Details
+Deeper explanation if needed. Keep it under 500 words.
+
+## Recommendation
+Recommended path forward with rationale.
+
+## Next Steps
+Concrete next actions.
+```
+
+If you cannot find a definitive answer, say so and explain what you did find.
+
+## Capturing Findings
+
+After research, offer to save to Obsidian via `mcp__obsidian__write_note`.
+
+Path pattern: `Research/YYYY-MM-DD-topic.md`

package/template/hooks/discord-notify.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Discord notification hook for Claude Code
+# Called by Stop/Notification hooks in settings.json
+# Usage: bash discord-notify.sh <event-type>
+# Receives JSON context via stdin
+
+EVENT="${1:-stop}"
+
+# Extract DISCORD_WEBHOOK_URL from ~/.claude/.env (handles quoted values)
+ENV_FILE="$HOME/.claude/.env"
+DISCORD_WEBHOOK_URL=""
+if [ -f "$ENV_FILE" ]; then
+  RAW=$(grep '^DISCORD_WEBHOOK_URL=' "$ENV_FILE" | head -1)
+  DISCORD_WEBHOOK_URL="${RAW#DISCORD_WEBHOOK_URL=}"
+  DISCORD_WEBHOOK_URL="${DISCORD_WEBHOOK_URL#\"}"
+  DISCORD_WEBHOOK_URL="${DISCORD_WEBHOOK_URL%\"}"
+fi
+
+[ -z "$DISCORD_WEBHOOK_URL" ] && exit 0
+
+# Read stdin (Claude Code passes session JSON here)
+INPUT=$(timeout 2 cat 2>/dev/null || echo '{}')
+
+# Build message based on event type
+case "$EVENT" in
+  stop)
+    SESSION_ID=$(echo "$INPUT" | python3 -c \
+      "import sys,json; d=json.load(sys.stdin); print(d.get('session_id','')[:8])" \
+      2>/dev/null || echo "")
+    # Skip --print mode sessions (no session_id = ephemeral CLI call, not a real session)
+    [ -z "$SESSION_ID" ] && exit 0
+    MSG="\u2705 **Claude Code** | Session \`${SESSION_ID}\` complete"
+    ;;
+  notification)
+    MSG="\ud83d\udc4b **Claude Code** | Needs your attention"
+    ;;
+  *)
+    MSG="\ud83d\udccc **Claude Code** | ${EVENT}"
+    ;;
+esac
+
+# POST to Discord webhook
+curl -s -X POST "$DISCORD_WEBHOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d "{\"username\":\"Claude Code\",\"content\":\"${MSG}\"}" \
+  > /dev/null 2>&1 || true

package/template/hooks/gsd-context-monitor.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// gsd-hook-version: 1.27.0
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error". See #775, #1162.
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) {
+          process.exit(0);
+        }
+      } catch (e) {
+        // Ignore config parse errors
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GSD is active (has .planning/STATE.md in working directory)
+    const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/gsd:pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+          'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
+    } else {
+      message = isGsdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/template/hooks/safety-guard.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// gsd-hook-version: 1.26.0
+/**
+ * PreToolUse safety guard
+ * Checks each subcommand in a pipeline/sequence individually.
+ * Only fires a pattern when the subcommand's first word matches.
+ * Exit with block decision JSON = blocked.
+ */
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  let input = {};
+  try { input = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  if (toolName !== 'Bash') process.exit(0);
+
+  const cmd = (toolInput.command || '').trim();
+
+  // Split on shell sequence operators to get individual commands
+  const subcommands = cmd.split(/\s*(?:;|&&|\|\|)\s*/).map(s => s.trim()).filter(Boolean);
+
+  // ─── Rules ────────────────────────────────────────────────────────────────────
+  //
+  // firstWord: only apply this rule when the subcommand starts with this word
+  //            (null = apply to any subcommand)
+  // re:        pattern to test against the full subcommand string
+  // level:     'block' (hard stop) or 'warn' (stderr only, allow through)
+
+  const RULES = [
+    // Hard blocks
+    { firstWord: 'rm',     level: 'block', re: /rm\s+(-[a-z]*f[a-z]*r[a-z]*|-[a-z]*r[a-z]*f[a-z]*)\s+(\/(\s|$|[;|&*])|~(\s|$|[;|&])|\$HOME(\s|$|[;|&])|\/\*)/, label: 'rm -rf on root/home' },
+    { firstWord: 'chmod',  level: 'block', re: /chmod\s+-R\s+777/,                    label: 'chmod -R 777' },
+    { firstWord: 'kill',   level: 'block', re: /kill\s+(-9\s+)?1(\s|$)/,              label: 'kill PID 1 (init)' },
+    { firstWord: null,     level: 'block', re: /:\(\)\s*\{.*\};\s*:/,                 label: 'fork bomb' },
+    { firstWord: null,     level: 'block', re: />\s*(\/etc\/passwd|\/etc\/sudoers|\/etc\/hosts)/, label: 'overwrite system file' },
+    { firstWords: ['psql', 'mysql', 'sqlite3', 'pgcli', 'mycli', 'duckdb'],
+                           level: 'block', re: /DROP\s+DATABASE/i,                    label: 'DROP DATABASE via SQL client' },
+
+    // Warnings (already gated by permissions.ask, this is belt-and-suspenders)
+    { firstWord: 'rm',     level: 'warn',  re: /rm\s+(-[a-z]*f[a-z]*r[a-z]*|-[a-z]*r[a-z]*f[a-z]*)/, label: 'recursive force rm' },
+    { firstWord: 'git',    level: 'warn',  re: /git\s+push\s+.*--force/,              label: 'force push' },
+    { firstWord: 'git',    level: 'warn',  re: /git\s+reset\s+--hard/,                label: 'git reset --hard' },
+    { firstWord: 'git',    level: 'warn',  re: /git\s+(checkout\s+--|restore)\s+\./,  label: 'discard all working tree changes' },
+    { firstWord: 'git',    level: 'warn',  re: /git\s+clean\s+-[a-z]*f/,             label: 'git clean -f' },
+    { firstWords: ['psql', 'mysql', 'sqlite3', 'pgcli', 'mycli', 'duckdb'],
+                           level: 'warn',  re: /DROP\s+TABLE/i,                       label: 'DROP TABLE via SQL client' },
+    { firstWords: ['psql', 'mysql', 'sqlite3', 'pgcli', 'mycli', 'duckdb'],
+                           level: 'warn',  re: /TRUNCATE\s+TABLE/i,                   label: 'TRUNCATE TABLE via SQL client' },
+  ];
+
+  function firstWordOf(s) {
+    return s.split(/\s+/)[0].replace(/^.*\//, ''); // strip path prefix (e.g. /usr/bin/rm → rm)
+  }
+
+  function ruleApplies(rule, subcmd) {
+    const fw = firstWordOf(subcmd);
+    if (rule.firstWord !== undefined && rule.firstWord !== null && fw !== rule.firstWord) return false;
+    if (rule.firstWords && !rule.firstWords.includes(fw)) return false;
+    return rule.re.test(subcmd);
+  }
+
+  for (const subcmd of subcommands) {
+    for (const rule of RULES) {
+      if (!ruleApplies(rule, subcmd)) continue;
+      if (rule.level === 'block') {
+        process.stdout.write(JSON.stringify({ decision: 'block', reason: `safety-guard: ${rule.label}` }));
+        process.exit(0);
+      }
+      if (rule.level === 'warn') {
+        process.stderr.write(`[safety-guard] WARNING: ${rule.label}\n  subcmd: ${subcmd}\n`);
+        break; // one warning per subcommand is enough
+      }
+    }
+  }
+
+  process.exit(0);
+});

package/template/mcp.json

@@ -0,0 +1,34 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "__SRC_DIR__"],
+      "description": "Direct file access to all projects in __SRC_DIR__"
+    },
+    "brave-search": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      },
+      "description": "Web search via Brave Search API — BRAVE_API_KEY in ~/.claude/.env"
+    },
+    "firecrawl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
+      },
+      "description": "Web scraping and crawling — FIRECRAWL_API_KEY in ~/.claude/.env"
+    },
+    "repomix": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "repomix@latest", "--mcp"],
+      "description": "Pack local/remote repos into LLM-readable format"
+    }
+  }
+}

package/template/rules/agents.md

@@ -0,0 +1,20 @@
+---
+description: When and how to invoke specialized agents and parallel dispatch patterns
+---
+
+# Agent Usage
+
+| Agent | Invoke for |
+|-------|-----------|
+| engineer | code, debugging, TDD, PR review, GitHub Actions |
+| pm | GSD planning, phases, roadmap, milestones |
+| researcher | web research, docs, library comparisons |
+| obsidian | save findings to vault, capture notes, query knowledge |
+| requirements-analyst | clarify ambiguous requirements before implementation |
+| root-cause-analyst | deep bug investigation using 5-Why + stack traces |
+| performance-engineer | profiling, N+1 detection, caching, query optimization |
+
+**Parallel dispatch:** For 2+ independent tasks use `superpowers:dispatching-parallel-agents`.
+**Team tools:** `/everything-claude-code:team-builder` (up to 5 agents) · `/everything-claude-code:claude-devfleet` (isolated worktrees)
+
+**gsd-pi agents** (researcher · worker · scout): used by `gsd` CLI pipelines only, not Claude Code sessions.

package/template/rules/code-standards.md

@@ -0,0 +1,30 @@
+---
+description: Code quality rules, file organization, testing, and language-specific standards
+---
+
+# Code Standards
+
+- No hardcoded secrets. No `console.log`/`print` in production. Input validation at system boundaries only.
+- Parameterized queries only. Error handling with try/catch at API boundaries.
+- Files: 200-400 lines typical, 800 max. Organize by feature/domain, not by type.
+- TDD: write failing test first. Unit tests for utilities. Integration tests for APIs and pipelines.
+- Python: type hints on all functions, prefer `uv pip` over `pip`.
+- TypeScript: preferred over JS, no `any`, conventional commits.
+- Markdown: always specify language in code fences (` ```bash `, ` ```json `, etc.). Never bare ` ``` `.
+
+**Before marking done:** runs ✓ | tests pass ✓ | edge cases handled ✓ | no regressions ✓ | logs clean ✓
+
+## Gotcha List Convention
+
+When Claude makes a mistake during a skill workflow: immediately add a `## Gotchas` entry to that SKILL.md — one line: `[date] what happened | rule`. Also append to `~/.claude/tasks/lessons.md`. Do not batch; log the moment it happens.
+
+## Stack Maintenance
+
+When any CLI, MCP, plugin, or agent is added/removed/renamed, update **all** of:
+
+| Doc | What to update |
+|-----|----------------|
+| `~/.claude/CLAUDE.md` | CLIs table, MCPs list, or Plugins line |
+| `~/.claude/USER_GUIDE.md` | Quick Reference tables |
+| `~/.claude/README.md` | Rules table (if rules/ changed), Agents table (if agents/ changed) |
+| `~/.claude/rules/agents.md` | Agent usage table (if new agent added) |

package/template/rules/cognitive.md

@@ -0,0 +1,37 @@
+---
+description: Think flags, PDCA loop, confidence protocol, and QA gate
+---
+
+# Cognitive Rules
+
+## Think Flags
+
+| Flag | When to use |
+|------|-------------|
+| `--think` | Ambiguous requirements, multi-step debugging, non-obvious trade-offs |
+| `--think-hard` | Architecture decisions, security-critical code, performance root cause |
+| `--ultrathink` | System design, complex refactors, decisions with large blast radius |
+
+Never upgrade the flag without user permission. Flag applies to current response only.
+
+## PDCA Loop
+
+Use when stuck or requirements are unclear. Max 3 iterations before surfacing to user.
+
+**Plan** (what + success criteria) → **Do** (minimum action) → **Check** (actual vs expected) → **Act** (standardize or retry)
+
+Output format: `PDCA — Iteration [N] | PLAN: … | DO: … | CHECK: … | ACT: …`
+
+## Confidence Protocol
+
+Before implementing any non-trivial solution: ≥90% → proceed · 70-89% → surface alternatives · <70% → ask first.
+
+If user says "just do it" after low-confidence disclosure → proceed.
+
+## QA Gate
+
+Run `/reflect` before marking any implementation complete.
+
+## Orchestrator Mode
+
+Write **goals + constraints**, not steps. "Add rate limiting to login, match existing patterns, don't break tests, add tests for new paths" — not "open auth.js, find login, add param." Review outputs; intervene on direction, not method.

package/template/rules/git-workflow.md

@@ -0,0 +1,22 @@
+# Git Workflow
+
+**Branch model:** `nc{N}-description` per feature. Never commit to `main` directly.
+
+```text
+/git-new-feature "desc"          → creates nc{N}-desc, pushes
+commit-commands:commit           → commit project changes
+```
+
+**Commit format:** `<type>: <description>` (imperative) + `Co-Authored-By: Claude <noreply@anthropic.com>`
+Types: `add`, `fix`, `update`, `refactor`, `test`, `docs`
+
+| Task | Command |
+|------|---------|
+| Create branch | `/git-new-feature "desc"` |
+| Commit project | `commit-commands:commit` |
+| Commit + PR | `commit-commands:commit-push-pr` |
+| Squash / sync / reset / changelog | `/git-squash` / `/git-sync` / `/git-reset-hard` / `/git-changelog` |
+
+**Returning to existing branch:** `git checkout nc{N}-description` — don't create a new branch.
+
+**License heuristic:** Next.js/SaaS → proprietary · CLI/library → MIT · personal → MIT

package/template/rules/new-project.md

@@ -0,0 +1,13 @@
+# New Project Checklist
+
+1. Create `.claudeignore`: `node_modules/`, `dist/`, `build/`, `.git/`, `*.log`, `coverage/`, `.env`, `*.lock`
+2. GitHub connected? Offer `/install-github-action` (confirm first, don't run automatically)
+3. Create `tasks/` with `lessons.md`, `todo.md`, `completed.md`
+4. Security gate before production: run a security audit before launch
+
+# GSD Customization Protocol
+
+`~/.claude/gsd-local/` tracks all local GSD modifications. GSD updates wipe `get-shit-done/`.
+
+Before modifying any GSD file: add PENDING entry to `gsd-local/PATCHES.md` → make change → save diff → mark ACTIVE.
+After `/gsd:update`: run `/gsd:reapply-patches`.