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 — the global memory layer

~/.great_cto/{preferences,decisions,lessons}.md is injected into every session of every project. Nothing about one project goes there — what is true of a project lives in its own .great_cto/. read-global-memory.mjs enforces it at the read door: an entry that names a private project (the same terms pre-push.sh derives) or declares project: <name> is dropped and the operator is warned. Anything that writes to the global layer — learner, /crystallize, a gate approval — writes cross-project patterns only, with the project name replaced by <private-project>.

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.

Authorship — everything is made as avelikiy

Every change to great_cto — commits, pushes, tags, releases, PRs, issues and comments — is made as avelikiy:

• Git author and committer: avelikiy <avelikiy@users.noreply.github.com>, the repository's own git config. Never pass -c user.name=… / -c user.email=…, never --author, never commit with another address.
• GitHub actions (gh pr, gh issue, gh release, comments): switch to the avelikiy account first — gh auth switch -u avelikiy.

Rationale: GitHub attributes a commit by its email. A commit with the owner's name and a different address is attributed to whatever account that address belongs to, and that account appears in the public contributors list for good.

The pre-push hook (scripts/hooks/pre-push.sh, check 1c) refuses a commit whose author or committer is avelikiy with any other address.

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)

Project capabilities

.great_cto/PROJECT.md may declare what this project's operational tools actually are — log store, pager, error tracker — under a capabilities: block. Agents refer to capabilities, never to a vendor, so swapping Datadog for Grafana changes no agent. Three states, and undeclared is not none: docs/reference/project-capabilities.md.

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.

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.

Gates follow reversibility, not just position (ADR-009)

The gates above are positional — gate:arch after architecture, gate:ship before deploy. That covers the main path, but position and cost-of-undo are different axes: an operation that is expensive to reverse gets a gate only if it happens to land on a stage boundary. /crystallize approve did not, and shipped ungated for months while activating a pattern injected into every future run of every project.

So ask the second question too:

Is this expensive to undo? If yes, it needs a human decision — wherever it sits in the pipeline.

Expensive-to-undo means any of:

A gate is not the only valid answer — a refusal (devops will not touch prod domains), a plan-and-stop (infra-provisioner prints cost and waits), or an evidence requirement (crystallize needs an eval) all satisfy it. Silence does not. Ask at design time, when the capability is added — not after the incident.