# great-cto

> CLI for the [great_cto](https://github.com/avelikiy/great_cto) engineering workspace, controlled runs and verified release updates.

**Verified distribution boundary:** ADR-045 replaces mutable installation and update
paths with signed artifact admission. This implementation refuses `init`, native
plugin refresh and automatic companion installation before mutation. The plain
npm self-update adapter requires an independently configured verifier and exact
signed release assets. See [verified updates](../../docs/reference/verified-updates.md).
The installation walkthrough below describes the legacy 3.70.1 flow; it is not
an activation route for this implementation.

```bash
npx great-cto init
```

That's it. The CLI detects your stack, picks the right archetype, clones the plugin, enables it, and writes a pre-filled `PROJECT.md`.

## What it does

1. **Scans** your project for stack signals — `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Chart.yaml`, `*.tf`, `hardhat.config.*`, etc.
2. **Picks** the matching great_cto archetype:
   - `web-service` · `mobile-app` · `ai-system` · `commerce` · `web3`
   - `data-platform` · `infra` · `library` · `iot-embedded` · `regulated` · `greenfield`
3. **Installs** the plugin into `~/.claude/plugins/cache/local/great_cto/<latest>/`
4. **Enables** it in `~/.claude/settings.json` (atomic merge — other keys preserved, backup taken)
5. **Bootstraps** `.great_cto/PROJECT.md` pre-filled with archetype, stack, suggested compliance frameworks

After install, restart Claude Code and run `/inbox` or `/audit`.

## Everyday use (source version)

```bash
great-cto run "build, fix or investigate something"
great-cto status
great-cto resume
```

Run launches interactive Claude Code through `/start`; resume targets its exact
pre-bound session through `/resume`. The plugin must be loaded. Status reads
private task metadata without launching a model. `/start` handles existing projects without resetting
their configuration. For the controlled Codex runtime use `--host codex` and,
when starting, an explicit scope such as `--allow src,tests,docs`.
`status --json` works for both hosts. `--task UUID` selects persisted task identity;
Codex status also includes its sanitized run listing. Optional repeated `--accept`
criteria are stored and passed to execution and verification. `--operation UUID`
provides idempotent launch receipts, and `resume --revision N` rejects stale intent.
See [the shared task contract](../../docs/WORK-TASK-CONTRACT.md) for ownership and recovery.
`resume --host codex` selects only one unfinished run in the target project;
ambiguity requires a UUID. Pending gates, runtime locks and verifier checks remain
in force. `--dir PATH` targets another project; `--dry-run` previews without agents.
Advanced policies, recovery and approvals stay under `codex-host`.
Research uses explicit `run --intent research`; controlled research writes reports
only and preserves its bounded stage retry budget. Advanced host approvals, outcome
attestations and cohort reports are under `task work`, documented in the shared
contract. Resume progress is measured from bound stage evidence, not exit zero.
Published npm versions may not include these source additions yet.

## What the plugin gives you

The CLI installs it; these are what it installs.

- **A pipeline of specialist agents** — architect, product owner, senior dev, QA,
  security officer, and archetype-specific reviewers — that run in sequence with
  human approval gates at the points that are expensive to undo.
- **Spending caps that refuse.** Set a per-agent cap; when measured spend passes
  it the dispatcher declines to run that agent instead of quietly continuing. An
  agent with no measurement reads as `unmeasured`, never as `$0`.
- **A board at `localhost:3141`** — tasks, metrics, per-agent budgets, docs
  search, and the decision journal, all served from your own machine. Nothing
  leaves it.
- **A decision journal** that records what each dispatch decided and why, so a
  pipeline that did not run looks different from one that ran and found nothing.

Telemetry is opt-in and off by default — see
[docs/PRIVACY.md](https://github.com/avelikiy/great_cto/blob/main/docs/PRIVACY.md).

## Examples

### Commerce detection (Stripe + Next.js)

```
[1/5] scanning /path/to/saas
  stack: next.js, nodejs, prisma, react, stripe, supabase, typescript
  languages: javascript, typescript
  tests: yes  CI: yes
[2/5] picking archetype
  archetype: commerce (confidence: medium)
  rationale: payments SDK detected: Stripe — PCI-DSS gate mandatory
  suggested compliance: gdpr, pci-dss
```

### AI system (MCP + Anthropic SDK)

```
  archetype: ai-system (confidence: high)
  rationale: AI/LLM tooling detected (MCP SDK, Anthropic SDK, LangChain) —
             security gate mandatory for prompt injection + output sanitization
  suggested compliance: eu-ai-act
```

### Infra repo (Terraform + Helm)

```
  archetype: infra (confidence: high)
  rationale: infrastructure-as-code detected: Terraform, Helm
```

## Options

```
npx great-cto init [options]

  -y, --yes              Skip confirmation prompts (non-interactive)
      --dry-run          Show what would be done without doing it
      --force            Reinstall even if already present
      --archetype NAME   Override detected archetype
      --version-tag VER  Pin to specific great_cto version (default: latest)
      --dir PATH         Run against a different directory (default: cwd)
  -h, --help             Show help
  -v, --version          Show CLI version
```

## Safety

- **Atomic `settings.json` merge**: a timestamped `.bak` file is written before any change. Other `enabledPlugins` entries and unrelated keys are preserved.
- **Dry-run by default**: run `--dry-run` first to see exactly what will happen.
- **Idempotent**: running twice does nothing the second time (unless `--force`).
- **Never overwrites `PROJECT.md`**: if you already have one, the CLI leaves it untouched.

## Requirements

- **Node.js ≥ 18.17.0** (Node 18 / 20 / 22 all tested in CI)
- **Git** (to clone the plugin repo)
- [Claude Code](https://claude.com/claude-code)

## Trust signals

- Zero runtime dependencies — only Node built-ins (`node:fs`, `node:path`, etc.)
- 305 unit tests covering stack detection, archetype scoring, and settings merge
- Tests and the release gate run locally (`scripts/ci-local.sh`) — the hosted CI
  workflows are present in the repo but have not run since June 2026, so treat the
  badge-shaped claims in this file as claims about the local gate, not a cloud matrix
- Source: [`packages/cli/src/`](https://github.com/avelikiy/great_cto/tree/main/packages/cli/src) — ~1.2k LOC TypeScript

## License

MIT — same as the plugin.

## Links

- Plugin: [github.com/avelikiy/great_cto](https://github.com/avelikiy/great_cto)
- Issues: [github.com/avelikiy/great_cto/issues](https://github.com/avelikiy/great_cto/issues)
- Author: [velykyi](https://www.linkedin.com/in/velykyi/)