@the-bearded-bear/claude-craft 5.6.0 → 5.7.0-next.bf058ea

package/Dev/i18n/en/Common/commands/team-security.md

@@ -0,0 +1,325 @@
+---
+description: Security Review Team - Parallel multi-dimension security audit using Agent Teams
+argument-hint: [--scope=full|code|deps|infra] [--max-workers=3]
+---
+
+# Security Review Team - Parallel Multi-Dimension Security Audit
+
+Orchestrate a comprehensive security audit using Claude Code Agent Teams (v2.1.32+). Spawns a security lead (opus) plus 3 specialized haiku reviewers, each analyzing a different security dimension in parallel: source code vulnerabilities, dependency/supply chain, and infrastructure/configuration.
+
+## Arguments
+
+$ARGUMENTS
+
+- `--scope=full`: Audit scope (default: `full`). Options: `full`, `code`, `deps`, `infra`
+- `--max-workers=3`: Maximum parallel reviewers (default: 3, max: 3)
+- `--severity=medium`: Minimum severity to report: `low`, `medium`, `high`, `critical`
+- `--output-dir=<path>`: Custom output directory for security results
+- `--dry-run`: Show team composition and scan plan without executing
+- `--sarif`: Output results in SARIF format (for CI/CD integration)
+
+## Prerequisites
+
+- Claude Code v2.1.32+ with Agent Teams support
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable set
+- Docker available for running security scanners
+- `Tools/AgentTeams/lib/compatibility-check.sh` available
+- `Tools/AgentTeams/lib/result-aggregator.sh` available
+- `Tools/AgentTeams/lib/cost-estimator.sh` available
+
+## Team Composition
+
+| Role | Model | Agent | Responsibility |
+|------|-------|-------|----------------|
+| Security Lead | opus | Custom (team lead) | Orchestration, threat modeling, report |
+| Code Reviewer | haiku | `{tech}-reviewer` | Source code vulnerability analysis |
+| Dependency Auditor | haiku | `{tech}-reviewer` | Supply chain, CVE, license compliance |
+| Infra Reviewer | haiku | `devops-engineer` or `docker-architect` | Container security, secrets, config |
+
+**Team size**: 4 agents (1 lead + 3 workers). Fixed composition for security review.
+
+## Process
+
+### Step 1: Project Reconnaissance
+
+The security lead performs initial reconnaissance:
+
+1. Detect technology stacks (same as full-audit detection)
+2. Identify entry points: API endpoints, forms, file uploads
+3. Map the attack surface: public routes, authentication boundaries, data flows
+4. Create threat model outline (STRIDE categories)
+
+### Step 2: Compatibility Check
+
+```bash
+# Verify code reviewer agent has required tools
+Tools/AgentTeams/lib/compatibility-check.sh \
+  --agent Dev/i18n/en/<Tech>/agents/<tech>-reviewer.md \
+  --require-tools Read,Glob,Grep,Bash
+
+# Verify infra reviewer
+Tools/AgentTeams/lib/compatibility-check.sh \
+  --agent Dev/i18n/en/Common/agents/devops-engineer.md \
+  --require-tools Read,Glob,Grep,Bash
+```
+
+### Step 3: Team Spawn (Fan-Out)
+
+```
+Security Lead (opus) — orchestrates via TaskCreate/SendMessage
+  |
+  +-- [Parallel Reviewers] ------------------+
+  |   Code Reviewer (haiku): Source analysis   |
+  |   Dependency Auditor (haiku): Supply chain |
+  |   Infra Reviewer (haiku): Configuration    |
+  +-------------------------------------------+
+  |
+  v (sync barrier)
+  |
+  Security Lead: Correlate, prioritize, report
+```
+
+The lead creates 3 tasks via `TaskCreate`:
+
+#### Task A: Source Code Security Review
+
+**Scope**: Application source code vulnerability analysis
+
+| Check | What to Look For | OWASP Category |
+|-------|-----------------|----------------|
+| Injection | SQL, NoSQL, OS command, LDAP injection patterns | A03:2021 |
+| XSS | Unescaped output, innerHTML, dangerouslySetInnerHTML | A03:2021 |
+| Authentication | Weak password policies, missing MFA, session fixation | A07:2021 |
+| Authorization | Missing access controls, IDOR, privilege escalation | A01:2021 |
+| Cryptography | Weak algorithms, hardcoded keys, insecure random | A02:2021 |
+| Input Validation | Missing sanitization, type coercion, file upload | A03:2021 |
+| Error Handling | Stack traces in responses, verbose errors | A05:2021 |
+| Logging | Sensitive data in logs, missing audit trail | A09:2021 |
+
+**Docker commands per stack**:
+
+```bash
+# PHP/Symfony
+docker compose exec php vendor/bin/phpstan analyse --level=max
+docker compose exec php php bin/console security:check
+
+# React/Node
+docker compose exec node npm run lint -- --rule 'no-eval: error'
+docker compose exec node npx eslint --plugin security .
+
+# Python
+docker compose exec app bandit -r src/
+docker compose exec app ruff check --select S .
+
+# General (all stacks)
+# Grep patterns for common vulnerabilities
+# Search for: eval(, exec(, system(, shell_exec(, innerHTML, dangerouslySetInnerHTML
+# Search for: hardcoded passwords, API keys, tokens in source
+```
+
+#### Task B: Dependency / Supply Chain Audit
+
+**Scope**: Third-party dependency vulnerability and license analysis
+
+| Check | What to Analyze |
+|-------|----------------|
+| Known CVEs | All direct and transitive dependencies |
+| Severity | Critical and High CVEs requiring immediate action |
+| License compliance | Copyleft licenses in proprietary projects |
+| Outdated packages | Packages with available security patches |
+| Typosquatting | Suspicious package names similar to popular packages |
+| Unused deps | Dependencies declared but never imported |
+
+**Docker commands per stack**:
+
+```bash
+# PHP
+docker compose exec php composer audit --format=json
+docker compose exec php composer outdated --direct
+
+# Node/React/Angular/Vue
+docker compose exec node npm audit --json
+docker compose exec node npm outdated
+
+# Python
+docker compose exec app pip-audit --format=json
+docker compose exec app pip list --outdated
+
+# Flutter/Dart
+docker run --rm -v $(pwd):/app -w /app dart dart pub outdated --json
+
+# C#/.NET
+docker compose exec app dotnet list package --vulnerable
+docker compose exec app dotnet list package --outdated
+```
+
+#### Task C: Infrastructure / Configuration Security Review
+
+**Scope**: Docker, deployment configuration, secrets management
+
+| Check | What to Analyze |
+|-------|----------------|
+| Dockerfile security | Base image pinning, non-root user, multi-stage builds |
+| Secrets exposure | .env files, hardcoded credentials, unencrypted secrets |
+| Docker Compose | Privileged containers, exposed ports, volume mounts |
+| Network policy | Unnecessary port exposure, missing network isolation |
+| TLS/SSL | Certificate validation, protocol versions, cipher suites |
+| CI/CD security | Secret injection, pipeline permissions, artifact integrity |
+| File permissions | World-readable configs, .git exposure, backup files |
+
+**Scan commands**:
+
+```bash
+# Docker security
+docker compose config --quiet  # Validate compose syntax
+# Review Dockerfiles for: USER root, latest tags, ADD vs COPY
+
+# Secrets scan
+# Search for: .env files not in .gitignore
+# Search for: AWS_SECRET, PRIVATE_KEY, password=, token= in source
+# Search for: base64-encoded secrets, SSH keys in repo
+
+# Configuration review
+# Check: CORS policies, CSP headers, HSTS
+# Check: Debug mode disabled in production configs
+# Check: Rate limiting configured
+```
+
+### Step 4: Sync Barrier
+
+Security lead waits for all 3 reviewer tasks to complete. Timeout: 8 minutes per reviewer. If a reviewer exceeds timeout, lead proceeds with available results and notes the gap.
+
+### Step 5: Correlation and Prioritization
+
+The security lead correlates findings across all 3 dimensions:
+
+1. **Cross-reference**: A vulnerable dependency (Task B) used in an injection-prone code path (Task A) is elevated to Critical
+2. **Attack chain analysis**: Combine findings to identify multi-step attack paths
+3. **Deduplicate**: Same issue found by multiple reviewers is merged
+4. **Prioritize**: Score each finding by severity x exploitability x impact
+
+**Severity matrix**:
+
+| Severity | CVSS Range | Response |
+|----------|-----------|----------|
+| Critical | 9.0 - 10.0 | Immediate fix required |
+| High | 7.0 - 8.9 | Fix within current sprint |
+| Medium | 4.0 - 6.9 | Plan for next sprint |
+| Low | 0.1 - 3.9 | Backlog / accept risk |
+
+### Step 6: Report Generation
+
+```
+================================================================
+SECURITY REVIEW TEAM - Report
+================================================================
+
+Project: <project-name>
+Date: YYYY-MM-DD
+Scope: <full|code|deps|infra>
+Team: 1 lead + 3 reviewers
+
+================================================================
+EXECUTIVE SUMMARY
+================================================================
+
+| Severity | Count |
+|----------|-------|
+| Critical | X |
+| High | X |
+| Medium | X |
+| Low | X |
+| Total | X |
+
+Overall Risk Level: <Critical|High|Medium|Low>
+
+================================================================
+FINDINGS BY DIMENSION
+================================================================
+
+-- SOURCE CODE (Code Reviewer) --
+
+| # | Severity | Category | File | Description |
+|---|----------|----------|------|-------------|
+| 1 | HIGH | A03:Injection | src/... | SQL injection in... |
+| 2 | MEDIUM | A07:Auth | src/... | Weak password... |
+
+-- DEPENDENCIES (Dependency Auditor) --
+
+| # | Severity | Package | Version | CVE | Fix Available |
+|---|----------|---------|---------|-----|---------------|
+| 1 | CRITICAL | lib-x | 1.2.3 | CVE-2026-XXXX | 1.2.4 |
+| 2 | HIGH | lib-y | 4.5.6 | CVE-2026-YYYY | 5.0.0 |
+
+-- INFRASTRUCTURE (Infra Reviewer) --
+
+| # | Severity | Component | Description |
+|---|----------|-----------|-------------|
+| 1 | HIGH | Dockerfile | Running as root |
+| 2 | MEDIUM | .env | Not in .gitignore |
+
+================================================================
+ATTACK CHAINS (Correlated Findings)
+================================================================
+
+Chain 1: SQL Injection via vulnerable dependency
+  Step 1: Outdated ORM library (CVE-2026-XXXX)
+  Step 2: User input reaches query builder without sanitization
+  Impact: Database compromise
+  Severity: CRITICAL
+
+================================================================
+REMEDIATION PLAN
+================================================================
+
+| Priority | Action | Effort | Impact |
+|----------|--------|--------|--------|
+| 1 | Update lib-x to 1.2.4 | Low | Fixes CVE-2026-XXXX |
+| 2 | Add input sanitization in src/... | Medium | Blocks injection |
+| 3 | Switch to non-root Docker user | Low | Reduces blast radius |
+
+================================================================
+EXECUTION METRICS
+================================================================
+
+| Metric | Value |
+|--------|-------|
+| Total time | Xs (vs ~Ys sequential) |
+| Speedup | ~X.Xx |
+| Total tokens | ~XK |
+| Findings discovered | X |
+| Reviewers completed | 3/3 |
+```
+
+### Step 7: Cleanup
+
+Security lead sends `shutdown_request` to all reviewers and cleans up isolated output directories.
+
+## Performance Expectations
+
+| Scope | Sequential Est. | Team Est. | Speedup | Token Overhead |
+|-------|----------------|-----------|---------|----------------|
+| Code only | ~5 min | ~5 min | 1x (no parallelism) | 0% |
+| Deps only | ~3 min | ~3 min | 1x (no parallelism) | 0% |
+| Full | ~12 min | ~6 min | ~2x | +30% |
+
+**Note**: Full scope benefits from 3-way parallelism. Individual scopes (`--scope=code`) run as single-worker tasks with no team overhead.
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Reviewer timeout (>8min) | Lead proceeds with partial results, notes gap |
+| Reviewer crash | Lead logs error, reports dimension as "not assessed" |
+| Docker not available | Reviewer falls back to source-only pattern analysis |
+| No vulnerabilities found | Report states clean status (not an error) |
+| Scanner tool not installed | Reviewer skips scanner, uses grep-based analysis |
+
+## Limitations
+
+- Fixed team of 4 agents (1 lead + 3 reviewers)
+- Cannot replace specialized security tools (SAST/DAST/SCA) -- supplements them
+- Findings depend on model's security knowledge (no zero-day detection)
+- Token cost ~30% higher than sequential due to context duplication
+- Requires Agent Teams Research Preview (API may change)
+- Attack chain correlation quality depends on lead agent's reasoning capability

package/Dev/i18n/en/Common/commands/team-sprint.md

@@ -0,0 +1,243 @@
+---
+description: Sprint Development Team - Parallel story implementation using Agent Teams
+argument-hint: <sprint-name> [--max-workers=3] [--overnight] [--use-teams]
+---
+
+# Sprint Development Team - Parallel Story Implementation
+
+Orchestrate parallel sprint execution using Claude Code Agent Teams (v2.1.32+). Spawns a sprint conductor (opus) plus 2-3 developer workers (sonnet), each taking an independent story from the backlog. Designed to integrate with the existing Ralph Sprint (`/common:ralph-sprint --use-teams`) flow.
+
+## Arguments
+
+$ARGUMENTS
+
+- `<sprint-name>`: Name or ID of the sprint to process
+- `--max-workers=3`: Maximum parallel dev workers (default: 2, max: 3)
+- `--overnight`: Run in overnight mode (bounded, stops at 6am)
+- `--supervised`: Pause before each story for human confirmation
+- `--max-stories=10`: Maximum stories to process (default: 10)
+- `--timeout=12`: Maximum runtime in hours (default: 12)
+- `--dry-run`: Show team composition and story assignments without executing
+- `--use-teams`: Flag passed from ralph-sprint to indicate Agent Teams mode
+
+## Prerequisites
+
+- Claude Code v2.1.32+ with Agent Teams support
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable set
+- BMAD sprint backlog with stories in `ready-for-dev` status
+- Sprint metadata in `.bmad/sprint-status.yaml`
+- At least 2 independent stories (single-story sprints use sequential Ralph)
+- `Tools/AgentTeams/lib/ralph-teams-adapter.sh` available
+- `Tools/AgentTeams/lib/compatibility-check.sh` available
+- `Tools/AgentTeams/lib/cost-estimator.sh` available
+
+## When to Use (vs. Sequential Sprint)
+
+| Condition | Use Team Sprint | Use Sequential `/common:ralph-sprint` |
+|-----------|----------------|----------------------------------------|
+| 1 story remaining | No | Yes |
+| 2+ independent stories | Yes (~2x speedup) | Also valid (simpler) |
+| Stories with shared files | No (write conflicts) | Yes |
+| Overnight unattended | Yes (with `--overnight`) | Also valid |
+| Budget-constrained | No (+25-35% token overhead) | Yes |
+
+**Critical**: Stories must be fully independent (no shared file domains). If stories modify overlapping files, the conductor assigns them sequentially to the same worker.
+
+## Process
+
+### Step 1: Sprint Initialization
+
+The sprint conductor loads sprint state:
+
+1. Read `.bmad/sprint-status.yaml` for story list and statuses
+2. Filter stories with status `ready-for-dev`
+3. Analyze story independence (check for file domain overlap)
+4. Partition stories into parallelizable groups
+
+**Independence check**: Two stories are independent if their acceptance criteria and implementation scope do not reference the same source files. The conductor reviews each story's description and tech spec references to determine this.
+
+### Step 2: Story Assignment
+
+```
+Sprint Conductor (opus) — coordinates via TaskCreate/SendMessage
+  |
+  +-- [Parallel Workers - max 3] --------+
+  |   dev-worker-1 (sonnet): US-001       |
+  |   dev-worker-2 (sonnet): US-002       |
+  |   dev-worker-3 (sonnet): US-003       |
+  +---------------------------------------+
+  |
+  v (sync barrier - all stories complete)
+  |
+  +-- [Sequential Review] ---------------+
+  |   Conductor validates each story DoD   |
+  +---------------------------------------+
+```
+
+The conductor creates one `TaskCreate` per story:
+
+- **Subject**: `Implement US-XXX: <story title>`
+- **Description**: Full story content, acceptance criteria, tech spec references, TDD requirements
+- **activeForm**: `Implementing US-XXX`
+
+### Step 3: Worker Execution (Per Story)
+
+Each dev worker follows the TDD cycle for its assigned story:
+
+```
+1. Read story and acceptance criteria
+2. RED: Write failing tests from acceptance criteria
+3. GREEN: Implement minimal code to pass tests
+4. REFACTOR: Clean up while keeping tests green
+5. Run full test suite (docker-based)
+6. Write result summary
+7. Mark task as completed
+```
+
+**Worker TDD commands** (technology-specific):
+
+```bash
+# Symfony
+docker compose exec php vendor/bin/phpunit
+docker compose exec php vendor/bin/phpstan analyse
+docker compose exec php php bin/console lint:container
+
+# React
+docker compose exec node npm run test
+docker compose exec node npm run lint
+docker compose exec node npm run build
+
+# Python
+docker compose exec app pytest --cov
+docker compose exec app ruff check .
+docker compose exec app mypy .
+
+# Flutter
+docker run --rm -v $(pwd):/app -w /app dart flutter test
+docker run --rm -v $(pwd):/app -w /app dart dart analyze
+```
+
+### Step 4: Story Transition
+
+As each worker completes, the conductor:
+
+1. Validates Definition of Done (DoD) for the story
+2. Transitions story status: `in-progress` -> `review`
+3. Assigns the next `ready-for-dev` story to the now-free worker
+4. Repeats until no stories remain or limits are reached
+
+**DoD validation checklist**:
+- [ ] All acceptance criteria tests pass
+- [ ] No new linting errors introduced
+- [ ] Code coverage not decreased
+- [ ] No secrets in committed code
+- [ ] Story implementation matches tech spec
+
+### Step 5: Error Recovery
+
+The conductor classifies errors per the Ralph recovery engine:
+
+| Level | Type | Action | Examples |
+|-------|------|--------|----------|
+| 0 | Transient | Auto-retry with backoff | Timeout, rate limit, network |
+| 1 | Recoverable | Worker auto-fix + retry | Lint errors, test failures, deps |
+| 2 | Degraded | Continue with warning | Docs, optional gates, coverage dip |
+| 3 | Blocked | Escalate to human | Security, architecture, auth |
+
+**Worker stuck detection**: If a worker hasn't updated its task in 10 minutes, the conductor sends a status check message. If no response within 2 minutes, the conductor marks the story as blocked and reassigns to another worker or queues for human review.
+
+### Step 6: Sprint Completion
+
+When all stories are processed:
+
+1. Conductor generates sprint summary report
+2. Updates `.bmad/sprint-status.yaml` via single-writer pattern
+3. Sends `shutdown_request` to all workers
+4. Reports final metrics
+
+## Output
+
+### Sprint Summary Report
+
+```
+================================================================
+SPRINT DEVELOPMENT TEAM - Summary
+================================================================
+
+Sprint: <sprint-name>
+Date: YYYY-MM-DD
+Mode: Parallel (Agent Teams)
+Team: 1 conductor + N dev workers
+
+----------------------------------------------------------------
+STORIES COMPLETED
+----------------------------------------------------------------
+
+| Story | Title | Worker | Time | DoD |
+|-------|-------|--------|------|-----|
+| US-001 | Login feature | dev-1 | 12m | PASS |
+| US-002 | User profile | dev-2 | 18m | PASS |
+| US-003 | Dashboard | dev-3 | 15m | PASS |
+
+----------------------------------------------------------------
+STORIES BLOCKED
+----------------------------------------------------------------
+
+| Story | Title | Reason | Escalation |
+|-------|-------|--------|------------|
+| US-004 | Payment | Architecture dependency | Queued for human |
+
+================================================================
+EXECUTION METRICS
+================================================================
+
+| Metric | Value |
+|--------|-------|
+| Stories completed | X / Y |
+| Stories blocked | Z |
+| Total time | Xm (vs ~Ym sequential) |
+| Speedup | ~X.Xx |
+| Total tokens | ~XK |
+| Workers spawned | N |
+| Avg time per story | Xm |
+```
+
+## Performance Expectations
+
+| Workers | Stories | Sequential Est. | Team Est. | Speedup | Token Overhead |
+|---------|---------|----------------|-----------|---------|----------------|
+| 2 | 4 | ~60 min | ~35 min | ~1.7x | +25% |
+| 2 | 6 | ~90 min | ~50 min | ~1.8x | +25% |
+| 3 | 6 | ~90 min | ~40 min | ~2.2x | +30% |
+| 3 | 9 | ~135 min | ~55 min | ~2.5x | +35% |
+
+**Note**: Speedup depends on story independence and comparable complexity. If one story takes 3x longer than others, the bottleneck story limits overall speedup.
+
+## Integration with Ralph Sprint
+
+When invoked via `/common:ralph-sprint --use-teams`, the Ralph Teams adapter (`Tools/AgentTeams/lib/ralph-teams-adapter.sh`) handles:
+
+1. Translating Ralph session config to Agent Teams parameters
+2. Bridging checkpoint/recovery between Ralph and Agent Teams
+3. Ensuring sprint-status.yaml updates follow single-writer pattern
+4. Mapping Ralph error levels to Agent Teams recovery actions
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Worker timeout (>15min per story) | Conductor reassigns story |
+| Worker crash | Story returns to `ready-for-dev`, another worker picks up |
+| All workers stuck | Conductor escalates to human |
+| Sprint-status.yaml conflict | Single-writer pattern via file locking |
+| Story has file overlap with another | Conductor assigns sequentially to same worker |
+| Docker not available | Worker reports error, conductor tries source-only |
+
+## Limitations
+
+- Maximum 3 parallel dev workers (4 total including conductor)
+- Stories must be independent (no shared file domains)
+- Token cost is ~25-35% higher than sequential due to context duplication
+- Requires Agent Teams Research Preview (API may change)
+- Overnight mode depends on conductor agent stability (orphan risk exists)
+- Not suitable for stories requiring interactive human decisions mid-implementation

package/README.md

@@ -4,6 +4,16 @@ A comprehensive framework for AI-assisted development with [Claude Code](https:/
 
 **Autonomous Sprint Ready**: Run entire sprints overnight with `/common:ralph-sprint` - auto-claim, error recovery, parallel processing.
 
+## What's New in v5.7 - Agent Teams Integration
+
+- **Agent Teams** — Multi-agent coordination with shared task management
+  - `/common:team-audit` — Parallel multi-technology audit (1 opus leader + N haiku auditors)
+  - `/common:team-sprint` — Sprint Development Team (1 opus conductor + 2-3 sonnet devs)
+  - `/common:team-security` — Security Review Team (1 opus lead + 3 haiku reviewers)
+- **Cost Framework** — Token cost estimation and visual dashboard before team launch
+- **Race Condition Fix** — Single-writer pattern for sprint-status.yaml
+- See [CHANGELOG](CHANGELOG.md) for full details
+
 ## What's New in v5.6 - Claude Code 2.1.33 / 2.1.34
 
 - **Agent Memory** (v2.1.33): Persistent `memory` frontmatter for agents (user/project/local scopes)