Ovid On invocation: announce "Running paad:paad-help v1.31.0-preview", then immediately proceed with the steps below — do not stop after announcing.
paad Help
Show help for paad skills. If $ARGUMENTS matches a skill name, show detailed help for that skill. Otherwise, show the overview.
Arguments
/paad-help— show all available skills/paad-help vibe— show detailed help for a specific skill/paad-help agentic-review— skill names with hyphens work too
Behavior
If $ARGUMENTS is provided and matches a skill name (with or without the paad: prefix), show the detailed help for that skill only. If the argument doesn't match any skill, say "Unknown skill: [name]. Available skills:" and show the overview.
Do NOT read files or run commands. All help text is below.
Common Mistakes
| Mistake | What to do instead |
|---|---|
| Paraphrasing or summarizing the help text | Display the blocks verbatim. Arguments and output paths are exact; a paraphrase invents flags that don't exist. |
| Answering for a skill not listed here | If it isn't below, it isn't a paad skill. Say "Unknown skill: [name]" and show the overview. |
| Running the skill the user asked about | They asked what it does, not for it to happen. Show the help and stop. |
Overview (no arguments)
When showing the overview, display exactly this:
paad — Engineering-driven AI.
Use your engineering excellence — the one thing AI reliably skips.
Full tutorial: https://curtispoe.org/paad/
Available skills:
/agentic-a11y [path] Accessibility audit (web, mobile, desktop, CLI, games)
/agentic-architecture [path...] Multi-agent architecture analysis (strengths & flaws)
/fix-architecture [report] Fix architectural flaws from an analysis report
/agentic-review [base-branch] [path] Multi-agent code review of current branch (bug hunting)
/alignment [files...] Requirements-to-tasks alignment + TDD rewrite
/makefile Create or update a Makefile with standard targets
/pushback [document] Spec/PRD/doc critic (finds issues before you build)
/vibe [task description] Safe vibe coding with TDD guardrails
Experimental — may change or be withdrawn in any release, including patches:
/backlog [clean|fix] Clean or fix the out-of-scope bug backlog
/agentic-dedup [scope] Find semantic duplication (same meaning, different code)
/agentic-owasp [scope] Security review against the OWASP Top 10:2025
/handoff [save|resume] Hand this session's work to a fresh session, in writing
/rethink [what to re-examine] Verify the premises under options already on the table
/test-roadmap Plan and build a test suite that catches real regressions
Picking between them:
Want structural flaws found? agentic-architecture (diagnoses, does not fix)
Want them fixed? fix-architecture (needs a report first)
Want bugs in a branch? agentic-review (a diff, not the codebase)
Have a backlog of found bugs? backlog (experimental; clean stale
entries, or fix the next one —
agentic-review fills it)
Want accessibility barriers? agentic-a11y (not general correctness)
Want duplicated logic found? agentic-dedup (experimental; reports,
never refactors)
Worried about security specifically? agentic-owasp (experimental; the OWASP
Top 10:2025, never exploits or fixes)
Have no tests, or tests you distrust? test-roadmap (experimental; the only
skill that writes and commits code)
Have one document, is it any good? pushback (a spec, a steering file, a
generated report)
Been handed options, are they sound? rethink (experimental; checks premises,
does not invent alternatives)
Out of context, work unfinished? handoff (experimental; writes a file for
a NEW session — /compact stays in this one)
Have a spec AND a plan, do they match? alignment (needs both; does not read code)
Making a small change? vibe (1-3 files, same module)
Change is clearly multi-module? write a plan, then alignment against it
Build is broken? none of these — makefile manages targets,
it does not debug builds
Run /paad-help <skill-name> for detailed help on a specific skill.
Invoking: the names above are slash commands on Claude Code. If your
assistant does not take them, ask for the skill by name ("run the pushback
skill"). If another plugin ships a skill with the same name, disambiguate with
the paad: prefix — /paad:vibe rather than /vibe.
Detailed Help (per skill)
agentic-a11y
/agentic-a11y [path]
Comprehensive multi-agent accessibility audit of user-facing code.
Supports: web, iOS, Android, React Native, Flutter, desktop, CLI, and games.
Target: WCAG 2.2 AA baseline, AAA flagged as bonus recommendations.
Output: paad/a11y-reviews/
Arguments:
/agentic-a11y Audit all user-facing code in the repo
/agentic-a11y src/components/ Scope to a directory
/agentic-a11y Modal.tsx Scope to a file
What it does:
1. Detects the platform(s) automatically
2. Dispatches 5 specialist agents in parallel:
- Screen Reader & Assistive Tech
- Visual & Color
- Keyboard & Motor
- Cognitive & Learning
- Multimedia & Temporal
3. Dispatches a Platform-Specific agent if a framework is detected
4. Verifies findings (filters false positives from component libraries)
5. Writes a report with:
- Impact summary by user group
- Issues ranked by severity (Critical/Serious/Moderate/Minor)
- WCAG conformance checklist
- Quick wins (top 5 highest-impact, lowest-effort fixes)
Best used in a fresh session — consumes significant context.
agentic-architecture
/agentic-architecture [path...]
Multi-agent architecture analysis. Diagnosis only — finds strengths and
flaws with evidence but does not propose fixes.
Output: paad/architecture-reviews/
Arguments:
/agentic-architecture Full repo
/agentic-architecture src/ Scope to a directory
/agentic-architecture packages/api/ packages/shared/ Multiple dirs
What it does:
1. Reconnaissance: repo overview, dependency snapshot, steering files
2. Dispatches 5 specialist agents in parallel:
- Structure & Boundaries (god objects, cohesion, domain modeling)
- Coupling & Dependencies (tight coupling, circular deps, abstractions)
- Integration & Data (API contracts, data ownership, resilience)
- Error Handling & Observability (error strategy, logging, config)
- Security & Code Quality (auth, secrets, dead code, test coverage)
3. Verifies findings (reads actual code, checks git history)
4. Writes a report with:
- 14 strength categories assessed
- 34 flaw/risk types assessed
- Coverage checklist (every category: observed / not observed / N/A)
- Hotspots (top 3 files/directories to review)
- Next questions (max 5, no solutions)
Best used in a fresh session — consumes significant context.
fix-architecture
/fix-architecture [report]
Guided fixing of architectural flaws from an agentic-architecture report.
Test-first workflow with developer approval at every step.
Output: Updates the report in paad/architecture-reviews/ with fix status
Arguments:
/fix-architecture Find most recent report
/fix-architecture path/to/report.md Use a specific report
Requirements:
- Must be on a feature branch (not main/master/trunk)
- An architecture report must exist (run /agentic-architecture first)
What it does:
1. Pre-flight: branch check, report staleness, test infrastructure,
baseline test run
2. Developer conversation:
- Solo or team? (affects batch size recommendations)
- Auto-commit or manual review?
- Flaw triage: high-impact, quick wins, or specific F-IDs
- Plan confirmation before any code is touched
3. For each selected flaw:
- Validates the flaw still exists (checks code and git history)
- Assesses test coverage, writes safety-net tests if needed
- Proposes fix options with tradeoffs (recommended option first)
- Executes with red/green/refactor
- Handles test failures (distinguishes structural vs behavioral)
- Commits (one per fix) and updates the report
- Checks if the fix resolved other flaws too
4. Post-session summary with remaining flaw count
Status tracking in the report:
Fixed | Won't fix | Partially fixed | Skipped |
Fixed (pre-existing) | Attempted, reverted
Best used in a fresh session — consumes significant context.
agentic-review
/agentic-review [base-branch] [path]
Multi-agent bug-hunting code review of the current branch.
Output: paad/code-reviews/<branch>-<timestamp>-<short-sha>.md (per-review)
paad/code-reviews/backlog.md (project-wide, persistent)
Arguments:
/agentic-review Diff against the default branch
/agentic-review develop Diff against a different branch
/agentic-review main src/auth/ Scope to a directory
One argument is read as a base branch if git can resolve it, otherwise
as a path if it exists on disk. If it is both -- "docs", "release",
"test" and "api" are ordinary names for either -- the skill stops and
asks rather than guessing.
Requirements:
- Must be on a feature branch (not the repository's default branch,
resolved from origin/HEAD, falling back to main/master/trunk)
- Uncommitted changes: asks whether to review the committed state or wait
Stops before reviewing when:
- The base branch does not resolve
- A path filter was given and does not exist
- An argument is neither a ref nor a path, or is ambiguously both
- An argument holds a character git could read as a flag
- The default branch cannot be determined at all
- The filtered diff is empty
What it does:
1. Reconnaissance: diff stats, file manifest, callers/callees
2. Dispatches 6 specialist agents in parallel:
- Logic & Correctness
- Error Handling & Edge Cases
- Contract & Integration
- Concurrency & State
- Security
- Spec Compliance — pulls intent from PR description, plan/design
docs, recent commits, or branch name; flags missing features,
deviations, and out-of-scope additions (replaces the older
Plan Alignment agent)
3. Verifies findings (reads actual code, filters false positives)
4. Classifies each finding as in-scope (this branch caused/worsened it),
out-of-scope (pre-existing bug — persists to project-wide backlog),
or out-of-scope-addition (this branch added it but the spec didn't
promise it — flagged for per-PR user decision)
5. Writes a report with:
- In-scope issues ranked: Critical / Important / Suggestion
- Out-of-scope bugs batched by tier with handoff instructions
- Out-of-scope additions in a separate section for keep/split/revert
decisions (no backlog persistence)
- Each finding: file:line, bug, impact, suggested fix, confidence,
and the model that found it
- Backlog updates surfaced in metadata
Best used in a fresh session — consumes significant context.
backlog
/backlog [clean|fix] EXPERIMENTAL
EXPERIMENTAL — arguments, modes, and behavior may change or be withdrawn in
any release, including patch releases.
Work the project-wide out-of-scope bug backlog that /agentic-review writes
to. Two modes, one flat file. Never commits — it edits files and prints the
commit command for you to run.
Input/output: paad/code-reviews/backlog.md (the file /agentic-review fills)
Arguments:
/backlog List the entries, then show the two-option menu
/backlog clean Go straight to Clean mode
/backlog fix Go straight to Fix mode
Requirements:
- A populated paad/code-reviews/backlog.md. If it is missing or empty,
the skill says so and points you at /agentic-review.
Clean mode:
1. One skeptical read-only analyst per entry re-verifies it against the
current code: STILL-PRESENT / RESOLVED / GONE, each with cited evidence
2. Deletes only RESOLVED/GONE entries — any doubt keeps the entry. A
renamed or moved symbol is not treated as a fix
3. Dedupes/merges any duplicate survivors (rare — agentic-review dedupes
at mint time)
4. Prints a git commit command with the resolution notes; does not run it
Fix mode:
1. Ranks entries by severity then age, proposes the top one, you pick
(one item per run — no batch-fixing)
2. Fixes the bug directly or via /vibe
3. Validation gate before removal: an INDEPENDENT read-only analyst must
confirm from the code that the bug is gone; project tests run if a
command exists. No test command means "validated by inspection only" —
never a pass on its own, and your own edit is never the evidence
4. Gate passes -> deletes the entry and prints the commit command;
gate fails -> keeps the entry and reports what is still wrong
Deleting a backlog entry destroys a record, so the skill leans conservative:
a wrongly-kept entry is one stale line, a wrongly-deleted one loses a real
bug (recoverable only from git log on the file).
alignment
/alignment [files...]
Checks that requirements and implementation plans are aligned.
Rewrites all tasks in TDD red/green/refactor format (mandatory).
Output: paad/alignment-reviews/
Arguments:
/alignment Auto-detect documents
/alignment requirements.md plan.md Specific files
/alignment docs/specs/ docs/plans/ Directories
Auto-detection scans: .kiro/, specs/ (spec-kit), docs/plans/, docs/specs/,
common filenames, and conversation history.
What it does:
1. Classifies documents as intent (requirements) vs action (tasks)
2. Reality check: scans git history for conflicts
3. Three alignment checks:
- Requirements coverage (every requirement has tasks?)
- Scope compliance (every task maps to a requirement?)
- Design alignment (if design docs exist)
4. Presents issues one at a time, dependency-ordered:
- Missing requirements first (root causes)
- Design gaps second
- Missing/orphaned tasks last (symptoms)
5. Rewrites all tasks in red/green/refactor format
6. Updates documents or writes a separate report
Works within an existing conversation — no fresh session needed.
makefile
/makefile
Creates or updates a project Makefile with standard targets.
Arguments:
/makefile Create a new Makefile or update an existing one
What it does:
1. Detects your stack (reads CLAUDE.md, README, package.json, etc.)
2. Checks if a Makefile already exists
3. Creating: builds from scratch with all required targets
4. Updating: adds missing targets; asks before changing existing ones
Required targets (always included):
help List all targets with descriptions
all Full CI pass (lint + format + test)
test Run test suite
cover One-shot coverage report
lint Lint (with autofix if available)
format Format code
Extra targets (build, dev, preview, etc.) added only if the project
supports them.
Key rules:
- Never modifies an existing target without explicit approval
- Forces one-shot mode for coverage (no watch-mode hanging)
- Uses self-documenting pattern (## comments + grep/awk help target)
- Balanced test output: concise on success, detailed on failure
No fresh session needed — this is a lightweight workflow skill.
pushback
/pushback [document]
Critically reviews a spec, PRD, or design before you start building —
or any document that makes claims about the code, such as an agent
steering file (CLAUDE.md, AGENTS.md) or a generated analysis report.
Every finding must name a concrete consequence and the mechanism behind
it; candidates that can't are dropped and reported as discards. Each
finding also names the off-disk fact that would change its severity —
or says it is unconditional.
Output: the conversation, plus your spec if you ask for edits.
Writes paad/pushback-reviews/ only when issues go undiscussed
or you ask for a report.
Arguments:
/pushback path/to/spec.md Review a specific file
/pushback Auto-detect from conversation or files
Auto-detection checks: conversation history first, then common locations
(docs/plans/, docs/specs/, requirements.md, PRD.md, spec.md), then agent
steering files (CLAUDE.md, AGENTS.md, .cursorrules, .kiro/steering/,
.github/copilot-instructions.md) and generated analysis (paad/*-reviews/).
What it does:
1. Reality check: scans git history for conflicts with what the
spec assumes (presented upfront — showstoppers first)
2. Scope shape check:
- Feature cohesion: flags unrelated features bundled together
(things that would be separate PRs)
- Spec size: flags oversized specs, suggests splits only when
each piece delivers independent value
3. Analyzes the spec across 6 categories:
- Contradictions
- Feasibility (given the current codebase)
- Scope imbalance
- Omissions
- Ambiguity
- Security concerns
4. Presents issues one at a time, most impactful first
5. For each: concrete options from best to worst, with recommendation
6. Stop when you say "good enough"
7. Updates the spec or writes a separate report
Works within an existing conversation — no fresh session needed.
rethink
/rethink [what to re-examine] EXPERIMENTAL
Independently verifies the premises under options that are already on
the table. Reports what it checked, and how it checked it.
Experimental: arguments, verdicts, and output shape may change — or the
skill may be withdrawn — in any release, including a patch release.
Output: none — it speaks in the conversation and writes no files.
Arguments:
/rethink Re-examine the most recent option set
/rethink the caching approach Name which decision, if several are live
What it does:
1. Extracts every premise the recommendation depends on, including
the unstated ones, and sorts them:
- checkable now (a primary source exists)
- checkable by experiment (names the cheapest one)
- not checkable (judgment, taste, prediction)
2. Dispatches one read-only subagent to verify them against
PRIMARY sources — the software, not its documentation
3. Reports one of five verdicts:
- Sound premises hold, and were checked
- Lucky premises hold, but nobody checked them
- Wrong reason a premise is false, the conclusion survives
- Premise false a premise is false, the conclusion does not
- Ungrounded unsettleable; names the experiment that would settle it
4. Per premise: what was claimed, what was found, what was checked
5. Re-presents the options in plain language — no jargon, no internal
names — with pros AND cons for each, and says what verification
changed about their standing
6. Recommends one, with the reason. Where the call also turns on
something it cannot see — a deadline, headcount, an unshipped
roadmap — it still recommends, then names that input and what it
would flip the answer to. It withholds entirely only when the
evidence supports no default at all
What it deliberately does NOT do:
- Produce an option list. It is not pushback. It proposes an
alternative only when verification exposed a defect, and then
exactly one, tied to that defect.
- Write, edit, or create any file.
Use it when a choice rests on cited docs, remembered behavior, or
premises nobody tested. Not for critiquing a spec — that is pushback.
vibe
/vibe [task description]
Safe vibe coding. Quick fixes with TDD guardrails.
Arguments:
/vibe fix the login timeout Task description inline
/vibe Ask what needs fixing
What it does:
1. Understands the task (asks clarifying questions if needed)
2. Pre-flight checks:
- Test infrastructure exists?
- Scope check (4+ files = warning)
- Architecture smell (simple task but hard work = investigate)
- Reusable components (search before building from scratch)
3. Implements with mandatory red/green/refactor:
- RED: one failing test first — a new one, or an existing test
updated to the new expectation (stop if unexpected behavior)
- GREEN: write minimal code to pass
- REFACTOR: clean up duplication, hard-coded values, patterns
4. Post-fix summary with contextual follow-up suggestions:
- Security-sensitive code → /agentic-review
- UI changes → /agentic-a11y
- Harder than expected → /agentic-architecture
No fresh session needed — this is a lightweight workflow skill.
agentic-dedup
/agentic-dedup [scope]
EXPERIMENTAL — arguments, output paths, and behavior may change or be
withdrawn in any release, including patch releases.
Multi-agent hunt for semantic duplication: code that means the same thing
behind different names, different syntax, different control flow, or
independently evolved implementations. Not a syntactic clone detector.
Output: paad/dedup-reviews/<branch-or-scope>-<timestamp>-<sha>.md
paad/dedup-reviews/INDEX.md (persistent, newest run on top)
Arguments:
/agentic-dedup Scan the repository
/agentic-dedup src/auth/ Scope to a path or module
/agentic-dedup --changed main Seed from the diff against main
/agentic-dedup --type-constraints Schemas, type aliases, validators
/agentic-dedup --domain "payments" Scope to a domain term
What it does:
1. Reconnaissance: manifest grouped by semantic domain, not by extension
2. Candidate discovery via six strategies: name/concept search,
behavioral fingerprints, type & constraint equivalence, control-flow
normalization, tests as behavioral specs, canonical utility search
3. Dispatches 5 specialist agents in parallel:
- Semantic Equivalence
- Type & Constraint Equivalence
- Domain Boundary & Intent
- Divergence Risk
- Refactoring Safety
4. Verifies findings — rejects name-only, shape-only, and structural
matches, and anything where duplication is the safer choice
5. Writes a report with:
- Findings ranked Critical / Important / Suggestion
- Type and constraint equivalence table (exact/overlap/subset/drift)
- Rejected candidates, so the next run does not rediscover them
- A consolidation strategy with a safe migration sequence
Never refactors anything. The report is the deliverable.
Best used in a fresh session — consumes significant context.
agentic-owasp
/agentic-owasp [scope]
EXPERIMENTAL — arguments, output paths, and behavior may change or be
withdrawn in any release, including patch releases.
Multi-agent security review of source code against the OWASP Top 10:2025.
Reads code. Never starts the app, never sends a request anywhere, never
writes exploit code, never fixes what it finds.
Output: paad/owasp-reviews/<branch-or-scope>-<timestamp>-<sha>.md
paad/owasp-reviews/INDEX.md (persistent, newest run on top)
Arguments:
/agentic-owasp Review the repository
/agentic-owasp src/api/ Scope to a path or module
/agentic-owasp --changed main Seed from the diff against main
/agentic-owasp --category A01 One category, or A01,A05,A07
/agentic-owasp --deps Supply chain only: deps, CI/CD
What it does:
1. Reconnaissance: framework defaults first — the ORM, template engine,
and middleware decide which findings are even real
2. Attack surface mapping: untrusted sources, dangerous sinks, and the
controls already sitting between them, each with path:line.
Then, before specialists launch, an optional benign-execution offer:
with your explicit yes, specialists may run read-only in-process
probes — your existing tests, a deparse, a pure-function call on
ordinary input — to settle questions reading cannot. Never a payload,
never a server or network, never a write; a separate decision from the
proof stage below, and off unless you say yes
3. Dispatches 7 specialist agents in parallel. Six cover all ten
categories with none left over:
- Access Control & Authentication (A01, A07)
- Injection & Untrusted Input (A05)
- Cryptography & Data Protection (A04)
- Configuration & Supply Chain (A02, A03)
- Design, Integrity & Failure Modes (A06, A08, A10)
- Logging, Alerting & Detection (A09)
The seventh owns no category and hunts by mechanism instead:
- Mechanism & Round-Trip (the seams)
Round-trip asymmetry between paired APIs, and facts the code
stores twice where a control reads only one copy. Files its
findings under the category of the impact.
4. Exploitability gate: a finding must name an attacker-controlled
source, a traced path to the sink, and why the existing controls do
not hold. Anything that cannot becomes a hardening note or is rejected.
The verifier's job is to refute, not confirm, and it clears a control
by enumerating the callers that bypass it — not by reading where the
control lives, and it composes across specialists before rejecting —
each specialist reports out-of-category observations as fragments, so a
weakness split across two categories is not lost by both
5. Optional proof stage: where a sink is reachable in-process, offers to
write a standalone script per finding that exits 0 while the weakness
is open, worked down the severity order rather than by whichever
proof looks easiest. Always asks first, with the trade-offs; never
executes without a yes. Declining costs nothing — unproven findings
keep their severity, and each says why it went unproven
6. Writes a report with:
- Coverage table across all ten categories — "not assessed" is
stated, never passed off as clean
- Findings ranked Critical / High / Medium, hardening notes separate
- Dependency findings marked called vs present-but-unreachable
- Every pooled fragment listed individually — path:line, what the
specialist saw, where it ended up — not just a count, so a sink
that was seen and dropped stays distinguishable from one nobody
looked at once the session is gone
- Rejected candidates, each with the positive evidence that killed
it, so the next run does not rediscover them
- A remediation order, which is not severity order
Live credentials are reported by location and type only — never by value,
and rotation comes before anything else in the report.
No report is a complete list of the weaknesses in the code, and the skill
says so at the end of every run — along with why committing the report is
risky even after the findings are fixed: git history is permanent, the
report ages into a false clearance, and the caveats do not travel with the
severity table. Zero findings means one reviewer looked once inside ten
categories and could not prove a path — not that the code is secure. Two
runs find different things, and the larger the codebase the wider the gap,
so union two runs rather than diffing them. Severity states impact;
whether a finding was executed is a separate field and never lowers it.
Scope is gated on size. Past roughly 40 source files the skill stops and
offers a choice: narrow to the untrusted-input surface, split into separate
subsystem passes, or take one wide pass with the dilution recorded in the
report. Breadth costs depth, and it costs it silently — a wide run returns a
different result rather than a shallower one, often reporting more findings
overall while missing a weakness a narrow pass over the same file finds
every time. Prefer several scoped runs to one repository-wide sweep.
Best used in a fresh session — consumes significant context.
test-roadmap
/test-roadmap
EXPERIMENTAL — arguments, output paths, and behavior may change or be
withdrawn in any release, including patch releases. This is the only paad
skill that writes and commits code.
Builds a test suite that catches real regressions, in phases, across as
many sessions as it takes. One command on day 1 and on day 90.
Run it once to get a roadmap, then KEEP RUNNING IT — one phase of tests
per run — until it tells you the roadmap is finished. A 14-phase roadmap
takes 15 invocations. Running it once leaves you with a plan and no
tests.
Output: paad/test-roadmap/test-roadmap.md (the roadmap, and the memory)
Tests, committed one phase per commit, on your working branch
Arguments:
/test-roadmap No arguments — the roadmap file decides the mode
Requirements:
- A git checkout (bug injection runs in a disposable git worktree)
- A working branch, not main/master/trunk — it offers to make one
What it does:
Routing is one check: does paad/test-roadmap/test-roadmap.md exist?
Absent → BUILD mode, five stages:
1. Detect — stack, test runner, and existing tests from manifests,
never from a hardcoded language list
2. Grade — fan-out subagents grade existing tests for weakness and
classify mocks (see the test-theater catalog)
3. Plan — phases, each naming the bug it would catch
4. Critique — a phase that cannot name its bug is coverage theater
and gets rewritten or dropped
5. Write — the roadmap, including the decisions you settled
Present → EXECUTE mode, one phase per run:
- Writes that phase's tests
- break-it-check: injects the very bug the phase claims to catch,
in a throwaway worktree, and confirms the test goes red
- Runs your whole suite, once normally and once under coverage;
will not call a phase done while the run is noisy
- Commits the phase and marks it done
- Ends by telling you where you are (Phase 8 of 14 — 7 done, 6 to
go) and to run it again, until no phases remain
Logs concrete bugs it finds along the way. It never fixes them.
Best used in a fresh session — consumes significant context.
handoff
/handoff [save|resume] EXPERIMENTAL
Writes a handoff.md that lets a FRESH session continue this one's
work, and reads it back on the other side.
Experimental: arguments, file format, and behavior may change — or the
skill may be withdrawn — in any release, including a patch release.
Output: handoff.md in the working directory. Suggests you gitignore it.
Arguments:
/handoff Infer: history above → save, empty session → resume
/handoff save Write a handoff regardless
/handoff resume Read the existing handoff regardless
Why not just /compact:
/compact summarizes and keeps working — same session, and the
summary is machine-written, unreviewed, and buried in
the transcript where you cannot edit it
--resume restores the whole prior conversation, re-paying the
context cost you were escaping
/clear genuinely fresh, carries nothing forward
handoff a file a human reads and corrects BEFORE anything is
built on it
That review is the only thing it adds. A handoff nobody reads is a
worse /compact.
Saving:
1. Checks .gitignore for handoff.md and suggests adding it —
never edits .gitignore itself
2. Verifies with tools what agents get wrong from memory:
commit and branch, what is really IN the last commit (not what
its message claims), file paths, line numbers, test names,
whether the suite passes. Unsettleable claims are marked
inferred, not asserted
3. Writes the file: goal and what done looks like, decisions and
why, approaches ruled out and how far they got, constraints the
user stated, the next step, the verify command
NOT: architecture tours, session narrative, anything git diff
already shows — padding makes the file too long to review
4. Names the two or three claims it is least sure of, instead of a
generic "review this, AI makes mistakes"
Resuming:
1. Reads handoff.md, summarizes it in a few lines
2. Compares the recorded commit against HEAD and reports drift
3. Asks before proceeding
4. Confirms the files and state it names still exist, reports every
mismatch, asks again
5. Then starts the recorded next step
Never deletes handoff.md — it is untracked, so git cannot restore
it. The next save overwrites it.