mindforge-cc 11.3.0 → 11.3.1

package/.agent/mindforge/multimodal.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:multimodal
+description: "Design multimodal AI system architecture. Usage: /mindforge:multimodal [system] [--modality vision|audio|text|multi] [--task generation|understanding|retrieval]"
+argument-hint: "[system] [--modality vision|audio|text|multi] [--task generation|understanding|retrieval]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design a comprehensive multimodal AI system that integrates multiple data modalities (vision, audio, text) for generation, understanding, or retrieval tasks. This command creates architecture blueprints for systems that process and synthesize information across different sensory inputs, ensuring efficient model selection, data alignment, and cross-modal reasoning capabilities.
+</objective>
+
+<execution_context>
+@.mindforge/skills/multimodal-ai/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/multimodal-ai/`
+State: Evaluates the target system's modality requirements, task characteristics, and performance constraints to generate a multimodal architecture with model recommendations, data pipeline design, and alignment strategies.
+</context>
+
+<process>
+1. **Modality Analysis**: Identify required input/output modalities (vision, audio, text, video) and their interaction patterns, analyzing data characteristics, resolution requirements, and temporal dependencies for each modality.
+
+2. **Model Selection Strategy**: Recommend foundation models (CLIP, Flamingo, GPT-4V, Gemini, LLaVA) based on task requirements, evaluate trade-offs between unified models vs specialized model ensembles, and specify fine-tuning approaches for domain adaptation.
+
+3. **Cross-Modal Alignment Architecture**: Design alignment mechanisms (contrastive learning, cross-attention, adapter layers) to map different modalities into shared representation spaces, ensuring semantic consistency and efficient cross-modal retrieval.
+
+4. **Data Pipeline Design**: Architect preprocessing pipelines for each modality including normalization, augmentation, and synchronization strategies, define batch composition strategies for mixed-modality training, and implement quality validation checkpoints.
+
+5. **Inference Optimization**: Design inference architecture with model serving patterns (sequential, parallel, cascade), implement caching strategies for embeddings and intermediate representations, and specify hardware allocation (GPU/CPU split) per modality.
+
+6. **Evaluation Framework**: Define modality-specific metrics (CLIP score for vision-text, audio quality metrics, generation fidelity), design cross-modal evaluation protocols, and establish baseline benchmarks for the target task.
+
+7. **Integration and Scaling**: Specify API contracts for modality inputs/outputs, design horizontal scaling strategies for high-throughput scenarios, implement monitoring for per-modality performance degradation, and document failure modes and fallback strategies.
+</process>

package/.agent/mindforge/new-runtime.md

@@ -0,0 +1,23 @@
+---
+description: Scaffold support for a new AI coding runtime.
+---
+
+# /mindforge:new-runtime
+
+Scaffold support for a new AI coding runtime.
+
+## Usage
+
+/mindforge:new-runtime [name]
+
+## Action
+
+1.  Identify target runtime's entry file format (e.g. .myrules, instructions.md)
+2.  Scaffold the required directories in both global and local scopes
+3.  Add a new entry to the RUNTIMES configuration in `bin/installer-core.js`
+4.  Generate first-run instructions for the new runtime
+
+## Examples
+
+/mindforge:new-runtime void-editor
+/mindforge:new-runtime zed-ai

package/.agent/mindforge/next.md

@@ -0,0 +1,109 @@
+---
+description: Auto-detect the current project state and execute the appropriate next step.
+---
+
+# MindForge — Next Command
+# Usage: /mindforge:next
+
+Auto-detect the current project state and execute the appropriate next step.
+The user does not need to know the workflow. MindForge figures it out.
+
+## HANDOFF.json priority rule
+Check HANDOFF.json BEFORE running the decision tree.
+
+If HANDOFF.json exists AND `updated_at` is within 48 hours AND `next_task` is not null:
+present the HANDOFF state first. Only run the decision tree if the user declines
+or the HANDOFF.json is stale.
+
+## State detection logic
+
+Read STATE.md and HANDOFF.json. Then follow this decision tree:
+
+### Decision tree
+
+```
+Does .planning/PROJECT.md exist AND have content?
+  NO  → Run /mindforge:init-project
+  YES → Continue
+
+Does .planning/ROADMAP.md exist AND have phases defined?
+  NO  → Tell user: "Project is initialised but no phases are defined yet.
+         Describe what Phase 1 should accomplish and I'll plan it."
+         Then run /mindforge:plan-phase 1
+  YES → Continue
+
+Read the phase status from STATE.md.
+
+Does the current phase have plans? (check .planning/phases/[N]/PLAN-[N]-*.md)
+  NO  → Run /mindforge:plan-phase [N]
+  YES → Continue
+
+Do SUMMARY files exist for all plans in the current phase?
+  NO  → Run /mindforge:execute-phase [N]
+  YES → Continue
+
+Does VERIFICATION.md exist for the current phase?
+  NO  → Run /mindforge:verify-phase [N] (automated part)
+  YES → Continue
+
+Does UAT.md exist and show all tests passing?
+  NO  → Run /mindforge:verify-phase [N] (UAT part)
+  YES → Continue
+
+Is this phase marked as shipped in STATE.md?
+  NO  → Run /mindforge:ship [N]
+  YES → Continue
+
+Are there more phases in ROADMAP.md?
+  YES → Increment phase number. Run /mindforge:plan-phase [N+1]
+  NO  → Tell user: "All phases complete! Run /mindforge:ship [N] for the final release."
+```
+
+## Partial phase execution handling
+In the decision tree step "Do SUMMARY files exist for all plans?":
+
+Do not treat this as binary. Check individually:
+
+```
+PLAN-[N]-01.md exists?          SUMMARY-[N]-01.md exists?
+PLAN-[N]-02.md exists?          SUMMARY-[N]-02.md exists?
+PLAN-[N]-03.md exists?          SUMMARY-[N]-03.md exists?
+```
+
+If some SUMMARY files exist and some don't: this is a partially-executed phase.
+Report: "Phase [N] is partially executed: plans [X, Y] are done, [Z] is not."
+Ask: "Resume execution from Plan [Z]? (yes/no)"
+Do not restart the entire phase — resume from the first missing SUMMARY.
+
+## Before auto-executing: always confirm
+Before running any command automatically, tell the user:
+
+```
+MindForge next step detected:
+  Current state : [description of current state]
+  Next action   : [what will be run]
+  Command       : /mindforge:[command] [args]
+
+Run this now? (yes/no/different)
+```
+
+If user says "different": ask what they want to do instead.
+If user says "yes": proceed with the detected command.
+
+## Handling HANDOFF.json (session restart)
+If HANDOFF.json has a `next_task` field from a previous session:
+Present it prominently:
+
+```
+Previous session found:
+  Saved at  : [updated_at from HANDOFF.json]
+  Left off  : [last_completed_task]
+  Next task : [next_task]
+
+Options:
+  1. Continue from where we left off
+  2. Check current state and determine next step fresh
+  3. Tell me what you want to do
+
+Choose 1, 2, or 3:
+```

package/.agent/mindforge/note.md

@@ -0,0 +1,35 @@
+---
+name: mindforge:note
+description: Capture an idea, task, or issue that surfaces during a session as a quick note for later
+argument-hint: <text> [list|promote N]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - multi_replace_file_content
+---
+
+<objective>
+Provide a zero-friction way to capture ephemeral thoughts, bugs, or todos during an active session without interrupting the current flow, with the ability to later promote them to official tasks.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/note.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The note text or subcommand like `list` or `promote`)
+Storage: .planning/notes/
+Target for Promotion: ROADMAP.md or STATE.md
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - If `list`: Read all files in `.planning/notes/` and present them.
+    - If `promote <N>`: Read note N, add it to current phase/milestone in STATE.md or ROADMAP.md, then move the note to `.planning/notes/archived/`.
+    - Else (default): Capture the text.
+2. **Capture Flow**:
+    - Ensure `.planning/notes/` directory.
+    - Create a file `note_[timestamp].md` with the content.
+3. **Confirm**: Quick confirmation of capture or promotion result.
+</process>

package/.agent/mindforge/observability-platform.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:observability-platform
+description: "Design unified observability platform. Usage: /mindforge:observability-platform [scope] [--stack otel|datadog|grafana] [--scale services]"
+argument-hint: "[scope] [--stack otel|datadog|grafana] [--scale services]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive observability-platform system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/platform-observability/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/platform-observability/`
+State: Analyzes requirements, constraints, and scale to generate optimized observability-platform architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements, performance constraints, and scalability needs.
+2. **Architecture Design**: Design system architecture with component interaction patterns and data flow.
+3. **Technology Selection**: Evaluate and select appropriate technologies, tools, and frameworks.
+4. **Integration Strategy**: Define integration patterns with existing systems and external dependencies.
+5. **Optimization Approach**: Implement performance, cost, and resource optimization strategies.
+6. **Monitoring Framework**: Design observability, alerting, and debugging mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures and disaster recovery.
+</process>

package/.agent/mindforge/observability.md

@@ -0,0 +1,75 @@
+---
+description: "Set up logging, tracing, and metrics stack. Usage: /mindforge:observability [service] [--stack otel|custom] [--alerts]"
+---
+
+<objective>
+Design and implement a comprehensive observability stack covering structured logging, distributed tracing, and metrics collection with alert definitions for a service or system.
+</objective>
+
+<execution_context>
+@.mindforge/skills/observability-stack/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (service name, optional --stack otel|custom, optional --alerts flag)
+Knowledge: Current infrastructure, existing monitoring, SLO definitions, incident history.
+</context>
+
+<process>
+1. **Identify golden signals**: For the target service, define:
+   - Latency: request duration distribution (p50, p95, p99)
+   - Traffic: requests per second, broken down by endpoint and method
+   - Errors: error rate by type (4xx client, 5xx server, timeout, circuit-open)
+   - Saturation: resource utilization (CPU, memory, connections, queue depth)
+   - Map each signal to concrete measurement points in the code
+   - Identify which signals are leading indicators vs lagging
+
+2. **Implement structured logging**: Design the logging layer:
+   - Format: JSON with consistent field names across all services
+   - Required fields: timestamp, level, service, trace_id, span_id, message
+   - Context fields: user_id, request_id, correlation_id, environment
+   - Log levels: ERROR (actionable), WARN (degraded), INFO (state changes), DEBUG (development)
+   - Correlation: inject trace_id and span_id into every log line
+   - Sampling: log 100% of errors, sample INFO/DEBUG in production
+   - Redaction: automatically mask PII fields (email, IP, tokens)
+
+3. **Add tracing (OpenTelemetry spans)**: Instrument the request lifecycle:
+   - Root span at service entry (HTTP handler or message consumer)
+   - Child spans for: database queries, external API calls, cache operations, queue publish
+   - Span attributes: operation name, status code, error message, duration
+   - Propagation: W3C TraceContext headers for cross-service correlation
+   - Sampling strategy: always-on for errors, probabilistic (10%) for success
+   - Exporter configuration: OTLP to collector, batch with 5s flush interval
+
+4. **Define metrics (RED for services, USE for resources)**:
+   - RED (Request-focused): Rate, Errors, Duration per endpoint
+   - USE (Resource-focused): Utilization, Saturation, Errors per resource
+   - Histogram buckets for latency: [5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 5s]
+   - Counter for requests by: method, path, status_code
+   - Gauge for: active connections, queue depth, cache size
+   - Summary for: batch job duration, background task completion time
+
+5. **Design alerts (symptom-based)**: When --alerts flag is set:
+   - SLO-based: alert on error budget burn rate (fast burn = 14.4x in 1h, slow burn = 6x in 6h)
+   - Latency: p99 > 2x target for 5 minutes
+   - Error rate: > 1% for 5 minutes (page), > 0.1% for 30 minutes (ticket)
+   - Saturation: resource > 80% for 10 minutes (warn), > 95% for 5 minutes (page)
+   - Absence: no data for 5 minutes (service may be down)
+   - Alert routing: PagerDuty for page-severity, Slack for warn-severity
+   - Runbook link in every alert annotation
+
+6. **Build dashboard**: Design the observability dashboard hierarchy:
+   - L0 (Overview): Service health grid, error budget remaining, top-level SLIs
+   - L1 (Service): Golden signals for the specific service, recent deployments overlay
+   - L2 (Request): Individual request trace waterfall, span breakdown
+   - L3 (Resource): CPU, memory, disk, network for underlying infrastructure
+   - Include: deployment markers, anomaly detection overlay, comparison (now vs last week)
+
+7. **Output observability plan**: Deliver:
+   - Architecture diagram (collector topology, data flow)
+   - Instrumentation code snippets for the target stack
+   - Alert definitions (Prometheus rules or equivalent)
+   - Dashboard JSON (Grafana or equivalent)
+   - Retention policy (hot: 7d full resolution, warm: 30d downsampled, cold: 90d aggregated)
+   - Cost estimate for the observability stack
+</process>

package/.agent/mindforge/offline.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:offline
+description: "Design offline-first data architecture. Usage: /mindforge:offline [feature] [--sync crdt|ot|custom] [--conflict lww|merge|manual]"
+argument-hint: "[feature] [--sync crdt|ot|custom] [--conflict lww|merge|manual]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design offline-first architectures with local-first data storage, optimistic UI updates, sync conflict resolution, and graceful degradation during network outages.
+</objective>
+
+<execution_context>
+@.mindforge/skills/offline-first-design/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/offline-first-design/`
+State: Designs local database schema, sync protocols (CRDT/OT), conflict resolution strategies, and queue management for offline operations.
+</context>
+
+<process>
+1. **Local Storage**: SQLite (structured relational data). IndexedDB (web, large datasets). Realm (mobile, reactive queries). WatermelonDB (React Native, observable). Choose based on platform and query patterns.
+
+2. **Sync Strategy**: CRDT (Conflict-free Replicated Data Types) → automatic merge, no conflicts, eventual consistency (Yjs, Automerge). OT (Operational Transformation) → transforms operations, preserves intent (Google Docs style). Custom → simpler logic but requires explicit conflict handling.
+
+3. **Conflict Resolution**: Last-Write-Wins → simple, risk of data loss, acceptable for low-conflict scenarios. Field-level merge → granular, preserves more data, requires schema design. Manual resolution → show UI for user decision, use for critical data. Version vectors track causality.
+
+4. **Optimistic UI**: Apply changes immediately to local state. Show pending indicator. Queue sync operation. Rollback on server rejection. Show conflicts in UI. Maintain operation log for debugging.
+
+5. **Queue Management**: Persist operations to disk (survive app restart). Retry with exponential backoff. Handle partial failures (some operations succeed, others fail). Order dependencies (create before update). Prune completed operations.
+
+6. **Data Pruning**: Archive old data (>90 days inactive). Delete ephemeral data (cached images). Compress large payloads. Implement storage quotas. Monitor disk usage. User-triggered full sync to recover space.
+
+7. **Testing**: Simulate offline mode. Test conflict scenarios (concurrent edits). Verify data integrity post-sync. Test with poor network (slow 3G). Load test sync with large datasets. Monitor sync latency and queue depth.
+</process>

package/.agent/mindforge/onboard.md

@@ -0,0 +1,37 @@
+---
+description: Generate a knowledge graph, entry point summary, and learning path for the current or specified codebase. Usage - /mindforge:onboard [path] [--depth shallow|deep] [--output ONBOARDING-REPORT.md]
+---
+
+<objective>
+Rapidly understand an unfamiliar codebase by generating structured summaries,
+identifying entry points, and creating an ordered learning path.
+</objective>
+
+<execution_context>
+@.mindforge/skills/codebase-onboarding/SKILL.md
+@.mindforge/engine/knowledge-graph-protocol.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Determine target directory (default: current working directory).
+2. Detect stack: scan for package.json, Cargo.toml, go.mod, pyproject.toml, etc.
+3. Identify languages, frameworks, build tools, and test frameworks.
+4. Find entry points: main files, bin entries, route definitions, CLI commands, event handlers.
+5. If --depth deep: build full module dependency graph (nodes=files, edges=imports).
+6. If --depth shallow: identify top 10 most-imported modules only.
+7. Identify hot paths: files modified most frequently (git log --name-only).
+8. Generate learning path: ordered file reading sequence (config → entry → core → utilities → edge cases).
+9. Write ONBOARDING-REPORT.md (or --output path) to `.planning/` with sections:
+   - Overview (1-paragraph summary)
+   - Tech Stack (detected languages, frameworks, tools)
+   - Entry Points (with file paths)
+   - Architecture (module graph summary)
+   - Hot Paths (most-active areas)
+   - Learning Path (ordered reading list with WHY for each file)
+   - Concerns (potential issues spotted during exploration)
+10. Log onboarding event in AUDIT.
+</process>

package/.agent/mindforge/orchestrate.md

@@ -0,0 +1,74 @@
+---
+description: "Design multi-agent orchestration pattern for a task. Usage: /mindforge:orchestrate [task] [--pattern supervisor|pipeline|debate|consensus|mapreduce]"
+---
+
+<objective>
+Design and implement a multi-agent orchestration pattern for a complex task, defining agent roles, handoff protocols, failure propagation, and coordination mechanisms.
+</objective>
+
+<execution_context>
+@.mindforge/skills/agent-orchestration-patterns/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (task description, optional --pattern supervisor|pipeline|debate|consensus|mapreduce)
+Knowledge: Available agent patterns, existing personas, swarm templates, coordination protocols.
+</context>
+
+<process>
+1. **Assess if multi-agent needed**: Evaluate single-agent vs multi-agent:
+   - Does the task require multiple distinct skill domains?
+   - Would sequential processing create unacceptable latency?
+   - Does the task benefit from adversarial validation?
+   - Is the task decomposable into independent subtasks?
+   - Would a single agent exceed context window constraints?
+   - If single-agent suffices, recommend that and stop
+
+2. **Select pattern from matrix**: Choose orchestration pattern:
+   - `supervisor`: Central coordinator delegates to specialists, aggregates results. Best for: heterogeneous subtasks with dependencies
+   - `pipeline`: Sequential handoff between stages. Best for: transformation chains (draft→review→edit→publish)
+   - `debate`: Multiple agents argue positions, judge synthesizes. Best for: architectural decisions, trade-off analysis
+   - `consensus`: All agents propose, vote on best approach. Best for: code review, quality assessment
+   - `mapreduce`: Fan-out identical tasks, merge results. Best for: parallel search, batch processing
+   - Document why the selected pattern fits this specific task
+
+3. **Define agent roles**: For each agent in the pattern:
+   - Role name and persona reference (from personas registry)
+   - Specific responsibility and decision authority
+   - Input contract (what it receives, in what format)
+   - Output contract (what it produces, schema)
+   - Knowledge requirements (which skills/context it needs)
+   - Trust tier (1=autonomous, 2=review, 3=HITL approval)
+
+4. **Design handoff protocol**: Define JSON contracts for agent communication:
+   - Message envelope schema (from, to, type, payload, correlation_id)
+   - State passing mechanism (full state vs delta vs reference)
+   - Acknowledgment requirements (fire-and-forget vs confirmed delivery)
+   - Timeout per handoff (prevent infinite waits)
+   - Schema validation at each boundary (reject malformed handoffs)
+   - Context budget per agent (prevent token overflow)
+
+5. **Define failure propagation**: For each failure mode:
+   - Agent timeout → retry with backoff, then escalate to supervisor
+   - Agent error → log, attempt recovery, propagate if unrecoverable
+   - Consensus failure → add tiebreaker agent or escalate to human
+   - Cascade failure → circuit breaker pattern, fail fast
+   - Partial completion → checkpoint state, enable resume
+   - Define maximum retry count and escalation path
+
+6. **Implement coordination**: Build the orchestration logic:
+   - Supervisor: task queue, assignment logic, result aggregation
+   - Pipeline: stage transitions, backpressure handling, error short-circuit
+   - Debate: round management, argument collection, verdict synthesis
+   - Consensus: proposal collection, voting mechanism, quorum rules
+   - MapReduce: work partitioning, parallel dispatch, merge strategy
+   - Add observability (trace each agent invocation, measure latency)
+
+7. **Test the orchestration**: Validate the design:
+   - Happy path: all agents succeed, results merge correctly
+   - Partial failure: one agent fails, system recovers gracefully
+   - Timeout: slow agent detected and handled within SLA
+   - Conflict: agents disagree, resolution mechanism activates
+   - Load: pattern scales with task size (10x input, linear cost)
+   - Output: orchestration spec with diagram and runnable configuration
+</process>

package/.agent/mindforge/payments.md

@@ -0,0 +1,28 @@
+---
+description: "Design payment flow architecture with PCI minimization. Usage: /mindforge:payments [flow] [--provider stripe|braintree] [--recurring]"
+---
+
+<objective>
+Design a robust payment flow architecture that minimizes PCI compliance scope through client-side tokenization, handles webhooks reliably, ensures idempotency across all charge operations, and accounts for the full lifecycle including refunds and disputes.
+</objective>
+
+<execution_context>
+@.mindforge/skills/payment-integration/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (payment flow type, optional --provider, optional --recurring flag)
+Knowledge: PCI DSS requirements, payment provider documentation, existing payment infrastructure, business rules for pricing/billing.
+</context>
+
+<process>
+1. **Design Payment State Machine**: Model all payment states (pending, processing, succeeded, failed, refunded, disputed) and valid transitions. Include timeout states and partial states (partial refund, partial capture). Visualize as a state diagram.
+2. **Implement Client-Side Tokenization**: Use the provider's client-side SDK (Stripe Elements, Braintree Drop-in) to tokenize card data in the browser. Server never sees raw card numbers — this reduces PCI scope to SAQ-A or SAQ-A-EP.
+3. **Set Up Webhook Handling**: Implement webhook endpoint with: signature verification (reject unverified), idempotent processing (dedup by event ID), async processing (acknowledge quickly, process in background), and ordered handling for related events.
+4. **Add Idempotency Keys To All Charges**: Every charge request must include an idempotency key (client-generated UUID). Store key-to-result mapping. On retry, return cached result instead of double-charging.
+5. **Implement Retry Logic For Failures**: Design retry strategy: exponential backoff for transient failures (network, 5xx), immediate fail for permanent errors (card declined, insufficient funds), and alert on repeated failures for the same customer.
+6. **Design Refund Flow**: Support full and partial refunds. Track refund reason codes. Implement refund limits (cannot refund more than charged). Handle refund-after-dispute edge case. Update accounting records atomically.
+7. **Set Up Daily Reconciliation**: Implement automated daily reconciliation between: internal payment records, provider settlement reports, and accounting system. Alert on discrepancies > threshold. Resolve within 24 hours.
+8. **Handle Disputes And Chargebacks**: Design dispute response workflow: auto-collect evidence (receipts, delivery proof, usage logs), notify team within SLA, track win rate, and implement prevention measures for common dispute reasons.
+9. **Document Edge Cases**: Catalog and handle: currency conversion timing, 3D Secure flows, subscription payment retries, card expiration mid-subscription, account updater responses, and cross-border payment restrictions.
+</process>

package/.agent/mindforge/pipeline.md

@@ -0,0 +1,84 @@
+---
+description: "Design CI/CD pipeline architecture. Usage: /mindforge:pipeline [--platform github|gitlab|jenkins] [--stages N]"
+---
+
+<objective>
+Design a comprehensive CI/CD pipeline architecture with quality gates, caching, secret management, parallelism, environment promotion, and rollback mechanisms.
+</objective>
+
+<execution_context>
+@.mindforge/skills/ci-cd-pipeline/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional --platform github|gitlab|jenkins, optional --stages N for stage count)
+Knowledge: Current repository structure, existing CI configuration, deployment targets, test suite characteristics.
+</context>
+
+<process>
+1. **Define stages**: Design the pipeline stages in order:
+   - **Lint**: Static analysis, formatting check, type-check (parallel)
+   - **Build**: Compile, bundle, generate artifacts
+   - **Test**: Unit tests, integration tests, contract tests (parallel by suite)
+   - **Scan**: Security scan (SAST, dependency audit, secret detection)
+   - **Package**: Container build, artifact versioning, manifest generation
+   - **Deploy**: Environment promotion (dev → staging → production)
+   - Each stage has clear entry/exit criteria (quality gates)
+
+2. **Add quality gates**: Define pass/fail criteria per stage:
+   - Lint: zero errors (warnings allowed with suppression comments)
+   - Build: successful compilation, artifact size within budget
+   - Test: 100% pass rate, coverage >= threshold (80% default)
+   - Scan: zero critical/high vulnerabilities, no leaked secrets
+   - Package: image builds successfully, passes container scan
+   - Deploy: health check passes within 60s, no error spike in 5min
+   - Gate failure blocks pipeline progression (no manual override without approval)
+
+3. **Configure caching**: Optimize pipeline speed:
+   - Dependencies: cache node_modules/pip/cargo by lockfile hash
+   - Build artifacts: cache intermediate compilation outputs
+   - Docker layers: cache base layers, invalidate on Dockerfile change
+   - Test results: cache unchanged test file results (incremental testing)
+   - Cache key strategy: OS + lockfile hash + branch (with fallback to main)
+   - Cache TTL: 7 days for dependencies, 1 day for build artifacts
+
+4. **Manage secrets**: Secure credential handling:
+   - Environment-specific secrets (dev, staging, prod) in vault/secrets manager
+   - Short-lived tokens for deployment (OIDC where possible)
+   - No secrets in pipeline YAML (reference by name only)
+   - Secret rotation: automated rotation with zero-downtime
+   - Audit log: track which pipeline accessed which secret
+   - Least privilege: each stage only accesses secrets it needs
+
+5. **Enable parallelism**: Maximize pipeline throughput:
+   - Independent stages run in parallel (lint + type-check + unit-test)
+   - Test suite splitting by file/timing data across N runners
+   - Matrix builds for multi-platform/multi-version testing
+   - Fan-out/fan-in for independent service deployments
+   - Resource constraints: limit concurrent deployments to prevent thundering herd
+   - Estimated total pipeline time: < 10 minutes for PR, < 20 minutes for deploy
+
+6. **Set up environment promotion**: Define the deployment ladder:
+   - Dev: auto-deploy on push to feature branch (ephemeral environments)
+   - Staging: auto-deploy on merge to main (persistent, production-mirror)
+   - Production: manual approval gate or automated canary with auto-promote
+   - Promotion criteria: all tests pass + no new alerts + stakeholder approval
+   - Environment parity: same container, same config structure, different values
+   - Feature flags: decouple deploy from release (dark launches)
+
+7. **Add rollback mechanism**: Design recovery paths:
+   - Automated rollback: revert to last-known-good on health check failure
+   - Manual rollback: one-click revert in CI UI with confirmation
+   - Database rollback: backward-compatible migrations only (expand-contract)
+   - Canary rollback: automatic if error rate exceeds baseline by 2x
+   - Rollback verification: post-rollback health check confirms recovery
+   - Incident tracking: auto-create incident ticket on rollback trigger
+
+8. **Output pipeline specification**: Deliver:
+   - Pipeline YAML/configuration for the target platform
+   - Stage dependency graph (DAG visualization)
+   - Timing estimates per stage
+   - Secret inventory and access matrix
+   - Rollback runbook
+   - Cost estimate (runner minutes per PR and per deploy)
+</process>