Setup

---
name: brewcode:setup
description: "Checks prerequisites and analyzes project structure to generate adapted templates in .claude/tasks/templates/."
disable-model-invocation: true
argument-hint: "[universal-template-path]"
allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
context: fork
model: opus
---


<instructions>

## Phase 0: Prerequisites Check

**Agent:** developer | **Action:** Verify and install required tools

> **Context:** This phase auto-checks prerequisites. If all required components are present, it skips to Phase 1 silently.

### Step 1: State Check

**EXECUTE** using Bash tool:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" state && echo "✅ state" || echo "❌ state FAILED"
```

> **STOP if ❌** — verify install.sh exists in scripts/.

### Step 2: Evaluate Results

Parse the state output table. Check required components: **brew**, **timeout**, **jq**.

- **If ALL required show ✅** → Skip to Phase 1 (log: "All prerequisites present, skipping installation.")
- **If ANY required show ❌ missing** → Continue to Step 3

### Step 2.5: Load Deferred Tool Schemas

Call **ToolSearch** with `query: "select:AskUserQuestion"` to load its schema.
This is required for Claude Code v2.1.107+ where AskUserQuestion is deferred.
If ToolSearch fails or returns no result, continue — AskUserQuestion may already be loaded.

### Step 3: Install Required Components

**EXECUTE** using Bash tool:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" check-timeout && echo "✅ timeout-check" || echo "❌ timeout-check FAILED"
```

**If TIMEOUT_EXISTS=false** → **ASK** (AskUserQuestion):
- Question: "The `timeout` command is missing. Create symlink to `gtimeout`? This is REQUIRED for brewcode."
- Options: "Yes, create" | "Cancel setup"

> **If cancel** → STOP: "Setup cancelled. timeout command is required for brewcode."

**EXECUTE** using Bash tool:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" required && echo "✅ required" || echo "❌ required FAILED"
```

> **STOP if ❌** — required components must be installed before continuing.

**If timeout still missing** → **EXECUTE**: `bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" timeout`

### Step 4: Semantic Search (Optional)

**If grepai not installed** → **ASK** (AskUserQuestion):
- Question: "Install semantic search (grepai)? Enables AI-powered code search (~1.5GB)."
- Options: "Yes, install grepai" | "Skip"

**If Yes** → **EXECUTE**: `bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" grepai`

### Step 5: Summary

**EXECUTE** using Bash tool:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/install.sh" summary && echo "✅ summary" || echo "❌ summary FAILED"
```

---

## Phase 1: Project Structure Analysis

**Agent:** Explore | **Action:** Scan project and gather intelligence

> **Context:** BC_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).

### Scan Commands

**EXECUTE** using Bash tool — gather project info:
```bash
bash "scripts/setup.sh" scan && echo "✅ scan" || echo "❌ scan FAILED"
```

> **STOP if ❌** — check script exists and plugin is installed.

---

## Phase 2: Intelligence Analysis

**Agent:** Plan | **Action:** Consolidate findings and create adaptation strategy

### Create Adaptation Plan

```markdown
# Adaptation Plan

## Tech Stack
- Language: [Java/Node.js/Python/Go/Rust]
- Framework: [Spring Boot/Express/Django/etc]
- Build: [Maven/Gradle/npm/pip/cargo]

## Testing
- Framework: [JUnit 5/pytest/Jest/Go testing]
- Assertion: [AssertJ/Hamcrest/Chai/assert]
- Mocking: [Mockito/unittest.mock/Sinon]
- Data: [DBRider/Testcontainers/fixtures]

## Database
- Type: [PostgreSQL/MySQL/MongoDB/Redis/ClickHouse]
- Access: [JOOQ/JPA/Hibernate/Sequelize/SQLAlchemy]

## Project Agents
- agent-name: purpose (model)

## Key Patterns (from CLAUDE.md)
- Pattern 1
- Pattern 2
- Pattern 3

## Template Adaptations
- Update AGENTS section with project agents
- Add tech-specific constraints
- Customize verification checklists
- Add database-specific final review agent
```

---

## Phase 3: Template Generation

**Agent:** developer | **Action:** Generate adapted template at `.claude/tasks/templates/PLAN.md.template`

### Create Structure

**EXECUTE** using Bash tool:
```bash
bash "scripts/setup.sh" structure && echo "✅ structure" || echo "❌ structure FAILED"
```

> **STOP if ❌** — verify .claude/tasks directory is writable.

### Copy/Update Templates

**EXECUTE** using Bash tool — sync templates from plugin (always overwrites if changed):
```bash
bash "scripts/setup.sh" sync && echo "✅ sync" || echo "❌ sync FAILED"
```

> **STOP if ❌** — verify plugin templates exist.

> **Note:** Templates synced from plugin. Rules created once (never overwritten). Review skill adapted by AI.

### Template Modifications

| Section | Adaptation |
|---------|-----------|
| Agents | Add project-specific agents from `.claude/agents/` |
| Reference Examples | Fill with project's reference files (controllers, services, tests) |
| Phase V agents | Customize reviewer focus for detected testing/code patterns |
| Final Review | Add project agents (db_expert, etc.) if relevant tech detected |

### Required Sections

> Preserve universal structure. Key sections to adapt:

```markdown
## Agents — Add project agents above Core Agents
## Reference Examples — R1..RN with project's canonical files
## Phases — Each phase has: Agent, Status, Context (C#), Refs (R#)
## Phase NV: Verification — 2+ agents, one checks patterns compliance
## Final Review — 3+ agents parallel
## Context Index — C1..CN task-specific files
```

---

## Phase 3.5: Copy and Adapt Review Skill

**Agent:** developer | **Action:** Copy review skill template and adapt for project

### Create Review Skill Directory and Copy Template

Before running the script, export project analysis results as environment variables:
```bash
export DETECTED_TECH="<detected technology stack from analysis>"
export AGENT_COUNT="<number of agents discovered>"
export GROUP_COUNT="<number of review groups>"
export MAIN_AGENT="<primary review agent name>"
export TEST_AGENT="<test review agent name>"
export DB_AGENT="<database review agent name>"
```

**EXECUTE** using Bash tool — create directory and copy review skill template:
```bash
bash "scripts/setup.sh" review && echo "✅ review" || echo "❌ review FAILED"
```

> **STOP if ❌** — verify review template exists in plugin.

### Adapt Review Skill

Replace placeholders based on Phase 2 analysis:

| Placeholder | Source | Example |
|-------------|--------|---------|
| `{PROJECT_AGENTS_TABLE}` | `.claude/agents/` scan | `\| db_expert \| PostgreSQL \| DB layer \|` |
| `{TECH_SPECIFIC_CHECKS}` | Detected tech stack | See Tech-Specific Checks below |
| `{PROJECT_RULES}` | CLAUDE.md patterns | AssertJ rules, Lombok, logging |
| `{MAIN_AGENT}` | Project agent or `reviewer` | `reviewer` |
| `{TEST_AGENT}` | Project agent or `tester` | `tester` |
| `{DB_AGENT}` | Project agent or `sql_expert` | `db_expert` |
| `{CUSTOM_GROUPS}` | Additional review groups | Security, API validation |
| `{CODEBASE_BLOCKS}` | Detected source patterns | `src/main/**`, `src/test/**` |

### Tech-Specific Checks Templates

**Java/Spring:**
```markdown
| Category | Checks |
|----------|--------|
| DI | Constructor injection, no field injection, @RequiredArgsConstructor |
| Transactions | @Transactional scope, rollback rules, isolation levels |
| Null-safety | Optional usage, @NonNull/@Nullable, null checks |
| N+1 | Eager vs lazy loading, batch fetching, entity graphs |
| Security | @PreAuthorize, input validation, SQL injection |
| Lombok | @Value, @Builder, @Slf4j usage |
```

**Node.js/TypeScript:**
```markdown
| Category | Checks |
|----------|--------|
| Async | Promise handling, unhandled rejections, async/await |
| Types | Strict null checks, type guards, generics |
| Validation | Input sanitization, schema validation (Zod/Joi) |
| Security | XSS prevention, CSRF tokens, helmet.js |
| Imports | ESM vs CJS, barrel exports, circular deps |
```

**Python:**
```markdown
| Category | Checks |
|----------|--------|
| Type hints | Function signatures, return types, generics |
| Exceptions | Specific exception types, context managers |
| Async | asyncio patterns, event loop handling |
| Security | SQL parameterization, input validation |
| Style | PEP8, docstrings, comprehensions |
```

**Go:**
```markdown
| Category | Checks |
|----------|--------|
| Error handling | Error wrapping, sentinel errors, error types |
| Concurrency | Goroutine leaks, channel patterns, sync primitives |
| Memory | Slice capacity, pointer semantics, defer usage |
| Security | SQL injection, input validation |
| Interfaces | Small interfaces, composition |
```

### Validation

**EXECUTE** using Bash tool — verify review skill:
```bash
test -f .claude/skills/brewcode-review/SKILL.md && echo "✅ Review skill created" || echo "❌ Review skill MISSING"
grep -q "Tech-Specific\|tech-specific\|Category.*Checks" .claude/skills/brewcode-review/SKILL.md && echo "✅ Tech checks" || echo "❌ Tech checks MISSING"
```

> **STOP if any ❌** — review skill must be created before continuing.

---

## Phase 3.6: Copy Configuration

**Agent:** developer | **Action:** Copy configuration template for runtime settings

**EXECUTE** using Bash tool — copy/update config template:
```bash
bash "scripts/setup.sh" config && echo "✅ config" || echo "❌ config FAILED"
```

> **STOP if ❌** — verify .claude/tasks/cfg directory exists.

### Configuration Options

| Setting | Default | Description |
|---------|---------|-------------|
| `knowledge.maxEntries` | 100 | Max KNOWLEDGE.jsonl entries after compaction |
| `knowledge.maxTokens` | 500 | Max tokens in ## K block injected to agents |
| `knowledge.priorities` | `["❌","✅","ℹ️"]` | Priority order for knowledge entries |
| `stop.maxAttempts` | 20 | Stop attempts before escape mechanism triggers |
| `agents.system` | [...] | System agents (don't receive ## K injection) |

> **Hooks-only architecture:** No external runtime. All context management via Claude Code hooks.

---

## Phase 4: Validation

**Agent:** developer | **Action:** Verify template structure

**EXECUTE** using Bash tool — ALL must pass:
```bash
bash "scripts/setup.sh" validate && echo "✅ validate" || echo "❌ validate FAILED"
```

> **STOP if any ❌** — go back to "Copy Templates" step and fix.

### Validation Report

| Check | Status |
|-------|--------|
| PLAN template | `.claude/tasks/templates/PLAN.md.template` |
| SPEC template | `.claude/tasks/templates/SPEC.md.template` |
| KNOWLEDGE template | `.claude/tasks/templates/KNOWLEDGE.jsonl.template` |
| Config file | `.claude/tasks/cfg/brewcode.config.json` |
| Project agents | [N] from `.claude/agents/` |
| Reference Examples | [N] canonical files populated |
| Tech-specific adaptations | Testing framework, DB patterns |
| Review skill | `.claude/skills/brewcode-review/SKILL.md` |

---

## Phase 5: Update Global CLAUDE.md Agents

**Agent:** developer | **Action:** Update agents section in global CLAUDE.md

### Step 1: Collect Agents

**EXECUTE** using Bash tool:
```bash
bash "scripts/setup.sh" agents > /tmp/agents-section.md && cat /tmp/agents-section.md
```

> **Output = Ready-to-insert content.** Script collects system + global + plugin agents.
> Internal agents (bc-coordinator, bc-grepai-configurator, bc-knowledge-manager) are automatically excluded.

### Step 2: Analyze Existing CLAUDE.md

**READ** `~/.claude/CLAUDE.md` using Read tool.

**LLM Analysis** — find ALL agent-related sections:
- `## Agents`, `## Agent Selection`, `### Core Agents`, `### Global Utility Agents`
- Any tables with columns like `Agent | Model | Purpose`
- Any lists of agent names (developer, tester, reviewer, etc.)

**Identify boundaries:**
- Start line number of agent section(s)
- End line number (before next unrelated ## heading)

### Step 3: Ask User

> **Preflight:** Call ToolSearch with `query: "select:AskUserQuestion"` before proceeding.

**ASK USER** with AskUserQuestion:
- Question: "Found agent sections in ~/.claude/CLAUDE.md. Replace with optimized LLM-friendly format?"
- Options:
  - "Yes — replace all agent sections"
  - "No — keep current format"

### Step 4: If YES — Replace

> **CRITICAL:** Use EXACTLY the content from `/tmp/agents-section.md`.
> DO NOT add agents manually — the script already filters internal agents.
> Internal agents (bc-coordinator, bc-grepai-configurator, bc-knowledge-manager) are excluded by design.

Using Edit tool:
1. **Read** `/tmp/agents-section.md` to get the exact replacement content
2. Find the `## Agents — DELEGATE!` section in `~/.claude/CLAUDE.md`
3. Replace that section with the EXACT content from `/tmp/agents-section.md`
4. Preserve `### Global Skills` subsection if it exists (append after agents table)
5. Preserve all non-agent content

**Key:** LLM determines section boundaries, not grep. Content comes from script output.

</instructions>

---

## Output Format

```markdown
# Template Adaptation Complete

## Detection

| Field | Value |
|-------|-------|
| Arguments | `{received args or empty}` |
| Mode | `full` |

## Tech Stack

| Category | Value |
|----------|-------|
| Language | [detected] |
| Framework | [detected] |
| Testing | [framework] |
| Database | [type/access] |
| Project Agents | [N]: `agent1`, `agent2` |

## Adaptations

| Section | Changes |
|---------|---------|
| Agents | +[N] project agents |
| Reference Examples | [N] canonical files |
| Phase V | Reviewers for [tech] patterns |
| Final Review | +[db_expert/project agents] |
| Review Skill | Tech-specific checks, project rules |

## Templates

**Plan template:** `.claude/tasks/templates/PLAN.md.template`
**Review skill:** `.claude/skills/brewcode-review/SKILL.md`

## Usage

/brewcode:spec "Implement feature X"
/brewcode:review "Check null safety"
```

---