mindforge-cc 8.2.0 → 10.0.0

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

@@ -1,120 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# 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

@@ -1,112 +0,0 @@
----
-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

@@ -1,21 +0,0 @@
-# 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

@@ -1,22 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,28 +0,0 @@
-# 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.