mindforge-cc 11.3.0 → 11.3.1

package/.claude/commands/mindforge/product-spec.md

@@ -0,0 +1,90 @@
+---
+description: "Create PRD with user stories and prioritized backlog. Usage: /mindforge:product-spec [feature] [--framework RICE|MoSCoW]"
+---
+
+<objective>
+Generate a Product Requirements Document with well-defined personas, user journeys, scored user stories, and a prioritized backlog ready for sprint planning. Outputs an actionable PRD with acceptance criteria.
+</objective>
+
+<execution_context>
+@.mindforge/skills/product-manager/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (feature name or description, optional --framework for prioritization)
+Knowledge: PROJECT.md, existing BRDs, market research, competitive analysis, user feedback.
+</context>
+
+<process>
+1. **Define personas**: Create 2-4 user personas relevant to the feature:
+   - Name, role, and demographic summary
+   - Goals and motivations
+   - Pain points and frustrations
+   - Technical proficiency level
+   - Key quote that captures their mindset
+   - Usage frequency (daily, weekly, monthly)
+
+2. **Map user journeys**: For each persona, trace the end-to-end journey:
+   - Trigger (what initiates the journey)
+   - Steps (each action the user takes)
+   - Touchpoints (where they interact with the system)
+   - Emotions at each step (frustrated, neutral, delighted)
+   - Drop-off risk points
+   - Success criteria for journey completion
+
+3. **Write user stories**: For each journey step that requires system behavior:
+   - Format: "As a [persona], I want to [action] so that [outcome]"
+   - Include edge cases as separate stories
+   - Tag with epic/theme grouping
+   - Estimate complexity (story points: 1, 2, 3, 5, 8, 13)
+
+4. **Score with framework**: Apply the selected prioritization framework:
+   - **RICE**: Reach * Impact * Confidence / Effort (score each 1-10)
+   - **MoSCoW**: Must have / Should have / Could have / Won't have
+   - Document scoring rationale for each story
+   - Flag any stories where team disagrees on score
+
+5. **Prioritize backlog**: Rank all stories by framework score:
+   - Group into release milestones (MVP, v1.1, v1.2, future)
+   - Identify dependencies between stories (must-before relationships)
+   - Mark stories that can be parallelized
+   - Calculate total effort per milestone
+
+6. **Define acceptance criteria**: For each Must-have story:
+   - Given-When-Then scenarios (happy path + error paths)
+   - Performance expectations (load time, response time)
+   - Accessibility requirements (WCAG level)
+   - Cross-browser/device requirements
+   - Data validation rules
+
+7. **Output PRD**: Write the complete PRD with sections:
+   - Problem Statement (what pain are we solving, for whom, why now)
+   - Goals and Non-Goals (explicitly state what we will NOT do)
+   - Personas and User Journeys
+   - Feature Requirements (prioritized backlog)
+   - Technical Constraints and Dependencies
+   - Success Metrics (leading and lagging indicators)
+   - Release Plan (milestones with dates)
+   - Open Questions and Risks
+
+8. **Define success metrics**: For the feature overall:
+   - Adoption metric (% of target users who try it)
+   - Engagement metric (frequency/depth of usage)
+   - Retention metric (continued usage after 30 days)
+   - Business metric (revenue, cost reduction, NPS impact)
+   - Technical metric (error rate, latency, support tickets)
+
+9. **Risk assessment**: Identify risks to successful delivery:
+   - Technical risks (feasibility, integration complexity)
+   - Market risks (user adoption, competitive response)
+   - Resource risks (team availability, skill gaps)
+   - Timeline risks (dependencies, scope creep triggers)
+   - Mitigation plan for each risk
+
+10. **Stakeholder review package**: Prepare summary for review:
+    - One-page executive summary
+    - Prioritized feature list with effort estimates
+    - Key trade-off decisions requiring input
+    - Timeline with confidence intervals
+    - Request specific decisions from specific stakeholders
+</process>

package/.claude/commands/mindforge/profile-team.md

@@ -0,0 +1,27 @@
+---
+description: Generate and maintain team/developer profiles for response personalization.
+---
+
+# MindForge — Profile Team Command
+# Usage: /mindforge:profile-team [--refresh] [--developer email] [--questionnaire]
+
+Generate and maintain team/developer profiles for response personalization.
+
+## Data sources
+1. Declared questionnaire preferences
+2. Inferred patterns from AUDIT + git history + metrics
+3. Defaults from org conventions
+
+## Outputs
+- `.mindforge/team/TEAM-PROFILE.md`
+- `.mindforge/team/profiles/PROFILE-[dev-id].md`
+
+## Modes
+- `--refresh`: inference-only update
+- `--developer`: target one developer profile
+- `--questionnaire`: prompt preference questions before writing
+
+## AUDIT
+```json
+{ "event": "team_profile_updated", "developers_profiled": 1, "method": "inferred" }
+```

package/.claude/commands/mindforge/prompt.md

@@ -0,0 +1,78 @@
+---
+description: "Design and optimize AI prompts with caching strategy. Usage: /mindforge:prompt [task-description] [--style system|few-shot|cot] [--cache]"
+---
+
+<objective>
+Design and optimize AI prompts with appropriate structure, caching strategy, and iteration based on edge-case testing — producing production-grade prompts that maximize model performance.
+</objective>
+
+<execution_context>
+@.mindforge/skills/prompt-engineering/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (task description, optional --style system|few-shot|cot, optional --cache flag)
+Knowledge: Current system prompts, model capabilities, prompt caching mechanics, few-shot example libraries.
+</context>
+
+<process>
+1. **Analyze task**: Understand the task requirements:
+   - What is the desired output format and quality bar?
+   - What model will execute this prompt? (capabilities, context window)
+   - What failure modes are likely? (hallucination, refusal, drift)
+   - What constraints exist? (token budget, latency, cost)
+   - Is this a one-shot task or a recurring pattern?
+
+2. **Select prompt style**: Based on --style flag or task analysis:
+   - `system`: Structured system prompt with role, constraints, and output format
+   - `few-shot`: System prompt + curated examples demonstrating desired behavior
+   - `cot`: Chain-of-thought with explicit reasoning steps before answer
+   - Hybrid: Combine styles when task complexity demands it
+   - Document rationale for style selection
+
+3. **Design system prompt structure**: Build the prompt skeleton:
+   - Identity/role definition (who the model is)
+   - Task description (what to do)
+   - Constraints and guardrails (what NOT to do)
+   - Output format specification (exact structure expected)
+   - Edge-case handling instructions (when ambiguous, do X)
+   - Prioritization rules (if conflicts, prefer Y over Z)
+
+4. **Add few-shot examples if needed**: When --style includes few-shot:
+   - Select 3-5 diverse examples covering the input distribution
+   - Include at least one edge case example
+   - Include at least one "refusal" example (when to say no)
+   - Order examples from simple to complex
+   - Ensure examples are representative, not cherry-picked
+
+5. **Implement caching strategy**: When --cache flag is set:
+   - Place static content first (system prompt, examples, reference docs)
+   - Mark cache breakpoint after static prefix
+   - Keep dynamic content (user input, session context) after breakpoint
+   - Estimate cache hit rate based on usage pattern
+   - Calculate cost savings (cached tokens at 90% discount)
+   - Ensure static prefix exceeds minimum cacheable length (1024 tokens)
+
+6. **Test with edge cases**: Validate the prompt against:
+   - Adversarial inputs (prompt injection attempts)
+   - Ambiguous inputs (multiple valid interpretations)
+   - Empty/minimal inputs (graceful handling)
+   - Maximum-length inputs (truncation behavior)
+   - Out-of-domain inputs (appropriate refusal)
+   - Multi-language inputs if applicable
+
+7. **Iterate on failures**: For each failure mode discovered:
+   - Identify root cause (missing constraint, ambiguous instruction, weak example)
+   - Add targeted fix (new constraint, clarified instruction, better example)
+   - Re-test to confirm fix without regression
+   - Document the failure and fix for future reference
+   - Version the prompt iteration (v1, v2, v3...)
+
+8. **Output final prompt**: Deliver the production prompt:
+   - Complete prompt text with clear section markers
+   - Token count breakdown (system, examples, dynamic budget)
+   - Caching configuration if applicable
+   - Known limitations and edge cases
+   - Recommended model and temperature settings
+   - Eval criteria for ongoing quality monitoring
+</process>

package/.claude/commands/mindforge/proofread.md

@@ -0,0 +1,87 @@
+---
+description: "Run copy editing pass for grammar, tone, clarity, and readability. Usage: /mindforge:proofread [file] [--tone formal|casual|technical] [--fix]"
+---
+
+<objective>
+Perform a thorough copy editing pass on a document or code comments, checking grammar, tone consistency, clarity, terminology, and readability — then either report findings or apply fixes directly.
+</objective>
+
+<execution_context>
+@.mindforge/skills/proofreader/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (file path to proofread, optional --tone target, optional --fix to auto-apply corrections)
+Knowledge: Project terminology from CONVENTIONS.md, brand voice guidelines, target audience.
+</context>
+
+<process>
+1. **Read for flow**: Read the entire document once without marking issues. Assess:
+   - Does the document have a clear logical structure?
+   - Does each section follow naturally from the previous?
+   - Are there abrupt transitions or missing connective tissue?
+   - Is the overall length appropriate for the content?
+   - Does it achieve its stated purpose?
+
+2. **Check grammar**: Scan for grammatical issues:
+   - Subject-verb agreement
+   - Tense consistency (past/present/future mixed incorrectly)
+   - Dangling modifiers and misplaced clauses
+   - Pronoun-antecedent agreement and clarity
+   - Run-on sentences and comma splices
+   - Incorrect word usage (affect/effect, its/it's, their/there)
+
+3. **Check clarity**: Evaluate sentence-level clarity:
+   - Sentence length (flag any over 30 words — suggest splitting)
+   - Active vs passive voice ratio (prefer active, flag unnecessary passive)
+   - Nominalization (verbs turned to nouns: "implementation of" → "implement")
+   - Hedge words that weaken claims (somewhat, rather, quite, basically)
+   - Ambiguous pronouns ("this", "it" without clear referent)
+
+4. **Check tone consistency**: Against --tone flag or inferred tone:
+   - `formal`: No contractions, no colloquialisms, third person
+   - `casual`: Contractions OK, direct address (you/we), conversational
+   - `technical`: Precise terminology, no anthropomorphism, specification-style
+   - Flag any sections that deviate from the target tone
+   - Note if tone shifts are intentional (e.g., callout boxes)
+
+5. **Check terminology**: Verify consistent term usage:
+   - Build a glossary of domain terms used in the document
+   - Flag synonyms used interchangeably (user/customer/client — pick one)
+   - Verify capitalization consistency for product names and features
+   - Check abbreviation introduction (first use should be spelled out)
+   - Cross-reference with CONVENTIONS.md terminology if available
+
+6. **Score readability**: Compute metrics:
+   - Average sentence length (target: 15-20 words)
+   - Average paragraph length (target: 3-5 sentences)
+   - Flesch-Kincaid grade level (target depends on audience)
+   - Percentage of passive voice (target: <15%)
+   - Jargon density (specialized terms per 100 words)
+
+7. **Check formatting**: Verify structural consistency:
+   - Heading hierarchy (no skipped levels)
+   - List formatting (parallel structure within lists)
+   - Code block syntax highlighting language tags
+   - Link text is descriptive (not "click here")
+   - Consistent use of bold/italic/code formatting
+
+8. **Report findings**: If --fix is NOT set, output a structured report:
+   - Summary statistics (word count, readability score, issue count by severity)
+   - Issues grouped by type (grammar, clarity, tone, terminology)
+   - Each issue: line number, original text, suggested fix, severity (error/warning/style)
+   - Top 3 most impactful improvements to make
+
+9. **Apply fixes**: If --fix IS set:
+   - Apply all error-severity fixes automatically
+   - Apply warning-severity fixes automatically
+   - Present style-level suggestions for user approval
+   - Show a diff summary of all changes made
+   - Preserve the author's voice — improve, don't rewrite
+
+10. **Final assessment**: Provide an overall quality rating:
+    - Grade: A (publish-ready) / B (minor polish needed) / C (significant editing needed) / D (rewrite recommended)
+    - Strengths of the writing (what works well)
+    - Top 3 areas for improvement
+    - Estimated time to address remaining issues
+</process>

package/.claude/commands/mindforge/publish-skill.md

@@ -0,0 +1,23 @@
+---
+description: Publish a skill to the npm registry (or private registry).
+---
+
+# MindForge — Publish Skill Command
+# Usage: /mindforge:publish-skill [skill-dir] [--registry URL] [--dry-run]
+
+Publish a skill to the npm registry (or private registry).
+
+Pre-publication checklist:
+1. Run full skill validation (Level 1 + 2 + 3 from skill-validator.md)
+   Fail if Level 1 or 2 fails. Warn if Level 3 fails.
+2. Verify package.json has `mindforge` field with all required sub-fields
+3. Verify CHANGELOG.md has an entry for the current version
+4. Check if version already published: `npm info [package-name]@[version]`
+   If already published: error "Version already exists. Bump the version."
+5. Run `npm pack --dry-run` to preview what will be published
+6. Confirm with user: "These files will be published: [list]. Proceed? (yes/no)"
+7. If --dry-run: stop here, show preview only
+8. Publish: `npm publish --access public`
+9. Verify: `npm info [package-name]@[version]` — confirm publication succeeded
+10. Write AUDIT: `{ "event": "skill_published", "package": "...", "version": "..." }`
+11. Report: "✅ [package-name]@[version] published to npm registry"

package/.claude/commands/mindforge/push-notify.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:push-notify
+description: "Design push notification architecture. Usage: /mindforge:push-notify [channel] [--platform ios|android|web] [--priority high|normal|low]"
+argument-hint: "[channel] [--platform ios|android|web] [--priority high|normal|low]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design push notification systems with platform-specific optimizations, delivery guarantees, user preference management, and A/B testing capabilities.
+</objective>
+
+<execution_context>
+@.mindforge/skills/push-notification-architecture/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/push-notification-architecture/`
+State: Designs notification delivery pipeline, platform integration (APNS/FCM), segmentation rules, opt-in flows, and analytics tracking.
+</context>
+
+<process>
+1. **Platform Integration**: iOS (APNs, certificates or token-based auth, silent/regular notifications). Android (FCM, priority handling, notification channels). Web (Push API, VAPID keys, service worker required). Use vendor SDKs (OneSignal, Pusher, Firebase) or direct APIs.
+
+2. **Delivery Architecture**: Queue-based system (SQS, RabbitMQ). Worker processes consume queue. Batch sends (1000/request). Exponential backoff on failure. Dead-letter queue for permanent failures. Monitor send rate and latency.
+
+3. **User Preferences**: Opt-in prompt timing (after first value delivered, not immediately). Granular channels (promotions, updates, transactional). Quiet hours (no notifications 10pm-8am). Frequency caps (max 3/day). Persistent preferences in user profile.
+
+4. **Personalization**: User segmentation (behavior, demographics, device). Dynamic content (name, location, recent activity). A/B testing (message variants, send times). Predictive send time optimization. Track conversion per variant.
+
+5. **Rich Notifications**: Images/videos in notification. Action buttons (reply, snooze, deep link). Grouped notifications (conversation threads). Badge count management. Sound/vibration customization. Lock screen vs notification center.
+
+6. **Analytics**: Delivery rate (sent vs delivered). Open rate (by platform, time, segment). Conversion rate (notification → action). Opt-out tracking (which channels). Notification fatigue metrics (declining engagement over time).
+
+7. **Compliance**: GDPR (explicit consent, right to withdraw). CAN-SPAM (transactional vs promotional). Time-sensitive (medical, financial) vs marketing. Unsubscribe mechanism. Audit log of sends. Rate limiting to prevent spam.
+</process>

package/.claude/commands/mindforge/pwa.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:pwa
+description: "Progressive Web App design. Usage: /mindforge:pwa [app] [--cache networkfirst|cachefirst|stale] [--scope full|partial]"
+argument-hint: "[app] [--cache networkfirst|cachefirst|stale] [--scope full|partial]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design Progressive Web Apps with service worker caching strategies, offline capabilities, install prompts, and native-like experiences on web.
+</objective>
+
+<execution_context>
+@.mindforge/skills/progressive-web-app/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/progressive-web-app/`
+State: Designs service worker architecture, caching strategies, manifest configuration, and progressive enhancement patterns for installable web apps.
+</context>
+
+<process>
+1. **Service Worker Strategy**: Network-first (fresh data, fallback to cache) → news apps. Cache-first (performance, stale data OK) → static assets, docs. Stale-while-revalidate (instant + fresh) → social feeds. Network-only → auth endpoints. Cache-only → app shell.
+
+2. **Caching Layers**: App shell (HTML/CSS/JS core, precache on install). Static assets (images/fonts, long cache TTL). API responses (runtime cache, short TTL). User content (IndexedDB for structured data). Max 50MB quota (mobile browsers).
+
+3. **Offline UX**: Detect offline with navigator.onLine. Show offline indicator. Queue mutations (background sync API). Cached content with freshness timestamp. Graceful feature degradation. Custom offline page.
+
+4. **Install Experience**: Manifest.json (name, icons, theme_color, display:standalone). Defer install prompt (show after user engagement). A2HS (Add to Home Screen) button. Track install analytics. Update prompt when new version available.
+
+5. **Performance**: Lighthouse score >90. First Contentful Paint <1.8s. Time to Interactive <3.5s. Cumulative Layout Shift <0.1. Code splitting. Lazy load images. Preload critical resources.
+
+6. **Platform Features**: Push notifications (with user permission). Background sync (retry failed requests). Share target (receive shared content). Shortcuts (quick actions in app icon menu). Badging API (unread count).
+
+7. **Update Strategy**: Skip waiting for critical updates. Prompt user for non-critical updates. Version in cache names. Migration logic for schema changes. Test update flow in CI. Monitor update adoption rate.
+</process>

package/.claude/commands/mindforge/qa.md

@@ -0,0 +1,20 @@
+---
+description: @mindforge qa [--phase N] [--auto]
+---
+
+# /mindforge:qa
+
+## Usage
+`@mindforge qa [--phase N] [--auto]`
+
+## Description
+Runs systematic visual QA on UI surfaces changed in the current phase.
+Analyzes git diff to find pages, navigates to them, and looks for errors.
+
+## Options
+- `--phase N`: Target specific phase for reporting (defaults to current).
+- `--auto`: Automatically run after successful wave execution if configured.
+
+## Output
+- `QA-REPORT-[N].md`: Found bugs with screenshots.
+- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.

package/.claude/commands/mindforge/quality-audit.md

@@ -0,0 +1,34 @@
+---
+description: Run weighted 4-dimension quality scoring on current output. Usage - /mindforge:quality-audit [target] [--mode quick|full|comparative] [--compare path]
+---
+
+<objective>
+Score output quality across four weighted dimensions (Clarity, Completeness,
+Accuracy, Usefulness) with a blocking accuracy gate.
+</objective>
+
+<execution_context>
+@.mindforge/skills/quality-audit/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse target (file/diff/output to evaluate) and mode (default: full).
+2. If --mode quick: evaluate Accuracy dimension only (fast gate check).
+3. If --mode full: evaluate all 4 dimensions.
+4. If --mode comparative: load --compare target, score BOTH, produce delta.
+5. For each dimension, score 1-5 with specific evidence citations:
+   - Clarity (25%): Is it understandable? Unambiguous? Well-structured?
+   - Completeness (25%): Does it cover all requirements? Any gaps?
+   - Accuracy (30%): Is it factually correct? Do code refs exist? Do examples work?
+   - Usefulness (20%): Does it solve the actual problem? Is it actionable?
+6. Compute weighted average: (clarity*0.25 + completeness*0.25 + accuracy*0.30 + usefulness*0.20).
+7. Check blocking gate: if accuracy < 3.0 → FAIL regardless of other scores.
+8. Determine verdict: weighted avg >= 3.0 AND accuracy >= 3.0 → PASS.
+9. Report per-dimension scores, weighted average, verdict, and evidence.
+10. If comparative: show side-by-side scores with improvement/regression indicators.
+11. Log quality audit in AUDIT.
+</process>

package/.claude/commands/mindforge/queue.md

@@ -0,0 +1,31 @@
+---
+description: Design message queue topology and broker selection. Usage - /mindforge:queue [domain] [--broker kafka|rabbitmq|sqs] [--pattern fanout|topic|p2p]
+---
+
+<objective>
+Design a message queue topology that selects the right broker for the workload,
+configures routing patterns for decoupled communication, implements dead-letter
+handling for poison messages, and provides observability into queue depth,
+consumer throughput, and delivery guarantees.
+</objective>
+
+<execution_context>
+@.mindforge/skills/queue-design/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify messaging needs by analyzing the domain: message volume (msgs/sec), payload size, ordering requirements, delivery guarantee (at-most-once, at-least-once, exactly-once), and retention period. Classify as command (point-to-point) or event (broadcast).
+2. Select broker based on --broker flag or requirements: Kafka for high-throughput ordered event streams with replay, RabbitMQ for complex routing with flexible patterns and low-latency RPC, SQS for serverless with minimal ops overhead. Document selection rationale.
+3. Design topic/queue topology based on --pattern: fanout (all consumers receive all messages), topic (content-based routing with wildcards), point-to-point (single consumer per message). Map domain events to topics/exchanges with clear naming conventions.
+4. Configure consumers: competing consumers for horizontal scaling (consumer groups), broadcast consumers for event notification, and exclusive consumers for ordered processing. Set prefetch count and acknowledgment mode.
+5. Set TTL and dead-letter queue (DLQ) policies: define message expiration per queue, max delivery attempts before DLQ routing, DLQ retention period, and DLQ monitoring with alerting on depth > 0. Implement DLQ replay tooling.
+6. Plan partition strategy (Kafka) or queue sharding (RabbitMQ): partition by entity key for ordering, configure replication factor for durability, set min-ISR for write safety. For SQS, configure visibility timeout and batch size.
+7. Configure monitoring and alerting: track queue depth, consumer lag, publish/consume rates, unacknowledged messages, and DLQ depth. Set alerts on queue depth exceeding 10x normal and consumer lag exceeding processing SLA.
+8. Document message schemas: define payload contracts (JSON Schema or Avro), versioning strategy (envelope with schema_version field), backward/forward compatibility rules, and schema registry integration.
+9. Design retry and error handling: exponential backoff with jitter for transient failures, circuit breaker for downstream unavailability, poison message detection (fail count > threshold), and manual intervention workflow for unprocessable messages.
+10. Log queue design decision in AUDIT with: domain, broker, pattern, throughput target, delivery guarantee, DLQ policy, and partition count.
+</process>

package/.claude/commands/mindforge/quick.md

@@ -0,0 +1,139 @@
+---
+description: Use QUICK for:
+---
+
+# MindForge — Quick Command
+# Usage: /mindforge:quick [--research] [--review] [--full]
+# For ad-hoc tasks that don't need full lifecycle management.
+
+## When to use quick vs plan-phase
+Use QUICK for:
+- Bug fixes not tied to a current phase
+- Small improvements (< 3 files, < 2 hours)
+- Dependency updates
+- Documentation corrections
+- One-off scripts or utilities
+
+Use PLAN-PHASE for:
+- Feature development
+- Anything touching more than 6 files
+- Anything requiring research before implementation
+- Anything with external dependencies or stakeholder requirements
+
+## Step 1 — Task intake
+
+Ask the user:
+"What do you want to do?"
+
+Listen to the description. If the task sounds larger than "quick" scope
+(more than 6 files, architectural change, new feature), say:
+"This sounds like more than a quick task. I recommend using /mindforge:plan-phase
+ instead to ensure it's properly planned and verified. Want to proceed with quick anyway?"
+
+## Step 2 — Optional research (--research flag or user requests it)
+
+If `--research` is provided or the task involves unfamiliar libraries:
+Spawn a focused research subagent. Give it:
+- The task description
+- The current tech stack from PROJECT.md
+Ask it to: investigate the best approach, identify gotchas, recommend specific
+libraries (with versions), and write a brief research note.
+
+Report research findings to the user before proceeding.
+
+## Step 3 — Create a quick plan
+
+### Sequential quick task numbering
+Determine the next quick task number by scanning `.planning/quick/`:
+1. List directories matching `[0-9][0-9][0-9]-*`
+2. Take the max numeric prefix and add 1 (start at 001 if none exist)
+3. If a directory already exists for the chosen number, require `--force` to proceed
+
+Create `.planning/quick/[NNN]-[slug]/PLAN.md` where NNN is a sequential number
+and slug is a 2-4 word kebab-case description.
+
+Example: `.planning/quick/001-fix-login-null-check/PLAN.md`
+
+Use the standard XML plan format:
+```xml
+<task type="quick">
+  <n>[task name]</n>
+  <persona>[appropriate persona]</persona>
+  <files>[files to touch]</files>
+  <context>[relevant context]</context>
+  <action>[implementation instructions]</action>
+  <verify>[verification command]</verify>
+  <done>[definition of done]</done>
+</task>
+```
+
+Show the plan to the user. Wait for approval before executing.
+
+## Step 4 — Execute the quick plan
+
+### Security auto-trigger (mandatory)
+Before execution, scan the task description and files for security keywords:
+auth, authentication, login, password, token, JWT, session, payment, PII, upload,
+credential, secret, key.
+
+If any keyword matches: load `security-review/SKILL.md` and activate
+`security-reviewer.md` persona for the implementation. This is required even
+without the `--full` flag.
+
+1. Load persona from `.mindforge/personas/`
+2. Load any relevant skills based on task keywords
+3. Execute the plan
+4. Run `<verify>` — must pass before committing
+5. Commit: `[type](quick/[NNN]): [task name]`
+6. Write `.planning/quick/[NNN]-[slug]/SUMMARY.md`
+
+### STATE.md update policy
+Quick tasks do not change phase status. If there is no active phase, note the
+quick task completion in STATE.md under "Last completed task".
+
+## Step 5 — Optional review (--review flag)
+
+If `--review` is provided:
+Activate `code-quality.md` skill on the diff.
+Report any issues before committing.
+If BLOCKING issues found: fix before commit.
+
+## Step 6 — Optional full mode (--full flag)
+
+If `--full` is provided, additionally:
+- Run the project's full test suite (not just task-specific verify)
+- Run the type checker and linter
+- Activate `security-reviewer.md` if the task touches any security-sensitive code
+- Write an AUDIT entry for the quick task
+
+## Linting always runs
+Regardless of flags, after every quick task execution:
+1. Run the project's linter (from CONVENTIONS.md — check which linter applies)
+2. If lint errors found: fix them before committing.
+3. Linting is not part of `--full` — it is always part of quick.
+
+## Flags are composable
+```
+/mindforge:quick                     # minimal — task, plan, execute
+/mindforge:quick --research          # adds domain research step
+/mindforge:quick --review            # adds code quality review of diff
+/mindforge:quick --full              # adds full test suite + linting + security
+/mindforge:quick --research --full   # all of the above
+```
+
+## AUDIT entry for quick tasks
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO-8601",
+  "event": "quick_task_completed",
+  "agent": "mindforge-orchestrator",
+  "phase": null,
+  "session_id": "sess_abc",
+  "quick_id": "001",
+  "task_name": "Fix login null check",
+  "commit_sha": "abc1234",
+  "files_changed": ["src/auth/login.ts"],
+  "flags_used": ["--review"]
+}
+```

package/.claude/commands/mindforge/rag.md

@@ -0,0 +1,30 @@
+---
+description: Design RAG pipeline architecture with chunking and retrieval. Usage - /mindforge:rag [corpus] [--chunking semantic|fixed] [--retrieval hybrid] [--rerank]
+---
+
+<objective>
+Design a production RAG (Retrieval-Augmented Generation) pipeline with optimized
+chunking, hybrid retrieval, and re-ranking. Covers corpus ingestion, embedding
+strategy, retrieval quality evaluation, and context window packing.
+</objective>
+
+<execution_context>
+@.mindforge/skills/rag-architecture/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Analyze the corpus: document types (PDF, markdown, code, HTML), average document length, structure (headings, tables, code blocks), and total size. Identify natural semantic boundaries.
+2. Choose chunking strategy based on --chunking flag: semantic (split at paragraph/section boundaries, variable size 200-1000 tokens) or fixed (512 tokens with 50-token overlap). For code: chunk at function/class boundaries.
+3. Select embedding model based on corpus domain and latency requirements: OpenAI text-embedding-3-large (general, high quality), Cohere embed-v3 (multilingual), or local (BAAI/bge-large for privacy). Benchmark on domain-specific queries.
+4. Configure retrieval strategy based on --retrieval flag: dense-only (vector similarity), sparse-only (BM25/TF-IDF), or hybrid (dense + sparse with Reciprocal Rank Fusion, alpha=0.7 dense weight). Hybrid recommended for most cases.
+5. Add re-ranking if --rerank flag is set: retrieve top-50 candidates with fast retrieval, then re-rank with cross-encoder (ms-marco-MiniLM or Cohere rerank-v3) to get top-k (k=5-10). Dramatically improves precision.
+6. Design context packing strategy: order chunks by relevance, fit within context window budget (reserve 30% for generation), deduplicate overlapping chunks, and include metadata (source, page, section title).
+7. Set up evaluation pipeline: measure recall@k (are relevant chunks in top-k?), MRR (Mean Reciprocal Rank), and end-to-end answer quality. Build a golden test set of 50+ query-answer pairs with source attribution.
+8. Iterate on retrieval quality: tune chunk size, overlap, embedding model, retrieval weights, and re-ranker threshold. Use evaluation metrics to drive decisions. Target recall@10 > 0.9 on golden set.
+9. Design the ingestion pipeline: document parsing, chunking, embedding generation, vector store upsert. Handle incremental updates (add/modify/delete documents) without full re-index.
+10. Log rag invocation in AUDIT with: corpus size, chunking strategy, embedding model, retrieval method, evaluation metrics (recall@k, MRR).
+</process>