@ai-content-space/loopx 0.2.9 → 0.2.10

package/skills/architecture-designer/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: architecture-designer
+description: "Applies loopx architecture discipline for system boundaries, ADRs, NFRs, scalability, failure modes, operability, and technology tradeoffs. Not for replacing clarify, spec, implementation planning, code review, or workflow state transitions."
+when_to_use: "architecture-designer, architecture, system design, ADR, NFR, scalability, failure modes, technology tradeoff, 架构设计"
+license: MIT
+metadata:
+  version: "0.2.10"
+  forked_from: https://github.com/Jeffallan/claude-skills/tree/main/skills/architecture-designer
+  maintained_by: loopx
+---
+
+# Architecture Designer
+
+## loopx Boundary
+
+`architecture-designer` is a support lens, not a workflow state. Use it directly for architecture review or system design discussion, and use it from `spec`, `review`, or `final-review` when changes affect system boundaries, operational behavior, or long-lived design decisions.
+
+This skill does not replace `clarify`, `spec`, `plan-to-exec`, `review`, or `final-review`. If architecture decisions are not yet approved, produce options and route the work through `spec`.
+
+When database technology, ownership, schema, migration, or query performance is part of the architecture decision, also use `sql-style`.
+
+## When to Use
+
+Use this lens when work involves:
+
+- Defining system boundaries, service boundaries, ownership, or integration contracts.
+- Choosing between architectural patterns such as modular monolith, microservices, event-driven, layered, or hexagonal architecture.
+- Evaluating scalability, availability, latency, consistency, durability, security, operability, or cost requirements.
+- Documenting Architecture Decision Records (ADRs) for decisions that will outlive the current implementation task.
+- Reviewing failure modes, operational complexity, deployment topology, infrastructure patterns, or technology tradeoffs.
+- Selecting database or storage technology as part of a broader architecture decision.
+
+Do not use it for code-level refactoring, API shape alone, issue triage, task planning, or workflow state transitions unless those activities expose architecture decisions.
+
+## Architecture Discipline
+
+Before recommending a design, establish:
+
+1. Functional goals and excluded goals.
+2. Non-functional requirements and their priority order.
+3. Current constraints: team skills, migration limits, budget, compliance, deployment environment, and operational ownership.
+4. Data ownership, consistency needs, read/write access patterns, retention, and migration constraints.
+5. Failure modes, recovery expectations, observability needs, and operational runbooks.
+
+Treat architecture as tradeoff management. For each major decision, state the decision, alternatives considered, why the chosen option fits the constraints, and what it makes harder.
+
+## Reference Guide
+
+Load detailed guidance only when the context needs it:
+
+| Topic | Reference | Load When |
+| --- | --- | --- |
+| Architecture patterns | `references/architecture-patterns.md` | Choosing architectural style or service boundaries |
+| ADR template | `references/adr-template.md` | Recording a long-lived decision |
+| System design | `references/system-design.md` | Producing a full architecture design |
+| Database selection | `references/database-selection.md` | Comparing storage technologies |
+| NFR checklist | `references/nfr-checklist.md` | Eliciting or reviewing quality attributes |
+
+## Core Checks
+
+### Must Cover
+
+- System boundaries and ownership.
+- Functional and non-functional requirements.
+- Architecture options and explicit tradeoffs.
+- Data model, storage, consistency, and migration implications when relevant.
+- Failure modes, degradation behavior, backup/restore, and recovery path.
+- Security, privacy, compliance, and access control concerns.
+- Observability, deployment, operability, and maintenance cost.
+- Risks, mitigations, and open questions.
+
+### Avoid
+
+- Choosing technology before requirements and constraints are clear.
+- Over-engineering for hypothetical scale.
+- Ignoring operational cost or team ownership.
+- Treating diagrams as proof of a good design.
+- Hiding tradeoffs behind generic "scalable" or "cloud-native" claims.
+- Finalizing unapproved architecture decisions outside the `spec` flow.
+
+## Output Shape
+
+For architecture discussion or review, produce the smallest useful artifact:
+
+1. Requirements and constraints summary.
+2. Options considered.
+3. Recommended architecture with a concise rationale.
+4. Major tradeoffs and rejected alternatives.
+5. Failure modes, operability concerns, and NFR coverage.
+6. ADR drafts for decisions that should be preserved.
+7. Open questions or decisions that must route through `spec`.
+
+Use Mermaid diagrams when they clarify component boundaries, data flow, ownership, or deployment topology.
+
+### ADR Skeleton
+
+```markdown
+# ADR-000: Decision Title
+
+## Status
+Proposed
+
+## Context
+What problem, constraints, requirements, and forces make this decision necessary?
+
+## Decision
+What option is selected?
+
+## Alternatives Considered
+- Option A: benefits, costs, and why rejected.
+- Option B: benefits, costs, and why rejected.
+
+## Consequences
+- Positive outcomes.
+- Negative outcomes.
+- Follow-up work, migration needs, or monitoring obligations.
+```

package/skills/architecture-designer/references/adr-template.md

@@ -0,0 +1,116 @@
+# ADR Template
+
+## ADR Format
+
+```markdown
+# ADR-{number}: {Title}
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[Describe the situation and forces at play. What is the problem?
+What constraints exist? What are we trying to achieve?]
+
+## Decision
+[State the decision clearly. What are we going to do?]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Neutral
+- [Side effect that is neither good nor bad]
+
+## Alternatives Considered
+[What other options were evaluated and why were they rejected?]
+
+## References
+- [Link to relevant documentation]
+- [Link to discussion/RFC]
+```
+
+## Example: Database Selection
+
+```markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+Accepted
+
+## Context
+We need a relational database for our e-commerce platform that:
+- Handles complex transactions with strong consistency
+- Supports JSON for flexible product attributes
+- Scales to millions of products and orders
+- Works well with our existing Python/Node stack
+
+Team has experience with PostgreSQL and MySQL.
+Budget allows for managed database service.
+
+## Decision
+Use PostgreSQL as the primary database, hosted on AWS RDS.
+
+## Consequences
+
+### Positive
+- ACID compliance for financial transactions
+- Rich feature set (JSON, full-text search, CTEs)
+- Strong community and tooling
+- Excellent performance with proper indexing
+- Free and open source
+
+### Negative
+- Vertical scaling has limits (addressed with read replicas)
+- Requires DBA expertise for optimization
+- AWS RDS costs for high availability
+
+### Neutral
+- Team will need to learn PostgreSQL-specific features
+- Migration from current SQLite dev database needed
+
+## Alternatives Considered
+
+**MySQL**
+- Rejected: Less feature-rich for JSON operations
+- Considered: Similar cost, familiar to team
+
+**MongoDB**
+- Rejected: Relational data model needed for orders/inventory
+- Considered: Great for product catalog flexibility
+
+**CockroachDB**
+- Rejected: Higher cost, team unfamiliar
+- Considered: Better horizontal scaling
+
+## References
+- https://www.postgresql.org/docs/current/
+- Internal RFC: Database Selection for E-commerce Platform
+```
+
+## ADR Naming Convention
+
+```
+docs/
+└── adr/
+    ├── 0001-use-postgresql-database.md
+    ├── 0002-adopt-microservices.md
+    ├── 0003-implement-event-sourcing.md
+    └── README.md
+```
+
+## Quick Reference
+
+| Section | Purpose | Key Question |
+|---------|---------|--------------|
+| Status | Current state | Is this active? |
+| Context | Background | Why are we deciding? |
+| Decision | The choice | What did we choose? |
+| Consequences | Impact | What happens now? |
+| Alternatives | Options | What else was considered? |

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

@@ -0,0 +1,346 @@
+# 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 |
+| **Hexagonal** | Testability, port swapping | Any | Clean boundaries; more indirection |
+| **CQRS** | Read-heavy, complex queries | 10+ | Optimized reads; eventual consistency |
+
+## 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
+
+## Modular Monolith
+
+```
+┌───────────────────────────────────────────────┐
+│                 Application                    │
+│  ┌───────────┐  ┌───────────┐  ┌───────────┐ │
+│  │  Users    │  │  Orders   │  │ Products  │ │
+│  │  Module   │  │  Module   │  │  Module   │ │
+│  │ ┌───────┐ │  │ ┌───────┐ │  │ ┌───────┐ │ │
+│  │ │ API   │ │  │ │ API   │ │  │ │ API   │ │ │
+│  │ │Domain │ │  │ │Domain │ │  │ │Domain │ │ │
+│  │ │ Data  │ │  │ │ Data  │ │  │ │ Data  │ │ │
+│  │ └───────┘ │  │ └───────┘ │  │ └───────┘ │ │
+│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘ │
+│        └───────────────┼───────────────┘       │
+│                   Shared DB                    │
+└───────────────────────────────────────────────┘
+```
+
+**When to Use**:
+- Team is growing but not ready for distributed systems
+- Domain boundaries are emerging but service split is premature
+- Need independent module development with single deployment
+- Want to prepare for future microservices extraction
+
+**Key Principles**:
+- Each module owns its domain logic, data access, and public API
+- Modules communicate through explicit interfaces, not shared tables
+- Database schema is logically separated per module (separate schemas or table prefixes)
+- Cross-module calls go through published interfaces, never direct data access
+
+**Boundary Enforcement**:
+- Compile-time: package visibility, internal packages (Go), module systems
+- Runtime: integration tests that verify no cross-module direct DB access
+- Review-time: ADR for any new cross-module dependency
+
+**Pros**: Module autonomy, single deploy, easy extraction to services later
+**Cons**: Still coupled at deploy, shared DB can leak, requires discipline
+
+**Migration Path to Microservices**:
+1. Identify the module with the most independent scaling/deployment need
+2. Extract its data into a separate database
+3. Replace in-process calls with API/event calls
+4. Deploy independently
+5. Repeat for next module
+
+## 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
+
+**Prerequisites (Do Not Skip)**:
+- Automated CI/CD pipeline per service
+- Centralized logging and distributed tracing
+- Service discovery and load balancing
+- Health checks and circuit breakers
+- Clear ownership model (one team per service)
+
+## Hexagonal Architecture (Ports and Adapters)
+
+```
+                    ┌─────────────────────────────────┐
+                    │         Application              │
+ ┌─────────┐       │  ┌───────────────────────────┐  │       ┌─────────┐
+ │  HTTP   │──Port──│  │                           │  │──Port──│Database │
+ │ Adapter │  (in)  │  │      Domain Core          │  │ (out)  │ Adapter │
+ └─────────┘       │  │                           │  │       └─────────┘
+                    │  │  - Entities               │  │
+ ┌─────────┐       │  │  - Value Objects           │  │       ┌─────────┐
+ │  gRPC   │──Port──│  │  - Domain Services        │  │──Port──│  Queue  │
+ │ Adapter │  (in)  │  │  - Repository Interfaces  │  │ (out)  │ Adapter │
+ └─────────┘       │  │                           │  │       └─────────┘
+                    │  └───────────────────────────┘  │
+ ┌─────────┐       │                                  │       ┌─────────┐
+ │  CLI    │──Port──│                                  │──Port──│  Cache  │
+ │ Adapter │  (in)  │                                  │ (out)  │ Adapter │
+ └─────────┘       └─────────────────────────────────┘       └─────────┘
+```
+
+**When to Use**:
+- Domain logic is complex and must be tested without infrastructure
+- Multiple entry points (HTTP, gRPC, CLI, events) drive the same logic
+- Infrastructure may change (swap databases, message queues, providers)
+- Long-lived system where maintainability is more important than speed-to-first-deploy
+
+**Key Principles**:
+- Domain core has zero dependencies on frameworks, databases, or transport
+- Ports are interfaces defined by the domain (what it needs, what it offers)
+- Adapters implement ports and live outside the core
+- Dependency direction always points inward (adapters depend on ports, never reverse)
+
+**Inbound Ports** (Driving): Define use cases the outside world can trigger
+```
+type OrderService interface {
+    PlaceOrder(ctx context.Context, cmd PlaceOrderCmd) (OrderID, error)
+    CancelOrder(ctx context.Context, id OrderID) error
+}
+```
+
+**Outbound Ports** (Driven): Define what the domain needs from infrastructure
+```
+type OrderRepository interface {
+    Save(ctx context.Context, order *Order) error
+    FindByID(ctx context.Context, id OrderID) (*Order, error)
+}
+```
+
+**Testing Benefits**:
+- Unit test domain logic with in-memory adapters
+- Integration test adapters against real infrastructure
+- E2E test through inbound adapters against the full stack
+
+**Pros**: Testable, swappable infrastructure, clear boundaries, long-term maintainability
+**Cons**: More indirection, initial boilerplate, over-engineering risk for simple CRUD
+
+## 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 (10:1 or more)
+- Complex read queries that don't map to the write model
+- Event sourcing architecture
+- Different optimization needs for reads vs writes
+
+**CQRS + Event Sourcing Detail**:
+
+```
+Command ──▶ Aggregate ──▶ Events ──▶ Event Store
+                                         │
+                                    ┌────┴────┐
+                                    ▼         ▼
+                              ┌─────────┐ ┌─────────┐
+                              │Read DB 1│ │Read DB 2│
+                              │(search) │ │(reports)│
+                              └─────────┘ └─────────┘
+```
+
+**Event Sourcing Principles**:
+- Store events as the source of truth, not current state
+- Rebuild current state by replaying events
+- Events are immutable and append-only
+- Snapshots optimize replay for aggregates with many events
+
+**When NOT to Use CQRS**:
+- Simple CRUD with balanced read/write
+- Small team without event-driven experience
+- Strong consistency requirements everywhere (CQRS introduces eventual consistency)
+
+**Pros**: Optimized reads, audit trail, temporal queries, scalable
+**Cons**: Eventual consistency, complexity, event versioning, debugging difficulty
+
+## Saga Pattern
+
+Use Sagas to coordinate multi-service transactions without distributed locks.
+
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│ Order   │───▶│ Payment │───▶│  Stock  │───▶│Shipping │
+│ Service │    │ Service │    │ Service │    │ Service │
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+     │              │              │              │
+     ▼              ▼              ▼              ▼
+ T1: Create    T2: Charge     T3: Reserve    T4: Ship
+ Order         Payment        Stock          Package
+     │              │              │              │
+     ▼              ▼              ▼              ▼
+ C1: Cancel    C2: Refund     C3: Release    C4: Cancel
+ Order         Payment        Stock          Shipment
+```
+
+### Choreography vs Orchestration
+
+| Aspect | Choreography | Orchestration |
+|--------|-------------|---------------|
+| Coordination | Event-driven, no central control | Central orchestrator directs steps |
+| Coupling | Loose; services react to events | Orchestrator knows all participants |
+| Visibility | Hard to trace full flow | Single place shows entire flow |
+| Complexity | Grows with participant count | Grows with flow logic |
+| Best for | Simple flows (2-4 steps) | Complex flows (5+ steps, conditions) |
+
+### Choreography Example
+
+```
+OrderService publishes: OrderCreated
+  → PaymentService listens, charges, publishes: PaymentCompleted
+    → StockService listens, reserves, publishes: StockReserved
+      → ShippingService listens, ships, publishes: ShipmentCreated
+
+On failure at any step:
+  Service publishes compensation event (e.g., PaymentFailed)
+  → Upstream services listen and execute compensating transactions
+```
+
+### Orchestration Example
+
+```
+OrderSaga (orchestrator):
+  1. Call PaymentService.Charge()
+     - On success → step 2
+     - On failure → Cancel Order
+  2. Call StockService.Reserve()
+     - On success → step 3
+     - On failure → Refund Payment, Cancel Order
+  3. Call ShippingService.Ship()
+     - On success → Complete
+     - On failure → Release Stock, Refund Payment, Cancel Order
+```
+
+### Saga Design Rules
+
+- Each step must have a compensating transaction
+- Compensating transactions must be idempotent (retries are safe)
+- Design for partial failure: any step can fail at any time
+- Use timeouts with compensation for steps that may hang
+- Store saga state for recovery after crashes
+- Prefer orchestration for flows with complex branching or conditional logic
+- Prefer choreography for simple linear flows with few participants
+
+## Serverless
+
+**When to Use**:
+- Variable or unpredictable load
+- Event-driven processing (file uploads, webhooks, schedules)
+- Cost optimization for low-traffic workloads
+- Rapid prototyping without infrastructure management
+
+**Considerations**:
+- Cold start latency (100ms–3s depending on runtime and dependencies)
+- Execution time limits (15 min for AWS Lambda)
+- Stateless by design; external state in DB/cache/queue
+- Vendor lock-in risk; abstract business logic from provider APIs
+- Monitoring and debugging is harder than traditional servers
+
+## Quick Decision Guide
+
+| Requirement | Recommended Pattern |
+|-------------|---------------------|
+| Simple CRUD app | Monolith |
+| Growing startup | Modular Monolith |
+| Enterprise scale | Microservices |
+| Variable load | Serverless |
+| Async processing | Event-Driven |
+| Read-heavy | CQRS |
+| Complex domain, testability | Hexagonal |
+| Multi-service transactions | Saga |
+| Complex domain + team autonomy | Microservices + Event-Driven |
+
+## Anti-Patterns
+
+| Anti-Pattern | Symptom | Fix |
+|---|---|---|
+| Distributed Monolith | Services share DB or deploy together | Enforce data ownership, async communication |
+| Shared Nothing Fallacy | Every service duplicates infrastructure | Shared platform services (logging, auth, config) |
+| Premature Microservices | < 10 devs, unclear boundaries | Start monolith, extract when boundaries are proven |
+| CQRS Everywhere | Simple CRUD with CQRS complexity | Use CQRS only for genuinely asymmetric read/write |
+| Event Soup | Everything is an event, no clear flow | Define event categories: domain, integration, notification |
+| Saga Without Compensation | Distributed flow without rollback plan | Design compensation for every step before building |

package/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 |