---
name: ccd-attach
description: This skill should be used when bootstrapping CCD in a new project workspace, when ccd start reports the project is not linked, or when connecting an existing checkout to a CCD profile for the first time
argument-hint: [optional display name]
---

# CCD Attach

Attach the current project workspace into the landed CCD state model. Prefer the CLI and do not recreate the old project-root compatibility workflow.

## Gotchas

- **Shared safety contract:** inspect existing project truth first, let the CLI own CCD-local writes, and require explicit developer confirmation before overwriting project-root docs.
- **CLI-owned state files:** never manually write `.ccd.toml`, registry compatibility files, or workspace-state files — let the CLI handle them.
- **No legacy patterns:** do not invent project-root compatibility files such as `next-session-prompt.md` or config-shaped `.ccd.toml` — these are obsolete patterns.
- **Existing project truth:** do not overwrite existing `AGENTS.md` or other project-truth docs without explicit developer confirmation.
- **Stale worktree binaries:** never fall back to `./target/debug/ccd` — worktree-local binaries go stale after merges.

## Resolve CLI

1. Resolve the CLI command once:
   - if `CCD_BIN` is set and points to an executable file, use that exact path
   - otherwise, if `which ccd` succeeds, use `ccd`
   - otherwise, if `$HOME/.ccd/bin/ccd` exists and is executable, use `$HOME/.ccd/bin/ccd`
   - otherwise, if `$HOME/.cargo/bin/ccd` exists and is executable, use `$HOME/.cargo/bin/ccd`
   - otherwise, treat the CLI as unavailable
   - **do not** fall back to `./target/debug/ccd` — worktree-local binaries go stale after merges and produce version mismatches
2. If the CLI is unavailable, stop and say `ccd attach` is unavailable in the current shell. Suggest installing or building CCD first. If the developer still wants help drafting project-truth docs such as `AGENTS.md`, point them to `bootstrap-prompt.md` as a separate follow-up.

## Bootstrap state

3. Run the resolved command with `attach --path .`
   - if `$ARGUMENTS` is present, pass it as `--display-name`
4. If the command fails, report the failure and stop.
5. Summarize the bootstrap result:
   - active profile
   - project ID (locality ID)
   - marker path
   - profile root
   - project overlay path
   - workspace-state path
   - next-step suggestions returned by the CLI

## Inspect project truth

6. Read `AGENTS.md` if it exists and note whether project policy already exists.
7. Read `README.md` (or another obvious project entrypoint) if it exists so you can name the project-truth sources already present in the project workspace.
8. Explain the split clearly:
   - project-root files such as `AGENTS.md`, `README.md`, specs, and tests are project truth
   - profile kernel lives under `~/.ccd/profiles/{profile}/`
   - project overlay lives under `~/.ccd/profiles/{profile}/repos/{locality_id}/`
   - handoff and session telemetry live under the active workspace state root (for Git: `$(git rev-parse --git-path ccd)/profiles/{profile}/`)

## Next steps

9. Give concise actor next steps:
   - start sessions with the shipped runtime lifecycle path when the current runtime supports it; otherwise use `/ccd-start` or `ccd start --activate --path .`. When the runtime has an explicit repo-local integration path, apply it deliberately with `ccd init --path .` plus `ccd host apply --host <host> --path .`
   - end sessions with `/ccd-radar` or `ccd handover`
   - use `ccd link --project-id <project_id>` to attach another workspace to the same project overlay
   - if `AGENTS.md` is missing, suggest `ccd scaffold --path .` as a separate follow-up
   - if those files already exist but are stale, offer to update them in a separate task

## Guard rails

- Do not manually write `.ccd.toml`, registry compatibility files, or workspace-state files when the CLI can do it.
- Do not invent project-root compatibility files such as `next-session-prompt.md` or config-shaped `.ccd.toml`.
- Do not overwrite existing project-truth docs without explicit confirmation.
