@whitehatd/crag 0.0.1 → 0.2.0

package/src/crag-agent.md

@@ -0,0 +1,254 @@
+---
+name: crag-project
+description: Generate Claude Code infrastructure from an interactive interview. Installs universal skills, generates project-specific governance, hooks, and agents.
+tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Edit
+model: opus
+---
+
+# Crag — Project Generator
+
+**START IMMEDIATELY.** When the user sends any message (even "go", "start", or empty), begin the interview. Do not wait for instructions. Do not explain what you are — just start asking questions.
+
+You are crag's interview agent. Interview the user about their project, then generate the infrastructure layer — governance rules, hooks, agents, and settings. The universal skills (pre-start, post-start) are already installed by the CLI.
+
+## What You Generate vs What Ships
+
+**Ships with crag (universal, same for everyone):**
+- `pre-start-context` skill — discovers any project at runtime
+- `post-start-validation` skill — validates any project using governance gates
+
+**You generate (project-specific, from interview):**
+- `governance.md` — the user's rules, quality bar, policies
+- Hook scripts — configured for their tools
+- Agent definitions — configured for their test/build commands
+- Settings — permissions + hook wiring
+- CI playbook template — based on their CI/CD
+- MemStack rules — if enabled
+- Session name — if remote access enabled
+
+## Phase 1: Interview
+
+Ask ONE question at a time. Wait for the answer. Adapt follow-ups. Skip obvious ones.
+
+### 1.1 Project Identity
+- Project name? (used for MemStack, session-name, commit references)
+- One-line description?
+
+### 1.2 Tech Stack
+- Backend: language + framework? (Java/Spring, Node/Express, Python/FastAPI, Go, Rust, etc.)
+- Frontend: framework? (Next.js, React+Vite, Vue, Svelte, none)
+- Database? (PostgreSQL, MySQL, MongoDB, SQLite, Redis, etc.)
+- Build system? (Gradle, Maven, npm, pnpm, cargo, pip, etc.)
+
+### 1.3 Architecture
+- Monolith or microservices? If micro: how many, names?
+- Monorepo or multi-repo?
+
+### 1.4 Deployment
+- How deployed? (Docker Compose, Kubernetes, Vercel, Fly.io, bare metal)
+- CI/CD? (GitHub Actions, GitLab CI, none)
+- Deploy strategy? (blue-green, rolling, recreate)
+
+### 1.5 Quality Bar
+- Testing? (framework + philosophy: TDD, integration, e2e, minimal)
+- Linting? (Biome, ESLint, Checkstyle, Clippy, ruff)
+- Type checking? (TypeScript strict, mypy, Java types)
+- Formatter? (Biome, Prettier, google-java-format, rustfmt, ruff)
+
+### 1.6 Security
+- Auth? (JWT, OAuth, session, API key, none)
+- Rate limiting? (yes/no, what tool)
+- File uploads? (yes/no, scanning?)
+- Security headers? (CSP, HSTS)
+
+### 1.7 Workflow
+- Branch strategy? (feature branches, trunk-based)
+- Commit convention? (conventional, free-form)
+- Git auth? (GITHUB_TOKEN, gh CLI, SSH key)
+- Autonomy: auto-commit after gates, or ask first?
+
+### 1.8 Session Management
+- Remote phone access? (yes/no)
+- If yes: tmux session name?
+- MemStack for cross-session memory? (yes/no)
+
+## Phase 2: Generate
+
+### 2.1 Universal Skills — DO NOT REGENERATE
+
+The CLI (`crag init`) already installed the universal skills before launching you. They exist at:
+- `.claude/skills/pre-start-context/SKILL.md`
+- `.claude/skills/post-start-validation/SKILL.md`
+- `.agents/workflows/pre-start-context.md`
+- `.agents/workflows/post-start-validation.md`
+
+**Do NOT overwrite them.** Check that they exist with `ls`. If missing (user ran you directly, not via CLI), create the directories and tell the user to run `crag init` to install them properly.
+
+### 2.2 Generate governance.md
+
+Write `.claude/governance.md` from the interview answers:
+
+```markdown
+# Governance — [project name]
+# This file defines YOUR rules. The universal skills read it and adapt.
+# Change this when your standards change. The skills never go stale.
+
+## Identity
+- Project: [name]
+- Description: [one-liner]
+
+## Gates (run in order, stop on failure)
+### Frontend
+- [lint command]
+- [type check command]
+- [build command]
+- [test command]
+
+### Backend
+- [test command with flags]
+- [compile/check command]
+
+## Branch Strategy
+- [feature branches / trunk-based]
+- [conventional commits / free-form]
+- Commit trailer: Co-Authored-By: Claude <noreply@anthropic.com>
+
+## Security Requirements
+- Auth: [JWT / OAuth / API key / none]
+- [rate limiting rules if any]
+- [file upload rules if any]
+- [security header rules if any]
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Autonomy
+- [auto-commit after gates pass / ask before commit / ask before everything]
+
+## Deployment
+- Target: [Docker Compose / K8s / Vercel / etc.]
+- CI: [GitHub Actions / GitLab / none]
+- Strategy: [blue-green / rolling / recreate]
+- [Verification command if applicable: health check URL, kubectl status, etc.]
+
+## Conventions
+- [Any project-specific rules from the interview]
+```
+
+### 2.3 Generate Hooks
+
+Create `.claude/hooks/`:
+
+**drift-detector.sh** — always generate. Check for existence of key files based on detected stack:
+- If Gradle: check build.gradle.kts, settings.gradle.kts
+- If npm: check package.json, tsconfig.json
+- If Python: check pyproject.toml, requirements.txt
+- If Go: check go.mod
+- Check CI workflow files
+- Check Docker/K8s configs
+
+**circuit-breaker.sh** — always generate. Same for all projects.
+
+**auto-post-start.sh** — always generate. Gate enforcement safety net. Reads tool input from stdin, checks if the command is a `git commit`, warns if `.claude/.gates-passed` sentinel doesn't exist. Non-blocking (warns, doesn't prevent). Same for all projects.
+
+**sandbox-guard.sh** — always generate. Security hardening. Reads tool input from stdin (PreToolUse on Bash), hard-blocks destructive system commands (rm -rf /, dd, mkfs, DROP TABLE, docker system prune, kubectl delete namespace, curl|bash, force-push to main). Warns on file operations targeting paths outside the project root. Same for all projects.
+
+**pre-compact-snapshot.sh** — only if MemStack enabled. Use correct project name.
+
+**post-compact-recovery.sh** — only if MemStack enabled. Use correct project name.
+
+### 2.4 Generate Settings
+
+Write `.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      // RTK wildcards for detected tools
+      "Bash(rtk ./gradlew:*)",  // if Gradle
+      "Bash(rtk npm:*)",        // if npm
+      "Bash(rtk cargo:*)",      // if Rust
+      "Bash(rtk pytest:*)",     // if Python
+      "Bash(rtk git:*)",
+      "Bash(rtk gh:*)",
+      "Bash(rtk docker:*)",
+      "Bash(rtk curl:*)"
+    ]
+  },
+  "hooks": {
+    // Wire the generated hook scripts
+  }
+}
+```
+
+Include PostToolUse auto-format hook using the project's formatter (Biome, Prettier, rustfmt, etc.).
+
+Wire the security and gate hooks as PreToolUse for Bash (sandbox-guard runs FIRST):
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash",
+    "hooks": [
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/sandbox-guard.sh"
+      },
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/auto-post-start.sh"
+      }
+    ]
+  }
+]
+```
+
+### 2.5 Generate Agents
+
+Create `.claude/agents/`:
+
+**test-runner.md** — always. Use the project's test commands from governance.md.
+**security-reviewer.md** — always. Reference the project's security stack.
+**dependency-scanner.md** — if package manager exists.
+**skill-auditor.md** — always.
+
+All agents get `isolation: worktree`.
+
+### 2.6 Generate CI Playbook
+
+Write `.claude/ci-playbook.md` with empty sections for the project's CI system. Include the correct format template.
+
+### 2.7 MemStack Rules (if enabled)
+
+Generate `.claude/rules/knowledge.md`, `diary.md`, `echo.md` with the correct project name and Python path.
+
+### 2.8 Session Name (if remote access enabled)
+
+Write `.claude/.session-name` with the tmux session name.
+
+## Phase 3: Summary
+
+Present:
+- Files created (list)
+- Governance rules (count)
+- Hooks configured (list)
+- Agents defined (list)
+- Next step: "Run /pre-start-context to verify everything works"
+- Mention: "Run `crag compile --target all` to generate CI workflows and git hooks from your governance"
+
+## Rules
+
+1. ASK before generating. Never assume.
+2. The governance.md is the ONLY project-specific configuration. Everything else either ships universal or is derived from governance.
+3. Use the project's actual tool names.
+4. Generate for Windows (Git Bash syntax) unless told otherwise.
+5. If user references another project they've scaffolded — read that governance file for reference.
+6. **Check pwd before navigating.** Don't cd into a directory you're already in.
+7. **Don't regenerate universal skills.** The CLI installs them. Check if they exist, don't overwrite.
+8. **MemStack:** Ask the user if they have a shared MemStack DB installed and where. If yes, wire the generated rules to that path. Otherwise generate local SQLite rules or skip MemStack entirely.
+9. **Sandbox boundaries.** Never run destructive commands (rm -rf /, dd, mkfs, DROP TABLE, docker system prune -a, kubectl delete namespace). Only write files within .claude/ and the project directory. Never modify system files or global config. Generated hooks and agents must inherit these boundaries.
+10. **Subagent isolation.** All generated agent definitions must include a `## Boundaries` section stating: operate only within this repository, no destructive system commands, no network access beyond task requirements, no permission escalation.

package/src/governance/gate-to-shell.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Escape a string for safe inclusion inside double quotes in a shell command.
+ * Escapes: backslash, backtick, dollar sign, double quote.
+ */
+function shellEscapeDoubleQuoted(s) {
+  return String(s).replace(/[\\`"$]/g, '\\$&');
+}
+
+/**
+ * Convert human-readable gate descriptions to shell commands.
+ * e.g. Verify src/skills/pre-start-context.md contains "discovers any project"
+ *   → grep -qi "discovers any project" "src/skills/pre-start-context.md"
+ *
+ * All interpolated values are shell-escaped to prevent command injection.
+ */
+function gateToShell(cmd) {
+  const verify = cmd.match(/^Verify\s+(\S+)\s+contains\s+["']([^"']+)["']$/i);
+  if (verify) {
+    const needle = shellEscapeDoubleQuoted(verify[2]);
+    const file = shellEscapeDoubleQuoted(verify[1]);
+    return `grep -qi "${needle}" "${file}"`;
+  }
+  return cmd;
+}
+
+module.exports = { gateToShell, shellEscapeDoubleQuoted };

package/src/governance/parse.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * Governance parser v2 — backward-compatible with v1.
+ *
+ * New optional annotations:
+ *   ### Section (path: dir/)        — path-scoped gates
+ *   ### Section (if: file)          — conditional section
+ *   - command                       # [OPTIONAL]
+ *   ## Gates (inherit: root)        — inheritance marker
+ */
+
+// Defensive cap: governance files should be well under this size.
+// Protects against ReDoS on catastrophic-backtracking-prone regex.
+const MAX_CONTENT_SIZE = 256 * 1024; // 256 KB
+
+/**
+ * Extract a markdown section body by heading name.
+ * Starts after the first line matching `## <name>` (with optional trailing text),
+ * ends at the next `## ` heading or EOF. Returns the body string, or null if not found.
+ *
+ * Implemented via line-by-line scan to avoid regex backtracking on large inputs.
+ */
+function extractSection(content, name) {
+  const lines = content.split('\n');
+  const headingPrefix = `## ${name}`;
+  let start = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === headingPrefix || line.startsWith(headingPrefix + ' ') || line.startsWith(headingPrefix + '\t')) {
+      start = i + 1;
+      break;
+    }
+  }
+
+  if (start === -1) return null;
+
+  let end = lines.length;
+  for (let i = start; i < lines.length; i++) {
+    // Next top-level section (## but not ###)
+    if (/^## [^#]/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  return lines.slice(start, end).join('\n');
+}
+
+function parseGovernance(content) {
+  const result = {
+    name: '',
+    description: '',
+    gates: {},
+    runtimes: [],
+    inherit: null,
+    warnings: [],
+  };
+
+  if (typeof content !== 'string') {
+    result.warnings.push('Invalid content type (expected string)');
+    return result;
+  }
+  if (content.length > MAX_CONTENT_SIZE) {
+    result.warnings.push(`governance.md exceeds ${MAX_CONTENT_SIZE} bytes — truncating`);
+    content = content.slice(0, MAX_CONTENT_SIZE);
+  }
+
+  const nameMatch = content.match(/- Project:\s*(.+)/);
+  if (nameMatch) result.name = nameMatch[1].trim();
+
+  const descMatch = content.match(/- Description:\s*(.+)/);
+  if (descMatch) result.description = descMatch[1].trim();
+
+  // Check for inheritance marker: ## Gates (inherit: root)
+  const inheritMatch = content.match(/## Gates[^\n]*\(inherit:\s*(\w+)\)/);
+  if (inheritMatch) result.inherit = inheritMatch[1].trim();
+
+  // Extract the Gates section (ends at next ## heading or EOF).
+  // Splitting manually avoids potential catastrophic backtracking on large inputs.
+  const gatesBody = extractSection(content, 'Gates');
+  if (gatesBody) {
+    let section = 'default';
+    let sectionMeta = { path: null, condition: null };
+
+    for (const line of gatesBody.split('\n')) {
+      // Match ### Section or ### Section (path: dir/) or ### Section (if: file)
+      const sub = line.match(/^### (.+?)(?:\s*\((?:(path|if):\s*(.+?))\))?\s*$/);
+      if (sub) {
+        section = sub[1].trim().toLowerCase();
+        sectionMeta = { path: null, condition: null };
+        if (sub[2] === 'path') sectionMeta.path = sub[3].trim();
+        if (sub[2] === 'if') sectionMeta.condition = sub[3].trim();
+        result.gates[section] = {
+          commands: [],
+          path: sectionMeta.path,
+          condition: sectionMeta.condition,
+        };
+      } else if (line.match(/^\s*- [^[\s]/) && line.trim() !== '-') {
+        let cmd = line.replace(/^\s*- /, '').trim();
+        let classification = 'MANDATORY';
+
+        // Check for # [OPTIONAL] or # [MANDATORY] suffix
+        const classMatch = cmd.match(/\s*#\s*\[(MANDATORY|OPTIONAL|ADVISORY)\]\s*$/);
+        if (classMatch) {
+          classification = classMatch[1];
+          cmd = cmd.replace(/\s*#\s*\[(?:MANDATORY|OPTIONAL|ADVISORY)\]\s*$/, '').trim();
+        }
+
+        if (cmd) {
+          if (!result.gates[section]) {
+            result.gates[section] = { commands: [], path: null, condition: null };
+          }
+          result.gates[section].commands.push({ cmd, classification });
+        }
+      }
+    }
+  }
+
+  // Warn if no gates were found (helps users catch structural mistakes)
+  if (Object.keys(result.gates).length === 0) {
+    result.warnings.push('No gates found in governance.md. Expected: "## Gates" section with "- command" entries.');
+  }
+
+  // Detect runtimes from gate commands
+  const allCmds = Object.values(result.gates)
+    .flatMap(g => (g.commands || []).map(c => c.cmd))
+    .join(' ');
+  if (/\b(node|npm|npx|eslint|prettier|biome|vitest|jest|next)\b/.test(allCmds)) result.runtimes.push('node');
+  if (/\b(cargo|rustc|clippy|rustfmt)\b/.test(allCmds)) result.runtimes.push('rust');
+  if (/\b(python|pip|pytest|ruff|mypy|django)\b/.test(allCmds)) result.runtimes.push('python');
+  if (/\b(java|gradle|gradlew|maven|mvn)\b/.test(allCmds)) result.runtimes.push('java');
+  if (/\bgo (build|test|vet|lint)\b/.test(allCmds)) result.runtimes.push('go');
+  if (/\bdocker\b/.test(allCmds)) result.runtimes.push('docker');
+
+  return result;
+}
+
+/**
+ * Flatten v2 gates to v1 format for backward compat with compile targets.
+ * Returns { sectionName: ['cmd1', 'cmd2'] } — classification and metadata are lost.
+ * Use flattenGatesRich() when you need annotations.
+ */
+function flattenGates(gates) {
+  const flat = {};
+  if (!gates || typeof gates !== 'object') return flat;
+  for (const [section, data] of Object.entries(gates)) {
+    if (!data || typeof data !== 'object') continue;
+    const cmds = Array.isArray(data.commands) ? data.commands : [];
+    flat[section] = cmds
+      .filter(c => c && typeof c.cmd === 'string' && c.cmd.trim())
+      .map(c => c.cmd);
+  }
+  return flat;
+}
+
+/**
+ * Flatten v2 gates preserving metadata.
+ * Returns an array of { section, cmd, classification, path, condition } in order.
+ */
+function flattenGatesRich(gates) {
+  const out = [];
+  if (!gates || typeof gates !== 'object') return out;
+  for (const [section, data] of Object.entries(gates)) {
+    if (!data || typeof data !== 'object') continue;
+    const cmds = Array.isArray(data.commands) ? data.commands : [];
+    for (const c of cmds) {
+      if (!c || typeof c.cmd !== 'string' || !c.cmd.trim()) continue;
+      out.push({
+        section,
+        cmd: c.cmd,
+        classification: c.classification || 'MANDATORY',
+        path: data.path || null,
+        condition: data.condition || null,
+      });
+    }
+  }
+  return out;
+}
+
+module.exports = { parseGovernance, flattenGates, flattenGatesRich, extractSection };