great-cto

CLI for the 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. The installation walkthrough below describes the legacy 3.70.1 flow; it is not an activation route for this implementation.

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)

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 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.

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

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/ — ~1.2k LOC TypeScript

License

MIT — same as the plugin.

Links

• Plugin: github.com/avelikiy/great_cto
• Issues: github.com/avelikiy/great_cto/issues
• Author: velykyi