@wipal/agent-team 1.0.0

package/.claude/skills/core/retrospect-work/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: retrospect-work
+description: |
+  Extract patterns and lessons from work sessions for continuous self-improvement.
+  Use this skill when: ending a work session, after receiving user corrections,
+  after completing a feature, after fixing a bug, at end of day/week, or when
+  user says "retrospect", "what did we learn", "update knowledge".
+  This skill MUST run before ending any significant work session.
+version: 1.0.0
+category: core
+tags:
+  - self-improvement
+  - learning
+  - knowledge-extraction
+depends_on: []
+recommends: []
+used_by:
+  - code-review
+---
+
+# Skill: Retrospect Work
+
+## Core Principle
+**Learn from every session. If you don't extract lessons, you'll repeat mistakes.**
+
+The difference between a junior and senior developer isn't just years of experience—it's how much they learn from each experience.
+
+## When to Use
+
+| Trigger | Example |
+|---------|---------|
+| End of work session | "That's all for today" |
+| User correction | "No, use X instead" |
+| Feature complete | "Done with the login page" |
+| Bug fixed | "Fixed the null pointer issue" |
+| User request | "/retrospect" or "what did we learn?" |
+
+## Hard Rules
+
+1. **NEVER auto-commit changes** - Always get user confirmation
+2. **NEVER skip after corrections** - User corrections are gold, extract lessons immediately
+3. **ALWAYS propose specific changes** - Show exactly what to add/update
+4. **ALWAYS explain WHY** - Not just what, but why it matters
+
+## Steps
+
+### Step 1: Analyze Session (30 seconds)
+Quick scan of what happened:
+- What tasks were completed?
+- What approaches were used?
+- What challenges arose?
+- Any user corrections?
+
+### Step 2: Identify Patterns
+Look for these pattern types:
+
+| Pattern Type | Signal | Action |
+|--------------|--------|--------|
+| **Success** | Worked well, felt smooth | Add to best practices |
+| **Pitfall** | Caused issues, wasted time | Add to anti-patterns |
+| **Correction** | User said "no, do X" | Extract as rule |
+| **Discovery** | Learned something new | Add to knowledge |
+
+### Step 3: Extract Lessons
+For each significant finding:
+
+```markdown
+### YYYY-MM-DD: [Lesson Title]
+**What happened:** [1-2 sentences]
+**Context:** [When/where]
+**Lesson:** [What to remember]
+**Rule:** [If applicable, rule to add]
+**Code:** (if applicable)
+```
+
+### Step 4: Propose Updates
+Show specific changes:
+
+```
+📁 Proposed Updates:
+
+knowledge.md:
++ ## Pattern: [Name]
++ [Description]
+
+lessons.md:
++ ### [Date]: [Title]
++ [Lesson content]
+
+Apply? [y/n/edit]:
+```
+
+## Common Mistakes
+
+| ❌ Mistake | ✅ Fix |
+|------------|--------|
+| Vague lessons ("be careful") | Specific rules ("always check null") |
+| Auto-committing | Always ask for confirmation |
+| Skipping after easy session | Even easy sessions have learnings |
+| Too many lessons at once | Focus on top 2-3 most impactful |
+| Only capturing failures | Capture successes too |
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════════
+🧠 RETROSPECT: [Session Topic]
+═══════════════════════════════════════════════════════════════
+
+📋 Completed:
+- [Task 1]
+- [Task 2]
+
+✅ Patterns That Worked:
+1. [Pattern] → [Why it worked]
+
+⚠️ Issues & Corrections:
+1. [Issue] → [Resolution]
+
+📝 Lessons to Capture:
+1. [Lesson] → [Rule to add]
+
+📁 Proposed Updates:
+- knowledge.md: +[pattern name]
+- lessons.md: +[lesson title]
+
+Apply these changes? [y/n]:
+═══════════════════════════════════════════════════════════════
+```
+
+## Pattern Promotion Lifecycle
+
+```
+Lesson (new finding)
+    ↓ Used 3+ times
+Pattern (reusable approach)
+    ↓ High confidence, 5+ uses
+Skill (codified process)
+    ↓ Proven reliable, 10+ uses
+Rule (hard requirement)
+```
+
+## Example
+
+**Session:** Implementing payment form
+
+```
+🧠 RETROSPECT: payment-form implementation
+
+✅ Patterns That Worked:
+1. Zod + react-hook-form → Type-safe, great DX
+
+⚠️ Issues & Corrections:
+1. User corrected: "Add loading state"
+   → Added isSubmitting state
+
+📝 Lessons to Capture:
+1. Always add loading state BEFORE async calls
+   Rule: "Loading state is not optional"
+
+📁 Proposed Updates:
+- knowledge.md: +Zod validation pattern
+- lessons.md: +Loading state lesson
+
+Apply? [y/n]:
+```
+
+## Integration
+
+- After **code-review**: Extract review patterns
+- After **debugging**: Document debugging approach
+- After **git-automation**: Commit learning updates

package/.claude/skills/domain/architecture/adr-writing/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: adr-writing
+description: |
+  Use when documenting architecture decisions. Architecture Decision Records (ADRs)
+  capture the context, decision, and consequences of important technical choices.
+version: 1.0.0
+category: documentation
+tags:
+  - adr
+  - architecture-decisions
+  - documentation
+dependencies: []
+references:
+  - references/adr-template.md
+  - references/adr-examples.md
+  - references/adr-best-practices.md
+---
+
+# ADR Writing
+
+## Core Principle
+**Document decisions, not just code. Every significant choice deserves a record.**
+
+## When to Use This Skill
+
+### Trigger Conditions
+- Making a significant architectural decision
+- Choosing between technologies
+- Changing an existing decision
+- Evaluating trade-offs
+- Need to justify a decision to stakeholders
+
+### Keywords
+- "we decided to"
+- "architecture decision"
+- "why did we choose"
+- "document this decision"
+- "ADR"
+
+## What is an ADR?
+
+An Architecture Decision Record is a short document that captures:
+1. **Context** - Why are we making this decision?
+2. **Decision** - What is the change?
+3. **Consequences** - What happens as a result?
+
+```
+ADR-001: Use PostgreSQL for Primary Database
+
+Status: Accepted
+
+Context:
+We need a relational database that supports ACID transactions...
+
+Decision:
+We will use PostgreSQL as our primary database...
+
+Consequences:
+- Team needs PostgreSQL expertise
+- We get strong consistency guarantees
+- Limited horizontal scaling compared to NoSQL...
+```
+
+## ADR Template
+
+```markdown
+# ADR-XXX: [Short Title]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-YYY]
+
+## Context
+[What is the issue that we're seeing?]
+[What is the business context?]
+[What are the constraints?]
+[What options were considered?]
+
+## Decision
+[What is the change that we're proposing/have made?]
+[Be specific and concrete.]
+
+## Consequences
+
+### Positive
+- [What becomes easier?]
+- [What benefits do we get?]
+
+### Negative
+- [What becomes harder?]
+- [What trade-offs are we making?]
+
+### Risks
+- [What could go wrong?]
+- [What mitigations exist?]
+
+## Alternatives Considered
+1. **Option A**: [Description]
+   - Pros: ...
+   - Cons: ...
+   - Why not chosen: ...
+
+2. **Option B**: [Description]
+   - Pros: ...
+   - Cons: ...
+   - Why not chosen: ...
+
+## Related Decisions
+- ADR-XXX: [Related decision]
+- ADR-YYY: [Depends on]
+
+## References
+- [Link to relevant documentation]
+- [Link to discussion]
+```
+
+## Decision Categories
+
+### When to Write an ADR
+```
+✅ Architecture decisions
+   - System structure
+   - Service boundaries
+   - Data flow patterns
+
+✅ Technology choices
+   - Frameworks
+   - Databases
+   - Cloud services
+
+✅ Security decisions
+   - Authentication approach
+   - Encryption strategy
+   - Access control model
+
+✅ Performance decisions
+   - Caching strategy
+   - Scaling approach
+   - Database sharding
+
+✅ Process decisions
+   - Deployment strategy
+   - Testing approach
+   - Code organization
+```
+
+### When NOT to Write an ADR
+```
+❌ Trivial decisions (variable naming)
+❌ Reversible decisions (temporary workaround)
+❌ Team-specific conventions (coding style)
+❌ Decisions already documented elsewhere
+```
+
+## ADR Lifecycle
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  ADR Lifecycle                        │
+├──────────────────────────────────────────────────────┤
+│                                                       │
+│   ┌──────────┐                                       │
+│   │ Proposed │ ─── Write initial ADR                 │
+│   └────┬─────┘                                       │
+│        │                                             │
+│        │ Team review, discussion                     │
+│        ▼                                             │
+│   ┌──────────┐                                       │
+│   │ Accepted │ ─── Decision is active                │
+│   └────┬─────┘                                       │
+│        │                                             │
+│        │ Context changes, better option found        │
+│        ▼                                             │
+│   ┌───────────┐                                      │
+│   │Deprecated │ ─── No longer recommended            │
+│   └─────┬─────┘     but still in use                 │
+│         │                                            │
+│         │ Replacement decision made                  │
+│         ▼                                            │
+│   ┌────────────┐                                     │
+│   │ Superseded │ ─── Replaced by new ADR             │
+│   │ by ADR-YYY │     Reference new ADR               │
+│   └────────────┘                                     │
+│                                                       │
+└──────────────────────────────────────────────────────┘
+```
+
+## Best Practices
+
+### Writing Style
+```
+DO:
+✅ Be concise (1-2 pages max)
+✅ Use active voice
+✅ Include concrete examples
+✅ Document alternatives considered
+✅ Update status over time
+✅ Link related ADRs
+✅ Include date and author
+
+DON'T:
+❌ Write lengthy documents
+❌ Use vague language
+❌ Skip alternatives
+❌ Ignore negative consequences
+❌ Leave status as "Proposed" forever
+❌ Create orphan ADRs
+```
+
+### Organization
+```
+Recommended structure:
+
+docs/
+└── architecture/
+    └── adr/
+        ├── README.md           # Index of all ADRs
+        ├── ADR-001-database.md
+        ├── ADR-002-auth.md
+        ├── ADR-003-api-design.md
+        ├── template.md
+        └── images/
+            └── ADR-001-diagram.png
+```
+
+## Rules
+
+### DO
+- ✅ Write ADR before major implementation
+- ✅ Get peer review before accepting
+- ✅ Include both pros and cons
+- ✅ Keep ADRs in version control
+- ✅ Review ADRs periodically
+- ✅ Link to supporting documentation
+
+### DON'T
+- ❌ Write ADR after the fact (unless retroactive)
+- ❌ Hide negative consequences
+- ❌ Make ADRs too long
+- ❌ Forget to update status
+- ❌ Delete old ADRs (supersede instead)
+
+## Output
+
+When writing an ADR:
+1. Create file: `docs/architecture/adr/ADR-XXX-title.md`
+2. Update ADR index
+3. Link from relevant documentation
+4. Share with team for review
+5. Update status after acceptance
+
+## Related Skills
+- `tech-selection` - Making technology choices
+- `system-design` - System design decisions
+- `architecture-patterns` - Pattern selection decisions

package/.claude/skills/domain/architecture/adr-writing/references/adr-best-practices.md

@@ -0,0 +1,257 @@
+# ADR Best Practices
+
+## Writing ADRs
+
+### 1. Start with Context
+```
+Good context explains:
+- What is the problem?
+- Why does it matter?
+- What constraints exist?
+- Who is affected?
+
+❌ Bad:
+"We decided to use Kubernetes."
+
+✅ Good:
+"Our deployment process takes 4 hours and requires 3 people.
+We deploy 5 times per week, spending 60 person-hours on deployments.
+The business needs faster time-to-market for features."
+```
+
+### 2. Be Specific in Decisions
+```
+❌ Bad:
+"We'll use microservices."
+
+✅ Good:
+"We will split the application into 5 services:
+1. User Service (authentication, profiles)
+2. Order Service (order lifecycle)
+3. Catalog Service (products, categories)
+4. Inventory Service (stock management)
+5. Notification Service (emails, SMS)
+
+Communication: REST over HTTP
+Data: Each service owns its database"
+```
+
+### 3. Be Honest About Consequences
+```
+❌ Bad (hiding negatives):
+"Consequences: Faster development, better scalability."
+
+✅ Good (honest):
+"Consequences:
+Positive:
+- Independent deployment
+- Team autonomy
+
+Negative:
+- Operational complexity increases
+- Debugging becomes harder
+- Need for service mesh
+
+Risks:
+- Data consistency across services
+- Network latency"
+```
+
+### 4. Document Alternatives
+```
+Always explain why alternatives were rejected:
+
+Option 1: Build in-house
+- Pros: Full control, no licensing
+- Cons: 6 months development, ongoing maintenance
+- Why not: Time to market critical, team bandwidth limited
+
+Option 2: Buy existing solution
+- Pros: Immediate availability, support
+- Cons: $50k/year, customization limits
+- Why not: Cost exceeds budget, overkill for needs
+```
+
+## ADR Numbering
+
+### Sequential Numbering
+```
+ADR-001: Database Selection
+ADR-002: API Gateway Choice
+ADR-003: Authentication Strategy
+...
+
+Simple and widely used.
+```
+
+### Category Prefixes (Alternative)
+```
+ADR-DB-001: Database Selection
+ADR-API-001: API Gateway
+ADR-SEC-001: Authentication
+...
+
+Good for large projects with many ADRs.
+```
+
+## ADR Review Process
+
+### Proposal Stage
+```
+1. Author writes ADR with "Proposed" status
+2. Share with relevant stakeholders
+3. Schedule review meeting (30 min)
+4. Gather feedback
+5. Iterate on ADR
+```
+
+### Acceptance
+```
+1. Decision makers approve
+2. Update status to "Accepted"
+3. Record decision date
+4. Communicate to broader team
+5. Begin implementation
+```
+
+### Rejection
+```
+If ADR is rejected:
+1. Update status to "Rejected"
+2. Document why rejected
+3. Keep ADR for historical record
+4. Don't delete - others may propose same thing
+```
+
+## Common Mistakes
+
+### 1. Too Long
+```
+❌ Bad: 10-page ADR with implementation details
+✅ Good: 1-2 pages, implementation in separate docs
+
+Keep ADRs focused on the decision.
+Details go in design docs.
+```
+
+### 2. Missing Context
+```
+❌ Bad: "We chose Kafka."
+       (Why? What problem?)
+
+✅ Good: "Our event pipeline needs to process 100k events/sec.
+       RabbitMQ maxes out at 50k. Kafka handles 1M+."
+```
+
+### 3. No Alternatives
+```
+❌ Bad: Decision without alternatives
+✅ Good: At least 2-3 alternatives considered
+
+If you didn't consider alternatives, you didn't make a decision.
+```
+
+### 4. Outdated Status
+```
+❌ Bad: ADR-001 shows "Proposed" from 2 years ago
+✅ Good: Status kept current throughout lifecycle
+```
+
+### 5. Orphaned ADRs
+```
+❌ Bad: ADRs in random locations, no index
+✅ Good: Centralized location with index/README
+```
+
+## ADR Index Template
+
+```markdown
+# Architecture Decision Records
+
+## Active Decisions
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| [ADR-015](ADR-015-jwt-auth.md) | JWT Authentication | Accepted | 2024-06-15 |
+| [ADR-014](ADR-014-graphql.md) | GraphQL API | Accepted | 2024-05-20 |
+| [ADR-016](ADR-016-observability.md) | Observability Stack | Proposed | 2024-06-20 |
+
+## Superseded/Deprecated
+
+| ADR | Title | Superseded By | Date |
+|-----|-------|---------------|------|
+| [ADR-003](ADR-003-redis-sessions.md) | Redis Sessions | ADR-015 | 2024-06-15 |
+| [ADR-001](ADR-001-mysql.md) | MySQL Database | ADR-010 | 2024-03-01 |
+
+## By Category
+
+### Data
+- ADR-010: PostgreSQL Migration
+- ADR-011: Data Retention Policy
+
+### API
+- ADR-005: GraphQL for Public API
+- ADR-006: API Versioning Strategy
+
+### Security
+- ADR-015: JWT Authentication
+- ADR-008: Encryption Standards
+```
+
+## Retrospective ADRs
+
+Sometimes you need to document decisions made earlier:
+
+```markdown
+# ADR-001: Use React for Frontend
+
+## Status
+Accepted (Retrospective)
+
+## Context
+This ADR documents a decision made in January 2023,
+before we started the ADR process.
+
+## Decision
+[Document what was decided]
+
+## Consequences
+[Document the actual consequences observed]
+```
+
+## Tools
+
+### ADR Tools
+```
+- adr-tools (CLI): GitHub.com/npryce/adr-tools
+- log4brains (Web): GitHub.com/thomvaill/log4brains
+- ADR Manager (VS Code extension)
+- Notion/Confluence templates
+```
+
+### Integration with Development
+```
+1. Keep ADRs in git (same repo as code)
+2. Link ADRs from code comments
+3. Reference ADRs in PRs
+4. Include ADR number in commit messages
+
+Example:
+git commit -m "feat(orders): implement saga pattern
+
+Implements compensating transactions as described
+in ADR-010.
+
+Refs: ADR-010"
+```
+
+## Metrics
+
+### Track ADR Health
+```
+- Total ADRs
+- Proposed but not reviewed (> 2 weeks)
+- Accepted without implementation (> 1 month)
+- Deprecated without migration plan
+- Average time from proposed to accepted
+```