mindforge-cc 2.3.5 → 3.0.0-rc1

package/.agent/skills/mindforge-plan-phase/SKILL.md

@@ -26,6 +26,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--skip-verify` — Skip verification loop
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
 - `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/mindforge-review`)
+- `--ads` — Use Adversarial Decision Synthesis (Architect vs Auditor) for high-fidelity planning
 - `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
 
 Normalize phase input in step 2 before any directory lookups.

package/.agent/skills/mindforge-system-architecture/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: system-architecture
+description: Design systems with appropriate complexity - no more, no less. Use when the user asks to architect applications, design system boundaries, plan service decomposition, evaluate monolith vs microservices, make scaling decisions, or review structural trade-offs. Applies to new system design, refactoring, and migration planning.
+---
+
+# System Architecture
+
+Design real structures with clear boundaries, explicit trade-offs, and appropriate complexity. Match architecture to actual requirements, not imagined future needs.
+
+## Workflow
+
+When the user requests an architecture, follow these steps:
+
+```
+Task Progress:
+- [ ] Step 1: Clarify constraints
+- [ ] Step 2: Identify domains
+- [ ] Step 3: Map data flow
+- [ ] Step 4: Draw boundaries with rationale
+- [ ] Step 5: Run complexity checklist
+- [ ] Step 6: Present architecture with trade-offs
+```
+
+**Step 1 - Clarify constraints.** Ask about:
+
+| Constraint | Question | Why it matters |
+|------------|----------|----------------|
+| Scale | What's the real load? (users, requests/sec, data size) | Design for 10x current, not 1000x |
+| Team | How many developers? How many teams? | Deployable units ≤ number of teams |
+| Lifespan | Prototype? MVP? Long-term product? | Temporary systems need temporary solutions |
+| Change vectors | What actually varies? | Abstract only where you have evidence of variation |
+
+**Step 2 - Identify domains.** Group by business capability, not technical layer. Look for things that change for different reasons and at different rates.
+
+**Step 3 - Map data flow.** Trace: where does data enter → how does it transform → where does it exit? Make the flow obvious.
+
+**Step 4 - Draw boundaries.** Every boundary needs a reason: different team, different change rate, different compliance requirement, or different scaling need.
+
+**Step 5 - Run complexity checklist.** Before adding any non-trivial pattern:
+
+```
+[ ] Have I tried the simple solution?
+[ ] Do I have evidence it's insufficient?
+[ ] Can my team operate this?
+[ ] Will this still make sense in 6 months?
+[ ] Can I explain why this complexity is necessary?
+```
+
+If any answer is "no", keep it simple.
+
+**Step 6 - Present the architecture** using the output template below.
+
+## Output Template
+
+```markdown
+### System: [Name]
+
+**Constraints**:
+- Scale: [current and expected load]
+- Team: [size and structure]
+- Lifespan: [prototype / MVP / long-term]
+
+**Architecture**:
+[Component diagram or description of components and their relationships]
+
+**Data Flow**:
+[How data enters → transforms → exits]
+
+**Key Boundaries**:
+| Boundary | Reason | Change Rate |
+|----------|--------|-------------|
+| ... | ... | ... |
+
+**Trade-offs**:
+- Chose X over Y because [reason]
+- Accepted [limitation] to gain [benefit]
+
+**Complexity Justification**:
+- [Each non-trivial pattern] → [why it's needed, with evidence]
+```
+
+## Core Principles
+
+1. **Boundaries at real differences.** Separate concerns that change for different reasons and at different rates.
+2. **Dependencies flow inward.** Core logic depends on nothing. Infrastructure depends on core.
+3. **Follow the data.** Architecture should make data flow obvious.
+4. **Design for failure.** Network fails. Databases timeout. Build compensation into the structure.
+5. **Design for operations.** You will debug this at 3am. Every request needs a trace. Every error needs context for replay.
+
+For concrete good/bad examples of each principle, see [examples.md](examples.md).
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Microservices for a 3-person team | Well-structured monolith |
+| Event sourcing for CRUD | Simple state storage |
+| Message queues within the same process | Just call the function |
+| Distributed transactions | Redesign to avoid, or accept eventual consistency |
+| Repository wrapping an ORM | Use the ORM directly |
+| Interfaces with one implementation | Mock at boundaries only |
+| AbstractFactoryFactoryBean | Just instantiate the thing |
+| DI containers for simple graphs | Constructor injection is enough |
+| Clean Architecture for a TODO app | Match layers to actual complexity |
+| DDD tactics without strategic design | Aggregates need bounded contexts |
+| Hexagonal ports with one adapter | Just call the database |
+| CQRS when reads = writes | Add when they diverge |
+| "We might swap databases" | You won't; rewrite if you do |
+| "Multi-tenant someday" | Build it when you have tenant #2 |
+| "Microservices for team scale" | Helps at 50+ engineers, not 4 |
+
+## Success Criteria
+
+Your architecture is right-sized when:
+
+1. **You can draw it** - dependency graph fits on a whiteboard
+2. **You can explain it** - new team member understands data flow in 30 minutes
+3. **You can change it** - adding a feature touches 1-3 modules, not 10
+4. **You can delete it** - removing a component needs no archaeology
+5. **You can debug it** - tracing a request takes minutes, not hours
+6. **It matches your team** - deployable units ≤ number of teams
+
+## When the Simple Solution Isn't Enough
+
+If the complexity checklist says "yes, scale is real", see [scaling-checklist.md](scaling-checklist.md) for concrete techniques covering caching, async processing, partitioning, horizontal scaling, and multi-region.
+
+## Iterative Architecture
+
+Architecture is discovered, not designed upfront:
+
+1. **Start obvious** - group by domain, not by technical layer
+2. **Let hotspots emerge** - monitor which modules change together
+3. **Extract when painful** - split only when the current form causes measurable problems
+4. **Document decisions** - record why boundaries exist so future you knows what's load-bearing
+
+Every senior engineer has a graveyard of over-engineered systems they regret. Learn from their pain. Build boring systems that work.

package/.agent/skills/mindforge-system-architecture/examples.md

@@ -0,0 +1,120 @@
+# Architecture Examples
+
+Concrete good/bad examples for each core principle in SKILL.md.
+
+---
+
+## Boundaries at Real Differences
+
+**Good** - Meaningful boundary:
+```
+# Users and Billing are separate bounded contexts
+# - Different teams own them
+# - Different change cadences (users: weekly, billing: quarterly)
+# - Different compliance requirements
+
+src/
+  users/           # User management domain
+    models.py
+    services.py
+    api.py
+  billing/         # Billing domain
+    models.py
+    services.py
+    api.py
+  shared/          # Truly shared utilities
+    auth.py
+```
+
+**Bad** - Ceremony without purpose:
+```
+# UserService → UserRepository → UserRepositoryImpl
+# ...when you'll never swap the database
+
+src/
+  interfaces/
+    IUserRepository.py      # One implementation exists
+  repositories/
+    UserRepositoryImpl.py   # Wraps SQLAlchemy, which is already a repository
+  services/
+    UserService.py          # Just calls the repository
+```
+
+---
+
+## Dependencies Flow Inward
+
+**Good** - Clear dependency direction:
+```
+# Dependency flows inward: infrastructure → application → domain
+
+domain/           # Pure business logic, no imports from outer layers
+  order.py        # Order entity with business rules
+
+application/      # Use cases, orchestrates domain
+  place_order.py  # Imports from domain/, not infrastructure/
+
+infrastructure/   # External concerns
+  postgres.py     # Implements persistence, imports from application/
+  stripe.py       # Implements payments
+```
+
+---
+
+## Follow the Data
+
+**Good** - Obvious data flow:
+```
+Request → Validate → Transform → Store → Respond
+
+# Each step is a clear function/module:
+api/routes.py        # Request enters
+validators.py        # Validation
+transformers.py      # Business logic transformation
+repositories.py      # Storage
+serializers.py       # Response shaping
+```
+
+---
+
+## Design for Failure
+
+**Good** - Failure-aware design with compensation:
+```python
+class OrderService:
+    def place_order(self, order: Order) -> Result:
+        inventory = self.inventory.reserve(order.items)
+        if inventory.failed:
+            return Result.failure("Items unavailable", retry=False)
+
+        payment = self.payments.charge(order.total)
+        if payment.failed:
+            self.inventory.release(inventory.reservation_id)  # Compensate
+            return Result.failure("Payment failed", retry=True)
+
+        return Result.success(order)
+```
+
+---
+
+## Design for Operations
+
+**Good** - Observable architecture:
+```python
+@trace
+def handle_request(request):
+    log.info("Processing", request_id=request.id, user=request.user_id)
+    try:
+        result = process(request)
+        log.info("Completed", request_id=request.id, result=result.status)
+        return result
+    except Exception as e:
+        log.error("Failed", request_id=request.id, error=str(e),
+                  context=request.to_dict())  # Full context for replay
+        raise
+```
+
+Key elements:
+- Every request gets a correlation ID
+- Every service logs with that ID
+- Every error includes full context for reproduction

package/.agent/skills/mindforge-system-architecture/scaling-checklist.md

@@ -0,0 +1,76 @@
+# Scaling Checklist
+
+Concrete techniques for when the complexity checklist in SKILL.md confirms scale is a real problem. Apply in order - each level solves the previous level's bottleneck.
+
+---
+
+## Level 0: Optimize First
+
+Before adding infrastructure, exhaust these:
+
+- [ ] Database queries have proper indexes
+- [ ] N+1 queries eliminated
+- [ ] Connection pooling configured
+- [ ] Slow endpoints profiled and optimized
+- [ ] Static assets served via CDN
+
+## Level 1: Read-Heavy
+
+**Symptom**: Database reads are the bottleneck.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Application cache (in-memory) | Small, frequently accessed data | Stale data, memory pressure |
+| Redis/Memcached | Shared cache across instances | Network hop, cache invalidation complexity |
+| Read replicas | High read volume, slight staleness OK | Replication lag, eventual consistency |
+| CDN | Static or semi-static content | Cache invalidation delay |
+
+## Level 2: Write-Heavy
+
+**Symptom**: Database writes or processing are the bottleneck.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Async task queue (Celery, SQS) | Work can be deferred | Eventual consistency, failure handling |
+| Write-behind cache | Batch frequent writes | Data loss risk on crash |
+| Event streaming (Kafka) | Multiple consumers of same data | Operational complexity, ordering guarantees |
+| CQRS | Reads and writes have diverged significantly | Two models to maintain |
+
+## Level 3: Traffic Spikes
+
+**Symptom**: Individual instances can't handle peak load.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Horizontal scaling + load balancer | Stateless services | Session management, deploy complexity |
+| Auto-scaling | Unpredictable traffic patterns | Cold start latency, cost spikes |
+| Rate limiting | Protect against abuse/spikes | Legitimate users may be throttled |
+| Circuit breakers | Downstream services degrade | Partial functionality during failures |
+
+## Level 4: Data Growth
+
+**Symptom**: Single database can't hold or query all the data efficiently.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Table partitioning | Time-series or naturally partitioned data | Query complexity, partition management |
+| Archival / cold storage | Old data rarely accessed | Access latency for archived data |
+| Database sharding | Partitioning insufficient, clear shard key exists | Cross-shard queries, operational burden |
+| Search index (Elasticsearch) | Full-text or complex queries on large datasets | Index lag, another system to operate |
+
+## Level 5: Multi-Region
+
+**Symptom**: Users are geographically distributed, latency matters.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| CDN + edge caching | Static/semi-static content | Cache invalidation |
+| Read replicas per region | Read-heavy, slight staleness OK | Replication lag |
+| Active-passive failover | Disaster recovery | Failover time, cost of standby |
+| Active-active multi-region | True global low-latency required | Conflict resolution, extreme complexity |
+
+---
+
+## Decision Rule
+
+Always start at Level 0. Move to the next level only when you have **measured evidence** that the current level is insufficient. Skipping levels is how you end up with Kafka for a TODO app.

package/.agent/skills/mindforge-tdd/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: tdd
+description: Strict TDD workflow (Red-Green-Refactor).
+---
+
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/.agent/skills/mindforge-tdd/deep-modules.md

@@ -0,0 +1,21 @@
+# Deep Modules in TDD
+
+Deep modules are those with complex internal logic but a simple, stable interface. In TDD, our goal is to test the **depth** of the logic through the **surface** of the interface.
+
+## Principles
+
+### 1. Test behavior, not implementation
+- Write tests against the public API of the module.
+- Avoid testing private methods or internal state directly.
+- If the internal logic is too complex to test through the public API, the module might be **too deep** or the interface **too narrow**.
+
+### 2. Isolate complexity
+- Use "Socialable Tests" for internal helper classes that are tightly coupled.
+- Use "Solitary Tests" (with mocks) for external dependencies (DB, API, etc.).
+
+### 3. Handle state transitions
+- Deep modules often manage complex state machines.
+- Use TDD to map out every valid (and invalid) state transition.
+
+## Strategy: The "Opaque Box" Approach
+Treat the module as an opaque box. Feed it inputs and verify outputs/side-effects. If the logic inside changes but the behavior remains the same, your tests should **not** break.

package/.agent/skills/mindforge-tdd/interface-design.md

@@ -0,0 +1,22 @@
+# Interface Design through TDD
+
+TDD is your best tool for designing clean, usable interfaces. By writing the test first, you are the **first consumer** of your own API.
+
+## Design Signals from Tests
+
+### "This test is too hard to setup"
+- **Signal**: Your class has too many dependencies or is doing too much (violating SRP).
+- **Fix**: Break the class into smaller, more focused components.
+
+### "I have to mock 5 things just to test one method"
+- **Signal**: Excessive coupling.
+- **Fix**: Use Dependency Injection and define clearer boundaries.
+
+### "I don't know what to name this test"
+- **Signal**: The behavior is ill-defined or the module has "Identity Crisis".
+- **Fix**: Re-evaluate the purpose of the component.
+
+## Best Practices
+- **Prefer Composition over Inheritance**: Tests are much easier to write for composed objects.
+- **Keep Interfaces Narrow**: Only expose what is absolutely necessary for the consumer (and the test).
+- **Return Meaningful Values**: Avoid `void` where possible; returning results makes assertion-based testing natural.

package/.agent/skills/mindforge-tdd/mocking.md

@@ -0,0 +1,24 @@
+# Mocking Strategies
+
+Mocking is a double-edged sword. Used correctly, it isolates your code. Used poorly, it creates brittle tests that break with every refactor.
+
+## When to Mock
+- **External Systems**: Databases, File Systems, Network APIs, 3rd-party libraries.
+- **Non-Deterministic Logic**: Time (`Date.now()`), Random numbers, GUID generation.
+- **Expensive Operations**: Heavy computations or long-running tasks that would slow down the TDD loop.
+
+## What NOT to Mock
+- **Value Objects**: Objects that only hold data.
+- **Internal Helpers**: If a helper is part of the module's logic, let the test exercise it ("Socialable Testing").
+- **Language Features**: Don't mock standard library functions unless necessary for environment isolation.
+
+## The Mocking Traps
+
+### 1. The "Mirror" Trap
+- **Problem**: Mocking internal calls so closely that the test just mirrors the implementation code.
+- **Result**: You can't refactor without breaking the test.
+- **Fix**: Assert on final outcomes or side-effects, not inner method calls.
+
+### 2. The "Over-Mocking" Trap
+- **Problem**: Mocking so many things that you aren't actually testing your code.
+- **Fix**: Use **Fakes** (real implementations of interfaces, e.g., `InMemoryDatabase`) over Mocks where possible.

package/.agent/skills/mindforge-tdd/refactoring.md

@@ -0,0 +1,21 @@
+# Refactoring with Confidence
+
+Step 3 of the TDD loop is **Refactor**. This is where we move from "working code" to "clean code".
+
+## The Refactoring Workflow
+1. **Ensure tests are Green**: Never refactor while tests are failing.
+2. **Make small changes**: One variable rename, one function extraction, or one pattern application.
+3. **Run tests after EVERY change**: If they turn red, undo immediately.
+4. **Repeat** until the code is clean.
+
+## Refactoring-Safe Tests
+Tests that facilitate refactoring have the following traits:
+- **Implementation Agnostic**: They don't care *how* the result is calculated.
+- **Explicit**: They clearly state the business rule being protected.
+- **Fast**: They run in milliseconds, allowing for frequent execution.
+
+## Signs You Need to Refactor
+- Duplicated code logic.
+- Long methods (> 20 lines).
+- Large classes with multiple responsibilities.
+- Hard-coded values that should be configuration.

package/.agent/skills/mindforge-tdd/tests.md

@@ -0,0 +1,28 @@
+# Writing Effective TDD Tests
+
+Your tests are the specification for your system. Treat them as first-class citizens.
+
+## The Test Anatomy: AAA
+
+- **Arrange**: Set up the environment, dependencies, and inputs.
+- **Act**: Call the method/function being tested.
+- **Assert**: Verify the result or state change.
+
+## High-Quality TDD Tests
+
+### 1. Single Responsibility
+Each test should verify exactly **one** requirement. If a test has "and" in its name, it's likely two tests.
+
+### 2. Descriptive Naming
+Use the `should ... when ...` pattern.
+- ✅ `should_calculate_discount_when_user_is_premium`
+- ❌ `test_discount_logic_1`
+
+### 3. Avoid Logic in Tests
+If your test has `if` statements or `for` loops, it's too complex. Tests should be straightforward declarations of expected behavior.
+
+### 4. Zero Watermarks
+Ensure your tests clean up after themselves (e.g., deleting temporary files or resetting mocks) to avoid "leaky state" affecting other tests.
+
+## Running Tests
+Always keep your test runner in "watch mode" during TDD. The feedback loop must be near-instant.

package/.agent/workflows/mindforge-plan-phase.md

@@ -34,7 +34,7 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`, `--reviews`, `--text`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`, `--reviews`, `--ads`, `--text`).
 
 Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for Claude Code remote sessions (`/rc` mode) where TUI menus don't work through the the agent App.
 
@@ -457,6 +457,8 @@ Proceed to Step 8 only if user selects 2 or 3.
 
 ## 8. Spawn mindforge-planner Agent
 
+**Skip if:** `--ads` flag is present. Proceed to Step 8.5.
+
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -550,6 +552,33 @@ Task(
 )
 ```
 
+## 8.5. Adversarial Decision Synthesis (ADS)
+
+**Skip if:** No `--ads` flag.
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MindForge ► ADS SYNTHESIS LOOP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning Blue-Team Architect...
+◆ Spawning Red-Team Auditor...
+◆ Spawning Gold-Team Synthesizer (SOUL Scorer)...
+```
+
+### Call ADS Engine
+
+Invoke the ADS orchestrator to perform the cross-model synthesis loop:
+
+```bash
+node "bin/review/ads-engine.js" --phase "${PHASE}" --output-dir "${PHASE_DIR}"
+```
+
+The ADS engine handles the 3-model logic, SOUL scoring, and ADR generation. Once complete, it will have written the finalized `PLAN.md` to the phase directory.
+
+Continue to Step 9.
+
 ## 9. Handle Planner Return
 
 - **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.

package/.agent/workflows/mindforge:architecture.md

@@ -0,0 +1,40 @@
+---
+description: Design systems with appropriate complexity - no more, no less.
+---
+# 🏗️ /mindforge:architecture
+
+<instruction>
+Architect robust systems with clear boundaries, explicit trade-offs, and justified complexity using the MindForge System Architecture framework.
+</instruction>
+
+<context>
+Follow the architectural governance defined in [.agent/skills/mindforge-system-architecture/SKILL.md](.agent/skills/mindforge-system-architecture/SKILL.md).
+</context>
+
+<rules>
+- **Justify Complexity**: Every architectural addition must solve a documented problem.
+- **Define Boundaries**: Ensure clear separation of concerns between services/modules.
+- **Traceability**: All decisions must be mapped to project requirements.
+- **Scale-Awareness**: Design for the next order of magnitude, but implement for the current one.
+</rules>
+
+<process>
+1.  **Constraint Analysis**: Clarify scale, team size, and system lifespan.
+2.  **Domain Mapping**: Identify core entities and their relationships.
+3.  **Data Flow Design**: Map end-to-end flows and state transitions.
+4.  **Complexity Audit**: Run the [Scaling Checklist](.agent/skills/mindforge-system-architecture/scaling-checklist.md) to eliminate over-engineering.
+5.  **Trade-off Matrix**: Document selected approach vs. alternatives with pros/cons.
+</process>
+
+<supporting_documents>
+- [Architecture Examples](.agent/skills/mindforge-system-architecture/examples.md)
+- [Complexity Checklist](.agent/skills/mindforge-system-architecture/scaling-checklist.md)
+</supporting_documents>
+
+<output_format>
+Produce an `ARCHITECTURE.md` draft or update containing:
+- Executive Summary
+- Component/Service Diagram (Mermaid)
+- Data Flow Overview
+- Trade-off Analysis
+</output_format>