agentic-sdlc 1.6.0 → 1.9.0

package/.agent/workflows/refactor.md

@@ -0,0 +1,132 @@
+---
+description: Process - Safe Refactoring Workflow
+---
+
+# /refactor - Safe Refactoring Workflow
+
+## ⚠️ PURPOSE
+Systematic approach to refactoring code safely without breaking existing functionality.
+
+// turbo-all
+
+## When to Use
+
+- Improving code structure
+- Reducing technical debt
+- Extracting reusable components
+- Renaming/reorganizing files
+
+## Golden Rule
+> **Tests MUST pass before AND after refactoring.**
+
+## Quick Commands
+
+```bash
+# Run tests before starting
+bun test
+
+# Check current coverage
+bun test --coverage
+```
+
+## Workflow Steps
+
+### 1. Define Scope
+- [ ] What exactly will be refactored?
+- [ ] What will NOT be touched?
+- [ ] Expected outcome (cleaner code, better performance, etc.)
+
+### 2. Verify Test Coverage
+```bash
+# Ensure code is covered by tests
+bun test --coverage
+
+# If coverage is low, add tests FIRST
+```
+
+**Critical:** If no tests exist for the code being refactored, write tests first!
+
+### 3. Create Feature Branch
+```bash
+git checkout -b refactor/[description]
+```
+
+### 4. Run Tests (Baseline)
+```bash
+# All tests must pass before refactoring
+bun test
+```
+
+### 5. Refactor in Small Steps
+- [ ] Make ONE small change
+- [ ] Run tests
+- [ ] Commit if green
+- [ ] Repeat
+
+```bash
+# Atomic commits
+git commit -m "refactor: extract [function] from [module]"
+```
+
+### 6. Run Full Test Suite
+```bash
+# Verify no regressions
+bun test
+
+# Check types
+bun run typecheck
+
+# Lint check
+bun run lint
+```
+
+### 7. Code Review
+```bash
+# Create PR for review
+gh pr create --title "refactor: [description]"
+```
+
+Invoke `/review` workflow for PR.
+
+### 8. Self-Learning
+```bash
+# Document refactoring pattern
+agentic-sdlc kb compound sync
+```
+
+## Refactoring Patterns
+
+| Pattern | Description | Risk |
+|---------|-------------|------|
+| **Extract Function** | Move code to reusable function | Low |
+| **Rename** | Improve naming | Low |
+| **Move File** | Reorganize structure | Medium |
+| **Extract Module** | Split large file | Medium |
+| **Change Signature** | Update function parameters | High |
+| **Replace Algorithm** | New implementation | High |
+
+## Anti-Patterns (Don't Do)
+
+- ❌ Refactor AND add features at same time
+- ❌ Refactor without tests
+- ❌ Large refactoring without incremental commits
+- ❌ Skip code review for "safe" refactoring
+
+## Integration
+
+- **@DEV** - Primary refactorer
+- **@TESTER** - Verify test coverage
+- **/review** - Code review after refactoring
+- **/cycle** - Standard task lifecycle
+
+#refactor #code-quality #technical-debt #cleanup
+
+## ⏭️ Next Steps
+- **If Tests Pass:** Trigger `/review` for code review
+- **If Tests Fail:** Fix regressions (do not merge)
+- **If Verified:** Trigger `/release` (if applicable)
+
+---
+
+## ENFORCEMENT REMINDER
+Tests MUST pass before AND after refactoring.

package/.agent/workflows/release.md

@@ -1,5 +1,5 @@
 ---
-description: [Support] Release Management Workflow
+description: Support - Release Management Workflow
 ---
 
 # /release - Changelog and Version Management
@@ -13,16 +13,16 @@ description: [Support] Release Management Workflow
 
 ```bash
 # Preview changes (dry run)
-python tools/release/release.py preview
+python tools/infrastructure/release/release.py preview
 
 # Generate changelog only
-python tools/release/release.py changelog --sprint 6
+python tools/infrastructure/release/release.py changelog --sprint 6
 
 # Bump version only
-python tools/release/release.py version --auto
+python tools/infrastructure/release/release.py version --auto
 
 # Full release cycle
-python tools/release/release.py release --commit --tag --push --publish
+python tools/infrastructure/release/release.py release --commit --tag --push --publish
 ```
 
 ## Conventional Commit Format
@@ -65,7 +65,7 @@ refactor(core): extract utility functions
 
 ### 1. Preview Changes
 ```bash
-python tools/release/release.py preview --sprint 6
+python tools/infrastructure/release/release.py preview --sprint 6
 ```
 Shows:
 - Last git tag
@@ -76,7 +76,7 @@ Shows:
 
 ### 2. Generate Changelog
 ```bash
-python tools/release/release.py changelog --sprint 6 --dry-run
+python tools/infrastructure/release/release.py changelog --sprint 6 --dry-run
 ```
 - Parses commits since last tag
 - Categorizes by type
@@ -86,16 +86,16 @@ python tools/release/release.py changelog --sprint 6 --dry-run
 ### 3. Bump Version
 ```bash
 # Auto-detect based on commits
-python tools/release/release.py version --auto
+python tools/infrastructure/release/release.py version --auto
 
 # Explicit bump type
-python tools/release/release.py version --bump minor
+python tools/infrastructure/release/release.py version --bump minor
 ```
 Updates `package.json` version.
 
 ### 4. Full Release
 ```bash
-python tools/release/release.py release --sprint 6 --commit --tag --push --publish
+python tools/infrastructure/release/release.py release --sprint 6 --commit --tag --push --publish
 ```
 Executes:
 1. Parse commits
@@ -141,13 +141,24 @@ git push && git push --tags
   bun run release            # Full release
   ```
 
+- **Update Methods:**
+  - **NPM Update:** `npm update -g agentic-sdlc`
+  - **Source Update:** `python tools/infrastructure/update/updater.py`
+
 - **CI/CD:** Can be triggered in GitHub Actions
 
+- **Publish to NPM:** To publish to NPM, ensure you are logged in using `npm login` then run the release command with the --publish flag.
+  ```bash
+  python tools/infrastructure/release/release.py release --publish
+  ```
+
 #release #versioning #changelog #semver #git-tags
 
+## ⏭️ Next Steps
+- **If Release Successful:** Trigger `/housekeeping`
+- **If Changelog Updated:** Notify stakeholders via `@REPORTER`
 
 ---
 
 ## ENFORCEMENT REMINDER
-Before executing, complete /preflight checks.
-
+Ensure all tests pass before releasing.

package/.agent/workflows/review.md

@@ -0,0 +1,99 @@
+---
+description: Process - Code Review Workflow for PRs
+---
+
+# /review - Code Review Workflow
+
+## ⚠️ PURPOSE
+Systematic code review process for Pull Requests. Ensures code quality, security, and consistency.
+
+// turbo-all
+
+## Quick Commands
+
+```bash
+# Review a specific PR
+agentic-sdlc review --pr 123
+
+# Review current branch changes
+git diff main...HEAD --stat
+```
+
+## Workflow Steps
+
+### 1. Context Gathering
+```bash
+# Search KB for similar implementations
+agentic-sdlc kb search "[feature/module]"
+
+# View PR diff
+git diff main...HEAD
+```
+
+### 2. Code Quality Checklist
+- [ ] **Readability:** Clear naming, comments where needed
+- [ ] **Structure:** Follows project patterns
+- [ ] **DRY:** No unnecessary duplication
+- [ ] **SOLID:** Single responsibility, clean interfaces
+
+### 3. Security Review (@SECA)
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] No SQL injection vulnerabilities
+- [ ] Proper error handling (no sensitive data in errors)
+
+### 4. Test Coverage (@TESTER)
+- [ ] Unit tests added for new code
+- [ ] Edge cases covered
+- [ ] Integration tests if needed
+- [ ] All tests passing
+
+### 5. Documentation
+- [ ] Code comments for complex logic
+- [ ] API docs updated if applicable
+- [ ] README updated if needed
+
+### 6. Provide Feedback
+```bash
+# Comment on PR (via GitHub CLI)
+gh pr comment 123 --body "LGTM with suggestions: ..."
+
+# Request changes
+gh pr review 123 --request-changes --body "Please fix: ..."
+
+# Approve
+gh pr review 123 --approve
+```
+
+### 7. Self-Learning
+```bash
+# Record review patterns for future reference
+agentic-sdlc kb compound sync
+```
+
+## Review Severity Levels
+
+| Level | Action | Examples |
+|-------|--------|----------|
+| 🔴 Blocker | Must fix before merge | Security issue, breaks build |
+| 🟠 Major | Should fix | Performance issue, wrong pattern |
+| 🟡 Minor | Nice to fix | Naming, style inconsistency |
+| 🟢 Nitpick | Optional | Personal preference |
+
+## Integration
+
+- **@TESTER** - Test coverage review
+- **@SECA** - Security review
+- **@DEV** - Code implementation review
+- **/cycle** - Part of standard task lifecycle
+
+#review #pr #code-quality #security
+
+## ⏭️ Next Steps
+- **If Approved:** Trigger `/release` (if ready) or Merger
+- **If Changes Requested:** Return to `@DEV` for fixes
+
+---
+
+## ENFORCEMENT REMINDER
+Search KB for similar patterns before commenting.

package/.agent/workflows/score.md

@@ -0,0 +1,104 @@
+---
+description: Intelligence - Score - Quality Scoring with Judge
+---
+
+# /score - Quality Scoring Workflow
+
+## ⚠️ PURPOSE
+Score code, reports, or artifacts using the Judge agent to assess quality and get improvement suggestions.
+
+// turbo-all
+
+## Quick Commands
+
+```bash
+# Score a code file
+python tools/intelligence/judge/scorer.py --code src/app.py
+
+# Score a report or document
+python tools/intelligence/judge/scorer.py --report docs/walkthroughs/latest.md
+
+# Score via Brain CLI
+python tools/core/brain/brain_cli.py score "path/to/file.py"
+
+# Score A/B test alternatives
+python tools/intelligence/judge/scorer.py --ab-test docs/reports/ab_tests/YYYY-MM-DD-auth.md
+```
+
+## When to Use
+
+- After completing implementation
+- Before submitting PR
+- During code review
+- To validate documentation quality
+
+## Workflow Steps
+
+### 1. Identify Target
+Determine what you want to score:
+- Code file
+- Documentation
+- Report
+- A/B test result
+
+### 2. Run Scoring
+```bash
+python tools/intelligence/judge/scorer.py --code [file_path]
+```
+
+### 3. Review Score
+
+**Code Scoring (0-100):**
+| Dimension | Description |
+|-----------|-------------|
+| Complexity | Cyclomatic complexity, nesting depth |
+| Readability | Naming, comments, structure |
+| Security | Vulnerabilities, best practices |
+| Performance | Efficiency, optimization |
+| Maintainability | Modularity, DRY, SOLID |
+
+**Report Scoring (0-100):**
+| Dimension | Description |
+|-----------|-------------|
+| Completeness | All sections present |
+| Clarity | Well-written, understandable |
+| Accuracy | Correct information |
+| Actionability | Clear next steps |
+
+### 4. Address Issues
+If score < 80:
+- Review improvement suggestions
+- Make necessary changes
+- Re-score to verify
+
+### 5. Document Result
+```bash
+python tools/core/brain/brain_cli.py learn "Improved [file] quality from X to Y"
+```
+
+## Score Thresholds
+
+| Score | Status | Action |
+|-------|--------|--------|
+| 90-100 | ✅ Excellent | Ship it |
+| 70-89 | 🟡 Good | Minor improvements optional |
+| 50-69 | 🟠 Needs Work | Address issues before PR |
+| 0-49 | 🔴 Critical | Major refactoring needed |
+
+## Integration
+
+- **@TESTER** - Quality assurance
+- **/cycle** - Pre-PR scoring
+- **/review** - Code review support
+- **/commit** - Score before commit
+
+#score #quality #judge #metrics
+
+## ⏭️ Next Steps
+- **If Score ≥ 80:** Proceed with `/commit` or `/review`
+- **If Score < 80:** Fix issues and re-score
+
+---
+
+## ENFORCEMENT REMINDER
+Target score of 80+ before committing code.

package/.agent/workflows/sprint.md

@@ -1,5 +1,5 @@
 ---
-description: [Process] Sprint Management Workflow
+description: Process - Sprint Management Workflow
 ---
 
 # /sprint - Sprint Lifecycle Management
@@ -13,13 +13,13 @@ description: [Process] Sprint Management Workflow
 
 ```bash
 # Start a new sprint
-python tools/workflows/sprint.py start 6
+python tools/infrastructure/workflows/sprint.py start 6
 
 # Check current sprint status
-python tools/workflows/sprint.py status
+python tools/infrastructure/workflows/sprint.py status
 
 # Close a sprint
-python tools/workflows/sprint.py close 5
+python tools/infrastructure/workflows/sprint.py close 5
 ```
 
 ## Sprint Start
@@ -40,7 +40,7 @@ python tools/workflows/sprint.py close 5
 
 ### Usage
 ```bash
-python tools/workflows/sprint.py start 6
+python tools/infrastructure/workflows/sprint.py start 6
 ```
 
 ### Next Steps After Start
@@ -58,7 +58,7 @@ python tools/workflows/sprint.py start 6
 
 ### Usage
 ```bash
-python tools/workflows/sprint.py status
+python tools/infrastructure/workflows/sprint.py status
 ```
 
 ## Sprint Close
@@ -78,13 +78,13 @@ python tools/workflows/sprint.py status
 
 ### Usage
 ```bash
-python tools/workflows/sprint.py close 5
+python tools/infrastructure/workflows/sprint.py close 5
 ```
 
 ### Next Steps After Close
 1. Fill in Sprint Review with accomplishments
 2. Complete Retrospective with team
-3. Start next sprint: `python tools/workflows/sprint.py start 6`
+3. Start next sprint: `python tools/infrastructure/workflows/sprint.py start 6`
 
 ## Sprint Folder Structure
 
@@ -116,10 +116,12 @@ docs/sprints/sprint-[N]/
 - **/release** references sprint in changelog
 
 #sprint #agile #lifecycle #planning #retrospective
-
-
----
-
-## ENFORCEMENT REMINDER
-Before executing, complete /preflight checks.
 
+## ⏭️ Next Steps
+- **If Sprint Started:** Trigger `@PM` for planning details
+- **If Sprint Closed:** Trigger `/housekeeping` for cleanup
+
+---
+
+## ENFORCEMENT REMINDER
+Run /onboarding if new to project.

package/.agent/workflows/validate.md

@@ -1,5 +1,5 @@
 ---
-description: [Utility] Validate - Workflow Compliance Checker
+description: Utility - Validate - Workflow Compliance Checker
 ---
 
 # /validate - Tool Reference Validator
@@ -11,13 +11,13 @@ Scans all workflow files for `python tools/...` commands and file path reference
 
 ```bash
 # Full validation
-python tools/validation/validate.py
+python tools/infrastructure/validation/validate.py
 
 # With fix suggestions
-python tools/validation/validate.py --fix
+python tools/infrastructure/validation/validate.py --fix
 
 # Generate report file
-python tools/validation/validate.py --report
+python tools/infrastructure/validation/validate.py --report
 ```
 
 ## What It Checks
@@ -110,7 +110,7 @@ Generates `docs/reports/Validation-Report-YYYY-MM-DD.md`:
 ## Fix Suggestions (--fix)
 
 ```bash
-python tools/validation/validate.py --fix
+python tools/infrastructure/validation/validate.py --fix
 ```
 
 Outputs:
@@ -137,10 +137,12 @@ Works with:
 - CI/CD pipelines
 
 #validate #health-check #workflow-audit #compliance
-
-
----
-
-## ENFORCEMENT REMINDER
-Before executing, complete /preflight checks.
 
+## ⏭️ Next Steps
+- **If Valid:** Continue current workflow
+- **If Invalid:** Fix references and re-run `/validate`
+
+---
+
+## ENFORCEMENT REMINDER
+Ensure all workflow references are valid before committing.

package/.agent/workflows/worktree.md

@@ -0,0 +1,154 @@
+---
+description: Support - Parallel AI Agent Worktree Management
+---
+
+# /worktree - Git Worktree Management with Worktrunk
+
+## ⚠️ STRICT EXECUTION PROTOCOL (MANDATORY)
+1. **PREREQUISITES:** Ensure Worktrunk is installed before using.
+2. **ONE BRANCH PER WORKTREE:** Each worktree = one branch.
+3. **CLEANUP:** Always remove worktrees after merging.
+
+## Prerequisites
+
+### Installation
+```bash
+# Via Cargo (Rust)
+cargo install worktrunk && wt config shell install
+
+# Via Homebrew (macOS/Linux)
+brew install max-sixty/worktrunk/wt && wt config shell install
+```
+
+### Verify Installation
+```bash
+wt --help
+wt list
+```
+
+## Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `wt switch <branch>` | Switch to existing worktree (creates if needed) |
+| `wt switch -c <branch>` | Create new worktree with new branch |
+| `wt list` | List all worktrees |
+| `wt remove` | Remove current worktree and its branch |
+| `wt merge` | Squash/merge current branch and cleanup |
+| `wt select` | Interactive worktree selector (fzf-like) |
+
+## Workflow Steps
+
+### 1. Start New Task in Worktree
+```bash
+# Create worktree for feature
+wt switch -c feat/task-123
+
+# Your terminal is now in the new worktree directory
+# e.g., ../repo.feat/task-123
+```
+
+### 2. Work in Parallel
+```bash
+# List all active worktrees
+wt list
+
+# Switch between worktrees
+wt switch feat/task-123
+wt switch fix/bug-456
+```
+
+### 3. Merge and Cleanup
+```bash
+# From the worktree you want to merge
+wt merge
+
+# This will:
+# 1. Squash commits
+# 2. Merge to main
+# 3. Remove the worktree
+# 4. Delete the branch
+```
+
+### 4. Manual Cleanup
+```bash
+# Remove current worktree without merging
+wt remove
+
+# Remove specific worktree
+wt remove feat/old-branch
+```
+
+## Hooks (Advanced)
+
+Create `.worktrunk/hooks/` in your repo root:
+
+```bash
+# .worktrunk/hooks/on-create.sh
+#!/bin/bash
+# Run after creating a new worktree
+bun install  # or npm install
+```
+
+```bash
+# .worktrunk/hooks/pre-merge.sh
+#!/bin/bash
+# Run before merging
+bun test
+```
+
+## Multi-Agent Workflow
+
+### Run Multiple AI Agents in Parallel
+```bash
+# Terminal 1: Agent working on feature
+wt switch -c feat/auth-system
+# Start Claude Code or other agent here
+
+# Terminal 2: Agent working on bug fix
+wt switch -c fix/login-issue
+# Start another agent here
+
+# Terminal 3: Agent working on docs
+wt switch -c docs/api-reference
+# Start another agent here
+```
+
+### Monitor All Agents
+```bash
+wt list
+# Shows all worktrees with their branches
+```
+
+## Integration
+
+- **@DEV** uses for parallel feature development
+- **@TESTER** can test in isolated worktrees
+- **/cycle** can leverage worktrees for complex tasks
+
+## Best Practices
+
+1. **Name branches descriptively**: `feat/`, `fix/`, `docs/`, `refactor/`
+2. **One task per worktree**: Keep scope focused
+3. **Merge frequently**: Don't let worktrees pile up
+4. **Use hooks**: Automate environment setup
+
+## Troubleshooting
+
+### Windows-Specific
+- Use Git Bash for best compatibility
+- PowerShell works for basic commands
+- Restart shell after `wt config shell install`
+
+### Common Issues
+| Issue | Solution |
+|-------|----------|
+| `wt` command not found | Run `wt config shell install` and restart shell |
+| Permission denied | Run shell as administrator (Windows) |
+| Path issues | Use Git Bash instead of PowerShell |
+
+## References
+- [Worktrunk Documentation](https://worktrunk.dev)
+- [GitHub: max-sixty/worktrunk](https://github.com/max-sixty/worktrunk)
+
+#worktree #parallel #agents #git #support