agentic-sdlc 1.5.1 → 1.8.1

package/docs/architecture/system-flow.mermaid

@@ -0,0 +1,81 @@
+graph TD
+    %% Actors
+    User([User])
+    
+    %% Brain Layer
+    Brain[Brain Meta-Controller]
+    Judge[Judge]
+    Learner[Learner]
+    
+    %% Workflows
+    Cycle["/cycle"]
+    Explore["/explore"]
+    Emergency["/emergency"]
+    Sprint["/sprint"]
+    Metrics["/metrics"]
+    
+    %% Roles
+    PM[Project Manager]
+    BA[Business Analyst]
+    SA[System Analyst]
+    UIUX[UI/UX Designer]
+    PO[Product Owner]
+    QA[Tester]
+    SecA[Security Analyst]
+    Dev[Developer]
+    DevOps[DevOps]
+    Reporter[Reporter]
+    Stakeholder[Stakeholder]
+    
+    %% Main Flow
+    User -->|Directives| Brain
+    Brain -->|Route| Cycle
+    Brain -->|Route| Explore
+    Brain -->|Route| Emergency
+    Brain -->|Route| Sprint
+    
+    %% Sprint Flow
+    Sprint -->|Start| PM
+    PM -->|Plan| BA
+    BA -->|Reqs| SA
+    BA -->|Reqs| UIUX
+    BA -->|Reqs| PO
+    
+    PO -->|Backlog| SA
+    PO -->|Backlog| UIUX
+    
+    SA -->|Design| QA
+    UIUX -->|Design| QA
+    
+    QA -->|Verify| SecA
+    SecA -->|Verify| Dev
+    
+    Dev -->|Code| DevOps
+    DevOps -->|Deploy| Tester["Tester/QA"]
+    
+    Tester -->|Pass| Reporter
+    Tester -->|Fail| Dev
+    
+    Reporter -->|Report| Stakeholder
+    Stakeholder -->|Approve| Brain
+    Stakeholder -->|Reject| PM
+    
+    %% Sub-flows
+    Cycle -->|Task| Dev
+    Explore -->|Analysis| PM
+    Emergency -->|Hotfix| Dev
+    
+    %% Feedback Loops
+    Brain -->|Score| Judge
+    Judge -->|Feedback| Brain
+    Brain -->|Learn| Learner
+    Learner -->|Update| Brain
+    
+    %% Next Steps (Explicit)
+    PM -.->|Next| SA
+    SA -.->|Next| QA
+    QA -.->|Next| Dev
+    Dev -.->|Next| Tester
+    Tester -.->|Next| Reporter
+    Reporter -.->|Next| Stakeholder
+    Stakeholder -.->|Next| Brain

package/docs/artifacts/2026-01-05-enforcement-gates-plan.md

@@ -0,0 +1,80 @@
+# Implementation Plan: Strengthen Brain Protocol Enforcement
+
+**Date:** 2026-01-05  
+**Issue:** Brain tools exist but not being called during agent sessions
+
+---
+
+## 🔴 User Identified Gaps
+
+| # | Gap | Current State | Required State |
+|---|-----|---------------|----------------|
+| 1 | **Observer** | Not halting on errors | MUST halt, fix, resume |
+| 2 | **A/B Testing** | Not used | Use for small tasks |
+| 3 | **Planning** | Jump to implementation | MUST plan first |
+| 4 | **Self-Improve** | Not running | Run after each session |
+| 5 | **Reports** | No artifacts | MUST create walkthrough |
+| 6 | **Housekeeping** | Not triggered | Run after task completion |
+
+---
+
+## Proposed Changes
+
+### [MODIFY] [GEMINI.md](file:///d:/dev/agentic-sdlc/GEMINI.md)
+
+Add **CRITICAL ENFORCEMENT GATES** section with mandatory checkpoints:
+
+```markdown
+## 🚨 CRITICAL ENFORCEMENT GATES
+
+### Gate 1: Pre-Task (BEFORE ANYTHING)
+```bash
+python tools/brain/observer.py --status
+python tools/brain/model_optimizer.py --recommend "[task]"
+```
+Decision: If task is small, consider A/B testing.
+
+### Gate 2: Planning (BEFORE CODE)
+- Create implementation_plan.md
+- Get user approval before execution
+
+### Gate 3: Error Handling
+If ANY script fails:
+1. STOP immediately
+2. Call: `python tools/brain/observer.py --halt "[error]"`
+3. Fix the issue
+4. Call: `python tools/brain/observer.py --resume`
+
+### Gate 4: Post-Task (AFTER COMPLETION)
+```bash
+python tools/brain/learner.py --learn "[task]"
+python tools/brain/judge.py --score "[artifact]"
+python tools/brain/self_improver.py --analyze
+python bin/kb_cli.py compound sync
+```
+
+### Gate 5: Reporting
+- Create walkthrough.md
+- Save to docs/walkthroughs/
+
+### Gate 6: Cleanup
+```bash
+python tools/workflows/housekeeping.py
+```
+```
+
+---
+
+## Verification Plan
+
+After implementation:
+1. Test a small task with A/B testing
+2. Intentionally cause an error to test halt
+3. Verify planning step is enforced
+4. Check report generation
+
+---
+
+## ❓ Awaiting Approval
+
+Proceed with strengthening GEMINI.md enforcement?

package/docs/artifacts/2026-01-05-workflow-analysis.md

@@ -0,0 +1,231 @@
+# 🔬 Workflow Analysis Report: Add/Remove Recommendations
+
+**Date:** 2026-01-05  
+**Purpose:** Deep analysis of `.agent/workflows/` to recommend additions and removals
+
+---
+
+## 📊 Current Workflow Inventory (13 workflows)
+
+| Workflow | Type | Size | Purpose |
+|----------|------|------|---------|
+| `brain.md` | Support | 2.6KB | Meta-level controller, sync, learning |
+| `compound.md` | Support | 1.0KB | Knowledge capture after tasks |
+| `cycle.md` | Process | 2.0KB | Task lifecycle (plan→work→review) |
+| `emergency.md` | Process | 3.3KB | Hotfix/incident response |
+| `explore.md` | Process | 3.5KB | Deep investigation |
+| `housekeeping.md` | Support | 2.9KB | Cleanup and maintenance |
+| `metrics.md` | Utility | 3.9KB | Project statistics |
+| `orchestrator.md` | Process | 2.2KB | Full SDLC automation |
+| `preflight.md` | Support | 1.0KB | Pre-task checks |
+| `release.md` | Support | 3.5KB | Changelog & versioning |
+| `route.md` | Support | 3.5KB | Workflow selection helper |
+| `sprint.md` | Process | 3.3KB | Sprint lifecycle |
+| `validate.md` | Utility | 3.7KB | Workflow compliance check |
+
+---
+
+## 🔴 RECOMMEND REMOVAL (3 workflows)
+
+### 1. ❌ REMOVE: `preflight.md`
+
+**Reason:**
+- **Redundancy:** This workflow duplicates the "Enforcement Reminder" that already exists at the bottom of EVERY workflow file
+- **Not automated:** Contains manual steps that AI agents already follow naturally
+- **Low value:** The GEMINI.md already enforces pre-flight checks via the "Pre-Flight Checklist" section
+- **Confusion:** Having both `preflight.md` AND enforcement reminders in each workflow creates duplication
+
+**Evidence:**
+```markdown
+# Every workflow ends with:
+## ENFORCEMENT REMINDER
+Before executing, complete /preflight checks.
+```
+
+**Alternative:** The enforcement is already embedded. Remove this standalone workflow.
+
+---
+
+### 2. ❌ REMOVE: `route.md`
+
+**Reason:**
+- **Redundancy with GEMINI.md:** The routing logic is already documented in `GEMINI.md` under "Role Activation Matrix" and "Slash Command Interpretation"
+- **Static content:** Contains no executable commands - it's purely reference documentation
+- **Better placement:** This should be reference documentation in `.agent/rules/` or `GEMINI.md`, not a workflow
+- **No /route command exists:** The routing happens automatically via `/orchestrator` and brain
+
+**Evidence:**
+- GEMINI.md already has:
+  ```markdown
+  ### Role Activation Matrix
+  | Task Type | Required Roles | Workflow |
+  |-----------|---------------|----------|
+  | New Feature/Project | @PM → @SA → @UIUX → @DEV → @TESTER | /orchestrator |
+  ```
+
+**Alternative:** Merge key content into `GEMINI.md` or `.agent/rules/global.md`
+
+---
+
+### 3. ❌ CONSIDER REMOVING: `compound.md`
+
+**Reason:**
+- **Already embedded in other workflows:** Both `/cycle` and `/emergency` already include compound learning steps (Step 7 in cycle, Step 7 in emergency)
+- **Very short (1KB):** Not enough value as standalone workflow
+- **Rarely invoked directly:** Users should use `/cycle` or `/emergency` which include compound learning
+
+**Evidence from cycle.md:**
+```markdown
+### 7. Self-Learning (MANDATORY)
+agentic-sdlc kb compound sync
+agentic-sdlc learn --record-success "TASK-ID" --task-type "feature"
+```
+
+**Alternative:** Keep as reference but mark as "called automatically by other workflows"
+
+---
+
+## 🟢 RECOMMEND ADDING (5 new workflows)
+
+### 1. ✅ ADD: `/review.md` - Code Review Workflow
+
+**Rationale:**
+- **Gap identified:** No dedicated workflow for PR reviews
+- **Current state:** `@TESTER` does design verification but no code review workflow
+- **High frequency task:** Code reviews happen daily
+
+**Proposed content:**
+- Quick PR review checklist
+- Integration with GitHub PR comments
+- Calling `@TESTER` and `@SECA` for specialized reviews
+- Link to KB for similar code patterns
+
+---
+
+### 2. ✅ ADD: `/debug.md` - Debugging Workflow
+
+**Rationale:**
+- **Gap identified:** No workflow for systematic debugging
+- **Different from /emergency:** Emergency is for production issues; debug is for local development
+- **High complexity task:** Debugging often takes 3+ hours, needs structure
+
+**Proposed content:**
+- Systematic debug steps (reproduce → isolate → identify → fix → verify)
+- Log analysis commands
+- Common debugging tools
+- KB search for similar bugs
+- Integration with `/compound` for learning
+
+---
+
+### 3. ✅ ADD: `/refactor.md` - Refactoring Workflow
+
+**Rationale:**
+- **Gap identified:** No workflow for safe refactoring
+- **High-risk activity:** Refactoring can break existing functionality
+- **Quality focus:** Needs verification steps
+
+**Proposed content:**
+- Scope definition (what's being refactored)
+- Test verification before/after
+- Atomic commits
+- Code review integration
+- **Key:** Run tests before AND after refactoring
+
+---
+
+### 4. ✅ ADD: `/onboarding.md` - New Agent Onboarding
+
+**Rationale:**
+- **Gap identified:** No workflow for new AI agents joining project
+- **Context needed:** New agents need to understand project structure
+- **Accelerate productivity:** Quick ramp-up for new sessions
+
+**Proposed content:**
+- Project structure overview
+- Key files to read first (`GEMINI.md`, `README.md`)
+- Current sprint status
+- KB search for relevant context
+- Active issues/tasks
+
+---
+
+### 5. ✅ ADD: `/docs.md` - Documentation Workflow
+
+**Rationale:**
+- **Gap identified:** No dedicated documentation workflow
+- **Current state:** `/cycle` mentions docs but no structure
+- **Quality:** Documentation often neglected
+
+**Proposed content:**
+- Types of docs (API, user guide, KB entry)
+- Template selection
+- Review process
+- Integration with `/release` for changelog
+
+---
+
+## 🟡 RECOMMEND IMPROVEMENTS (Existing workflows)
+
+### 1. 🔧 IMPROVE: `orchestrator.md`
+
+**Current issues:**
+- Very lightweight (2.2KB) for "Full SDLC Automation"
+- Missing detailed phase transitions
+- No artifact checklists per phase
+
+**Recommendation:**
+- Expand with detailed steps per phase
+- Add artifact requirements per phase
+- Add time estimates
+
+---
+
+### 2. 🔧 IMPROVE: `brain.md`
+
+**Current issues:**
+- References non-existent tools: `tools/brain/observer.py`, `tools/brain/judge.py`, etc.
+- Only `tools/brain/brain_cli.py` exists
+
+**Recommendation:**
+- Update to match actual tool inventory
+- Either create missing tools or remove references
+
+---
+
+### 3. 🔧 IMPROVE: `cycle.md`
+
+**Current issues:**
+- Team Communication step references tool that may not exist: `tools/communication/cli.py`
+- Missing explicit test requirements
+
+**Recommendation:**
+- Verify tool existence
+- Add explicit "run tests" step
+
+---
+
+## 📋 Summary
+
+| Action | Count | Workflows |
+|--------|-------|-----------|
+| **Remove** | 2-3 | `preflight.md`, `route.md`, (optionally `compound.md`) |
+| **Add** | 5 | `review.md`, `debug.md`, `refactor.md`, `onboarding.md`, `docs.md` |
+| **Improve** | 3 | `orchestrator.md`, `brain.md`, `cycle.md` |
+
+---
+
+## 🎯 Priority Order
+
+1. **P0 - Critical:** Add `/review.md` and `/debug.md` (most common use cases)
+2. **P1 - Important:** Remove `preflight.md` and `route.md` (reduce confusion)
+3. **P2 - Nice to have:** Add `/refactor.md`, `/onboarding.md`, `/docs.md`
+4. **P3 - Backlog:** Improve `orchestrator.md`, fix tool references
+
+---
+
+## ❓ Open Questions for User
+
+1. **Compound workflow:** Keep as standalone or merge into cycle/emergency?
+2. **Tool references:** Should we create missing brain tools or remove references?
+3. **Priority:** Which new workflows should we implement first?

package/docs/artifacts/README.md

@@ -0,0 +1,26 @@
+# Artifacts Directory
+
+This folder stores IDE-generated artifacts that must be persisted for self-learning.
+
+## What Goes Here
+
+| Artifact Type | Example |
+|---------------|---------|
+| Analysis reports | `2026-01-05-workflow-analysis.md` |
+| Task summaries | `2026-01-05-task-refactoring.md` |
+| Investigation reports | `2026-01-05-explore-auth.md` |
+| Gap analysis | `2026-01-05-gap-analysis.md` |
+
+## Naming Convention
+
+```
+[YYYY-MM-DD]-[task-name].md
+```
+
+## Sync to Neo4j
+
+After adding artifacts:
+
+```bash
+agentic-sdlc kb compound sync
+```

package/docs/guides/MCP-GUIDE.md

@@ -14,6 +14,7 @@ The following servers are integrated into the team roles. Ensure these are confi
 | **GitIngest** | Codebase snapshots | @ORCHESTRATOR, @REPORTER |
 | **Apidog** | API Testing & Design | @SA, @TESTER |
 | **Brave Search** | External Research | @PM, @PO |
+| **Deep Search** | Technical Research (DDG + GitHub + StackOverflow) | @RESEARCH, @SA, @DEV |
 | **Firecrawl** | Web Scraper / Log research | @SECA, @DEVOPS |
 | **Playwright** | E2E / Browser Testing | @QA, @TESTER |
 | **Context7** | Architecture Analysis | @SA, @DEV |

package/docs/reports/2026-01-05-autogen-evaluation.md

@@ -0,0 +1,64 @@
+# Evaluation Report: Microsoft AutoGen Integration
+
+**Date:** 2026-01-05
+**Status:** Draft
+**Author:** @BRAIN (Research)
+
+## 1. Executive Summary
+This report evaluates the applicability of **Microsoft AutoGen** (specifically v0.4+) to the **Agentic SDLC** project.
+
+**Conclusion:** AutoGen represents a significant paradigm shift from the current `CLI + Workflow` architecture to a `Runtime + Event-Driven` architecture. While it offers powerful capabilities for autonomous multi-agent collaboration and state management, a full migration would require substantial refactoring.
+**Recommendation:** We recommend a **Phased Adoption (Hybrid Approach)**, starting with a pilot implementation for the `@Orchestrator` role or a specific complex workflow (e.g., `/sprint`), while maintaining the existing stable CLI tools for atomic tasks.
+
+---
+
+## 2. Microsoft AutoGen Overview
+AutoGen is a framework for building event-driven, distributed, agentic applications.
+*   **Core Unit:** `ConversableAgent` (an object that can send/receive messages).
+*   **Key Features:**
+    *   **Multi-Agent Conversation:** Built-in patterns for Two-Agent Chat, Group Chat, and Hierarchical Chat.
+    *   **Human-in-the-loop:** `UserProxyAgent` allows seamless human intervention.
+    *   **Code Execution:** Native support for executing code (Docker/Local) within conversations.
+    *   **Tool Use:** Agents can be equipped with functions (Tools) to interact with the environment.
+    *   **Ecosystem:** v0.4 introduces an event-driven architecture, enabling distributed agents and better scalability.
+
+## 3. Current "Agentic SDLC" Architecture Analysis
+The current system acts as a **Meta-Level Controller** using a "Brain" workflow.
+*   **Architecture:** `CLI-First`. Interactions are discrete tool calls driven by prompt engineering and static Markdown definitions (`.agent/skills/`, `.agent/workflows/`).
+*   **Execution Model:** "Run & Stop". Scripts in `tools/` run, perform an action, and exit. State is persisted in files (Markdown, JSON) or Neo4j.
+*   **Pros:** Simple, transparent, stateless (easy to debug), strongly typed workflows (Markdown).
+*   **Cons:** Limited "autonomy" between steps; rigid workflow adherence; limited inter-agent negotiation (requires user as relay).
+
+## 4. Gap Analysis
+
+| Feature | Agentic SDLC (Current) | Microsoft AutoGen (Target) | Gap/Bridge |
+| :--- | :--- | :--- | :--- |
+| **Agent Definition** | Markdown Prompts + CLI Tools | Python Classes (`AssistantAgent`) | Requires wrapping Prompts into Class metadata. |
+| **Communication** | Invisible (Prompt -> Tool -> Output) | Explicit Message Passing | Needs a message loop (runtime). |
+| **Orchestration** | User / Static Workflow Files | Dynamic GroupChat Manager | AutoGen excels here. |
+| **Human Inputs** | `notify_user` / Interrupts | `UserProxyAgent` | Direct replacement possible. |
+| **Tools** | `tools/` directory (Python scripts) | `autogen.tools` | Existing tools can be registered easily. |
+
+## 5. Integration Scenarios
+
+### Scenario A: The "Super-Tool" (Recommended Pilot)
+Treat AutoGen as a *Tool* within the existing SDLC.
+*   **Concept:** Create a new tool `tools/autogen/runner.py`.
+*   **Usage:** The current Brain invokes this tool to spin up a simpler sub-team (e.g., "Solver Team: Dev + Tester") to solve a specific hard problem autonomously.
+*   **Pros:** Low risk, high value for complex tasks.
+*   **Cons:** Context switching between "System Agent" and "AutoGen Sub-agents".
+
+### Scenario B: The "Brain Replacement" (Long Term)
+Refactor the entire `bin/agentic-sdlc` CLI to wrap an AutoGen runtime.
+*   **Concept:** When the user types `/orchestrator`, it launches a persistent AutoGen `GroupChat` involving `@PM`, `@Dev`, etc.
+*   **Pros:** True agentic autonomy, dynamic planning.
+*   **Cons:** Complete rewrite of the Supervisor layer.
+
+## 6. Proposed Pilot: "The Auto-Coder"
+We propose building a pilot module using AutoGen to handle the `/emergency` or `/debug` workflow.
+**Objective:** Give an AutoGen "Debugger Agent" access to `grep`, `read_file`, and `run_test` tools and let it autonomously find root causes without constant user prompting.
+
+## 7. Next Steps
+1.  **Prototype:** Create a `tools/experiment/autogen_pilot.py`.
+2.  **Define:** Map the `@DEV` and `@TESTER` roles to AutoGen definitions.
+3.  **Evaluate:** Measure if the AutoGen loop resolves bugs faster than the manual `/debug` workflow.

package/docs/reports/2026-01-05-brain-layer-analysis.md

@@ -0,0 +1,109 @@
+# 🧠 Brain Root Layer Analysis
+
+**Date:** 2026-01-05  
+**Issue:** Brain components not working during agent chat
+
+---
+
+## Current State: All Tools EXIST ✅
+
+| Component | Script | Lines | Status |
+|-----------|--------|-------|--------|
+| Observer | `tools/brain/observer.py` | 297 | ✅ Implemented |
+| Judge | `tools/brain/judge.py` | 341 | ✅ Implemented |
+| Learner | `tools/brain/learner.py` | 298 | ✅ Implemented |
+| A/B Tester | `tools/brain/ab_tester.py` | 353 | ✅ Implemented |
+| Model Optimizer | `tools/brain/model_optimizer.py` | 341 | ✅ Implemented |
+| Self-Improver | `tools/brain/self_improver.py` | 372 | ✅ Implemented |
+
+---
+
+## 🔴 The Problem
+
+The brain tools are **standalone CLI scripts** that must be called explicitly. They do NOT:
+- Auto-run when agent starts a session
+- Monitor chat in real-time
+- Intercept agent actions
+- Auto-trigger learning after tasks
+
+**Current reality:**
+```
+User Chat → Agent → Executes Task
+                  ↓
+          (Brain tools NOT called)
+```
+
+**Expected:**
+```
+User Chat → Agent → Brain Observer watches
+                  → Agent Executes Task
+                  → Judge scores result
+                  → Learner records patterns
+                  → Self-Improver updates rules
+```
+
+---
+
+## 🟢 Solution Options
+
+### Option 1: IDE Integration (Best but Hard)
+**How:** IDE hooks call brain tools before/after each agent action.
+- **Cursor:** Custom MCP server
+- **Windsurf:** Cascade plugin
+- **Antigravity:** Extension hooks
+
+**Pros:** Fully automatic, no agent changes needed
+**Cons:** Requires IDE-specific development
+
+---
+
+### Option 2: Agent Protocol (Recommended)
+**How:** Add mandatory steps to GEMINI.md that agents MUST follow:
+
+```markdown
+## Brain Protocol (MANDATORY)
+
+Before EVERY task:
+1. Check observer status: `python tools/brain/observer.py --status`
+2. Get model recommendation: `python tools/brain/model_optimizer.py --recommend "[task]"`
+
+After EVERY task:
+1. Score result: `python tools/brain/judge.py --score "[artifact]"`
+2. Trigger learning: `python tools/brain/learner.py --learn "[description]"`
+3. Record A/B if applicable
+```
+
+**Pros:** Works now, no IDE changes
+**Cons:** Relies on agent compliance
+
+---
+
+### Option 3: Batch/Scheduled (Easiest)
+**How:** Run brain analysis periodically, not per-task.
+
+```bash
+# Daily brain sync (add to workflow)
+python tools/brain/observer.py --watch
+python tools/brain/self_improver.py --analyze
+python tools/brain/self_improver.py --plan
+```
+
+**Pros:** Simple, low overhead
+**Cons:** Not real-time
+
+---
+
+## 📋 Recommendation: Option 2 + Option 3
+
+1. **Update GEMINI.md** with mandatory brain protocol
+2. **Add brain check to `/onboarding`**
+3. **Add brain sync to `/housekeeping`**
+4. **Future:** Build MCP server for full integration
+
+---
+
+## ❓ Questions for User
+
+1. Implement Option 2 (add brain protocol to GEMINI.md)?
+2. Add brain hooks to existing workflows?
+3. Build MCP server for Cursor/Windsurf (future)?