Imported from pokhrelboss/craftcode-cli (AGENTS.md). Install upstream with npx skills add pokhrelboss/craftcode-cli. Copyright stays with the author.

AGENTS.md — CraftCode CLI

CraftCode (craft) is a CLI-first coding-agent orchestrator. Claude/Codex/Gemini/OpenCode/local models are workers. Core decides decomposition, assignment, context, parallelism, verification, retries, review, done-ness. Simplicity (craft → › Build the feature.) is the standard; capability stays underneath.

Architecture rules

• Names: craftcode or craft only. New CLI code (apps/craft, packages/craftcode-*) must never import the legacy runtime (@craftcode/server, @craftcode/contracts, @craftcode/shared, @craftcode/ssh, @craftcode/tailscale) — port, don't depend.
• Packages: apps/craft, packages/craftcode-{core,providers,tools,context,sessions,tui,cli,shared}. craftcode-core NEVER imports craftcode-tui. TUI renders events only.
• Providers: all specifics in packages/craftcode-providers/<name>/ behind CraftProviderAdapter (authenticate/health/listModels/capabilities/createSession/send/stream/cancel/usage/dispose). No provider if-chains in core.
• Orchestration stays pure; complexity at adapter boundary. Inferred types over annotations. No any. No quota-bypass mechanisms.
• Events for everything: craftcode.session.created|goal.created|task.created|task.completed|agent.spawned|agent.completed|model.selected|tool.called|file.modified|command.executed|test.failed|test.passed|review.completed|checkpoint.created.
• Storage: .craft/ (project) + ~/.craft/ (global). Checkpoints are git refs refs/craft/checkpoints/*. Secrets redacted from logs/context/tool output/doctor.

Safety (inherited, still binding)

1. Killing by pattern. Never pkill -f / pgrep | kill. Kill only PIDs you spawned.
2. Live installs. ~/.craft, ~/.t3/userdata may be live. Read/copy OK; never open read-write, never serve against them, never clean them. Test state lives in worktree .craft/ or temp dirs. (VACUUM INTO for consistent SQLite copies.)
3. No baked origins. No hardcoded localhost URLs in bundles.

Commands

• Install: vp i (repo root; pnpm install also works). New craft app: apps/craft (craft --help, craft doctor, craft run "..."). Legacy server runtime: apps/server (craft-server, see its src/bin.ts).
• Focused checks only: pnpm --filter craft... typecheck, ... test. Never repo-wide vp check / -r test unless asked.
• Manual proof after each phase: craft --help, craft doctor, craft run --json "..." on a temp repo.
• Debug: CRAFT_LOG=debug craft ... or craft --debug. Logs to stderr, never stdout in --json mode.

Conventions

• Config precedence: CLI flags > .craft/config.json > ~/.craft/config.json > defaults > env for automation. Schema-validate; human-readable errors.
• Tests: pure unit (scheduler/router/redaction) + mocked-adapter integration (no live models in CI). Wait on receipts/drains, never sleeps.
• Docs: PRD.md (what/why), ARCHITECTURE.md (boundaries), TODO.md (phases). Keep code comments about usage; don't narrate control flow.
• Current progress: Phase 0–13 done. Phase 14 done: self-test 1–20 — E2E auto-loop green (fix-loop + worktree-merge + review), 80 unit/integration tests green, localhost OpenAI-stub proved discovery/send/SSE/abort, interactive gauntlet green, craft auth green on Windows. Live-model spend NOT exercised (no credentials configured; will not spend user quota). Fixed en route: provider-session cwd scoping, verify-fail task status, untracked-file merge/review, circuit breaker, Windows .cmd shim launch + quoting. See TODO.md.
• Never break: craft instant startup, Model: Auto default, context preserved across model switch, /undo restores checkpoint, dangerous ops always gated even in YOLO.