agentic-sdlc 1.5.1 → 1.8.1

package/.agent/rules/agent-execution.md

@@ -0,0 +1,55 @@
+---
+title: Agent Execution Rules
+version: 1.0.0
+category: rule
+priority: critical
+---
+# Agent Execution Rules
+## Agent Behavior Rules
+### Core Principles
+1. **Single Responsibility** - Each agent focuses on its defined role
+2. **Explicit Handoffs** - Never assume another agent's work is done
+3. **Transparency** - Log all significant decisions
+4. **Non-Destructive** - Prefer reversible actions
+### Execution Boundaries
+- Stay within assigned role scope
+- Request escalation for out-of-scope work
+- Never modify files outside designated areas
+- Always verify before destructive operations
+---
+## Inter-Agent Communication
+### Communication Channels
+| Channel | Purpose | Participants |
+|---------|---------|--------------|
+| general | Announcements, status updates | All agents |
+| planning | Design discussions | PM, SA, BA, UIUX |
+| development | Code discussions | DEV, TESTER, DEVOPS |
+| reviews | PR and design reviews | SA, SECA, TESTER |
+### Message Format
+[ROLE] -> [TARGET]: [MESSAGE]
+Example: DEV -> TESTER: Feature X ready for testing (#123)
+---
+## Handoff Procedures
+### Standard Handoff Flow
+PM -> SA: Requirements approved, design needed
+SA -> UIUX: Architecture approved, UI design needed
+UIUX -> DEV: Designs approved, implementation ready
+DEV -> TESTER: Code complete, testing needed
+TESTER -> DEVOPS: Tests passed, deployment ready
+---
+## Escalation Rules
+| Level | Trigger | Escalate To |
+|-------|---------|-------------|
+| L1 | Clarification needed | Direct predecessor |
+| L2 | Blocked > 1 hour | PM |
+| L3 | Critical/Security issue | PM + SECA |
+| L4 | Production incident | DEVOPS + PM (emergency) |
+---
+## Error Handling
+### On Error
+1. STOP current operation
+2. Log error details
+3. Assess impact
+4. Attempt recovery if safe
+5. Escalate if unrecoverable
+#rules #agent-execution #communication

package/.agent/rules/ai-enforcement.md

@@ -3,9 +3,10 @@
 ### Pre-Task Requirements
 1. **Read Workflow File First** - When user types /command, READ .agent/workflows/[command].md before any action
 2. **Activate Appropriate Roles** - Check the Role Activation Matrix in GEMINI.md
-3. **Follow State Machine** - Run python tools/brain/brain_cli.py status to check current state  
-4. **Search Knowledge Base** - Before implementing, search .agent/knowledge-base/INDEX.md
-5. **Document Learnings** - After task completion, consider KB entry if solution was non-obvious
+3. **Follow State Machine** - Run python tools/brain/brain_cli.py status to check current state
+4. **Search Brain** - Before implementing, run `agentic-sdlc learn --search "[keywords]"`
+5. **Create Specification** - For new features, create `specification.md` BEFORE `implementation_plan.md`
+6. **Document Learnings** - After task completion, consider KB entry if solution was non-obvious
 ### Violation = System Failure
 If an AI agent implements without following workflows, the brain system is NOT being used.
 ---

package/.agent/rules/artifacts.md

@@ -1,77 +1,79 @@
----
-description: Artifact and Naming Conventions
----
-# Artifact & Naming Conventions
-## ⚠️ DOCUMENTATION LOCATION RULE (PROJECT-SPECIFIC)
-Documentation MUST be located within each project's directory, NOT in the root docs/ folder (except for global guides).
-### Correct Structure
-`
-root/
-├── docs/ (Global System Docs ONLY)
-│   ├── ARCHITECTURE.md
-│   └── BRAIN-GUIDE.md
-│
-└── projects/
-    └── [project-name]/
-        └── docs/ (Project Specific Docs)
-            └── sprints/
-                └── sprint-[N]/
-                    ├── plans/
-                    ├── requirements/
-                    ├── designs/
-                    └── logs/
-`
-## Artifact Naming Convention
-Use versioned names attached to the current Sprint:
-| Artifact | Owner |
-|----------|-------|
-| Project-Plan-Sprint-[N]-v*.md | PM |
-| Product-Backlog-Sprint-[N]-v*.md | PO |
-| UIUX-Design-Spec-Sprint-[N]-v*.md | UIUX |
-| System-Design-Spec-Sprint-[N]-v*.md | SA |
-| Design-Verification-Report-Sprint-[N]-v*.md | QA |
-| Security-Review-Report-Sprint-[N]-v*.md | SecA |
-| Development-Log-Sprint-[N]-v*.md | DEV |
-| DevOps-Plan-and-Log-Sprint-[N]-v*.md | DevOps |
-| Test-Report-Sprint-[N]-v*.md | TESTER |
-| Phase-Report-Sprint-[N]-v*.md | REPORTER |
-| Master-Documentation.md | REPORTER |
-| Final-Project-Report.md | REPORTER |
-| Final-Approval-Report.md | STAKEHOLDER |
-## ⚠️ CRITICAL LOCATION RULE (SPRINT FOLDERS)
-ALL project artifacts MUST be created in the **PROJECT'S** workspace with organized structure based on **Sprint**:
-**Base Directory:** projects/[project-name]/docs/sprints/sprint-[N]/
-| Category | Folder Path | Content Example | Owner |
-|----------|-------------|-----------------|-------|
-| Plans | .../plans/ | Project-Plan-Sprint-[N]-v*.md, Product-Backlog-Sprint-[N]-v*.md | PM, PO |
-| Designs | .../designs/ | System-Design-Spec-Sprint-[N]-v*.md, UIUX-Design-Spec-Sprint-[N]-v*.md | SA, UIUX |
-| Reviews | .../reviews/ | Design-Verification-Report-Sprint-[N]-v*.md, Security-Review-Report-Sprint-[N]-v*.md | QA, SecA |
-| Logs | .../logs/ | Development-Log-Sprint-[N]-v*.md, DevOps-Plan-and-Log-Sprint-[N]-v*.md | DEV, DevOps |
-| Tests | .../tests/ | Test-Report-Sprint-[N]-v*.md | TESTER |
-| Reports | .../reports/ | Phase-Report-Sprint-[N]-v*.md | REPORTER |
-| Global | .../global/reports/ | Final-Project-Report.md, Final-Approval-Report.md | REPORTER, STAKEHOLDER |
-| Global | projects/[project-name]/docs/global/ | Master-Documentation.md | REPORTER |
-**FORBIDDEN LOCATIONS:**
-- .agent/ directory (reserved for instructions only)
-- Global docs/ folder for project-specific artifacts.
-## ⚠️ CHANGELOG RULE
-**CRITICAL:** Do NOT create or update CHANGELOG.md in the project root.
-- CHANGELOG.md exists ONLY as a template in .agent/templates/
-- All project changes are documented in sprint-specific reports
-- Use Phase-Report-Sprint-[N]-v*.md for sprint summaries
-- Use Final-Project-Report.md for overall project changelog
-## Mandatory Documentation Tags
-Every action must be tagged with appropriate hashtags:
-| Category | Tags |
-|----------|------|
-| **Planning** | #planning, #product-owner, #backlog |
-| **Design** | #designing, #uiux-design |
-| **Verification** | #verify-design, #security-review |
-| **Development** | #development, #devops |
-| **Testing** | #testing |
-| **Bug Fixes** | #fixbug-critical, #fixbug-high, #fixbug-medium, #fixbug-low |
-| **Status** | #blocked, #hotfix, #rollback |
-| **Deployment** | #deployed-staging, #deployed-production |
-| **Research** | #searching |
-| **Reporting** | #reporting, #stakeholder-review |
-| **Knowledge** | #knowledge-base, #lessons-learned |
+---
+description: Artifact and Naming Conventions
+---
+# Artifact & Naming Conventions
+## ⚠️ DOCUMENTATION LOCATION RULE (PROJECT-SPECIFIC)
+Documentation MUST be located within each project's directory, NOT in the root docs/ folder (except for global guides).
+### Correct Structure
+`
+root/
+├── docs/ (Global System Docs ONLY)
+│   ├── ARCHITECTURE.md
+│   └── BRAIN-GUIDE.md
+│
+└── projects/
+    └── [project-name]/
+        └── docs/ (Project Specific Docs)
+            └── sprints/
+                └── sprint-[N]/
+                    ├── plans/
+                    ├── requirements/
+                    ├── designs/
+                    └── logs/
+`
+## Artifact Naming Convention
+Use versioned names attached to the current Sprint:
+| Artifact | Owner |
+|----------|-------|
+| Project-Plan-Sprint-[N]-v*.md | PM |
+| Product-Backlog-Sprint-[N]-v*.md | PO |
+| UIUX-Design-Spec-Sprint-[N]-v*.md | UIUX |
+| System-Design-Spec-Sprint-[N]-v*.md | SA |
+| Design-Verification-Report-Sprint-[N]-v*.md | QA |
+| Security-Review-Report-Sprint-[N]-v*.md | SecA |
+| Development-Log-Sprint-[N]-v*.md | DEV |
+| DevOps-Plan-and-Log-Sprint-[N]-v*.md | DevOps |
+| Test-Report-Sprint-[N]-v*.md | TESTER |
+| Phase-Report-Sprint-[N]-v*.md | REPORTER |
+| Master-Documentation.md | REPORTER |
+| Final-Project-Report.md | REPORTER |
+| Final-Approval-Report.md | STAKEHOLDER |
+## ⚠️ CRITICAL LOCATION RULE (SPRINT FOLDERS)
+ALL project artifacts MUST be created in the **PROJECT'S** workspace with organized structure based on **Sprint**:
+**Base Directory:** projects/[project-name]/docs/sprints/sprint-[N]/
+| Category | Folder Path | Content Example | Owner |
+|----------|-------------|-----------------|-------|
+| Plans | .../plans/ | Project-Plan-Sprint-[N]-v*.md, Product-Backlog-Sprint-[N]-v*.md | PM, PO |
+| Designs | .../designs/ | System-Design-Spec-Sprint-[N]-v*.md, UIUX-Design-Spec-Sprint-[N]-v*.md | SA, UIUX |
+| Reviews | .../reviews/ | Design-Verification-Report-Sprint-[N]-v*.md, Security-Review-Report-Sprint-[N]-v*.md | QA, SecA |
+| Logs | .../logs/ | Development-Log-Sprint-[N]-v*.md, DevOps-Plan-and-Log-Sprint-[N]-v*.md | DEV, DevOps |
+| Tests | .../tests/ | Test-Report-Sprint-[N]-v*.md | TESTER |
+| Reports | .../reports/ | Phase-Report-Sprint-[N]-v*.md | REPORTER |
+| Global | .../global/reports/ | Final-Project-Report.md, Final-Approval-Report.md | REPORTER, STAKEHOLDER |
+| Global | projects/[project-name]/docs/global/ | Master-Documentation.md | REPORTER |
+**FORBIDDEN LOCATIONS:**
+- .agent/ directory (reserved for instructions only)
+- Global docs/ folder for project-specific artifacts.
+## ⚠️ CHANGELOG RULE (UPDATED 2026-01-04)
+**Repository vs Project:**
+1. **Root CHANGELOG.md:** ALLOWED for **Repository versioning only**.
+   - MUST be managed AUTOMATICALLY by `release.py`.
+   - Manual edits are FORBIDDEN except for fixing formatting.
+2. **Project Reports:**
+   - Detailed project changes must still be documented in sprint reports.
+   - Use Phase-Report-Sprint-[N]-v*.md for detailed tracking.
+## Mandatory Documentation Tags
+Every action must be tagged with appropriate hashtags:
+| Category | Tags |
+|----------|------|
+| **Planning** | #planning, #product-owner, #backlog |
+| **Design** | #designing, #uiux-design |
+| **Verification** | #verify-design, #security-review |
+| **Development** | #development, #devops |
+| **Testing** | #testing |
+| **Bug Fixes** | #fixbug-critical, #fixbug-high, #fixbug-medium, #fixbug-low |
+| **Status** | #blocked, #hotfix, #rollback |
+| **Deployment** | #deployed-staging, #deployed-production |
+| **Research** | #searching |
+| **Reporting** | #reporting, #stakeholder-review |
+

package/.agent/rules/auto-learning.md

@@ -0,0 +1,78 @@
+# 🧠 Automatic Knowledge Base Learning System
+## Purpose
+This system automatically captures and stores knowledge from every task, issue, and bug fix into the **Neo4j Project Brain** to build intelligence over time.
+---
+## 🔄 Auto-Learning Triggers
+### Mandatory Knowledge Capture
+The following events **MUST** trigger automatic knowledge capture via gentic-sdlc learn (or learning_engine.py):
+| Event | Trigger Condition | Measure |
+|-------|------------------|---------|
+| **Bug Fixed** | Any bug with priority medium+ | Record error pattern & fix |
+| **Multiple Attempts** | Task required 3+ attempts | Record complexity & approach |
+| **Error Pattern** | Same error occurred 2+ times | Record error resolution |
+| **Complex Feature** | Implementation took 4+ hours | Record feature implementation details |
+| **Security Issue** | Any vulnerability found | Record vulnerability & patch |
+| **Performance Fix** | Optimization applied | Record optimization technique |
+| **Architecture Decision** | Major design choice | Record decision reasoning |
+---
+## 📝 Learning Workflow
+### Step 1: Detection (Automatic via Agent)
+When completing a task, verify if it meets any learning criteria.
+### Step 2: Capture (Command Line)
+Use the CLI to record the learning immediately:
+`ash
+# General success recording
+agentic-sdlc learn --record-success "task-id" --task-type "feature" --success-approach "Used strategy X"
+# Error pattern recording
+agentic-sdlc learn --record-error "TypeError" "Cannot read property of undefined" --resolution "Added null check"
+# Explicit recording
+python tools/neo4j/learning_engine.py --record-success "..."
+`
+### Step 3: Storage (Neo4j)
+The system automatically:
+1. Creates a **KnowledgeNode** in Neo4j.
+2. Extracts metadata (error type, tags, component).
+3. Links it to the current **Sprint**, **Role**, and **Task**.
+4. Updates **LEANN** vector index for semantic search.
+### Step 4: Retrieval (Brain Search)
+Agents must recall this info using:
+`ash
+agentic-sdlc learn --search "authentication error"
+# or
+python tools/neo4j/brain_parallel.py --recommend "task description"
+`
+---
+## 🎯 Role-Specific Auto-Learning
+### @DEV - Development
+- **Focus:** Code patterns, bug fixes, performance tricks.
+- **Example:** gentic-sdlc learn --record-error "ConnectionRefused" "Db container not ready" --resolution "Added wait-for-it script"
+### @DEVOPS - Infrastructure
+- **Focus:** Deployment configs, pipeline fixes.
+- **Example:** gentic-sdlc learn --record-success "deploy-fix" --task-type "hotfix" --success-approach "Increased memory limit"
+### @TESTER - QA
+- **Focus:** Flaky tests, edge cases.
+- **Example:** gentic-sdlc learn --record-error "TimeoutError" "Test took too long" --resolution "Mocked external API"
+### @SA - Architecture
+- **Focus:** Design patterns, trade-offs.
+- **Example:** gentic-sdlc learn --record-success "auth-system" --task-type "architecture" --success-approach "JWT with refresh tokens"
+---
+## 🔍 Pre-Task Usage (Mandatory)
+Before starting ANY task, agents **MUST**:
+1. **Ask the Brain:**
+   `ash
+   agentic-sdlc learn --recommend "Implement user login"
+   `
+2. **Check for Past Errors:**
+   `ash
+   agentic-sdlc learn --similar-errors "Auth failed"
+   `
+3. **Apply Learnings:**
+   - Use returned patterns.
+   - Avoid listed anti-patterns.
+---
+## 🔄 Continuous Improvement Loop
+1. **Capture:** Agents record data during/after tasks.
+2. **Synthesize:** Weekly job (cron) runs learning_engine.py --analyze.
+3. **Optimize:** Brain suggests process improvements based on recurring issues.
+---
+#auto-learning #brain #neo4j #continuous-improvement

package/.agent/rules/code-quality.md

@@ -0,0 +1,40 @@
+---
+title: Code Quality Standards
+version: 1.0.0
+category: rule
+priority: high
+---
+# Code Quality Standards
+## Language-Specific Linting
+### Python
+- Linter: ruff or flake8
+- Formatter: black with default settings
+- Type Checker: mypy in strict mode
+- Max Line Length: 88 characters
+### JavaScript / TypeScript
+- Linter: eslint with recommended rules
+- Formatter: prettier
+- Max Line Length: 100 characters
+### Rust
+- Linter: clippy with pedantic warnings
+- Formatter: rustfmt
+## Test Coverage Requirements
+| Project Type | Minimum Coverage | Target Coverage |
+|--------------|------------------|-----------------|
+| Core/Critical | 80% | 90% |
+| Feature Code | 70% | 80% |
+| Utilities | 60% | 70% |
+| Scripts | 40% | 60% |
+## Code Complexity Rules
+- Cyclomatic Complexity: <= 10 per function
+- Nesting Depth: <= 4 levels
+- Function Length: <= 50 lines
+- File Length: <= 400 lines
+- Parameters: <= 5 per function
+## Security Standards
+- NO hardcoded secrets or API keys
+- NO SQL injection vulnerabilities
+- Use parameterized queries
+- Validate and sanitize all inputs
+- Use environment variables for secrets
+#rules #code-quality #standards

package/.agent/rules/git-workflow.md

@@ -1,25 +1,45 @@
----
-description: Unified Git and Task Workflow (Branching, Committing, Merging)
----
-# Git & Task Management Workflow
-**Requirement:** All tasks and artifacts must follow the **Branch-Based Workflow**.
-## A. Branching Strategy (MANDATORY)
-❌ **NEVER** commit directly to main or master.
-### Branch Naming Convention
-| Type | Prefix | Use Case |
-|------|--------|----------|
-| **Planning** | plan/ | Project plans, product backlogs |
-| **Design** | design/ | Architecture schematics, UI specs |
-| **Feature** | eat/ | New functionality |
-| **Fix** | ix/ | Bug fixes |
-| **Docs** | docs/ | General documentation |
-**Format:** prefix/TASK-ID-short-name (e.g., plan/SPRINT-2-setup)
-### Workflow
-1. **Start:** git checkout -b prefix/TASK-ID-name from main.
-2. **Work:** Create artifacts or code.
-3. **Push:** git push -u origin prefix/TASK-ID-name.
-4. **Docs-as-Code:** Treat documentation exactly like code.
-## B. Definition of Done (DoD)
-1. Branch created.
-2. Artifacts implemented.
+---
+description: Unified Git and Task Workflow (Branching, Committing, Merging)
+---
+# Git & Task Management Workflow
+**Requirement:** All tasks and artifacts must follow the **Branch-Based Workflow**.
+## A. Branching Strategy (MANDATORY)
+❌ **NEVER** commit directly to main or master.
+### Branch Naming Convention
+| Type | Prefix | Use Case |
+|------|--------|----------|
+| **Planning** | plan/ | Project plans, product backlogs |
+| **Design** | design/ | Architecture schematics, UI specs |
+| **Feature** | feat/ | New functionality |
+| **Fix** | fix/ | Bug fixes |
+| **Docs** | docs/ | General documentation |
+**Format:** prefix/TASK-ID-short-name (e.g., plan/SPRINT-2-setup)
+### Workflow
+1. **Start:** git checkout -b prefix/TASK-ID-name from main.
+2. **Work:** Create artifacts or code.
+3. **Push:** git push -u origin prefix/TASK-ID-name.
+4. **Docs-as-Code:** Treat documentation exactly like code.
+## B. Definition of Done (DoD)
+1. Branch created.
+2. Artifacts implemented.
 3. Pull Request created & merged.
+## C. Release Workflow (AUTOMATED)
+Releases are managed by the Release Agent (`release.py`).
+1. **Trigger:** Human or CI runs `/release`.
+2. **Commit:** Agent creates `chore(release): vX.Y.Z` commit.
+3. **Tag:** Agent creates `vX.Y.Z` tag.
+4. **Push:** Agent pushes commit and tags.
+## D. Commit Conventions (MANDATORY)
+We follow [Conventional Commits](https://www.conventionalcommits.org/) to enable automated semantic versioning.
+**Format:** `type(scope): description`
+**Types:**
+- `feat`: New feature (MINOR bump)
+- `fix`: Bug fix (PATCH bump)
+- `docs`: Documentation only
+- `style`: Formatting, missing semi-colons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Build process, auxiliary tools, libraries updates
+**Breaking Changes:**
+Append `!` after type/scope (e.g., `feat!: drop support for Node 12`) for MAJOR bump.

package/.agent/rules/global.md

@@ -1,7 +1,7 @@
 # TeamLifecycle Global Rules & Conventions
-(Version 1.4 – Strict IT SDLC Simulation for Google Antigravity)
+(Version 1.5 – Strict IT SDLC Simulation for Google Antigravity)
 
-**Last Updated:** 2026-01-01  
+**Last Updated:** 2026-01-04
 **Maintainer:** Project Team
 
 ---
@@ -73,8 +73,8 @@ This document defines the mandatory rules, conventions, and lifecycle flow that
    - Covers: Naming conventions, folder structure, forbidden locations.
 2. **Git & Task Workflow:** `.agent/rules/git-workflow.md`
    - Covers: Jira-style task tracking, atomic commits, Definition of Done.
-3. **Knowledge Base:** `.agent/rules/knowledge-base.md`
-   - Covers: When and how to create knowledge entries.
+
+
 4. **Auto-Learning System:** `.agent/rules/auto-learning.md`
    - Covers: Automatic knowledge capture from tasks, issues, and bug fixes.
 
@@ -134,6 +134,11 @@ Use this at the end of **every artifact**:
 #[appropriate-tags]
 ```
 
+### 8. Tooling Standards (New)
+- **Polyglot Support:** Tools should run in environment-agnostic ways (e.g. CLI bridges).
+- **Testing:** All tools MUST be covered by integration tests in `tests/`.
+- **CLI Interface:** All tools MUST support `--help` for discoverability.
+
 ---
 
 ## Final Note
@@ -150,10 +155,9 @@ Use this at the end of **every artifact**:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.5 | 2026-01-04 | Added Tooling Standards, Polyglot Support. |
 | 1.4 | 2026-01-01 | Split large rules into artifacts.md, git-workflow.md, knowledge-base.md |
 | 1.3 | 2026-01-01 | Added Task Management & Atomic Git Commit Rules |
 | 1.2 | 2026-01-01 | Migrated to Native Agent structure (.agent/). Updated paths. |
 | 1.1 | 2025-12-23 | Added PO role, new tags (#product-owner, #backlog, #blocked, #hotfix, #rollback, #deployed-*), Definition of Done, Cross-Role Dependencies diagram, Incident/Hotfix workflow, Changelog |
 | 1.0 | Initial | Initial release with 10 roles and core SDLC flow |
-
-

package/.agent/rules/naming-conventions.md

@@ -0,0 +1,55 @@
+---
+title: Naming Conventions
+version: 1.0.0
+category: rule
+priority: high
+---
+# Naming Conventions
+## File Naming
+| Language | Convention | Example |
+|----------|------------|---------|
+| Python | snake_case.py | user_service.py |
+| JavaScript/TypeScript | kebab-case.ts | user-service.ts |
+| React Components | PascalCase.tsx | UserProfile.tsx |
+| CSS/SCSS | kebab-case.css | user-profile.css |
+| Tests | *.test.ts, *_test.py | user.test.ts |
+## Code Naming
+### Variables and Functions
+| Element | Convention | Example |
+|---------|------------|---------|
+| Variables (JS/TS) | camelCase | userName, isActive |
+| Variables (Python) | snake_case | user_name, is_active |
+| Constants | UPPER_SNAKE_CASE | MAX_RETRIES, API_URL |
+| Functions (JS/TS) | camelCase | getUserById |
+| Functions (Python) | snake_case | get_user_by_id |
+| Private | Prefix with _ | _internalState |
+### Classes and Types
+| Element | Convention | Example |
+|---------|------------|---------|
+| Classes | PascalCase | UserService, AuthController |
+| Interfaces (TS) | PascalCase | IUserRepository |
+| Type Aliases | PascalCase | UserId, ResponseData |
+| Enums | PascalCase | UserStatus, OrderType |
+| Enum Members | UPPER_SNAKE_CASE | USER_ACTIVE |
+## Database Naming
+| Element | Convention | Example |
+|---------|------------|---------|
+| Tables | snake_case plural | users, order_items |
+| Columns | snake_case | user_id, created_at |
+| Primary Keys | id or table_id | id, user_id |
+| Foreign Keys | referenced_table_id | user_id, order_id |
+| Indexes | idx_table_column | idx_users_email |
+## API Endpoints
+| Element | Convention | Example |
+|---------|------------|---------|
+| Resources | kebab-case plural | /api/users, /api/order-items |
+| Query Params | camelCase | ?userId=123 |
+| Path Params | camelCase | /users/:userId |
+## Git Branch Names
+| Type | Convention | Example |
+|------|------------|---------|
+| Feature | feat/description | feat/user-auth |
+| Bugfix | fix/description | fix/login-error |
+| Hotfix | hotfix/description | hotfix/security-patch |
+| Release | release/version | release/1.2.0 |
+#rules #naming #conventions

package/.agent/skills/role-ba.md

@@ -2,7 +2,7 @@
 inclusion: manual
 ---
 
-# Business Analyst (BA) Role
+# @ROLE - Business Analyst (BA)
 
 When acting as @BA, you are the bridge between business needs and technical implementation.
 
@@ -72,5 +72,9 @@ Activate when user mentions: `@BA`, "business analyst", "requirements", "user st
 ### 3. **Backlog Prioritization:**
    - Work with @PM to prioritize according to MoSCoW (Must, Should, Could, Won't).
 
-### 4. **Handoff:**
+### 4. Handoff:
    - Notify @SA and @PM when requirements are validated and ready for design/task-breakdown.
+
+## ⏭️ Next Steps
+- **If Requirements Approved:** Notify `@SA` and `@PM`.
+- **If Info Missing:** Schedule workshops with stakeholders.

package/.agent/skills/role-brain.md

@@ -467,4 +467,8 @@ Waiting for user requirements...
 7. **PREVENT scope creep** - Only approved features allowed
 8. **COMPOUND learnings** - Document all non-obvious solutions
 
-#brain #master-orchestrator #workflow-controller #state-machine
+#brain #master-orchestrator #workflow-controller #state-machine #role-tag #skills-enabled
+
+## ⏭️ Next Steps
+- **If Phase Complete:** Validate and transition state.
+- **If Error:** Trigger error recovery protocols.

package/.agent/skills/role-cloud.md

@@ -0,0 +1,38 @@
+---
+title: "@CLOUD - Cloud Architect"
+version: 1.0.0
+category: role
+priority: high
+phase: development
+---
+# Cloud Architect (CLOUD) Role
+When acting as @CLOUD, you are the Cloud Architect for cloud infrastructure.
+## Role Activation
+Activate when user mentions: @CLOUD, cloud, AWS, GCP, Azure, Terraform, Kubernetes
+## Primary Responsibilities
+### 1. Cloud Platform Expertise
+- AWS: EC2, ECS, Lambda, S3, RDS
+- GCP: Compute Engine, GKE, Cloud Run
+- Azure: VMs, AKS, Azure Functions
+### 2. Infrastructure as Code
+- Terraform for multi-cloud
+- Pulumi for programmatic IaC
+- CloudFormation for AWS
+- ARM/Bicep for Azure
+### 3. Container Orchestration
+- Kubernetes cluster design
+- Helm charts for deployments
+- Service mesh (Istio, Linkerd)
+### 4. Security and Compliance
+- IAM and access management
+- Network security, encryption
+- Compliance (SOC2, HIPAA)
+## Collaboration
+- Work with @SA for architecture alignment
+- Partner with @DEVOPS for CI/CD
+- Coordinate with @SECA for security
+## Strict Rules
+- ALWAYS use IaC, never manual config
+- ALWAYS encrypt data at rest/transit
+- NEVER expose secrets in code
+#cloud #aws #gcp #azure #terraform #kubernetes #skills-enabled

package/.agent/skills/role-dev.md

@@ -23,7 +23,6 @@ kb search "feature-name"
 kb compound search "architecture-pattern"
 ```
 
-- Check `.agent/knowledge-base/` for similar implementations
 - Review `docs/` for architecture decisions
 - Search Neo4j Brain for related patterns
 - Reuse proven solutions to save time
@@ -62,6 +61,11 @@ kb compound search "architecture-pattern"
 - Communicate blockers immediately
 - Share learnings with team via KB
 
+### 7. Tooling Standards
+- **Polyglot:** Support Python/Node environments (use `agentic-sdlc` bridge).
+- **Testing:** ALL new tools must include integration tests in `tests/`.
+- **CLI:** Ensure tools have `-h/--help` support.
+
 ## Artifact Requirements
 
 **Focus on code, not logs.**
@@ -90,16 +94,16 @@ kb compound search "architecture-pattern"
 ### How to Document
 ```bash
 # Interactive KB entry creation
-kb add
+agentic-sdlc kb add
 
 # Or compound add (auto-syncs to Neo4j)
-kb compound add
+agentic-sdlc kb compound add
 
 # Update index
-kb index
+agentic-sdlc kb index
 
 # Full sync to Neo4j Brain
-kb compound sync
+agentic-sdlc kb compound sync
 ```
 
 ### KB Entry Template
@@ -228,6 +232,24 @@ After implementation:
 
 ## Enhanced Workflows
 
+### `/worktree` - Parallel Development
+For running multiple agents in parallel using git worktrees:
+```bash
+# Install Worktrunk (one-time)
+cargo install worktrunk && wt config shell install
+
+# Create worktree for new task
+wt switch -c feat/task-123
+
+# List all worktrees
+wt list
+
+# Merge and cleanup when done
+wt merge
+```
+
+See full workflow: `.agent/workflows/worktree.md`
+
 ### `/cycle` - Complete Task Lifecycle
 For small, self-contained tasks (< 4 hours):
 ```
@@ -336,3 +358,7 @@ kb search "your-solution"
 - **Neo4j Sync Status:** KB entries synced to graph database
 
 #dev #developer #implementation #compound-learning
+
+## ⏭️ Next Steps
+- **If Code Committed:** Trigger `@TESTER` for verification.
+- **If Blocked:** Notify `@SA` or `@PM`.