# Checkpoint

> Shadow git checkpoint system for pipeline rollback. Creates working directory snapshots without modifying the project's git history. Invoked by build, quality-gate, and debugging orchestrators at pipeline boundaries.

- **Type:** Skill
- **Install:** `agentstack add skill-raddue-crucible-checkpoint`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raddue](https://agentstack.voostack.com/s/raddue)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raddue](https://github.com/raddue)
- **Source:** https://github.com/raddue/crucible/tree/main/skills/checkpoint

## Install

```sh
agentstack add skill-raddue-crucible-checkpoint
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Checkpoint

Shadow git checkpoint system that snapshots and restores working directory state using an isolated git repository. The project's `.git` history is never touched.

**Skill type:** Rigid — follow exactly, no shortcuts.

**Execution model:** No modes, no subagent dispatch. The consuming orchestrator (build, quality-gate, debugging) follows these instructions directly when taking or restoring checkpoints.

## Shadow Repository Setup

Initialize once per session, on first checkpoint request:

1. **Compute directory hash:** SHA-256 of the absolute working directory path, truncated to 16 characters.
   ```
   echo -n "/absolute/path/to/project" | sha256sum | cut -c1-16
   ```

2. **Shadow repo path:** `~/.claude/projects//checkpoints//`

3. **Initialize:** If the shadow repo does not exist:
   ```bash
   GIT_DIR= GIT_WORK_TREE= git init
   ```

4. **Write `.gitignore`** in the shadow repo (not the project):
   ```
   node_modules/
   .env
   .env.*
   __pycache__/
   .git/
   venv/
   .venv/
   dist/
   build/
   .next/
   *.pyc
   .DS_Store
   ```

5. **Health check:** Before every operation, verify:
   ```bash
   GIT_DIR= git rev-parse --git-dir
   ```
   If this fails, reinitialize the shadow repo and warn: "Shadow repo was corrupt — reinitialized. Prior checkpoints are lost."

**Tool constraint:** All shadow repo operations MUST use the Bash tool with explicit `GIT_DIR` and `GIT_WORK_TREE` environment variables. Never use Write/Read/Glob for shadow repo git operations. Never run git commands without these env vars — bare `git` commands would affect the project repo.

## Pre-Check: Directory Size

Before the first checkpoint in a session, count files in the working directory (excluding ignored paths):

```bash
find  -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/__pycache__/*' -not -path '*/venv/*' -not -path '*/.venv/*' -type f | wc -l
```

If count exceeds 50,000: skip all checkpoints for this directory with warning "Directory has >50,000 files — checkpoints disabled for performance." Cache this decision for the session (do not re-count).

## Create Checkpoint

1. **Deduplication:** Read the latest commit timestamp from the shadow repo:
   ```bash
   GIT_DIR= git log -1 --format=%ct 2>/dev/null
   ```
   If the current time minus the commit timestamp is less than 1 second, skip this checkpoint (deduplication).

2. **Stage all files:**
   ```bash
   GIT_DIR= GIT_WORK_TREE= git add -A
   ```

3. **Commit:**
   ```bash
   GIT_DIR= GIT_WORK_TREE= git commit -m " |  | " --allow-empty-message
   ```
   The `` is a structured string (e.g., `pre-design-gate`, `pre-wave-3`, `pre-qg-fix-round-2`). The `` is the consuming skill name (build, quality-gate, debugging).

4. **Record the commit hash** as the checkpoint ID.

5. **Update manifest:** Append an entry to `checkpoint-manifest.md` in the shadow repo directory (outside the git tree):
   ```
   |  |  |  |  |
   ```

6. **Eviction:** After commit, count entries in `checkpoint-manifest.md`. If count exceeds 50 (configurable — orchestrators may override), remove the oldest entries from the manifest. Git objects for evicted commits are cleaned up by the Prune step.

## List Checkpoints

Read `checkpoint-manifest.md` from the shadow repo directory. Display in most-recent-first order:

```
| Hash     | Timestamp           | Reason              | Source       |
|----------|---------------------|----------------------|--------------|
| a1b2c3d4 | 2026-03-24 12:45:30 | pre-wave-3           | build        |
| e5f6g7h8 | 2026-03-24 12:30:15 | pre-plan-gate        | build        |
```

## Restore (Full Directory)

1. **Create a pre-restore safety checkpoint** with reason `pre-restore-safety` and source `checkpoint`. This enables "undo the undo."

2. **Restore:**
   ```bash
   GIT_DIR= GIT_WORK_TREE= git checkout  -- .
   ```

3. **Verify:** Run the project's test suite or relevant subset to confirm the restored state is healthy.

4. **Report:** "Restored to checkpoint `` (``). Safety checkpoint created at `` — use this to undo the restore."

## Restore (Single File)

1. **Create a pre-restore safety checkpoint** with reason `pre-restore-safety-file` and source `checkpoint`.

2. **Restore:**
   ```bash
   GIT_DIR= GIT_WORK_TREE= git checkout  -- 
   ```

3. **Report:** "Restored `` from checkpoint `` (``)."

## Prune

Run at session start (before first checkpoint) to reclaim space:

1. ```bash
   GIT_DIR= GIT_WORK_TREE= git gc --prune=now
   ```

2. Read `checkpoint-manifest.md` and verify each entry's hash exists:
   ```bash
   GIT_DIR= git cat-file -t 
   ```
   Remove entries with invalid hashes (orphaned by prior gc).

## Compaction Recovery

The checkpoint manifest and shadow repo persist across compaction because they live in `~/.claude/projects/` (not in `/tmp/` or in-memory).

After compaction:
1. Recompute the directory hash from the current working directory path
2. Check if `~/.claude/projects//checkpoints//` exists
3. If yes: read `checkpoint-manifest.md` to recover available checkpoints
4. If no: checkpoints are unavailable for this session (no error — the pipeline continues without checkpoint protection)

No active marker file is needed — the shadow repo's existence IS the marker. The directory hash computation is deterministic from the working directory path.

## Red Flags

- **NEVER** modify the project's `.git` directory
- **NEVER** run git commands without `GIT_DIR` and `GIT_WORK_TREE` env vars
- **NEVER** take a checkpoint mid-wave — wait for all parallel agents to complete before snapshotting
- **NEVER** auto-restore without user confirmation — always present restore as an option, not an action
- **NEVER** delete the shadow repo without explicit user request

## Integration

Consuming skills:
- **crucible:build** — Pipeline boundary checkpoints (pre-design-gate, pre-plan-gate, pre-wave-N, pre-cleanup-task-N, pre-temper, pre-inquisitor, pre-impl-gate)
- **crucible:quality-gate** — Pre-fix-round checkpoints for code artifacts (pre-qg-fix-round-N)
- **crucible:debugging** — Pre-implementation, pre-sibling, and pre-quality-gate checkpoints (pre-debug-fix-cycle-N, pre-where-else, pre-debug-gate)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raddue](https://github.com/raddue)
- **Source:** [raddue/crucible](https://github.com/raddue/crucible)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-raddue-crucible-checkpoint
- Seller: https://agentstack.voostack.com/s/raddue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.