Quick start

This guide takes a new user from installation to a reviewed commit: machine setup once, then project setup once.

Prerequisites

• macOS or Linux with git and zsh or bash.
• OpenSSL 3 for the first install’s signature check (brew install openssl@3 on macOS; the system LibreSSL cannot verify ed25519).
• A supported coding agent: Claude Code, or Codex and OpenCode through the runtime adapters.
• Access to the signed endpoint or a local checkout.

1. Set up the machine

Install from the signed endpoint; no repository access or SSH key is needed:

bash

curl -fsSL https://devkit.one-dot.io/install.sh | sh

Or bootstrap from a checkout with cargo run -p devkit -- install. Either way the installer installs jq, wires the SessionStart hook and runs the first sync; if it adds a marked export PATH=… line to your shell startup file, open a new shell.

Verify the installation:

bash

devkit status   # version, source/channel, sync age
devkit doctor   # symlinks, personal configuration, tools

The first sync installs every required tool. That includes the delegate CLIs, the /share renderers, the pen design toolchain and the vulnerability scanner. A few remain optional (prime-agent, kimi, opencode): on a terminal, devkit sync asks for each one and remembers a no, devkit tools --install <name> adds one later, the flag below adds all. What each tool unlocks and what it still needs from you: Tools that need a step from you.

bash

devkit tools --optional   # or: devkit sync --optional

Each optional tool is version-pinned like a required one. devkit sync now brings drifted tools back to their pin by itself, at most once every 24 hours; devkit tools --outdated lists them and devkit tools --upgrade forces the pass, and DEVKIT_TOOLS_AUTO_UPGRADE=0 turns the automatic one off.

From now on every session start applies a fetched update and fetches the next one in the background. devkit off removes the runtime links and hooks but keeps version and config; devkit on restores them.

2. Set up the project

Shortest path: start claude in the project and type /index. It shows what devkit init would change, applies it after one yes and then builds the context; run it again after every devkit update.

Run devkit init in the project folder. It guides you: git init if the folder has no git yet, the plan and one question before anything changes, the stack skills from the ONEDOT boilerplate, and a commit of the new files. Then start claude and run /index. It builds .agents/context/ (STACK, CONVENTIONS, SUMMARY, STRUCTURE); commit it for the team.

3. Make a green commit

Describe a small change. The agent works inline, checks for existing code to reuse, then runs these gates in order:

Skill	Gate
/test	Targeted tests; /test --full only on request or when the risk needs it.
/review	Independent read-only review of the current diff.
/commit	Stages only this session's files, scans them with gitleaks and refuses agent-state paths.

This is daily work. When rollback is costly or no deterministic check exists yet, start with /spec instead: feature.

If setup fails

Run devkit doctor first, then see Troubleshooting.

Next steps

• Workflows
• How it works
• Skill overview