Skip to content

SETUP.md

Latest commit

 

History

History
196 lines (156 loc) · 12.7 KB

SETUP.md

File metadata and controls

196 lines (156 loc) · 12.7 KB
Raw

Setup scope and project changes

ak setup always performs machine setup. It also performs project setup when the current directory contains a .git entry. ak setup --project forces that same project phase in the current directory even when .git is absent.

The flag does not select a gentler or different initializer. If project setup would already run, ak setup and ak setup --project have the same effect.

How the ak binary was obtained does not change this behavior. A local dependency or one-shot npm exec invocation still performs the same machine, current-user, and project work. See Installation and scope for the package-install methods and their separate footprints.

Warning

Project setup runs ruflo init --full --force. In an existing project, that can replace agent configuration and generated Ruflo/AQE assets. Commit or back up the project first, run from the intended project root, and preview the high-level plan with ak setup --dry-run.

Which scopes run?

Where the command is run ak setup ak setup --project
Git repository root (.git exists in the current directory) Machine + project Machine + project; the flag is redundant
New or existing non-Git directory Machine only Machine + project in that directory
Subdirectory of a Git repository without its own .git entry Machine only Machine + project in the subdirectory, not the repository root
Home directory Machine only Machine + project in the home directory; avoid this unless it is intentional

--minimal overrides both automatic detection and --project: it performs machine setup only.

Project detection does not walk upward to find a repository. For predictable results, change to the project root before running either form.

What machine setup does

The machine phase is the same with or without --project. It:

  • creates or updates the agentic-kit machine configuration;
  • ensures enabled global tools and hosts are installed, while generally retaining already-installed tool versions;
  • repairs required native packages and deploys the token-audit skill;
  • reconciles agentic-kit's managed guidance blocks in the user-level Claude and Codex files that exist on the machine;
  • offers user-scope Ruflo MCP registration; and
  • applies saved host, provider, and routing choices.

ak setup is the first-time installer, not the routine upgrade command. Once the kit is installed, use ak sync to upgrade and reconverge it.

What project setup changes

Project setup first delegates to the installed Ruflo version, then applies agentic-kit's normalization and verification steps. Ruflo and agentic-qe own some generated assets, so exact generated filenames can change between their versions. The table below describes the current contract.

Path or state Existing project New/empty project
Application source, package.json, and arbitrary project files Not intentionally changed by agentic-kit. No application is scaffolded.
.claude/settings.json Regenerated by ruflo init --full --force; agentic-kit then disables claudeFlow.daemon.autoStart if it is true, and AQE may merge its hooks/settings. Custom content can be at risk. Created with Ruflo settings, then normalized and optionally extended by AQE.
.claude/settings.local.json Valid existing JSON is preserved and merged with an absolute env.CLAUDE_FLOW_DB_PATH. A one-time .bak is created before agentic-kit writes it. Invalid JSON is treated as empty. Created with the absolute memory path.
.claude/skills/, .claude/commands/, .claude/agents/, .claude/helpers/ Ruflo's matching generated assets are overwritten; AQE assets are then added or refreshed. Unrelated extra files are generally not swept. Generated and populated.
CLAUDE.md Ruflo backs up the prior file as a .pre-ruflo variant, then agentic-kit replaces the active file with its lean project stub and adds the AQE sentinel when AQE is enabled. Existing prose is not merged into the active file. Created as the lean project stub, with the AQE sentinel when enabled.
.mcp.json Ruflo force-init regenerates this file before agentic-kit removes project-local ruflo, claude-flow, ruv-swarm, and flow-nexus entries. The file is deleted if those are the only remaining content. AQE may subsequently add its own server. Because regeneration happens first, pre-existing custom MCP entries can be lost; preserve them separately and restore them after setup. Temporarily generated and sanitized; it may be absent afterward unless AQE or another retained entry needs it.
Claude's project-local ruflo MCP registration Removed with claude mcp remove ruflo -s local; agentic-kit offers user-scope registration instead. Same behavior.
.claude-flow/ generated config and runtime support files Ruflo-generated files are refreshed. Agentic-kit initializes memory and swarm state, starts the local-only daemon, and injects/heals the status-line footer. Created and initialized.
.swarm/memory.db and adjacent memory stores Initialized or migrated in place. Agentic-kit writes a disposable verification record, confirms the on-disk row, and removes only that probe. Created/initialized and verified.
.agentic-qe/ and AQE integration assets With AQE enabled, aqe init --auto migrates or refreshes its database, configuration, workers, skills, agents, hooks, and platform integrations. Generated assets can change with the installed AQE version. Created and initialized when AQE is enabled.
Oversized .agentic-qe/*.rvf stores An RVF file over 2 GiB and its .lock, .idmap.json, and .manifest.json sidecars are removed before AQE initialization. Normal-sized stores are left to AQE. Normally not applicable.
Root .gitignore Ruflo appends missing runtime/local-secret exclusions while preserving existing entries. Created or extended as needed.
.agents/skills/ruflo/ Added or refreshed; a detected oversized/broken generated Ruflo skill installation may be replaced. Created when supported by the installed Ruflo version.
Project AGENTS.md Arbitrary project content is preserved. Agentic-kit only reconciles its own sentinel-delimited managed blocks, including removing stale blocks that no longer apply. Created only when a selected integration needs managed guidance.

Project setup also reapplies enabled host/provider wiring and seeds the default per-activity routing policy in dual-host mode. With Codex enabled, it repairs both directions of the Claude/Codex–Ruflo bridge.

Setup trust manifest

Before making any machine, user, or project change, setup derives one manifest from the enabled host adapters and prints every applicable approval, registration, and host-integration change. Interactive setup asks for one confirmation after this preflight. --yes suppresses the question but still prints the manifest, so automation retains an auditable record; --dry-run is the non-mutating way to inspect the effective manifest for the current flags. A non-interactive setup with applicable trust changes must pass --yes; otherwise it prints the manifest and exits before mutation.

The host registry requires every present or future host adapter to declare an approval posture and its setup-time trust changes. A future host cannot pass registry validation without that declaration, and setup consumes it without a host-specific disclosure branch. Enabling a host later with ak host pick uses the same registry-derived preflight for changes that command applies; already-enabled hosts are not prompted again.

Claude Code project auto-approvals

Project setup discloses the exact Claude Code rules that Ruflo and agentic-qe may ensure or retain in .claude/settings.json:

Owner Auto-approved rule Effect
Ruflo Bash(npx @claude-flow*) Run scoped @claude-flow npx commands
Ruflo Bash(npx claude-flow*) Run scoped claude-flow npx commands
Ruflo Bash(node .claude/*) Run repository-local .claude Node helpers
Ruflo mcp__claude-flow__* Call the project Ruflo MCP tool family
agentic-qe Bash(npx agentic-qe:*) Run scoped agentic-qe npx commands
agentic-qe Bash(npx @anthropics/agentic-qe:*) Run scoped @anthropics/agentic-qe npx commands
agentic-qe mcp__agentic-qe__* Call the project agentic-qe MCP tool family

The last three rules are omitted with --no-aqe. Rules that existed before setup remain user-owned. After each upstream initializer, agentic-kit compares the resulting allow-list with the manifest: any newly added, undisclosed rule is removed and setup fails instead of silently expanding project trust.

Codex and OpenCode

Codex does not need an agentic-kit auto-approve list. The manifest instead names the project Claude-to-Codex MCP bridge, the user-scope Codex-to-Ruflo MCP registration, and the AQE Codex integration that project setup will create. Agentic-kit does not alter Codex's sandbox or approval policy.

Codex also retains exclusive ownership of third-party plugins. Agentic-kit never installs or enables a Codex plugin (including security-guidance), and setup/sync never rewrites Codex's plugin tables or cache. ak status only reads enabled bundles to report known hook and skill portability problems.

All enabled hosts converge on the same project-scoped Ruflo memory contract. Claude receives the absolute CLAUDE_FLOW_DB_PATH in project settings. Codex's user-scoped Ruflo MCP registration launches ak x ruflo-mcp, which derives the pin from the workspace at process start. OpenCode's managed MCP gateway and lifecycle bridge receive its project directory and set the same absolute pin. Ruflo's native bridge may write .swarm/agentdb-memory.db beside the pinned .swarm/memory.db; that sibling is the active native store, not configuration drift. ak x verify memory proves the actual writer with a disposable round trip.

OpenCode's user-scope manifest names all four wildcard tool approvals, the Ruflo and optional Brain MCP registrations, the lifecycle plugin, and the managed agent/skill/guidance projection. These are workspace-trust grants, not an agentic-kit sandbox.

The separately offered Claude user-scope Ruflo MCP registration retains its own dedicated prompt because it is optional rather than a deterministic setup change. --yes accepts that prompt as documented.

Existing projects

For an existing project:

  1. Commit or back up the working tree, especially CLAUDE.md, .mcp.json, .claude/, .claude-flow/, .agentic-qe/, and .agents/.
  2. Change to the repository root. Do not rely on --project from a nested directory.
  3. Run ak setup --dry-run to confirm that both machine and project phases are intended. The preview is high-level; it is not a per-file diff.
  4. Run ak setup at a Git root, or ak setup --project only when the intended root has no .git entry.
  5. Review the resulting diff, restoring custom MCP entries or generated-file customizations where necessary, then run ak status.

If agentic-kit is already working in the project, prefer ak sync. Re-running setup is normally appropriate only when deliberately rebuilding the initial integration state.

New projects

For an empty or newly created directory:

  • If it has already been initialized with Git, the two commands are equivalent.
  • If it has no .git entry, plain ak setup performs machine setup only; ak setup --project also creates the Ruflo/AQE integration in that directory.
  • Neither form runs git init, creates application source, selects a framework, or installs project application dependencies.

Flags that alter project setup

  • --minimal skips project setup entirely, even with --project.
  • --no-aqe skips AQE installation/configuration for this setup and records AQE as disabled in agentic-kit's machine configuration.
  • --codex, --opencode, and --primary-host enable and wire the selected hosts before the project phase.
  • --yes accepts prompts; it does not hide the setup trust manifest or change the project mutation contract.
  • --dry-run prints a high-level plan and changes nothing.

The clean-machine regression runs from the packed release artifact on GitHub's macos-latest runner with disposable HOME, XDG directories, npm global prefix/cache, Brain KB, and project directory. Local regression coverage uses the same isolation model in a child process. Neither test runs setup against the developer's existing home or global npm prefix.

See Upgrading for the setup versus sync lifecycle and Troubleshooting for setup and health-check failures. See Host support before enabling Claude, Codex, or OpenCode.