---
name: apt:pause
description: "Human-initiated session handoff — save CONTINUE artifacts when YOU want to stop"
apt-skill-version: {{APT_VERSION}}
stage: pause
intent: capture
when_to_use: "The human operator wants to stop work for the day or hand off — save CONTINUE artifacts for later /apt:resume. Not for agent-initiated context bailouts."
user_invocable: true
internal: false
spawns_agent: false
agent_name: null
task_context: none
default_execution_mode: auto
execution_modes:
  - auto
  - step
allowed-tools: "Bash, Read, Write"
argument-hint: "apt:pause [reason]"
gates: []
---
<objective>
Capture the current work state so a different session — or a future you — can pick up exactly where you left off. Records decisions made, work completed, remaining tasks, blockers, and next steps.

**Use this when the human operator wants to stop.** End of day, going on vacation, switching to a different task, handing off to a teammate. `/apt:pause` is a human ergonomics tool, not a framework-internal state handoff.

**Do NOT use this to "gracefully exit" when context is tight.** The query loop auto-compacts when it needs to. Agents executing plans (`/apt:execute`, `/apt:run`, `/apt:review`, etc.) must keep running through auto-compact by checkpointing to `build-progress.json` on every subtask — that is the resume mechanism for harness-driven interruptions. `apt:pause` is only invoked when the human types `/apt:pause` themselves.

Supports parallel pausing — each task gets its own CONTINUE.md, and an index tracks all paused sessions.
</objective>

<your_environment>
- **Working directory:** The project root (where you were invoked)
- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
- **Constitution:** Read `AGENTS.md` in the project root if it exists
- **Pause index:** `.aperant/CONTINUE_INDEX.md`
</your_environment>

<state_files>
## State Files

**Reads:**
- `AGENTS.md` — Project constitution
- Any active Aperant state files:
  - `{task_dir}/spec.md`, `{task_dir}/implementation_plan.json`, `{task_dir}/build-progress.json` (from apt:plan/execute)
  - `{task_dir}/qa_signoff.json` (from apt:verify)
  - `review.json` (from apt:review)
  - `.aperant/debug/*/DEBUG.md` (from apt:debug)
  - `.aperant/quick/*/TASK.md` (from apt:quick)
- Git state (branch, uncommitted changes, stash)

**Writes:**
- `{task_dir}/CONTINUE.md` — Per-task session handoff (if inside a routed task)
- `.aperant/paused/{session-slug}/CONTINUE.md` — Ad-hoc session handoff (if NOT inside a routed task)
- `.aperant/CONTINUE_INDEX.md` — Index of all paused sessions
</state_files>

<process>

## 1. Determine Pause Location

Decide where to write the CONTINUE.md based on context:

**If inside a routed task** (task_dir is known from the conversation, or state.json has an active task for this branch):
- Write to `{task_dir}/CONTINUE.md`
- The task_dir is typically `.aperant/tasks/{task-id}/`

**If ad-hoc work** (manual coding, not routed through /apt):
- Generate a session slug: `paused-{YYYYMMDD}-{short-description}` (e.g., `paused-20260413-chat-ui-polish`)
- Write to `.aperant/paused/{session-slug}/CONTINUE.md`

```bash
mkdir -p {continue_dir}
```

## 2. Gather Current State

Collect all context about the current work session:

### 2a. Git State
```bash
git branch --show-current
git status --short
git log --oneline -5
git stash list
```

### 2b. Active Aperant Artifacts
Check for the presence of these files and read their status:
- `implementation_plan.json` — How many subtasks completed vs pending?
- `build-progress.json` — Where did execution stop?
- `qa_signoff.json` — Was verification run? What was the verdict?
- `review.json` — Was review run? What was the assessment?
- `.aperant/debug/*/DEBUG.md` — Any active debug sessions?

### 2c. Conversation Context
From the current conversation, extract:
- What task was being worked on
- Key decisions made and their rationale
- What was tried and what worked/failed
- Any blockers or open questions

## 3. Write CONTINUE.md

Create `{continue_dir}/CONTINUE.md`:

```markdown
# Continue: {task description}

## Session Info
- **Date:** {ISO date}
- **Branch:** {current branch}
- **Last commit:** {hash} — {message}
- **Task ID:** {task-id, if routed task}

## What Was Being Done
{Clear description of the task and current activity}

## Decisions Made
- {decision 1} — {rationale}
- {decision 2} — {rationale}

## Work Completed
- [x] {completed item 1}
- [x] {completed item 2}

## Remaining Work
- [ ] {remaining item 1}
- [ ] {remaining item 2}

## Current State
- **Pipeline stage:** {plan | execute | verify | review | debug | quick | none}
- **Subtask progress:** {n}/{total} (if applicable)
- **Uncommitted changes:** {yes/no — what files}
- **Stashed work:** {yes/no}

## Blockers
- {blocker 1 — what's needed to unblock}
- (none)

## What Was Tried
- {approach 1} — {outcome}
- {approach 2} — {outcome}

## Next Steps
1. {immediate next action}
2. {following action}

## Key Files
- {file1} — {why it's relevant}
- {file2} — {why it's relevant}

## Resume Command
```
/apt:resume
```
```

## 4. Update Pause Index

Update `.aperant/CONTINUE_INDEX.md`:

If the file does not exist, create it with this header:
```markdown
# Paused Sessions

| Task | Branch | Date | Location |
|------|--------|------|----------|
```

Append one row for this pause:
```
| {task description (truncated to 50 chars)} | {branch} | {YYYY-MM-DD} | {relative path to CONTINUE.md} |
```

If a row already exists for this task (same CONTINUE.md path), update it instead of appending a duplicate.

## 5. Handle Uncommitted Work

If there are uncommitted changes:
```bash
git stash push -m "apt-pause: {task description}"
```

Note the stash in CONTINUE.md under "Current State".

## 6. Report

```
Work paused. Handoff saved to: {continue_dir}/CONTINUE.md

Summary:
  Task: {description}
  Branch: {branch}
  Progress: {brief status}
  Uncommitted: {stashed / none}
  Paused sessions: {total count from index}

Resume in a new session with: /apt:resume
```

</process>
