git:20260703.251991a to git:20260727.6ea57e6

# CLAUDE.md — AI agent instructions for great_cto

This file is read automatically by Claude Code at session start.

Rules here apply to all agents working in this repository.

---

## Privacy — private project names

**Never mention specific private project names in any artifact that could reach

the public repository:**

- Commit messages

- PR titles / descriptions

- Code comments

- Documentation (docs/, README, CHANGELOG)

- Agent verdicts (verdicts/*.log)

- Any string literal in source code

Use the placeholder **`<private-project>`** instead.

Examples of private names (not exhaustive — when in doubt, use the placeholder):

any client/product repos that are not `great_cto` itself.

Rationale: `great_cto` is a public open-source tool. References to private

project names in its history constitute a privacy leak for the owner's clients.

The pre-push hook (`scripts/hooks/pre-push.sh`) enforces this automatically.

---

## Privacy — local paths

Never hardcode `/Users/<username>/...` paths in committed files.

Use `~/.great_cto/` notation or environment variable references.

---

## Privacy — telemetry

`great_cto` ships an **opt-in** telemetry pipeline (`packages/cli/src/telemetry.ts`) that is

**off by default** — nothing is sent unless a user explicitly enables it. `docs/PRIVACY.md` is

the source of truth for what's collected, what's never collected, and how opt-in/opt-out work;

keep it in sync with the code.

Rules for agents:

- Never make telemetry (or any new tracking) on-by-default. Default must stay off.

- Never expand what's collected, add a new event, or add a new endpoint without an ADR that

updates `docs/PRIVACY.md` in the same change.

- Do not add tracking, install pings, or analytics calls outside the existing telemetry module

and its documented, opt-in fields.

---

## Code style

- TypeScript strict mode; no `any` without comment explaining why

- ESM modules only (`.mjs` / `"type":"module"`)

- Node.js ≥ 20 — use `node:` prefix for built-ins

- No external runtime dependencies in `packages/board/server.mjs` (zero-dep)

- Commit format: `<type>: <description>` (feat/fix/refactor/docs/test/chore/perf/ci)

---

## Agent routing

See `skills/great_cto/SKILL.md` for subagent routing table.

Auto-attach reviewers fire from `scripts/hooks/auto-attach-reviewers.mjs`.

---

## Request classifier

When the model receives a request, classify it first — the class determines which agents run and whether a gate is needed.

| Class | Signal words / patterns | Pipeline |

|-------|------------------------|---------|

| **QUESTION** | "what is", "how does", "explain", "why", "what's the difference" | Answer inline — no agents |

| **SURVEY** | "show me", "list", "what files", "status", "what's pending", "show report" | Read-only — Explore or Bash only |

| **SIMPLE CODE** | "fix", "typo", "rename", "minor", "patch", single file implied | Fast path: senior-dev → gate:ship |

| **COMPLEX CODE** | "implement", "build", "add feature", "refactor", "migrate" | Full pipeline: arch → pm → senior-dev → qa+cso → devops |

| **DESIGN** | "design", "architect", "plan", "RFC", "ADR", "how should we" | Architect agent → gate:arch → optional pm |

| **SLASH CMD** | Message starts with `/` | Route to matching command in `commands/` |

| **INCIDENT** | "broken", "down", "prod issue", "incident", "P0", "alert" | l3-support immediately, no pipeline |

| **COORDINATE** | "parallelize", "orchestrate", "3+ streams", complex dependency graph | coordinator agent |

**Auto-routing rule**: classify BEFORE choosing an agent. If the class is ambiguous between SIMPLE CODE and COMPLEX CODE, prefer COMPLEX CODE — the cost of under-engineering exceeds the cost of a gate pause.

---

## Triage Gate — depth inside each class

After classifying a request, apply the triage gate to select how much process to run. This prevents running the full pipeline on trivial changes.

### SIMPLE CODE — depth levels

```

Classify into one of three depths:

Tiny — single expression / typo / rename within one function.

→ Fix inline, no plan, no Beads task. 30 s turnaround.

Small — 1-file change, clear scope, no behavior risk.

→ senior-dev direct, no architect. Gate: gate:ship only.

Medium — 2-5 files, some behavior risk, needs validation.

→ senior-dev → qa-engineer. Gate: gate:ship.

```

Escalation check: if you discover ambiguity, cross-file risk, data model/API/permission impact while working → stop, reclassify as COMPLEX CODE.

### COMPLEX CODE — depth levels

```

Classify into one of three depths:

Small — well-understood scope, ≤5 files, low ambiguity.

→ architect (brief) → senior-dev → gate:ship.

Skip pm decomposition if < 3 work streams.

Medium — cross-file, some design decisions needed.

→ architect → pm → senior-dev → qa+cso → gate:ship.

Large — significant ambiguity, migrations, cross-cutting concerns,

rollout risk, backward compat constraints.

→ Full pipeline: arch → pm → senior-dev → qa+cso → devops.

Two gates: gate:arch + gate:ship.

⚠️ Decomposition Matrix required before any implementation starts.

Coordinator must produce this table (or block until it exists):

| Stream | Write-zone (files/dirs) | Depends on | Why parallel-safe |

|--------|------------------------|------------|-------------------|

| <name> | <owned files> | <stream #> | <no shared state> |

If two streams share any file → force sequential, add dependency.

Reference: shared/orchestrator.toml [parallelism] section.

```

**Default rule**: when depth is ambiguous, choose the deeper level — skipping a gate is recoverable, skipping architecture review on a Large change is not.