mindforge-cc 9.0.0 → 10.0.0

package/docs/Templates/Agents/CLAUDE-MD.md

@@ -1,122 +0,0 @@
-# GEMINI.md Template
-
-Template for project-root `GEMINI.md` — auto-generated by `mindforge-tools generate-claude-md`.
-
-Contains 6 marker-bounded sections. Each section is independently updatable.
-The `generate-claude-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement).
-The profile section is managed exclusively by `generate-claude-profile`.
-
----
-
-## Section Templates
-
-### Project Section
-```
-<!-- MindForge:project-start source:PROJECT.md -->
-## Project
-
-{{project_content}}
-<!-- MindForge:project-end -->
-```
-
-**Fallback text:**
-```
-Project not yet initialized. Run /mindforge-new-project to set up.
-```
-
-### Stack Section
-```
-<!-- MindForge:stack-start source:STACK.md -->
-## Technology Stack
-
-{{stack_content}}
-<!-- MindForge:stack-end -->
-```
-
-**Fallback text:**
-```
-Technology stack not yet documented. Will populate after codebase mapping or first phase.
-```
-
-### Conventions Section
-```
-<!-- MindForge:conventions-start source:CONVENTIONS.md -->
-## Conventions
-
-{{conventions_content}}
-<!-- MindForge:conventions-end -->
-```
-
-**Fallback text:**
-```
-Conventions not yet established. Will populate as patterns emerge during development.
-```
-
-### Architecture Section
-```
-<!-- MindForge:architecture-start source:ARCHITECTURE.md -->
-## Architecture
-
-{{architecture_content}}
-<!-- MindForge:architecture-end -->
-```
-
-**Fallback text:**
-```
-Architecture not yet mapped. Follow existing patterns found in the codebase.
-```
-
-### Workflow Enforcement Section
-```
-<!-- MindForge:workflow-start source:MindForge defaults -->
-## MindForge Workflow Enforcement
-
-Before using Edit, Write, or other file-changing tools, start work through a MindForge command so planning artifacts and execution context stay in sync.
-
-Use these entry points:
-- `/mindforge-quick` for small fixes, doc updates, and ad-hoc tasks
-- `/mindforge-debug` for investigation and bug fixing
-- `/mindforge-execute-phase` for planned phase work
-
-Do not make direct repo edits outside a MindForge workflow unless the user explicitly asks to bypass it.
-<!-- MindForge:workflow-end -->
-```
-
-### Profile Section (Placeholder Only)
-```
-<!-- MindForge:profile-start -->
-## Developer Profile
-
-> Profile not yet configured. Run `/mindforge-profile-user` to generate your developer profile.
-> This section is managed by `generate-claude-profile` — do not edit manually.
-<!-- MindForge:profile-end -->
-```
-
-**Note:** This section is NOT managed by `generate-claude-md`. It is managed exclusively
-by `generate-claude-profile`. The placeholder above is only used when creating a new
-GEMINI.md file and no profile section exists yet.
-
----
-
-## Section Ordering
-
-1. **Project** — Identity and purpose (what this project is)
-2. **Stack** — Technology choices (what tools are used)
-3. **Conventions** — Code patterns and rules (how code is written)
-4. **Architecture** — System structure (how components fit together)
-5. **Workflow Enforcement** — Default MindForge entry points for file-changing work
-6. **Profile** — Developer behavioral preferences (how to interact)
-
-## Marker Format
-
-- Start: `<!-- MindForge:{name}-start source:{file} -->`
-- End: `<!-- MindForge:{name}-end -->`
-- Source attribute enables targeted updates when source files change
-- Partial match on start marker (without closing `-->`) for detection
-
-## Fallback Behavior
-
-When a source file is missing, fallback text provides Claude-actionable guidance:
-- Guides the agent's behavior in the absence of data
-- Not placeholder ads or "missing" notices
-- Each fallback tells the agent what to do, not just what's absent

package/docs/Templates/Agents/COPILOT-INSTRUCTIONS.md

@@ -1,7 +0,0 @@
-# Instructions for MindForge
-
-- Use the mindforge skill when the user asks for MindForge or uses a `mindforge-*` command.
-- Treat `/mindforge-...` or `mindforge-...` as command invocations and load the matching file from `.github/skills/mindforge-*`.
-- When a command says to spawn a subagent, prefer a matching custom agent from `.github/agents`.
-- Do not apply MindForge workflows unless the user explicitly asks for them.
-- After completing any `mindforge-*` command (or any deliverable it triggers: feature, bug fix, tests, docs, etc.), ALWAYS: (1) offer the user the next step by prompting via `ask_user`; repeat this feedback loop until the user explicitly indicates they are done.

package/docs/Templates/Agents/DEBUGGER-PROMPT.md

@@ -1,91 +0,0 @@
-# Debug Subagent Prompt Template
-
-Template for spawning mindforge-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
-
----
-
-## Template
-
-```markdown
-<objective>
-Investigate issue: {issue_id}
-
-**Summary:** {issue_summary}
-</objective>
-
-<symptoms>
-expected: {expected}
-actual: {actual}
-errors: {errors}
-reproduction: {reproduction}
-timeline: {timeline}
-</symptoms>
-
-<mode>
-symptoms_prefilled: {true_or_false}
-goal: {find_root_cause_only | find_and_fix}
-</mode>
-
-<debug_file>
-Create: .planning/debug/{slug}.md
-</debug_file>
-```
-
----
-
-## Placeholders
-
-| Placeholder | Source | Example |
-|-------------|--------|---------|
-| `{issue_id}` | MindForge Principal-assigned | `auth-screen-dark` |
-| `{issue_summary}` | User description | `Auth screen is too dark` |
-| `{expected}` | From symptoms | `See logo clearly` |
-| `{actual}` | From symptoms | `Screen is dark` |
-| `{errors}` | From symptoms | `None in console` |
-| `{reproduction}` | From symptoms | `Open /auth page` |
-| `{timeline}` | From symptoms | `After recent deploy` |
-| `{goal}` | MindForge Principal sets | `find_and_fix` |
-| `{slug}` | Generated | `auth-screen-dark` |
-
----
-
-## Usage
-
-**From /mindforge-debug:**
-```python
-Task(
-  prompt=filled_template,
-  subagent_type="mindforge-debugger",
-  description="Debug {slug}"
-)
-```
-
-**From diagnose-issues (UAT):**
-```python
-Task(prompt=template, subagent_type="mindforge-debugger", description="Debug UAT-001")
-```
-
----
-
-## Continuation
-
-For checkpoints, spawn fresh agent with:
-
-```markdown
-<objective>
-Continue debugging {slug}. Evidence is in the debug file.
-</objective>
-
-<prior_state>
-Debug file: @.planning/debug/{slug}.md
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-
-<mode>
-goal: {goal}
-</mode>
-```

package/docs/Templates/Agents/PLANNER-PROMPT.md

@@ -1,117 +0,0 @@
-# Planner Subagent Prompt Template
-
-Template for spawning mindforge-planner agent. The agent contains all planning expertise - this template provides planning context only.
-
----
-
-## Template
-
-```markdown
-<planning_context>
-
-**Phase:** {phase_number}
-**Mode:** {standard | gap_closure}
-
-**Project State:**
-@.planning/STATE.md
-
-**Roadmap:**
-@.planning/ROADMAP.md
-
-**Requirements (if exists):**
-@.planning/REQUIREMENTS.md
-
-**Phase Context (if exists):**
-@.planning/phases/{phase_dir}/{phase_num}-CONTEXT.md
-
-**Research (if exists):**
-@.planning/phases/{phase_dir}/{phase_num}-RESEARCH.md
-
-**Gap Closure (if --gaps mode):**
-@.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
-@.planning/phases/{phase_dir}/{phase_num}-UAT.md
-
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /mindforge-execute-phase
-Plans must be executable prompts with:
-- Frontmatter (wave, depends_on, files_modified, autonomous)
-- Tasks in XML format
-- Verification criteria
-- must_haves for goal-backward verification
-</downstream_consumer>
-
-<quality_gate>
-Before returning PLANNING COMPLETE:
-- [ ] PLAN.md files created in phase directory
-- [ ] Each plan has valid frontmatter
-- [ ] Tasks are specific and actionable
-- [ ] Dependencies correctly identified
-- [ ] Waves assigned for parallel execution
-- [ ] must_haves derived from phase goal
-</quality_gate>
-```
-
----
-
-## Placeholders
-
-| Placeholder | Source | Example |
-|-------------|--------|---------|
-| `{phase_number}` | From roadmap/arguments | `5` or `2.1` |
-| `{phase_dir}` | Phase directory name | `05-user-profiles` |
-| `{phase}` | Phase prefix | `05` |
-| `{standard \| gap_closure}` | Mode flag | `standard` |
-
----
-
-## Usage
-
-**From /mindforge-plan-phase (standard mode):**
-```python
-Task(
-  prompt=filled_template,
-  subagent_type="mindforge-planner",
-  description="Plan Phase {phase}"
-)
-```
-
-**From /mindforge-plan-phase --gaps (gap closure mode):**
-```python
-Task(
-  prompt=filled_template,  # with mode: gap_closure
-  subagent_type="mindforge-planner",
-  description="Plan gaps for Phase {phase}"
-)
-```
-
----
-
-## Continuation
-
-For checkpoints, spawn fresh agent with:
-
-```markdown
-<objective>
-Continue planning for Phase {phase_number}: {phase_name}
-</objective>
-
-<prior_state>
-Phase directory: @.planning/phases/{phase_dir}/
-Existing plans: @.planning/phases/{phase_dir}/*-PLAN.md
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-
-<mode>
-Continue: {standard | gap_closure}
-</mode>
-```
-
----
-
-**Note:** Planning methodology, task breakdown, dependency analysis, wave assignment, TDD detection, and goal-backward derivation are baked into the mindforge-planner agent. This template only passes context.

package/docs/Templates/Codebase/architecture.md

@@ -1,255 +0,0 @@
-# Architecture Template
-
-Template for `.mindforge/codebase/ARCHITECTURE.md` - captures conceptual code organization.
-
-**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
-
----
-
-## File Template
-
-```markdown
-# Architecture
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Pattern Overview
-
-**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
-
-**Key Characteristics:**
-- [Characteristic 1: e.g., "Single executable"]
-- [Characteristic 2: e.g., "Stateless request handling"]
-- [Characteristic 3: e.g., "Event-driven"]
-
-## Layers
-
-[Describe the conceptual layers and their responsibilities]
-
-**[Layer Name]:**
-- Purpose: [What this layer does]
-- Contains: [Types of code: e.g., "route handlers", "business logic"]
-- Depends on: [What it uses: e.g., "data layer only"]
-- Used by: [What uses it: e.g., "API routes"]
-
-**[Layer Name]:**
-- Purpose: [What this layer does]
-- Contains: [Types of code]
-- Depends on: [What it uses]
-- Used by: [What uses it]
-
-## Data Flow
-
-[Describe the typical request/execution lifecycle]
-
-**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
-
-1. [Entry point: e.g., "User runs command"]
-2. [Processing step: e.g., "Router matches path"]
-3. [Processing step: e.g., "Controller validates input"]
-4. [Processing step: e.g., "Service executes logic"]
-5. [Output: e.g., "Response returned"]
-
-**State Management:**
-- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
-
-## Key Abstractions
-
-[Core concepts/patterns used throughout the codebase]
-
-**[Abstraction Name]:**
-- Purpose: [What it represents]
-- Examples: [e.g., "UserService, ProjectService"]
-- Pattern: [e.g., "Singleton", "Factory", "Repository"]
-
-**[Abstraction Name]:**
-- Purpose: [What it represents]
-- Examples: [Concrete examples]
-- Pattern: [Pattern used]
-
-## Entry Points
-
-[Where execution begins]
-
-**[Entry Point]:**
-- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
-- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
-- Responsibilities: [What it does: e.g., "Parse args, route to command"]
-
-## Error Handling
-
-**Strategy:** [How errors are handled: e.g., "Exception bubbling to top-level handler", "Per-route error middleware"]
-
-**Patterns:**
-- [Pattern: e.g., "try/catch at controller level"]
-- [Pattern: e.g., "Error codes returned to user"]
-
-## Cross-Cutting Concerns
-
-[Aspects that affect multiple layers]
-
-**Logging:**
-- [Approach: e.g., "Winston logger, injected per-request"]
-
-**Validation:**
-- [Approach: e.g., "Zod schemas at API boundary"]
-
-**Authentication:**
-- [Approach: e.g., "JWT middleware on protected routes"]
-
----
-
-*Architecture analysis: [date]*
-*Update when major patterns change*
-```
-
-<good_examples>
-```markdown
-# Architecture
-
-**Analysis Date:** 2025-01-20
-
-## Pattern Overview
-
-**Overall:** CLI Application with Plugin System
-
-**Key Characteristics:**
-- Single executable with subcommands
-- Plugin-based extensibility
-- File-based state (no database)
-- Synchronous execution model
-
-## Layers
-
-**Command Layer:**
-- Purpose: Parse user input and route to appropriate handler
-- Contains: Command definitions, argument parsing, help text
-- Location: `src/commands/*.ts`
-- Depends on: Service layer for business logic
-- Used by: CLI entry point (`src/index.ts`)
-
-**Service Layer:**
-- Purpose: Core business logic
-- Contains: FileService, TemplateService, InstallService
-- Location: `src/services/*.ts`
-- Depends on: File system utilities, external tools
-- Used by: Command handlers
-
-**Utility Layer:**
-- Purpose: Shared helpers and abstractions
-- Contains: File I/O wrappers, path resolution, string formatting
-- Location: `src/utils/*.ts`
-- Depends on: Node.js built-ins only
-- Used by: Service layer
-
-## Data Flow
-
-**CLI Command Execution:**
-
-1. User runs: `mindforge new-project`
-2. Commander parses args and flags
-3. Command handler invoked (`src/commands/new-project.ts`)
-4. Handler calls service methods (`src/services/project.ts` → `create()`)
-5. Service reads templates, processes files, writes output
-6. Results logged to console
-7. Process exits with status code
-
-**State Management:**
-- File-based: All state lives in `.mindforge/` directory
-- No persistent in-memory state
-- Each command execution is independent
-
-## Key Abstractions
-
-**Service:**
-- Purpose: Encapsulate business logic for a domain
-- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
-- Pattern: Singleton-like (imported as modules, not instantiated)
-
-**Command:**
-- Purpose: CLI command definition
-- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
-- Pattern: Commander.js command registration
-
-**Template:**
-- Purpose: Reusable document structures
-- Examples: MINDFORGE.md, PLAN.md templates
-- Pattern: Markdown files with substitution variables
-
-## Entry Points
-
-**CLI Entry:**
-- Location: `src/index.ts`
-- Triggers: User runs `mindforge <command>`
-- Responsibilities: Register commands, parse args, display help
-
-**Commands:**
-- Location: `src/commands/*.ts`
-- Triggers: Matched command from CLI
-- Responsibilities: Validate input, call services, format output
-
-## Error Handling
-
-**Strategy:** Throw exceptions, catch at command level, log and exit
-
-**Patterns:**
-- Services throw Error with descriptive messages
-- Command handlers catch, log error to stderr, exit(1)
-- Validation errors shown before execution (fail fast)
-
-## Cross-Cutting Concerns
-
-**Logging:**
-- Console.log for normal output
-- Console.error for errors
-- Chalk for colored output
-
-**Validation:**
-- Zod schemas for config file parsing
-- Manual validation in command handlers
-- Fail fast on invalid input
-
-**File Operations:**
-- FileService abstraction over fs-extra
-- All paths validated before operations
-- Atomic writes (temp file + rename)
-
----
-
-*Architecture analysis: 2025-01-20*
-*Update when major patterns change*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in ARCHITECTURE.md:**
-- Overall architectural pattern (monolith, microservices, layered, etc.)
-- Conceptual layers and their relationships
-- Data flow / request lifecycle
-- Key abstractions and patterns
-- Entry points
-- Error handling strategy
-- Cross-cutting concerns (logging, auth, validation)
-
-**What does NOT belong here:**
-- Exhaustive file listings (that's STRUCTURE.md)
-- Technology choices (that's STACK.md)
-- Line-by-line code walkthrough (defer to code reading)
-- Implementation details of specific features
-
-**File paths ARE welcome:**
-Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for MindForge when planning.
-
-**When filling this template:**
-- Read main entry points (index, server, main)
-- Identify layers by reading imports/dependencies
-- Trace a typical request/command execution
-- Note recurring patterns (services, controllers, repositories)
-- Keep descriptions conceptual, not mechanical
-
-**Useful for phase planning when:**
-- Adding new features (where does it fit in the layers?)
-- Refactoring (understanding current patterns)
-- Identifying where to add code (which layer handles X?)
-- Understanding dependencies between components
-</guidelines>