maxsimcli 4.8.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxsimcli",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "private": false,
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by MayStudios.",
   "bin": {

package/dist/assets/hooks/maxsim-context-monitor.cjs

@@ -1,121 +0,0 @@
-#!/usr/bin/env node
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
-let node_fs = require("node:fs");
-node_fs = __toESM(node_fs);
-let node_os = require("node:os");
-node_os = __toESM(node_os);
-let node_path = require("node:path");
-node_path = __toESM(node_path);
-
-//#region src/hooks/shared.ts
-/**
-* Shared utilities for MAXSIM hooks.
-*/
-/**
-* Read all stdin as a string, then invoke callback with parsed JSON.
-* Used by context-monitor and statusline hooks.
-*/
-function readStdinJson(callback) {
-	let input = "";
-	process.stdin.setEncoding("utf8");
-	process.stdin.on("data", (chunk) => input += chunk);
-	process.stdin.on("end", () => {
-		try {
-			callback(JSON.parse(input));
-		} catch {
-			process.exit(0);
-		}
-	});
-}
-
-//#endregion
-//#region src/hooks/maxsim-context-monitor.ts
-/**
-* Context Monitor - PostToolUse hook
-* Reads context metrics from the statusline bridge file and injects
-* warnings when context usage is high.
-*/
-const WARNING_THRESHOLD = 35;
-const CRITICAL_THRESHOLD = 25;
-const STALE_SECONDS = 60;
-const DEBOUNCE_CALLS = 5;
-function processContextMonitor(data) {
-	const sessionId = data.session_id;
-	if (!sessionId) return null;
-	const tmpDir = node_os.tmpdir();
-	const metricsPath = node_path.join(tmpDir, `claude-ctx-${sessionId}.json`);
-	if (!node_fs.existsSync(metricsPath)) return null;
-	const metrics = JSON.parse(node_fs.readFileSync(metricsPath, "utf8"));
-	const now = Math.floor(Date.now() / 1e3);
-	if (metrics.timestamp && now - metrics.timestamp > STALE_SECONDS) return null;
-	const remaining = metrics.remaining_percentage;
-	const usedPct = metrics.used_pct;
-	if (remaining > WARNING_THRESHOLD) return null;
-	const warnPath = node_path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
-	let warnData = {
-		callsSinceWarn: 0,
-		lastLevel: null
-	};
-	let firstWarn = true;
-	if (node_fs.existsSync(warnPath)) try {
-		warnData = JSON.parse(node_fs.readFileSync(warnPath, "utf8"));
-		firstWarn = false;
-	} catch {}
-	warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
-	const isCritical = remaining <= CRITICAL_THRESHOLD;
-	const currentLevel = isCritical ? "critical" : "warning";
-	const severityEscalated = currentLevel === "critical" && warnData.lastLevel === "warning";
-	if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-		node_fs.writeFileSync(warnPath, JSON.stringify(warnData));
-		return null;
-	}
-	warnData.callsSinceWarn = 0;
-	warnData.lastLevel = currentLevel;
-	node_fs.writeFileSync(warnPath, JSON.stringify(warnData));
-	let message;
-	if (isCritical) message = `CONTEXT MONITOR CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. If using MAXSIM, run /maxsim:pause-work to save execution state.`;
-	else message = `CONTEXT MONITOR WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. Begin wrapping up current task. Do not start new complex work. If using MAXSIM, consider /maxsim:pause-work to save state.`;
-	return { hookSpecificOutput: {
-		hookEventName: "PostToolUse",
-		additionalContext: message
-	} };
-}
-if (require.main === module) readStdinJson((data) => {
-	const result = processContextMonitor(data);
-	if (result) process.stdout.write(JSON.stringify(result));
-});
-
-//#endregion
-exports.CRITICAL_THRESHOLD = CRITICAL_THRESHOLD;
-exports.DEBOUNCE_CALLS = DEBOUNCE_CALLS;
-exports.STALE_SECONDS = STALE_SECONDS;
-exports.WARNING_THRESHOLD = WARNING_THRESHOLD;
-exports.processContextMonitor = processContextMonitor;
-//# sourceMappingURL=maxsim-context-monitor.cjs.map

package/dist/assets/hooks/maxsim-context-monitor.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"maxsim-context-monitor.cjs","names":["os","path","fs"],"sources":["../../../src/hooks/shared.ts","../../../src/hooks/maxsim-context-monitor.ts"],"sourcesContent":["/**\n * Shared utilities for MAXSIM hooks.\n */\n\n/**\n * Read all stdin as a string, then invoke callback with parsed JSON.\n * Used by context-monitor and statusline hooks.\n */\nexport function readStdinJson<T>(callback: (data: T) => void): void {\n  let input = '';\n  process.stdin.setEncoding('utf8');\n  process.stdin.on('data', (chunk: string) => (input += chunk));\n  process.stdin.on('end', () => {\n    try {\n      const data = JSON.parse(input) as T;\n      callback(data);\n    } catch {\n      // Silent fail -- never block hook execution\n      process.exit(0);\n    }\n  });\n}\n\n/** The '.claude' path segment -- template marker replaced during install. */\nexport const CLAUDE_DIR = '.claude';\n","#!/usr/bin/env node\n/**\n * Context Monitor - PostToolUse hook\n * Reads context metrics from the statusline bridge file and injects\n * warnings when context usage is high.\n */\n\nimport * as fs from 'node:fs';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport { readStdinJson, CLAUDE_DIR } from './shared';\n\nexport const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%\nexport const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%\nexport const STALE_SECONDS = 60;      // ignore metrics older than 60s\nexport const DEBOUNCE_CALLS = 5;      // min tool uses between warnings\n\nexport interface ContextMonitorInput {\n  session_id?: string;\n}\n\nexport interface ContextMonitorOutput {\n  hookSpecificOutput: {\n    hookEventName: string;\n    additionalContext: string;\n  };\n}\n\ninterface BridgeMetrics {\n  session_id: string;\n  remaining_percentage: number;\n  used_pct: number;\n  timestamp: number;\n}\n\ninterface WarnState {\n  callsSinceWarn: number;\n  lastLevel: string | null;\n}\n\nexport function processContextMonitor(data: ContextMonitorInput): ContextMonitorOutput | null {\n  const sessionId = data.session_id;\n\n  if (!sessionId) {\n    return null;\n  }\n\n  const tmpDir = os.tmpdir();\n  const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);\n\n  // If no metrics file, this is a subagent or fresh session -- exit silently\n  if (!fs.existsSync(metricsPath)) {\n    return null;\n  }\n\n  const metrics: BridgeMetrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));\n  const now = Math.floor(Date.now() / 1000);\n\n  // Ignore stale metrics\n  if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {\n    return null;\n  }\n\n  const remaining = metrics.remaining_percentage;\n  const usedPct = metrics.used_pct;\n\n  // No warning needed\n  if (remaining > WARNING_THRESHOLD) {\n    return null;\n  }\n\n  // Debounce: check if we warned recently\n  const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);\n  let warnData: WarnState = { callsSinceWarn: 0, lastLevel: null };\n  let firstWarn = true;\n\n  if (fs.existsSync(warnPath)) {\n    try {\n      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));\n      firstWarn = false;\n    } catch {\n      // Corrupted file, reset\n    }\n  }\n\n  warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;\n\n  const isCritical = remaining <= CRITICAL_THRESHOLD;\n  const currentLevel = isCritical ? 'critical' : 'warning';\n\n  // Emit immediately on first warning, then debounce subsequent ones\n  // Severity escalation (WARNING -> CRITICAL) bypasses debounce\n  const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';\n  if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {\n    // Update counter and exit without warning\n    fs.writeFileSync(warnPath, JSON.stringify(warnData));\n    return null;\n  }\n\n  // Reset debounce counter\n  warnData.callsSinceWarn = 0;\n  warnData.lastLevel = currentLevel;\n  fs.writeFileSync(warnPath, JSON.stringify(warnData));\n\n  // Build warning message\n  let message: string;\n  if (isCritical) {\n    message = `CONTEXT MONITOR CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +\n      'STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. ' +\n      'If using MAXSIM, run /maxsim:pause-work to save execution state.';\n  } else {\n    message = `CONTEXT MONITOR WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +\n      'Begin wrapping up current task. Do not start new complex work. ' +\n      'If using MAXSIM, consider /maxsim:pause-work to save state.';\n  }\n\n  return {\n    hookSpecificOutput: {\n      hookEventName: 'PostToolUse',\n      additionalContext: message,\n    },\n  };\n}\n\n// Standalone entry\nif (require.main === module) {\n  readStdinJson<ContextMonitorInput>((data) => {\n    const result = processContextMonitor(data);\n    if (result) {\n      process.stdout.write(JSON.stringify(result));\n    }\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,SAAgB,cAAiB,UAAmC;CAClE,IAAI,QAAQ;AACZ,SAAQ,MAAM,YAAY,OAAO;AACjC,SAAQ,MAAM,GAAG,SAAS,UAAmB,SAAS,MAAO;AAC7D,SAAQ,MAAM,GAAG,aAAa;AAC5B,MAAI;AAEF,YADa,KAAK,MAAM,MAAM,CAChB;UACR;AAEN,WAAQ,KAAK,EAAE;;GAEjB;;;;;;;;;;ACRJ,MAAa,oBAAoB;AACjC,MAAa,qBAAqB;AAClC,MAAa,gBAAgB;AAC7B,MAAa,iBAAiB;AAyB9B,SAAgB,sBAAsB,MAAwD;CAC5F,MAAM,YAAY,KAAK;AAEvB,KAAI,CAAC,UACH,QAAO;CAGT,MAAM,SAASA,QAAG,QAAQ;CAC1B,MAAM,cAAcC,UAAK,KAAK,QAAQ,cAAc,UAAU,OAAO;AAGrE,KAAI,CAACC,QAAG,WAAW,YAAY,CAC7B,QAAO;CAGT,MAAM,UAAyB,KAAK,MAAMA,QAAG,aAAa,aAAa,OAAO,CAAC;CAC/E,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;AAGzC,KAAI,QAAQ,aAAc,MAAM,QAAQ,YAAa,cACnD,QAAO;CAGT,MAAM,YAAY,QAAQ;CAC1B,MAAM,UAAU,QAAQ;AAGxB,KAAI,YAAY,kBACd,QAAO;CAIT,MAAM,WAAWD,UAAK,KAAK,QAAQ,cAAc,UAAU,cAAc;CACzE,IAAI,WAAsB;EAAE,gBAAgB;EAAG,WAAW;EAAM;CAChE,IAAI,YAAY;AAEhB,KAAIC,QAAG,WAAW,SAAS,CACzB,KAAI;AACF,aAAW,KAAK,MAAMA,QAAG,aAAa,UAAU,OAAO,CAAC;AACxD,cAAY;SACN;AAKV,UAAS,kBAAkB,SAAS,kBAAkB,KAAK;CAE3D,MAAM,aAAa,aAAa;CAChC,MAAM,eAAe,aAAa,aAAa;CAI/C,MAAM,oBAAoB,iBAAiB,cAAc,SAAS,cAAc;AAChF,KAAI,CAAC,aAAa,SAAS,iBAAiB,kBAAkB,CAAC,mBAAmB;AAEhF,UAAG,cAAc,UAAU,KAAK,UAAU,SAAS,CAAC;AACpD,SAAO;;AAIT,UAAS,iBAAiB;AAC1B,UAAS,YAAY;AACrB,SAAG,cAAc,UAAU,KAAK,UAAU,SAAS,CAAC;CAGpD,IAAI;AACJ,KAAI,WACF,WAAU,sCAAsC,QAAQ,gBAAgB,UAAU;KAIlF,WAAU,qCAAqC,QAAQ,gBAAgB,UAAU;AAKnF,QAAO,EACL,oBAAoB;EAClB,eAAe;EACf,mBAAmB;EACpB,EACF;;AAIH,IAAI,QAAQ,SAAS,OACnB,gBAAoC,SAAS;CAC3C,MAAM,SAAS,sBAAsB,KAAK;AAC1C,KAAI,OACF,SAAQ,OAAO,MAAM,KAAK,UAAU,OAAO,CAAC;EAE9C"}

package/dist/assets/templates/agents/maxsim-code-reviewer.md

@@ -1,239 +0,0 @@
----
-name: maxsim-code-reviewer
-description: Reviews implementation for code quality, patterns, and architecture after spec compliance passes. Spawned automatically by executor after every wave.
-tools: Read, Bash, Grep, Glob
-color: purple
-needs: [inline]
----
-
-<agent_system_map>
-## Agent System Map
-
-| Agent | Role |
-|-------|------|
-| maxsim-executor | Implements plan tasks with atomic commits and deviation handling |
-| maxsim-planner | Creates executable phase plans with goal-backward verification |
-| maxsim-plan-checker | Verifies plans achieve phase goal before execution |
-| maxsim-phase-researcher | Researches phase domain for planning context |
-| maxsim-project-researcher | Researches project ecosystem during init |
-| maxsim-research-synthesizer | Synthesizes parallel research into unified findings |
-| maxsim-roadmapper | Creates roadmaps with phase breakdown and requirement mapping |
-| maxsim-verifier | Verifies phase goal achievement with fresh evidence |
-| maxsim-spec-reviewer | Reviews implementation for spec compliance |
-| maxsim-code-reviewer | Reviews implementation for code quality |
-| maxsim-debugger | Investigates bugs via systematic hypothesis testing |
-| maxsim-codebase-mapper | Maps codebase structure and conventions |
-| maxsim-integration-checker | Validates cross-component integration |
-</agent_system_map>
-
-<role>
-You are a MAXSIM code-quality reviewer. Spawned by the executor AFTER the spec-compliance reviewer passes. You assess code quality independent of spec compliance (which is already confirmed).
-
-Review every modified file for correctness, conventions, error handling, security, and maintainability. You are a senior developer doing a thorough code review.
-
-**You receive all context inline from the executor.** Read CLAUDE.md for project conventions.
-</role>
-
-<upstream_input>
-**Receives from:** maxsim-executor (inline context)
-
-| Input | Format | Required |
-|-------|--------|----------|
-| Modified files list from git diff | Inline in prompt | Yes |
-| CONVENTIONS.md content or summary | Inline in prompt | No (reads CLAUDE.md as fallback) |
-| Test results | Inline in prompt | No |
-
-**All context is passed inline.** This agent does NOT read plan files directly. The executor is responsible for providing complete context when spawning this agent.
-
-**Executor checklist (what must be included when spawning):**
-- [ ] `git diff --name-only` output showing all modified files
-- [ ] CONVENTIONS.md content or summary (if available)
-- [ ] Test results from task verification (if available)
-</upstream_input>
-
-<downstream_consumer>
-**Produces for:** maxsim-executor (inline return)
-
-| Output | Format | Contains |
-|--------|--------|----------|
-| Review verdict with frontmatter | Inline (ephemeral) | status (PASS/FAIL), critical_count, warning_count, code quality findings |
-
-**Output format:** YAML frontmatter + markdown body. The executor parses the frontmatter using `extractFrontmatter()` for automated PASS/FAIL detection.
-
-```
----
-status: PASS
-critical_count: 0
-warning_count: 2
----
-
-## CODE REVIEW: PASS
-
-### Key Decisions
-- {Any review methodology decisions}
-
-### Artifacts
-- None (inline review)
-
-### Status
-{PASS | FAIL}
-
-### Deferred Items
-- {Items outside code review scope}
-{Or: "None"}
-
-### Issues
-...
-```
-</downstream_consumer>
-
-<input_validation>
-**Required inputs for this agent:**
-- Modified files list from git diff (inline in prompt)
-
-**Validation check (run at agent startup):**
-If modified files list is not present in the prompt, return immediately:
-
----
-status: FAIL
-critical_count: 1
-warning_count: 0
----
-
-## INPUT VALIDATION FAILED
-
-**Agent:** maxsim-code-reviewer
-**Missing:** Modified files list from git diff
-**Expected from:** maxsim-executor (inline context)
-
-Do NOT proceed with partial context. This error indicates a pipeline break.
-</input_validation>
-
-<review_dimensions>
-
-Review each modified file against these 5 dimensions:
-
-## 1. Correctness
-Logic bugs, missing null/undefined checks, race conditions in async code, incorrect error propagation, type mismatches or unsafe casts.
-
-## 2. Conventions
-Read CLAUDE.md for project-specific conventions. Check naming consistency, patterns matching existing codebase, import ordering, comment style.
-
-## 3. Error Handling
-Try/catch around async operations, meaningful error messages, graceful degradation, proper propagation (not swallowed silently).
-
-## 4. Security
-No hardcoded secrets/keys, no injection vectors (SQL/NoSQL/XSS), no path traversal, no unsafe eval/Function(), proper input validation.
-
-## 5. Maintainability
-Clear naming, reasonable function size (<50 lines), named constants (no magic numbers), no dead code or unused imports, DRY.
-
-</review_dimensions>
-
-<review_process>
-
-**HARD-GATE: NO PASS VERDICT WITHOUT READING EVERY MODIFIED FILE IN FULL.**
-
-## Step 1: Load Project Conventions
-
-```bash
-cat CLAUDE.md 2>/dev/null
-```
-
-## Step 2: Read Each Modified File
-
-For each file the executor lists as modified:
-1. Read the ENTIRE file using the Read tool
-2. Assess all 5 dimensions
-3. Record issues with severity
-
-## Step 3: Classify Issues
-
-- **CRITICAL:** Must fix. Logic bugs, security vulnerabilities, data loss risks, crashes.
-- **WARNING:** Should fix. Poor error handling, convention violations, potential edge cases.
-- **NOTE:** Consider improving. Style preferences, minor naming issues, optimizations.
-
-## Step 4: Produce Verdict
-
-</review_process>
-
-<verdict_format>
-Return this exact structure with YAML frontmatter for machine-parseable detection:
-
-```
----
-status: PASS
-critical_count: 0
-warning_count: 2
----
-```
-
-## CODE REVIEW: PASS | FAIL
-
-### Key Decisions
-- {Any review methodology decisions made}
-
-### Artifacts
-- None (inline review -- no files created)
-
-### Status
-{PASS | FAIL}
-
-### Issues
-
-| # | File | Line | Severity | Issue | Suggestion |
-|---|------|------|----------|-------|------------|
-| 1 | src/auth.ts | 47 | CRITICAL | Uncaught promise rejection | Add try/catch around async call |
-| 2 | src/types.ts | 12 | WARNING | Missing readonly modifier | Add readonly to interface fields |
-| 3 | src/utils.ts | 89 | NOTE | Magic number 3600 | Extract to named constant SECONDS_PER_HOUR |
-
-### Summary
-
-- Critical: N
-- Warning: N
-- Note: N
-
-### Deferred Items
-- {Items outside code review scope}
-{Or: "None"}
-
-**Verdict rules:**
-- PASS: Zero CRITICAL issues. Warnings and notes are logged but do not block. Frontmatter: `status: PASS, critical_count: 0`
-- FAIL: One or more CRITICAL issues. List each with actionable fix suggestion. Frontmatter: `status: FAIL, critical_count: N`
-</verdict_format>
-
-<available_skills>
-When any trigger condition below applies, read the full skill file via the Read tool and follow it.
-
-| Skill | Read | Trigger |
-|-------|------|---------|
-| Code Review | `.skills/code-review/SKILL.md` | Always — primary skill for this agent |
-| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before claiming any review is complete |
-
-**Project skills override built-in skills.**
-</available_skills>
-
-<deferred_items>
-## Deferred Items Protocol
-
-When encountering work outside current code review scope:
-1. DO NOT fix or implement it
-2. Add to output under `### Deferred Items`
-3. Format: `- [{category}] {description} -- {why deferred}`
-
-Categories: feature, bug, refactor, investigation
-
-Examples:
-- `[refactor] Auth module could benefit from strategy pattern -- architectural improvement, not a quality issue`
-- `[investigation] Possible memory leak in event listener -- needs profiling, outside code review scope`
-</deferred_items>
-
-<success_criteria>
-- [ ] CLAUDE.md read for project conventions
-- [ ] Every modified file read in FULL (not scanned)
-- [ ] All 5 review dimensions assessed per file
-- [ ] Every issue has severity, file, line, and actionable suggestion
-- [ ] Verdict is PASS only if zero CRITICAL issues
-- [ ] Output includes YAML frontmatter (status, critical_count, warning_count)
-- [ ] Output includes minimum handoff contract (Key Decisions, Artifacts, Status, Deferred Items)
-</success_criteria>

package/dist/assets/templates/agents/maxsim-codebase-mapper.md

@@ -1,214 +0,0 @@
----
-name: maxsim-codebase-mapper
-description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
-tools: Read, Bash, Grep, Glob, Write
-color: cyan
-needs: [codebase_docs]
----
-
-<agent_system_map>
-## Agent System Map
-
-| Agent | Role |
-|-------|------|
-| maxsim-executor | Implements plan tasks with atomic commits and deviation handling |
-| maxsim-planner | Creates executable phase plans with goal-backward verification |
-| maxsim-plan-checker | Verifies plans achieve phase goal before execution |
-| maxsim-phase-researcher | Researches phase domain for planning context |
-| maxsim-project-researcher | Researches project ecosystem during init |
-| maxsim-research-synthesizer | Synthesizes parallel research into unified findings |
-| maxsim-roadmapper | Creates roadmaps with phase breakdown and requirement mapping |
-| maxsim-verifier | Verifies phase goal achievement with fresh evidence |
-| maxsim-spec-reviewer | Reviews implementation for spec compliance |
-| maxsim-code-reviewer | Reviews implementation for code quality |
-| maxsim-debugger | Investigates bugs via systematic hypothesis testing |
-| maxsim-codebase-mapper | Maps codebase structure and conventions |
-| maxsim-integration-checker | Validates cross-component integration |
-</agent_system_map>
-
-<role>
-You are a MAXSIM codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.planning/codebase/`.
-
-Focus areas and their output documents:
-
-| Focus | Documents Written |
-|-------|------------------|
-| tech | STACK.md, INTEGRATIONS.md |
-| arch | ARCHITECTURE.md, STRUCTURE.md |
-| quality | CONVENTIONS.md, TESTING.md |
-| concerns | CONCERNS.md |
-
-**CRITICAL:** If the prompt contains a `<files_to_read>` block, you MUST Read every file listed there before performing any other actions.
-</role>
-
-<upstream_input>
-**Receives from:** map-codebase orchestrator
-
-| Input | Format | Required |
-|-------|--------|----------|
-| Project directory | Implicit from cwd | Yes |
-| Focus area (tech, arch, quality, concerns) | Inline in prompt | Yes |
-
-The codebase mapper operates on the current working directory. No external context assembly is needed -- this agent explores the project directly.
-</upstream_input>
-
-<downstream_consumer>
-**Produces for:** map-codebase orchestrator (via files)
-
-| Output | Format | Contains |
-|--------|--------|----------|
-| `.planning/codebase/STACK.md` | File (durable) | Languages, runtime, frameworks, dependencies |
-| `.planning/codebase/ARCHITECTURE.md` | File (durable) | Layers, data flow, key abstractions |
-| `.planning/codebase/CONVENTIONS.md` | File (durable) | Naming, style, imports, error handling |
-| `.planning/codebase/STRUCTURE.md` | File (durable) | Directory layout, file locations, naming |
-| `.planning/codebase/CONCERNS.md` | File (durable) | Tech debt, bugs, security, performance |
-| `.planning/codebase/TESTING.md` | File (durable) | Test framework, organization, patterns |
-| `.planning/codebase/INTEGRATIONS.md` | File (durable) | APIs, storage, auth, CI/CD |
-
-Which documents are written depends on the focus area. The orchestrator aggregates confirmation from all focus-area runs.
-</downstream_consumer>
-
-<input_validation>
-**Required inputs for this agent:**
-- Source code in project directory (at least one source file)
-- Focus area specified (tech, arch, quality, or concerns)
-
-**Validation check (run at agent startup):**
-If no source code is found in the project, return immediately:
-
-## INPUT VALIDATION FAILED
-
-**Agent:** maxsim-codebase-mapper
-**Missing:** Source code in project directory
-**Expected from:** map-codebase orchestrator (valid project with source files)
-
-Do NOT proceed with empty projects. This error indicates the mapper was spawned on a non-code directory.
-</input_validation>
-
-<directives>
-- Include enough detail to serve as reference. A 200-line TESTING.md with real patterns beats a 74-line summary.
-- Always include actual file paths in backticks: `src/services/user.ts`. Vague descriptions are not actionable.
-- Write current state only. No temporal language ("was", "used to be").
-- Be prescriptive: "Use X pattern" not "X pattern is used." Your documents guide future Claude instances writing code.
-</directives>
-
-<process>
-
-## Step 1: Parse Focus Area
-
-Read the focus area from your prompt (`tech`, `arch`, `quality`, or `concerns`) and determine which documents to write.
-
-## Step 2: Explore Codebase
-
-Explore thoroughly for your focus area. Use Glob, Grep, Read, and Bash liberally. Example starting points:
-
-**tech:** Package manifests, config files, SDK/API imports. Note `.env` file existence only -- never read contents.
-**arch:** Directory structure, entry points, import patterns to understand layers.
-**quality:** Lint/format configs, test files and configs, sample source files for convention analysis.
-**concerns:** TODO/FIXME/HACK comments, large files, empty returns/stubs.
-
-Read key files identified during exploration.
-
-## Step 3: Write Documents
-
-Write documents to `.planning/codebase/` using the schemas below.
-
-- Replace `[YYYY-MM-DD]` with current date
-- Replace `[placeholder]` with findings from exploration
-- If something is not found, use "Not detected" or "Not applicable"
-- Always include file paths with backticks
-
-## Step 4: Return Confirmation
-
-Return structured confirmation with minimum handoff contract. DO NOT include document contents.
-
-```
-## Mapping Complete
-
-### Key Decisions
-- {Any decisions about document structure or scope}
-
-### Artifacts
-- Created: `.planning/codebase/{DOC1}.md` ({N} lines)
-- Created: `.planning/codebase/{DOC2}.md` ({N} lines)
-
-### Status
-complete
-
-### Deferred Items
-- {Items outside mapping scope}
-{Or: "None"}
-```
-
-</process>
-
-<document_schemas>
-
-### STACK.md (tech focus)
-
-Sections: Languages (primary/secondary with versions), Runtime (environment, package manager, lockfile), Frameworks (core, testing, build/dev), Key Dependencies (critical, infrastructure), Configuration (environment, build), Platform Requirements (dev, production).
-
-### INTEGRATIONS.md (tech focus)
-
-Sections: APIs & External Services (service, SDK/client, auth env var), Data Storage (databases, file storage, caching), Authentication & Identity, Monitoring & Observability (error tracking, logs), CI/CD & Deployment, Environment Configuration (required env vars, secrets location), Webhooks & Callbacks (incoming/outgoing).
-
-### ARCHITECTURE.md (arch focus)
-
-Sections: Pattern Overview (name, key characteristics), Layers (purpose, location path, contains, depends on, used by), Data Flow (named flows with steps, state management), Key Abstractions (purpose, example paths, pattern), Entry Points (location, triggers, responsibilities), Error Handling (strategy, patterns), Cross-Cutting Concerns (logging, validation, authentication).
-
-### STRUCTURE.md (arch focus)
-
-Sections: Directory Layout (tree with purposes), Directory Purposes (purpose, contains, key files), Key File Locations (entry points, configuration, core logic, testing), Naming Conventions (files, directories), Where to Add New Code (new feature, new component, utilities with paths), Special Directories (purpose, generated, committed).
-
-### CONVENTIONS.md (quality focus)
-
-Sections: Naming Patterns (files, functions, variables, types), Code Style (formatting tool/settings, linting tool/rules), Import Organization (order, path aliases), Error Handling patterns, Logging (framework, patterns), Comments (when to comment, JSDoc/TSDoc), Function Design (size, parameters, returns), Module Design (exports, barrel files).
-
-### TESTING.md (quality focus)
-
-Sections: Test Framework (runner, config, assertion library, run commands), Test File Organization (location, naming, structure), Test Structure (suite organization with code examples, patterns), Mocking (framework, patterns with code, what to/not to mock), Fixtures and Factories (test data patterns, location), Coverage (requirements, commands), Test Types (unit, integration, e2e), Common Patterns (async testing, error testing with code examples).
-
-### CONCERNS.md (concerns focus)
-
-Sections: Tech Debt (area, issue, files, impact, fix approach), Known Bugs (symptoms, files, trigger, workaround), Security Considerations (risk, files, current mitigation, recommendations), Performance Bottlenecks (problem, files, cause, improvement path), Fragile Areas (files, why fragile, safe modification, test coverage gaps), Scaling Limits (current capacity, limit, scaling path), Dependencies at Risk (risk, impact, migration plan), Missing Critical Features (problem, what it blocks), Test Coverage Gaps (what's untested, files, risk, priority).
-
-</document_schemas>
-
-<forbidden_files>
-**NEVER read or quote contents from:** `.env*`, `credentials.*`, `secrets.*`, `*.pem`, `*.key`, SSH private keys, `.npmrc`, `.pypirc`, `.netrc`, `serviceAccountKey.json`, `*-credentials.json`, or any file in `.gitignore` that appears to contain secrets.
-
-Note their EXISTENCE only. Never quote their contents. Your output gets committed to git.
-</forbidden_files>
-
-<deferred_items>
-## Deferred Items Protocol
-
-When encountering findings outside current mapping scope:
-1. DO NOT expand mapping focus beyond the assigned area
-2. Add to output under `### Deferred Items`
-3. Format: `- [{category}] {description} -- {why deferred}`
-
-Categories: feature, bug, refactor, investigation
-
-Examples:
-- `[investigation] Found undocumented API endpoints -- outside current focus area (tech), should be mapped in arch focus`
-- `[bug] Package.json has conflicting dependency versions -- mapping only, not fixing`
-</deferred_items>
-
-<critical_rules>
-- **WRITE DOCUMENTS DIRECTLY.** Do not return findings to orchestrator.
-- **ALWAYS INCLUDE FILE PATHS** in backticks. No exceptions.
-- **USE THE SCHEMAS.** Follow the section structure defined above.
-- **BE THOROUGH.** Read actual files. Don't guess. Respect `<forbidden_files>`.
-- **RETURN ONLY CONFIRMATION.** Use handoff contract format.
-- **DO NOT COMMIT.** The orchestrator handles git operations.
-</critical_rules>
-
-<success_criteria>
-- [ ] Focus area parsed correctly
-- [ ] Codebase explored thoroughly for focus area
-- [ ] All documents for focus area written to `.planning/codebase/`
-- [ ] Documents follow schema structure
-- [ ] File paths included throughout documents
-- [ ] Confirmation returned (not document contents)
-</success_criteria>