mindforge-cc 2.0.0 → 2.1.1

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

@@ -0,0 +1,122 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,91 @@
+# 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

@@ -0,0 +1,117 @@
+# 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/Execution/CONTINUE-HERE.md

@@ -0,0 +1,78 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Where exactly are we? What's the immediate context?]
+</current_state>
+
+<completed_work>
+[What got done this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</completed_work>
+
+<remaining_work>
+[What's left in this phase]
+
+- Task 3: [name] - [what's left to do]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</remaining_work>
+
+<decisions_made>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</context>
+
+<next_action>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</next_action>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `phase`: Directory name (e.g., `02-authentication`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in phase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh the agent instance understands immediately
+- Include WHY decisions were made, not just what
+- The `<next_action>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>

package/docs/templates/Execution/DISCUSSION-LOG.md

@@ -0,0 +1,63 @@
+# Discussion Log Template
+
+Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit trail of discuss-phase Q&A sessions.
+
+**Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents.
+
+**NOT for LLM consumption.** This file should never be referenced in `<files_to_read>` blocks or agent prompts.
+
+## Format
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+## [Area 1 Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Brief description] | |
+| [Option 2] | [Brief description] | ✓ |
+| [Option 3] | [Brief description] | |
+
+**User's choice:** [Selected option or verbatim free-text response]
+**Notes:** [Any clarifications or rationale provided during discussion]
+
+---
+
+## [Area 2 Name]
+
+...
+
+---
+
+## the agent's Discretion
+
+[Areas delegated to the agent's judgment — list what was deferred and why]
+
+## Deferred Ideas
+
+[Ideas mentioned but not in scope for this phase]
+
+---
+
+*Phase: XX-name*
+*Discussion log generated: [date]*
+```
+
+## Rules
+
+- Generated automatically at end of every discuss-phase session
+- Includes ALL options considered, not just the selected one
+- Includes user's freeform notes and clarifications
+- Clearly marked as audit-only, not an implementation artifact
+- Does NOT interfere with CONTEXT.md generation or downstream agent behavior
+- Committed alongside CONTEXT.md in the same git commit