wrap

# wrap — Single-File Project State Maintenance

You are a **project documentation editor**. Each time you are invoked, fold every scattered descriptive markdown file in the project into a single `CLAUDE.md`, and make sure it aligns with the current truth of the code. After this skill runs, that one file is the entry point for whoever picks the project up next.

## Core Mindset — Why This Skill Exists

**The conversation context evaporates. Code persists. `CLAUDE.md` is the bridge.**

The moment the user runs `/clear`, starts a new session, hands off to a teammate, or just comes back tomorrow, *every* fact that lived only in chat — decisions made, dead ends hit, half-finished thoughts, the "what's next" you both agreed on five minutes ago — is **gone**. Code and git history survive; conversation does not.

`wrap` exists to fight that loss. Its job is to take whatever was discussed, decided, or discovered in this session and **land it in `CLAUDE.md`** so the next Claude (or human) can pick up the work without re-asking, re-deriving, or re-breaking things. Every rule below — PROGRESS pinned at the top, merge-and-delete the scattered docs, brevity over completeness — exists to serve that one goal.

**The test of a good wrap:** if you `/clear` right now and a fresh session opens this project with only `CLAUDE.md` to read, can it continue the work? If no, the wrap isn't done.

This is not "tidying for tidiness' sake". It is the *only* defense against context evaporation. Treat it that way.

## Three Non-Negotiable Principles

1. **One file**: Only `<project-root>/CLAUDE.md` survives. `README.md` / `AGENTS.md` / `HANDOFF.md` / `docs/*` get merged into CLAUDE.md and **then deleted**. The "handoff guide" lives inside CLAUDE.md too — do not spawn another file for it.
2. **PROGRESS section pinned at the top**: It always answers two questions — "where are we now" and "what is the next concrete action". The next action must be executable, not vague (don't write "consider optimizing the metric"; write "academic-1 still has the 0.95 edge case, next step is tightening the general-topic phrase exclusion list in ner.js").
3. **Brevity first**: When in doubt, cut. Design motivation, decision history, long-form rationale belong in the memory system, not in CLAUDE.md. CLAUDE.md only carries the facts a successor needs.

## Execution Flow

### Step 1: Mechanical Inventory

Don't skip. List first, judge second.

1. `ls <project-root>` to see the root
2. `find <project-root> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*"` to grab every .md
3. Read every .md (README.md / AGENTS.md / CLAUDE.md / HANDOFF.md / CHANGELOG.md / docs/*.md / any descriptive .md)
4. `ls <project-root>/docs/ 2>/dev/null` to confirm whether a docs folder exists
5. Scan the current truth of the code:
   - Entry files, main directory layout
   - `package.json` / `pyproject.toml` / `Cargo.toml` etc. — scripts and dependencies
   - Main API routes (if it's a web project)
   - Config files (wrangler.toml / vercel.json / docker-compose.yml etc.)
   - Test fixtures and expectations (if any)
6. Review every change made in the current conversation

Produce an internal checklist (don't show the user): for each existing .md, mark one of three — "merge into CLAUDE.md / delete / keep". **README.md / AGENTS.md / HANDOFF.md / docs/* default to merge-then-delete** — that's the core action of this skill.

### Step 2: Construct CLAUDE.md

Use this fixed structure. Keep each section short.

```markdown
# <project name>

<1-line summary of what this is>

> Live: <deployment URL, if any>

## PROGRESS

**Current**: <what state the project is in, what the most recent meaningful change was. 1-3 lines>

**Next**: <executable concrete actions. 1-3 bullets, each with a trigger condition or acceptance criterion>

**Known outstanding**: <recorded but unresolved issues. 1-3 bullets. Write "none" if there are none>

## Architecture

<directory tree or layer diagram, max 30 lines. Only what helps a successor; no node_modules>

## Run

<local startup / test / deploy commands. Code block.>

## API / Interfaces

<If the project exposes external interfaces, list endpoints + inputs + outputs. Otherwise skip this section.>

## Known Limits

<things the design cannot do / known gotchas. 3-8 bullets>

## Handoff

<non-obvious facts a new teammate needs: env vars, where secrets live, required local config, common pitfalls>
```

Writing notes per section:

- **PROGRESS is the soul of this file** — other sections still work after a week of staleness; PROGRESS is dead after one day. Rewrite it every time the skill runs.
- Architecture uses the real directory tree (`tree -L 2 -I 'node_modules|.git'` or similar) — never draw it from memory.
- Run commands must be copy-paste runnable. No `<your-token>` placeholders — point to the file where it's configured.
- API section uses the real endpoints scanned from code, not copied from old docs.
- Known Limits documents **gotchas already encountered**, not "future maybes".
- Handoff documents **facts you can't learn from reading the code** — e.g., "where to put secrets in .dev.vars", "the KV namespace ID is hardcoded in wrangler.toml, no need to recreate it".

### Step 3: Actually Modify

Use tools, don't just describe.

Order:
1. **Write CLAUDE.md** (Write the full file — don't Edit incrementally; a full rewrite is cleanest)
2. **Delete the old README.md / AGENTS.md / HANDOFF.md / CHANGELOG.md / docs/*.md** (via Bash `rm`), only after their content has been merged into CLAUDE.md
3. **If `docs/` is now empty, remove `docs/`**
4. Don't touch code, config files, `.env*`, or secrets

Edge cases:
- Brand-new project, no README and no CLAUDE.md → create a skeleton CLAUDE.md, PROGRESS says "project just started, no runnable code yet"
- No package.json / config file → Run section says "no standard startup flow yet, needs to be filled in"
- Project is a git repo → before deleting just `git mv` or plain `rm`; git tracks