mindforge-cc 1.0.0

package/.planning/HANDOFF.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "1.0.0",
+  "project": null,
+  "phase": null,
+  "plan": null,
+  "plan_step": null,
+  "last_completed_task": {
+    "description": null,
+    "commit_sha": null,
+    "verified": null
+  },
+  "next_task": "Run /mindforge:init-project",
+  "in_progress": {
+    "file": null,
+    "intent": null,
+    "completed_steps": [],
+    "remaining_steps": []
+  },
+  "blockers": [],
+  "decisions_needed": [],
+  "context_refs": [],
+  "agent_notes": "",
+  "session_summary": "",
+  "recent_files": [],
+  "recent_commits": [],
+  "updated_at": null,
+  "_warning": "Never store secrets, tokens, or passwords in this file. It is tracked in git."
+}

package/.planning/PROJECT.md

@@ -0,0 +1,33 @@
+# [Project Name]
+
+> One sentence describing what this project does and for whom.
+
+## Status
+🚧 In development — Phase 0 (not started)
+
+## Problem statement
+[What pain does this solve? Be specific.]
+
+## Target users
+[Who uses this? Describe them precisely. Avoid "developers" — say "solo developers
+building production apps with Claude Code who want structured AI workflows."]
+
+## Tech stack
+| Layer      | Technology  | Version | Rationale                        |
+|------------|-------------|---------|----------------------------------|
+|            |             |         |                                  |
+
+## v1 Scope — IN
+- [ ] [Feature 1]
+- [ ] [Feature 2]
+
+## v1 Scope — OUT (explicitly excluded)
+- [Item 1] — reason: [why not v1]
+- [Item 2] — reason: [why not v1]
+
+## Success criteria
+[How will you know v1 is done? Be specific and measurable.]
+
+## Key constraints
+- [Constraint 1]
+- [Constraint 2]

package/.planning/RELEASE-CHECKLIST.md

@@ -0,0 +1,68 @@
+# MindForge v1.0.0 — Release Checklist
+
+Use this file to record verification results for the 50-point production
+readiness checklist in `.mindforge/production/production-checklist.md`.
+
+## Metadata
+- Target version: v1.0.0
+- Release date: 2026-03-22
+- Release manager: [name]
+
+## Verification log
+| Item | Result | Verified by | Date | Notes |
+|---|---|---|---|---|
+| A01 |  |  |  |  |
+| A02 |  |  |  |  |
+| A03 |  |  |  |  |
+| A04 |  |  |  |  |
+| A05 |  |  |  |  |
+| A06 |  |  |  |  |
+| A07 |  |  |  |  |
+| A08 |  |  |  |  |
+| A09 |  |  |  |  |
+| A10 |  |  |  |  |
+| B01 |  |  |  |  |
+| B02 |  |  |  |  |
+| B03 |  |  |  |  |
+| B04 |  |  |  |  |
+| B05 |  |  |  |  |
+| B06 |  |  |  |  |
+| B07 |  |  |  |  |
+| B08 |  |  |  |  |
+| B09 |  |  |  |  |
+| B10 |  |  |  |  |
+| C01 |  |  |  |  |
+| C02 |  |  |  |  |
+| C03 |  |  |  |  |
+| C04 |  |  |  |  |
+| C05 |  |  |  |  |
+| C06 |  |  |  |  |
+| C07 |  |  |  |  |
+| C08 |  |  |  |  |
+| C09 |  |  |  |  |
+| C10 |  |  |  |  |
+| D01 |  |  |  |  |
+| D02 |  |  |  |  |
+| D03 |  |  |  |  |
+| D04 |  |  |  |  |
+| D05 |  |  |  |  |
+| D06 |  |  |  |  |
+| D07 |  |  |  |  |
+| D08 |  |  |  |  |
+| D09 |  |  |  |  |
+| D10 |  |  |  |  |
+| E01 |  |  |  |  |
+| E02 |  |  |  |  |
+| E03 |  |  |  |  |
+| E04 |  |  |  |  |
+| E05 |  |  |  |  |
+| E06 |  |  |  |  |
+| E07 |  |  |  |  |
+| E08 |  |  |  |  |
+| E09 |  |  |  |  |
+| E10 |  |  |  |  |
+| F01 |  |  |  |  |
+| F02 |  |  |  |  |
+| F03 |  |  |  |  |
+| F04 |  |  |  |  |
+| F05 |  |  |  |  |

package/.planning/STATE.md

@@ -0,0 +1,31 @@
+# MindForge — Project State
+
+## Status
+🔴 Not started
+
+## IMPORTANT
+HANDOFF.json is committed to git. Never write secrets or credentials into it.
+Write "see .env" or "stored in secrets manager" if a note needs to reference credentials.
+
+
+## Current phase
+None
+
+## Last completed task
+None — project not yet initialised.
+
+## Next action
+Run `/mindforge:init-project` to initialise this project.
+
+## Decisions made
+None yet.
+
+## Active blockers
+None.
+
+## Context for next session
+Fresh MindForge install. No project has been initialised yet.
+Start by running `/mindforge:init-project`.
+
+## Last updated
+[ISO 8601 timestamp on first use]

package/.planning/approvals/.gitkeep

@@ -0,0 +1 @@
+

package/.planning/archive/.gitkeep

@@ -0,0 +1 @@
+

package/.planning/audit-archive/.gitkeep

@@ -0,0 +1 @@
+

package/.planning/decisions/ADR-001-handoff-tracking.md

@@ -0,0 +1,41 @@
+# ADR-001: Track HANDOFF.json in git
+
+**Status:** Accepted
+**Date:** 2026-03-20
+**Deciders:** MindForge core team
+
+## Context
+HANDOFF.json stores the current session state for agent continuity.
+It needs to be readable by the next agent session. The question is whether
+it should be committed to git (team-visible) or gitignored (local-only).
+
+## Decision
+Track HANDOFF.json in git.
+
+## Options considered
+
+### Option A — Track in git (chosen)
+Pros:
+- Any team member or new machine can pick up where the last session left off
+- Git history shows the evolution of session state
+- No risk of losing state on machine failure
+
+Cons:
+- File changes create noise in git history
+- Risk of accidentally committing sensitive session data
+
+Mitigations:
+- Added `_warning` field to prevent accidental secret storage
+- SUMMARY.md captures human-readable history; HANDOFF.json is machine state only
+
+### Option B — Gitignore
+Pros: No git noise, no secret exposure risk
+Cons: State lost on machine switch or re-clone; breaks team continuity
+
+## Rationale
+Team continuity outweighs the git noise concern. The warning field and
+documentation mitigate the secret exposure risk sufficiently.
+
+## Consequences
+Team must be educated to never write secrets into HANDOFF.json.
+CI should include a secret-scanning step that checks HANDOFF.json.

package/.planning/decisions/ADR-002-markdown-commands.md

@@ -0,0 +1,46 @@
+# ADR-002: Use Markdown files for slash commands (not TypeScript)
+
+**Status:** Accepted
+**Date:** 2026-03-20
+**Deciders:** MindForge core team
+
+## Context
+MindForge slash commands could be implemented as:
+A) Markdown instruction files (what we chose)
+B) TypeScript/JavaScript executable scripts
+C) A mix of both
+
+## Decision
+Markdown instruction files for all commands.
+
+## Options considered
+
+### Option A — Markdown instruction files (chosen)
+Pros:
+- Readable and editable without a build step
+- Can be updated directly by modifying text — no recompile
+- Agents can read and follow them natively
+- Community can contribute without TypeScript knowledge
+- Work identically across all runtimes (Claude Code, Antigravity, OpenCode)
+
+Cons:
+- No type safety for command logic
+- Cannot run unit tests on individual steps
+- Edge case handling is described in prose, not enforced in code
+
+### Option B — TypeScript scripts
+Pros: Type safety, unit testable, programmatic edge case handling
+Cons: Build step required, runtime-specific, harder to contribute to,
+      loses the "human-readable instructions" quality that makes them good agent prompts
+
+### Option C — Mix
+Assessed as worst of both: complexity of both without full benefit of either.
+
+## Rationale
+MindForge commands are agent prompts, not programs. Their primary consumer is
+an AI agent reading natural language. Markdown is the best format for that use case.
+Logic enforcement happens through agent quality gates, not code compilation.
+
+## Consequences
+Command edge cases must be described carefully in prose.
+A future "command validator" tool could parse and verify command files statically.

package/.planning/decisions/ADR-003-skills-trigger-model.md

@@ -0,0 +1,37 @@
+# ADR-003: Keyword-trigger model for skill discovery
+
+**Status:** Accepted
+**Date:** 2026-03-20
+**Deciders:** MindForge core team
+
+## Context
+Skills need to be loaded by the agent at the right time. The question is
+how the agent knows which skills are relevant for a given task.
+
+## Decision
+Keyword matching against a `triggers:` list in skill frontmatter.
+
+## Options considered
+
+### Option A — Keyword triggers in frontmatter (chosen)
+Pros: Simple, transparent, editable by anyone, no dependency on AI judgment
+Cons: Can miss contextual relevance; false positives on common words
+
+### Option B — AI decides which skills to load
+Pros: Contextually accurate matching
+Cons: Non-deterministic; different sessions might load different skills
+      for the same task; hard to debug; requires extra model call
+
+### Option C — Explicit user invocation only
+Pros: Precise control
+Cons: Loses the "just-in-time" benefit; users forget to invoke skills
+
+## Rationale
+Determinism is more valuable than perfect accuracy for a framework.
+Teams need to be able to predict what skills will activate. Keyword triggers
+provide that predictability. False positives are acceptable — loading a skill
+unnecessarily has low cost; missing a needed skill has high cost.
+
+## Consequences
+Trigger keyword lists must be maintained as skills evolve.
+A skill with too-narrow triggers will be missed. Err on the side of more triggers.

package/.planning/decisions/ADR-004-wave-parallelism-model.md

@@ -0,0 +1,45 @@
+# ADR-004: Wave-based parallel execution over full parallelism
+
+**Status:** Accepted
+**Date:** 2026-03-20
+**Deciders:** MindForge core team
+
+## Context
+When executing multiple tasks in a phase, we can choose:
+A) Run all tasks simultaneously (maximum parallelism)
+B) Run tasks in dependency-ordered waves (wave parallelism — chosen)
+C) Run tasks sequentially (no parallelism)
+
+## Decision
+Wave-based parallel execution. Tasks within a wave run in parallel.
+Waves execute sequentially.
+
+## Options considered
+
+### Option A — Full parallelism
+Pros: Maximum speed
+Cons: Cannot handle dependencies safely. If Plan 03 depends on Plan 01's output
+and both run simultaneously, Plan 03 reads stale data. Produces corrupt output.
+
+### Option B — Wave parallelism (chosen)
+Pros: Safely parallel within dependency constraints. Significantly faster than
+sequential. Dependency correctness is guaranteed by wave ordering.
+Cons: Some tasks that could theoretically run in parallel must wait for their
+dependency wave to complete.
+
+### Option C — Sequential
+Pros: Simplest to implement and reason about.
+Cons: Discards the primary quality advantage of parallel subagents — isolated
+200K token contexts per task. In sequential mode, the orchestrator's context
+fills up across tasks, degrading output quality over time.
+
+## Rationale
+Wave parallelism gives the correctness of sequential execution (dependency order
+respected) with the quality benefits of parallel isolation (each task gets a
+fresh 200K context). This is the optimal tradeoff.
+
+## Consequences
+- Plan authors must declare dependencies accurately — incorrect dependencies
+  can cause parallel tasks to conflict.
+- The dependency parser must catch cycles and conflicts before execution starts.
+- A small planning overhead (building the wave graph) is incurred per phase.

package/.planning/decisions/ADR-005-append-only-audit-log.md

@@ -0,0 +1,51 @@
+# ADR-005: Append-only JSONL audit log over structured database
+
+**Status:** Accepted
+**Date:** 2026-03-20
+**Deciders:** MindForge core team
+
+## Context
+MindForge needs an audit trail of agent actions. The storage format choices are:
+A) Append-only JSONL file (chosen)
+B) SQLite database
+C) In-memory log (written to JSON on session end)
+
+## Decision
+Append-only JSONL file: `.planning/AUDIT.jsonl`
+
+## Options considered
+
+### Option A — Append-only JSONL (chosen)
+Pros:
+- Zero dependencies (no SQLite driver needed)
+- Readable with standard Unix tools (grep, jq, tail)
+- Git-trackable — history of history
+- Tamper-evident via git (any deletion or modification is visible in `git diff`)
+- Works identically across all platforms and environments
+
+Cons:
+- No query language — filtering requires grep/jq
+- File grows unboundedly (mitigated by archiving strategy)
+- No transactions — a crash mid-write could produce a partial line
+
+### Option B — SQLite
+Pros: Full SQL query capability, transactional writes
+Cons: Binary file — not readable without tooling, not meaningfully git-diffable,
+      adds a native dependency, harder to inspect in CI/CD environments
+
+### Option C — In-memory log
+Pros: No I/O overhead during session
+Cons: Lost entirely if session crashes mid-execution — exactly when the audit log
+      is most needed.
+
+## Rationale
+For a framework targeting solo developers and small teams, readability and
+zero-dependency simplicity outweigh query sophistication. The primary audit use
+case is "what happened in this phase?" which grep handles well.
+
+## Consequences
+- A partial-line recovery tool should be built in a future hardening pass.
+  (Run `python3 -c "import sys,json;[print(l.strip()) for l in sys.stdin if json.loads(l)]"`
+  to filter clean lines from a corrupted AUDIT.jsonl)
+- An archiving strategy (rotate after 10,000 lines) will be added in Day 4.
+- The `status` command reads AUDIT.jsonl from the tail for performance.

package/.planning/decisions/ADR-006-tiered-skills-system.md

@@ -0,0 +1,22 @@
+# ADR-006: Three-tier skills architecture (Core → Org → Project)
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+Skills need to be distributed at three scopes: universal best practices,
+organisation-specific standards, and project-specific patterns.
+
+## Decision
+Three-tier architecture with explicit priority: Project (T3) > Org (T2) > Core (T1).
+
+## Rationale
+The tier system solves the key tension: MindForge provides sensible defaults
+(Core), organisations customise for their standards (Org), and projects fine-tune
+for their specific context (Project). Higher tiers override lower tiers by same name,
+enabling intentional, documented overrides without modifying shared core skills.
+
+## Consequences
+- Skill authors must understand which tier is appropriate for their skill
+- Conflict resolution rules must be well-documented (see conflict-resolver.md)
+- Org-tier skills should be maintained in a shared repo, not per-project

package/.planning/decisions/ADR-007-trigger-keyword-model.md

@@ -0,0 +1,22 @@
+# ADR-007: Keyword-trigger model over AI-decided skill selection
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+How should the agent decide which skills to load for a given task?
+Options: keyword triggers in frontmatter vs. AI-decided relevance.
+
+## Decision
+Keyword triggers in frontmatter (same model as Day 1 ADR-003, confirmed at Day 3 scale).
+
+## Additional rationale at Day 3 scale
+With 10+ skills, AI-decided selection has a higher risk of selecting wrong skills
+due to hallucinated relevance. Keyword triggers are deterministic — identical tasks
+always load identical skills, enabling reproducible results across sessions.
+The added specificity of file-name matching (not just text matching) improves
+trigger accuracy without sacrificing determinism.
+
+## Consequences
+Trigger keyword lists require ongoing maintenance as skill content evolves.
+The conflict resolver handles cases where multiple skills match.

package/.planning/decisions/ADR-008-just-in-time-skill-loading.md

@@ -0,0 +1,29 @@
+# ADR-008: Just-in-time skill loading over session-start loading
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+When should skills be loaded — at session start (front-loaded) or at task time (JIT)?
+
+## Decision
+Just-in-time loading: skills are loaded immediately before the task that needs them.
+Skills are not loaded at session start.
+
+## Rationale
+Front-loading all skills at session start would:
+- Consume 30K+ tokens for 10 skills before any work begins
+- Load skills irrelevant to the current task (e.g., loading incident-response
+  skills for a UI component task)
+- Pollute the agent's context with contradictory guidance from multiple domains
+
+JIT loading means:
+- Each task starts with only the relevant skills in context
+- Context budget is spent on relevant expertise, not irrelevant policies
+- Skills load at the moment they are most useful to the agent
+
+## Consequences
+- Skills must be re-loaded for each task (no session-level caching)
+- The trigger index is built once at session start (inexpensive: reads frontmatter only)
+- Skills that need to be available across multiple tasks should use the
+  minimal context injection (trigger + mandatory actions only) to save budget

package/.planning/decisions/ADR-009-enterprise-integration-retry-policy.md

@@ -0,0 +1,8 @@
+# ADR-009: Standardized retry/backoff policy for enterprise integrations
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Decision
+Use bounded exponential backoff with jitter for integration APIs and stop retrying
+on explicit authorization failures.

package/.planning/decisions/ADR-010-governance-tier-escalation.md

@@ -0,0 +1,8 @@
+# ADR-010: Governance tier escalation by path, content, and history
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Decision
+Classify changes using path signals, code-content risk signals, and recent audit
+history so risk is not underestimated by filename-only matching.

package/.planning/decisions/ADR-011-multi-developer-handoff-contract.md

@@ -0,0 +1,8 @@
+# ADR-011: Multi-developer handoff must remain append-only and conflict-aware
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Decision
+Use append-only handoff records with staleness checks and explicit ownership of
+files/plans to reduce merge-time coordination failures.

package/.planning/decisions/ADR-012-intelligence-feedback-loops.md

@@ -0,0 +1,19 @@
+# ADR-012: Intelligence outputs must feed back into behavior
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+Day 5 introduces difficulty scoring, retrospectives, compaction quality, and
+session metrics. Without explicit feedback connectors these become passive
+reports.
+
+## Decision
+Use explicit loops:
+- difficulty -> planning granularity
+- retrospective -> MINDFORGE updates
+- quality metrics -> session behavior adjustments
+- compaction -> richer handoff continuity
+
+## Consequences
+Every intelligence artifact must define its downstream behavioral effect.

package/.planning/decisions/ADR-013-mindforge-md-constitution.md

@@ -0,0 +1,16 @@
+# ADR-013: MINDFORGE.md is configurable but cannot disable governance primitives
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+Project-level customization is required, but unrestricted overrides would allow
+accidental or malicious disabling of core safety guarantees.
+
+## Decision
+Allow MINDFORGE overrides only for configurable preferences and thresholds.
+Keep secret detection, security auto-trigger, plan-first, and audit-writing
+as non-overridable primitives.
+
+## Consequences
+Customization remains flexible while governance stays enforceable.

package/.planning/decisions/ADR-014-metrics-as-signals-not-evaluation.md

@@ -0,0 +1,15 @@
+# ADR-014: Metrics are process signals, not developer performance metrics
+
+**Status:** Accepted
+**Date:** 2026-03-20
+
+## Context
+Session and phase quality metrics can be misused as individual performance
+scores, which undermines reliability and psychological safety.
+
+## Decision
+Use metrics solely for system/process improvement and personalization.
+Do not use them for individual performance evaluation.
+
+## Consequences
+Documentation and profile policy must explicitly prohibit evaluative use.

package/.planning/decisions/ADR-015-npm-based-skill-registry.md

@@ -0,0 +1,26 @@
+# ADR-015: npm as the MindForge Skills Registry
+
+**Status:** Accepted
+**Date:** 2026-03-21
+
+## Context
+MindForge needs a way to distribute community and organisation skills.
+Options: custom registry server, GitHub releases, npm registry.
+
+## Decision
+Use the standard npm registry with `mindforge-skill-` package naming convention.
+
+## Rationale
+npm is the world's largest package registry with existing infrastructure for:
+versioning, authentication, access control, search, and deprecation.
+Building a custom registry duplicates all of this at significant cost.
+The npm ecosystem's supply chain security tooling (npm audit, Dependabot,
+Snyk) works natively. Private registries (Verdaccio, Artifactory, GitHub Packages)
+are npm-compatible — organisations with private skills don't need separate tooling.
+
+## Consequences
+- Skill names follow npm conventions (lowercase, hyphens)
+- Version management follows npm semver conventions
+- Private skills require a compatible private npm registry
+- The injection guard and validation pipeline are the primary
+  supply chain security controls (npm audit is insufficient alone for SKILL.md content)

package/.planning/decisions/ADR-016-ci-exit-code-0-on-timeout.md

@@ -0,0 +1,27 @@
+# ADR-016: CI timeout exits with code 0 (soft stop)
+
+**Status:** Accepted
+**Date:** 2026-03-21
+
+## Context
+MindForge CI may run out of time before completing all phases.
+The question is: should timeout exit with code 0 (success) or non-zero (failure)?
+
+## Decision
+Timeout exits with code 0. State is saved. Next CI run resumes.
+
+## Rationale
+A MindForge CI timeout is not a code failure — it is a resource limit.
+Failing the build on timeout would:
+1. Block the PR with a failure that has no fix (the code is fine — time ran out)
+2. Force teams to either increase CI limits or split phases artificially
+3. Make MindForge feel unreliable ("it randomly fails when there's a lot to do")
+
+The correct behaviour: save progress, exit cleanly, let the next run continue.
+The CI pipeline is designed for continuation, not completion in a single run.
+
+## Consequences
+- CI pipelines may run multiple times for a single phase
+- HANDOFF.json must be committed during CI runs (CI has write access)
+- Teams must monitor CI for timeout patterns (frequent timeouts → split phases)
+- GitHub Actions step summary provides visibility into timeout state

package/.planning/decisions/ADR-017-sdk-localhost-only.md

@@ -0,0 +1,28 @@
+# ADR-017: MindForge SDK event stream is localhost-only
+
+**Status:** Accepted
+**Date:** 2026-03-21
+
+## Context
+The MindForge SDK includes an SSE event stream for real-time progress.
+The question is whether it should bind to all interfaces or localhost only.
+
+## Decision
+The event stream binds to 127.0.0.1 (localhost) only.
+
+## Rationale
+The event stream exposes:
+- AUDIT.jsonl entries (which contain sensitive project state)
+- Task completion events (which reveal code structure and timing)
+- Security finding events (which reveal vulnerability information)
+
+Exposing this to all network interfaces in a shared development environment
+(VMs, shared cloud desktops, containers) would allow other users to monitor
+another developer's project state in real-time.
+Localhost binding provides adequate protection for the primary use case
+(local developer tooling) without requiring authentication infrastructure.
+
+## Consequences
+- Remote integrations cannot use the event stream directly
+- For remote monitoring: use the audit log query API via SSH tunnel
+- Container environments: map the port explicitly if remote access is needed

package/.planning/decisions/ADR-018-installer-self-install-detection.md

@@ -0,0 +1,15 @@
+# ADR-018: Installer detects and handles self-install scenario
+
+**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
+
+## Context
+Running `npx mindforge-cc --claude --local` inside the MindForge repo itself
+would copy `.mindforge/` to `.mindforge/` (source = destination).
+
+## Decision
+Detect self-install by checking `package.json.name === 'mindforge-cc'`.
+If self-install: skip framework file copies. Only install commands.
+
+## Rationale
+Core team runs the installer locally for testing frequently.
+Silent no-op with a clear warning is better than a cryptic error or accidental self-overwrite.