Park Thread

park-thread

Parking is the "alive but paused" state. A thread gets parked when work is blocked on something external (a missing dependency, a decision elsewhere, a quarter-boundary wait), or when the author realizes the thread is not the right shape yet but does not want to discard it. Parked threads stay at their original path and keep every byte of their content — only status and a small set of park metadata fields change.

Unparking is the symmetric reverse: clear the park metadata, restore status: active, and restore the maturity value held at park time. The skill treats the two directions as one operation with a --unpark flag because they share every non-trivial step (resolve, validate, flip, re-sync index, commit) and the divergence is narrow.

When to invoke

• "Park this thread" / "pause this" / "shelve this for now"
• "I need to stop thinking about <slug> until <X>"
• "Unpark <slug>" / "resume this thread" / "pick this back up"
• When current-state.md is cluttered with threads the user isn't actively working, and they want to hide them without killing them
• Before switching contexts for a long stretch and wanting to document why the thread was left

Inputs

Prompt strategy: resolve thread_slug from cwd. Infer mode from current status; if ambiguous (e.g. skill invoked without context), ask the user to pick park-vs-unpark. For park, always prompt for reason even if the user supplied an inline reason in their original message — parked threads are often re-read weeks later and a one-word reason is rarely enough.

Preconditions

The skill refuses if any of these are not met.

1. Current working directory is inside a brain root (a project-brain/ directory containing CONVENTIONS.md) or an explicit --brain=<path> was given. 2. project-brain/threads/[thread_slug]/thread.md exists. 3. For park mode:

• Thread status is active. Parking from in-review is refused (close or merge the PR first); parking from parked is a no-op refuse; parking from archived is refused.
• reason is non-empty.

4. For unpark mode:

• Thread status is parked.
• parked_at, parked_by, parked_reason are present in frontmatter (any missing means the thread was hand-edited into a bad state; refuse and route to manual fix or verify-tree).
• The preserved maturity value is one of exploring | refining | locking.

5. Working tree has no uncommitted changes to project-brain/thread-index.md, project-brain/current-state.md, or the thread's thread.md. 6. parked_by is resolvable. If --by <email> is supplied, use it. Otherwise write the literal placeholder TODO@example.com into the parked_by frontmatter field and append a TODO note to the thread body reminding the user to fix it. No `git` invocation and no env-var read — rc4 keeps park-thread shell-free. Precondition always succeeds (placeholder is always available); it never refuses.

Process

### ⛔️ HARD CONSTRAINT — ONE TOOL CALL

>

Call `${PROJECT_BRAIN_PACK_ROOT}/scripts/park-thread.sh` ONCE. No Read of thread.md, no pre-flight status check. The script reads frontmatter, determines park vs unpark (from the thread's current status or --unpark flag), validates, mutates, rebuilds indexes.

>

Derive mode + reason/trigger from language. "Park this for now, waiting on X" → --reason='waiting on X'. "Pick this back up — X just landed" → --unpark --trigger='X landed'. Don't ask.

One call:

"${PROJECT_BRAIN_PACK_ROOT}/scripts/park-thread.sh" \
  --brain=<absolute brain path> \
  --slug=<thread_slug>          \
  --reason='<reason>'           \    # park mode
  [--unpark]                    \    # unpark mode (alternative)
  [--trigger='<trigger>']       \    # optional unpark trigger description
  [--by=<email>]

Infer --slug from cwd. After success, echo the script's stdout in your response message verbatim — don't rely on the Bash tool's result card to display it; the user should see the script's output as part of your reply.

Dry-run semantics

When --dry-run is set:

1. Run all preconditions (steps 1–2 above), including brain-root existence, thread existence, status checks. Exit 1 if any fail. 2. Compute the full plan: print the mode (park or unpark), the frontmatter changes, any body append for unpark note, and the rebuild step. 3. Invoke `verify-tree --rebuild-index --dry-run` to surface any index-rebuild failures. If that fails, print the error and exit 1. 4. Write NOTHING to disk: neither frontmatter edits, nor body appends, nor the transcript. 5. Exit 0 if the plan would succeed end-to-end, exit 1 if any check failed, exit 2 on unexpected error.

Print the plan to stdout as a numbered list. When exiting 1, also print the failing precondition or rebuild error.

Side effects

Files written or modified

No file moves. The thread directory stays at threads/[slug]/ in both directions. This is deliberate — parking is not archiving.

Git operations

None. This skill performs file operations only. The user runs git add and git commit themselves (§ Git deferred).

When --dry-run is set: NO side effects. Stdout output only.

External calls

None.

Outputs

User-facing summary. A short message with:

• The commit SHA.
• The new status (parked or active) and the preserved (park) or restored (unpark) maturity.
• For park: the reason and unpark trigger, plus the suggestion "Run park-thread --unpark [slug] when you're ready to resume."
• For unpark: a pointer to the ## Park log entry (if written) and the suggestion "Continue with update-thread or promote-thread-to-tree."

State passed forward.

• thread_slug — unchanged.
• mode — park or unpark (the one that ran).
• thread_status — resulting status (parked or active).
• preserved_maturity — the maturity value carried through (always present in both directions).
• parked_reason — present if mode == park.

Verbosity contract

Reads verbosity from <brain>/config.yaml (env override: PROJECT_BRAIN_VERBOSITY). Defaults to terse.

• terse (default): one acknowledgement line naming the operation + thread, then Done.
• Example output: Parking project-brain/threads/alpha/ (reason: blocked on ADP). Done.
• normal: structured summary of frontmatter changes (status flip, metadata added/removed).
• verbose: full narration (pre-rc4 default). Use for debugging.

Frontmatter flips

maturity is never flipped by this skill in either direction. It is preserved across the park/unpark round-trip by design.

When --dry-run is set: no files are written; the frontmatter changes and any body appends are described in the plan output instead.

Postconditions

• Thread directory unchanged at threads/[slug]/. Nothing moved, no content deleted.
• On park: status == parked, the four park metadata fields are populated, and the thread is visible under ## Parked in thread-index.md (autogenerated).
• On unpark: status == active, no park metadata present, and the thread is visible under ## Active in thread-index.md (autogenerated).
• maturity equals whatever it was pre-skill (park direction) or pre-park (unpark direction). The round-trip is lossless.
• thread-index.md and current-state.md reflect the post-operation state of all threads (autogenerated).
• Exactly one commit was added.
• verify-tree passes on the thread.

Failure modes

Related skills

• Coordinates with: update-thread, discard-thread — the three pre-promotion thread operations; mutually exclusive per invocation.
• Blocks: promote-thread-to-tree — will refuse on a parked thread; unpark first.
• Compatible with: verify-tree — run after unpark to confirm the round-trip restored a clean state.
• Mutually exclusive with: itself — cannot be re-invoked in the same mode without an interleaving flip (no-op refuse).

Asset dependencies

None. The skill edits existing frontmatter and index files; it does not create files from templates. The ## Park log heading in thread.md is created on-demand by unpark when a note is supplied.

Versioning

0.2.2 — Added --dry-run flag specification with full semantics contract, including exit codes 0/1/2 (2 reserved for unexpected errors).

0.2.0 — Stage 2 of v0.9.0: index-file updates moved to centralized verify-tree --rebuild-index final step; previous inline edits removed.

0.1.0 — initial draft. Minor bump if a pin/snooze variant is added (e.g. a "park until <date>" that auto-unparks). Major bump if the preservation semantics around maturity change (e.g. a rule that parking always resets maturity to refining on unpark).