mindforge-cc 11.3.0 → 11.4.0

package/.agent/forge/help.md

@@ -0,0 +1,11 @@
+---
+description: Show all available FORGE commands and what they do.
+---
+
+Show all available FORGE commands and what they do.
+
+List every .md file in .claude/commands/forge/ and display:
+- Command name (filename without extension)
+- First line of the file as its description
+
+Format as a clean table. Also remind the user to read CLAUDE.md if they haven't yet.

package/.agent/forge/init-project.md

@@ -0,0 +1,36 @@
+---
+description: Initialize a new project under the FORGE framework.
+---
+
+Initialize a new project under the FORGE framework.
+
+Follow these steps in order:
+
+1. Ask the user these questions one at a time (wait for each answer before asking the next):
+   - What is this project? (1-2 sentence description)
+   - Who is the target user?
+   - What is the core problem it solves?
+   - What tech stack do you want to use? (or "help me decide")
+   - What is absolutely NOT in scope for v1?
+   - What does success look like at the end of v1?
+
+2. If the user said "help me decide" on tech stack, ask 3 clarifying questions then recommend a stack with brief reasoning.
+
+3. Create `.planning/PROJECT.md` with:
+   - Project name and one-line description
+   - Problem statement
+   - Target user
+   - Tech stack (with brief rationale for each choice)
+   - v1 scope (what's in)
+   - Out of scope (what's explicitly not in v1)
+   - Success criteria
+
+4. Create `.planning/STATE.md` with:
+   - Status: Project initialized
+   - Current phase: None (not started)
+   - Last action: Project initialization
+   - Next step: Run /forge:plan-phase 1
+
+5. Create `.planning/REQUIREMENTS.md` (blank template with sections)
+
+6. Tell the user: "Project initialized. Run /forge:plan-phase 1 to begin planning your first phase."

package/.agent/forge/plan-phase.md

@@ -0,0 +1,34 @@
+---
+description: Plan a phase of the project. Usage: /forge:plan-phase [N]
+---
+
+Plan a phase of the project. Usage: /forge:plan-phase [N]
+
+If N is not provided, check STATE.md for the current phase and use that.
+
+Steps:
+1. Read PROJECT.md, REQUIREMENTS.md, and STATE.md.
+2. Ask the user: "Describe what phase [N] should accomplish in 2-3 sentences."
+3. Ask: "Are there any specific implementation decisions you've already made for this phase?"
+4. Spawn a research subagent: Read the project's tech stack from PROJECT.md and research the best patterns, libraries, and pitfalls for implementing this phase. Write findings to `.planning/phases/phase-[N]/RESEARCH.md`.
+5. Create 3-6 atomic task plans in `.planning/phases/phase-[N]/`. Each PLAN file must use this XML format:
+```xml
+<plan>
+  <task>Task name</task>
+  <files>
+    specific/file/paths/to/touch.ts
+  </files>
+  <instructions>
+    Precise implementation instructions. Include:
+    - Which library to use and why (mention specific version if relevant)
+    - Any gotchas or anti-patterns to avoid
+    - The exact approach, not just "implement X"
+  </instructions>
+  <verify>Specific command or check that confirms this task is done</verify>
+  <done>One sentence definition of done for this task</done>
+</plan>
+```
+
+6. Check each plan against REQUIREMENTS.md. If a plan implements something out of scope, revise it.
+7. Update STATE.md: current phase = N, status = "Phase [N] planned, ready to execute"
+8. Tell the user: "Phase [N] has [X] task plans ready. Run /forge:execute-phase [N] to begin execution."

package/.agent/mindforge/add-backlog.md

@@ -0,0 +1,32 @@
+---
+name: mindforge:add-backlog
+description: Capture ideas in a "parking lot" to keep them out of the active phase sequence
+argument-hint: <description>
+allowed-tools:
+  - view_file
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+---
+
+<objective>
+Capture an idea, task, or feature request in a "parking lot" section of the ROADMAP.md to prevent it from cluttering the active development phases.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/add-backlog.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The description of the backlog item)
+Target File: ROADMAP.md
+State: Uses 999.x numbering scheme for backlog items.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Locate the `## Backlog` or `## Future Milestones` section.
+2. **Initialize if missing**: If no backlog section exists, create `## Backlog` at the end of the file.
+3. **Determine numbering**: Find the last `999.x` item. If none, start with `999.1`.
+4. **Append item**: Add the new backlog item with the determined number and the provided description.
+5. **Confirm**: Notify the user that the item has been parked in the backlog.
+</process>

package/.agent/mindforge/agent-deploy.md

@@ -0,0 +1,34 @@
+---
+name: mindforge:agent-deploy
+description: "Deploy and monitor AI agents in production. Usage: /mindforge:agent-deploy [agent] [--strategy canary|shadow|blue-green] [--monitor]"
+argument-hint: "[agent] [--strategy canary|shadow|blue-green] [--monitor]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Deploy AI agents to production with version pinning, progressive rollout strategies, and comprehensive monitoring that captures both operational metrics and output quality signals.
+</objective>
+
+<execution_context>
+@.mindforge/skills/ai-agent-deployment/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/ai-agent-deployment/`
+State: Manages agent lifecycle from staging validation through progressive production rollout with quality-aware monitoring.
+</context>
+
+<process>
+1. **Pin Agent Version**: Lock the complete agent configuration — model version, system prompt hash, tool definitions, and parameter settings. Create an immutable deployment artifact with a unique version identifier.
+2. **Select Deployment Strategy**: Choose between canary (gradual traffic shift), shadow (parallel execution without serving), or blue-green (instant cutover with rollback). Base decision on risk tolerance and observability maturity.
+3. **Deploy to Staging**: Push the pinned agent version to a staging environment that mirrors production data patterns. Run automated acceptance tests covering core use cases and edge cases.
+4. **Run Shadow Test**: Execute the new agent version in parallel with the current production agent on real traffic. Compare outputs without serving new agent responses. Measure quality delta and identify regressions.
+5. **Canary to 5% Traffic**: Route a small percentage of production traffic to the new agent version. Monitor error rates, latency, token consumption, and output quality metrics during the canary window.
+6. **Monitor Production Signals**: Track operational metrics (latency p50/p95/p99, token usage, error rate, timeout rate) and quality metrics (user satisfaction, task completion, hallucination rate, tool call success rate).
+7. **Promote or Rollback**: Define automated promotion criteria (error rate < threshold, quality score >= baseline). If criteria are not met within the canary window, automatically rollback to the previous version.
+8. **Configure Health Probes**: Set up liveness and readiness probes that verify the agent can successfully complete a representative task. Include model availability checks and tool connectivity verification.
+9. **Set Up Alerting**: Configure alerts for anomalous behavior — latency spikes, token budget overruns, error rate increases, quality score drops. Route alerts based on severity to appropriate on-call channels.
+10. **Document Rollback Procedure**: Produce a runbook covering manual rollback steps, traffic drain procedure, and post-incident analysis checklist for agent deployment failures.
+</process>

package/.agent/mindforge/agent-design.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:agent-design
+description: "Design autonomous agent architecture. Usage: /mindforge:agent-design [agent] [--loop react|plan-execute|reflexion] [--tools number]"
+argument-hint: "[agent] [--loop react|plan-execute|reflexion] [--tools number]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive agent-design system architecture.
+</objective>
+
+<execution_context>
+@.mindforge/skills/autonomous-agents/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/autonomous-agents/`
+State: Analyzes requirements and constraints to generate agent-design architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements and constraints.
+2. **Architecture Design**: Design scalable system architecture with best practices.
+3. **Component Selection**: Select appropriate technologies and tools for implementation.
+4. **Integration Strategy**: Define integration patterns with existing systems.
+5. **Optimization Approach**: Implement performance and cost optimization strategies.
+6. **Monitoring Framework**: Design observability and alerting mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures.
+</process>

package/.agent/mindforge/agent-eval.md

@@ -0,0 +1,27 @@
+---
+description: "Benchmark agent performance end-to-end. Usage: /mindforge:agent-eval [agent] [--tasks N] [--compare baseline] [--metrics quality|cost|speed]"
+---
+
+<objective>
+Systematically benchmark an agent's end-to-end performance using stratified task datasets, statistical rigor with confidence intervals, and multi-dimensional metrics covering quality, cost, and speed to drive data-informed optimization decisions.
+</objective>
+
+<execution_context>
+@.mindforge/skills/agent-evaluation-framework/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (agent name or config, optional --tasks count, optional --compare baseline, optional --metrics focus)
+Knowledge: Agent configuration, available task datasets, baseline performance numbers, cost per invocation.
+</context>
+
+<process>
+1. **Define Evaluation Metrics**: Establish the metrics framework: task completion rate (binary success), output quality score (1-5 rubric), cost per task (tokens in + out), time to completion (wall clock), and error rate (crashes, timeouts, hallucinations).
+2. **Build Task Dataset**: Create a stratified dataset with tasks across difficulty levels (easy/medium/hard), task types (research, code, analysis, creative), and edge cases. Minimum 30 tasks per stratum for statistical significance.
+3. **Run Agent N Times Per Task**: Execute each task multiple times (minimum 3, ideally 5) to measure variance. Use different random seeds if applicable. Record all outputs and intermediate steps for analysis.
+4. **Compute Metrics With Confidence Intervals**: Calculate mean and 95% confidence interval for each metric. Report variance — high variance on the same task indicates reliability issues. Use bootstrap resampling if sample size is small.
+5. **Compare To Baseline**: If a baseline exists, compute the delta for each metric with statistical significance testing (paired t-test or Wilcoxon signed-rank). Report effect size (Cohen's d) alongside p-value. Visualize improvements and regressions.
+6. **Identify Regression And Improvement Patterns**: Analyze which task types improved and which regressed. Cluster failures by error type. Identify if improvements in one area came at the cost of another (quality-cost tradeoff).
+7. **Generate Benchmark Report**: Produce a structured report: executive summary (1 paragraph), metrics table with CIs, task-level breakdown, failure analysis, comparison to baseline, and trend over time (if historical data exists).
+8. **Recommend Optimizations**: Based on the evaluation data, recommend specific optimizations: prompt changes for quality issues, caching for cost issues, parallelization for speed issues, or guardrails for reliability issues. Prioritize by impact-to-effort ratio.
+</process>

package/.agent/mindforge/agent-memory.md

@@ -0,0 +1,27 @@
+---
+description: "Design agent memory architecture across time scales. Usage: /mindforge:agent-memory [agent] [--layers 4] [--retrieval semantic|key|hybrid]"
+---
+
+<objective>
+Design a multi-layered agent memory architecture that operates across different time scales, balancing recall accuracy with storage efficiency through consolidation, decay, and retrieval optimization strategies.
+</objective>
+
+<execution_context>
+@.mindforge/skills/agent-memory-design/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (agent name or system, optional --layers count, optional --retrieval strategy)
+Knowledge: Agent's task domain, interaction patterns, storage constraints, latency requirements.
+</context>
+
+<process>
+1. **Classify Information By Time-Scale**: Categorize all information the agent handles into layers: working memory (current turn, seconds), short-term (current session, minutes-hours), medium-term (recent sessions, days-weeks), long-term (permanent knowledge, months-years).
+2. **Design Storage Per Layer**: Working memory = in-context window. Short-term = structured scratchpad (JSON/key-value). Medium-term = vector store with temporal weighting. Long-term = knowledge graph + compressed summaries. Choose storage technology for each.
+3. **Implement Retrieval Strategy Per Layer**: Working memory = direct access. Short-term = key-based lookup. Medium-term = semantic search with recency boost. Long-term = hybrid (semantic + keyword + graph traversal). Define retrieval latency budgets per layer.
+4. **Add Consolidation Process**: At session end, extract key learnings from short-term memory, index them with semantic embeddings, link to existing knowledge graph nodes, and promote to medium-term. Weekly: consolidate medium-term patterns into long-term compressed representations.
+5. **Configure Decay Mechanism**: Unreinforced memories fade over time. Implement decay function: access count increases retention, time since last access decreases it. Set thresholds: below threshold = archive (not delete). Reinforced memories (accessed 3+ times) get permanence boost.
+6. **Set Memory Budget Per Layer**: Define token/storage budgets: working memory = context window limit minus system prompt. Short-term = 10K tokens max. Medium-term = 100K entries. Long-term = unlimited but retrieval-limited. Implement eviction when budget exceeded.
+7. **Test Recall Accuracy**: Design evaluation suite: inject known facts, query after N turns/sessions, measure recall@k. Target: working memory 100%, short-term 95%, medium-term 80%, long-term 70%. Identify failure modes.
+8. **Monitor Retrieval Relevance**: Track retrieval quality metrics: precision@5, user corrections (retrieved wrong context), latency percentiles. Set up alerting for degradation. A/B test retrieval strategy changes.
+</process>

package/.agent/mindforge/agent.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:agent
+description: Spawn or invoke a specialized enterprise persona from the MindForge library
+argument-hint: "[persona-name] [prompt]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provide an on-demand mechanism to "spawn" any of the 13+ standardized MindForge personas. This allows the user to switch the AI assistant's context, role, and process to a specific specialized mode (e.g., Roadmapper, Security Reviewer, Analyst).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/agent.md
+</execution_context>
+
+<context>
+Personas Directory: `.mindforge/personas/`
+State: Loads the persona's XML-tagged structure into the active system context.
+</context>
+
+<process>
+1. **List Personas**: If no arguments are provided, list all available `.md` files in `.mindforge/personas/` with their name and description (parsed from YAML).
+2. **Load Persona**: If a name is provided:
+    - Locate `.mindforge/personas/[name].md`.
+    - Read the file content.
+    - Present the persona's role and success criteria to the user.
+3. **Switch Mode**: Instruct the AI (through the current session context) to adopt the role, philosophy, and process defined in the loaded file.
+4. **Initial Task**: If a prompt is provided as the second argument, immediately execute that prompt using the newly adopted persona.
+</process>

package/.agent/mindforge/ai-cost.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:ai-cost
+description: "Optimize AI/ML infrastructure costs. Usage: /mindforge:ai-cost [system] [--budget monthly] [--optimize latency|cost|quality]"
+argument-hint: "[system] [--budget monthly] [--optimize latency|cost|quality]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive ai-cost system architecture.
+</objective>
+
+<execution_context>
+@.mindforge/skills/ai-cost-management/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/ai-cost-management/`
+State: Analyzes requirements and constraints to generate ai-cost architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements and constraints.
+2. **Architecture Design**: Design scalable system architecture with best practices.
+3. **Component Selection**: Select appropriate technologies and tools for implementation.
+4. **Integration Strategy**: Define integration patterns with existing systems.
+5. **Optimization Approach**: Implement performance and cost optimization strategies.
+6. **Monitoring Framework**: Design observability and alerting mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures.
+</process>

package/.agent/mindforge/ai-safety.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:ai-safety
+description: "Design AI safety and alignment controls. Usage: /mindforge:ai-safety [system] [--scope output|input|pipeline] [--level basic|comprehensive]"
+argument-hint: "[system] [--scope output|input|pipeline] [--level basic|comprehensive]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive AI safety and alignment controls for production AI systems, implementing guardrails, monitoring, and intervention mechanisms across input validation, output filtering, and pipeline orchestration. This command creates safety architecture that prevents harmful outputs, detects adversarial inputs, and ensures alignment with ethical guidelines and business policies.
+</objective>
+
+<execution_context>
+@.mindforge/skills/ai-safety-alignment/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/ai-safety-alignment/`
+State: Analyzes the AI system's risk surface, regulatory requirements, and business constraints to generate layered safety controls with monitoring dashboards and incident response protocols.
+</context>
+
+<process>
+1. **Risk Surface Mapping**: Identify potential failure modes (harmful content, PII leakage, hallucinations, adversarial manipulation), categorize risks by severity and likelihood, and define acceptable risk thresholds per use case.
+
+2. **Input Validation Layer**: Design prompt injection detection using classifier models and pattern matching, implement adversarial input filtering with anomaly detection, and create user intent verification for high-risk operations.
+
+3. **Output Safety Controls**: Architect content moderation pipeline with toxicity classifiers (Perspective API, OpenAI Moderation), implement fact-checking and hallucination detection for critical domains, and design PII redaction with entity recognition and regex patterns.
+
+4. **Alignment Mechanisms**: Define constitutional AI principles and values hierarchy, implement preference learning from human feedback (RLHF/RLAIF), and design reward modeling for behavior shaping toward safe outcomes.
+
+5. **Monitoring and Observability**: Create real-time dashboards tracking safety metric distributions (toxicity scores, rejection rates), implement anomaly alerting for policy violations, and design audit logging for compliance and forensics.
+
+6. **Intervention Protocols**: Design human-in-the-loop workflows for uncertain cases, implement circuit breakers with automatic system degradation, and create escalation paths for critical safety incidents.
+
+7. **Continuous Improvement**: Establish red-teaming protocols for adversarial testing, design A/B testing framework for safety mechanism refinement, and implement feedback loops from user reports and moderator reviews.
+</process>

package/.agent/mindforge/analytics.md

@@ -0,0 +1,28 @@
+---
+description: "Design event tracking taxonomy and instrumentation plan. Usage: /mindforge:analytics [feature] [--format object_action] [--privacy strict]"
+---
+
+<objective>
+Design a comprehensive event tracking taxonomy and instrumentation plan that enables data-driven product decisions while respecting user privacy and maintaining long-term data quality through governance processes.
+</objective>
+
+<execution_context>
+@.mindforge/skills/analytics-instrumentation/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (feature or product area, optional --format for naming convention, optional --privacy level)
+Knowledge: Existing tracking plan, privacy policy, consent framework, analytics platform documentation.
+</context>
+
+<process>
+1. **Define User Journeys To Measure**: Map the critical user journeys for the feature. Identify key decision points, drop-off risks, and success moments. Each journey becomes a funnel to instrument.
+2. **Design Event Taxonomy**: Create a consistent naming convention using object_action format (e.g., button_clicked, form_submitted, page_viewed). Define hierarchy: namespace > object > action. Ensure names are self-documenting and greppable.
+3. **Create Tracking Plan Spreadsheet**: Document every event in a structured format: event name, trigger condition, properties, expected volume, owner, and data consumer. This becomes the single source of truth.
+4. **Define Event Properties Per Event**: For each event, specify required and optional properties with their types, allowed values, and descriptions. Include: user context, session context, feature context, and business context.
+5. **Implement Data Layer**: Design the client-side data layer that decouples tracking from UI code. Use a centralized analytics service/module that validates events against the schema before sending.
+6. **Configure Consent and Privacy**: Implement consent-based tracking (essential/functional/analytics/marketing tiers). Ensure PII is never sent without explicit consent. Apply data minimization — only collect what is needed for defined use cases.
+7. **Validate Events In CI**: Add automated tests that verify: event names match the taxonomy, required properties are present, property types are correct, and no PII leaks into analytics events.
+8. **Set Up Funnel Dashboards**: For each instrumented journey, create a dashboard showing: conversion rates per step, drop-off analysis, segmentation by key dimensions, and trend over time.
+9. **Schedule Quarterly Cleanup**: Establish a governance process: review event volume quarterly, archive low-value events, update the tracking plan, and prune unused properties to prevent data bloat.
+</process>

package/.agent/mindforge/approve.md

@@ -0,0 +1,22 @@
+---
+description: Process pending approvals and emergency overrides. Usage:
+---
+
+Process pending approvals and emergency overrides. Usage:
+`/mindforge:approve [approval-id] [--approve|--reject] [--reason "..."] [--emergency]`
+
+## Listing approvals
+Scan `.planning/approvals/` and show only files with `status: pending` unless
+ the user explicitly asks for historical records.
+
+## Standard approval flow
+1. Read the approval file
+2. Confirm current identity from `git config user.email` or `$USER`
+3. Validate approver eligibility from `INTEGRATIONS-CONFIG.md`
+4. Record approval or rejection with timestamp and reason
+
+## Emergency overrides
+Emergency override requires the `--emergency` flag.
+Read `EMERGENCY_APPROVERS` from `INTEGRATIONS-CONFIG.md` and deny the request if
+ the current identity is not listed. Document that git-config-based identity is
+ a convenience layer, not a high-assurance identity proof.

package/.agent/mindforge/audit.md

@@ -0,0 +1,34 @@
+---
+description: Query .planning/AUDIT.jsonl by phase, event, date, severity, integration, or
+---
+
+Query `.planning/AUDIT.jsonl` by phase, event, date, severity, integration, or
+ agent. Usage: `/mindforge:audit [filters]`
+
+## Supported options
+- `--phase N`
+- `--event NAME`
+- `--agent NAME`
+- `--severity LEVEL`
+- `--date YYYY-MM-DD`
+- `--summary`
+- `--verify`
+- `--export PATH`
+
+## Summary mode
+Summarise counts by event, severity, integration, and phase.
+Entries with `"phase": null` are reported as `project-level`, not dropped.
+
+## Verify mode
+Validate JSONL shape and chronological ordering.
+Timestamp comparison may use string comparison because ISO-8601 UTC timestamps
+ with a `Z` suffix sort lexicographically.
+
+## Archive rotation
+If the active audit log exceeds 10,000 lines, rotate it into
+ `.planning/audit-archive/` before continuing heavy writes. Rotation must never
+ delete history; it archives then resets the active file.
+
+## Export safety
+Validate export paths stay inside the project directory. If a path traversal or
+ unsafe destination is requested, export into `.planning/` instead.

package/.agent/mindforge/auth-flow.md

@@ -0,0 +1,76 @@
+---
+description: "Design authentication and authorization flow. Usage: /mindforge:auth-flow [--type oauth2|session|jwt] [--mfa] [--authz rbac|abac]"
+---
+
+<objective>
+Design a complete authentication and authorization flow including authn mechanism selection, token lifecycle, MFA integration, and authz model implementation with security audit considerations.
+</objective>
+
+<execution_context>
+@.mindforge/skills/auth-patterns/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional --type oauth2|session|jwt, optional --mfa flag, optional --authz rbac|abac)
+Knowledge: Current auth implementation, user types, permission requirements, compliance needs (SOC2, GDPR).
+</context>
+
+<process>
+1. **Identify auth requirements**: Assess the system needs:
+   - User types: end-users, service accounts, admin, API consumers
+   - Client types: SPA, mobile app, server-to-server, CLI
+   - Session requirements: duration, concurrent sessions, device tracking
+   - Compliance: SOC2 (audit logs), GDPR (consent, deletion), HIPAA (access controls)
+   - Performance: auth check latency budget (< 5ms for hot path)
+   - Scale: concurrent users, tokens in circulation, auth checks per second
+
+2. **Select authn flow**: Based on --type flag or client analysis:
+   - **OAuth2 + PKCE** (for SPAs/mobile): Authorization Code flow with PKCE, no client secret exposed
+   - **Session-based** (for server-rendered): HTTP-only secure cookies, server-side session store
+   - **JWT** (for APIs/microservices): Signed tokens with short expiry, refresh token rotation
+   - For each: document the full flow (request → redirect → callback → token → validation)
+   - Specify token storage location (httpOnly cookie, secure storage, never localStorage)
+   - Define logout mechanism (token revocation, session invalidation, cookie clearing)
+
+3. **Design token lifecycle**: Define the token management:
+   - Access token: short-lived (15 min), contains minimal claims (sub, scope, exp)
+   - Refresh token: longer-lived (7 days), rotated on each use (detect theft via reuse)
+   - ID token: user profile claims, validated once at login
+   - Token revocation: maintain revocation list or use short expiry + refresh
+   - Token validation: signature check → expiry check → issuer check → audience check
+   - Clock skew tolerance: 30 seconds maximum
+
+4. **Add MFA if needed**: When --mfa flag is set:
+   - Primary factors: password (argon2id hash), social login (OAuth2)
+   - Second factors: TOTP (authenticator app), WebAuthn (hardware key), SMS (fallback only)
+   - Step-up auth: require MFA for sensitive operations (password change, payment, admin)
+   - Recovery: backup codes (10 single-use), admin override with audit log
+   - Enrollment flow: optional at signup, required for admin/elevated roles
+   - Remember device: trust for 30 days with device fingerprint
+
+5. **Design authz model**: Based on --authz flag:
+   - **RBAC** (Role-Based): Define roles (admin, editor, viewer) → map to permissions → assign to users
+   - **ABAC** (Attribute-Based): Define policies based on subject attributes, resource attributes, action, and context
+   - Permission granularity: resource-level (can edit ANY post) vs instance-level (can edit OWN posts)
+   - Inheritance: role hierarchy (admin inherits editor permissions)
+   - Deny-by-default: all access denied unless explicitly granted
+   - Policy evaluation: eager (at login, cache in token) vs lazy (at access time, check service)
+   - Group-based: assign roles to groups, users inherit from groups
+
+6. **Implement**: Translate design to code:
+   - Auth middleware: validate token on every request, attach user context
+   - Permission check: decorator/middleware pattern at route or controller level
+   - Service-to-service: mutual TLS or signed JWT with service identity
+   - Rate limiting: per-user and per-IP on auth endpoints (prevent brute force)
+   - Audit logging: log every auth event (login, logout, failure, permission denied, MFA challenge)
+   - Error responses: generic messages (never reveal "user not found" vs "wrong password")
+
+7. **Audit**: Validate the auth implementation:
+   - OWASP Authentication Cheat Sheet compliance
+   - Session fixation protection (regenerate session ID on login)
+   - CSRF protection on state-changing endpoints (SameSite cookies + CSRF token)
+   - Credential stuffing protection (rate limiting, CAPTCHA after N failures)
+   - Token leakage vectors (URL parameters, referrer headers, logs)
+   - Privilege escalation paths (horizontal: access other user data, vertical: gain admin)
+   - Output: security assessment report with findings and remediation
+</process>

package/.agent/mindforge/auto.md

@@ -0,0 +1,26 @@
+---
+description: Starts the MindForge Autonomous Execution Engine for the
+---
+
+# /mindforge:auto [Phase N]
+
+**Purpose**: Starts the MindForge Autonomous Execution Engine for the
+specified phase. The agent will execute all waves, handle repairs, and
+perform compliance gates without requiring human confirmation.
+
+## Usage
+- `/mindforge:auto --phase 3` (Standard unattended mode)
+- `/mindforge:auto --resume` (Resumes from last checkpoint)
+- `/mindforge:auto --headless` (CI/CD optimized output)
+- `/mindforge:auto --dry-run` (Show the wave DAG and plan without executing)
+
+## Behavior
+- **Zero-Interaction**: Auto-approves Tier 1/2 changes if gates pass.
+- **Self-Repair**: Tries RETRY/DECOMPOSE before asking for help.
+- **Checkpointing**: Constant state persistence in `HANDOFF.json`.
+- **Governance**: ESCALATES on Tier 3 changes (Auth/Payment/PII).
+
+## Environment Variables
+- `AUTO_MODE_TIMEOUT_MINUTES`: Default 120.
+- `AUTO_PUSH_ON_WAVE_COMPLETE`: Default false.
+- `SLACK_WEBHOOK_URL`: Required for notifications.

package/.agent/mindforge/benchmark.md

@@ -0,0 +1,37 @@
+---
+description: Measure skill effectiveness over time.
+---
+
+# MindForge — Benchmark Command
+# Usage: /mindforge:benchmark [--skill skill-name] [--compare skill-a skill-b]
+
+Measure skill effectiveness over time.
+
+## Single skill benchmark
+For a named skill, analyse AUDIT.jsonl and skill-usage.jsonl:
+- How many times was the skill loaded this month?
+- What is the verify pass rate for tasks where this skill was loaded?
+- Are there anti-patterns less common after this skill is loaded?
+- What is the average session quality score when this skill is active?
+
+Report:
+```
+Skill Benchmark: security-review v1.0.0
+────────────────────────────────────────
+Usage (last 30 days): 47 task loads
+Trigger distribution: text match 68%, file-path 22%, file-name 10%
+Verify pass rate:     91% (vs. 84% baseline without this skill)
+Security findings:    8 HIGH caught (0 CRITICAL missed in tasks using this skill)
+Session quality lift: +6.2 points average when loaded
+
+Assessment: HIGH VALUE — clear quality improvement signal
+```
+
+## Skill comparison
+Compare two skills head-to-head:
+- Load frequency
+- Verify pass rate improvement
+- Anti-pattern detection rate
+- Context budget cost (token estimate)
+
+Helps decide: should you keep both skills, or deprecate the lower-performer?