SuperAPI AI Directory

stashing

General & other

View repository

Updated 10-16 09:29

About this skill

Stashing Unfinished Work

Pause the active project in .writing/ without claiming it is done.

Core principle: archive = done, stash = paused. The target is the active project (design, plan, findings, progress), not "the session."

Announce at start: "I'm using the stashing skill to pause this work safely."

When to Use

Use this skill when:

  • current work is unfinished but you need to switch projects
  • you are blocked on external input, dependency, or review
  • you want to keep .writing/ clean without losing working context
  • the task should be resumable later

Do not use this skill for completed work. Use superpower-writing:archiving instead.

The Process

Step 1: Check stash-worthiness and completion guard

Run the planning state check:

${CLAUDE_PLUGIN_ROOT}/scripts/check-writing-state.sh

Act on the result:

  • missing or empty → warn the user there is nothing meaningful to stash. Stop.
  • complete → do not stash. Redirect to superpower-writing:archiving.
  • active → proceed to Step 2.

Step 2: Determine stash name

Derive a short stash name from the active task, then ask the user to confirm or modify it.

Generate a unique directory name:

mkdir -p .writing/stash
${CLAUDE_PLUGIN_ROOT}/scripts/unique-filename.sh .writing/stash "<name>" ""

The empty extension "" produces a directory-compatible name without .md suffix. Create the directory:

mkdir -p "<returned-path>"

Step 3: Save active project into stash directory

Save all active project files using the shared snapshot script:

${CLAUDE_PLUGIN_ROOT}/scripts/snapshot-save.sh "<returned-path>"

Then write a snapshot.md with metadata for quick resume context:

# Stash: <name>
**Date:** YYYY-MM-DD
**Status:** paused

## Current Goal
<!-- 1-2 lines -->

## Where We Stopped
<!-- concrete current status -->

## Next Steps
<!-- immediate next 3-5 actions -->

## Open Questions / Blockers
<!-- what is missing, blocked, or uncertain -->

## Important Files / Branches
<!-- key files, branch names -->

Step 4: Reset active state

${CLAUDE_PLUGIN_ROOT}/scripts/writing-reset.sh

This removes design.md, plan.md, progress.md, findings.md, and agents/, then recreates clean templates. archive/ and stash/ are preserved.

Report: "Stashed to .writing/stash//"

Step 5: Resume protocol

When resuming from a stash later:

  1. Check active work first:
${CLAUDE_PLUGIN_ROOT}/scripts/check-writing-state.sh
  • missing or empty → safe to proceed
  • active or complete → warn the user and offer options:
    1. Stash active work first, then resume
    2. Archive active work first, then resume
    3. Overwrite active work (destructive)
  • Do not overwrite without explicit confirmation.
  1. List available stashes:
${CLAUDE_PLUGIN_ROOT}/scripts/stash-list.sh
  1. If multiple exist, use AskUserQuestion to let the user choose one
  2. Restore files from stash directory to .writing/ root:
${CLAUDE_PLUGIN_ROOT}/scripts/stash-restore.sh ".writing/stash/<selected>"
  1. Read snapshot.md from the stash directory for resume context
  2. Perform stale-findings check before continuing:
    • compare stash assumptions against current repo state
    • run git diff --stat
    • quickly verify referenced files, paths, and branch still exist
    • mark findings as:
      • still valid
      • needs refresh
      • obsolete
  3. Explicitly report any stale or questionable findings before execution resumes
  4. If drift is large, recommend switching to superpower-writing:brainstorming or superpower-writing:writing-plans instead of blindly continuing

Legacy stash format: If the selected stash is a single .md file (old format) instead of a directory, read it and restore context into .writing/findings.md and .writing/progress.md as before.

Resume Output Format

When resuming, summarize in this format:

Stash resumed: <name>

Findings freshness check:
- still valid: <items>
- needs refresh: <items>
- obsolete: <items>

Recommended next step:
- <single best next action>

Key Principles

  • stash is for paused unfinished work, not completed work
  • stash preserves the entire active project (design, plan, findings, progress, agents)
  • stale-findings check is mandatory on resume
  • if resume reveals major drift, suggest re-planning instead of blindly continuing