Stats
Actions
Tags
From escapement
Archive completed scratchpads and session logs to project history. Invoke when user says "archive this work", "clean up scratchpad", "archive scratchpad", or after PR is merged.
How this skill is triggered — by the user, by Claude, or both
Slash command
/escapement:archive-workThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Archive completed scratchpads and development artifacts to maintain clean project roots while preserving work history for future reference. This skill organizes completed work into a structured archive.
Archive completed scratchpads and development artifacts to maintain clean project roots while preserving work history for future reference. This skill organizes completed work into a structured archive.
Context-path aware: If the project's CLAUDE.md defines a context-path, archives are written to the external context directory instead of docs/dev/cc-archive/. This keeps the code repo clean of development artifacts.
This skill activates when the user says things like:
Read project's CLAUDE.md and check for Escapement Settings:
## Escapement Settings
- **context-path**: ../myproject-ctx
If context-path is set:
{context-path}/{branch}/archive/ARCHIVE_MODE=contextIf context-path is NOT set:
docs/dev/cc-archive/ (existing behavior)ARCHIVE_MODE=in-repoExecute these searches in parallel for faster detection:
Find Scratchpads:
Glob: SCRATCHPAD_*.md in project rootFind Session Logs:
Glob: SESSION_LOG_*.jsonl in project root (current format — raw JSONL transcripts)Glob: SESSION_LOG_*.md in project root (legacy format — pre-converted markdown)Find Other Related Files:
Check Git Status:
After parallel detection, verify completion:
Context Mode (context-path set):
{context-path}/
└── {branch-name}/
└── archive/
├── SCRATCHPAD_{issue_number}.md
├── SESSION_LOG_1.md # Converted from .jsonl during archive
├── SESSION_LOG_2.md # (or legacy .md moved directly)
└── README.md
No timestamp prefix on the branch directory — the branch name is the identifier. If multiple archives exist for the same branch (rare), add a timestamp suffix to the archive directory.
In-Repo Mode (no context-path):
docs/dev/cc-archive/
└── {YYYYMMDDHHMM}-{issue-number}-{brief-description}/
├── SCRATCHPAD_{issue_number}.md
├── SESSION_LOG_1.md (converted or legacy)
└── README.md (summary)
Note: The final archive always contains .md files only. Any .jsonl files are converted to markdown during archiving (see Phase 4).
For each SESSION_LOG_*.jsonl file found in Phase 2, convert to markdown before archiving.
The conversion uses scripts/convert-session-log.py from the Escapement plugin directory (${CLAUDE_PLUGIN_ROOT}).
For each .jsonl file:
CODE_SHA=$(git rev-parse --short HEAD)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/convert-session-log.py" \
SESSION_LOG_{N}.jsonl SESSION_LOG_{N}.md "$CODE_SHA"
rm SESSION_LOG_{N}.jsonl
This produces a markdown file with:
### User / ### Assistant / ### Summary)<details> blocksThe resulting .md file is ready to be moved to the archive directory in Phase 4 (alongside any legacy .md session logs).
Legacy .md files: Session logs already in .md format (from before this change) need no conversion — they pass through to Phase 4 directly.
Create Archive Directory:
Context mode:
CONTEXT_PATH=$(sed -n 's/^[[:space:]]*-[[:space:]]*\*\*context-path\*\*:[[:space:]]*\([^[:space:]]*\).*/\1/p' CLAUDE.md | head -1)
BRANCH=$(git branch --show-current)
ARCHIVE_DIR="$CONTEXT_PATH/$BRANCH/archive"
mkdir -p "$ARCHIVE_DIR"
In-repo mode:
TIMESTAMP=$(date +%Y%m%d%H%M)
ARCHIVE_DIR="docs/dev/cc-archive/${TIMESTAMP}-{issue-number}-{description}"
mkdir -p "$ARCHIVE_DIR"
Generate Archive Summary:
Create README.md in archive folder:
# Issue #{issue_number} - {title}
**Archived:** {date}
**Branch:** {branch_name}
**Code SHA:** {HEAD sha at time of archive}
**PR:** #{pr_number} (if applicable)
**Status:** {Completed/Merged/Abandoned}
## Summary
{Brief description of what was accomplished}
## Key Decisions
{Extract from scratchpad Decisions Made section}
## Files Changed
{List of files that were modified}
## Lessons Learned
{Any notable insights from Work Log}
Move Files:
Context mode:
# Copy scratchpad to context directory FIRST (before git rm deletes it)
cp SCRATCHPAD_{issue_number}.md "$ARCHIVE_DIR/"
# Then remove scratchpad from code repo tracking
git rm SCRATCHPAD_{issue_number}.md
# Move converted session logs from project root (.md only — .jsonl already
# converted and deleted in Phase 3.5)
for log in SESSION_LOG_*.md; do
if [ -f "$log" ]; then
mv "$log" "$ARCHIVE_DIR/"
fi
done
In-repo mode (existing behavior):
git mv SCRATCHPAD_{issue_number}.md "$ARCHIVE_DIR/"
for log in SESSION_LOG_*.md; do
if [ -f "$log" ]; then
mv "$log" "$ARCHIVE_DIR/"
fi
done
git add "$ARCHIVE_DIR"/SESSION_LOG_*.md 2>/dev/null || true
Important (context mode): Copy the scratchpad BEFORE git rm — git rm deletes
the working tree copy. The scratchpad content is preserved in the context directory.
The context directory is NOT a git repo managed by this skill — the operator handles
that separately.
AskUserQuestion:
question: "Ready to archive this work?"
header: "Archive"
options:
- "Yes, archive and commit"
description: "Move files to archive and create commit"
- "Archive without commit"
description: "Move files but don't commit yet"
- "Show me what will be archived"
description: "Preview the archive operation"
- "Cancel"
description: "Keep scratchpad in current location"
Context mode additional info:
Archive destination: {resolved context path}/{branch}/archive/
(outside code repo — context directory)
Code repo changes:
- SCRATCHPAD_{issue_number}.md will be removed (git rm)
Context directory changes:
- Scratchpad, session logs, and summary will be written
- You'll need to commit the context directory separately if it's git-tracked
Move Files (per Phase 4 instructions based on mode)
Write README.md to archive directory
Update INDEX.md (context mode only)
Skip this step entirely if ARCHIVE_MODE=in-repo.
When ARCHIVE_MODE=context, maintain a chronological manifest at the context-path root:
INDEX_FILE="{context-path}/INDEX.md"
Algorithm:
INDEX_FILE with the Read tool (if it exists)# Archive Index
| Archived | Branch | Issue | Status |
|----------|--------|-------|--------|
| {YYYY-MM-DD} | {branch} | [#{issue_number}]({issue_github_url}) {issue_title} | {status} |
{YYYY-MM-DD}: today's date{branch}: the branch being archived (from git branch --show-current){issue_number}, {issue_title}, {issue_github_url}: from the scratchpad{status}: the same value used in the archive README (Merged, Completed, or Abandoned)Example result after two archives:
# Archive Index
| Archived | Branch | Issue | Status |
|----------|--------|-------|--------|
| 2026-02-20 | 43-fix-login-bug | [#43](https://github.com/owner/repo/issues/43) Fix login bug | Merged |
| 2026-02-25 | 44-refactor-api | [#44](https://github.com/owner/repo/issues/44) Refactor API | Merged |
Commit in Code Repo: If user opted to commit:
Context mode:
Skill: commit-changes
# Commit message will be:
# 📚🗃️ chore(docs): Archive work for issue #{issue_number}
#
# Scratchpad archived to context directory
# PR: #{pr_number}
The commit only contains the removal of the scratchpad from project root. No archive files are added to the code repo.
In-repo mode:
Skill: commit-changes
# Commit message will be:
# 📚🗃️ chore(docs): Archive work for issue #{issue_number}
#
# Completed work archived to docs/dev/cc-archive/
# PR: #{pr_number}
Context mode:
Work archived successfully.
Context archive:
{context-path}/{branch}/archive/
Files archived (to context directory):
- SCRATCHPAD_{issue_number}.md
- SESSION_LOG_*.md (if any existed)
- README.md (summary generated)
INDEX.md updated:
- {context-path}/INDEX.md
- Added row: {date} | {branch} | #{issue_number} | {status}
Code repo cleanup:
- Removed SCRATCHPAD_{issue_number}.md (git rm)
- Removed SESSION_LOG_*.md from project root
{If committed}
Code repo committed: {commit hash}
- Removed: SCRATCHPAD_{issue_number}.md
Note: context directory changes are not auto-committed.
If your context directory is git-tracked, commit separately:
cd {context-path} && git add -A && git commit -m "Archive {branch} work"
In-repo mode:
Work archived successfully.
Archive location:
docs/dev/cc-archive/{YYYYMMDDHHMM}-{issue-number}-{description}/
Files archived:
- SCRATCHPAD_{issue_number}.md
- SESSION_LOG_*.md (if any existed)
- README.md (summary generated)
Cleaned up:
- Removed scratchpad from project root (tracked via git mv)
- Removed session logs from project root
{If committed}
Committed: {commit hash}
- Added: archive directory with scratchpad, session logs, README
- Removed: SCRATCHPAD_{issue_number}.md from project root
- Removed: SESSION_LOG_*.md from project root
If user prefers not to keep history:
AskUserQuestion:
question: "How to handle the scratchpad?"
options:
- "Archive (keep history)"
- "Delete (no history)"
- "Keep in place"
Allow user to specify different archive location:
AskUserQuestion:
question: "Archive to default location?"
options:
- "Yes, use {detected location}"
- "Specify custom location"
No scratchpad found to archive.
Looking for: SCRATCHPAD_*.md in project root
Scratchpad has incomplete tasks:
- {unchecked task 1}
- {unchecked task 2}
Archive anyway?
1. Yes, archive incomplete work
2. No, continue working first
Context path configured but directory not found:
{context-path}
Options:
1. Create it now
2. Fall back to in-repo archive
3. Cancel
Archive already exists for this branch
{context-path}/{branch}/archive/
Options:
1. Merge into existing archive
2. Create timestamped subdirectory
3. Cancel
No PR found for this work.
Archive anyway?
1. Yes, archive without PR reference
2. No, create PR first
Invoked by:
do-work skill - After completing all tasksInvokes:
commit-changes skill - To commit archiveReads from:
git rm for scratchpads in context mode (clean code repo history)git rm before copying the file (it deletes the working copy)Version: 2.2.1 Last Updated: 2026-02-26 Maintained By: Escapement Changelog:
npx claudepluginhub fusupo/escapement --plugin escapementCreates, loads, syncs, and archives work sessions with git worktree support. Requires explicit session paths or .samocode config.
Sync tracking documents based on current conversation results. Updates subtask, progress, findings, task_plan, project CLAUDE.md. Use when finishing a task or reaching a milestone.
Archives a completed or abandoned plan by moving it to an archived folder with metadata and timestamp.