agentic-sdlc 1.6.0 → 1.8.1

package/docs/.brain-scores.json

@@ -0,0 +1,310 @@
+{
+  "scores": [
+    {
+      "file": "projects\\landing-page\\src\\components\\Features.astro",
+      "scores": {
+        "completeness": 0,
+        "quality": 8.5,
+        "compliance": 2
+      },
+      "finalScore": 3.4,
+      "passed": false,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:28:25.776905"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-landing-page-orchestrator.md",
+      "scores": {
+        "completeness": 0,
+        "quality": 8.5,
+        "compliance": 0
+      },
+      "finalScore": 2.5,
+      "passed": false,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:32:11.806806"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-landing-page-orchestrator.md",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 4
+      },
+      "finalScore": 7.1,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:33:57.519120"
+    },
+    {
+      "file": "projects\\landing-page\\src\\components\\Features.astro",
+      "type": "code",
+      "scores": {
+        "structure": 10.0,
+        "quality": 9,
+        "completeness": 9
+      },
+      "finalScore": 9.3,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:45:00.343382"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-landing-page-orchestrator.md",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 4
+      },
+      "finalScore": 7.1,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:45:04.197872"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-judge-enhancement.md",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 4
+      },
+      "finalScore": 7.1,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:46:24.661632"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-landing-page-orchestrator.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 7
+      },
+      "improvements": [
+        "Add code blocks with ``` → +1.5 quality",
+        "Add links to related .md files → +3 compliance"
+      ],
+      "finalScore": 8.3,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T09:53:27.263595"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-landing-page-orchestrator.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 10.0,
+        "compliance": 10
+      },
+      "improvements": [],
+      "finalScore": 10.0,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:22:55.679975"
+    },
+    {
+      "file": "docs\\reports\\Validation-Report-2026-01-05.md",
+      "type": "report",
+      "scores": {
+        "completeness": 0,
+        "quality": 6.5,
+        "compliance": 5
+      },
+      "improvements": [
+        "Add '## Problem' or '## Challenge' section → +2.5 completeness",
+        "Add '## Solution' or '## Implementation' section → +2.5 completeness",
+        "Add '## Artifacts' or '## Output' section → +2.5 completeness",
+        "Add '## Next Steps' or '## Actions' section → +2.5 completeness",
+        "Add more content (>500 chars) → +2 quality",
+        "Add code blocks with ``` → +1.5 quality",
+        "Add YAML frontmatter (---) at top → +2 compliance",
+        "Add links to related .md files → +3 compliance"
+      ],
+      "finalScore": 4.0,
+      "passed": false,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:36:59.243527"
+    },
+    {
+      "file": "docs\\reports\\Validation-Report-2026-01-05.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 10.0,
+        "compliance": 7
+      },
+      "improvements": [
+        "Add links to related .md files → +3 compliance"
+      ],
+      "finalScore": 8.8,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:38:47.659767"
+    },
+    {
+      "file": "docs\\reports\\Validation-Report-2026-01-05.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 10.0,
+        "compliance": 10
+      },
+      "improvements": [],
+      "finalScore": 10.0,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:39:15.430011"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-validation.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 10
+      },
+      "improvements": [
+        "Add code blocks with ``` → +1.5 quality"
+      ],
+      "finalScore": 9.5,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:39:42.013040"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-validation.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 8.5,
+        "compliance": 10
+      },
+      "improvements": [
+        "Add code blocks with ``` → +1.5 quality"
+      ],
+      "finalScore": 9.5,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T10:41:11.057977"
+    },
+    {
+      "file": "docs\\walkthroughs\\2026-01-05-workflow-audit.md",
+      "type": "report",
+      "scores": {
+        "completeness": 10.0,
+        "quality": 10.0,
+        "compliance": 5
+      },
+      "improvements": [
+        "Add hashtag tags like #walkthrough → +2 compliance",
+        "Add links to related .md files → +3 compliance"
+      ],
+      "finalScore": 8.0,
+      "passed": true,
+      "threshold": 6,
+      "timestamp": "2026-01-05T11:37:48.912264"
+    },
+    {
+      "file": "C:\\Users\\HOANG LAM\\.gemini\\antigravity\\brain\\f0371fce-9649-421a-97e7-9aea427efcbb\\walkthrough.md",
+      "type": "report",
+      "scores": {
+        "completeness": 0,
+        "quality": 8.5,
+        "compliance": 0
+      },
+      "finalScore": 2.5,
+      "passed": false,
+      "threshold": 6,
+      "improvements": [
+        "Add Problem section → +2.5",
+        "Add Solution section → +2.5",
+        "Add Artifacts section → +2.5",
+        "Add Next Steps section → +2.5",
+        "Add code blocks → +1.5",
+        "Add YAML frontmatter → +2",
+        "Add hashtags → +2",
+        "Move to docs/ subfolder → +3",
+        "Add links → +3"
+      ],
+      "timestamp": "2026-01-06T07:24:05.203744"
+    },
+    {
+      "file": "C:\\Users\\HOANG LAM\\.gemini\\antigravity\\brain\\f0371fce-9649-421a-97e7-9aea427efcbb\\test_execution_report.md",
+      "type": "report",
+      "scores": {
+        "completeness": 0,
+        "quality": 10.0,
+        "compliance": 2
+      },
+      "finalScore": 3.8,
+      "passed": false,
+      "threshold": 6,
+      "improvements": [
+        "Add Problem section → +2.5",
+        "Add Solution section → +2.5",
+        "Add Artifacts section → +2.5",
+        "Add Next Steps section → +2.5",
+        "Add YAML frontmatter → +2",
+        "Move to docs/ subfolder → +3",
+        "Add links → +3"
+      ],
+      "timestamp": "2026-01-06T07:43:32.050567"
+    },
+    {
+      "file": "GEMINI.md",
+      "type": "report",
+      "scores": {
+        "completeness": 5.0,
+        "quality": 10.0,
+        "compliance": 10
+      },
+      "finalScore": 8.5,
+      "passed": true,
+      "threshold": 6,
+      "improvements": [
+        "Add Problem/Goal section → +2.5",
+        "Add Solution/Approach section → +2.5"
+      ],
+      "timestamp": "2026-01-08T10:43:43.198673"
+    },
+    {
+      "file": "tools\\intelligence\\monitor\\resources.py",
+      "type": "code",
+      "scores": {
+        "structure": 10.0,
+        "quality": 10,
+        "completeness": 8
+      },
+      "finalScore": 9.4,
+      "passed": true,
+      "threshold": 6,
+      "improvements": [
+        "Add logic implementation → +2 completeness"
+      ],
+      "timestamp": "2026-01-08T21:00:12.480515"
+    },
+    {
+      "file": "tools\\intelligence\\monitor\\resources.py",
+      "type": "code",
+      "scores": {
+        "structure": 10.0,
+        "quality": 10,
+        "completeness": 8
+      },
+      "finalScore": 9.4,
+      "passed": true,
+      "threshold": 6,
+      "improvements": [
+        "Add logic implementation → +2 completeness"
+      ],
+      "timestamp": "2026-01-08T21:00:42.834044"
+    }
+  ],
+  "averageScore": 7.27,
+  "totalReviews": 19,
+  "passThreshold": 6,
+  "createdAt": "2026-01-05T09:28:25.776862",
+  "lastUpdated": "2026-01-08T21:00:42.834535"
+}

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?