agentic-sdlc 1.0.0 → 1.5.0

package/.agent/workflows/metrics.md

@@ -0,0 +1,179 @@
+---
+description: [Utility] Metrics - Project Statistics
+---
+
+# /metrics - Metrics Dashboard Generator
+
+## ⚠️ PURPOSE
+Analyzes KB entries, workflow usage, and project health to generate a metrics dashboard showing learning velocity, quality indicators, and system health.
+
+## Quick Commands
+
+```bash
+# Generate dashboard
+python tools/kb/metrics-dashboard.py
+
+# Weekly report focus
+python tools/kb/metrics-dashboard.py --weekly
+
+# Sprint-specific metrics
+python tools/kb/metrics-dashboard.py --sprint 6
+
+# Custom output path
+python tools/kb/metrics-dashboard.py --output ./my-report.md
+```
+
+## What It Measures
+
+### 1. Knowledge Base Metrics
+- **Total KB Entries:** Count of all knowledge entries
+- **This Week:** Entries added in last 7 days
+- **This Month:** Entries added in last 30 days
+- **Category Breakdown:** Distribution across categories
+
+### 2. Learning Velocity
+- Entries per week trend
+- Strong (3+), Moderate (1-2), Low (0)
+
+### 3. Time Saved
+- Estimated hours saved per entry
+- Total accumulated time saved
+- Average time per entry
+
+### 4. Quality Indicators
+- Priority distribution (critical, high, medium, low)
+- Category diversity
+- Contributor activity
+
+## Console Output
+
+```
+============================================================
+Metrics Dashboard Generator
+============================================================
+[INFO] Analyzing knowledge base...
+[OK] Analyzed 12 entries
+
+============================================================
+Quick Stats
+============================================================
+  Total Entries:      12
+  This Week:          +3
+  This Month:         +8
+  Total Time Saved:   24 hours
+
+  Health Status: Good
+```
+
+## Dashboard Report
+
+Generates `docs/reports/Metrics-Dashboard-YYYY-MM-DD.md`:
+
+```markdown
+# 📊 Metrics Dashboard
+
+**Generated:** 2026-01-03 18:30  
+**Overall Health:** 🟢 Excellent
+
+---
+
+## Executive Summary
+
+| Metric | Value |
+|--------|-------|
+| Total KB Entries | 12 |
+| This Week | +3 |
+| This Month | +8 |
+| Total Time Saved | 24 hours |
+| Avg Time per Entry | 2.0 hours |
+
+---
+
+## 📈 Learning Velocity
+
+✅ **Strong learning velocity** - Team is actively documenting solutions
+
+---
+
+## 📁 Category Breakdown
+
+| Category | Count | % |
+|----------|-------|---|
+| feature | 7 | 58% |
+| bug | 3 | 25% |
+| security | 2 | 17% |
+
+---
+
+## ⚠️ Priority Distribution
+
+| Priority | Count |
+|----------|-------|
+| 🟠 High | 4 |
+| 🟡 Medium | 6 |
+| 🟢 Low | 2 |
+
+---
+
+## 👥 Top Contributors
+
+| Author | Entries |
+|--------|---------|
+| @DEV | 5 |
+| @SA | 3 |
+| @TESTER | 2 |
+
+---
+
+## 🎯 Recommendations
+
+- ✅ Keep up the great work!
+```
+
+## Health Score Calculation
+
+| Points | Criteria |
+|--------|----------|
+| +30 | 20+ total entries |
+| +20 | 10-19 total entries |
+| +30 | 3+ entries this week |
+| +15 | 1-2 entries this week |
+| +20 | 5+ categories |
+| +20 | 10+ hours time saved |
+
+| Score | Status |
+|-------|--------|
+| 80-100 | 🟢 Excellent |
+| 50-79 | 🟡 Good |
+| 0-49 | 🔴 Needs Attention |
+
+## Recommendations Engine
+
+Auto-generates recommendations based on:
+- Low documentation velocity
+- Missing bug documentation
+- Missing architecture decisions
+- Unbalanced category distribution
+
+## When to Run
+
+- **Weekly:** Track learning velocity
+- **End of Sprint:** Generate sprint metrics
+- **Monthly:** Long-term trend analysis
+- **Stakeholder Reports:** Project health overview
+
+## Integration
+
+- **/brain** - Uses KB data for recommendations
+- **/compound** - Creates entries that affect metrics
+- **/housekeeping** - References health status
+- **/sprint close** - Include metrics in retrospective
+
+#metrics #dashboard #analytics #health #knowledge-base
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/orchestrator.md

@@ -0,0 +1,68 @@
+---
+description: [Process] Orchestrator - Full Automation Workflow
+---
+
+# Orchestrator Workflow
+
+> **Master Controller:** [View @BRAIN Skill](../../skills/role-brain.md)
+> 
+> **⚠️ Supervised by @BRAIN.** Report status on each phase transition.
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+All phases must be executed in order. No skipping.
+
+## State Machine Integration
+This workflow follows the state machine defined in `@BRAIN`. Before each phase transition:
+1. Run `python tools/brain/brain_cli.py validate` to check prerequisites
+2. Run `python tools/brain/brain_cli.py transition <NEW_STATE>` to update state
+3. Artifacts required per state are validated automatically
+
+### 0.0 **Team Communication (MANDATORY):**
+   - **Announce:** `python tools/communication/cli.py send --channel general --thread "SDLC-Flow" --role ORCHESTRATOR --content "Starting Full SDLC Automation."`
+
+### 0.1 **Initialize State (If New Sprint):**
+```bash
+python tools/brain/brain_cli.py init <SPRINT_NUMBER>
+```
+
+## SDLC Flow (State Transitions)
+
+### Phase 1: Planning (@PM)
+- Research, create Project Plan, wait for User approval.
+
+### Phase 2: Requirements (@BA)
+- Create User Stories with Gherkin acceptance criteria.
+
+### Phase 3: Design (@SA + @UIUX)
+- Create Backend and UI/UX design specs.
+
+### Phase 4: Design Verification (@TESTER + @SECA)
+- Review designs for quality and security.
+
+### Phase 5: Development (@DEV + @DEVOPS)
+- Feature branch, atomic commits, PRs, GitHub issues.
+
+### Phase 6: Testing (@TESTER)
+- E2E testing, provide `#testing-passed`.
+
+### Phase 7: Bug Fixing (@DEV)
+- Fix bugs, update KB.
+
+### Phase 8: Deployment (@DEVOPS)
+- Merge to main, deploy to staging/production.
+
+### Phase 9-10: Reporting & Closure (@PM)
+- Update CHANGELOG, Final Review.
+
+### Phase 11: Self-Learning
+- Run: `python tools/neo4j/sync_skills_to_neo4j.py`
+- Run: `python tools/neo4j/learning_engine.py --record-success`
+
+#orchestrator #automation #sdlc
+---
+## ⚠️ ENFORCEMENT REMINDER
+Before executing this workflow, agent MUST:
+1. Have completed /preflight checks
+2. Searched knowledge base for similar tasks
+3. Checked current brain state
+Failure to complete pre-flight = workflow violation.

package/.agent/workflows/preflight.md

@@ -0,0 +1,35 @@
+---
+description: [Support] Pre-flight workflow checker - Run BEFORE any task
+---
+# Pre-Flight Workflow
+> **MANDATORY:** This workflow MUST be executed conceptually before ANY task.
+## Step 1: Identify Task Type
+Analyze user request and determine:
+- Is this a new feature? -> Use /orchestrator
+- Is this a bug fix? -> Use /cycle
+- Is this investigation? -> Use /explore
+- Is this emergency? -> Use /emergency
+## Step 2: Read Workflow File
+`bash
+# For /orchestrator tasks
+cat .agent/workflows/orchestrator.md
+# For /cycle tasks  
+cat .agent/workflows/cycle.md
+`
+## Step 3: Search Knowledge Base
+`bash
+grep -r "relevant_keyword" .agent/knowledge-base/
+`
+## Step 4: Check Brain State
+`bash
+python tools/brain/brain_cli.py status
+`
+## Step 5: Identify Required Roles
+Based on task type, activate roles:
+- @PM for planning
+- @SA for architecture  
+- @DEV for implementation
+- @TESTER for testing
+## Step 6: Proceed with Workflow
+Now follow the identified workflow file step-by-step.
+#preflight #mandatory #enforcement

package/.agent/workflows/release.md

@@ -0,0 +1,153 @@
+---
+description: [Support] Release Management Workflow
+---
+
+# /release - Changelog and Version Management
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **CONVENTIONAL COMMITS:** All commits must follow conventional commit format.
+2. **SEMVER:** Version bumps follow semantic versioning.
+3. **CHANGELOG:** Update CHANGELOG.md before releasing.
+
+## Quick Commands
+
+```bash
+# Preview changes (dry run)
+python tools/release/release.py preview
+
+# Generate changelog only
+python tools/release/release.py changelog --sprint 6
+
+# Bump version only
+python tools/release/release.py version --auto
+
+# Full release cycle
+python tools/release/release.py release --commit --tag --push --publish
+```
+
+## Conventional Commit Format
+
+```
+type(scope): description
+
+feat(landing): add hero section animation
+fix(api): resolve timeout issue
+docs(kb): update authentication guide
+refactor(core): extract utility functions
+```
+
+### Types and Changelog Categories
+
+| Type | Changelog Category | Version Bump |
+|------|-------------------|--------------|
+| `feat` | Added | Minor |
+| `fix` | Fixed | Patch |
+| `docs` | Documentation | Patch |
+| `refactor` | Changed | Patch |
+| `perf` | Performance | Patch |
+| `test` | Testing | - |
+| `chore` | Maintenance | - |
+| `BREAKING CHANGE` | Breaking | Major |
+
+### Scopes (Optional)
+
+| Scope | Tag in Changelog |
+|-------|------------------|
+| `landing` | [Landing Page] |
+| `agent` | [Agent System] |
+| `workflow` | [Workflows] |
+| `kb` | [Knowledge Base] |
+| `tools` | [Tools] |
+| `ui` | [UI] |
+| `api` | [API] |
+
+## Workflow Steps
+
+### 1. Preview Changes
+```bash
+python tools/release/release.py preview --sprint 6
+```
+Shows:
+- Last git tag
+- Current version
+- Commits since last release
+- Auto-detected bump type
+- Preview changelog entry
+
+### 2. Generate Changelog
+```bash
+python tools/release/release.py changelog --sprint 6 --dry-run
+```
+- Parses commits since last tag
+- Categorizes by type
+- Generates markdown section
+- Inserts into CHANGELOG.md
+
+### 3. Bump Version
+```bash
+# Auto-detect based on commits
+python tools/release/release.py version --auto
+
+# Explicit bump type
+python tools/release/release.py version --bump minor
+```
+Updates `package.json` version.
+
+### 4. Full Release
+```bash
+python tools/release/release.py release --sprint 6 --commit --tag --push --publish
+```
+Executes:
+1. Parse commits
+2. Detect bump type
+3. Generate changelog
+4. Update version
+5. Commit changes (optional)
+6. Create git tag (optional)
+7. Push changes (optional)
+8. Publish to npm/bun (optional)
+
+### 5. Manual Push (Backup)
+```bash
+git add CHANGELOG.md package.json
+git commit -m "chore(release): v1.2.0"
+git push && git push --tags
+```
+
+## Example Changelog Output
+
+```markdown
+## [1.2.0] - 2026-01-03 (Sprint 6)
+
+### Added
+- [Landing Page] Hero section with animations
+- [Agent System] New orchestrator workflow
+
+### Fixed
+- [API] Timeout issue in authentication
+- [KB] Index update race condition
+
+### Documentation
+- Updated quick start guide
+- Added MCP integration docs
+```
+
+## Integration
+
+- **Package Scripts:**
+  ```bash
+  bun run release:preview    # Preview changes
+  bun run release:changelog  # Generate changelog
+  bun run release            # Full release
+  ```
+
+- **CI/CD:** Can be triggered in GitHub Actions
+
+#release #versioning #changelog #semver #git-tags
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/route.md

@@ -0,0 +1,160 @@
+---
+description: [Support] Route - Workflow Selection Helper
+---
+
+# /route - Intelligent Request Routing
+
+## ⚠️ PURPOSE
+Analyzes user requests and routes to the appropriate workflow or role. Use when unsure which workflow to invoke.
+
+## Quick Reference
+
+### By Request Type
+
+| Request Type | Recommended Route |
+|--------------|-------------------|
+| "Build a new feature" | `/orchestrator` or `/pm` → full SDLC |
+| "Fix this bug" | `/dev` or `/emergency` (if P0) |
+| "Review this design" | `/tester` + `/seca` |
+| "Set up infrastructure" | `/devops` |
+| "Create user stories" | `/ba` |
+| "Design the UI" | `/uiux` |
+| "Design the API" | `/sa` |
+| "How do I..." | `/explore` first, then appropriate role |
+
+### By Urgency
+
+| Urgency | Route |
+|---------|-------|
+| 🔴 Production down | `/emergency --severity P0` |
+| 🟠 Major bug | `/emergency --severity P1` |
+| 🟡 Normal task | `/cycle` |
+| 🟢 Investigation | `/explore` |
+
+### By Phase
+
+| SDLC Phase | Route |
+|------------|-------|
+| Planning | `/pm` |
+| Requirements | `/ba` |
+| Design | `/sa` + `/uiux` |
+| Verification | `/tester` + `/seca` |
+| Implementation | `/dev` |
+| Testing | `/tester` |
+| Deployment | `/devops` |
+| Closure | `/pm` |
+
+## Decision Tree
+
+```
+Is this an emergency?
+├── Yes → /emergency
+└── No → Continue
+
+Is this a full project/feature?
+├── Yes → /orchestrator (full automation)
+└── No → Continue
+
+Is this a single task?
+├── Yes → /cycle
+└── No → Continue
+
+What phase are you in?
+├── Planning → /pm
+├── Requirements → /ba
+├── Design → /sa or /uiux
+├── Review → /tester or /seca
+├── Development → /dev
+├── Testing → /tester
+└── Deployment → /devops
+
+Need maintenance?
+├── Brain sync → /brain
+├── Cleanup → /housekeeping
+├── Validation → /validate
+├── Metrics → /metrics
+└── Release → /release
+```
+
+## Role Selection Guide
+
+### @PM - Project Manager
+**Use when:**
+- Starting a new project
+- Creating project plans
+- Tracking sprint progress
+- Generating reports
+
+### @BA - Business Analyst
+**Use when:**
+- Gathering requirements
+- Writing user stories
+- Defining acceptance criteria
+
+### @SA - System Analyst
+**Use when:**
+- Designing architecture
+- Creating API specifications
+- Making technical decisions
+
+### @UIUX - UI/UX Designer
+**Use when:**
+- Designing interfaces
+- Creating wireframes
+- Ensuring accessibility
+
+### @DEV - Developer
+**Use when:**
+- Implementing features
+- Writing code
+- Fixing bugs
+
+### @TESTER - Tester
+**Use when:**
+- Reviewing designs
+- Writing test plans
+- Executing E2E tests
+
+### @SECA - Security Analyst
+**Use when:**
+- Security review
+- Threat modeling
+- Compliance checking
+
+### @DEVOPS - DevOps Engineer
+**Use when:**
+- Setting up CI/CD
+- Managing deployments
+- Merging PRs
+
+## Common Patterns
+
+### New Feature Request
+```
+/pm → /ba → /sa + /uiux → /tester + /seca → /dev → /tester → /devops
+```
+
+### Bug Fix
+```
+Minor: /cycle
+Major: /emergency → /dev → /tester → /devops → /compound
+```
+
+### Documentation Update
+```
+/dev (for code docs) or /pm (for project docs)
+```
+
+### Maintenance
+```
+/housekeeping → /validate → /metrics → /brain
+```
+
+#route #routing #decision-tree #workflow-selection
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/sprint.md

@@ -0,0 +1,125 @@
+---
+description: [Process] Sprint Management Workflow
+---
+
+# /sprint - Sprint Lifecycle Management
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **SPRINT START:** Create folder structure and archive previous sprint.
+2. **SPRINT STATUS:** Monitor progress during sprint.
+3. **SPRINT CLOSE:** Generate review and retrospective templates.
+
+## Quick Commands
+
+```bash
+# Start a new sprint
+python tools/workflows/sprint.py start 6
+
+# Check current sprint status
+python tools/workflows/sprint.py status
+
+# Close a sprint
+python tools/workflows/sprint.py close 5
+```
+
+## Sprint Start
+
+### What It Does
+1. **Archives previous sprint** (copies to `docs/archive/sprint-[N-1]/`)
+2. **Creates new sprint folder structure:**
+   ```
+   docs/sprints/sprint-[N]/
+   ├── plans/        # Sprint planning docs
+   ├── designs/      # Technical designs
+   ├── logs/         # Daily logs and notes
+   ├── reviews/      # Code review records
+   └── reports/      # Sprint reports
+   ```
+3. **Creates sprint README.md** with goals template
+4. **Updates current sprint** in project config
+
+### Usage
+```bash
+python tools/workflows/sprint.py start 6
+```
+
+### Next Steps After Start
+1. Run `@PM /planning` to create sprint plan
+2. Sync backlog with GitHub Issues
+3. Announce sprint start to team
+
+## Sprint Status
+
+### What It Shows
+- Current sprint name
+- Sprint directory existence
+- File counts per folder
+- README presence
+
+### Usage
+```bash
+python tools/workflows/sprint.py status
+```
+
+## Sprint Close
+
+### What It Does
+1. **Generates Sprint Review template** (`reports/Sprint-Review-[N].md`)
+   - Accomplishments section
+   - Metrics placeholders
+   - Demo highlights
+   - Stakeholder feedback
+
+2. **Generates Retrospective template** (`reports/Retrospective-[N].md`)
+   - What went well
+   - What didn't go well
+   - What we learned
+   - Action items for next sprint
+
+### Usage
+```bash
+python tools/workflows/sprint.py close 5
+```
+
+### Next Steps After Close
+1. Fill in Sprint Review with accomplishments
+2. Complete Retrospective with team
+3. Start next sprint: `python tools/workflows/sprint.py start 6`
+
+## Sprint Folder Structure
+
+```
+docs/sprints/sprint-[N]/
+├── README.md           # Sprint overview and goals
+├── plans/
+│   ├── Project-Plan-Sprint-[N]-v*.md
+│   └── Product-Backlog-Sprint-[N]-v*.md
+├── designs/
+│   ├── Backend-Design-Spec-Sprint-[N]-v*.md
+│   └── UIUX-Design-Spec-Sprint-[N]-v*.md
+├── logs/
+│   ├── Development-Log-Sprint-[N]-v*.md
+│   └── Incident-Report-*.json
+├── reviews/
+│   ├── Design-Verification-Report-Sprint-[N].md
+│   └── Security-Review-Report-Sprint-[N].md
+└── reports/
+    ├── Sprint-Review-[N].md
+    └── Retrospective-[N].md
+```
+
+## Integration with Other Workflows
+
+- **@PM** uses sprint folders for planning artifacts
+- **@DEV** logs progress in `Development-Log.md`
+- **/emergency** creates incident reports in `logs/`
+- **/release** references sprint in changelog
+
+#sprint #agile #lifecycle #planning #retrospective
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+