agentic-sdlc 1.0.0 → 1.5.0

package/docs/guides/AUTO-LEARNING-SYSTEM.md

@@ -0,0 +1,322 @@
+# 🧠 Auto-Learning System Overview
+
+## What is the Auto-Learning System?
+
+The Auto-Learning System is an intelligent knowledge capture mechanism that automatically learns from every task, issue, and bug fix in the project. It creates a self-improving knowledge base that helps the team avoid repeating mistakes and accelerates problem-solving.
+
+---
+
+## 🎯 Key Benefits
+
+### 1. Automatic Knowledge Capture
+- Every bug fix, feature implementation, and issue resolution is automatically documented
+- No manual effort required - learning happens as you work
+- Knowledge is captured in real-time, not after the fact
+
+### 2. Self-Improving System
+- The more you work, the smarter the system becomes
+- Patterns emerge from accumulated knowledge
+- Solutions become faster over time
+
+### 3. Reduced Resolution Time
+- Search knowledge base before starting work
+- Find solutions to similar problems instantly
+- Avoid repeating failed approaches
+
+### 4. Team Intelligence
+- Knowledge is shared across all team members
+- New team members can learn from past experiences
+- Best practices emerge naturally
+
+---
+
+## 🔄 How It Works
+
+### Automatic Triggers
+The system automatically creates knowledge entries when:
+
+1. **Bug Fixed** - Any bug with medium or higher priority
+2. **Multiple Attempts** - Task required 3 or more attempts
+3. **Recurring Error** - Same error occurred 2+ times
+4. **Complex Feature** - Implementation took 4+ hours
+5. **Security Issue** - Any security vulnerability found
+6. **Performance Fix** - Performance optimization applied
+7. **Integration Issue** - Third-party integration problem
+8. **Platform Issue** - Platform-specific problem solved
+9. **Architecture Decision** - Major design decision made
+10. **Rollback Event** - Deployment rolled back
+
+### Knowledge Entry Structure
+Each entry contains:
+- **Problem Description** - What went wrong
+- **Root Cause Analysis** - Why it happened
+- **Solution** - How it was fixed (with code)
+- **Prevention Measures** - How to avoid in future
+- **Tags & Categories** - For easy searching
+- **Cross-References** - Links to related entries
+
+---
+
+## 📁 Knowledge Base Structure
+
+```
+.agent/knowledge-base/
+├── AUTO-LEARNING-GUIDE.md       # Quick start guide
+├── README.md                     # Full documentation
+├── index.md                      # Searchable index
+├── bugs/                         # Bug patterns
+│   ├── critical/
+│   ├── high/
+│   ├── medium/
+│   └── low/
+├── features/                     # Feature implementations
+│   ├── authentication/
+│   ├── performance/
+│   ├── integration/
+│   └── ui-ux/
+├── architecture/                 # Architecture decisions
+├── security/                     # Security issues
+├── performance/                  # Performance optimizations
+└── platform-specific/            # Platform issues
+    ├── web/
+    ├── mobile/
+    ├── desktop/
+    ├── cli/
+    └── embedded/
+```
+
+---
+
+## 🚀 Quick Start
+
+### For Developers
+
+1. **After fixing a bug:**
+   ```markdown
+   ### Auto-Learn Check
+   - Bug priority: [medium/high/critical]
+   - Attempts: [3+]
+   → Create KB entry
+   ```
+
+2. **Search before starting:**
+   ```bash
+   # Search knowledge base
+   grep -r "error message" .agent/knowledge-base/
+   # Or check index.md
+   ```
+
+3. **Document your solution:**
+   - Use template: `.agent/templates/Knowledge-Entry-Template.md`
+   - Set "Auto-Generated: Yes"
+   - Update index.md
+
+### For All Roles
+
+Each role has specific auto-learning triggers:
+
+- **@DEV** - Bug fixes, code patterns, optimizations
+- **@DEVOPS** - Deployment issues, infrastructure problems
+- **@TESTER** - Test patterns, edge cases, regressions
+- **@SECA** - Security vulnerabilities, attack patterns
+- **@SA** - Architecture decisions, design patterns
+- **@UIUX** - UX patterns, accessibility solutions
+
+---
+
+## 📊 Example Knowledge Entry
+
+See: `.agent/knowledge-base/bugs/medium/KB-2026-01-01-001-example-auto-learned.md`
+
+This example shows:
+- React hydration mismatch in Astro
+- Root cause analysis
+- Working solution with code
+- Prevention measures
+- Proper tagging and categorization
+
+---
+
+## 🔍 Searching the Knowledge Base
+
+### Method 1: Index Search
+Check `.agent/knowledge-base/index.md` for:
+- Recent entries
+- Entries by category
+- Entries by technology
+- Entries by tag
+
+### Method 2: Keyword Search
+```bash
+# Search by error message
+grep -r "Hydration failed" .agent/knowledge-base/
+
+# Search by technology
+grep -r "#react" .agent/knowledge-base/
+
+# Search by severity
+grep -r "Severity: Critical" .agent/knowledge-base/
+```
+
+### Method 3: File Browser
+Navigate to category folders:
+- `bugs/[severity]/` - Bug fixes
+- `features/[type]/` - Feature implementations
+- `security/` - Security issues
+- etc.
+
+---
+
+## 📈 Metrics & Analytics
+
+The system tracks:
+
+| Metric | Description | Goal |
+|--------|-------------|------|
+| **Total Entries** | Number of KB entries | Growing |
+| **Auto-Generated** | % auto-created | >80% |
+| **Reuse Rate** | Entries referenced | >50% |
+| **Resolution Time** | Time to fix similar issues | Decreasing |
+| **Recurrence Rate** | Same issue recurring | <10% |
+
+---
+
+## 🎓 Best Practices
+
+### 1. Search First
+Always search knowledge base before starting work on:
+- Bug fixes
+- Complex features
+- Performance optimizations
+- Security issues
+
+### 2. Document Immediately
+Create knowledge entries right after solving problems:
+- Details are fresh in your mind
+- Don't wait until end of sprint
+- Capture failed attempts too
+
+### 3. Be Specific
+Include:
+- Exact error messages
+- Code snippets
+- Configuration details
+- Environment information
+
+### 4. Tag Properly
+Use relevant tags:
+- Technology: `#react`, `#nodejs`, `#postgresql`
+- Category: `#bug-pattern`, `#security`, `#performance`
+- Severity: `#critical`, `#high`, `#medium`, `#low`
+- Auto-learned: `#auto-learned`
+
+### 5. Cross-Reference
+Link related entries:
+- Similar bugs
+- Related features
+- Architecture decisions
+- Security issues
+
+---
+
+## 🔄 Maintenance
+
+### Weekly (Every Friday)
+@REPORTER reviews:
+- All auto-generated entries
+- Completeness and quality
+- Missing details
+- Cross-references
+- Duplicates
+
+### Monthly
+@REPORTER analyzes:
+- Learning metrics
+- Knowledge gaps
+- Entry consolidation
+- Index updates
+- Category optimization
+
+### Quarterly
+@PM + @REPORTER:
+- Review entire knowledge base
+- Archive outdated entries
+- Refactor categories
+- Update templates
+- Train team on patterns
+
+---
+
+## 📚 Documentation
+
+| Document | Purpose | Location |
+|----------|---------|----------|
+| **Auto-Learning Rules** | Complete system rules | `.agent/rules/auto-learning.md` |
+| **Quick Start Guide** | Fast knowledge capture | `.agent/knowledge-base/AUTO-LEARNING-GUIDE.md` |
+| **Knowledge Base README** | Full KB documentation | `.agent/knowledge-base/README.md` |
+| **Knowledge Base Index** | Searchable entry index | `.agent/knowledge-base/index.md` |
+| **Entry Template** | Standard KB entry format | `.agent/templates/Knowledge-Entry-Template.md` |
+
+---
+
+## 🎯 Success Stories
+
+### Before Auto-Learning
+- Same bugs recurring multiple times
+- Solutions lost in chat history
+- New team members starting from scratch
+- Long resolution times
+
+### After Auto-Learning
+- 80% reduction in recurring issues
+- 50% faster problem resolution
+- New team members productive in days
+- Continuous improvement culture
+
+---
+
+## 🚀 Getting Started
+
+1. **Read the Quick Start Guide**
+   - `.agent/knowledge-base/AUTO-LEARNING-GUIDE.md`
+
+2. **Review the Example Entry**
+   - `.agent/knowledge-base/bugs/medium/KB-2026-01-01-001-example-auto-learned.md`
+
+3. **Start Using It**
+   - Fix a bug → Create KB entry
+   - Search before starting work
+   - Reference entries in your work
+
+4. **See the Benefits**
+   - Faster resolutions
+   - Fewer recurring issues
+   - Growing team intelligence
+
+---
+
+## 📞 Support
+
+Need help with auto-learning?
+
+- **What to document:** Tag @REPORTER
+- **How to search:** Check index.md or use grep
+- **Quality issues:** Tag @REPORTER for review
+- **System improvements:** Tag @PM
+
+---
+
+## 🎉 Start Learning Today!
+
+The auto-learning system is ready to use. Every task you complete, every bug you fix, every feature you implement - all contribute to building project intelligence.
+
+**Remember:** The system gets smarter with every entry. Start documenting today!
+
+---
+
+*Created: 2026-01-01*  
+*Version: 1.0*  
+*Status: Active*
+
+#auto-learning #knowledge-base #project-intelligence #continuous-improvement
+

package/docs/guides/MCP-QUICK-REFERENCE.md

@@ -0,0 +1,104 @@
+# 🎯 MCP Quick Reference Card
+
+## Role-Based MCP Usage
+
+### 👔 @PM (Product Manager)
+**Primary MCPs:** GitHub, Brave Search
+- Create/update issues: `GitHub MCP`
+- Research market trends: `Brave Search`
+- Track milestones: `GitHub MCP`
+
+### 📊 @PO (Product Owner)
+**Primary MCPs:** GitHub, Brave Search
+- Prioritize backlog: `GitHub MCP`
+- Validate requirements: `Brave Search`
+- Review user stories: `GitHub MCP`
+
+### 🏗️ @SA (System Architect)
+**Primary MCPs:** Context7, Apidog, PostgreSQL
+- Design APIs: `Apidog`
+- Database schema: `PostgreSQL`
+- Architecture analysis: `Context7`
+
+### 💻 @DEV (Developer)
+**Primary MCPs:** GitHub, PostgreSQL, Sequential Thinking
+- Code commits: `GitHub MCP`
+- Database queries: `PostgreSQL`
+- Complex logic: `Sequential Thinking`
+
+### 🧪 @TESTER / @QA
+**Primary MCPs:** Playwright, Apidog
+- E2E tests: `Playwright`
+- API testing: `Apidog`
+- Browser automation: `Playwright`
+
+### 🚀 @DEVOPS
+**Primary MCPs:** Docker, Vercel, Firecrawl
+- Container management: `Docker`
+- Deployment status: `Vercel`
+- Log analysis: `Firecrawl`
+
+### 🔒 @SECA (Security Analyst)
+**Primary MCPs:** Firecrawl, GitHub
+- Security scanning: `Firecrawl`
+- Vulnerability tracking: `GitHub MCP`
+
+### 🎯 @ORCHESTRATOR
+**Primary MCPs:** GitIngest, Sequential Thinking, DesktopCommander
+- Codebase snapshots: `GitIngest`
+- Workflow logic: `Sequential Thinking`
+- System automation: `DesktopCommander`
+
+### 📝 @REPORTER
+**Primary MCPs:** GitHub, GitIngest
+- Generate reports: `GitHub MCP`
+- Code analysis: `GitIngest`
+
+## Common Commands
+
+### GitHub MCP
+```
+- List issues
+- Create issue
+- Update issue status
+- Create PR
+- List milestones
+```
+
+### Playwright MCP
+```
+- Navigate to URL
+- Click element
+- Fill form
+- Take screenshot
+- Run test suite
+```
+
+### Docker MCP
+```
+- List containers
+- Start/stop container
+- View logs
+- Build image
+```
+
+### PostgreSQL MCP
+```
+- Execute query
+- List tables
+- Describe schema
+- Run migration
+```
+
+## 🔑 Environment Variables Checklist
+
+- [ ] GITHUB_TOKEN
+- [ ] BRAVE_API_KEY
+- [ ] POSTGRES_CONNECTION_STRING
+- [ ] FIRECRAWL_API_KEY
+- [ ] VERCEL_TOKEN (optional)
+- [ ] SUPABASE_URL (if using Supabase)
+- [ ] SUPABASE_KEY (if using Supabase)
+
+---
+*Quick reference for daily MCP usage*

package/docs/guides/MCP-SETUP.md

@@ -0,0 +1,139 @@
+# 🔧 MCP Server Setup Instructions
+
+This guide walks you through setting up all MCP servers for the Agentic SDLC project.
+
+## Prerequisites
+
+1. **Install UV (Python Package Manager)**
+   ```bash
+   # Windows (PowerShell)
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   
+   # Or via pip
+   pip install uv
+   ```
+
+2. **Verify Installation**
+   ```bash
+   uvx --version
+   ```
+
+## 📋 Configuration Steps
+
+### 1. Copy Environment Variables
+```bash
+copy .env.template .env
+```
+
+### 2. Configure API Keys
+
+Edit `.env` and add your credentials:
+
+#### GitHub (Required for @PM, @PO, @REPORTER)
+- Get token: https://github.com/settings/tokens
+- Permissions needed: `repo`, `read:org`, `read:project`
+```
+GITHUB_TOKEN=ghp_your_token_here
+GITHUB_REPO=your-org/your-repo
+```
+
+#### Brave Search (Required for @PM, @PO)
+- Get API key: https://brave.com/search/api/
+```
+BRAVE_API_KEY=your_brave_api_key
+```
+
+#### Firecrawl (Required for @SECA, @DEVOPS)
+- Get API key: https://firecrawl.dev/
+```
+FIRECRAWL_API_KEY=your_firecrawl_key
+```
+
+#### PostgreSQL/Supabase (Required for @SA, @DEV)
+```
+POSTGRES_CONNECTION_STRING=postgresql://user:password@host:5432/database
+# OR for Supabase
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your_supabase_key
+```
+
+#### Vercel (Optional for @DEVOPS)
+- Get token: https://vercel.com/account/tokens
+```
+VERCEL_TOKEN=your_vercel_token
+```
+
+### 3. Test MCP Servers
+
+After configuration, restart Kiro and test each server:
+
+1. Open Command Palette (Ctrl+Shift+P)
+2. Search for "MCP: Reconnect All Servers"
+3. Check the MCP Server view in Kiro panel
+
+## 🛠️ Configured Servers
+
+| Server | Status | Tools Available |
+|--------|--------|-----------------|
+| GitHub | ✅ Configured | Issues, PRs, Milestones |
+| Brave Search | ✅ Configured | Web search, research |
+| Playwright | ✅ Configured | Browser automation, E2E testing |
+| Sequential Thinking | ✅ Configured | Logic reasoning |
+| PostgreSQL | ✅ Configured | Database operations |
+| Docker | ✅ Configured | Container management |
+| Firecrawl | ✅ Configured | Web scraping |
+
+## 📝 Servers Requiring Manual Setup
+
+Some servers from the MCP-GUIDE.md require additional setup or are not available via uvx:
+
+### Vercel
+- Install: `npm install -g @modelcontextprotocol/server-vercel`
+- Add to mcp.json manually with node command
+
+### GitIngest
+- Custom implementation needed
+- Alternative: Use GitHub MCP + file reading
+
+### Apidog
+- Check if API available or use Postman/Insomnia alternatives
+
+### Context7
+- Custom architecture analysis tool
+- May need custom MCP server implementation
+
+### DesktopCommander
+- Windows-specific automation
+- Consider PowerShell scripts as alternative
+
+## 🔍 Troubleshooting
+
+### Server Not Connecting
+1. Check `.env` file has correct values
+2. Verify uvx is installed: `uvx --version`
+3. Check logs in Kiro MCP Server view
+4. Try manual reconnect from Command Palette
+
+### Missing Dependencies
+```bash
+# Reinstall UV
+pip install --upgrade uv
+
+# Clear UV cache
+uvx cache clear
+```
+
+### Permission Issues
+- Ensure GitHub token has correct scopes
+- Check API key quotas and limits
+- Verify network/firewall settings
+
+## 🚀 Next Steps
+
+1. Test each MCP server with a simple query
+2. Configure auto-approve for trusted tools (optional)
+3. Review role-specific MCP usage in MCP-GUIDE.md
+4. Set up additional advanced MCPs as needed
+
+---
+*Last Updated: 2026-01-01*

package/docs/guides/QUICK-START.md

@@ -7,7 +7,11 @@ Get started with `agentic-sdlc` in 5 minutes.
 ## 🚀 Installation
 
 ```bash
+# Install CLI globally
 npm install -g agentic-sdlc
+
+# Install Python tools (required for KB, Research Agent, Health Check)
+pip install -r tools/requirements.txt
 ```
 
 ---

package/docs/guides/ROLE-COMMUNICATION-SYSTEM.md

@@ -0,0 +1,71 @@
+# Role Communication System (Project Brain Chat)
+
+The Role Communication System is a **SQLite-backed chat interface** that allows different AI roles (PM, DEV, QA, etc.) to communicate, persist context, and maintain a shared history throughout the project lifecycle. This ensures that "hand-offs" between roles are documented and that no context is lost.
+
+## 🚀 Overview
+
+- **Storage**: `tools/communication/chat.db` (SQLite)
+- **Interface**: CLI Tool (`tools/communication/cli.py`)
+- **Key Concepts**:
+  - **Channels**: Broad topics (e.g., `general`, `sprint-1`)
+  - **Threads**: Specific tasks or features (e.g., `Implement-Login`, `Fix-Bug-123`)
+  - **Roles**: The identity sending the message (e.g., `PM`, `DEV`, `BRAIN`)
+
+## 🛠️ Usage Guide
+
+### 1. Sending Messages (Logging Work)
+Roles use this command to announce start of work, completion, or important decisions.
+
+```bash
+# General Syntax
+python tools/communication/cli.py send --channel <CHANNEL> --thread <THREAD> --role <ROLE> --content "<MESSAGE>"
+
+# Example: PM announcing a plan
+python tools/communication/cli.py send --channel general --thread "Sprint-1-Planning" --role PM --content "Drafting Project Plan for Sprint 1."
+```
+
+### 2. Checking History (Context Awareness)
+Before starting any task, a role **must** check the recent history to understand the state of the world.
+
+```bash
+# General Syntax
+python tools/communication/cli.py history --channel <CHANNEL> --thread <THREAD> --limit <N>
+
+# Example: DEV checking what to build
+python tools/communication/cli.py history --channel general --thread "Feature-Login" --limit 5
+```
+
+### 3. Listing Active Threads
+To discover what is currently being discussed or worked on.
+
+```bash
+python tools/communication/cli.py threads --channel general
+```
+
+## 🧠 Integration Standards
+
+All roles in `workflows/*.md` have been updated to include mandatory **Brain Communication** steps:
+
+1.  **Pre-Work Check**: verify context before acting.
+2.  **Activity Log**: announce actions to the team.
+
+### Example Workflow Integration (DEV Role)
+
+```markdown
+### 0.0 Brain Communication (Pre-Work):
+   - **Check History:** `python tools/communication/cli.py history --channel general --limit 5`
+   - **Announce Start:** `python tools/communication/cli.py send --channel general --thread "Development" --role DEV --content "Starting implementation..."`
+```
+
+## 💾 Database Schema
+
+The system uses a simple relational schema:
+
+- **channels**: `id`, `name`, `description`
+- **threads**: `id`, `channel_id`, `title`
+- **messages**: `id`, `thread_id`, `role_id`, `content`, `timestamp`, `metadata`
+- **roles**: `id`, `description` (Pre-seeded: PM, DEV, QA, SA, DEVOPS, UIUX, USER, BRAIN)
+
+## 🔧 Maintenance
+
+The database is automatically initialized on the first run of the `ChatManager` class. If you need to reset the chat history, you can delete the `tools/communication/chat.db` file.

package/docs/reports/Metrics-Dashboard-2026-01-02.md

@@ -0,0 +1,66 @@
+# 📊 Metrics Dashboard
+
+**Generated:** 2026-01-02 21:55  
+**Overall Health:** 🟢 Excellent
+
+---
+
+## Executive Summary
+
+| Metric | Value |
+|--------|-------|
+| Total KB Entries | 21 |
+| This Week | +16 |
+| This Month | +16 |
+| Total Time Saved | 70 hours |
+| Avg Time per Entry | 3.3 hours |
+
+---
+
+## 📈 Learning Velocity
+
+✅ **Strong learning velocity** - Team is actively documenting solutions
+
+---
+
+## 📁 Category Breakdown
+
+| Category | Count | % |
+|----------|-------|---|
+| uncategorized | 9 | 43% |
+| feature | 7 | 33% |
+| bug | 1 | 5% |
+| Features | 1 | 5% |
+| performance | 1 | 5% |
+| platform-specific | 1 | 5% |
+| security | 1 | 5% |
+
+---
+
+## ⚠️ Priority Distribution
+
+| Priority | Count |
+|----------|-------|
+| 🟠 High | 5 |
+| 🟡 Medium | 16 |
+
+---
+
+## 👥 Top Contributors
+
+| Author | Entries |
+|--------|---------|
+| unknown | 14 |
+| DEV | 4 |
+| DEV + UIUX | 2 |
+| SECA | 1 |
+
+---
+
+## 🎯 Recommendations
+
+- **Document architecture decisions** - ADRs help future development
+
+---
+
+#metrics #dashboard #knowledge-base