@aperant/framework 0.8.0 → 0.8.4

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

@@ -0,0 +1,228 @@
+---
+name: apt:handoff
+description: "Agent-to-agent handoff — compact current conversation into a HANDOFF artifact in the repo for a fresh agent to pick up"
+apt-skill-version: {{APT_VERSION}}
+stage: pause
+intent: capture
+when_to_use: "An agent (not a human) needs to transfer in-flight work to a different agent — different model, different CLI, a fan-out peer, or a fresh context window. Writes a HANDOFF artifact under .aperant/ so the receiver picks up exactly where the sender left off. NOT for human end-of-day stops (use /apt:pause) and NOT for harness auto-compact (the query loop handles that itself)."
+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:handoff [what the next session will focus on]"
+gates: []
+---
+<objective>
+Compact the current conversation into a HANDOFF document so a different agent — different model, different CLI, fan-out peer, or fresh context window — can pick up the work without re-discovering everything you already know.
+
+Writes the handoff to `.aperant/handoffs/{id}/HANDOFF.md` (or `{task_dir}/handoffs/{id}/HANDOFF.md` when inside a routed task) so the artifact lives with the repo, survives across machines, and is discoverable by `/apt:resume` and team-status tooling.
+
+**Use when:** an agent decides to transfer the work mid-flight. Examples — sender hit context-budget cap, the next phase needs a different model (e.g. Codex for a heavy refactor), a fan-out conductor is sharding scope to peers, or a planning agent is handing a locked plan to an executor.
+
+**Do NOT use when:**
+- The human operator wants to stop — use `/apt:pause` (it stashes uncommitted work and updates `CONTINUE_INDEX.md`).
+- The harness is about to auto-compact — the query loop handles that itself; agents executing plans must checkpoint to `build-progress.json` instead.
+- A new task is starting fresh — use `/apt` (router) or `/apt:plan`.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (or current task worktree if `state.active_tasks[taskId].worktree_path` is set)
+- **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
+- **Handoff index:** `.aperant/HANDOFFS_INDEX.md`
+- **Sibling skills:** `/apt:pause` (human stop), `/apt:resume` (restore from CONTINUE *or* HANDOFF), `/apt:fan-out` (parallel peers)
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `AGENTS.md` — Project constitution
+- Active Aperant artifacts for the current task, if any:
+  - `{task_dir}/spec.md`, `{task_dir}/implementation_plan.json`, `{task_dir}/build-progress.json`
+  - `{task_dir}/qa_signoff.json`, `{task_dir}/review.json`
+  - `.aperant/debug/*/DEBUG.md`, `.aperant/quick/*/TASK.md`
+- Git state (branch, uncommitted changes, recent commits)
+- `.aperant/state.json` — active tasks, worktree paths
+
+**Writes:**
+- `{task_dir}/handoffs/{handoff-id}/HANDOFF.md` — if inside a routed task
+- `.aperant/handoffs/{handoff-id}/HANDOFF.md` — if ad-hoc work outside any task
+- `.aperant/HANDOFFS_INDEX.md` — index of all open handoffs
+
+**Does NOT touch:**
+- The git working tree. Handoffs are read-only against code. If there are uncommitted changes the sender intends the receiver to keep working on, reference them in the HANDOFF (path + status from `git status --short`) — do NOT stash. Stashing is `/apt:pause` semantics, not `/apt:handoff`.
+</state_files>
+
+<process>
+
+## 1. Determine Handoff Location
+
+Generate a handoff id: `handoff-{YYYYMMDD-HHMM}-{short-slug-of-next-focus}` (e.g. `handoff-20260522-1430-finish-mcp-token-rotation`).
+
+**If inside a routed task** (task_dir is known from the conversation, or `state.json` has an active task for the current branch):
+- Write to `{task_dir}/handoffs/{handoff-id}/HANDOFF.md`
+
+**If ad-hoc work** (manual coding, not routed through /apt):
+- Write to `.aperant/handoffs/{handoff-id}/HANDOFF.md`
+
+```bash
+mkdir -p {handoff_dir}
+```
+
+## 2. Gather Current State
+
+### 2a. Git State
+```bash
+git branch --show-current
+git status --short
+git log --oneline -5
+git stash list
+```
+
+### 2b. Active Aperant Artifacts
+Check and read status of any of: `implementation_plan.json`, `build-progress.json`, `qa_signoff.json`, `review.json`, `.aperant/debug/*/DEBUG.md`.
+
+### 2c. Conversation Context
+From the current conversation, extract:
+- What task was being worked on and the user's framing of why
+- Key decisions made + rationale (especially decisions NOT obvious from the diff)
+- What was tried, what worked, what failed and why
+- Live blockers and open questions
+- Any external state the receiver must check (running processes, deployed previews, CI runs, MCP server sessions)
+
+## 3. Write HANDOFF.md
+
+Create `{handoff_dir}/HANDOFF.md`:
+
+```markdown
+# Handoff: {one-line summary of what the next agent should focus on}
+
+## Session Info
+- **Date:** {ISO datetime}
+- **Sender:** {model + CLI, e.g. "Claude Opus 4.7 / Claude Code"}
+- **Suggested receiver:** {model + CLI hint, or "any agent"}
+- **Branch:** {current branch}
+- **Worktree:** {worktree_path if task-isolated, else repo root}
+- **Last commit:** {hash} — {message}
+- **Task ID:** {task-id, if routed task; else "ad-hoc"}
+
+## Focus For The Receiver
+{The single most important paragraph — what is the receiver supposed to DO next, in concrete terms. If the user passed args to /apt:handoff, that text drives this section.}
+
+## What Was Being Done
+{Plain-language description of the current activity and how it fits the broader task.}
+
+## Decisions Made (do NOT relitigate)
+- {decision 1} — {rationale}
+- {decision 2} — {rationale}
+
+## Existing Artifacts (read these, do not duplicate)
+- `{path or URL}` — {what it contains, why it matters}
+- `{path or URL}` — {what it contains, why it matters}
+
+> Reference paths and URLs instead of pasting content. PRDs, plans, ADRs, issues, commits, diffs, /apt:debug DEBUG.md, /apt:design DESIGN.md — link, don't copy.
+
+## Current State
+- **Pipeline stage:** {plan | execute | verify | review | debug | design | quick | none}
+- **Subtask progress:** {n}/{total} (if applicable, with the in-flight subtask id)
+- **Uncommitted changes:** {yes/no — list files, do not stash}
+- **External state the receiver must check:** {running dev servers, open PRs, MCP sessions, etc.}
+
+## Blockers
+- {blocker 1 — what's needed to unblock, and which file/person/check resolves it}
+- (none)
+
+## What Was Tried
+- {approach 1} — {outcome}
+- {approach 2} — {outcome}
+
+## Next Steps (ordered)
+1. {immediate next action}
+2. {following action}
+3. {…}
+
+## Suggested Skills
+Tell the receiver which Aperant skills are likely to fire next. Map verbs to the live `/apt:*` registry — do NOT invent skill names.
+
+- `/apt:resume` — first thing the receiver should run to load this handoff into context.
+- `/apt:execute` — if a plan exists and subtasks remain.
+- `/apt:debug` — if the open blocker is a reproducible bug without a known cause.
+- `/apt:spar` — if the next decision wants a second-LLM challenge before committing.
+- `/apt:plan` — if scope changed and the existing plan is stale.
+- (omit any that don't apply)
+
+## Redaction Checklist
+Before saving, scrub the HANDOFF for:
+- [ ] API keys, bearer tokens, OAuth secrets (Anthropic, Stripe, Convex, GitHub, etc.)
+- [ ] Database connection strings with passwords
+- [ ] Personally identifiable information not already in the repo
+- [ ] Internal URLs that should not leave the team
+```
+
+## 4. Update Handoff Index
+
+Update `.aperant/HANDOFFS_INDEX.md`. Create with this header if it does not exist:
+```markdown
+# Open Handoffs
+
+| Focus | Branch | Date | Suggested receiver | Location |
+|-------|--------|------|--------------------|----------|
+```
+
+Append one row:
+```
+| {focus (truncated to 60 chars)} | {branch} | {YYYY-MM-DD HH:MM} | {model hint or "any"} | {relative path to HANDOFF.md} |
+```
+
+If a row already exists for this handoff path, update it instead of appending.
+
+## 5. Report
+
+```
+Handoff written: {handoff_dir}/HANDOFF.md
+
+Summary:
+  Focus: {one-line}
+  Branch: {branch}
+  Pipeline stage: {stage}
+  Suggested next skill: {/apt:resume → /apt:{stage}}
+  Open handoffs: {total count from index}
+
+Receiver picks up with:
+  /apt:resume                # discovers this handoff via HANDOFFS_INDEX.md
+  OR read {handoff_dir}/HANDOFF.md directly
+```
+
+</process>
+
+<notes>
+## Why this skill exists separately from /apt:pause
+
+`/apt:pause` and `/apt:handoff` write the same shape of artifact but have different triggers and side effects:
+
+| | `/apt:pause` | `/apt:handoff` |
+|---|---|---|
+| Trigger | Human types it | Agent decides mid-work |
+| Audience | Future-you (same human) | A different agent |
+| Uncommitted work | Stashes via `git stash` | Does NOT stash — references in-place |
+| Index file | `.aperant/CONTINUE_INDEX.md` | `.aperant/HANDOFFS_INDEX.md` |
+| Artifact name | `CONTINUE.md` | `HANDOFF.md` |
+| Typical follow-up | Human runs `/apt:resume` hours/days later | Receiver agent runs `/apt:resume` immediately |
+
+Keeping the index files separate lets `/apt:resume` distinguish "the human stopped here" from "another agent dropped this in your lap" when presenting recovery options.
+
+## Receiver contract
+
+The receiver is expected to:
+1. Run `/apt:resume` (or read HANDOFF.md directly).
+2. Load the referenced artifacts (paths under "Existing Artifacts").
+3. Verify the listed external state still holds (e.g. dev server still running, PR still open).
+4. Delete the HANDOFF.md and its index row after picking up. `/apt:resume` handles the cleanup automatically; manual readers should do it themselves to keep `HANDOFFS_INDEX.md` from drifting.
+</notes>

package/dist/plugin/skills/apt-improve/DEEPENING.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/DEEPENING.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with the deletion-test priority
-rubric in Phase 2.
--->
-
 # DEEPENING — Domain-modeling depth lens
 
 This lens asks: **does this area model the domain at the right depth?**

package/dist/plugin/skills/apt-improve/INTERFACE-DESIGN.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with apt:review Pass 4's boundary
-audit semantics (this lens is proactive; Pass 4 is reactive).
--->
-
 # INTERFACE-DESIGN — Boundary-shape lens
 
 This lens asks: **are the boundaries between modules well-shaped?** Are

package/dist/plugin/skills/apt-improve/LANGUAGE.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/LANGUAGE.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with CONTEXT.md's aliases-to-avoid
-field — this lens reads that field to catch term conflations.
--->
-
 # LANGUAGE — Naming-consistency lens
 
 This lens asks: **does the codebase use the same word for the same

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

@@ -22,15 +22,15 @@ gates: []
 
 # Improve — Proactive Refactor Discovery
 
-Open question #2 in the Pocock adoption spec was answered concretely:
+Open question #2 in adoption spec was answered concretely:
 `apt:review` Pass 4 (architecture) is strictly **reactive** — it audits
 the current diff for boundary violations. The work-intent "look at this
 codebase and tell me what to refactor proactively" has no home today
 (users retrofit it onto `apt:discuss --brainstorm` or `/apt:roundtable`,
 both scope-mismatched). This skill is that home.
 
-**Pocock adoption attribution.** 3-phase workflow + DEEPENING /
-INTERFACE-DESIGN / LANGUAGE lenses ported from Matt Pocock's MIT-licensed
+**Aperant adoption attribution.** 3-phase workflow + DEEPENING /
+INTERFACE-DESIGN / LANGUAGE lenses ported from 
 `improve-codebase-architecture` skill. Aperant-specific: spawns the
 `apt-improver` agent and references `apt-discuss/appendices/grill-discipline.md`
 as the canonical source for the autonomy-aware deepening loop rather than
@@ -118,7 +118,7 @@ The deepening loop produces a concrete refactor plan (which becomes
 - `INTERFACE-DESIGN.md` — boundary-shape lens
 - `LANGUAGE.md` — naming-consistency lens
 
-All three are ported from Matt Pocock's improve-codebase-architecture
+All three are ported from 's improve-codebase-architecture
 skill with MIT attribution per AC15.
 
 ## Agent spawned

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

@@ -19,7 +19,7 @@ execution_modes:
   - plan-only
   - research
 allowed-tools: "Read, Grep, Glob, Write, Bash, WebSearch"
-argument-hint: "apt:plan [task description]"
+argument-hint: "apt:plan [task description] [--spar]"
 gates: 
   - constitution-read
   - constitution-coverage
@@ -33,7 +33,7 @@ Analyze a task, assess complexity, investigate the codebase, and produce a struc
 - **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
 - **Prompts directory:** Installed alongside this command in the @aperant/framework package
 - **Constitution:** Read `AGENTS.md` in the project root if it exists — it defines project principles, tech stack, and conventions that override defaults
-- **Task directory:** `{task_dir}` — passed from the router. All plan artifacts (spec.md, implementation_plan.json) are written here, NOT to project root.
+- **Task directory:** `{task_dir}` — passed from the router as an absolute main-repo path. All plan artifacts (spec.md, implementation_plan.json) are written here, NOT to project root and NOT to a worktree-local `.aperant/tasks/` directory.
 </your_environment>
 
 <state_files>
@@ -122,9 +122,9 @@ If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it
 
 ## 5. Write Specification
 
-Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `.aperant/tasks/{task-id}/spec.md`).
+Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `/abs/main/repo/.aperant/tasks/{task-id}/spec.md`). Do not use a relative `.aperant/tasks/{task-id}/spec.md` path when the agent is running in a worktree.
 
-**Content format branches on track (Fast Path Guarantee — Pocock adoption ID-05):**
+**Content format branches on track (Fast Path Guarantee — ID-05):**
 
 ### 5.A. QUICK track — legacy 4-section format (hard-exempt from PRD upgrade)
 
@@ -309,7 +309,7 @@ When `status: warn` (non-blocking enforcement) and the user is in **auto mode**
 
 Create `implementation_plan.json` in the task directory (`{task_dir}/implementation_plan.json`).
 
-**Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).**
+**Subtask schema branches on track.**
 
 ### 6.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 
@@ -454,6 +454,24 @@ Plan created:
 Next: /apt:execute
 ```
 
+### 9b. --spar flag (FRAMEWORK-RFC-001)
+
+If `$ARGUMENTS` contained `--spar`, dispatch `/apt:spar` against the
+just-written `spec.md` + `implementation_plan.json` before reporting Next.
+
+Topic frame: the §1 Scope paragraph from `spec.md` (1-2 sentences). Same
+`--timeout-ms 120000` pipeline-mode budget and NO `--rounds` flag (per
+FRAMEWORK-BUG-038 — pipeline gates always defer to the skill default).
+When merged-config `spar.partner` is set, append `--with <partner>`.
+
+```
+/apt:spar --timeout-ms 120000 [--with <partner>] <topic-frame-from-spec.md-§Scope>
+```
+
+After spar returns, append the termination headline + Layer 2 path
+(`.aperant/spar/<slug>-<ts>.md`) into the report output so the user can
+review findings before invoking `/apt:execute`.
+
 ### 9a. Mode-Aware Compact Suggestion (Human-in-the-Loop Only)
 
 Decide whether to show a compact suggestion by reading the **per-task autonomy** from state — not the global default, because the router asks per-task and stores the answer on the task record.

package/dist/plugin/skills/apt-plan/adapters/conductor.md

@@ -42,7 +42,7 @@ auto-stamped `terminal_id`.
 
 This replaces the earlier markdown-discipline emit step. The earlier
 step was correctly skipped on QUICK / SIMPLE classified tasks (Fast
-Path Guarantee, Pocock adoption ID-05) — moving the emit to a
+Path Guarantee, ID-05) — moving the emit to a
 framework postcondition makes it work uniformly across QUICK, STANDARD,
 DEEP, and COMPLEX without violating the Fast Path Guarantee.
 

package/dist/plugin/skills/apt-pr-review/SKILL.md

@@ -1110,6 +1110,8 @@ For `AUTHORSHIP_MODE == "owned"`, continue normally.
 
 AI agents have near-zero marginal cost per fix. The framework fixes **all** confirmed findings — critical, high, medium, and low — regardless of autonomy level. There is no severity gate and no "report for manual resolution" path. If a finding was confirmed by the validator, it gets fixed.
 
+**Hard rule — context budget is NOT a valid skip reason.** The orchestrator MAY NOT defer, drop, downgrade, or "punt for follow-up" any confirmed finding because its own context window feels heavy, because the run has already produced many fixes, or because it judges marginal value low. The query loop auto-compacts on its own — trust it. Per-finding fix work happens inside fix agents (separate context windows), so orchestrator pressure does not justify cutting their inputs. The only valid skip reasons are the ones enumerated in Key Principle #2 (`fixable: false`, critical finding without user approval, file assigned to another fixer). Any other skip is an unauthorized policy deviation — emit all confirmed findings to fixers, then let the audit gate adjudicate outcomes.
+
 | Autonomy | Action |
 |----------|--------|
 | `< 2` | Show findings summary before fixing. Then proceed with auto-fix. |
@@ -1647,7 +1649,7 @@ node packages/framework/bin/apt-tools.mjs workflow destroy . --id ${REVIEW_ID}
 Agents do NOT assign confidence percentages. Either they have evidence (actual code snippet from Read tool) or they do not have a finding. The validator independently verifies every finding against real code.
 
 ### 2. Fix Everything Found
-If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
+If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. **Neither is "my context window is heavy" or "I've already done a lot this run"** — orchestrator context pressure never authorizes dropping a confirmed finding (see Phase 6 → Principle: Fix Everything). The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
 
 ### 3. Findings Flow Through Files
 Agents write to `.aperant/pr-reviews/{review-id}/findings/`. The orchestrator reads with the Read tool. Fix agents read finding files directly. This keeps the orchestrator context under 30%.
@@ -1711,6 +1713,11 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 **Wrong:** Skipping Phase 6 entirely when autonomy < 2.
 **Right:** Always fix all confirmed findings. At autonomy < 2, show findings summary first, then proceed with auto-fix. The only difference is whether findings are displayed before fixing — not whether they get fixed.
 
+### Mistake 7a: Dropping Findings Because Orchestrator Context Feels Heavy
+
+**Wrong:** Mid-Phase-6, the orchestrator decides "my window is getting heavy after 6 specialist rounds + Round 1 fixes — I'll skip the minor findings and report a partial fix." This is an unauthorized policy deviation, even when phrased as "judgment call" or "context-budget reasons."
+**Right:** Spawn fix agents for **every** confirmed finding regardless of orchestrator context state. Fix work happens in the fixer's window, not yours. The query loop auto-compacts when it needs to — trust it. If you genuinely cannot fit the spawn calls, that is a framework bug to file (not a license to ship a partial fix); emit all findings to fixers in the smallest batches possible and let the audit gate adjudicate. Severity, "diminishing returns," and your own token pressure are NOT skip authorities — only the three reasons in Key Principle #2 are.
+
 ### Mistake 8: Forgetting to Update metadata.json
 
 **Wrong:** Writing review.json but leaving metadata.json stuck at `"status": "in-progress"`.

package/dist/plugin/skills/apt-prototype/LOGIC.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/LOGIC.md
-Licensed under MIT. Modifications: scoped to terminal-app prototypes
-that validate state machines, protocols, and control flow. Aligned with
-the 5 universal rules in apt-prototype/SKILL.md.
--->
-
 # LOGIC branch — Terminal app for state-machine validation
 
 When the user's question is about **behavior**, the prototype is a

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

@@ -29,7 +29,7 @@ planning artifact, NOT a feature, and NOT something to merge. The output
 is a single-command-runnable prototype that lets the user feel whether
 the question's answer is "yes" or "no", then gets thrown away.
 
-**Pocock adoption attribution.** Discipline ported from Matt Pocock's
+**Aperant adoption attribution.** Discipline ported from 's
 MIT-licensed `prototype` skill. Routes between two branches by
 question-type; the UI branch delegates to Aperant's existing
 `/apt:mockup` skill for HTML+Tailwind variants. The LOGIC branch and
@@ -70,7 +70,7 @@ If the question is genuinely ambiguous, ask ONE clarifying question
 ("are you asking about behavior or appearance?") — do NOT enter a long
 interview.
 
-## The 5 Universal Rules (Pocock discipline, applies to both branches)
+## The 5 Universal Rules (Aperant discipline, applies to both branches)
 
 These five rules apply to EVERY prototype this skill produces. They are
 load-bearing — violating them collapses the prototype into ceremony
@@ -109,7 +109,7 @@ disguised as a question.
 When the question is about behavior / control flow / state machines /
 protocols:
 
-1. Read `LOGIC.md` for the discipline (ported from Pocock's
+1. Read `LOGIC.md` for the discipline (ported from 's
    `prototype/LOGIC.md` with MIT attribution).
 2. Write ONE file (e.g., `prototype.mjs`, `prototype.ts`, or
    `prototype.py`) that:
@@ -126,7 +126,7 @@ protocols:
 
 When the question is about layout / aesthetics / flow / discoverability:
 
-1. Read `UI.md` for the discipline (ported from Pocock's
+1. Read `UI.md` for the discipline (ported from 's
    `prototype/UI.md` with MIT attribution).
 2. Invoke `/apt:mockup --variants 3` as a sub-step. apt:mockup already
    enforces the UI-specific universal rules (zero-dep Tailwind CDN, no

package/dist/plugin/skills/apt-prototype/UI.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/UI.md
-Licensed under MIT. Modifications: routed through Aperant's existing
-apt:mockup skill rather than a freestanding HTML+Tailwind generator;
-aligned with the 5 universal rules in apt-prototype/SKILL.md.
--->
-
 # UI branch — Delegates to apt:mockup
 
 When the user's question is about **appearance / layout / flow /

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

@@ -52,7 +52,37 @@ Execute a small task quickly without full pipeline overhead. For small fixes, do
 
 Extract the task description from `$ARGUMENTS`.
 
-Generate a task ID: `quick-{YYYYMMDD}-{short-slug}` (e.g., `quick-20260410-fix-typo`).
+### 1a. Resolve canonical task id (idempotent)
+
+QUICK now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile. The body owns idempotency because `apt-tools task create` does NOT guard against existing ids (see spec §3 R8).
+
+Two invocation paths converge here:
+
+- **Router path** (`/apt` → `/apt:quick`): the router has already called `task create` and injected `task_id` into your skill context.
+- **Direct path** (`/apt:quick foo`): no `task_id` in context — you create one now.
+
+Sequence:
+
+1. **If `task_id` is present in skill context** (router path):
+   ```bash
+   apt-tools task get . --id {task_id}
+   ```
+   - If exit 0 AND the returned record has `track === "QUICK"` → reuse, skip the create call.
+   - Else (record missing OR wrong track) → call:
+     ```bash
+     apt-tools task create . --description "$ARGUMENTS" --track QUICK --id {task_id}
+     ```
+     Parse `task_id` from the returned envelope (it will match the id you passed).
+
+2. **If no `task_id` in skill context** (direct path):
+   ```bash
+   apt-tools task create . --description "$ARGUMENTS" --track QUICK
+   ```
+   Parse the generated `task_id` from the envelope — it will be the canonical `{slug}_YY-MM-DD` shape.
+
+The task id is now canonical (no more `quick-YYYYMMDD-*` invention). `QuickTaskSchema` accepts both the canonical `{slug}_YY-MM-DD` form and the legacy `quick-YYYYMMDD-{slug}` form for back-compat with already-shipped task records on disk.
+
+### 1b. Create QUICK working directory
 
 ```bash
 mkdir -p .aperant/quick/{task-id}