maxsimcli 4.2.3 → 4.3.0

package/dist/assets/templates/templates/conventions.md

@@ -0,0 +1,138 @@
+# CONVENTIONS.md Template
+
+Template for `.planning/CONVENTIONS.md` — the coding conventions document that agents follow without asking.
+
+<template>
+
+```markdown
+# Conventions
+
+**Generated:** {{date}}
+**Source:** {{source}}
+
+## Tech Stack
+
+Locked technology choices. Agents use these to write correct import statements and configurations.
+
+| Category | Technology | Version | Purpose |
+|----------|-----------|---------|---------|
+<!-- | Runtime | Node.js | 22.x | Server and build tooling | -->
+<!-- | Language | TypeScript | 5.x | Type safety across codebase | -->
+<!-- | Framework | Next.js | 15.x | Full-stack React framework | -->
+<!-- | Database | PostgreSQL | 16.x | Primary relational data store | -->
+<!-- | ORM | Drizzle | latest | Type-safe database queries | -->
+<!-- | Testing | Vitest | latest | Unit and integration tests | -->
+
+## File Layout
+
+Agents use this to know WHERE to create files and HOW to name them.
+
+| Type | Location | Naming Convention | Example |
+|------|----------|-------------------|---------|
+<!-- | Pages/Routes | src/app/ | kebab-case dirs | src/app/user-settings/page.tsx | -->
+<!-- | Components | src/components/ | PascalCase.tsx | src/components/UserCard.tsx | -->
+<!-- | Utilities | src/utils/ | camelCase.ts | src/utils/formatDate.ts | -->
+<!-- | API routes | src/app/api/ | route.ts in kebab-case dirs | src/app/api/auth/route.ts | -->
+<!-- | Tests | src/__tests__/ or colocated | *.test.ts | src/utils/__tests__/formatDate.test.ts | -->
+<!-- | Types | src/types/ | PascalCase.ts | src/types/User.ts | -->
+<!-- | Config | project root | lowercase dotfiles | .env.local, tsconfig.json | -->
+
+## Error Handling
+
+Agents use this to write consistent error handling across all tasks.
+
+**Pattern:** {{error_pattern}}
+<!-- Options: exceptions / Result types / error codes / error boundaries -->
+
+**Standard flow:**
+{{error_flow}}
+<!-- Describe how errors propagate through the system. Example:
+  1. Database/external errors throw typed exceptions
+  2. Service layer catches and wraps in domain errors
+  3. API layer catches domain errors and maps to HTTP status codes
+  4. Client receives structured { error, message, code } responses
+  5. Unexpected errors propagate to global error handler + logging
+-->
+
+**What to catch vs let propagate:**
+{{catch_vs_propagate}}
+<!-- Example:
+  - CATCH: Validation errors, auth failures, not-found, rate limits
+  - PROPAGATE: Unexpected errors, system failures (let global handler log + alert)
+  - NEVER SWALLOW: Errors without logging — always log before handling
+-->
+
+## Testing
+
+| Aspect | Standard |
+|--------|----------|
+| Framework | {{test_framework}} |
+| Test location | {{test_location}} |
+| Naming convention | {{test_naming}} |
+| Coverage target | {{coverage_target}} |
+| What to test per task | {{test_scope}} |
+<!-- Example values:
+  Framework: Vitest
+  Test location: Colocated __tests__/ dirs or tests/ at project root
+  Naming convention: [module].test.ts for unit, [feature].e2e.ts for e2e
+  Coverage target: 80% lines for business logic, no target for UI components
+  What to test per task: Every new function gets unit tests. API endpoints get integration tests. UI gets smoke tests only.
+-->
+```
+
+</template>
+
+<generation_notes>
+
+**Greenfield (new-project init):**
+Populate from research agent recommendations + questioning confirmations.
+- Tech Stack: from locked decisions in research synthesis
+- File Layout: from recommended framework conventions
+- Error Handling: from user's stated preference during questioning
+- Testing: from user's stated testing strategy during questioning
+- Set `{{source}}` to "new-project init"
+- Set `{{generated_or_confirmed}}` to "generated"
+
+**Brownfield (init-existing / init-existing scan + user confirmation):**
+Populate from codebase scan results (`codebase/CONVENTIONS.md`) + user confirmation of each convention.
+- Tech Stack: from detected dependencies in `codebase/STACK.md`
+- File Layout: from detected file structure in `codebase/STRUCTURE.md`
+- Error Handling: from detected patterns in `codebase/CONVENTIONS.md`
+- Testing: from detected test setup in `codebase/STACK.md`
+- Present each section to user: "Your codebase uses these patterns. Should new code follow them?"
+- Set `{{source}}` to "init-existing scan + user confirmation"
+- Set `{{generated_or_confirmed}}` to "confirmed"
+
+**Lifecycle note:**
+Generated at init. Update when conventions change. See Phase 3 (Agent Coherence) for lifecycle updates.
+
+</generation_notes>
+
+<guidelines>
+
+**Tech Stack:**
+- Only include architecturally significant choices (frameworks, databases, ORMs, runtimes)
+- Exclude utility libraries (lodash, uuid, date-fns) unless they represent a project-wide convention
+- Version should be specific enough for agents to use (major.minor, not just "latest")
+- Purpose column explains WHY this technology was chosen
+
+**File Layout:**
+- Cover all file types agents will create: components, pages, utils, tests, types, config
+- Use consistent naming conventions (PascalCase, camelCase, kebab-case)
+- Include concrete examples — agents learn from examples more than rules
+- Match the actual project structure, not an ideal one
+
+**Error Handling:**
+- Pick ONE pattern and stick with it — inconsistency is worse than any single approach
+- Describe the full flow from error origin to user-facing response
+- Be explicit about catch vs propagate — this prevents error swallowing
+
+**Testing:**
+- Coverage target should be realistic and specific to code type
+- "What to test per task" is the most important row — agents read this before writing tests
+- Include the test command if non-obvious
+
+</guidelines>
+
+---
+*Conventions {{generated_or_confirmed}}: {{date}}*

package/dist/assets/templates/templates/no-gos.md

@@ -1,9 +1,50 @@
 # No-Gos
 
-> Things explicitly out of scope or forbidden.
+> Explicit boundaries, forbidden patterns, and constraints for this project. Violating these is a blocking issue.
 
-**Created:** {{date}}
+**Generated:** {{date}}
+**Source:** {{source}}
 
-## Boundaries
+---
 
-- _No entries yet._
+## Hard Constraints
+
+> Non-negotiable technical and architectural boundaries. These are absolute -- no exceptions.
+
+| # | Constraint | Rationale |
+|---|-----------|-----------|
+| | | |
+
+---
+
+## Anti-Patterns
+
+> Patterns explicitly forbidden in this codebase. If you catch yourself reaching for one of these, stop and reconsider.
+
+| # | Pattern | Why It's Forbidden | Use Instead |
+|---|---------|-------------------|-------------|
+| | | | |
+
+---
+
+## Previous Failures
+
+> Lessons from past attempts, previous versions, or burned-on approaches. These are experience-driven no-gos.
+
+| # | What Failed | Context | Lesson |
+|---|------------|---------|--------|
+| | | | |
+
+---
+
+## Domain-Specific Risks
+
+> Common pitfalls for this type of project. These may not all apply but were flagged during initialization as worth tracking.
+
+| # | Risk | Applies To | Mitigation |
+|---|------|-----------|------------|
+| | | | |
+
+---
+
+*Confirmed by user during project initialization: {{date}}*

package/dist/assets/templates/templates/project.md

@@ -63,6 +63,21 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 |----------|-----------|---------|
 | [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
 
+## Tech Stack Decisions
+
+<!-- Locked technology choices from research synthesis. Agents treat these as constraints.
+     These are non-negotiable for the current milestone — changing them requires explicit discussion. -->
+
+| Category | Decision | Rationale | Alternatives Rejected | Effort |
+|----------|----------|-----------|----------------------|--------|
+| [e.g. Framework] | [e.g. Next.js 15] | [Why this choice] | [What was considered and why not] | [S/M/L/XL] |
+
+<!-- Effort: S = hours, M = days, L = week, XL = weeks -->
+
+<!-- If no research was conducted, this section may be empty or populated from questioning context. -->
+
+See `.planning/CONVENTIONS.md` for coding standards and file layout conventions.
+
 ---
 *Last updated: [date] after [trigger]*
 ```
@@ -117,6 +132,14 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
   - ⚠️ Revisit — decision may need reconsideration
   - — Pending — too early to evaluate
 
+**Tech Stack Decisions:**
+- Locked technology choices from research synthesis or questioning
+- Agents treat these as hard constraints — no substitutions without explicit approval
+- Each row includes: what was chosen, why, what was rejected, and effort estimate
+- Populated by research synthesizer (if research ran) or from questioning context
+- Links to CONVENTIONS.md for coding standards (file layout, error handling, testing)
+- If no research was conducted, this section may be empty or minimal
+
 **Last Updated:**
 - Always note when and why the document was updated
 - Format: `after Phase 2` or `after v1.0 milestone`

package/dist/assets/templates/workflows/batch.md

@@ -84,7 +84,7 @@ Task(
 - .planning/STATE.md (Project State)
 - .planning/ROADMAP.md (Phase structure)
 - ./CLAUDE.md (if exists — follow project-specific guidelines)
-- .skills/batch-worktree/SKILL.md (if exists — batch-worktree constraints)
+- .skills/maxsim-batch/SKILL.md (if exists — maxsim-batch constraints)
 </files_to_read>
 
 **Project skills:** Check .skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules

package/dist/assets/templates/workflows/init-existing.md

@@ -8,6 +8,7 @@ Output: `.planning/` directory with config.json, PROJECT.md, REQUIREMENTS.md, RO
 Read all files referenced by the invoking prompt's execution_context before starting.
 @./references/dashboard-bridge.md
 @./references/thinking-partner.md
+@./references/questioning.md
 </required_reading>
 
 <tool_mandate>
@@ -535,6 +536,130 @@ Apply thinking-partner behaviors when presenting findings:
 - **Make consequences visible** — "Your architecture pattern means Y for future phases."
 - **Propose alternatives** — If concerns were found, suggest approaches: "The scan found tech debt in Z. We could address it early or defer — here are the trade-offs."
 
+## Step 6b: Stack Preference Questions
+
+**If auto mode:** Skip. Use all detected technologies as-is (keep all). Proceed to Step 6c.
+
+Read `.planning/codebase/STACK.md` and extract architecturally significant dependencies.
+
+**Filter to only framework-level choices:**
+- Framework (React, Next.js, Express, Django, etc.)
+- Database (PostgreSQL, MongoDB, Redis, etc.)
+- ORM/Query builder (Drizzle, Prisma, SQLAlchemy, etc.)
+- State management (Redux, Zustand, Vuex, etc.)
+- Testing framework (Vitest, Jest, pytest, etc.)
+- Build tools (Vite, Webpack, tsup, etc.)
+
+**Explicitly EXCLUDE:**
+- Utility libraries (lodash, uuid, date-fns, etc.)
+- Dev tools (prettier, eslint, biome, etc.)
+- Type definitions (@types/*)
+- Runtime dependencies that are implementation details
+
+**Cap at 8-10 items max** to avoid overwhelming the user.
+
+Present to user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► STACK PREFERENCES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Your codebase uses these key technologies. For each, do you want to keep, evolve, or replace?
+```
+
+For each significant dependency, use AskUserQuestion:
+- header: "[Technology Name]"
+- question: "[Technology] [version] -- [detected purpose]"
+- options:
+  - "Keep" -- Continue using [Technology] as-is
+  - "Evolve" -- Upgrade or modernize (describe target)
+  - "Replace" -- Switch to alternative (describe replacement)
+
+If "Evolve" or "Replace": capture the target via freeform follow-up.
+
+**Capture decisions as constraints** for CONVENTIONS.md and DECISIONS.md. "Keep" entries become locked stack conventions. "Evolve" entries become phase goals. "Replace" entries become phase goals with migration requirements.
+
+## Step 6c: Convention Confirmation
+
+**If auto mode:** Skip. Promote all scan-detected conventions as-is. Proceed to Step 6d.
+
+Read `.planning/codebase/CONVENTIONS.md` (from the codebase mapper agent) and extract detected coding conventions.
+
+Present scan-detected conventions to user for confirmation:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► CONVENTION CONFIRMATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Your codebase uses these patterns. Should new code follow them?
+```
+
+For each major convention category (file naming, error handling, testing patterns, code style):
+
+Use AskUserQuestion:
+- header: "[Convention Category]"
+- question: "Detected: [description of convention]. Should new code follow this?"
+- options:
+  - "Yes, follow this" -- Promote to project convention
+  - "No, change it" -- Describe the preferred convention
+  - "Not sure" -- Skip for now
+
+If "No, change it": capture the preferred convention via freeform.
+
+**Promote confirmed conventions** to `.planning/CONVENTIONS.md` using the template from `templates/conventions.md`:
+- Tech Stack: from Step 6b stack preferences (keep/evolve decisions)
+- File Layout: from confirmed file structure conventions
+- Error Handling: from confirmed error handling patterns
+- Testing: from confirmed testing conventions
+- Set `{{source}}` to "init-existing scan + user confirmation"
+- Set `{{generated_or_confirmed}}` to "confirmed"
+
+Write `.planning/CONVENTIONS.md`:
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write .planning/CONVENTIONS.md
+```
+
+## Step 6d: No-Gos from Scan
+
+**If auto mode:** Skip. Auto-generate no-gos from CONCERNS.md findings. Proceed to Step 7.
+
+Read `.planning/codebase/CONCERNS.md` (if it exists) and extract findings as candidate no-gos.
+
+Present scan findings as candidate no-gos:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► NO-GOS FROM CODEBASE SCAN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Based on the codebase scan, here are potential no-gos for new code:
+```
+
+For each significant finding from CONCERNS.md:
+
+Use AskUserQuestion:
+- header: "No-Go?"
+- question: "[Finding from CONCERNS.md] -- should this be a no-go for new code?"
+- options:
+  - "Yes, add as no-go" -- This should be explicitly forbidden
+  - "No, skip" -- This is acceptable or not relevant
+  - "Modify" -- I want to adjust the wording
+
+If "Modify": capture adjusted wording via freeform.
+
+After all findings are reviewed:
+
+Use AskUserQuestion:
+- header: "Additional"
+- question: "Any additional no-gos based on your experience with this codebase?"
+- options:
+  - "No, that covers it" -- Proceed
+  - "Yes, let me add" -- Capture additional no-gos
+
+Confirmed no-gos flow into NO-GOS.md during document generation (Step 9f) using the structured template from `templates/no-gos.md`.
+
 ## Step 7: Future Direction Questions
 
 **If auto mode:** Skip. Generate generic "continue development" goals. Proceed to Step 9.
@@ -1104,6 +1229,61 @@ Write content:
 node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: generate initialization artefakte" --files .planning/DECISIONS.md .planning/ACCEPTANCE-CRITERIA.md .planning/NO-GOS.md
 ```
 
+## Step 9g: Agent Dry-Run Validation
+
+**Always runs after all documents are generated — this is the quality gate for init output.**
+
+Spawn a test agent to validate that all generated docs contain enough information for a fresh agent to start Phase 1 without asking clarifying questions.
+
+```
+Task(prompt="
+You are a fresh agent about to start Phase 1 of this project.
+Read the following files and report what you would need to ask before starting work.
+
+Do NOT infer missing information. If a specific library version is not stated, report it as a gap.
+If the error handling pattern is not described, report it as a gap.
+Your job is to find what is NOT written, not to demonstrate you could figure it out.
+
+<files_to_read>
+- .planning/PROJECT.md
+- .planning/REQUIREMENTS.md
+- .planning/CONVENTIONS.md
+- .planning/NO-GOS.md
+- .planning/ROADMAP.md
+</files_to_read>
+
+Report format:
+
+## DRY-RUN RESULT
+
+### Can Start: YES/NO
+
+### Gaps Found:
+- [What information is missing]
+- [What is ambiguous]
+- [What would need clarification]
+
+### Quality Score: [1-10]
+(10 = could start immediately with zero questions, 1 = need major clarifications)
+", model="{planner_model}", description="Agent readiness dry-run")
+```
+
+**Handle dry-run results:**
+
+**If gaps found (Can Start = NO or Quality Score < 7):**
+- For each gap, update the relevant document to fill it:
+  - Missing tech versions → update CONVENTIONS.md Tech Stack
+  - Missing error handling → update CONVENTIONS.md Error Handling
+  - Ambiguous requirements → update REQUIREMENTS.md
+  - Missing constraints → update NO-GOS.md
+- Commit the fixes:
+  ```bash
+  node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: fill gaps from agent dry-run validation" --files .planning/PROJECT.md .planning/REQUIREMENTS.md .planning/CONVENTIONS.md .planning/NO-GOS.md
+  ```
+
+**If no gaps (Can Start = YES and Quality Score >= 7):**
+- Continue to Step 10.
+
 ## Step 10: Git Stage and Summary
 
 Stage all changed files:
@@ -1126,6 +1306,7 @@ Print structured summary:
 Created:
   ✓ .planning/config.json         -- Workflow preferences
   ✓ .planning/PROJECT.md          -- Project context + current state
+  ✓ .planning/CONVENTIONS.md      -- Confirmed coding conventions for agents
   ✓ .planning/REQUIREMENTS.md     -- [Stage]-format requirements
   ✓ .planning/ROADMAP.md          -- [Milestone name] + [N] phases
   ✓ .planning/STATE.md            -- Pre-populated project memory
@@ -1167,6 +1348,7 @@ Print next steps:
 
 - `.planning/config.json`
 - `.planning/PROJECT.md`
+- `.planning/CONVENTIONS.md`
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
@@ -1200,6 +1382,11 @@ Print next steps:
 - [ ] config.json created with workflow settings
 - [ ] .planning/codebase/ populated with scan documents
 - [ ] Git staging completed
+- [ ] Stack preference questions asked (keep/evolve/replace for framework-level choices)
+- [ ] Convention confirmation completed (scan-detected conventions presented to user)
+- [ ] CONVENTIONS.md generated from confirmed conventions
+- [ ] CONCERNS.md findings presented as candidate no-gos
+- [ ] Agent dry-run validation passed (Quality Score >= 7)
 - [ ] Structured summary printed
 - [ ] Next steps suggested: /maxsim:roadmap then /maxsim:plan-phase 1