liamlin/park

/park — Capture, View & Resume Unfinished Work

Persist structured parked files so any future agent (in any session or worktree) can discover and resume work.

Routing

Inspect the subcommand argument and run the matching flow:

| Argument | Flow | |---|---| | (none) | Park — infer from context, draft, confirm, write | | "quoted text" or any text that isn't list/resume/done | Park — use text as title | | list | List — show all parked items | | resume | Resume — pick an item, create tasks, mark in-progress | | done or done <slug> | Done — mark a parked item completed |

---

Park Flow

This is often the last action before the user clears the session. Be aggressive about inferring — do not ask open-ended questions. One confirmation round max.

Step 1: Gather Context

Run in parallel: git log --oneline -20, git diff --stat HEAD, git branch --show-current

Also:

• Glob the project memory directory for existing parked_*.md files to avoid duplicates
• Read any active plan file (glob .claude/plans/*.md for recently modified files)
• Check for incomplete tasks via TaskList

Step 2: Draft the Parked File

Using the gathered context + conversation history, draft a complete parked file. If the user provided a summary string, use it as the title. Otherwise, infer a title from the work done.

Critical — capture things that won't survive context clear:

• Key decisions made and WHY (rationale, trade-offs discussed)
• Approaches tried and rejected
• Non-obvious context the next agent will need
• Concrete file paths, function names, commit hashes

Present the draft to the user. If they say "yes", "looks good", "lgtm", or similar — write immediately. If they give corrections, apply and write. One round only.

Step 3: Write the File

Location: The project's memory directory (find it by looking for MEMORY.md in the .claude/projects/ tree).

Filename: parked_<slug>_<YYYYMMDD>.md where <slug> is a kebab-case version of the title.

If a file with a matching slug already exists (ignoring the date suffix), update it by default. Create a new one only if the user explicitly requests it.

File format:

---
name: <descriptive title>
description: <one-line summary — will appear in MEMORY.md index>
type: project
status: parked
parked_at: <ISO 8601 timestamp, e.g. 2026-04-03T16:30:00+08:00>
branch: <git branch name>
---

## Completed

- <commit hash> — <commit message>
- Uncommitted: <summary of unstaged/staged changes, if any>

## Remaining

Priority order:

1. **<Item title>** — <what needs to be done>
   - Depends on: <dependency, if any>
2. **<Item title>** — <description>

## Key Decisions

- **<Decision>**: <rationale — why this choice was made>

## Pickup Instructions

1. **Read first**: <2-3 most important files for context, with paths>
2. **Run first**: <commands to verify current state, e.g. `pnpm typecheck`, `pnpm test`>
3. **Start with**: <which Remaining item to tackle first and why>

Step 4: Update MEMORY.md

Find MEMORY.md in the same directory. Append one line:

- [parked_<slug>_<date>.md](parked_<slug>_<date>.md) — [PARKED] <summary>

The [PARKED] tag makes items scannable.

Step 5: Confirm

Print a brief summary: title, remaining item count, file path. The user can now safely clear the session.

---

List Flow

1. Glob parked_*.md in the project memory directory
2. Read each file's YAML frontmatter to get name, status, parked_at, branch
3. Count remaining items (numbered list items under ## Remaining)
4. Print a formatted table:

Parked Work:
  1. [parked] shop-api-timezone (2026-04-03, main) — 3 items remaining
  2. [in-progress] booking-refactor (2026-04-01, feat/booking) — 5 items remaining
  3. [done] queue-fix (2026-03-28, main)

If no parked_*.md files exist, print: "Nothing parked."

---

Resume Flow

1. Run the List flow to show available items
2. Filter to items with status: parked only
3. If exactly one parked item, auto-select it; if multiple, ask the user to pick by number
4. Read the selected parked file in full
5. Present to the user: title, Key Decisions, and Pickup Instructions sections
6. Create tasks from the Remaining items using TaskCreate — each numbered item becomes a task, preserving priority order and dependency notes
7. Update the parked file's frontmatter: change status: parked to status: in-progress
8. Update MEMORY.md: change [PARKED] to [IN-PROGRESS] on the matching line

The tasks are now queued. The agent works through them after finishing current work.

---

Done Flow

1. If a slug is provided (e.g., /park done shop-api-timezone), find the matching parked_*.md file by partial slug match
2. If no slug provided, run the List flow and ask which item is done
3. Update the parked file's frontmatter: change status to completed
4. Update MEMORY.md: change [PARKED] or [IN-PROGRESS] to [DONE] on the matching line
5. Print confirmation