create-claude-stack 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# Claude Power Stack
+
+A power-user `~/.claude` configuration for Claude Code — with GSD workflow, safety hooks, modular rules, and a fleet of specialized agents.
+
+## Install
+
+```bash
+# npm create (recommended — zero global install)
+npm create claude-stack@latest
+
+# or npx
+npx create-claude-stack@latest
+
+# or curl (macOS / Linux / WSL)
+curl -fsSL https://raw.githubusercontent.com/nattechan/claude-power-stack/main/install.sh | bash
+```
+
+The installer is interactive: it asks where your projects live, whether you use Obsidian, and whether you want Discord notifications. **Existing files are never silently overwritten** — conflicts are shown with a diff and you choose what to do.
+
+## What's included
+
+### `CLAUDE.md`
+Global instructions that load in every Claude Code session. Establishes the GSD workflow, tool hierarchy, confidence protocol, and session state pattern. Edit it to describe your stack.
+
+### `rules/`
+Modular rule files loaded alongside `CLAUDE.md`:
+
+| File | What it governs |
+|------|----------------|
+| `cognitive.md` | Think flags, PDCA loop, confidence protocol |
+| `git-workflow.md` | Branch model (`nc{N}`), commit format, PR flow |
+| `code-standards.md` | Language standards, TDD, file size limits |
+| `agents.md` | Which agent to reach for which task |
+| `new-project.md` | New project checklist, GSD customization |
+
+### `hooks/`
+Lifecycle hooks that run automatically:
+
+| Hook | When it runs | What it does |
+|------|-------------|--------------|
+| `safety-guard.js` | Before every Bash tool call | Blocks `rm -rf /`, fork bombs, DROP DATABASE, force push to main, etc. |
+| `gsd-context-monitor.js` | After every tool call | Warns the agent at 35% / 25% context remaining so it can wrap up before hitting limits |
+| `discord-notify.sh` | On session stop + notification | Posts a message to a Discord channel (optional — needs `DISCORD_WEBHOOK_URL` in `.env`) |
+
+### `agents/`
+Specialized subagents dispatched with the Agent tool:
+
+| Agent | Use for |
+|-------|---------|
+| `engineer` | Code implementation, debugging, TDD, PR review |
+| `pm` | GSD phase planning, roadmap, milestone management |
+| `researcher` | Web research, docs, library comparisons |
+| `obsidian` | Save findings to vault, query knowledge, daily logs |
+
+### `mcp.json`
+Global MCP server configuration: `filesystem`, `brave-search`, `firecrawl`, `repomix`.
+
+### `settings.json`
+Permissions (allow/ask/deny), hooks wiring, enabled plugins, and autoApprove list.
+
+## Prerequisites
+
+- **Claude Code CLI** — [install guide](https://docs.anthropic.com/en/docs/claude-code)
+- **Node.js 18+** — required for hooks and the installer
+- **GSD plugin** — install inside Claude Code: `/install get-shit-done`
+
+## Recommended plugins
+
+Install these in Claude Code after setup:
+
+```
+superpowers          — writing plans, executing plans, brainstorming, debugging
+everything-claude-code — 100+ skills: TDD, security review, code review, etc.
+commit-commands      — /commit, /push, /pr in one shot
+feature-dev          — feature planning and implementation workflow
+frontend-design      — UI/UX implementation workflow
+```
+
+## Optional integrations
+
+### Discord notifications
+
+Add your webhook to `~/.claude/.env`:
+
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your/webhook
+```
+
+Session-complete and attention-needed events post to your channel.
+
+### Obsidian vault
+
+If you chose Obsidian during install, the `obsidian` agent knows your vault path.
+Install the `obsidian` plugin in Claude Code for `/obsidian-daily-note`, `/obsidian-compress`, etc.
+
+### Brave Search
+
+Free tier at [brave.com/search/api](https://brave.com/search/api) — 2 000 queries/month.
+Add `BRAVE_API_KEY` to `~/.claude/.env`.
+
+## Customizing
+
+- **CLAUDE.md** — edit to describe your tech stack, preferred tools, and project domains
+- **rules/** — each file is ≤ 100 lines; add or remove rule files as needed
+- **agents/** — copy an existing agent as a template for domain-specific agents
+- **hooks/** — edit `safety-guard.js` to add your own blocked command patterns
+- **mcp.json** — add project-specific MCP servers (n8n, Supabase, Sentry, etc.)
+
+## Project layout after install
+
+```text
+~/.claude/
+├── CLAUDE.md              ← Global instructions
+├── mcp.json               ← MCP servers
+├── settings.json          ← Permissions + hooks
+├── .env.example           ← API key template (copy to .env)
+├── rules/                 ← Modular rule files
+├── hooks/                 ← Lifecycle hooks
+├── agents/                ← Subagent definitions
+└── tasks/
+    └── lessons.md         ← Self-learning log
+```
+
+## License
+
+MIT

package/bin/create.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const rl_  = require('readline');
+const { execSync } = require('child_process');
+
+const HOME       = os.homedir();
+const CLAUDE_DIR = path.join(HOME, '.claude');
+const TMPL_DIR   = path.join(__dirname, '..', 'template');
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const C = {
+  green:  s => `\x1b[32m${s}\x1b[0m`,
+  yellow: s => `\x1b[33m${s}\x1b[0m`,
+  cyan:   s => `\x1b[36m${s}\x1b[0m`,
+  red:    s => `\x1b[31m${s}\x1b[0m`,
+  bold:   s => `\x1b[1m${s}\x1b[0m`,
+  dim:    s => `\x1b[2m${s}\x1b[0m`,
+};
+
+const ok   = msg => console.log(`  ${C.green('✓')} ${msg}`);
+const skip = msg => console.log(`  ${C.dim('–')} ${msg} ${C.dim('(skipped)')}`);
+const warn = msg => console.log(`  ${C.yellow('⚠')} ${msg}`);
+const err  = msg => console.log(`  ${C.red('✗')} ${msg}`);
+const hdr  = msg => console.log(`\n${C.bold(msg)}`);
+
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// ── Readline helpers ──────────────────────────────────────────────────────────
+let rl;
+
+function openRL() {
+  rl = rl_.createInterface({ input: process.stdin, output: process.stdout });
+}
+function closeRL() {
+  rl.close();
+}
+function ask(question, defaultVal) {
+  return new Promise(resolve => {
+    const hint = defaultVal ? ` ${C.dim(`[${defaultVal}]`)}` : '';
+    rl.question(`  ${question}${hint} `, ans => {
+      resolve(ans.trim() || defaultVal || '');
+    });
+  });
+}
+function askYN(question, defaultYes = true) {
+  return new Promise(resolve => {
+    const hint = defaultYes ? C.dim('[Y/n]') : C.dim('[y/N]');
+    rl.question(`  ${question} ${hint} `, ans => {
+      const a = ans.trim().toLowerCase();
+      resolve(!a ? defaultYes : a === 'y' || a === 'yes');
+    });
+  });
+}
+async function askChoice(question, choices) {
+  // choices: [{key, label}]
+  console.log(`  ${question}`);
+  choices.forEach(({ key, label }) => console.log(`    ${C.cyan(key)}) ${label}`));
+  return new Promise(resolve => {
+    rl.question('  Choice: ', ans => resolve(ans.trim().toLowerCase()));
+  });
+}
+
+// ── File helpers ──────────────────────────────────────────────────────────────
+function readTemplate(relPath) {
+  return fs.readFileSync(path.join(TMPL_DIR, relPath), 'utf8');
+}
+
+function substitute(content, vars) {
+  let result = content;
+  for (const [k, v] of Object.entries(vars)) {
+    result = result.split(k).join(v);
+  }
+  return result;
+}
+
+function fileExists(relPath) {
+  return fs.existsSync(path.join(CLAUDE_DIR, relPath));
+}
+
+function destContent(relPath) {
+  const p = path.join(CLAUDE_DIR, relPath);
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+}
+
+// ── Conflict resolution ───────────────────────────────────────────────────────
+// Returns true if the file should be written.
+async function resolveConflict(relPath, newContent) {
+  const existing = destContent(relPath);
+
+  // File doesn't exist → always write
+  if (existing === null) return true;
+
+  // File is identical → nothing to do
+  if (existing === newContent) { skip(relPath); return false; }
+
+  // File differs → ask
+  console.log(`\n  ${C.yellow('conflict')} ${relPath}`);
+  const choice = await askChoice(
+    'This file already exists and differs from the template. What would you like to do?',
+    [
+      { key: 'o', label: 'Overwrite with template version' },
+      { key: 'k', label: 'Keep existing (skip this file)' },
+      { key: 'm', label: 'Merge: keep existing, append template as a comment block at the end' },
+      { key: 'd', label: 'Show diff then decide' },
+    ]
+  );
+
+  if (choice === 'd') {
+    // Show a simple line diff summary
+    const existingLines = existing.split('\n');
+    const newLines      = newContent.split('\n');
+    console.log(C.dim(`  --- existing (${existingLines.length} lines)  +++ template (${newLines.length} lines)`));
+    // Print first differing lines for context
+    let shown = 0;
+    for (let i = 0; i < Math.max(existingLines.length, newLines.length) && shown < 8; i++) {
+      const eL = existingLines[i] ?? '';
+      const nL = newLines[i] ?? '';
+      if (eL !== nL) {
+        if (eL) console.log(C.red(`  - ${eL.slice(0, 80)}`));
+        if (nL) console.log(C.green(`  + ${nL.slice(0, 80)}`));
+        shown++;
+      }
+    }
+    if (shown === 8) console.log(C.dim('  ... (truncated)'));
+    return resolveConflict(relPath, newContent); // re-ask after showing diff
+  }
+
+  if (choice === 'o') return true;
+  if (choice === 'k') { skip(relPath); return false; }
+  if (choice === 'm') {
+    const merged = existing + '\n\n# ─── Template version (appended by claude-power-stack installer) ───\n# ' +
+      newContent.split('\n').join('\n# ');
+    if (!DRY_RUN) {
+      fs.mkdirSync(path.dirname(path.join(CLAUDE_DIR, relPath)), { recursive: true });
+      fs.writeFileSync(path.join(CLAUDE_DIR, relPath), merged);
+    }
+    ok(`${relPath} ${C.dim('(merged)')}`);
+    return false; // already written
+  }
+  // unrecognised → keep
+  skip(relPath);
+  return false;
+}
+
+// ── Backup ────────────────────────────────────────────────────────────────────
+function backupExisting() {
+  const stamp  = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backup = `${CLAUDE_DIR}.bak-${stamp}`;
+  if (!DRY_RUN) fs.cpSync(CLAUDE_DIR, backup, { recursive: true });
+  warn(`Full backup written to ${backup}`);
+  return backup;
+}
+
+// ── Install one file ──────────────────────────────────────────────────────────
+async function installFile(relPath, vars) {
+  let content;
+  try {
+    content = readTemplate(relPath);
+  } catch {
+    warn(`Template not found: ${relPath}`);
+    return;
+  }
+
+  const final = substitute(content, vars);
+  const write = await resolveConflict(relPath, final);
+
+  if (write) {
+    if (!DRY_RUN) {
+      fs.mkdirSync(path.dirname(path.join(CLAUDE_DIR, relPath)), { recursive: true });
+      fs.writeFileSync(path.join(CLAUDE_DIR, relPath), final);
+    }
+    ok(relPath);
+  }
+}
+
+// ── Preview what will change ──────────────────────────────────────────────────
+function previewChanges(files, vars) {
+  const statuses = files.map(f => {
+    const tmplPath = path.join(TMPL_DIR, f);
+    if (!fs.existsSync(tmplPath)) return { f, status: 'missing-template' };
+    const existing = destContent(f);
+    if (existing === null) return { f, status: 'new' };
+    const newContent = substitute(fs.readFileSync(tmplPath, 'utf8'), vars);
+    if (existing === newContent) return { f, status: 'unchanged' };
+    return { f, status: 'conflict' };
+  });
+
+  const newFiles      = statuses.filter(s => s.status === 'new');
+  const conflicts     = statuses.filter(s => s.status === 'conflict');
+  const unchanged     = statuses.filter(s => s.status === 'unchanged');
+
+  hdr('Preview of changes:');
+  if (newFiles.length) {
+    console.log(`\n  ${C.green('New files')} (${newFiles.length}):`);
+    newFiles.forEach(s => console.log(`    ${C.green('+')} ${s.f}`));
+  }
+  if (conflicts.length) {
+    console.log(`\n  ${C.yellow('Conflicts')} (${conflicts.length}) — you will be asked what to do:`);
+    conflicts.forEach(s => console.log(`    ${C.yellow('~')} ${s.f}`));
+  }
+  if (unchanged.length) {
+    console.log(`\n  ${C.dim('Unchanged')} (${unchanged.length}) — will be skipped automatically`);
+  }
+
+  return { newFiles, conflicts, unchanged };
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+  console.log(`\n${C.bold('━━━ Claude Power Stack Installer ━━━')}`);
+  console.log('  Power-user ~/.claude configuration with GSD, safety hooks, and modular rules.\n');
+
+  if (DRY_RUN) warn('Dry-run mode — no files will be written.\n');
+
+  openRL();
+
+  // 1. Gather config
+  hdr('Configuration:');
+  const srcDir      = await ask('Where do you store your projects?', path.join(HOME, 'src'));
+  const useObsidian = await askYN('Do you use Obsidian?', false);
+  let obsidianPath  = path.join(HOME, 'obsidian_vault');
+  if (useObsidian) {
+    const defaultVault = path.join(HOME, 'Library', 'Mobile Documents',
+      'iCloud~md~obsidian', 'Documents', 'obsidian_vault');
+    obsidianPath = await ask('Obsidian vault path?', defaultVault);
+  }
+  const useDiscord = await askYN('Enable Discord notifications? (add webhook to .env later)', false);
+
+  closeRL();
+
+  const vars = {
+    '__SRC_DIR__':       srcDir,
+    '__OBSIDIAN_PATH__': obsidianPath,
+  };
+
+  const ALL_FILES = [
+    'CLAUDE.md',
+    'mcp.json',
+    'settings.json',
+    'rules/cognitive.md',
+    'rules/git-workflow.md',
+    'rules/code-standards.md',
+    'rules/agents.md',
+    'rules/new-project.md',
+    'hooks/safety-guard.js',
+    'hooks/gsd-context-monitor.js',
+    'hooks/discord-notify.sh',
+    'agents/engineer.md',
+    'agents/pm.md',
+    'agents/researcher.md',
+    'agents/obsidian.md',
+  ];
+
+  // 2. Preview
+  const existingClaude = fs.existsSync(CLAUDE_DIR);
+  const preview = previewChanges(ALL_FILES, vars);
+
+  // 3. Backup offer
+  if (existingClaude) {
+    openRL();
+    console.log('');
+    const doBackup = await askYN(
+      `~/.claude already exists. Create a full backup before installing?`,
+      true
+    );
+    if (doBackup) backupExisting();
+    closeRL();
+  }
+
+  // 4. Final confirm
+  openRL();
+  console.log('');
+  console.log(`  Will install to: ${C.cyan(CLAUDE_DIR)}`);
+  if (preview.conflicts.length) {
+    console.log(`  ${C.yellow(preview.conflicts.length + ' conflicts')} will be resolved interactively.`);
+  }
+  const go = await askYN('Proceed with installation?', true);
+  closeRL();
+
+  if (!go) { console.log('\n  Aborted.'); process.exit(0); }
+
+  // 5. Install files
+  hdr('Installing:');
+  if (!DRY_RUN) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+
+  openRL(); // keep open for conflict resolution prompts
+  for (const f of ALL_FILES) {
+    await installFile(f, vars);
+  }
+
+  // Make discord hook executable
+  const discordHookDest = path.join(CLAUDE_DIR, 'hooks', 'discord-notify.sh');
+  if (!DRY_RUN && fs.existsSync(discordHookDest)) {
+    fs.chmodSync(discordHookDest, 0o755);
+  }
+
+  // .env.example
+  const envLines = [
+    '# Claude Power Stack — API Keys',
+    '# Copy this file to .env and fill in your keys.',
+    '',
+    '# Web search (free tier: https://brave.com/search/api/)',
+    'BRAVE_API_KEY=',
+    '',
+    '# Web scraping (https://firecrawl.dev)',
+    'FIRECRAWL_API_KEY=',
+  ];
+  if (useDiscord) {
+    envLines.push('', '# Discord notifications (create webhook in Server Settings → Integrations)');
+    envLines.push('DISCORD_WEBHOOK_URL=');
+  }
+  const envContent = envLines.join('\n') + '\n';
+  const envWrite = await resolveConflict('.env.example', envContent);
+  if (envWrite && !DRY_RUN) {
+    fs.writeFileSync(path.join(CLAUDE_DIR, '.env.example'), envContent);
+    ok('.env.example');
+  }
+
+  // tasks/ scaffold (only create if doesn't exist)
+  const lessonsPath = path.join(CLAUDE_DIR, 'tasks', 'lessons.md');
+  if (!fs.existsSync(lessonsPath)) {
+    if (!DRY_RUN) {
+      fs.mkdirSync(path.join(CLAUDE_DIR, 'tasks'), { recursive: true });
+      fs.writeFileSync(lessonsPath, '# Lessons\n\n| Date | What went wrong | Rule to follow |\n|------|----------------|----------------|\n');
+    }
+    ok('tasks/lessons.md');
+  } else {
+    skip('tasks/lessons.md (already exists — your notes are safe)');
+  }
+
+  closeRL();
+
+  // 6. Next steps
+  hdr('Done! Next steps:\n');
+  console.log(`  1. ${C.bold('Add API keys')}`);
+  console.log(`     cp ~/.claude/.env.example ~/.claude/.env`);
+  console.log(`     # Edit .env — add BRAVE_API_KEY at minimum\n`);
+  console.log(`  2. ${C.bold('Install GSD workflow plugin')} (primary workflow engine)`);
+  console.log(`     Open Claude Code and run: /install get-shit-done\n`);
+  console.log(`  3. ${C.bold('Install recommended plugins')} in Claude Code:`);
+  console.log(`     superpowers  · everything-claude-code  · commit-commands\n`);
+  if (useDiscord) {
+    console.log(`  4. ${C.bold('Set up Discord notifications')}`);
+    console.log(`     Add your webhook URL to ~/.claude/.env as DISCORD_WEBHOOK_URL\n`);
+  }
+  console.log(`  Full docs: https://github.com/nattechan/claude-power-stack\n`);
+}
+
+main().catch(e => { console.error(C.red('\nFatal: ' + e.message)); process.exit(1); });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-claude-stack",
+  "version": "1.0.0",
+  "description": "Scaffold a power-user Claude Code configuration with GSD workflow, safety hooks, and modular rules",
+  "bin": {
+    "create-claude-stack": "bin/create.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nattechan/claude-power-stack.git"
+  },
+  "homepage": "https://github.com/nattechan/claude-power-stack#readme",
+  "bugs": {
+    "url": "https://github.com/nattechan/claude-power-stack/issues"
+  },
+  "author": "",
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "scripts": {
+    "test": "node bin/create.js --dry-run"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "developer-tools",
+    "configuration"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md — Global Protocol
+
+## Context Budget
+
+`CLAUDE.md` ≤ 150 lines. Each `rules/` file ≤ 100 lines. Prefer a file path reference over inlining content. If adding content would exceed the budget, trim something first.
+
+## Role
+
+Generalist engineer and technical PM. Delegates to specialized agents.
+GSD is the primary workflow for all project work.
+
+## Primary Workflow — GSD
+
+```text
+/gsd:discuss-phase → /gsd:plan-phase → /gsd:execute-phase → /gsd:verify-work → /gsd:ship
+...repeat per phase... → /gsd:complete-milestone → /gsd:new-milestone
+```
+
+Quick access: `/gsd:new-project` | `/gsd:progress` | `/gsd:plan-phase` | `/gsd:execute-phase` | `/gsd:quick` | `/gsd:do`
+
+## Available Tools
+
+**Hierarchy: CLI > MCP > Plugin.**
+
+### CLIs
+
+| CLI | Purpose |
+|-----|---------|
+| `gh` | GitHub: PRs, issues, Actions, releases |
+| `git` | version control |
+| `supabase` | local dev, migrations, functions |
+| `vercel` | deploy and manage Vercel projects |
+| `docker` | build images, compose stacks |
+| `npx playwright` / `playwright-cli` | browser automation |
+| `repomix` | pack repo into LLM file (`--style markdown`, `--remote <url>`) |
+| `gemini` | Gemini CLI: research, code review, multi-modal |
+| `firecrawl` | web scraping: scrape, crawl, map, search |
+| `tsc` / `ts-node` | TypeScript compiler and runner |
+| `markdownlint-cli2` | lint/fix markdown |
+
+### MCPs
+
+- `filesystem` — direct access to `__SRC_DIR__`
+- `context7` — up-to-date library docs
+- `brave-search` — web search (requires `BRAVE_API_KEY` in `~/.claude/.env`)
+- `firecrawl` — web scraping (requires `FIRECRAWL_API_KEY`)
+
+### Plugins (invoke via Skill tool)
+
+`superpowers` · `GSD` · `commit-commands` · `everything-claude-code` · `feature-dev` · `frontend-design` · `app-security` · `cost-reducer`
+
+## Universal Rules
+
+1. Check for relevant skill before acting — use Skill tool
+2. GSD for any multi-step project — never plan inline in chat
+3. Tool hierarchy: CLI > MCP > Plugin
+4. Use `gh` CLI for all GitHub operations — no GitHub MCP
+5. Browser automation: `playwright-cli` / `npx playwright` only
+6. Verification: never mark complete without proving it works (run tests, check logs, diff behavior)
+7. Self-learning: after any correction → append to `~/.claude/tasks/lessons.md`: `[date] | what went wrong | rule to follow`
+8. Confidence: ≥90% → proceed; 70-89% → surface alternatives; <70% → ask first
+9. Plan-first: 3+ step tasks → write plan before implementing; stop and re-plan if blocked mid-task
+
+## Session State
+
+`~/.claude/primer.md` — rewritten each session end, re-injected after `/compact`.
+Before closing: *"Rewrite `~/.claude/primer.md` with: active project, completed, exact next step, blockers. Under 100 lines."*
+At session start: scan `~/.claude/tasks/lessons.md` for patterns relevant to the current task before acting.
+
+## Key Patterns
+
+| Situation | Action |
+|-----------|--------|
+| Context long | `/gsd:pause-work` → new session → `/gsd:resume-work` |
+| Recurring task | Ralph Loop or CronCreate |
+| Unsure next step | `/gsd:progress` |
+| New skill | `/skill-create` (everything-claude-code) |
+| Security review | `/app-security` |
+
+## Autocompact
+
+At 35% remaining: wrap up current task. At 25%: run `/compact` immediately, then resume.
+
+## Usage Limit Handling
+
+1. GSD active (`.planning/STATE.md` exists): `/gsd:pause-work` immediately
+2. No GSD: write to `~/.claude/primer.md`
+3. Tell user: "Usage limit reached. State saved. Run `/gsd:resume-work` in new session."

package/template/agents/engineer.md

@@ -0,0 +1,39 @@
+---
+name: engineer
+description: Software engineer agent. Use for code implementation, debugging, TDD, PR reviews, GitHub Actions. Invokes superpowers skills for structured workflows.
+tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+You are a senior software engineer. You write clean, tested, production-ready code.
+
+## Approach
+
+- Always read existing code before modifying
+- Use TDD: write failing test first (`superpowers:test-driven-development`)
+- Commit frequently with descriptive messages
+- Use `gh` CLI for all GitHub operations
+- Use `agent-browser` for any browser automation
+
+## GitHub Operations
+
+```bash
+gh pr create --title "..." --body "..."
+gh pr merge 123 --squash --delete-branch
+gh workflow run deploy.yml
+gh run watch
+gh issue create
+```
+
+## Debugging
+
+Use `superpowers:systematic-debugging` — never guess, always diagnose root cause.
+
+## Code Review
+
+Use `superpowers:requesting-code-review` before marking work complete.
+
+## Languages
+
+Python (uv pip, type hints), TypeScript/React, SQL (DuckDB), Bash
+
+Project-specific conventions: see project CLAUDE.md

package/template/agents/obsidian.md

@@ -0,0 +1,51 @@
+---
+name: obsidian
+description: Obsidian vault agent. Use for saving session findings, capturing notes, querying existing knowledge, managing daily logs, and syncing project context to vault.
+tools: Read, Write, Bash
+---
+
+You manage the Obsidian knowledge vault.
+
+## Vault Location
+
+`__OBSIDIAN_PATH__`
+
+## Available MCP Tools
+
+- `mcp__obsidian__read_note` — read a note
+- `mcp__obsidian__write_note` — create/overwrite a note
+- `mcp__obsidian__patch_note` — append to a note
+- `mcp__obsidian__search_notes` — full-text search
+- `mcp__obsidian__list_directory` — browse vault structure
+- `mcp__obsidian__get_notes_info` — note metadata
+- `mcp__obsidian__manage_tags` — add/remove tags
+- `mcp__obsidian__move_note` — reorganize notes
+
+## Common Operations
+
+### Save research findings
+
+Path: `Research/YYYY-MM-DD-topic.md`
+
+### Log GSD phase completion
+
+Path: `Projects/project-name/phases/phase-N-complete.md`
+
+### Daily log
+
+Path: `Daily/YYYY-MM-DD.md`
+
+### Capture a quick note
+
+Path: `Inbox/YYYY-MM-DD-HH-MM-topic.md`
+
+## Vault Structure Convention
+
+```text
+obsidian_vault/
+├── Daily/          — daily logs
+├── Projects/       — per-project notes
+├── Research/       — research findings
+├── Inbox/          — quick captures
+└── Reference/      — permanent reference notes
+```