# Mission Kit / Agent Kit - Installation

> **You are the installer for Mission Kit 5.** Marketing name: **Mission Kit** ([missionkit.io](https://missionkit.io)). Technical surfaces: **Agent Kit** CLI, npm package, slash commands, and `.cursor/agent-kit.json`. Set up the kit **in the user's project** without copying the entire Agent Kit monorepo into it.

## Contract (mandatory)

1. **Forbidden:** create or maintain an `agent-kit/` folder with the entire repo (CLI, `packages/`, `node_modules`, etc.) inside the consumer project.
2. **Mandatory:** minimal bootstrap layout - see [docs/bootstrap.md](docs/bootstrap.md).
3. **Result:** `.cursor/` with L0 + `.cursor/agent-kit.json` + `autogit/` at project root.

## Preference: CLI

**Prerequisites:** Node.js 22.12+ for the CLI. Git is recommended for readiness and the staging→prod flow. Fresh Ubuntu 24.04 server with no Node.js at all: [docs/install-ubuntu24-bare-metal.md](docs/install-ubuntu24-bare-metal.md) puts a Node bootstrap in front of this same CLI path.

If Node.js is available, in the **consumer project root**:

```bash
npx @dadado/agent-kit-cli@latest install
```

Use `@latest` so npx does not reuse a stale cached CLI. Pin a version when you need a reproducible install: `npx @dadado/agent-kit-cli@x.y.z install` (replace `x.y.z` with a version from npm).

**Project-root guard:** before any write, `install`, `update`, and `init` refuse `/` and the home directory, a folder with neither `.git` nor `.cursor/agent-kit.json`, and a folder that has `.git` but also contains two or more child repositories (parent-of-repos). Interactive terminals get a `Proceed anyway?` prompt defaulting to **no**; `--yes` / CI refuses outright with exit 1 and no files written. `--force-root` is the explicit bypass and skips every root check - confirm the absolute path first. Details: [docs/getting-started.md](docs/getting-started.md#project-root-guard).

**Starting from an empty folder:** an empty directory hits that guard. Three sanctioned paths, all printed by the refusal: `git init` here and re-run (recommended), re-run with `--force-root`, or answer **yes** to the interactive `Proceed anyway?` prompt. Installing without Git is supported - `/agent-kit-onboard` owns the Git pillar afterwards (`Keep repository without Git` / `Initialize local Git`). The CLI never runs `git init` for you. Details: [docs/getting-started.md](docs/getting-started.md#starting-from-an-empty-folder).

Claude Code plugin (optional, core skills only; it does not replace the install above, which writes the slash commands, `CLAUDE.md` and `.cursor/agent-kit.json`):

```text
/plugin install agent-kit --marketplace agent-kit-startup/agent-kit
```

On Claude Code before 2.1.275: `/plugin marketplace add agent-kit-startup/agent-kit`, then `/plugin install agent-kit@agent-kit`.

Optional L1 packs (separate command):

```bash
npx @dadado/agent-kit-cli@latest install --pack clean-code,context-management
```

After: `npx @dadado/agent-kit-cli status`. `npx` is ephemeral - it leaves no `agent-kit` on `PATH`, so keep prefixing subcommands with `npx @dadado/agent-kit-cli` (or run `npm i -g @dadado/agent-kit-cli` once if you want the bare `agent-kit` bin). Kit L0 does **not** copy Mission Control's `dashboard/` tree into the project. The panel runs from the CLI package, which ships `dashboard/` from 4.8.2 onward, or from an agent-kit checkout (see [Getting started - Mission Control](docs/getting-started.md#mission-control-production-ship-constraints)). If `/dashboard` or the `dashboard` subcommand reports missing `start.mjs`, the installed CLI predates 4.8.2: upgrade it, or set kit-host env/sibling.

Contributors working from a kit monorepo checkout: use the local CLI examples in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) (Working on the kit). Do not paste monorepo `pnpm --filter` commands into a consumer project.

If CLI runs successfully, skip to **Onboarding** below.

## Port B: install via chat (no CLI)

Entry path: either the user drags `install.md` into chat, or they paste the agent brief from [install-prompt.md](install-prompt.md) which points to this contract. Before any file writes, confirm the absolute workspace root path using **Ask questions** tool (fallback to chat if unavailable). Prefer running `npx @dadado/agent-kit-cli@latest install` when Node.js/npx are available; use the file sync below only when CLI is not available.

> **Multi-workspace safety:** the Port B chat install performs the same root-confirm duty as the CLI's `confirmProjectRoot`. The Ask above is the Port B equivalent of that guard: confirm the workspace root before any L0 write. The shared registry cache is locked during CLI installs/updates, and each workspace keeps its own `.cursor/` tree plus its own Mission Control listen port.

### 1. Create minimal structure (L0 + session)

```
.cursor/
├── agent-kit.json
├── hooks.json      # Cursor-native thin adapters -> agent-kit CLI
├── rules/          # rules L0 listadas abaixo
├── commands/       # commands L0
├── hooks/
│   ├── pre-commit/
│   │   └── check-secrets.sh
│   └── agent/
│       ├── resolve-agent-kit.sh
│       ├── session-start.sh
│       ├── pre-compact.sh
│       ├── guard-shell.sh
│       ├── after-edit-schema.sh
│       └── secrets-prompt.sh
├── plans/
├── memory/
├── context/
│   ├── templates/  # optional: context-pack, handoff, task-brief, adr
│   ├── current/
│   └── archive/
└── HANDOFF.md      # if it does not exist yet
autogit/
├── gitupdate.md
└── plan-routine.md
```

**Don't** create complete skill tree n8n/SQL/ClickUp by default - that's L2 (`agent-kit add`) or L1 pack.

### 2. L0 content (source = this repository / registry)

Copy **only** these artifacts (same content from SoT / registry), not the monorepo:

| Destination | Source in kit |
|-------------|---------------|
| `.cursor/rules/cursor-plan-handoff.mdc` | `.cursor/rules/cursor-plan-handoff.mdc` |
| `.cursor/rules/context-guardian.mdc` | idem |
| `.cursor/rules/cursor-skills-git-workflow.mdc` | idem |
| `.cursor/rules/cursor-skills-general.mdc` | idem |
| `.cursor/rules/ux-tone.mdc` | idem |
| `.cursor/rules/agent-output-hygiene.mdc` | idem |
| `.cursor/rules/docs-professional-standard.mdc` | idem |
| `.cursor/rules/memory-loop.mdc` | idem |
| `.cursor/rules/hitl-ask-questions.mdc` | idem |
| `.cursor/skills/core/hitl-gates/SKILL.md` | idem |
| `.cursor/skills/core/hitl-gates/procedures.md` | idem |
| `.cursor/skills/core/hitl-gates/run-plan-tick-contract.md` | idem |
| `.cursor/skills/core/hitl-gates/start-project-intake.md` | idem |
| `.cursor/skills/core/hitl-gates/run-plan-all-queue.md` | idem |
| `.cursor/skills/core/hitl-gates/pending-ticket.md` | idem |
| `.cursor/skills/core/hitl-gates/promote-merge-wait.md` | idem |
| `.cursor/skills/core/qa/SKILL.md` | idem |
| `.cursor/skills/core/dashboard-broadcast/SKILL.md` | idem |
| `.cursor/skills/core/plan-review-triage/procedure.md` | idem |
| `.cursor/skills/core/plan-external-review/procedure.md` | idem |
| `.cursor/skills/core/agent-kit-onboard/procedure.md` | idem |
| `.cursor/skills/core/field-report-resolve/procedure.md` | idem |
| `.cursor/skills/core/backlog-add/procedure.md` | idem |
| `.cursor/rules/git-secrets-safety.mdc` | `registry/rules/git-secrets-safety.mdc` |
| `.cursor/commands/start-project.md` | idem |
| `.cursor/commands/backlog-add.md` | idem |
| `.cursor/commands/backlog-edit.md` | idem |
| `.cursor/commands/backlog-delete.md` | idem |
| `.cursor/commands/backlog-cancel.md` | idem |
| `.cursor/commands/cancel-plan.md` | idem |
| `.cursor/commands/archive-plan.md` | idem |
| `.cursor/commands/agent-kit-onboard.md` | idem |
| `.cursor/commands/continue-plan.md` | idem |
| `.cursor/commands/run-plan.md` | idem |
| `.cursor/commands/hotfix.md` | idem |
| `.cursor/commands/run-plan-all.md` | idem |
| `.cursor/commands/run-plan-loop.md` | idem (deprecated alias) |
| `.cursor/commands/run-plan-orchestrated.md` | idem (deprecated alias) |
| `.cursor/commands/handoff.md` | idem |
| `.cursor/commands/summary.md` | idem |
| `.cursor/commands/dashboard.md` | idem |
| `.cursor/commands/dashboard-broadcast.md` | idem |
| `.cursor/commands/git-staging.md` | idem |
| `.cursor/commands/git-prod.md` | idem |
| `.cursor/commands/plan-external-review.md` | idem |
| `.cursor/commands/plan-review-triage.md` | idem |
| `.cursor/commands/field-report-resolve.md` | idem |
| `.cursor/commands/dogfood.md` | idem |
| `.cursor/commands/review-pack.md` | idem |
| `.cursor/commands/resolve-conflicts.md` | idem |
| `.cursor/commands/cursor-update-awareness.md` | idem |
| `.cursor/commands/qa.md` | idem |
| `.cursor/commands/update.md` | idem |
| `.cursor/context/templates/plan.md` | idem |
| `.cursor/context/templates/context-pack.md` | idem |
| `.cursor/context/templates/task-brief.md` | idem |
| `.cursor/context/templates/handoff.md` | idem |
| `.cursor/context/templates/adr.md` | idem |
| `.cursor/context/templates/plan-monitor.md` | idem |
| `.cursor/context/templates/memory-entry.md` | idem |
| `.cursor/context/templates/plan-external-review-prompt.md` | idem |
| `.cursor/context/config.example.json` | idem |
| `.cursor/scripts/plan-external-review.sh` | idem |
| `.cursor/scripts/field-report-cadence-bump.sh` | idem |
| `.cursor/scripts/run-plan-all-consolidate.sh` | idem |
| `.cursor/hooks.json` | idem |
| `.cursor/hooks/pre-commit/check-secrets.sh` | idem |
| `.cursor/hooks/agent/resolve-agent-kit.sh` | idem |
| `.cursor/hooks/agent/session-start.sh` | idem |
| `.cursor/hooks/agent/pre-compact.sh` | idem |
| `.cursor/hooks/agent/guard-shell.sh` | idem |
| `.cursor/hooks/agent/after-edit-schema.sh` | idem |
| `.cursor/hooks/agent/secrets-prompt.sh` | idem |
| `autogit/gitupdate.md` | `autogit/gitupdate.md` |
| `autogit/plan-routine.md` | `autogit/plan-routine.md` |
| `git-hooks/prepare-commit-msg` | idem |

After copying the agent hook scripts by hand (Port B), make them executable so Cursor can run them:

```bash
chmod +x .cursor/hooks/agent/*.sh .cursor/hooks/pre-commit/check-secrets.sh
```

Managed `agent-kit install` / `update` already preserves the executable bit via `copyFile`. `git-hooks/prepare-commit-msg` needs no chmod: the signature gate runs it as `sh git-hooks/prepare-commit-msg --check -`.

If the agent has the Agent Kit monorepo open as workspace, use those paths. If only in consumer project, prefer **Port A** (`npx @dadado/agent-kit-cli@latest install`) so files come from the integrity-checked npm package. Port B raw fetches have **no package checksum**: treat them as a fallback only.

Default public base URL: `https://raw.githubusercontent.com/agent-kit-startup/agent-kit/main/` + each file path. Use **Ask questions** for any registry source confirmation:
Options: `Fetch from public registry` / `Use different registry URL` / `Skip registry for now`

When the operator picks **Use different registry URL**, stop and require an explicit trust decision before fetching. Do not silently substitute an untrusted host. Prefer pinning a known public commit SHA (or tag) in the URL path over floating `main` when the operator needs reproducibility. After copy, run `npx @dadado/agent-kit-cli doctor` / `npx @dadado/agent-kit-cli status` when the CLI is available so the install can be validated.

**Fallback:** if Ask questions tool unavailable, ask the same options in chat as numbered list.

### 3. Manifest `.cursor/agent-kit.json`

Create if it doesn't exist (adjust `version` / `registry` to current SoT):

```json
{
  "schemaVersion": 1,
  "version": "5.3.0",
  "profile": "default",
  "packs": [],
  "skills": [],
  "protected": [
    ".cursor/HANDOFF.md",
    ".cursor/plans/**",
    ".cursor/memory/**",
    ".cursor/context/config.json",
    ".cursor/context/current/**",
    ".cursor/context/backups/**"
  ],
  "registry": {
    "url": "https://github.com/agent-kit-startup/agent-kit",
    "ref": "main"
  }
}
```

Schema: [docs/agent-kit-manifest.md](docs/agent-kit-manifest.md).

### 4. HANDOFF (first installation)

If `.cursor/HANDOFF.md` does **not** exist, create from `HANDOFF.md.example` or `.cursor/context/templates/handoff.md`.

### 5. Git hooks (optional)

Use **Ask questions** tool to confirm git hooks installation:
Options: `Install git hooks` / `Skip hooks` / `Show hook paths only`

**Fallback:** if Ask questions tool unavailable, ask the same options in chat as numbered list.

```bash
# secrets (if project already uses custom pre-commit, integrate check-secrets.sh)
cp .cursor/hooks/pre-commit/check-secrets.sh .git/hooks/  # only if repo flow requires

# prepare-commit-msg: copy the *file* from registry, never the agent-kit/ folder
# source in kit: git-hooks/prepare-commit-msg → .git/hooks/prepare-commit-msg
```

### 6. Repository readiness onboarding

After L0 files are written, run `npx @dadado/agent-kit-cli doctor --json` (bare `agent-kit doctor --json` only after a global `npm i -g @dadado/agent-kit-cli`) to refresh `.cursor/context/readiness.json`, then run or offer `/agent-kit-onboard`. The command is the sole coordinator for progressive repository preparation. Follow [`.cursor/commands/agent-kit-onboard.md`](.cursor/commands/agent-kit-onboard.md).

The first useful message reports current readiness progress, detected facts, safe fixes, and exactly one next action. It does not ask about skins, external review, or a first deliverable before essential readiness passes.

Use **Ask questions** one decision at a time when scanner evidence cannot resolve intent. Confirm branch, remote, hooks, CI, deployment, protection, and other external or destructive mutations before acting. A skipped or cancelled answer stops the proposed action.

**Fallback:** if Ask questions is unavailable, present the same concrete options as a numbered list and accept a number, label, or custom answer.

**Note:** CLI setup uses terminal prompts where needed. Its Next block points at `/agent-kit-onboard` when readiness has pending actions.

### 7. Migrate old copy

If project still has nested `agent-kit/`: preserve L3, install via CLI/manifest, then use **Ask questions** tool before removal:
Options: `Migrate and remove nested folder` / `Keep nested folder` / `Cancel migration`

**Fallback:** if Ask questions tool unavailable, ask the same options in chat as numbered list.

Details: [docs/bootstrap.md](docs/bootstrap.md).

---

## What NOT to install by default

- Stack rules/skills (n8n, SQL, Node, PM tools) - `agent-kit add` or `--pack`
- Kit subtree `packages/`, `node_modules`, `pnpm-lock`
- Legacy CLI `cursor-handoff` as requirement - prefer `@dadado/agent-kit-cli`

## References

- [docs/bootstrap.md](docs/bootstrap.md) - bootstrap contract
- [docs/layers-spec.md](docs/layers-spec.md) - L0–L3
- [docs/getting-started.md](docs/getting-started.md) - lifecycle commands