agentic-sdlc 1.0.0 → 1.5.0

package/.agent/workflows/brain.md

@@ -1,56 +1,87 @@
 ---
-description: LEANN AI Brain - Automated Project Memory
+description: [Support] @BRAIN Meta-Level System Controller
 ---
 
-# LEANN AI Brain Workflow
-
-This workflow manages the automated project memory using the LEANN (Lean and Efficient AI Near-memory) framework.
-
-## 🚀 Setup & Initialization
-
-1. **Install LEANN Core**
-   If not already installed, run:
-   ```bash
-   pip install leann-core leann-backend-hnsw
-   ```
-
-2. **Initialize Project Index**
-   Index the current workspace with AST-aware chunking:
-   ```bash
-   leann index --path .
-   ```
-
-## 🧠 Memory & Reasoning Management
-
-3. **Update LEANN Index (Vector)**
-   Run this for semantic code search:
-   ```bash
-   leann index --update
-   ```
-
-4. **Update Neo4j Graph (Reasoning)**
-   Run this to sync project structure and GitHub issues to the cloud:
-   ```bash
-   # Sync file structure
-   python bin/graph_brain.py
-   
-   # Sync GitHub issues
-   python bin/sync_github.py
-   ```
-
-5. **Search Project Brain**
-   - **Semantic Search:** `leann search "{{query}}"`
-   - **Reasoning Query:** Use the Neo4j console or custom scripts to find relationships between issues and code.
-
-## 🔌 IDE Integration (MCP)
-
-6. **Start LEANN MCP Server**
-   ```bash
-   bunx --bun @yichuan-w/leann-mcp
-   ```
-   *Note: Add this to your `claude_desktop_config.json` or Cursor MCP settings.*
-
-## 📋 Best Practices
-- Use `/brain <query>` in chat to trigger this workflow.
-- Indexing is AST-aware; it understands functions, classes, and logic flow better than standard grep.
-- Keep the index updated to ensure agents have the latest context.
+# Brain Workflow
+
+> **Skill Definition:** [View Skill](../../skills/role-brain.md)
+
+## Identity
+@BRAIN is the **Meta-Level Controller** that supervises ALL workflows in the system.
+Brain is NOT an executor—it monitors, detects issues, routes to handlers, scores quality, and creates self-improvement plans.
+
+// turbo-all
+
+## Root Components (Layer 1)
+
+### Observer (Halt on Errors)
+```bash
+python tools/brain/observer.py --watch       # Monitor workflows
+python tools/brain/observer.py --halt "Err"  # Halt system
+python tools/brain/observer.py --resume      # Resume after halt
+```
+
+### Judge (Score Quality)
+```bash
+python tools/brain/judge.py --score "path/to/report.md"
+python tools/brain/judge.py --review --sprint 1
+python tools/brain/judge.py --threshold 7    # Set pass threshold
+```
+
+### Learner (Auto-Learning)
+```bash
+python tools/brain/learner.py --learn "Task completed"
+python tools/brain/learner.py --watch
+python tools/brain/learner.py --stats
+```
+
+### A/B Tester (Compare Options)
+```bash
+python tools/brain/ab_tester.py --create "Test description"
+python tools/brain/ab_tester.py --compare --test-id TEST-001
+python tools/brain/ab_tester.py --select A --test-id TEST-001
+```
+
+### Model Optimizer (Token Efficiency)
+```bash
+python tools/brain/model_optimizer.py --recommend "Task description"
+python tools/brain/model_optimizer.py --record --model "gemini-2.5" --tokens 1500
+```
+
+### Self-Improver (Create Improvement Plans)
+```bash
+python tools/brain/self_improver.py --analyze  # Analyze all data
+python tools/brain/self_improver.py --plan     # Create improvement plan
+python tools/brain/self_improver.py --apply-plan PLAN-ID
+```
+
+## State Management
+```bash
+python tools/brain/brain_cli.py init 1          # Initialize sprint
+python tools/brain/brain_cli.py status          # Check status
+python tools/brain/brain_cli.py transition STATE --reason "Reason"
+python tools/brain/brain_cli.py validate        # Validate state
+python tools/brain/brain_cli.py rollback        # Rollback
+```
+
+## Supervisor Commands
+```bash
+python tools/brain/brain_cli.py watch   # Monitor workflows
+python tools/brain/brain_cli.py route "request"  # Route to workflow
+python tools/brain/brain_cli.py health  # Health check
+```
+
+## Sync Commands
+```bash
+python tools/neo4j/brain_parallel.py --sync  # Quick sync
+python tools/neo4j/brain_parallel.py --full  # Full sync
+```
+
+#brain #root-layer #meta-controller
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/compound.md

@@ -0,0 +1,51 @@
+---
+description: [Support] Compound Knowledge Capture - After Tasks
+---
+
+# Compound Learning Workflow
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+This workflow MUST be executed after completing any significant task.
+
+## When to Use
+- After fixing a bug (medium+ priority)
+- After completing a feature
+- After resolving a complex problem (3+ hours)
+
+## Steps
+
+### 1. Create KB Entry
+```bash
+cp .agent/templates/Knowledge-Entry-Template.md \
+   .agent/knowledge-base/[category]/KB-$(date +%Y-%m-%d)-###-[name].md
+```
+
+### 2. Fill Entry
+- Problem/Challenge
+- Solution
+- Implementation details
+- Learnings
+
+### 3. Sync to Neo4j
+```bash
+python tools/neo4j/sync_skills_to_neo4j.py
+```
+
+### 4. Update KB Index
+```bash
+python bin/kb_cli.py update-index
+```
+
+### 5. Record Success (Learning Engine)
+```bash
+python tools/neo4j/learning_engine.py --record-success "TASK-ID" --task-type "feature"
+```
+
+#compound #learning #knowledge-base
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/cycle.md

@@ -0,0 +1,61 @@
+---
+description: [Process] Complete Task Lifecycle - Plan → Work → Review → Compound
+---
+
+# /cycle - Complete Task Lifecycle
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **NO SKIPPING:** Every step is MANDATORY.
+2. **TEAM COMMUNICATION FIRST:** Announce start and check history.
+3. **GIT FLOW:** Feature branch, atomic commits, PR.
+4. **SELF-LEARNING:** After completion, update Neo4j.
+
+### 0.0 **Team Communication (MANDATORY):**
+   - **Check History:** `python tools/communication/cli.py history --channel general --limit 10`
+   - **Announce Start:** `python tools/communication/cli.py send --channel general --thread "SDLC-Flow" --role AGENT --content "Starting /cycle for [Task]."`
+
+## Workflow Steps
+
+### 1. Research Phase (MANDATORY)
+```bash
+python tools/research/research_agent.py --feature "[task]" --type feature
+```
+- [ ] Search KB for similar implementations.
+- [ ] Check GitHub issues for context.
+
+### 2. Planning
+- Define acceptance criteria.
+- Add task to `Development-Log.md`.
+
+### 3. Feature Branch
+```bash
+git checkout -b feat/TASK-ID-name
+git push -u origin feat/TASK-ID-name
+```
+
+### 4. Implementation
+- Code according to plan.
+- Atomic commits: `git commit -m "[TASK-ID] feat: description"`
+
+### 5. Verification
+- Run local tests.
+- Create PR, tag @TESTER.
+
+### 6. Merge
+- Wait for `#testing-passed`.
+- Merge via @DEVOPS or @SA.
+
+### 7. Self-Learning (MANDATORY)
+```bash
+python tools/neo4j/sync_skills_to_neo4j.py
+python tools/neo4j/learning_engine.py --record-success "TASK-ID" --task-type "feature"
+```
+- Update `CHANGELOG.md`.
+
+#cycle #workflow #git-flow #self-learning---
+## ⚠️ 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/emergency.md

@@ -0,0 +1,114 @@
+---
+description: [Process] Emergency/Hotfix Response Workflow
+---
+
+# /emergency - Critical Incident Response
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **IMMEDIATE ACTION:** This workflow takes priority over all other tasks.
+2. **TIME-BOXED ASSESSMENT:** Max 5 minutes for initial assessment.
+3. **MITIGATION FIRST:** Stop the bleeding before fixing root cause.
+4. **COMPOUND LEARNING:** Create KB entry after resolution (MANDATORY).
+
+### 0.0 **Declare Incident:**
+```bash
+python tools/workflows/emergency.py --severity P0 --issue "[issue description]"
+```
+
+## Severity Levels
+
+| Level | Response Time | Examples |
+|-------|--------------|----------|
+| **P0** | < 15 min | Production down, data loss, security breach |
+| **P1** | < 1 hour | Major feature broken, significant user impact |
+| **P2** | < 4 hours | Minor feature broken, workaround available |
+
+## Workflow Steps
+
+### 1. Declare Incident (Minute 0)
+- Assign incident ID: `INCIDENT-YYYYMMDDHHMMSS`
+- Create incident channel/thread
+- Notify stakeholders
+- Assign incident commander
+
+### 2. Rapid Assessment (5 min max)
+```bash
+# Search KB for similar incidents
+python tools/research/research_agent.py --task "[issue]" --type bug
+```
+**Quick Checks:**
+- [ ] Check monitoring/logs
+- [ ] Verify deployment timeline
+- [ ] Check external dependencies
+- [ ] Review recent commits
+
+### 3. Immediate Mitigation
+
+**Options (fastest first):**
+1. **Rollback** - Revert to last known good (~2 min)
+2. **Feature Flag** - Disable broken feature (~1 min)
+3. **Traffic** - Route around problem (~5 min)
+4. **Scale Up** - Add resources if capacity issue (~10 min)
+
+### 4. Root Cause Analysis
+While mitigation deploys:
+- Review error logs
+- Check monitoring dashboards
+- Reproduce in staging
+
+### 5. Hotfix Development (Fast Track)
+**Skip for speed:**
+- ❌ Full design review (document after)
+- ❌ Full test suite (critical path only)
+- ✅ Single reviewer approval
+
+```bash
+git checkout -b hotfix/INCIDENT-ID
+# Make minimal fix
+git commit -m "hotfix: description (#INCIDENT-ID)"
+```
+
+### 6. Verify Resolution
+- [ ] Error rate returned to normal
+- [ ] Key metrics recovered
+- [ ] User reports stopped
+- [ ] No new issues introduced
+
+### 7. Compound Learning (MANDATORY)
+```bash
+# Create KB entry automatically
+python tools/workflows/emergency.py --severity P0 --issue "[issue]"
+
+# Or manually update Neo4j
+python tools/neo4j/sync_skills_to_neo4j.py
+python tools/neo4j/learning_engine.py --record-error "ErrorType" "description" --resolution "fix"
+```
+
+### 8. Post-Incident
+- [ ] Schedule postmortem (within 24 hours)
+- [ ] Review and assign action items
+- [ ] Update runbooks if needed
+- [ ] Notify stakeholders of resolution
+
+## CLI Usage
+
+```bash
+# Interactive workflow
+python tools/workflows/emergency.py -s P0 -i "Payment gateway 500 errors"
+
+# Non-interactive (for automation)
+python tools/workflows/emergency.py -s P1 -i "API timeout" --non-interactive
+```
+
+## Output Artifacts
+- `docs/sprints/sprint-[N]/logs/Incident-Report-[ID].json`
+- KB entry in `.agent/knowledge-base/bugs/`
+
+#emergency #hotfix #incident #production #p0
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/explore.md

@@ -0,0 +1,147 @@
+---
+description: [Process] Deep Investigation Workflow
+---
+
+# /explore - Multi-Order Analysis
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **USE BEFORE PLANNING:** Run before major architectural decisions.
+2. **MULTI-ORDER THINKING:** Go beyond surface-level analysis.
+3. **EVIDENCE-BASED:** All findings must have supporting evidence.
+4. **DOCUMENT FINDINGS:** Create exploration report.
+
+## When to Use
+
+- **Complex Features:** Before implementing features with many dependencies
+- **Architecture Decisions:** Before major structural changes
+- **Unknown Territory:** When entering unfamiliar domains
+- **Risk Assessment:** Before high-impact changes
+
+## Workflow Steps
+
+### 1. First-Order Analysis (Surface Level)
+**Question:** What does the user want?
+
+```bash
+# Basic research
+python tools/research/research_agent.py --task "[feature]" --type general
+```
+
+- [ ] Understand explicit requirements
+- [ ] Identify immediate stakeholders
+- [ ] List obvious technical needs
+
+### 2. Second-Order Analysis (Dependencies)
+**Question:** What does this depend on?
+
+- [ ] Identify technical dependencies
+- [ ] Map affected components
+- [ ] Find related existing implementations
+
+```bash
+# Search KB for related entries
+python bin/kb_cli.py search "[related topic]"
+```
+
+### 3. Third-Order Analysis (Implications)
+**Question:** What are the ripple effects?
+
+- [ ] Performance implications
+- [ ] Security implications
+- [ ] Scalability considerations
+- [ ] Maintenance burden
+
+### 4. Fourth-Order Analysis (Hidden Risks)
+**Question:** What could go wrong that we haven't considered?
+
+- [ ] Edge cases
+- [ ] Failure modes
+- [ ] Integration conflicts
+- [ ] Future constraints
+
+```bash
+# Check for similar issues in KB
+python bin/kb_cli.py search "bug" --category bugs
+```
+
+### 5. Synthesis
+**Question:** What's the recommended approach?
+
+Create exploration report with:
+- Key findings per order of analysis
+- Risk assessment matrix
+- Recommended approach with rationale
+- Alternative approaches considered
+- Open questions requiring stakeholder input
+
+## Output Template
+
+```markdown
+# Exploration Report: [Feature/Decision]
+
+**Date:** YYYY-MM-DD  
+**Author:** @[ROLE]
+
+## Executive Summary
+[1-2 paragraph summary]
+
+## First-Order Analysis
+### User Requirements
+- ...
+
+## Second-Order Analysis
+### Dependencies
+- ...
+
+## Third-Order Analysis
+### Implications
+- ...
+
+## Fourth-Order Analysis
+### Hidden Risks
+- ...
+
+## Risk Matrix
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| ... | ... | ... | ... |
+
+## Recommendation
+[Recommended approach with rationale]
+
+## Alternatives Considered
+1. ...
+2. ...
+
+## Open Questions
+- [ ] ...
+```
+
+## Integration
+
+- **@PM** triggers before major planning
+- **@SA** uses for architecture decisions
+- **@SECA** incorporates in security review
+- **/cycle** may trigger for complex tasks
+
+## Example Usage
+
+```
+User: "We need to add OAuth authentication"
+
+/explore OAuth implementation
+
+First-Order: User wants social login
+Second-Order: Depends on token storage, session management, user model
+Third-Order: Affects all API endpoints, session timeout, refresh logic
+Fourth-Order: Token revocation, multi-device sessions, privacy compliance
+```
+
+#explore #analysis #research #architecture #risk-assessment
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+

package/.agent/workflows/housekeeping.md

@@ -0,0 +1,105 @@
+---
+description: [Support] Housekeeping - Cleanup and Maintenance
+---
+
+# /housekeeping - System Maintenance Workflow
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **RUN REGULARLY:** Execute at least once per sprint.
+2. **VERIFY HEALTH:** Ensure all indexes are updated.
+3. **ARCHIVE OLD DATA:** Move completed sprint data to archive.
+
+## Quick Command
+
+```bash
+python tools/workflows/housekeeping.py
+```
+
+## Workflow Steps
+
+### Step 1: Archive Old Sprints
+- Identifies completed sprints
+- Moves to `docs/archive/sprint-[N]/`
+- Preserves reference copies
+
+### Step 2: Fix Documentation Drift
+- Checks for stale references
+- Identifies broken links
+- Reports outdated documentation
+
+### Step 3: Update Indexes
+```bash
+# Updates KB index
+python bin/kb_cli.py update-index
+```
+- Regenerates `.agent/knowledge-base/INDEX.md`
+- Ensures all entries are indexed
+- Updates statistics
+
+### Step 4: Verify System Health
+Reports:
+- Total KB entries
+- Number of categories
+- Current sprint status
+- System health status
+
+## Expected Output
+
+```
+============================================================
+Housekeeping Workflow
+============================================================
+
+[INFO] Run housekeeping tasks? (Y/n): y
+
+============================================================
+Step 1: Archive Old Sprints
+============================================================
+[INFO] Checking for completed sprints...
+[OK] No sprints to archive
+
+============================================================
+Step 2: Fix Documentation Drift
+============================================================
+[INFO] Checking for documentation drift...
+[OK] No drift detected
+
+============================================================
+Step 3: Update Indexes
+============================================================
+[INFO] Updating knowledge base index...
+[OK] KB index updated
+
+============================================================
+Step 4: Verify System Health
+============================================================
+[INFO] Total KB entries: 12
+[INFO] Categories: 6
+[INFO] Current sprint: sprint-6
+[OK] System health check passed
+
+🎉 Housekeeping completed successfully!
+```
+
+## When to Run
+
+- **Weekly:** During sprint (recommended)
+- **End of Sprint:** Before closing sprint
+- **After Major Changes:** After bulk KB entries or documentation updates
+- **Before Release:** Ensure clean state
+
+## Related Workflows
+
+- **/brain** - For syncing Neo4j and LEANN
+- **/validate** - For checking workflow tool references
+- **/metrics** - For generating project statistics
+- **/sprint close** - Triggers housekeeping automatically
+
+#housekeeping #maintenance #cleanup #health-check
+
+
+---
+
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+