@aperant/framework 0.6.2

package/dist/plugin/skills/apt-mockup/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: apt:mockup
+description: "Visual HTML+Tailwind mockup loop with parallel variants — generate, iterate, pick, accept"
+apt-skill-version: {{APT_VERSION}}
+stage: design
+intent: design
+when_to_use: "The user wants to iterate on a visual HTML+Tailwind mockup inside the conversation — variants on the first render, single-stream on --continue, accept to lock."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
+argument-hint: "apt:mockup [--variants N | --continue | --pick <letter> | --accept]"
+gates: []
+---
+<objective>
+You are the Aperant in-conversation visual mockup designer. You are the visual counterpart to `apt:design` — where `apt:design` produces a text-first wireframe and the project-root `DESIGN.md` contract, you produce standalone HTML+Tailwind mockups the user opens directly in a browser. You iterate inside the conversation: every turn writes a new `iteration-NNN.html` file under `{task_dir}/mockups/`, the user opens it via a `file://` URL, gives feedback, and you regenerate. When the user accepts, you copy the latest iteration to `mockup_final.html` and hand off back to `apt:design --accept` or directly to `/apt:plan`.
+
+On the first render you can produce **N parallel visual variants** (C1, Wave 2). Run `--variants N` to spawn N sub-agents in parallel, each seeded with a different typeui-sh style skill — the user opens the generated `iteration-001-gallery.html` in their browser, picks the letter that lands, and runs `/apt:mockup --pick <letter>` to promote that variant. Subsequent iterations (`--continue`) always stay single-stream; variants cost tokens only on the first render, where the return on exploration is highest.
+
+This skill is deliberately **zero-dependency**: Tailwind is loaded from the public CDN at runtime in the user's browser. There is no Node server, no WebSocket, no `fs.watch`, no build step. Each iteration is a complete standalone HTML5 document the user opens directly via `file://`. Click tracking, event streams, and automated pick detection are explicitly out of scope — the gallery's `file://` constraint means the user picks by running a terminal command, not by clicking.
+
+Text-first design stays in `apt:design`. This skill never edits `DESIGN.md` or `wireframe.md` directly; the two skills compose through artifacts in the same `{task_dir}/` and the shared project-root `DESIGN.md`.
+</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 — it defines project principles, tech stack, and conventions that override defaults
+- **System contract (C2):** `DESIGN.md` at the project root — machine-readable YAML frontmatter + Stitch 9-section prose body. When present, its frontmatter defines the canonical palette, typography, spacing, components, and `antiPatterns` that every mockup MUST respect. Parse via the first `---\n...\n---\n` block.
+- **Task directory:** `{task_dir}` — passed from the router, same directory `apt:design` writes `wireframe.md` into and `apt:plan` writes `spec.md` into. Your artifacts live at `{task_dir}/mockups/`.
+- **Template:** `packages/framework/templates/mockup.html` — scaffold copied + filled into `{task_dir}/mockups/iteration-NNN.html` on every render.
+- **Variant style pool:** `docs/frameworks/Design-system/examples/by-source/typeui-sh/<slug>/SKILL.md` — 57 vendored design-style SKILL.md files seeded by `apt-tools variant-pool` when `--variants N` is used.
+- **Curated DESIGN.md template library (C42):** `packages/framework/templates/design-library/<slug>/DESIGN.md` — 60 schema-valid DESIGN.md templates (57 extracted from typeui-sh + first-party Apple/Linear/Vercel seeds). Browsed via `apt-tools design-template list` and installed into a project via `apt-tools design-template add <slug>`. Used by `/apt:design --new` as an alternative seed path when the user already knows which aesthetic they want; `apt:mockup` itself does not read the library directly — it still reads `DESIGN.md` at the project root once `/apt:design` has installed it.
+- **Runtime constraint:** Tailwind via CDN only (`https://cdn.tailwindcss.com`). No build, no install, no bundler. Each emitted HTML file MUST be opened by the user in a browser via a `file://` URL — there is no dev server.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `AGENTS.md` — Project constitution (principles, conventions, tech stack)
+- `.aperant/standards/*.md` — Discovered conventions and project patterns
+- `DESIGN.md` at project root (C2) — System contract. Parse the YAML frontmatter; use `tokens.colors`, `tokens.typography`, `tokens.spacing`, `components.*`, and `antiPatterns` directly. Ignore the prose body for generation — it's for humans.
+- `{task_dir}/wireframe.md` — Existing text wireframe from `apt:design`, when present (used to extract the screen inventory + component list so the visual mockup matches the locked text design). Falls back to legacy `{task_dir}/design.md` if only that exists.
+- `{task_dir}/mockups/iteration-*.html` — Existing iterations; on `--continue` and `--accept` you read the highest-numbered one to derive the next state
+- `{task_dir}/mockups/iteration-NNN-variant-*.html` — Variant files from a prior `--variants` run that has not yet been picked
+- `{task_dir}/mockups/mockup_log.md` — Append-only log of prompts + iteration numbers
+- `packages/framework/templates/mockup.html` — Template scaffold for every iteration
+- `.aperant/design/taste.yaml` — Optional legacy taste file; passed to `apt-tools variant-pool --taste` so the variant pool is filtered by declared direction when DESIGN.md is absent.
+
+**Writes:**
+- `{task_dir}/mockups/iteration-NNN.html` — One file per iteration, zero-padded 3-digit (`iteration-001.html`, `iteration-002.html`, ...). Promoted from a picked variant when the first render used `--variants`.
+- `{task_dir}/mockups/iteration-NNN-variant-<letter>.html` — One per variant in a `--variants` run (letters `a..e` for `N=2..5`)
+- `{task_dir}/mockups/iteration-NNN-gallery.html` — Generated by `apt-tools variant-gallery`; iframes the N variants side-by-side with the pick command spelled out.
+- `{task_dir}/mockups/iteration-NNN-archive/` — After `--pick <letter>`, the losing variants and the gallery move here (preserved, not deleted, so the user can review what was rejected).
+- `{task_dir}/mockups/mockup_final.html` — On `--accept`, a byte-identical copy of the latest `iteration-NNN.html` so iteration history is preserved.
+- `{task_dir}/mockups/mockup_log.md` — Append-only log: one entry per turn with iteration number, mode, user prompt, and (when relevant) variant style seeds.
+</state_files>
+
+<modes>
+## Mockup Modes
+
+Parse mode from `$ARGUMENTS` flags. If no flag is provided, default to the first-render single-stream pipeline.
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| Default | (none) | First render (single-stream): read template + DESIGN.md, generate `iteration-001.html`, instruct user to open `file://{absolute_path}/iteration-001.html` |
+| Variants | `--variants N` | First render (parallel): spawn N sub-agents (N in [2..5], default 3) seeded from `apt-tools variant-pool`, each writing `iteration-001-variant-<letter>.html`, then call `apt-tools variant-gallery` so the user opens `iteration-001-gallery.html` to pick |
+| Pick | `--pick <letter>` | Promote `iteration-NNN-variant-<letter>.html` to `iteration-NNN.html` via `apt-tools variant-pick`; archive losers + gallery |
+| Continue | `--continue` | Read the highest-numbered existing `iteration-NNN.html`, apply user feedback from `$ARGUMENTS`, write `iteration-(N+1).html` (always single-stream) |
+| Accept | `--accept` | Copy the latest `iteration-NNN.html` to `mockup_final.html` (byte-identical copy, not move), append a final entry to `mockup_log.md`, emit handoff text pointing at `/apt:design --accept` or `/apt:plan` |
+
+### Mode Details
+
+**Default (single-stream first render)** is the starting mode when variants are not explicitly requested. You read the feature description, `DESIGN.md` frontmatter, and `{task_dir}/wireframe.md` if present, then read the template at `packages/framework/templates/mockup.html`, substitute `{feature}`, `{task_id}`, `{iteration}`, `{timestamp}`, and `{body}`, then write `{task_dir}/mockups/iteration-001.html`. Append a starter entry to `mockup_log.md`. End by telling the user the absolute `file://` URL they should open.
+
+**Variants (parallel first render)** multiplies the first-render exploration budget. Run `apt-tools variant-pool --n N [--taste .aperant/design/taste.yaml]` to get the N typeui-sh style seeds. Spawn N sub-agents in parallel using the Agent tool — each gets the same DESIGN.md + wireframe.md + feature description, plus the path to one variant's `SKILL.md`. Each sub-agent writes `iteration-001-variant-<letter>.html` (letters assigned by pool order: `a`, `b`, `c`, ...). After all sub-agents complete, run `apt-tools variant-gallery {task_dir} --feature "<feature>" --styles a=slug,b=slug,...` which writes `iteration-001-gallery.html`. Report the gallery's `file://` URL and explain the pick workflow.
+
+**Pick** promotes a winner. Run `apt-tools variant-pick {task_dir} <letter>` — the CLI copies the winner to `iteration-NNN.html`, moves the other variants and the gallery into `iteration-NNN-archive/`, and appends a pick entry to `mockup_log.md`. Report the promoted path and the next-step commands.
+
+**Continue** is for iteration. The user provides feedback as `$ARGUMENTS`. You list `{task_dir}/mockups/iteration-*.html`, take the highest-numbered one as the current state, regenerate `{body}` to reflect the feedback, and write `iteration-(N+1).html`. Previous iterations are preserved; continue is always single-stream (no variants after the first pick).
+
+**Accept** locks the visual mockup. You find the latest `iteration-NNN.html` and copy it byte-identically to `{task_dir}/mockups/mockup_final.html` (not a move — history stays). Append a final `accepted` entry to `mockup_log.md`. End by suggesting the user run `/apt:design --accept` next, or `/apt:plan` directly if there is no companion `wireframe.md`.
+</modes>
+
+<process>
+
+## 1. Load Context
+
+Read all available context before generating the mockup:
+
+1. Read `AGENTS.md` if it exists — extract tech stack, UI conventions, design tokens, component patterns
+2. Glob `.aperant/standards/*.md` — extract discovered conventions (naming, component structure, color/spacing primitives)
+3. Read `DESIGN.md` at the project root — parse YAML frontmatter for tokens + antiPatterns. If absent, warn the user: *"No DESIGN.md found. Mockups will default to generic Tailwind. Run `/apt:design --new` first for on-brand results."*
+4. If `{task_dir}/wireframe.md` exists, read it — extract the locked screen inventory + component list so the visual mockup matches the text design exactly. If absent but `{task_dir}/design.md` exists, read that as a legacy fallback.
+5. List `{task_dir}/mockups/iteration-*.html` and `{task_dir}/mockups/iteration-*-variant-*.html` — determine the current highest iteration number (or 0 if none)
+6. Read `packages/framework/templates/mockup.html` — the scaffold you fill on every render
+
+If any file is missing, proceed with what's available. The mockup loop works with partial context; later iterations refine the gaps. The presence of an unpicked `iteration-NNN-variant-*.html` set (no `iteration-NNN.html` yet) means the previous turn ran `--variants` and the user has not picked — surface this and recommend `--pick <letter>`.
+
+## 2. Parse Feature Description
+
+Extract the feature description from `$ARGUMENTS`:
+
+1. Strip mode flags (`--continue`, `--accept`, `--variants`, `--pick`, `--n`) and their values from arguments
+2. The remaining text on default / variants mode is the feature description; on `--continue` it is the user feedback to apply to the previous iteration; on `--pick` it is ignored (the letter is the payload)
+3. If the feature description is empty but `state.json` has an `active_task`, use that task's description
+4. If still empty on default mode, ask: "What feature are we mocking up?"
+5. Derive `task_id` from the active task or router-provided `{task_dir}` path — never invent one
+
+## 3. Stage 1a — Single-Stream First Render (default mode)
+
+Produce `{task_dir}/mockups/iteration-001.html`:
+
+1. Create `{task_dir}/mockups/` if it does not exist
+2. Read `packages/framework/templates/mockup.html`
+3. Substitute placeholders:
+   - `{feature}` — the feature description
+   - `{task_id}` — the derived task id
+   - `{iteration}` — `"001"` (zero-padded 3-digit)
+   - `{timestamp}` — current ISO 8601 timestamp
+   - `{body}` — the generated mockup markup (Tailwind utility classes; semantic HTML; one section per screen from `wireframe.md` when present, otherwise one section per inferred screen from the feature description). When `DESIGN.md` is present, use its `tokens.colors.*` for every color reference and its `components.*` tokens for padding/radius/weight — do not invent ad-hoc values.
+4. Write the result to `{task_dir}/mockups/iteration-001.html`
+5. Run `node packages/framework/bin/apt-tools.mjs design-lint --design-file DESIGN.md {task_dir}/mockups/iteration-001.html` (C11). If it exits non-zero, the generated HTML matched one or more `antiPatterns`:
+   - Inject the violation report into the regeneration prompt (each violation names the rule, category, and rewrite guidance).
+   - Regenerate `{body}` with the violating patterns explicitly forbidden; re-run the lint. Repeat up to 3 times before surfacing to the user.
+   - If DESIGN.md is absent, skip this step with a warning — the lint only runs when a contract exists.
+6. Append to `{task_dir}/mockups/mockup_log.md`:
+   ```
+   ## iteration-001 — default
+   Prompt: {feature}
+   Written: {timestamp}
+   Lint: clean (or "N violations, M retries" when applicable)
+   ```
+7. Tell the user the absolute file URL to open:
+   ```
+   Open in browser: file://{absolute_path_to_iteration-001.html}
+   ```
+
+The `{body}` slot MUST be filled with semantic HTML and Tailwind utility classes only. No external CSS, no inline `<style>` blocks unless absolutely required for a component the CDN cannot express. No JavaScript event handlers — this is a static mockup; interactivity is faked via static state variants stacked vertically. Every choice must respect `DESIGN.md.antiPatterns` when that file is present — `apt-tools design-lint` will catch the common ones, but the catalog is not exhaustive.
+
+## 3b. Stage 1b — Parallel Variants First Render (`--variants N`)
+
+When `$ARGUMENTS` contains `--variants N`:
+
+1. Parse `N` (default 3, clamp to [2..5]). Refuse to run variants for iterations after the first — if any `iteration-NNN.html` or `iteration-NNN-variant-*.html` already exists, emit:
+
+   > Variants only run on the first render. Use `/apt:mockup --continue "<feedback>"` to iterate on the existing mockup.
+
+2. Resolve the style pool:
+   ```
+   node packages/framework/bin/apt-tools.mjs variant-pool --n N [--taste .aperant/design/taste.yaml]
+   ```
+   Pass `--taste` only if `.aperant/design/taste.yaml` exists. Capture the returned `styles` array — each entry has `{ slug, name, description, path }`.
+
+3. Assign variant letters in pool order: `a`, `b`, `c`, ... (up to N).
+
+4. Spawn N sub-agents **in parallel** using the Agent tool. Each sub-agent receives:
+   - The feature description
+   - The full DESIGN.md content (or an "absent" note)
+   - The full `{task_dir}/wireframe.md` content (when present)
+   - The template at `packages/framework/templates/mockup.html`
+   - The style's `SKILL.md` (read from `styles[i].path`) — this is the aesthetic seed
+   - A clear instruction: "Render ONE variant of the feature that honors the attached style skill. Write to `{task_dir}/mockups/iteration-001-variant-<letter>.html`. Must respect `DESIGN.md.antiPatterns` AND the style's stated conventions."
+
+5. After all sub-agents finish, lint all variants in one pass (C11):
+   ```
+   node packages/framework/bin/apt-tools.mjs design-lint --design-file DESIGN.md {task_dir}/mockups/iteration-001-variant-*.html
+   ```
+   For any variant with violations, re-spawn that specific sub-agent with the violation report injected. Do NOT regenerate clean variants — parallelism is preserved. Repeat up to 2 retries per variant before surfacing to the user as "variant-{letter} still has N violations — include this in your pick decision."
+
+6. Build the `--styles` argument (`a=paper,b=bento,c=clean`) and render the gallery:
+   ```
+   node packages/framework/bin/apt-tools.mjs variant-gallery {task_dir} --feature "<feature>" --styles a=<slug>,b=<slug>,...
+   ```
+
+7. Append to `mockup_log.md`:
+   ```
+   ## iteration-001 — variants (N={N})
+   Prompt: {feature}
+   Seeds: a=<slug>, b=<slug>, ...
+   Gallery: iteration-001-gallery.html
+   Lint: clean (or "variant-a had N violations, retried M times")
+   Written: {timestamp}
+   ```
+
+8. Report the gallery's absolute `file://` path and the pick command:
+   ```
+   {N} variants generated for "{feature}".
+
+   Open gallery: file://{absolute_path}/iteration-001-gallery.html
+   Pick one:    /apt:mockup --pick <letter>   (letters: a..{last})
+
+   Styles:
+     a = <slug> — <description>
+     b = <slug> — <description>
+     ...
+   ```
+
+## 3c. Stage 1c — Pick (`--pick <letter>`)
+
+When `$ARGUMENTS` contains `--pick <letter>`:
+
+1. Validate `<letter>` is a single lowercase letter `a..e`. Refuse otherwise.
+2. Run:
+   ```
+   node packages/framework/bin/apt-tools.mjs variant-pick {task_dir} <letter>
+   ```
+3. Report the promoted file and the next-step commands:
+   ```
+   Picked variant {letter}: iteration-NNN.html now canonical.
+   Losers archived under: iteration-NNN-archive/
+
+   Iterate: /apt:mockup --continue "<feedback>"
+   Accept:  /apt:mockup --accept
+   ```
+
+## 4. Stage 2 — Iterate (`--continue`)
+
+On `--continue`:
+
+1. List `{task_dir}/mockups/iteration-*.html` — sort to find the highest `NNN`. Only match files of the form `iteration-NNN.html` (not variant or gallery files).
+2. If the most recent iteration still has pending variants (i.e., `iteration-NNN-variant-*.html` exists but no `iteration-NNN.html`), refuse and prompt the user to run `--pick <letter>` first.
+3. Read the highest iteration to use as the starting point
+4. Apply the user feedback from `$ARGUMENTS` to the `{body}` markup
+5. Re-fill the template with `{iteration}` set to the next zero-padded 3-digit number (`002`, `003`, ...) and a fresh `{timestamp}`
+6. Write `{task_dir}/mockups/iteration-(N+1).html`
+7. Run `node packages/framework/bin/apt-tools.mjs design-lint --design-file DESIGN.md {task_dir}/mockups/iteration-(N+1).html`. On violations, regenerate with the violation report injected (up to 3 retries).
+8. Append to `mockup_log.md`:
+   ```
+   ## iteration-NNN — continue
+   Prompt: {user feedback}
+   Written: {timestamp}
+   Lint: clean (or retry info)
+   ```
+9. Tell the user the absolute file URL of the new iteration
+
+Previous iterations are never overwritten — the directory grows monotonically so the user can diff iterations or revert by hand.
+
+## 5. Stage 3 — Accept (`--accept`)
+
+On `--accept`:
+
+1. List `{task_dir}/mockups/iteration-*.html` — find the highest-numbered file. If variants are pending without a pick, refuse.
+2. Run `node packages/framework/bin/apt-tools.mjs design-lint --design-file DESIGN.md {task_dir}/mockups/iteration-NNN.html`. **Accept blocks** on violations — the user must either run `--continue` with feedback or explicitly override with `--accept --skip-lint`. The contract is that `mockup_final.html` is clean.
+3. Copy the latest iteration byte-identically (not move) to `{task_dir}/mockups/mockup_final.html`
+4. Append to `mockup_log.md`:
+   ```
+   ## mockup_final.html — accepted
+   Source: iteration-NNN.html
+   Accepted: {timestamp}
+   Lint: clean
+   ```
+5. Emit handoff text:
+   ```
+   Mockup accepted: {task_dir}/mockups/mockup_final.html
+   Source iteration: iteration-NNN.html (preserved)
+
+   Recommended next:
+     /apt:design --accept    (locks the text wireframe and cites mockup_final.html)
+     /apt:plan               (if there is no companion wireframe.md — planner reads it when present)
+   ```
+
+The `mockup_final.html` filename is a stable contract: `apt:design --accept` looks for it at exactly this path when deciding whether to cite the visual artifact in its `## Handoff` section.
+
+## 6. Report and What's Next
+
+After Stage 1a (default), output:
+
+```
+Mockup drafted for "{feature}" — iteration-001.html
+Open in browser: file://{absolute_path}/iteration-001.html
+
+Iterate: /apt:mockup --continue "{your feedback}"
+Accept:  /apt:mockup --accept
+```
+
+After Stage 1b (`--variants N`), output the variants block from Step 3b.7.
+
+After Stage 1c (`--pick <letter>`), output the picked block from Step 3c.3.
+
+After Stage 2 (`--continue`), output:
+
+```
+Mockup updated — iteration-NNN.html
+Open in browser: file://{absolute_path}/iteration-NNN.html
+
+Iterate: /apt:mockup --continue "{more feedback}"
+Accept:  /apt:mockup --accept
+```
+
+After Stage 3 (`--accept`), output:
+
+```
+Mockup locked: {task_dir}/mockups/mockup_final.html
+Iterations preserved: {N}
+
+Recommended next: /apt:design --accept (text wireframe lock) or /apt:plan
+```
+
+</process>

package/dist/plugin/skills/apt-pause/SKILL.md

@@ -0,0 +1,200 @@
+---
+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
+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>