@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/architecture-decision-records/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: architecture-decision-records
+description: "Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes."
+tags: ["engineering","writing"]
+tools: ["monograph_query","monograph_context"]
+license: MIT
+source: https://github.com/wshobson/agents
+source_path: "plugins/documentation-generation/skills/architecture-decision-records"
+source_commit: 4236bb91f8395b0435f1d8b8baf9e8e4c69a8620
+---
+# Architecture Decision Records
+
+Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
+
+## When to Use This Skill
+
+- Making significant architectural decisions
+- Documenting technology choices
+- Recording design trade-offs
+- Onboarding new team members
+- Reviewing historical decisions
+- Establishing decision-making processes
+
+## Core Concepts
+
+### 1. What is an ADR?
+
+An Architecture Decision Record captures:
+
+- **Context**: Why we needed to make a decision
+- **Decision**: What we decided
+- **Consequences**: What happens as a result
+
+### 2. When to Write an ADR
+
+| Write ADR                  | Skip ADR               |
+| -------------------------- | ---------------------- |
+| New framework adoption     | Minor version upgrades |
+| Database technology choice | Bug fixes              |
+| API design patterns        | Implementation details |
+| Security architecture      | Routine maintenance    |
+| Integration patterns       | Configuration changes  |
+
+### 3. ADR Lifecycle
+
+```
+Proposed → Accepted → Deprecated → Superseded
+              ↓
+           Rejected
+```
+
+## Templates
+
+### Template 1: Standard ADR (MADR Format)
+
+```markdown
+# ADR-0001: Use PostgreSQL as Primary Database
+
+## Status
+
+Accepted
+
+## Context
+
+We need to select a primary database for our new e-commerce platform. The system
+will handle:
+
+- ~10,000 concurrent users
+- Complex product catalog with hierarchical categories
+- Transaction processing for orders and payments
+- Full-text search for products
+- Geospatial queries for store locator
+
+The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
+compliance for financial transactions.
+
+## Decision Drivers
+
+- **Must have ACID compliance** for payment processing
+- **Must support complex queries** for reporting
+- **Should support full-text search** to reduce infrastructure complexity
+- **Should have good JSON support** for flexible product attributes
+- **Team familiarity** reduces onboarding time
+
+## Considered Options
+
+### Option 1: PostgreSQL
+
+- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
+  search, PostGIS for geospatial, team has experience
+- **Cons**: Slightly more complex replication setup than MySQL
+
+### Option 2: MySQL
+
+- **Pros**: Very familiar to team, simple replication, large community
+- **Cons**: Weaker JSON support, no built-in full-text search (need
+  Elasticsearch), no geospatial without extensions
+
+### Option 3: MongoDB
+
+- **Pros**: Flexible schema, native JSON, horizontal scaling
+- **Cons**: No ACID for multi-document transactions (at decision time),
+  team has limited experience, requires schema design discipline
+
+## Decision
+
+We will use **PostgreSQL 15** as our primary database.
+
+## Rationale
+
+PostgreSQL provides the best balance of:
+
+1. **ACID compliance** essential for e-commerce transactions
+2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
+   infrastructure complexity
+3. **Team familiarity** with SQL databases reduces learning curve
+4. **Mature ecosystem** with excellent tooling and community support
+
+The slight complexity in replication is outweighed by the reduction in
+additional services (no separate Elasticsearch needed).
+
+## Consequences
+
+### Positive
+
+- Single database handles transactions, search, and geospatial queries
+- Reduced operational complexity (fewer services to manage)
+- Strong consistency guarantees for financial data
+- Team can leverage existing SQL expertise
+
+### Negative
+
+- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
+- Vertical scaling limits may require read replicas sooner
+- Some team members need PostgreSQL-specific training
+
+### Risks
+
+- Full-text search may not scale as well as dedicated search engines
+- Mitigation: Design for potential Elasticsearch addition if needed
+
+## Implementation Notes
+
+- Use JSONB for flexible product attributes
+- Implement connection pooling with PgBouncer
+- Set up streaming replication for read replicas
+- Use pg_trgm extension for fuzzy search
+
+## Related Decisions
+
+- ADR-0002: Caching Strategy (Redis) - complements database choice
+- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
+
+## References
+
+- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
+- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
+- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`
+```
+
+### Template 2: Lightweight ADR
+
+```markdown
+# ADR-0012: Adopt TypeScript for Frontend Development
+
+**Status**: Accepted
+**Date**: 2024-01-15
+**Deciders**: @alice, @bob, @charlie
+
+## Context
+
+Our React codebase has grown to 50+ components with increasing bug reports
+related to prop type mismatches and undefined errors. PropTypes provide
+runtime-only checking.
+
+## Decision
+
+Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
+
+## Consequences
+
+**Good**: Catch type errors at compile time, better IDE support, self-documenting
+code.
+
+**Bad**: Learning curve for team, initial slowdown, build complexity increase.
+
+**Mitigations**: TypeScript training sessions, allow gradual adoption with
+`allowJs: true`.
+```
+
+### Template 3: Y-Statement Format
+
+```markdown
+# ADR-0015: API Gateway Selection
+
+In the context of **building a microservices architecture**,
+facing **the need for centralized API management, authentication, and rate limiting**,
+we decided for **Kong Gateway**
+and against **AWS API Gateway and custom Nginx solution**,
+to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
+accepting that **we need to manage Kong infrastructure ourselves**.
+```
+
+### Template 4: ADR for Deprecation
+
+```markdown
+# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL
+
+## Status
+
+Accepted (Supersedes ADR-0003)
+
+## Context
+
+ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
+needs. Since then:
+
+- MongoDB's multi-document transactions remain problematic for our use case
+- Our schema has stabilized and rarely changes
+- We now have PostgreSQL expertise from other services
+- Maintaining two databases increases operational burden
+
+## Decision
+
+Deprecate MongoDB and migrate user profiles to PostgreSQL.
+
+## Migration Plan
+
+1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
+2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
+3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
+4. **Phase 4** (Week 6): Remove MongoDB writes, decommission
+
+## Consequences
+
+### Positive
+
+- Single database technology reduces operational complexity
+- ACID transactions for user data
+- Team can focus PostgreSQL expertise
+
+### Negative
+
+- Migration effort (~4 weeks)
+- Risk of data issues during migration
+- Lose some schema flexibility
+
+## Lessons Learned
+
+Document from ADR-0003 experience:
+
+- Schema flexibility benefits were overestimated
+- Operational cost of multiple databases was underestimated
+- Consider long-term maintenance in technology decisions
+```
+
+### Template 5: Request for Comments (RFC) Style
+
+```markdown
+# RFC-0025: Adopt Event Sourcing for Order Management
+
+## Summary
+
+Propose adopting event sourcing pattern for the order management domain to
+improve auditability, enable temporal queries, and support business analytics.
+
+## Motivation
+
+Current challenges:
+
+1. Audit requirements need complete order history
+2. "What was the order state at time X?" queries are impossible
+3. Analytics team needs event stream for real-time dashboards
+4. Order state reconstruction for customer support is manual
+
+## Detailed Design
+
+### Event Store
+```
+
+OrderCreated { orderId, customerId, items[], timestamp }
+OrderItemAdded { orderId, item, timestamp }
+OrderItemRemoved { orderId, itemId, timestamp }
+PaymentReceived { orderId, amount, paymentId, timestamp }
+OrderShipped { orderId, trackingNumber, timestamp }
+
+```
+
+### Projections
+
+- **CurrentOrderState**: Materialized view for queries
+- **OrderHistory**: Complete timeline for audit
+- **DailyOrderMetrics**: Analytics aggregation
+
+### Technology
+
+- Event Store: EventStoreDB (purpose-built, handles projections)
+- Alternative considered: Kafka + custom projection service
+
+## Drawbacks
+
+- Learning curve for team
+- Increased complexity vs. CRUD
+- Need to design events carefully (immutable once stored)
+- Storage growth (events never deleted)
+
+## Alternatives
+
+1. **Audit tables**: Simpler but doesn't enable temporal queries
+2. **CDC from existing DB**: Complex, doesn't change data model
+3. **Hybrid**: Event source only for order state changes
+
+## Unresolved Questions
+
+- [ ] Event schema versioning strategy
+- [ ] Retention policy for events
+- [ ] Snapshot frequency for performance
+
+## Implementation Plan
+
+1. Prototype with single order type (2 weeks)
+2. Team training on event sourcing (1 week)
+3. Full implementation and migration (4 weeks)
+4. Monitoring and optimization (ongoing)
+
+## References
+
+- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
+- [EventStoreDB Documentation](https://www.eventstore.com/docs)
+```
+
+## ADR Management
+
+### Directory Structure
+
+```
+docs/
+├── adr/
+│   ├── README.md           # Index and guidelines
+│   ├── template.md         # Team's ADR template
+│   ├── 0001-use-postgresql.md
+│   ├── 0002-caching-strategy.md
+│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
+│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
+```
+
+### ADR Index (README.md)
+
+```markdown
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for [Project Name].
+
+## Index
+
+| ADR                                   | Title                              | Status     | Date       |
+| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
+| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
+| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
+| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
+| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |
+
+## Creating a New ADR
+
+1. Copy `template.md` to `NNNN-title-with-dashes.md`
+2. Fill in the template
+3. Submit PR for review
+4. Update this index after approval
+
+## ADR Status
+
+- **Proposed**: Under discussion
+- **Accepted**: Decision made, implementing
+- **Deprecated**: No longer relevant
+- **Superseded**: Replaced by another ADR
+- **Rejected**: Considered but not adopted
+```
+
+### Automation (adr-tools)
+
+```bash
+# Install adr-tools
+brew install adr-tools
+
+# Initialize ADR directory
+adr init docs/adr
+
+# Create new ADR
+adr new "Use PostgreSQL as Primary Database"
+
+# Supersede an ADR
+adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
+
+# Generate table of contents
+adr generate toc > docs/adr/README.md
+
+# Link related ADRs
+adr link 2 "Complements" 1 "Is complemented by"
+```
+
+## Review Process
+
+```markdown
+## ADR Review Checklist
+
+### Before Submission
+
+- [ ] Context clearly explains the problem
+- [ ] All viable options considered
+- [ ] Pros/cons balanced and honest
+- [ ] Consequences (positive and negative) documented
+- [ ] Related ADRs linked
+
+### During Review
+
+- [ ] At least 2 senior engineers reviewed
+- [ ] Affected teams consulted
+- [ ] Security implications considered
+- [ ] Cost implications documented
+- [ ] Reversibility assessed
+
+### After Acceptance
+
+- [ ] ADR index updated
+- [ ] Team notified
+- [ ] Implementation tickets created
+- [ ] Related documentation updated
+```
+
+## Best Practices
+
+### Do's
+
+- **Write ADRs early** - Before implementation starts
+- **Keep them short** - 1-2 pages maximum
+- **Be honest about trade-offs** - Include real cons
+- **Link related decisions** - Build decision graph
+- **Update status** - Deprecate when superseded
+
+### Don'ts
+
+- **Don't change accepted ADRs** - Write new ones to supersede
+- **Don't skip context** - Future readers need background
+- **Don't hide failures** - Rejected decisions are valuable
+- **Don't be vague** - Specific decisions, specific consequences
+- **Don't forget implementation** - ADR without action is waste

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

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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-designer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: architecture-designer
+description: "Use when designing new high-level system architecture, reviewing existing designs, or making architectural decisions. Invoke to create architecture diagrams, write Architecture Decision Records (ADRs), evaluate technology trade-offs, design component interactions, and plan for scalability."
+tags: ["engineering"]
+tools: ["monograph_query","monograph_context","monograph_suggest"]
+license: MIT
+source: https://github.com/Jeffallan/claude-skills
+source_path: "skills/architecture-designer"
+source_commit: 882ef55e377dbf9a4dbe496bb41ac6ccd0e555cf
+---
+# Architecture Designer
+
+Senior software architect specializing in system design, design patterns, and architectural decision-making.
+
+## Role Definition
+
+You are a principal architect with 15+ years of experience designing scalable, distributed systems. You make pragmatic trade-offs, document decisions with ADRs, and prioritize long-term maintainability.
+
+## When to Use This Skill
+
+- Designing new system architecture
+- Choosing between architectural patterns
+- Reviewing existing architecture
+- Creating Architecture Decision Records (ADRs)
+- Planning for scalability
+- Evaluating technology choices
+
+## Core Workflow
+
+1. **Understand requirements** — Gather functional, non-functional, and constraint requirements. _Verify full requirements coverage before proceeding._
+2. **Identify patterns** — Match requirements to architectural patterns (see Reference Guide).
+3. **Design** — Create architecture with trade-offs explicitly documented; produce a diagram.
+4. **Document** — Write ADRs for all key decisions.
+5. **Review** — Validate with stakeholders. _If review fails, return to step 3 with recorded feedback._
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices |
+| ADR Template | `references/adr-template.md` | Documenting decisions |
+| System Design | `references/system-design.md` | Full system design template |
+| Database Selection | `references/database-selection.md` | Choosing database technology |
+| NFR Checklist | `references/nfr-checklist.md` | Gathering non-functional requirements |
+
+## Constraints
+
+### MUST DO
+- Document all significant decisions with ADRs
+- Consider non-functional requirements explicitly
+- Evaluate trade-offs, not just benefits
+- Plan for failure modes
+- Consider operational complexity
+- Review with stakeholders before finalizing
+
+### MUST NOT DO
+- Over-engineer for hypothetical scale
+- Choose technology without evaluating alternatives
+- Ignore operational costs
+- Design without understanding requirements
+- Skip security considerations
+
+## Output Templates
+
+When designing architecture, provide:
+1. Requirements summary (functional + non-functional)
+2. High-level architecture diagram (Mermaid preferred — see example below)
+3. Key decisions with trade-offs (ADR format — see example below)
+4. Technology recommendations with rationale
+5. Risks and mitigation strategies
+
+### Architecture Diagram (Mermaid)
+
+```mermaid
+graph TD
+    Client["Client (Web/Mobile)"] --> Gateway["API Gateway"]
+    Gateway --> AuthSvc["Auth Service"]
+    Gateway --> OrderSvc["Order Service"]
+    OrderSvc --> DB[("Orders DB\n(PostgreSQL)")]
+    OrderSvc --> Queue["Message Queue\n(RabbitMQ)"]
+    Queue --> NotifySvc["Notification Service"]
+```
+
+### ADR Example
+
+```markdown
+# ADR-001: Use PostgreSQL for Order Storage
+
+## Status
+Accepted
+
+## Context
+The Order Service requires ACID-compliant transactions and complex relational queries
+across orders, line items, and customers.
+
+## Decision
+Use PostgreSQL as the primary datastore for the Order Service.
+
+## Alternatives Considered
+- **MongoDB** — flexible schema, but lacks strong ACID guarantees across documents.
+- **DynamoDB** — excellent scalability, but complex query patterns require denormalization.
+
+## Consequences
+- Positive: Strong consistency, mature tooling, complex query support.
+- Negative: Vertical scaling limits; horizontal sharding adds operational complexity.
+
+## Trade-offs
+Consistency and query flexibility are prioritised over unlimited horizontal write scalability.
+```
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/api-architecture/architecture-designer/)

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