codev - Project Management CLI
Commands
codev init [project-name] Create a new codev project directory
codev adopt Add codev to the current directory
codev bootstrap-docs Draft the governance docs from this codebase
codev update Update protocols, roles, skills from package
codev doctor Check system dependencies
codev init
Creates a new directory with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, .codex/skills/, .codev/config.json, and .gitignore.
codev init my-app # Interactive setup
codev init my-app -y # Non-interactive with defaults
codev adopt
Adds codev to the current directory (existing project). Run from the project root. If CLAUDE.md or AGENTS.md already exists, creates .codev-new versions and spawns Claude to merge.
codev adopt # Interactive
codev adopt -y # Skip conflict prompts
On a project with code, adopt then offers to draft the governance docs (default No); with -y it only prints the command.
codev bootstrap-docs
Drafts codev/resources/{arch,lessons-learned,arch-critical,lessons-critical}.md from the codebase and git history. Rewrites only files that are still untouched starters; curated files are never edited. Always confirms before launching the agent, then reports what changed and runs a three-way review of the drafts. Nothing is committed.
codev bootstrap-docs --dry-run # Eligible files and the launch, nothing run
codev bootstrap-docs # Draft, report, review
codev update
Updates framework files (protocols, roles, skills) from the installed @cluesmith/codev package. Never touches user data (specs, plans, reviews). Creates .codev-new versions for customized files. Missing Claude and Codex skills are added. A skill you never edited is replaced with the package's version; an edited one is kept and gets <file>.codev-new copies to merge.
codev update # Interactive update
codev update --dry-run # Preview changes
codev update --force # Overwrite all framework files
codev update --agent # Agent mode: JSON stdout, no interactive merge
codev doctor
Checks all required dependencies: Node.js (>=18), git (>=2.5), gh (authenticated), and at least one AI CLI (Claude, Gemini, or Codex).
codev doctor
Common mistakes
- There is NO
codev tower command — use afx tower start/stop
codev init creates a new directory — use codev adopt for existing projects- Always run
codev adopt and codev update from the project root
codev update only updates framework files — it never touches specs/plans/reviews
Local build and install (this repository)
Test changes locally before publishing. Run from the repository root:
pnpm build # builds core first, then codev (including dashboard)
pnpm -w run local-install # packs both packages, installs globally, restarts Tower
local-install (scripts/local-install.sh) packs @cluesmith/codev-core and
@cluesmith/codev, installs both in a single npm install -g (separate installs fail —
codev-core is not on the public registry), restores the executable bit on
scripts/forge/**/*.sh that pnpm pack strips, and restarts Tower last. Install runs while
Tower is up; only the final restart causes downtime. Do not stop Tower first, and do not use
npm link / pnpm link — it breaks global installs.
pnpm build also runs copy-skeleton, which copies codev-skeleton/ into
packages/codev/skeleton. Tests read that copy, so after editing anything under
codev-skeleton/ you must rebuild before the suite reflects your change.
Run codev update in this repository only with a package built from it. An older installed
package treats unpublished skill edits as local edits: it writes .codev-new copies holding
the older text (a merge can fold that back in), and --force overwrites the edits outright.
Where to run things
pnpm install — repository root (installs all workspace packages)pnpm build / pnpm test — packages/codev/, or pnpm --filter @cluesmith/codev build- Unit tests
packages/codev/tests/unit/ · E2E packages/codev/tests/e2e/
- Never run npm commands from the repository root unless told to
Measuring code size
tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .