agentic-sdlc 1.6.0 → 1.8.1

package/.agent/workflows/autogen.md

@@ -0,0 +1,65 @@
+---
+description: Process - Multi-Agent Task Execution with AutoGen
+---
+
+# AutoGen Workflow
+
+> **Skill Definition:** Multi-agent orchestration using Microsoft AutoGen framework
+
+// turbo-all
+
+## Overview
+Use AutoGen for complex tasks requiring autonomous multi-agent collaboration:
+- Debugging sessions
+- Code generation with testing
+- Research and synthesis
+
+## Usage
+
+### Single Agent
+```bash
+agentic-sdlc autogen --task "Write a Python function to parse JSON" --team dev
+```
+
+### Multi-Agent Team
+```bash
+agentic-sdlc autogen --task "Write and test a sorting algorithm" --team dev,tester
+```
+
+### With Custom Model
+```bash
+agentic-sdlc autogen --task "Debug login issue" --team dev --model gpt-4o
+```
+
+## Available Roles
+| Role | Description |
+|------|-------------|
+| `dev` | Developer - code implementation |
+| `tester` | Quality Assurance - testing and verification |
+| `orchestrator` | Coordinator - task breakdown and delegation |
+
+## Options
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--task, -t` | Task description (required) | - |
+| `--team` | Comma-separated roles | `dev` |
+| `--model, -m` | LLM model | `gemini-2.0-flash` |
+| `--max-turns` | Max conversation turns | `10` |
+
+## Examples
+
+### Debug a Bug
+```bash
+agentic-sdlc autogen -t "Find why login returns 401" --team dev,tester
+```
+
+### Generate Feature
+```bash
+agentic-sdlc autogen -t "Create REST API for user profiles" --team dev
+```
+
+## Requirements
+- `GOOGLE_GENAI_API_KEY` or `OPENAI_API_KEY` in `.env`
+- AutoGen packages installed: `pip install -r tools/requirements.txt`
+
+#autogen #multi-agent #automation

package/.agent/workflows/brain.md

@@ -1,5 +1,5 @@
 ---
-description: [Support] @BRAIN Meta-Level System Controller
+description: Support - BRAIN Meta-Level System Controller
 ---
 
 # Brain Workflow
@@ -12,75 +12,86 @@ Brain is NOT an executor—it monitors, detects issues, routes to handlers, scor
 
 // turbo-all
 
-## Root Components (Layer 1)
+## Root Components (Layer 2: Intelligence)
 
-### Observer (Halt on Errors)
+### Observer (Compliance Monitor)
 ```bash
-agentic-sdlc run tools/brain/observer.py --watch       # Monitor workflows
-agentic-sdlc run tools/brain/observer.py --halt "Err"  # Halt system
-agentic-sdlc run tools/brain/observer.py --resume      # Resume after halt
+# Check compliance of an action
+python tools/core/brain/brain_cli.py observe --action "create file" --context '{"file": "test.py"}'
+
+# Show compliance stats
+python tools/core/brain/brain_cli.py observe
 ```
 
-### Judge (Score Quality)
+### Judge (Quality Scorer)
 ```bash
-agentic-sdlc run tools/brain/judge.py --score "path/to/report.md"
-agentic-sdlc run tools/brain/judge.py --review --sprint 1
-agentic-sdlc run tools/brain/judge.py --threshold 7    # Set pass threshold
+# Score a file
+python tools/core/brain/brain_cli.py score "path/to/file.py"
+
+# Score a report
+python tools/core/brain/brain_cli.py score "docs/reports/latest.md"
 ```
 
 ### Learner (Auto-Learning)
 ```bash
-agentic-sdlc learn --learn "Task completed"
-agentic-sdlc learn --watch
-agentic-sdlc learn --stats
+# Record learning
+python tools/core/brain/brain_cli.py learn "Fixed bug in auth module by updating token expiry"
+
+# Get recommendations
+python tools/core/brain/brain_cli.py recommend "implement oauth"
 ```
 
-### A/B Tester (Compare Options)
+### A/B Tester (Decision Making)
 ```bash
-agentic-sdlc run tools/brain/ab_tester.py --create "Test description"
-agentic-sdlc run tools/brain/ab_tester.py --compare --test-id TEST-001
-agentic-sdlc run tools/brain/ab_tester.py --select A --test-id TEST-001
+# Run A/B test
+python tools/core/brain/brain_cli.py ab-test "Should we use JWT or Session Auth?"
 ```
 
-### Model Optimizer (Token Efficiency)
+### Router (Model Selection)
 ```bash
-agentic-sdlc run tools/brain/model_optimizer.py --recommend "Task description"
-agentic-sdlc run tools/brain/model_optimizer.py --record --model "gemini-2.5" --tokens 1500
+# Route request to optimal AI model
+python tools/core/brain/brain_cli.py route "Generate complex architectural diagram"
 ```
 
-### Self-Improver (Create Improvement Plans)
+### Artifact Generator
 ```bash
-agentic-sdlc run tools/brain/self_improver.py --analyze  # Analyze all data
-agentic-sdlc run tools/brain/self_improver.py --plan     # Create improvement plan
-agentic-sdlc run tools/brain/self_improver.py --apply-plan PLAN-ID
+# Generate document from template
+python tools/core/brain/brain_cli.py gen --template "project-plan" --context '{"project": "New App"}' --output "plan.md"
 ```
 
-## State Management
+### Health Monitor
 ```bash
-agentic-sdlc brain init 1          # Initialize sprint
-agentic-sdlc brain status          # Check status
-agentic-sdlc brain transition STATE --reason "Reason"
-agentic-sdlc brain validate        # Validate state
-agentic-sdlc brain rollback        # Rollback
+# Check system health
+python tools/core/brain/brain_cli.py health
+
+# Get improvement suggestions
+python tools/core/brain/brain_cli.py health --suggest
 ```
 
-## Supervisor Commands
+## State Management (Layer 1: Core)
 ```bash
-agentic-sdlc brain watch   # Monitor workflows
-agentic-sdlc run tools/brain/brain_cli.py route "request"  # Route to workflow
-agentic-sdlc health  # Health check
+python tools/core/brain/brain_cli.py init 1          # Initialize sprint
+python tools/core/brain/brain_cli.py status          # Check status
+python tools/core/brain/brain_cli.py transition STATE --reason "Reason"
+python tools/core/brain/brain_cli.py validate        # Validate state
+python tools/core/brain/brain_cli.py rollback        # Rollback
 ```
 
 ## Sync Commands
 ```bash
-agentic-sdlc kb compound sync
-agentic-sdlc kb compound sync --full
+python tools/core/brain/brain_cli.py sync      # Quick sync
+python tools/core/brain/brain_cli.py full-sync # Full sync
 ```
 
 #brain #root-layer #meta-controller
 
+## ⏭️ Next Steps
+- **If State == IDLE:** Wait for user requirements (Active Listening)
+- **If State == PLANNING:** Monitor @PM and validate Project Plan
+- **If Critical Error:** Trigger `/emergency` workflow
+- **If Task Complete:** Trigger `/compound` for learning
 
 ---
 
 ## ENFORCEMENT REMINDER
-Before executing, complete /preflight checks.
+Ensure KB is synced before major operations.

package/.agent/workflows/commit.md

@@ -0,0 +1,61 @@
+---
+description: Process - Automated Code Review and Commit
+---
+
+# /commit - Review and Commit Changes
+
+## ⚠️ PURPOSE
+Automates the process of reviewing changes, generating Conventional Commits messages, and saving progress.
+
+// turbo-all
+
+## When to Use
+- You have made code changes and want to save them.
+- You need to generate a structured commit message.
+- You want a quick sanity check (lint/diff) before committing.
+
+## Workflow Steps
+
+### 1. Check Status
+```bash
+python tools/infrastructure/git/commit.py review
+```
+
+### 2. Review Diff
+- **If files UNSTAGED:**
+  ```bash
+  git add .
+  ```
+- **If files STAGED:**
+  - Read `git diff --cached` to understand changes.
+```
+
+### 3. Generate Message
+- Format: `type(scope): description`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Example: `feat(auth): implement jwt login`
+
+### 4. Commit using Git
+```bash
+git commit -m "type(scope): description"
+```
+*Wait for user confirmation if in interactive mode, otherwise proceed if confident.*
+
+### 5. Verify
+```bash
+git log -1 --oneline
+```
+
+### 6. Push Changes
+- **If main or feature branch:**
+  ```bash
+  python tools/infrastructure/git/commit.py push
+  ```
+  *Or manually:* `git push`
+
+## ⏭️ Next Steps
+- **If Success:** Return to previous workflow (e.g., `/cycle`).
+
+---
+## ENFORCEMENT REMINDER
+Always use Conventional Commits format.

package/.agent/workflows/cycle.md

@@ -1,18 +1,21 @@
 ---
-description: [Process] Complete Task Lifecycle - Plan → Work → Review → Compound
+description: Process - Complete Task Lifecycle - Plan, Work, Review, Compound
 ---
 
 # /cycle - Complete Task Lifecycle
 
+Complete Task Lifecycle workflow for small to medium tasks. This workflow guides you through planning, implementation, testing, and knowledge capture.
+
 ## ⚠️ 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.
+5. **QUALITY CHECKS:** Run Observer and Judge before PR.
 
 ### 0.0 **Team Communication (MANDATORY):**
-   - **Check History:** `agentic-sdlc run tools/communication/cli.py history --channel general --limit 10`
-   - **Announce Start:** `agentic-sdlc run tools/communication/cli.py send --channel general --thread "SDLC-Flow" --role AGENT --content "Starting /cycle for [Task]."`
+   - **Check History:** `agentic-sdlc run tools/infrastructure/communication/cli.py history --channel general --limit 10`
+   - **Announce Start:** `agentic-sdlc run tools/infrastructure/communication/cli.py send --channel general --thread "SDLC-Flow" --role AGENT --content "Starting /cycle for [Task]."`
 
 ## Workflow Steps
 
@@ -26,6 +29,10 @@ agentic-sdlc research --feature "[task]" --type feature
 ### 2. Planning
 - Define acceptance criteria.
 - Add task to `Development-Log.md`.
+- **Observer Check:**
+  ```bash
+  python tools/core/brain/brain_cli.py observe --action "planning" --context '{"task": "[task]"}'
+  ```
 
 ### 3. Feature Branch
 ```bash
@@ -37,25 +44,39 @@ git push -u origin feat/TASK-ID-name
 - Code according to plan.
 - Atomic commits: `git commit -m "[TASK-ID] feat: description"`
 
-### 5. Verification
+### 5. Verification & Quality Assurance (MANDATORY)
 - Run local tests.
-- Create PR, tag @TESTER.
+- **Judge Score (Target > 8/10):**
+  ```bash
+  python tools/core/brain/brain_cli.py score "path/to/main_file.py"
+  ```
+- **Compliance Check:**
+  ```bash
+  python tools/core/brain/brain_cli.py observe
+  ```
 
 ### 6. Merge
+- Create PR, tag @TESTER.
 - Wait for `#testing-passed`.
 - Merge via @DEVOPS or @SA.
 
 ### 7. Self-Learning (MANDATORY)
 ```bash
 agentic-sdlc kb compound sync
-agentic-sdlc learn --record-success "TASK-ID" --task-type "feature"
+python tools/core/brain/brain_cli.py learn "Completed [task] using [approach]"
 ```
 - Update `CHANGELOG.md`.
 
-#cycle #workflow #git-flow #self-learning---
+#cycle #workflow #git-flow #self-learning
+
+## ⏭️ Next Steps
+- **If Compound Complete:** Workflow finished, ready for next task
+- **If Issues Found:** Repeat `/cycle` or escalate to `/explore`
+- **If Blocked:** Notify user via `notify_user`
+
+---
 ## ⚠️ 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.
+1. Search knowledge base for similar tasks
+2. Check current brain state
+3. Run /onboarding if new to project

package/.agent/workflows/debug.md

@@ -0,0 +1,123 @@
+---
+description: Process - Systematic Debugging Workflow
+---
+
+# /debug - Debugging Workflow
+
+## ⚠️ PURPOSE
+Systematic approach to debugging issues in development. Different from `/emergency` which is for production incidents.
+
+// turbo-all
+
+## When to Use
+
+- Local development bugs
+- Test failures
+- Unexpected behavior
+- Performance issues (dev environment)
+
+## Quick Commands
+
+```bash
+# Search KB for similar bugs
+agentic-sdlc kb search "error type" --category bugs
+
+# Check learning engine for similar errors
+agentic-sdlc learn --similar-errors "ErrorType"
+```
+
+## Workflow Steps
+
+### 1. Reproduce the Issue
+- [ ] Identify exact steps to reproduce
+- [ ] Note environment (OS, versions, config)
+- [ ] Capture error message/stack trace
+
+```bash
+# Run failing test in isolation
+bun test --watch [test-file]
+```
+
+### 2. Search Knowledge Base
+```bash
+# Check if similar bug was fixed before
+agentic-sdlc kb search "[error message]"
+
+# Check neo4j for patterns
+agentic-sdlc learn --similar-errors "[ErrorType]"
+```
+
+### 3. Isolate the Problem
+- [ ] Binary search: Comment out code to find the culprit
+- [ ] Check recent changes: `git log --oneline -10`
+- [ ] Review git blame: `git blame [file]`
+
+### 4. Identify Root Cause
+- [ ] Add logging/breakpoints
+- [ ] Check input data
+- [ ] Verify assumptions
+- [ ] Review dependencies
+
+```bash
+# Debug with verbose output
+DEBUG=* bun run [script]
+```
+
+### 5. Implement Fix
+- [ ] Write failing test first (TDD)
+- [ ] Implement minimal fix
+- [ ] Verify fix works
+
+```bash
+git commit -m "fix: [description of fix]"
+```
+
+### 6. Verify No Regression
+```bash
+# Run full test suite
+bun test
+
+# Run type check
+bun run typecheck
+```
+
+### 7. Document & Learn (MANDATORY)
+
+```bash
+# Record error pattern for future reference
+agentic-sdlc learn --record-error "ErrorType" "[description]" \
+  --resolution "[how it was fixed]" \
+  --approach "[debugging approach used]"
+
+# Sync KB
+agentic-sdlc kb compound sync
+```
+
+## Common Debug Strategies
+
+| Strategy | When to Use | Command |
+|----------|-------------|---------|
+| **Binary Search** | Large codebase, unknown location | Comment out half |
+| **Git Bisect** | Regression, worked before | `git bisect start` |
+| **Logging** | Runtime issues | Add console.log/print |
+| **Breakpoints** | Complex state | Use debugger |
+| **Rubber Duck** | Stuck, need fresh perspective | Explain to "duck" |
+
+## Integration
+
+- **@DEV** - Primary debugger
+- **@TESTER** - Verify fix with tests
+- **/emergency** - Escalate if production issue
+- **/compound** - Document solution (embedded)
+
+#debug #troubleshooting #bugs #development
+
+## ⏭️ Next Steps
+- **If Fixed:** Trigger `/cycle` to resume normal work
+- **If Root Cause Unknown:** Trigger `/explore` for deeper analysis
+- **If Hotfix Needed:** Trigger `/emergency` or `/release`
+
+---
+
+## ENFORCEMENT REMINDER
+Always record error patterns after fixing bugs.

package/.agent/workflows/deep-search.md

@@ -0,0 +1,82 @@
+---
+description: Intelligence - Deep Search MCP for Technical Research
+---
+
+# /deep-search - Technical Research Workflow
+
+Deep web search using DuckDuckGo, GitHub, and StackOverflow APIs.
+**No third-party AI services** - fully manual implementation.
+
+// turbo-all
+
+## Quick Commands
+
+```bash
+# Aggregated search (all sources)
+python mcp/connectors/deep_search.py --search "query"
+
+# DuckDuckGo only
+python mcp/connectors/deep_search.py --ddg "query"
+
+# GitHub repos/code
+python mcp/connectors/deep_search.py --github "query"
+
+# StackOverflow Q&A
+python mcp/connectors/deep_search.py --stackoverflow "query"
+
+# Check status
+python mcp/connectors/deep_search.py --status
+```
+
+## Available Tools
+
+| Tool | Description | API Key |
+|------|-------------|---------|
+| `deep_search` | Aggregated multi-source search | None |
+| `ddg_search` | DuckDuckGo web search | None |
+| `github_search` | GitHub repos/code/issues | Optional |
+| `stackoverflow_search` | Stack Overflow Q&A | None |
+| `fetch_content` | Extract content from URL | None |
+
+## Python Usage
+
+```python
+from mcp.connectors.deep_search import DeepSearchConnector
+import json
+
+connector = DeepSearchConnector()
+
+# Aggregated search
+result = connector.call_tool("deep_search", {"query": "Python async await"})
+print(json.dumps(result, indent=2))
+
+# GitHub with filters
+result = connector.call_tool("github_search", {
+    "query": "MCP connector",
+    "search_type": "repositories",
+    "language": "python",
+    "sort": "stars"
+})
+
+# StackOverflow with tags
+result = connector.call_tool("stackoverflow_search", {
+    "query": "async programming",
+    "tags": ["python", "asyncio"],
+    "sort": "votes"
+})
+```
+
+## Integration
+
+- **@RESEARCH** - Primary user for investigations
+- **@SA** - Architecture decision research
+- **@DEV** - Solution lookup
+- **/explore** - Deep investigation workflow
+- **/planning** - Requirements research
+
+#deep-search #research #mcp #technical
+
+## ⏭️ Next Steps
+- **If Found Solution:** Apply to implementation
+- **If Need More Info:** Use `fetch_content` to extract URL details
+- **If GitHub Rate Limited:** Set `GITHUB_TOKEN` env var

package/.agent/workflows/docs.md

@@ -0,0 +1,144 @@
+---
+description: Support - Documentation Creation Workflow
+---
+
+# /docs - Documentation Workflow
+
+## ⚠️ PURPOSE
+Systematic approach to creating and maintaining project documentation.
+
+// turbo-all
+
+## When to Use
+
+- Creating new documentation
+- Updating existing docs
+- Writing KB entries
+- API documentation
+- User guides
+
+## Types of Documentation
+
+| Type | Template | Location |
+|------|----------|----------|
+| API Docs | Inline/OpenAPI | `docs/api/` |
+| User Guide | `User-Guide-Template.md` | `docs/guides/` |
+| Architecture | `Architecture-Spec-Template.md` | `docs/architecture/` |
+| Sprint Report | `Sprint-Review-Template.md` | `docs/sprints/sprint-[N]/` |
+
+## Workflow Steps
+
+### 1. Identify Doc Type
+- What are you documenting?
+- Who is the audience?
+- What template should you use?
+
+### 2. Check Existing Docs
+```bash
+# Search for related docs
+find docs -name "*.md" | xargs grep -l "[topic]"
+
+# Check KB for similar entries
+agentic-sdlc kb search "[topic]"
+```
+
+### 3. Choose Template
+```bash
+# List available templates
+ls .agent/templates/
+
+# Copy template
+cp .agent/templates/[Template].md docs/[appropriate-folder]/[new-doc].md
+```
+
+### 4. Write Content
+
+**Structure Guidelines:**
+- Start with clear heading
+- Add overview/purpose section
+- Use code blocks for commands
+- Include examples
+- Add cross-references
+
+**Style Guidelines:**
+- Use active voice
+- Keep sentences short
+- Use bullet points/tables
+- Include visuals when helpful
+
+### 5. Add Metadata (for KB entries)
+```yaml
+---
+category: feature|bug|architecture|security|performance
+tags: [relevant, tags]
+date: YYYY-MM-DD
+author: @ROLE
+---
+```
+
+### 6. Review & Validate
+- [ ] Spelling/grammar check
+- [ ] Links work
+- [ ] Code examples are correct
+- [ ] Follows project conventions
+
+```bash
+# Check for broken links
+find docs -name "*.md" -exec grep -l "\[.*\](.*)" {} \;
+```
+
+### 7. Update Indexes
+```bash
+# Update KB index
+agentic-sdlc kb update-index
+
+# Sync to Neo4j
+agentic-sdlc kb compound sync
+```
+
+## Documentation Standards
+
+### Naming Convention
+```
+[Type]-[Topic]-[Sprint]-v[Version].md
+Example: Architecture-Auth-Sprint-6-v1.md
+```
+
+### Required Sections
+
+**For KB Entries:**
+- Problem/Challenge
+- Solution
+- Implementation
+- Learnings
+
+**For User Guides:**
+- Overview
+- Prerequisites
+- Steps
+- Troubleshooting
+
+**For API Docs:**
+- Endpoint
+- Parameters
+- Response
+- Examples
+
+## Integration
+
+- **@PM** - Project documentation
+- **@SA** - Architecture docs
+- **@DEV** - Code documentation
+- **@REPORTER** - Reports and summaries
+- **/release** - Changelog updates
+
+#docs #documentation #writing 
+
+## ⏭️ Next Steps
+- **If Docs Created:** Trigger `/review` for feedback
+- **If Index Updated:** Trigger `/housekeeping` to verify health
+
+---
+
+## ENFORCEMENT REMINDER
+Update KB index after adding new entries.