azclaude-copilot 0.1.0

package/templates/commands/setup.md

@@ -0,0 +1,97 @@
+---
+name: setup
+description: Analyze the project, fill CLAUDE.md, create memory structure. Run once at project start or to fill unfilled placeholders.
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# /setup — Project Environment Setup
+
+Current environment:
+!`bash .claude/scripts/env-scan.sh 2>/dev/null || echo '{"note": "run npx azclaude first to install scripts"}'`
+
+---
+
+## Step 1: Scan
+
+Check for project signals:
+```bash
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
+find . -name "*.ts" -o -name "*.py" -o -name "*.rs" | head -5 2>/dev/null
+ls knowledge/ docs/ 2>/dev/null
+```
+
+Read existing CLAUDE.md if present — note which fields are unfilled placeholders.
+
+---
+
+## Step 2: Clarify (if domain is ambiguous)
+
+If the scan cannot determine domain clearly (e.g. mixed signals, no code files, empty project):
+Use **AskUserQuestion** to collect:
+- **Domain**: developer / writer / researcher / compliance / data-ML / other
+- **Primary language / stack** (if developer)
+- **Team size**: solo / small team / org
+- **What's the main goal of this project?**
+
+Skip this step if the scan already answers these clearly.
+
+---
+
+## Step 3: Track Setup Progress
+
+**TaskCreate** for each step before starting:
+- `Scan project` (mark completed after Step 1)
+- `Fill CLAUDE.md`
+- `Create memory structure`
+- `Create skills`
+- `Run quality check`
+
+**TaskUpdate → in_progress** as each step begins.
+
+---
+
+## Step 4: Spawn Initialization Specialist
+
+Spawn `agents/orchestrator-init.md` as a subagent with:
+- Current working directory
+- Domain and stack (from scan or AskUserQuestion answers)
+- Project scale (file count)
+- Existing CLAUDE.md content (to avoid overwriting intentional config)
+
+The orchestrator-init agent:
+- Detects scale, domain, and signals
+- Fills CLAUDE.md
+- Creates `.claude/memory/goals.md`
+- Creates `knowledge-index.md` if `knowledge/` directory exists
+- Runs environment scan as a single script (not 15 separate calls)
+
+**TaskUpdate → completed** for Fill CLAUDE.md and Create memory structure steps.
+
+---
+
+## Step 5: Quality Gate
+
+Load `capabilities/shared/quality-check.md` and run the full environment check.
+
+**TaskUpdate → completed** for Run quality check.
+
+All ✓ required before printing "Setup complete."
+
+---
+
+## If Running Again on an Existing Project
+
+Do not overwrite CLAUDE.md — read it first and update only the placeholders that are still unfilled.
+Do not overwrite goals.md — read it and preserve existing threads.
+
+---
+
+## Completion Rule
+
+Show:
+1. Filled CLAUDE.md (full content)
+2. Created goals.md (full content)
+3. All TaskUpdate items marked completed
+
+Do not say "setup complete" without showing these outputs.

package/templates/commands/ship.md

@@ -0,0 +1,131 @@
+---
+name: ship
+description: >
+  Stage changes, commit, and push to GitHub. Pre-ship gate: IDE diagnostics + tests must pass.
+  Triggers on: "ship", "push", "commit and push", "deploy", "send to GitHub", "save and push".
+  Skips .env and secrets automatically. Never ships with failing tests or IDE errors.
+argument-hint: "[optional: commit message hint]"
+disable-model-invocation: true
+allowed-tools: Bash, Read
+---
+
+# /ship — Save and Push to GitHub
+
+$ARGUMENTS
+
+---
+
+## Pre-Ship Gate (runs before any commit)
+
+**1. IDE diagnostics** — use `mcp__ide__getDiagnostics` if available.
+If unavailable or empty: skip this check.
+If errors exist: STOP.
+```
+✗ Pre-ship blocked: {N} IDE errors. Fix with /fix before shipping.
+```
+
+**2. Tests**
+```bash
+{test command}; EXIT=$?
+echo "Exit: $EXIT"
+```
+If EXIT ≠ 0: STOP.
+```
+✗ Pre-ship blocked: tests failing. Run /test to fix.
+```
+
+If both pass: `✓ Pre-ship gate passed`
+
+---
+
+## Step 0.5: Docs Sync (runs before commit)
+
+Check for stale documentation — 3 quick greps, no file reads required:
+
+```bash
+# 1. Version in README matches package.json?
+README_VER=$(grep -oE '[0-9]+\.[0-9]+\.[0-9]+' README.md 2>/dev/null | head -1)
+PKG_VER=$(node -p "require('./package.json').version" 2>/dev/null)
+[ "$README_VER" != "$PKG_VER" ] && echo "⚠ README version ($README_VER) ≠ package.json ($PKG_VER) — update README"
+
+# 2. Command count in README matches installed commands?
+README_CMDS=$(grep -oE '[0-9]+ commands?' README.md 2>/dev/null | grep -oE '[0-9]+' | head -1)
+ACTUAL_CMDS=$(ls .claude/commands/*.md 2>/dev/null | wc -l | tr -d ' ')
+[ -n "$README_CMDS" ] && [ "$README_CMDS" != "$ACTUAL_CMDS" ] && echo "⚠ README says $README_CMDS commands, found $ACTUAL_CMDS"
+
+# 3. Known stale risk section?
+grep -q "bash.*Windows\|Git Bash.*fail" README.md 2>/dev/null && echo "⚠ README still has stale bash/Windows risk — update to Node.js hooks"
+```
+
+If any warnings fire: update README before committing.
+If README does not exist or all checks pass: skip.
+
+---
+
+## Step 1: Show What Will Ship
+
+```bash
+git status --short
+git diff --stat HEAD
+```
+
+---
+
+## Step 2: Secret Scan
+
+```bash
+git status --short | grep -iE "\.env|secret|credential|\.key|token|password"
+```
+
+If found: warn and skip those files. Never stage secrets.
+
+---
+
+## Step 3: Stage and Commit
+
+Stage changed files — never `.env`, secrets, `node_modules`.
+
+Generate commit message:
+- Format: `{type}: {what changed} — {why}`
+- Types: `feat` / `fix` / `refactor` / `docs` / `chore`
+- Lead with impact ("add user auth" not "update auth.ts")
+- Use $ARGUMENTS hint if provided
+
+If not a git repo: run `git init` first.
+
+---
+
+## Step 4: Push
+
+If remote exists: `git push`
+
+If no remote:
+```
+git remote add origin https://github.com/{username}/{repo}.git
+git push -u origin main
+```
+
+---
+
+## Step 5: Deploy (Copilot Mode Only)
+
+```bash
+[ -f .claude/copilot-intent.md ] && echo "COPILOT_MODE" || echo "INTERACTIVE_MODE"
+```
+
+If `COPILOT_MODE` and the intent mentions deploy targets (Vercel, Railway, Netlify, etc.):
+1. Check if deploy config exists (vercel.json, railway.json, netlify.toml, Dockerfile)
+2. If config exists → run the deploy command (`vercel --prod`, `railway up`, etc.)
+3. If deploy succeeds → record URL in `.claude/copilot-report.md`
+4. If deploy fails → log to `.claude/memory/blockers.md`, continue (product is still built)
+5. If no deploy target mentioned → skip deployment, push is sufficient
+
+If `INTERACTIVE_MODE`: skip Step 5.
+
+---
+
+## Completion Rule
+
+Show: files changed, commit hash, branch, push status.
+If no changes: "Nothing to ship — working tree is clean."
+Do not say "shipped" without showing the push output.

package/templates/commands/snapshot.md

@@ -0,0 +1,70 @@
+---
+name: snapshot
+description: Mid-session snapshot — captures current reasoning, decisions, and state to survive context compaction. Run every 15-20 turns on complex work. Auto-injected on next session start.
+argument-hint: "[optional: topic label]"
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit
+---
+
+# /snapshot — Mid-Session Snapshot
+
+**Purpose**: Write your current mental model to disk NOW, before context compaction loses it.
+This is different from `/persist` (end-of-session). Checkpoint = mid-flight snapshot.
+
+---
+
+## Step 1: Read Current State
+
+Read `.claude/memory/goals.md` — scan the "In progress" entries and "Current threads."
+
+---
+
+## Step 2: Write Checkpoint File
+
+Write `.claude/memory/checkpoints/{YYYY-MM-DD}-{HH:MM}.md`:
+
+```markdown
+---
+date: {ISO datetime}
+label: {$ARGUMENTS or "mid-session"}
+files_in_progress: [{list from goals.md ## In progress}]
+---
+
+## What I'm doing right now
+{1-2 sentences: the specific task in flight, not the project description}
+
+## Why — key decisions made this session
+{Bullet list: each decision + the reason. Example:}
+- Used spawnSync over exec: timeout needed, exec doesn't block
+- Skipped STRUCTURE-ONLY on SKIM projects: blueprint.json already has scale field
+
+## What I know that isn't written down yet
+{Anything in working memory that hasn't been committed to a file or comment}
+
+## What's next (top 3)
+1. {next concrete action}
+2.
+3.
+
+## Risk / open question
+{Anything uncertain that needs resolution — or "None"}
+```
+
+Create the directory if needed: `.claude/memory/checkpoints/`
+
+---
+
+## Step 3: Update goals.md
+
+Add one line to the top of `## Current threads`:
+```
+- [checkpoint] {HH:MM} — {label} → .claude/memory/checkpoints/{date}-{HH:MM}.md
+```
+
+---
+
+## Step 4: Confirm
+
+Print the checkpoint file content.
+Print: `Checkpoint saved. Inject on next session start: UserPromptSubmit will load the latest checkpoint automatically.`
+Do NOT say "checkpoint saved" without showing the content.

package/templates/commands/test.md

@@ -0,0 +1,86 @@
+---
+name: test
+description: >
+  Run the test suite, interpret results, and fix failures.
+  Triggers on: "run tests", "test this", "check tests", "tests failing", "are tests passing",
+  "run the suite", "test file X", "why is X test failing", "test before ship".
+  Checks IDE diagnostics first — type errors cause test failures.
+argument-hint: "[test file, test name, or blank for full suite]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Grep
+---
+
+# /test — Run and Interpret Tests
+
+$ARGUMENTS
+
+---
+
+## Step 1: IDE Diagnostics First
+
+Use `mcp__ide__getDiagnostics` if available.
+
+If it returns errors:
+```
+IDE errors found — these will cause test failures. Fix first:
+  file:line — message
+```
+If unavailable or returns empty: skip this step and proceed to Step 2.
+
+Type errors and import failures cause misleading test output — clear them before running.
+
+---
+
+## Step 2: Detect Test Framework
+
+```bash
+grep -E '"test":|"jest"|"vitest"|"mocha"|"playwright"' package.json 2>/dev/null | head -3
+grep -E "pytest|unittest" requirements.txt pyproject.toml 2>/dev/null | head -3
+ls Cargo.toml go.mod 2>/dev/null
+```
+
+Use the framework already in the project. Never introduce a new one.
+
+---
+
+## Step 3: Run Tests
+
+Scope:
+- $ARGUMENTS = specific file → run that file only
+- $ARGUMENTS = test name → run matching test
+- blank → run the full suite
+
+```bash
+{test command} {scope}; EXIT=$?
+echo "Exit: $EXIT"
+```
+
+Paste the **full output** — never summarize it.
+
+---
+
+## Step 4: Interpret Results
+
+**If EXIT = 0**: Report `Tests: {N} passed, 0 failed` — done.
+
+**If EXIT ≠ 0**: For each failing test:
+1. Name the test exactly
+2. Map to `file:line`
+3. Classify:
+   - **Compile/type error** → fix IDE errors first (Step 1)
+   - **Assertion failure** → go to /fix Phase 2 at `file:line`
+   - **Timeout** → check for async issues, missing mocks
+   - **Not found / import error** → check module paths
+
+Fix one failing test at a time — not all at once.
+Apply /fix self-correction loop for each: 2 attempts, then escalate.
+
+---
+
+## Completion Rule
+
+Show the full test output.
+State: `Tests: {N} passed, {M} failed`.
+
+If failures remain: list each with `file:line` — stay in progress.
+Do not report "tests done" with failures open.

package/templates/hooks/post-tool-use.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * AZCLAUDE — PostToolUse hook
+ * Tracks edits to goals.md after every Write/Edit.
+ * Captures: timestamp, file path, git diff stat (+N/-N), and change summary.
+ * Survives Claude Code context compaction — goals.md is the external memory.
+ * No user action required. Silent. Works on Windows/macOS/Linux.
+ */
+const fs            = require('fs');
+const path          = require('path');
+const os            = require('os');
+const { spawnSync } = require('child_process');
+
+// ── Hook profile gate ───────────────────────────────────────────────────────
+// AZCLAUDE_HOOK_PROFILE=minimal|standard|strict (default: standard)
+// minimal = goals.md tracking only (no observations, no cost tracking)
+// standard = all features (default)
+// strict = all features + extra validation
+const HOOK_PROFILE = process.env.AZCLAUDE_HOOK_PROFILE || 'standard';
+
+// Read tool input + response from stdin — Claude Code sends JSON and closes stdin
+let filePath = '';
+let changeSummary = '';
+try {
+  const raw  = fs.readFileSync(0, 'utf8'); // fd 0 = stdin, cross-platform
+  const data = JSON.parse(raw);
+  filePath   = data.tool_input?.file_path || data.tool_input?.path || '';
+  // Extract change summary from old_string/new_string diff hint (Edit tool)
+  const oldStr = data.tool_input?.old_string || '';
+  const newStr = data.tool_input?.new_string || '';
+  if (oldStr && newStr) {
+    // Summarize: first non-empty line of new content (what was added)
+    const firstNew = newStr.split('\n').find(l => l.trim().length > 0) || '';
+    if (firstNew.length > 0 && firstNew.length < 80) {
+      changeSummary = ' — ' + firstNew.trim().replace(/^[-*#`]+\s*/, '').slice(0, 60);
+    }
+  }
+} catch (_) {}
+
+// Also accept env var fallback (older Claude Code versions)
+if (!filePath) filePath = process.env.CLAUDE_FILE_PATH || '';
+if (!filePath) process.exit(0);
+
+// Guard: skip memory files (prevent write loop), skip non-project paths
+const rel = path.relative(process.cwd(), path.resolve(filePath));
+if (rel.startsWith('..'))                           process.exit(0); // outside project
+if (/goals\.md$/.test(rel))                         process.exit(0); // prevent loop
+if (/node_modules[\\/]|\.git[\\/]/.test(rel))       process.exit(0); // noise
+
+const cfg       = process.env.AZCLAUDE_CFG || '.claude';
+// Guard: cfg must resolve inside the project root
+if (path.resolve(cfg).indexOf(process.cwd()) !== 0) process.exit(0);
+const goalsPath = path.join(cfg, 'memory', 'goals.md');
+if (!fs.existsSync(goalsPath)) process.exit(0); // not an AZCLAUDE project
+
+// Timestamp HH:MM
+const now = new Date();
+const ts  = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+
+// Git diff stat: "+N/-M" — cached for 5s to avoid repeated git calls on consecutive edits
+let diffStat = '';
+const diffCachePath = path.join(os.tmpdir(), `.azclaude-diff-${process.ppid || process.pid}`);
+let diffCache = {};
+try { diffCache = JSON.parse(fs.readFileSync(diffCachePath, 'utf8')); } catch (_) {}
+const cacheAge = Date.now() - (diffCache._ts || 0);
+const cached   = diffCache[rel];
+if (cached && cacheAge < 5000) {
+  diffStat = cached;
+} else {
+  try {
+    const r = spawnSync('git', ['diff', 'HEAD', '--numstat', '--', rel],
+      { encoding: 'utf8', cwd: process.cwd(), timeout: 3000 });
+    if (r.status === 0 && r.stdout.trim()) {
+      const [added, deleted] = r.stdout.trim().split('\t');
+      const a = parseInt(added, 10);
+      const d = parseInt(deleted, 10);
+      if (!isNaN(a) && !isNaN(d) && (a > 0 || d > 0)) {
+        diffStat = ` (+${a}/-${d})`;
+      }
+    }
+  } catch (_) {}
+  // Update cache
+  if (cacheAge >= 5000) diffCache = {};
+  diffCache[rel] = diffStat;
+  diffCache._ts  = Date.now();
+  try { fs.writeFileSync(diffCachePath, JSON.stringify(diffCache)); } catch (_) {}
+}
+
+const entry = `- ${ts} — ${rel}${diffStat}${changeSummary}`;
+
+let content = fs.readFileSync(goalsPath, 'utf8');
+
+const HEADING = '## In progress';
+
+if (!content.includes(HEADING)) {
+  // Add section at end
+  content = content.trimEnd() + `\n\n${HEADING}\n${entry}\n`;
+} else {
+  const lines  = content.split('\n');
+  const hIdx   = lines.findIndex(l => l.trim() === HEADING);
+
+  // Remove any existing entry for the same file (dedup — keep latest timestamp)
+  const cleaned = lines.filter((l, i) => {
+    if (i <= hIdx) return true;               // keep heading and everything before
+    if (!l.startsWith('- ')) return true;     // keep non-entry lines
+    return !l.includes(rel);                  // remove old entry for this file
+  });
+
+  // Insert new entry right after heading
+  cleaned.splice(hIdx + 1, 0, entry);
+  content = cleaned.join('\n');
+}
+
+try { fs.writeFileSync(goalsPath, content); } catch (_) {}
+
+// ── Reflex observation capture (standard/strict only) ───────────────────────
+// Append tool-use observation to observations.jsonl for pattern detection.
+// Lightweight: one JSON line per tool call. Secret patterns scrubbed.
+if (HOOK_PROFILE !== 'minimal') {
+  const reflexDir = path.join(cfg, 'memory', 'reflexes');
+  try {
+    fs.mkdirSync(reflexDir, { recursive: true });
+    const obsPath = path.join(reflexDir, 'observations.jsonl');
+    const obsTs   = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const tool    = 'Edit'; // PostToolUse matcher is Write|Edit
+    // Scrub secrets: strip API keys, tokens, passwords from file paths
+    const safeRel = rel.replace(/\.(env|key|pem|secret|credential)/gi, '.[REDACTED]');
+    const obs     = JSON.stringify({
+      ts: obsTs, tool, file: safeRel, session: process.ppid || process.pid, event: 'complete'
+    });
+    fs.appendFileSync(obsPath, obs + '\n');
+    // Auto-truncate: keep last 2000 lines max (prevent unbounded growth)
+    try {
+      const obsContent = fs.readFileSync(obsPath, 'utf8');
+      const obsLines   = obsContent.split('\n').filter(Boolean);
+      if (obsLines.length > 2000) {
+        fs.writeFileSync(obsPath, obsLines.slice(-500).join('\n') + '\n');
+      }
+    } catch (_) {}
+  } catch (_) {}
+}
+
+// ── Cost tracking (standard/strict only) ────────────────────────────────────
+// Append estimated cost per tool call to costs.jsonl for budget awareness.
+if (HOOK_PROFILE !== 'minimal') {
+  try {
+    const costsDir = path.join(cfg, 'memory', 'metrics');
+    fs.mkdirSync(costsDir, { recursive: true });
+    const costsPath = path.join(costsDir, 'costs.jsonl');
+    const costEntry = JSON.stringify({
+      ts: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+      tool: 'Edit',
+      file: rel,
+      session: process.ppid || process.pid
+    });
+    fs.appendFileSync(costsPath, costEntry + '\n');
+    // Auto-truncate: keep last 1000 entries
+    try {
+      const costLines = fs.readFileSync(costsPath, 'utf8').split('\n').filter(Boolean);
+      if (costLines.length > 1000) {
+        fs.writeFileSync(costsPath, costLines.slice(-500).join('\n') + '\n');
+      }
+    } catch (_) {}
+  } catch (_) {}
+}
+
+// ── Checkpoint reminder every 15 edits ──────────────────────────────────────
+const counterPath = path.join(os.tmpdir(), `.azclaude-edit-count-${process.ppid || process.pid}`);
+let editCount = 1;
+try { editCount = parseInt(fs.readFileSync(counterPath, 'utf8'), 10) + 1; } catch (_) {}
+try { fs.writeFileSync(counterPath, String(editCount)); } catch (_) {}
+if (editCount > 0 && editCount % 15 === 0) {
+  process.stdout.write(`\n⚠ ${editCount} edits this session — run /snapshot before context compaction loses your reasoning\n`);
+}

package/templates/hooks/stop.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * AZCLAUDE — Stop hook
+ * Runs at end of every session.
+ * 1. Migrates "In progress" entries → "Done this session"
+ * 2. Stamps goals.md with today's date
+ * 3. Writes friction stub if /persist was not run
+ * Works on: Windows (PowerShell/CMD/Git Bash), macOS, Linux.
+ */
+const fs   = require('fs');
+const path = require('path');
+
+// ── Hook profile gate ───────────────────────────────────────────────────────
+// AZCLAUDE_HOOK_PROFILE=minimal|standard|strict (default: standard)
+const HOOK_PROFILE = process.env.AZCLAUDE_HOOK_PROFILE || 'standard';
+
+const cfg       = process.env.AZCLAUDE_CFG || '.claude';
+// Guard: cfg must resolve inside the project root
+if (path.resolve(cfg).indexOf(process.cwd()) !== 0) process.exit(0);
+const goalsPath = path.join(cfg, 'memory', 'goals.md');
+
+if (!fs.existsSync(goalsPath)) process.exit(0);
+
+const today   = new Date().toISOString().slice(0, 10);
+let   content = fs.readFileSync(goalsPath, 'utf8');
+
+// ── Migrate "In progress" → "Done this session" ──────────────────────────────
+const IN_PROGRESS = '## In progress';
+const DONE        = '## Done this session';
+
+if (content.includes(IN_PROGRESS)) {
+  const lines    = content.split('\n');
+  const ipIdx    = lines.findIndex(l => l.trim() === IN_PROGRESS);
+  const doneIdx  = lines.findIndex(l => l.trim() === DONE);
+
+  // Collect entries under ## In progress (lines starting with "- " until next ##)
+  const ipEntries = [];
+  for (let i = ipIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ')) break;
+    if (lines[i].startsWith('- ')) ipEntries.push(lines[i]);
+  }
+
+  if (ipEntries.length > 0) {
+    // Remove ## In progress section entirely
+    const withoutIP = [];
+    let skip = false;
+    for (const line of lines) {
+      if (line.trim() === IN_PROGRESS) { skip = true; continue; }
+      if (skip && line.startsWith('## ')) skip = false;
+      if (!skip) withoutIP.push(line);
+    }
+
+    // Add entries to ## Done this session
+    const dIdx = withoutIP.findIndex(l => l.trim() === DONE);
+    if (dIdx !== -1) {
+      withoutIP.splice(dIdx + 1, 0, ...ipEntries);
+    } else {
+      // No Done section — create one
+      withoutIP.push('', DONE, ...ipEntries);
+    }
+
+    content = withoutIP.join('\n');
+  } else {
+    // Empty In progress — just remove the heading
+    content = content.replace(`\n${IN_PROGRESS}\n`, '\n');
+  }
+}
+
+// ── Stamp today's date ────────────────────────────────────────────────────────
+content = content.replace(/^Updated: .*/m, `Updated: ${today}`);
+try { fs.writeFileSync(goalsPath, content); } catch (_) {}
+
+// ── Warn if /persist was not run (only in AZCLAUDE projects with obs dir) ──
+const obsDir = path.join('ops', 'observations');
+if (!fs.existsSync(obsDir)) process.exit(0);
+const todayStamp = today.replace(/-/g, '');
+try {
+  const existing = fs.readdirSync(obsDir).filter(f => f.startsWith(todayStamp) && f.endsWith('-friction.md'));
+  if (existing.length === 0) {
+    process.stdout.write('⚠ session state not persisted — run /persist before closing\n');
+  }
+} catch (_) {
+  // obs dir doesn't exist yet — that's fine
+}