refactor: rename agents to PascalCase + add swarm orchestration system

CLAUDE.md

@@ -95,22 +95,22 @@ ensure_docs_dir "audits/$BRANCH_SLUG"
 ### Agent Persistence Rules
 
 **Persisting agents** (create files in `.docs/`):
-- `catch-up` → `.docs/CATCH_UP.md` (overwrite latest)
+- `CatchUp` → `.docs/CATCH_UP.md` (overwrite latest)
 - `devlog` → `.docs/status/{timestamp}.md` + `compact/` + `INDEX.md`
-- `debug` → `.docs/debug/debug-{timestamp}.md` + `KNOWLEDGE_BASE.md`
-- `brainstorm` → `.docs/brainstorm/{topic-slug}-{timestamp}.md`
-- `design` → `.docs/design/{topic-slug}-{timestamp}.md`
-- `audit-*` (9 types) → `.docs/audits/{branch-slug}/{type}-report-{timestamp}.md`
-- `code-review` → `.docs/audits/{branch-slug}/review-summary-{timestamp}.md`
-- `release` → `.docs/releases/RELEASE_NOTES_v{version}.md`
+- `Debug` → `.docs/debug/debug-{timestamp}.md` + `KNOWLEDGE_BASE.md`
+- `Brainstorm` → `.docs/brainstorm/{topic-slug}-{timestamp}.md`
+- `Design` → `.docs/design/{topic-slug}-{timestamp}.md`
+- `*Review` (9 types) → `.docs/audits/{branch-slug}/{type}-report-{timestamp}.md`
+- `CodeReview` → `.docs/audits/{branch-slug}/review-summary-{timestamp}.md`
+- `Release` → `.docs/releases/RELEASE_NOTES_v{version}.md`
 
 **Non-persisting agents** (ephemeral, no files):
-- `commit` - Creates git commit only
-- `get-issue` - Fetches GitHub issue, creates branch
-- `pull-request` - Creates GitHub PR only
-- `project-state` - Read-only, used by catch-up
-- `pr-comments` - Creates PR comments only
-- `tech-debt` - Updates GitHub issue only
+- `Commit` - Creates git commit only
+- `GetIssue` - Fetches GitHub issue, creates branch
+- `PullRequest` - Creates GitHub PR only
+- `ProjectState` - Read-only, used by CatchUp
+- `PrComments` - Creates PR comments only
+- `TechDebt` - Updates GitHub issue only
 
 ### Implementation Checklist
 

README.md

@@ -87,23 +87,23 @@ This gives you the best of both worlds: automatic assistance when needed, manual
 
 | Sub-Agent | Specialty | Purpose |
 |-----------|-----------|---------|
-| `audit-security` | Security Analysis | Expert vulnerability detection and security code review |
-| `audit-performance` | Performance | Optimization and bottleneck detection |
-| `audit-architecture` | Architecture | Design pattern analysis and code structure review |
-| `audit-tests` | Testing | Test quality, coverage, and effectiveness analysis (surgical execution) |
-| `audit-complexity` | Complexity | Code complexity and maintainability assessment |
-| `audit-dependencies` | Dependencies | Dependency management and security analysis |
-| `audit-database` | Database | Database design and optimization review |
-| `audit-documentation` | Documentation | Docs-code alignment, API accuracy, comment quality |
-| `audit-typescript` | TypeScript | Type safety enforcement and TypeScript code quality |
-| `brainstorm` | Design Decisions | Explore architectural approaches and evaluate trade-offs |
-| `design` | Implementation Planning | Detailed implementation design with integration points and edge cases |
-| `catch-up` | Context Restoration | Project status and context restoration with validation |
-| `commit` | Git Operations | Intelligent commit creation with safety checks |
-| `get-issue` | GitHub Issues | Fetch issue details and create working branches |
-| `pull-request` | PR Creation | Analyze commits/changes and generate comprehensive PR descriptions |
-| `release` | Release Automation | Project-agnostic release workflow with version management |
-| `debug` | Debugging | Systematic debugging with hypothesis testing and issue tracking |
+| `SecurityReview` | Security Analysis | Expert vulnerability detection and security code review |
+| `PerformanceReview` | Performance | Optimization and bottleneck detection |
+| `ArchitectureReview` | Architecture | Design pattern analysis and code structure review |
+| `TestsReview` | Testing | Test quality, coverage, and effectiveness analysis (surgical execution) |
+| `ComplexityReview` | Complexity | Code complexity and maintainability assessment |
+| `DependenciesReview` | Dependencies | Dependency management and security analysis |
+| `DatabaseReview` | Database | Database design and optimization review |
+| `DocumentationReview` | Documentation | Docs-code alignment, API accuracy, comment quality |
+| `TypescriptReview` | TypeScript | Type safety enforcement and TypeScript code quality |
+| `Brainstorm` | Design Decisions | Explore architectural approaches and evaluate trade-offs |
+| `Design` | Implementation Planning | Detailed implementation design with integration points and edge cases |
+| `CatchUp` | Context Restoration | Project status and context restoration with validation |
+| `Commit` | Git Operations | Intelligent commit creation with safety checks |
+| `GetIssue` | GitHub Issues | Fetch issue details and create working branches |
+| `PullRequest` | PR Creation | Analyze commits/changes and generate comprehensive PR descriptions |
+| `Release` | Release Automation | Project-agnostic release workflow with version management |
+| `Debug` | Debugging | Systematic debugging with hypothesis testing and issue tracking |
 
 **How Sub-Agents Work:**
 - Specialized AI assistants with deep expertise in specific domains
@@ -114,7 +114,7 @@ This gives you the best of both worlds: automatic assistance when needed, manual
 **Invoking Sub-Agents:**
 ```bash
 # Explicit invocation
-"Use the audit-security sub-agent to analyze this authentication code"
+"Use the SecurityReview sub-agent to analyze this authentication code"
 
 # Automatic delegation (Claude Code decides which sub-agent to use)
 "Review this code for security issues"

src/claude/CLAUDE.md

@@ -1,4 +1,4 @@
-# Global Claude Code Instructions
+# Global Development Context
 
 ## ROLE
 

src/claude/agents/devflow/audit-architecture.md

@@ -1,7 +1,6 @@
 ---
-name: audit-architecture
+name: ArchitectureReview
 description: Software architecture and design pattern analysis specialist
-tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
@@ -112,13 +111,50 @@ git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.tx
 - ✅ APPROVED
 ```
 
-### Step 5: Save Report
+### Step 5: Create PR Line Comments
+
+**If PR_NUMBER is provided**, create line-specific comments for 🔴 blocking issues:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+# For each blocking issue with file:line
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" -f line="$LINE" -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+    sleep 1  # Rate limiting
+}
+
+# Comment format:
+# **🔴 Architecture: {Issue}**
+# {Description}
+# **Suggested Fix:** {code}
+# ---
+# *Severity: {level}*
+# <sub>🤖 Claude Code `/code-review`</sub>
+```
+
+### Step 6: Save Report
 
 ```bash
 REPORT_FILE="${AUDIT_BASE_DIR}/architecture-report.${TIMESTAMP}.md"
 mkdir -p "$(dirname "$REPORT_FILE")"
 cat > "$REPORT_FILE" <<'REPORT'
 {Generated report content}
+
+---
+## PR Comments: ${COMMENTS_CREATED} created, ${COMMENTS_SKIPPED} skipped
 REPORT
 echo "✅ Architecture audit saved: $REPORT_FILE"
 ```

src/claude/agents/devflow/audit-complexity.md

@@ -1,7 +1,6 @@
 ---
-name: audit-complexity
+name: ComplexityReview
 description: Code complexity and maintainability analysis specialist
-tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
@@ -112,13 +111,41 @@ git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.tx
 - ✅ APPROVED
 ```
 
-### Step 5: Save Report
+### Step 5: Create PR Line Comments
+
+**If PR_NUMBER is provided**, create line-specific comments for 🔴 blocking issues:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" -f line="$LINE" -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+    sleep 1
+}
+```
+
+### Step 6: Save Report
 
 ```bash
 REPORT_FILE="${AUDIT_BASE_DIR}/complexity-report.${TIMESTAMP}.md"
 mkdir -p "$(dirname "$REPORT_FILE")"
 cat > "$REPORT_FILE" <<'REPORT'
 {Generated report content}
+
+---
+## PR Comments: ${COMMENTS_CREATED} created, ${COMMENTS_SKIPPED} skipped
 REPORT
 echo "✅ Complexity audit saved: $REPORT_FILE"
 ```

src/claude/agents/devflow/audit-database.md

@@ -1,7 +1,6 @@
 ---
-name: audit-database
+name: DatabaseReview
 description: Database design and optimization review specialist
-tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
@@ -112,13 +111,41 @@ git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.tx
 - ✅ APPROVED
 ```
 
-### Step 5: Save Report
+### Step 5: Create PR Line Comments
+
+**If PR_NUMBER is provided**, create line-specific comments for 🔴 blocking issues:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" -f line="$LINE" -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+    sleep 1
+}
+```
+
+### Step 6: Save Report
 
 ```bash
 REPORT_FILE="${AUDIT_BASE_DIR}/database-report.${TIMESTAMP}.md"
 mkdir -p "$(dirname "$REPORT_FILE")"
 cat > "$REPORT_FILE" <<'REPORT'
 {Generated report content}
+
+---
+## PR Comments: ${COMMENTS_CREATED} created, ${COMMENTS_SKIPPED} skipped
 REPORT
 echo "✅ Database audit saved: $REPORT_FILE"
 ```

src/claude/agents/devflow/audit-dependencies.md

@@ -1,7 +1,6 @@
 ---
-name: audit-dependencies
+name: DependenciesReview
 description: Dependency management and security analysis specialist
-tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
@@ -112,13 +111,41 @@ git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.tx
 - ✅ APPROVED
 ```
 
-### Step 5: Save Report
+### Step 5: Create PR Line Comments
+
+**If PR_NUMBER is provided**, create line-specific comments for 🔴 blocking issues:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" -f line="$LINE" -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+    sleep 1
+}
+```
+
+### Step 6: Save Report
 
 ```bash
 REPORT_FILE="${AUDIT_BASE_DIR}/dependencies-report.${TIMESTAMP}.md"
 mkdir -p "$(dirname "$REPORT_FILE")"
 cat > "$REPORT_FILE" <<'REPORT'
 {Generated report content}
+
+---
+## PR Comments: ${COMMENTS_CREATED} created, ${COMMENTS_SKIPPED} skipped
 REPORT
 echo "✅ Dependencies audit saved: $REPORT_FILE"
 ```

src/claude/agents/devflow/audit-documentation.md

@@ -1,7 +1,6 @@
 ---
-name: audit-documentation
+name: DocumentationReview
 description: Documentation quality and code-documentation alignment specialist
-tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
@@ -112,13 +111,41 @@ git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.tx
 - ✅ APPROVED
 ```
 
-### Step 5: Save Report
+### Step 5: Create PR Line Comments
+
+**If PR_NUMBER is provided**, create line-specific comments for 🔴 blocking issues:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" -f line="$LINE" -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+    sleep 1
+}
+```
+
+### Step 6: Save Report
 
 ```bash
 REPORT_FILE="${AUDIT_BASE_DIR}/documentation-report.${TIMESTAMP}.md"
 mkdir -p "$(dirname "$REPORT_FILE")"
 cat > "$REPORT_FILE" <<'REPORT'
 {Generated report content}
+
+---
+## PR Comments: ${COMMENTS_CREATED} created, ${COMMENTS_SKIPPED} skipped
 REPORT
 echo "✅ Documentation audit saved: $REPORT_FILE"
 ```