maxsimcli 5.0.7 → 5.1.0

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "maxsimcli",
-  "version": "5.0.7",
+  "version": "5.1.0",
   "private": false,
-  "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by MayStudios.",
+  "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by MayStudios.",
   "bin": {
     "maxsimcli": "dist/install.cjs"
   },
   "main": "./dist/cli.cjs",
-  "types": "./dist/cli.d.cts",
   "files": [
     "dist",
     "README.md"
@@ -24,11 +23,7 @@
     "ai",
     "meta-prompting",
     "context-engineering",
-    "spec-driven-development",
-    "gemini",
-    "gemini-cli",
-    "codex",
-    "codex-cli"
+    "spec-driven-development"
   ],
   "author": "MayStudios",
   "license": "MIT",
@@ -40,29 +35,28 @@
   "bugs": {
     "url": "https://github.com/maystudios/maxsimcli/issues"
   },
-  "devDependencies": {
+  "dependencies": {
     "@inquirer/prompts": "^8.3.0",
-    "@types/figlet": "^1.7.0",
-    "@types/fs-extra": "^11.0.4",
-    "@types/minimist": "^1.2.5",
-    "@types/node": "^25.3.0",
+    "@octokit/plugin-retry": "^8.1.0",
+    "@octokit/plugin-throttling": "^11.0.3",
+    "@octokit/rest": "^22.0.1",
     "chalk": "^5.6.2",
-    "esbuild": "^0.24.0",
     "escape-string-regexp": "^5.0.0",
+    "figlet": "^1.10.0",
     "fs-extra": "^11.3.3",
     "minimist": "^1.2.8",
     "ora": "^9.3.0",
     "simple-git": "^3.32.2",
     "slugify": "^1.6.6",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
     "yaml": "^2.8.2"
   },
-  "dependencies": {
-    "@octokit/plugin-retry": "^8.1.0",
-    "@octokit/plugin-throttling": "^11.0.3",
-    "@octokit/rest": "^22.0.1",
-    "figlet": "^1.10.0"
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^25.3.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }

package/dist/assets/templates/skills/agent-system-map/SKILL.md

@@ -1,92 +0,0 @@
----
-name: agent-system-map
-description: >-
-  Registry of MAXSIM's 4 agent types with their roles, base tools, preloaded
-  skills, and typical tasks. Documents the orchestrator-mediated communication
-  pattern where agents return results to the orchestrator for pipeline routing.
-  Use when spawning agents, understanding agent capabilities, or designing
-  agent interactions.
-user-invocable: false
----
-
-# Agent System Map
-
-MAXSIM uses 4 generic agent types. Specialization comes from orchestrator instructions and skills, not from separate agent definitions.
-
-## Agent Registry
-
-| Agent | Role | Base Tools | Preloaded Skills |
-|-------|------|-----------|-----------------|
-| **executor** | Implements plans with atomic commits and verified completion | Read, Write, Edit, Bash, Grep, Glob | handoff-contract, evidence-collection, commit-conventions |
-| **planner** | Creates structured PLAN.md files from requirements and research | Read, Bash, Grep, Glob | handoff-contract |
-| **researcher** | Investigates technical domains and produces structured findings | Read, Bash, Grep, Glob, WebFetch | research-methodology, handoff-contract |
-| **verifier** | Verifies work quality, spec compliance, and goal achievement | Read, Bash, Grep, Glob | verification-gates, evidence-collection, handoff-contract |
-
-## Specialization via Orchestrator
-
-The orchestrator provides task-specific context in the spawn prompt. The same `verifier` agent handles code review, spec review, debugging, and integration checking based on what the orchestrator asks:
-
-| Task | Orchestrator Instruction |
-|------|------------------------|
-| Code review | "Review these files for code quality, security, and conventions" |
-| Spec review | "Check these files against the plan's must_haves and done criteria" |
-| Debugging | "Investigate this failing test using systematic hypothesis testing" |
-| Integration check | "Validate cross-component integration for these changed files" |
-
-## Communication Pattern: Orchestrator-Mediated
-
-**Subagents CANNOT spawn other subagents.** This is a Claude Code platform constraint. All agent-to-agent communication routes through the orchestrator.
-
-```
-Orchestrator
-  |-- spawns --> Researcher (returns findings)
-  |-- spawns --> Planner (returns PLAN.md)
-  |-- spawns --> Executor (returns SUMMARY.md)
-  |-- spawns --> Verifier (returns verification report)
-```
-
-**Flow:**
-1. Orchestrator spawns Agent A with task + context
-2. Agent A executes, produces results using handoff contract
-3. Agent A returns to orchestrator
-4. Orchestrator reads results, decides next step
-5. Orchestrator spawns Agent B with Agent A's results as context
-
-Agents never call each other directly. The orchestrator is the single routing point.
-
-## Spawn Prompt Format
-
-When spawning an agent, use natural language with markdown sections:
-
-```markdown
-## Task
-[What the agent should do -- specific, actionable]
-
-## Context
-[Phase, plan, prior results, relevant decisions]
-
-## Files to Read
-- [file paths the agent should read at startup]
-
-## Suggested Skills
-- [skills that may be helpful for this task]
-
-## Success Criteria
-- [measurable outcomes the orchestrator will check]
-```
-
-The orchestrator carries the specialization context. Agents are generic -- the spawn prompt makes them specific.
-
-## Model Selection
-
-Each agent type has a default model from the config profile:
-
-| Profile | Executor | Planner | Researcher | Verifier |
-|---------|----------|---------|------------|----------|
-| quality | opus | opus | opus | sonnet |
-| balanced | sonnet | sonnet | sonnet | sonnet |
-| budget | sonnet | haiku | haiku | haiku |
-
-The orchestrator can override per-spawn for complex tasks (e.g., force opus for critical research).
-
-Agents use `model: inherit` in their frontmatter -- the orchestrator or CLI resolves the actual model at spawn time based on the config profile.

package/dist/assets/templates/skills/evidence-collection/SKILL.md

@@ -1,87 +0,0 @@
----
-name: evidence-collection
-description: >-
-  Systematic evidence gathering using tool output before making claims. Covers
-  what counts as evidence, the collection process, and common pitfalls that lead
-  to false claims. Use when verifying work completion, checking test results,
-  validating build success, or before any completion gate.
-user-invocable: false
----
-
-# Evidence Collection
-
-Gather fresh evidence using tool output before making any claim. Evidence must come from THIS turn -- not prior turns, not cached knowledge, not reasoning.
-
-## Collection Process
-
-For each claim you need to support:
-
-1. **IDENTIFY** -- What command proves this claim?
-   - Pick the most direct verification (e.g., `npm test` for "tests pass", not "I wrote the test")
-   - If no single command exists, identify all required checks
-
-2. **RUN** -- Execute the command fresh in THIS turn
-   - Do not reuse output from a previous turn
-   - Do not rely on output from a different command
-   - Run the full command, not a partial check
-
-3. **READ** -- Read the complete output
-   - Check the exit code (0 = success, non-zero = failure)
-   - Read all output, not just the summary line
-   - Look for warnings or partial failures hidden in verbose output
-
-4. **CHECK** -- Does the output actually confirm the claim?
-   - Match output against specific expected values
-   - A passing build does not mean passing tests
-   - A created file does not mean correct file contents
-
-5. **CITE** -- Include the evidence in your response
-   - Use the evidence block format
-   - Quote specific output lines, not paraphrased summaries
-
-## What Counts as Evidence
-
-| Claim | Requires | Not Sufficient |
-|-------|----------|----------------|
-| "Tests pass" | Test command output showing 0 failures | Previous run, "should pass", partial run |
-| "Build succeeds" | Build command with exit code 0 | Linter passing, "logs look clean" |
-| "Bug is fixed" | Original failing test now passes | "Code changed, assumed fixed" |
-| "Task complete" | All done criteria checked with evidence | "I implemented everything in the plan" |
-| "No regressions" | Full test suite passing | "I only changed one file" |
-| "File created" | Read tool or `test -f` output | "I ran the Write tool" (verify it wrote) |
-| "Content correct" | Read tool showing expected content | "I wrote the correct content" |
-| "API responds" | curl/fetch output with status code | "Server is running" without calling it |
-
-## Evidence Block Format
-
-```
-CLAIM: [what you are claiming]
-EVIDENCE: [exact command run in THIS turn]
-OUTPUT: [relevant excerpt of actual output]
-VERDICT: PASS | FAIL
-```
-
-## Common Pitfalls
-
-| Excuse | Why It Fails |
-|--------|-------------|
-| "Should work now" | "Should" is not evidence. Run the command. |
-| "I'm confident in the logic" | Confidence is not evidence. Run it. |
-| "The linter passed" | Linter passing does not mean tests pass or build succeeds. |
-| "I only changed one line" | One line can break everything. Verify. |
-| "The subagent reported success" | Trust test output and VCS diffs, not agent reports. |
-| "I already checked this" | In a previous turn. Evidence expires each turn. Run it again. |
-| "The error was in a different file" | Side effects cross files. Run the full suite. |
-| "It compiled, so it works" | Compilation checks types, not logic. Run tests. |
-
-## Key Rules
-
-- **THIS-turn only**: Evidence from prior turns is stale. Always re-run.
-- **Tool output only**: Your reasoning, analysis, and confidence are not evidence.
-- **Full output**: Read the complete output, not just the first or last line.
-- **Specific citations**: Quote the output. "It passed" is not a citation.
-- **One block per claim**: Each distinct claim needs its own evidence or an explicit grouping note.
-
-## See Also
-
-The `verification-gates` skill defines the gate framework where evidence collection is applied. The always-loaded `verification-protocol` rule provides the enforcement language.

package/dist/assets/templates/skills/github-artifact-protocol/SKILL.md

@@ -1,67 +0,0 @@
-# Skill: GitHub Artifact Protocol
-
-## Trigger
-When reading from or writing to GitHub Issues for MAXSIM artifacts.
-
-## Protocol
-
-### Artifact Types and Comment Conventions
-
-All MAXSIM artifacts are stored as GitHub Issue comments with type metadata:
-
-| Artifact | Comment Type | Tool | Format |
-|----------|-------------|------|--------|
-| Context decisions | `context` | `github post-comment --type context` | `<!-- maxsim:type=context -->` header |
-| Research findings | `research` | `github post-comment --type research` | `<!-- maxsim:type=research -->` header |
-| Plan content | (plan header) | `github post-plan-comment` | `<!-- maxsim:type=plan -->` header |
-| Summary | `summary` | `github post-comment --type summary` | `<!-- maxsim:type=summary -->` header |
-| Verification | `verification` | `github post-comment --type verification` | `<!-- maxsim:type=verification -->` header |
-| UAT | `uat` | `github post-comment --type uat` | `<!-- maxsim:type=uat -->` header |
-| Completion | (structured) | `github post-completion` | Commit SHA + files |
-
-### Issue Lifecycle State Machine
-
-**Phase Issues:**
-```
-To Do --> In Progress --> In Review --> Done
-(created)  (plan done)    (PR created)  (PR merged + verified)
-```
-
-**Task Sub-Issues:**
-```
-To Do --> In Progress --> Done
-(created)  (started)      (completed + review passed)
-Done --> In Progress (review failed, reopened)
-```
-
-### Write Order (WIRE-01)
-
-1. Build content in memory
-2. POST to GitHub via CLI command
-3. If successful, operation succeeds
-4. If failed, operation aborts entirely -- no partial state
-
-### Rollback Pattern (WIRE-07)
-
-On partial failure during batch operations:
-1. Close partially-created issues with `state_reason: 'not_planned'`
-2. Post `[MAXSIM-ROLLBACK]` comment explaining why
-3. Report what succeeded and what failed
-4. Offer targeted retry
-
-### External Edit Detection (WIRE-06)
-
-- Body hash (SHA-256) stored in `github-issues.json` mapping after each write
-- On read, compare live body hash against stored hash
-- If different, warn user about external modification
-- Do not auto-incorporate -- user decides
-
-### What Stays Local
-
-- `config.json` -- project settings
-- `PROJECT.md` -- project vision
-- `REQUIREMENTS.md` -- requirements
-- `ROADMAP.md` -- phase structure
-- `STATE.md` -- decisions, blockers, metrics
-- `github-issues.json` -- mapping cache (rebuildable)
-- `codebase/` -- stack, architecture, conventions

package/dist/assets/templates/skills/github-tools-guide/SKILL.md

@@ -1,89 +0,0 @@
-# Skill: GitHub Tools Guide
-
-## Trigger
-When interacting with GitHub Issues, project boards, or progress tracking in MAXSIM.
-
-## CLI Invocation
-
-All GitHub operations use the MAXSIM CLI tools router:
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github <command> [--flag value] [--raw]
-```
-
-Add `--raw` to get machine-readable JSON output (no formatting).
-
-## Command Reference
-
-### Setup
-| Command | Description |
-|---------|-------------|
-| `github setup [--milestone-title "T"]` | Set up GitHub integration: board, labels, milestone, templates |
-
-### Phase Lifecycle
-| Command | Description |
-|---------|-------------|
-| `github create-phase --phase-number "01" --phase-name "Name" --goal "Goal" [--requirements "R1,R2"] [--success-criteria "SC1,SC2"]` | Create phase issue + add to board + set "To Do" |
-| `github create-task --phase-number "01" --task-id "T1" --title "Title" --body "Body" --parent-issue-number N` | Create task sub-issue |
-| `github batch-create-tasks --phase-number "01" --parent-issue-number N --tasks '[{"task_id":"1.1","title":"Title","body":"Body"}, ...]'` | Batch create tasks with rollback |
-| `github post-plan-comment --phase-issue-number N --plan-number "01" --plan-content "..." [--plan-content-file F]` | Post plan comment on phase issue |
-
-### Comments
-| Command | Description |
-|---------|-------------|
-| `github post-comment --issue-number N --body "..." [--body-file F] [--type TYPE]` | Post comment (types: research, context, summary, verification, uat, general) |
-| `github post-completion --issue-number N --commit-sha "SHA" --files-changed "a.ts,b.ts"` | Post completion comment |
-
-### Issue Operations
-| Command | Description |
-|---------|-------------|
-| `github get-issue --issue-number N [--include-comments]` | Get issue details (with optional comments) |
-| `github list-sub-issues --phase-issue-number N` | List sub-issues of a phase issue |
-| `github close-issue --issue-number N [--reason "..."] [--state-reason completed\|not_planned]` | Close issue |
-| `github reopen-issue --issue-number N` | Reopen closed issue |
-| `github bounce-issue --issue-number N --reason "feedback"` | Bounce to In Progress with feedback |
-| `github move-issue --issue-number N --status "STATUS"` | Move to board column (To Do, In Progress, In Review, Done) |
-| `github detect-external-edits --phase-number "01"` | Check body hash mismatch |
-
-### Board Operations
-| Command | Description |
-|---------|-------------|
-| `github query-board --project-number N [--status "STATUS"] [--phase "01"]` | Query board items |
-| `github add-to-board --project-number N --issue-number M` | Add issue to board |
-| `github search-issues [--labels "L1,L2"] [--state open\|closed\|all] [--query "text"]` | Search issues |
-| `github sync-check` | Verify local mapping matches GitHub state |
-
-### Progress
-| Command | Description |
-|---------|-------------|
-| `github phase-progress --phase-issue-number N` | Phase progress from sub-issues |
-| `github all-progress` | All phases progress overview |
-| `github detect-interrupted --phase-issue-number N` | Detect interrupted phase |
-
-### Convenience
-| Command | Description |
-|---------|-------------|
-| `github status` | Combined progress + interrupted + board overview |
-| `github sync` | Sync check + repair actions |
-| `github overview` | Board summary grouped by column |
-
-## Text Arguments
-
-For large text (body, plan-content), write to a tmpfile and use `--*-file`:
-
-```bash
-TMPFILE=$(mktemp)
-cat > "$TMPFILE" << 'EOF'
-Multi-line content here...
-EOF
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number 42 --body-file "$TMPFILE" --type summary
-```
-
-## Output Format
-
-All commands return JSON when `--raw` is passed:
-```json
-{"ok": true, "result": "...", "rawValue": {...}}
-```
-
-Without `--raw`, returns human-readable formatted output.

package/dist/assets/templates/skills/input-validation/SKILL.md

@@ -1,51 +0,0 @@
----
-name: input-validation
-description: >-
-  Validates required inputs exist before agent work begins. Checks file paths,
-  environment variables, and CLI arguments at startup. Use at agent startup to
-  fail fast with structured error instead of proceeding with missing context.
-user-invocable: false
----
-
-# Input Validation
-
-Validate all required inputs before doing any work. Fail fast with a structured error -- never attempt partial work with missing context.
-
-## Process
-
-At agent startup, before any implementation:
-
-1. **List required inputs** -- files, env vars, CLI args, state files
-2. **Check each input exists** -- use tool calls, not assumptions
-3. **Collect all missing inputs** -- do not stop at the first missing item
-4. **If any missing: return structured error immediately**
-
-## Structured Error Format
-
-```
-AGENT RESULT: INPUT VALIDATION FAILED
-
-Missing:
-- [input 1] -- [what it is, where it should come from]
-- [input 2] -- [what it is, where it should come from]
-
-Expected from: [source -- orchestrator spawn prompt, user environment, prior agent output]
-```
-
-## Validation Checks by Type
-
-| Input Type | How to Check | Example |
-|-----------|-------------|---------|
-| File path | `test -f "path"` or Read tool | PLAN.md, STATE.md, config.json |
-| Directory | `test -d "path"` | .planning/, templates/ |
-| Env variable | `echo "$VAR"` or `test -n "$VAR"` | GITHUB_TOKEN, NODE_ENV |
-| CLI argument | Check prompt context for required fields | Phase number, plan number |
-| Prior output | Check expected file or git commit exists | SUMMARY.md from previous plan |
-
-## Rules
-
-- **Check ALL inputs before reporting** -- collect the complete list of missing items
-- **Do NOT attempt partial work** -- if inputs are missing, the output will be wrong
-- **Do NOT guess missing values** -- return the error and let the orchestrator fix it
-- **Include the source** -- tell the user where the missing input should come from
-- **This is a hard gate** -- no workarounds, no "I'll proceed without it"

package/dist/assets/templates/skills/memory-management/SKILL.md

@@ -1,75 +0,0 @@
----
-name: memory-management
-description: >-
-  Pattern and error persistence across sessions. Defines what to persist, where
-  to store it, and when to capture. Use when encountering recurring patterns,
-  solving non-trivial problems, making architectural decisions, or discovering
-  environment-specific behaviors.
----
-
-# Memory Management
-
-Context dies with each session. Patterns discovered but not saved are patterns lost.
-
-## What to Persist
-
-| Trigger | Threshold | What to Save |
-|---------|-----------|-------------|
-| Same error encountered | 2+ occurrences | Error pattern, root cause, fix |
-| Same debugging path followed | 2+ times | The shortcut or solution |
-| Architectural decision made | Once (if significant) | Decision, rationale, alternatives rejected |
-| Non-obvious convention discovered | Once | The convention and where it applies |
-| Workaround for tooling/framework quirk | Once | The quirk and the workaround |
-| Project-specific pattern confirmed | 2+ uses | The pattern and when to apply it |
-
-**Do NOT save:** Session-specific context, information already in CLAUDE.md, speculative conclusions, temporary workarounds, or obvious patterns.
-
-## Where to Store
-
-| Location | Content | When Loaded |
-|----------|---------|-------------|
-| STATE.md | Project-level decisions, blockers, metrics | Every MAXSIM session |
-| CLAUDE.md | Project conventions, build commands, architecture | Every Claude Code session |
-| LESSONS.md | Cross-session codebase-specific lessons | MAXSIM execution startup |
-
-### Entry Format
-
-```markdown
-- [YYYY-MM-DD] [{phase}-{plan}] {actionable lesson}
-```
-
-For LESSONS.md entries. For STATE.md decisions, use the `state add-decision` tool.
-
-## When to Persist
-
-Persist at natural breakpoints:
-
-- After resolving a non-trivial bug (save error pattern + fix)
-- After making an architectural decision (save decision + rationale)
-- After discovering a recurring pattern (save pattern + when to apply)
-- At checkpoints (save current understanding before context resets)
-- At session end (review what was learned, save anything missed)
-
-## Error Escalation
-
-```
-Error seen once     -- Note it, move on
-Error seen twice    -- Save to LESSONS.md with pattern and fix
-Error seen 3+ times -- Save AND add to CLAUDE.md for immediate visibility
-```
-
-## Process
-
-1. **DETECT** -- Recognize a save trigger from the table above
-2. **CHECK** -- Read existing memory files before writing to avoid duplicates
-3. **WRITE** -- Add the entry to the appropriate file
-4. **VERIFY** -- Re-read the file to confirm the entry was written correctly and is actionable
-
-## Common Pitfalls
-
-- Encountering the same error a second time without saving it
-- Making the same architectural decision you made in a previous session
-- Debugging a problem you already solved before
-- Leaving a session without updating memory for patterns discovered
-
-If any of these occur: stop, write the memory entry now, then continue.

package/dist/assets/templates/skills/research-methodology/SKILL.md

@@ -1,137 +0,0 @@
----
-name: research-methodology
-description: >-
-  Research process with tool priorities, confidence levels, and source evaluation.
-  Defines how to investigate technical domains, evaluate sources, and structure
-  findings with confidence tags. Use when researching libraries, APIs, architecture
-  patterns, or any domain requiring external knowledge gathering.
-user-invocable: false
----
-
-# Research Methodology
-
-Systematic process for investigating technical domains and producing structured findings with confidence levels.
-
-## Research Process
-
-### 1. Define Questions
-
-Before researching, write explicit questions:
-
-- What specific information do I need?
-- What decisions will this research inform?
-- What would change my approach if I learned X vs Y?
-
-Avoid open-ended exploration. Each question should have a clear "answered" state.
-
-### 2. Identify Sources
-
-Use this priority order for source selection:
-
-| Priority | Source Type | Tool | Best For |
-|----------|-----------|------|----------|
-| 1 | Official documentation | WebFetch | API specs, config options, platform features |
-| 2 | Codebase (existing code) | Grep, Glob, Read | Current patterns, conventions, dependencies |
-| 3 | CLI tool help | Bash (`--help`, `--version`) | Tool capabilities, available flags |
-| 4 | Package registries | WebFetch (npm, PyPI) | Version info, dependency trees |
-| 5 | Reputable technical blogs | WebFetch | Architecture patterns, best practices |
-| 6 | Community forums | WebFetch | Edge cases, workarounds, known issues |
-
-### 3. Evaluate Sources
-
-Not all sources are equal. Tag each finding with a confidence level:
-
-| Level | Criteria | Examples |
-|-------|----------|---------|
-| **HIGH** | Official docs, verified by tool output, multiple primary sources agree | Platform docs, API reference, confirmed by running code |
-| **MEDIUM** | Reputable blogs, community consensus, single primary source | Well-known tech blogs, Stack Overflow accepted answers, conference talks |
-| **LOW** | Single non-official source, outdated (>1 year), unverified claims | Personal blogs, forum posts, AI-generated content without verification |
-
-**Source evaluation checklist:**
-- Is this a primary source (official docs) or secondary (blog post)?
-- When was it published or last updated?
-- Does it match what I see in the actual codebase/tool?
-- Do multiple independent sources agree?
-
-### 4. Cross-Reference Claims
-
-For any finding that influences architecture or design:
-
-- Find at least 2 independent sources
-- Verify against actual tool behavior (run a command, read a config)
-- Note when sources disagree and which you trust more
-- Mark single-source findings as LOW confidence
-
-### 5. Structure Output
-
-Research findings follow this format:
-
-```markdown
-## Finding: [Title]
-
-**Confidence:** HIGH | MEDIUM | LOW
-**Sources:** [list of sources with links]
-
-[Finding description -- what was learned]
-
-**Implications:** [How this affects our decisions]
-**Open questions:** [What remains unclear]
-```
-
-## Research Output Template
-
-```markdown
-# [Domain] Research
-
-**Researched:** [date]
-**Confidence:** [overall confidence level]
-
-## Key Findings
-- [Finding 1] (HIGH confidence)
-- [Finding 2] (MEDIUM confidence)
-
-## Standard Stack
-| Component | Choice | Why |
-|-----------|--------|-----|
-| [area] | [choice] | [reason] |
-
-## Don't Hand-Roll
-| Problem | Don't Build | Use Instead |
-|---------|-------------|-------------|
-| [problem] | [custom solution] | [existing solution] |
-
-## Common Pitfalls
-### Pitfall 1: [name]
-**What goes wrong:** [description]
-**How to avoid:** [recommendation]
-
-## Open Questions
-- [Unanswered questions for future investigation]
-
-## Sources
-### Primary (HIGH confidence)
-- [source with link]
-### Secondary (MEDIUM confidence)
-- [source with link]
-```
-
-## Common Research Mistakes
-
-| Mistake | Why It's Wrong | Do Instead |
-|---------|---------------|------------|
-| Using only AI knowledge | May be outdated or hallucinated | Fetch actual docs with WebFetch |
-| Trusting a single blog post | Could be wrong, outdated, or opinionated | Cross-reference with official docs |
-| Skipping version checks | APIs change between versions | Verify against the actual version in use |
-| Assuming current codebase is correct | Code may have bugs or outdated patterns | Verify patterns against official docs |
-| Not recording sources | Cannot verify or update findings later | Always include links and dates |
-| Research without questions | Leads to unfocused exploration | Define questions first, research to answer them |
-
-## Time Boxing
-
-Research is a means to an end, not the end itself:
-
-- **Quick lookup** (5 min): Single question, check official docs, done
-- **Standard research** (30 min): Multiple questions, cross-reference, structured output
-- **Deep investigation** (60 min): Architecture decision, multiple domains, full template
-
-If you cannot answer a question within the time box, document it as an open question and move on.