@monoes/monomindcli 2.15.3 → 2.15.5

package/org-skills/architecture-designer/references/architecture-patterns.md

@@ -0,0 +1,111 @@
+# Architecture Patterns
+
+## Pattern Comparison
+
+| Pattern | Best For | Team Size | Trade-offs |
+|---------|----------|-----------|------------|
+| **Monolith** | Simple domain, small team | 1-10 | Simple deploy; hard to scale parts |
+| **Modular Monolith** | Growing complexity | 5-20 | Module boundaries; still single deploy |
+| **Microservices** | Complex domain, large org | 20+ | Independent scale; operational complexity |
+| **Serverless** | Variable load, event-driven | Any | Auto-scale; cold starts, vendor lock |
+| **Event-Driven** | Async processing | 10+ | Loose coupling; debugging complexity |
+
+## Monolith
+
+```
+┌─────────────────────────────────────┐
+│            Application              │
+│  ┌─────┐  ┌─────┐  ┌─────┐         │
+│  │Users│  │Orders│ │Products│       │
+│  └─────┘  └─────┘  └─────┘         │
+│  └──────────┬──────────────┘        │
+│          Database                    │
+└─────────────────────────────────────┘
+```
+
+**When to Use**:
+- Starting a new project
+- Small team (< 10 developers)
+- Simple domain
+- Rapid iteration needed
+
+**Pros**: Simple deployment, easy debugging, no network latency
+**Cons**: Hard to scale independently, technology locked, deployment risk
+
+## Microservices
+
+```
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│  Users   │  │  Orders  │  │ Products │
+│ Service  │  │ Service  │  │ Service  │
+└────┬─────┘  └────┬─────┘  └────┬─────┘
+     │             │             │
+┌────▼────┐  ┌────▼────┐  ┌────▼────┐
+│ User DB │  │Order DB │  │ Prod DB │
+└─────────┘  └─────────┘  └─────────┘
+```
+
+**When to Use**:
+- Large team (20+ developers)
+- Complex domain with clear boundaries
+- Different scaling requirements per service
+- Polyglot technology needs
+
+**Pros**: Independent scaling, team autonomy, fault isolation
+**Cons**: Distributed system complexity, eventual consistency, operational overhead
+
+## Event-Driven
+
+```
+┌──────────┐     ┌─────────────┐     ┌──────────┐
+│ Producer │────▶│ Message Bus │────▶│ Consumer │
+└──────────┘     │  (Kafka)    │     └──────────┘
+                 └─────────────┘
+                       │
+                       ▼
+                 ┌──────────┐
+                 │ Consumer │
+                 └──────────┘
+```
+
+**When to Use**:
+- Async processing required
+- Loose coupling between services
+- Event sourcing needs
+- High throughput messaging
+
+**Pros**: Decoupled services, scalable, audit trail
+**Cons**: Eventual consistency, debugging complexity, message ordering
+
+## CQRS (Command Query Responsibility Segregation)
+
+```
+┌─────────┐         ┌─────────────┐
+│ Commands│────────▶│ Write Model │──┐
+└─────────┘         └─────────────┘  │
+                                     ▼
+                              ┌──────────┐
+                              │  Events  │
+                              └──────────┘
+                                     │
+┌─────────┐         ┌─────────────┐  │
+│ Queries │◀────────│ Read Model  │◀─┘
+└─────────┘         └─────────────┘
+```
+
+**When to Use**:
+- Read/write ratio heavily skewed
+- Complex read queries
+- Event sourcing architecture
+- Different optimization needs
+
+## Quick Reference
+
+| Requirement | Recommended Pattern |
+|-------------|---------------------|
+| Simple CRUD app | Monolith |
+| Growing startup | Modular Monolith |
+| Enterprise scale | Microservices |
+| Variable load | Serverless |
+| Async processing | Event-Driven |
+| Read-heavy | CQRS |

package/org-skills/architecture-designer/references/database-selection.md

@@ -0,0 +1,102 @@
+# Database Selection
+
+## Database Types
+
+| Type | Examples | Best For |
+|------|----------|----------|
+| **Relational** | PostgreSQL, MySQL | Transactions, complex queries, relationships |
+| **Document** | MongoDB, Firestore | Flexible schemas, rapid iteration |
+| **Key-Value** | Redis, DynamoDB | Caching, sessions, high throughput |
+| **Time-Series** | TimescaleDB, InfluxDB | Metrics, IoT, analytics |
+| **Graph** | Neo4j, Neptune | Relationships, social networks |
+| **Search** | Elasticsearch, Meilisearch | Full-text search, logs |
+
+## Relational (PostgreSQL, MySQL)
+
+```
+Best For:
+- Financial transactions (ACID compliance)
+- Complex queries with joins
+- Data integrity requirements
+- Structured, predictable schemas
+
+When to Avoid:
+- Highly variable schemas
+- Massive horizontal scaling needs
+- Simple key-value access patterns
+```
+
+| Feature | PostgreSQL | MySQL |
+|---------|------------|-------|
+| JSON support | Excellent (JSONB) | Good (JSON) |
+| Full-text search | Built-in | Basic |
+| Extensions | Rich ecosystem | Limited |
+| Replication | Streaming, logical | Statement, row-based |
+
+## Document (MongoDB, Firestore)
+
+```
+Best For:
+- Flexible, evolving schemas
+- Hierarchical data (nested documents)
+- Rapid prototyping
+- Content management
+
+When to Avoid:
+- Complex transactions across documents
+- Heavy relational queries
+- Strict schema requirements
+```
+
+## Key-Value (Redis, DynamoDB)
+
+```
+Best For:
+- Session storage
+- Caching layer
+- Real-time leaderboards
+- Rate limiting counters
+
+When to Avoid:
+- Complex queries
+- Relational data
+- Large value sizes (>1MB)
+```
+
+## Time-Series (TimescaleDB, InfluxDB)
+
+```
+Best For:
+- Metrics and monitoring
+- IoT sensor data
+- Financial tick data
+- Event logging with timestamps
+
+When to Avoid:
+- Frequent updates to existing records
+- Complex relational queries
+- Non-time-based access patterns
+```
+
+## Decision Matrix
+
+| Requirement | Recommended |
+|-------------|-------------|
+| ACID transactions | PostgreSQL, MySQL |
+| Flexible schema | MongoDB, Firestore |
+| High-speed caching | Redis |
+| Time-series data | TimescaleDB, InfluxDB |
+| Social relationships | Neo4j |
+| Full-text search | Elasticsearch |
+| Serverless scale | DynamoDB, Firestore |
+
+## Quick Reference
+
+| Question | If Yes → |
+|----------|----------|
+| Need ACID transactions? | Relational (PostgreSQL) |
+| Schema changes frequently? | Document (MongoDB) |
+| Sub-millisecond reads? | Key-Value (Redis) |
+| Time-based queries? | Time-Series |
+| Traversing relationships? | Graph (Neo4j) |
+| Full-text search primary? | Elasticsearch |

package/org-skills/architecture-designer/references/nfr-checklist.md

@@ -0,0 +1,112 @@
+# Non-Functional Requirements Checklist
+
+## NFR Categories
+
+### Scalability
+
+| Question | Common Targets |
+|----------|----------------|
+| Expected concurrent users? | 100 / 1K / 10K / 100K |
+| Requests per second? | 10 / 100 / 1000 / 10000 |
+| Data volume? | GB / TB / PB |
+| Growth rate? | 10% / 50% / 100% per year |
+| Peak vs average load? | 2x / 5x / 10x |
+
+### Performance
+
+| Question | Common Targets |
+|----------|----------------|
+| API response time? | < 100ms / 200ms / 500ms p95 |
+| Page load time? | < 1s / 2s / 3s |
+| Database query time? | < 10ms / 50ms / 100ms |
+| Batch processing throughput? | 1K / 10K / 100K records/hour |
+
+### Availability
+
+| Target | Downtime/Year | Use Case |
+|--------|---------------|----------|
+| 99% | 3.65 days | Internal tools |
+| 99.9% | 8.76 hours | Business apps |
+| 99.95% | 4.38 hours | E-commerce |
+| 99.99% | 52.6 minutes | Financial systems |
+| 99.999% | 5.26 minutes | Life-critical |
+
+### Security
+
+| Question | Considerations |
+|----------|----------------|
+| Authentication required? | JWT, OAuth, SAML, MFA |
+| Authorization model? | RBAC, ABAC, ACL |
+| Data sensitivity? | Public, internal, confidential, PII |
+| Compliance requirements? | GDPR, HIPAA, PCI DSS, SOC 2 |
+| Encryption needs? | At rest, in transit, end-to-end |
+
+### Reliability
+
+| Question | Considerations |
+|----------|----------------|
+| Acceptable data loss? | RPO: 0 / 1hr / 24hr |
+| Recovery time target? | RTO: 1hr / 4hr / 24hr |
+| Backup frequency? | Real-time / hourly / daily |
+| Disaster recovery? | Single region / multi-region |
+
+### Maintainability
+
+| Question | Considerations |
+|----------|----------------|
+| Deployment frequency? | Daily / weekly / monthly |
+| Deployment strategy? | Blue-green, canary, rolling |
+| Monitoring requirements? | Logs, metrics, traces, alerts |
+| On-call requirements? | 24/7, business hours |
+
+### Cost
+
+| Question | Considerations |
+|----------|----------------|
+| Infrastructure budget? | $/month, $/user, $/request |
+| Operational budget? | FTE for maintenance |
+| Cost optimization? | Reserved instances, spot instances |
+| Cost alerts? | Thresholds for notification |
+
+## Template
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+- API response time: < 200ms p95
+- Page load time: < 2s
+- Database query time: < 50ms
+
+### Scalability
+- Concurrent users: 10,000
+- Requests per second: 1,000
+- Data volume: 1TB
+
+### Availability
+- Target: 99.9% (8.76 hours/year downtime)
+- RPO: 1 hour
+- RTO: 4 hours
+
+### Security
+- Authentication: JWT with refresh tokens
+- Authorization: Role-based (admin, user, guest)
+- Compliance: GDPR, SOC 2
+
+### Observability
+- Logging: Structured JSON to ELK
+- Metrics: Prometheus + Grafana
+- Tracing: OpenTelemetry
+- Alerts: PagerDuty integration
+```
+
+## Quick Reference
+
+| Category | Key Metric |
+|----------|------------|
+| Performance | Response time (p95) |
+| Scalability | Concurrent users, RPS |
+| Availability | Uptime percentage |
+| Reliability | RPO, RTO |
+| Security | Compliance requirements |
+| Cost | $/month budget |

package/org-skills/architecture-designer/references/system-design.md

@@ -0,0 +1,100 @@
+# System Design Template
+
+## Design Template
+
+```markdown
+# System: {System Name}
+
+## Requirements
+
+### Functional
+- [What the system must do]
+- [Core features and capabilities]
+
+### Non-Functional
+- **Performance**: Response time < 200ms p95
+- **Availability**: 99.9% uptime (8.76 hours downtime/year)
+- **Scalability**: Support 10,000 concurrent users
+- **Security**: PCI DSS compliance required
+
+### Constraints
+- Budget: $X/month for infrastructure
+- Timeline: MVP in 3 months
+- Team: 5 backend, 3 frontend engineers
+
+## High-Level Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│  API Gateway │────▶│  Service    │
+│   (Web)     │     │   (Kong)    │     │  (Node.js)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │                   │
+                           ▼                   ▼
+                    ┌─────────────┐     ┌─────────────┐
+                    │    Auth     │     │  Database   │
+                    │  (Auth0)    │     │ (PostgreSQL)│
+                    └─────────────┘     └─────────────┘
+```
+
+## Component Details
+
+### API Layer
+- Technology: Node.js with Express/NestJS
+- Responsibilities: Request routing, validation, auth
+- Scaling: Horizontal via load balancer
+
+### Data Layer
+- Primary: PostgreSQL (transactions, relationships)
+- Cache: Redis (sessions, hot data)
+- Storage: S3 (files, images)
+
+### External Services
+- Auth: Auth0 (SSO, MFA)
+- Email: SendGrid (transactional)
+- Monitoring: Datadog (APM, logs)
+
+## Key Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| PostgreSQL over MongoDB | Relational data, ACID needed |
+| Redis for caching | Sub-ms latency required |
+| Auth0 over custom | Reduce security risk |
+
+## Scaling Strategy
+
+### Current (MVP)
+- Single region deployment
+- 2 API instances behind ALB
+- Single RDS instance
+
+### Future (10x growth)
+- Multi-region with CDN
+- Auto-scaling API (2-10 instances)
+- RDS read replicas
+
+## Security Considerations
+- All traffic over TLS 1.3
+- JWT tokens with 15-min expiry
+- Rate limiting: 100 req/min per user
+- WAF for common attacks
+
+## Failure Modes
+
+| Failure | Impact | Mitigation |
+|---------|--------|------------|
+| DB down | Full outage | Multi-AZ failover |
+| Cache down | Degraded perf | Fallback to DB |
+| Auth down | No new logins | Cache valid tokens |
+```
+
+## Quick Reference
+
+| Section | Key Questions |
+|---------|---------------|
+| Requirements | What must it do? How well? |
+| Architecture | What components? How connected? |
+| Decisions | Why these choices? |
+| Scaling | How to grow? |
+| Failures | What can break? How to recover? |

package/org-skills/architecture-patterns/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seth Hobson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/org-skills/architecture-patterns/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: architecture-patterns
+description: "Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use this skill when designing clean architecture for a new microservice, when refactoring a monolith to use bounded contexts, when implementing hexagonal or onion architecture patterns, or when debugging dependency cycles between application layers."
+tags: ["engineering","backend"]
+tools: ["monograph_query","monograph_context","monograph_impact","monograph_suggest"]
+license: MIT
+source: https://github.com/wshobson/agents
+source_path: "plugins/backend-development/skills/architecture-patterns"
+source_commit: 4236bb91f8395b0435f1d8b8baf9e8e4c69a8620
+---
+# Architecture Patterns
+
+Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems.
+
+**Given:** a service boundary or module to architect.
+**Produces:** layered structure with clear dependency rules, interface definitions, and test boundaries.
+
+## When to Use This Skill
+
+- Designing new backend services or microservices from scratch
+- Refactoring monolithic applications where business logic is entangled with ORM models or HTTP concerns
+- Establishing bounded contexts before splitting a system into services
+- Debugging dependency cycles where infrastructure code bleeds into the domain layer
+- Creating testable codebases where use-case tests do not require a running database
+- Implementing domain-driven design tactical patterns (aggregates, value objects, domain events)
+
+## Core Concepts
+
+### 1. Clean Architecture (Uncle Bob)
+
+**Layers (dependency flows inward):**
+
+- **Entities**: Core business models, no framework imports
+- **Use Cases**: Application business rules, orchestrate entities
+- **Interface Adapters**: Controllers, presenters, gateways — translate between use cases and external formats
+- **Frameworks & Drivers**: UI, database, external services — all at the outermost ring
+
+**Key Principles:**
+
+- Dependencies point inward only; inner layers know nothing about outer layers
+- Business logic is independent of frameworks, databases, and delivery mechanisms
+- Every layer boundary is crossed via an abstract interface
+- Testable without UI, database, or external services
+
+### 2. Hexagonal Architecture (Ports and Adapters)
+
+**Components:**
+
+- **Domain Core**: Business logic lives here, framework-free
+- **Ports**: Abstract interfaces that define how the core interacts with the outside world (driving and driven)
+- **Adapters**: Concrete implementations of ports (PostgreSQL adapter, Stripe adapter, REST adapter)
+
+**Benefits:**
+
+- Swap implementations without touching the core (e.g., replace PostgreSQL with DynamoDB)
+- Use in-memory adapters in tests — no Docker required
+- Technology decisions deferred to the edges
+
+### 3. Domain-Driven Design (DDD)
+
+**Strategic Patterns:**
+
+- **Bounded Contexts**: Isolate a coherent model for one subdomain; avoid sharing a single model across the whole system
+- **Context Mapping**: Define how contexts relate (Anti-Corruption Layer, Shared Kernel, Open Host Service)
+- **Ubiquitous Language**: Every term in code matches the term used by domain experts
+
+**Tactical Patterns:**
+
+- **Entities**: Objects with stable identity that change over time
+- **Value Objects**: Immutable objects identified by their attributes (Email, Money, Address)
+- **Aggregates**: Consistency boundaries; only the root is accessible from outside
+- **Repositories**: Persist and reconstitute aggregates; abstract over the storage mechanism
+- **Domain Events**: Capture things that happened inside the domain; used for cross-aggregate coordination
+
+## Detailed patterns and worked examples
+
+Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
+
+## Testing — In-Memory Adapters
+
+The hallmark of correctly applied Clean Architecture is that every use case can be exercised in a plain unit test with no real database, no Docker, and no network:
+
+```python
+# tests/unit/test_create_user.py
+import asyncio
+from typing import Dict, Optional
+from domain.entities.user import User
+from domain.interfaces.user_repository import IUserRepository
+from use_cases.create_user import CreateUserUseCase, CreateUserRequest
+
+
+class InMemoryUserRepository(IUserRepository):
+    def __init__(self):
+        self._store: Dict[str, User] = {}
+
+    async def find_by_id(self, user_id: str) -> Optional[User]:
+        return self._store.get(user_id)
+
+    async def find_by_email(self, email: str) -> Optional[User]:
+        return next((u for u in self._store.values() if u.email == email), None)
+
+    async def save(self, user: User) -> User:
+        self._store[user.id] = user
+        return user
+
+    async def delete(self, user_id: str) -> bool:
+        return self._store.pop(user_id, None) is not None
+
+
+async def test_create_user_succeeds():
+    repo = InMemoryUserRepository()
+    use_case = CreateUserUseCase(user_repository=repo)
+
+    response = await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice"))
+
+    assert response.success
+    assert response.user.email == "alice@example.com"
+    assert response.user.id is not None
+
+
+async def test_duplicate_email_rejected():
+    repo = InMemoryUserRepository()
+    use_case = CreateUserUseCase(user_repository=repo)
+
+    await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice"))
+    response = await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice2"))
+
+    assert not response.success
+    assert "already exists" in response.error
+```
+
+## Troubleshooting
+
+### Use case tests require a running database
+
+Business logic has leaked into the infrastructure layer. Move all database calls behind an `IRepository` interface and inject an in-memory implementation in tests (see Testing section above). The use case constructor must accept the abstract port, not the concrete class.
+
+### Circular imports between layers
+
+A common symptom is `ImportError: cannot import name X` between `use_cases` and `adapters`. This happens when a use case imports a concrete adapter class instead of the abstract port. Enforce the rule: `use_cases/` imports only from `domain/` (entities and interfaces). It must never import from `adapters/` or `infrastructure/`.
+
+### Framework decorators appearing in domain entities
+
+If SQLAlchemy `Column()` or Pydantic `Field()` annotations appear on domain entities, the entity is no longer pure. Create a separate ORM model in `adapters/repositories/` and map to/from the domain entity in the repository's `_to_entity()` method.
+
+### All logic ending up in controllers
+
+When the controller grows beyond HTTP parsing and response formatting, extract the logic into a use case class. A controller method should do three things only: parse the request, call a use case, map the response.
+
+### Value objects raising errors too late
+
+Validate invariants in `__post_init__` (Python) or the constructor so an invalid `Email` or `Money` cannot be constructed at all. This surfaces bad data at the boundary, not deep inside business logic.
+
+### Context bleed across bounded contexts
+
+If the `Order` context is importing `User` entities from the `Identity` context, introduce an Anti-Corruption Layer. The `Order` context should hold its own lightweight `CustomerId` value object and only call the `Identity` context through an explicit interface.
+
+## Advanced Patterns
+
+For detailed DDD bounded context mapping, full multi-service project trees, Anti-Corruption Layer implementations, and Onion Architecture comparisons, see:
+
+- [`references/advanced-patterns.md`](references/advanced-patterns.md)
+
+## Related Skills
+
+- `microservices-patterns` — Apply these architecture patterns when decomposing a monolith into services
+- `cqrs-implementation` — Use Clean Architecture as the structural foundation for CQRS command/query separation
+- `saga-orchestration` — Sagas require well-defined aggregate boundaries, which DDD tactical patterns provide
+- `event-store-design` — Domain events produced by aggregates feed directly into an event store