Setup

---
name: setup
description: Scaffold the handoff project-memory system into THIS repository (new or existing) — copies the template tree into .handoff/, then runs a guided discovery pass that drafts a real STATUS, MAP, TECH_STACK, and PRODUCT from the actual codebase and confirms with the user before saving. Use when the user says "set up handoff", "initialize handoff", "add project memory", or when a repo has no .handoff/ and the user wants one. Run once per repo.
---

# Set up handoff in this repo

Scaffold the durable project-memory system, then populate it from the real
codebase so it ships useful — not blank. **Discovery drafts; the user confirms
before anything is saved.** Never invent project facts (RULES rule 5).

## 0. Locate templates & detect existing install
- The template tree is bundled with this plugin at `../../templates/` relative
  to this skill file (i.e. `<plugin-root>/templates/`). Resolve that absolute path.
- Check whether `.handoff/` already exists in the project root:
  - **Exists** → do NOT overwrite. Tell the user it's already set up; offer to
    *refresh* specific files (e.g. re-run discovery for STATUS/MAP/TECH_STACK)
    or seed a CONTEXT.md. Stop here unless they choose a refresh.
  - **Absent** → continue.

## 1. Copy the template tree
Copy the bundled `templates/` into the project as `.handoff/`, preserving
structure (BOOT, RULES, STATUS, MAP, CHANGELOG, context/, docs/ with
SKILL-WORKFLOW.md, tasks/ with inbox/now/done). Keep the `.gitkeep` files.
Do not edit RULES' universal section.
Write the current plugin version into `.handoff/VERSION` (single line) — the
SessionStart hook uses it for template-drift detection.

## 2. Guided discovery (read the repo — do not guess)
Read what actually exists, quietly:
- Build/manifest files: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
  `composer.json`, `Gemfile`, Makefile, CI config, framework config files.
- Top-level directory layout and the largest/most-central source folders.
- `git log --oneline -20` and current branch for recent direction.
- Any existing README for product intent.
Derive: project name, type, primary stack, common commands (build/dev/test/lint),
deploy target, and the **verify commands** for RULES rule 10.

## 3. Draft, then CONFIRM before saving
Present concise drafts for the user to correct:
- **STATUS.md** — Current State (where the repo stands now), Active Work (none
  unless evident), Blockers (none unless evident). Keep ≤ 25 lines.
- **context/TECH_STACK.md** — stack, commands, env vars, deploy, verify commands.
- **MAP.md** — entry points, key directories, where to make common changes.
- **context/PRODUCT.md** — only if a README/product intent is discoverable;
  otherwise leave the template prompts and say so.
- Replace the `<PROJECT_NAME>/<PROJECT_TYPE>/<PRIMARY_STACK>` placeholders in BOOT.md.
**Wait for the user's confirmation/edits. Only then write the files.** For
anything you cannot determine from the repo, leave the template prompt in place
rather than inventing — and tell the user what you left blank.

## 4. Seed folder-level CONTEXT.md (offer, then confirm)
Identify the 1–3 folders with the most local architecture or conventions a
future session should read before editing (e.g. a design-system dir, a core
domain module). Propose a short CONTEXT.md for each (structure, conventions,
gotchas — not a file listing). Save only the ones the user approves. These are
auto-injected by the PreToolUse hook on first edit in that folder.

## 5. Thin-fallback CLAUDE.md
The plugin's hooks load full state when installed, but a clone opened WITHOUT
the plugin needs a minimal fallback. In the project root:
- If `CLAUDE.md` exists, append (don't duplicate) a short block. If it doesn't,
  create one. Never create `AGENTS.md` if `CLAUDE.md` exists, or vice versa —
  edit whichever is present.
- The block:

```markdown
## Project memory (handoff)
This repo uses handoff. With the plugin installed, the SessionStart hook
auto-loads `.handoff/STATUS.md` + `RULES.md`. If hooks are off, read those
two first. Hard rules (always apply):
- Preserve user work; never delete/overwrite/revert changes unless asked.
- Never `git add -A` / `git add .` for a scoped commit — stage only what you changed.
- Verify with the commands in `.handoff/context/TECH_STACK.md` before claiming done.
- Update `.handoff/STATUS.md` + `CHANGELOG.md` whenever code or config changes —
  before committing, in the same commit as the change.
```

## 6. Finish
Tell the user: setup is complete; the SessionStart hook will load STATUS+RULES
from the next session; the PreToolUse hook injects any folder's CONTEXT.md on
edit; the Stop hook nudges state updates. They can edit `.handoff/*` directly
anytime. Re-run this skill only to refresh discovery or start over.
Also tell them the repo now has a tiered 6-phase workflow — point them at
`.handoff/docs/SKILL-WORKFLOW.md` and the `workflow` skill.

Add a dated line to `.handoff/CHANGELOG.md`: "Project initialized with handoff."