sharpy / analysis

v2 2026-04-18 ← cheatsheet proposal → source

design philosophy

Commands exist to make sharpy's behaviour legible and terminal-friendly. Every command has a single job, a declared access level, and a predictable tool budget. The framework optimizes for recoverability (nothing silently lost), reversibility (destructive ops gated), and cost transparency (you can plan around a budget).

Categories are not arbitrary. They map to state-machine position (lifecycle), classification vs. action (persistence), meta/hygiene (maintenance), multi-conversation coordination (orchestration), and the one external workflow heavy enough to earn its own category (review).

conversation state machine

                               /kill  (auto /reap if UNPERSISTED)
             ┌───────────────────────────────────▶ DEAD ◀─────────────┐
             │                          /kill!  (bypass)              │
   ALIVE ────┼── /rite     (classify, read-only)                      │
             │                                                        │
             └── /reap     (act on /rite; auto-halts on low-conf)     │
                                                                      │
                                                            /resurrect
                                                    (spawns NEW convo;
                                                      self-deletes DEAD)

from	via	to	notes
ALIVE	/kill	DEAD or ALIVE	If UNPERSISTED → auto-`/reap`; halts on low-conf, stays ALIVE. If clean → DEAD.
ALIVE	/kill!	DEAD	No checks. `/rite` runs for the record only.
ALIVE	/rite	ALIVE	Read-only classification.
ALIVE	/reap	ALIVE	Acts on `/rite` output with sane defaults; halts on low-conf.
DEAD	/resurrect	ALIVE' (new convo)	Spawns remaining work in a fresh conv; self-deletes the corpse. Alias: `/undead`.
DEAD	anything else	DEAD	Replies `DEAD`.

access levels

level	scope	commands	examples of mutation
RO	none (reports only)	/rite, /audit, /commands	none
RW-conv	conversation state only	/kill, /kill!, /resurrect	flips ALIVE↔DEAD; self-delete JS
RW-project	project files, new convos	/spawn, /fanout, /meteorite, /review, /profile	creates convos; writes `agent-project-profile.md`
RW-mem	agent memory	/compact, /transcend	edit/erase/compact memory entries
RW-project+mem	project files + memory	/inhale	writes 4 mirror files + refreshes memory
RW-project/repo/mem	everything except destructive defaults	/reap	act on UNPERSISTED with sane defaults; gated on confidence and destructiveness

budget reference

Budget = tool calls. N = worker count.

command	typical	worst	scaling
/spawn	1–2	2	fixed
/rite	2–3 light / 6–8 full	8	fixed
/reap	N×1–3	proportional	O(items)
/kill	2–6	8 (if auto-reap)	fixed + O(items)
/kill!	2–4	4	fixed
/resurrect	3–6	6	fixed
/compact	4–8	12	O(memory entries)
/transcend	15–30	40+	O(stale convos)
/inhale	8–12	14	fixed
/audit	8–12	14	fixed
/commands	4–6	6	fixed
/profile	2–5	5	fixed
/fanout	N×5+3	—	O(workers)
/meteorite	N×5+3	—	O(convos in window)
/review	10–25 per PR	N×5 + 20	O(comments, workers)

command relationships

/kill

runs /rite → may auto-run /reap
bypassed by /kill!

/resurrect

wraps /spawn (hands off remaining work)
alias: /undead

/meteorite

alias for /fanout rite --since=90
per-worker: runs /rite

/fanout

each worker: mandatory dual-cave (anthro + open)
harvester: /spawn-ed fresh conv (/review pattern)

/review

internally uses /fanout semantics for workers
harvester = fresh /spawn-ed conv

/inhale

reads agent-project-profile.md (set via /profile)
rewrites Dust mirrors on every run

/profile

edits agent-project-profile.md; effect applied by next /inhale

/audit

includes /commands structural check

/commands

--profile flag: annotate per-project filters

decision flows

I want to end this conversation.

Run /kill. If UNPERSISTED items exist, /kill will auto-/reap them with sane defaults and die. If /reap halts on low-confidence items, resolve them, then /kill again. Force-death with /kill!.

I killed a conversation by mistake / need to continue that work.

Run /resurrect (or /undead). It will /spawn a new conversation with the remaining work and self-delete the dead one.

The framework in this project feels stale.

Run /inhale. It pulls canonical files from GH, applies the project profile, and rewrites the Dust mirrors. Memory gets refreshed; PATs get checked.

A command does not apply to this project (policy / scope).

Use /profile omit /command or /profile stub /command "reason". Effect applies on the next /inhale run.

I want to know what changed in memory this month.

Run /audit. It flags memory entries older than 30 days, PAT expiry, and repo HEAD drift.

I need N parallel investigations that don't leak context.

Run /fanout N <task template>. Workers run with dual-cave mandate; harvest with /fanout harvest RUN-XXXX.

PR review pending.

/review #N (single), /review #33 #44 (list), or /review chain (resolve chain from memory).

aliases & triggers

alias / trigger	expands to	notes
/meteorite	/fanout rite --since=90	Project-wide `/rite` scan. `--self` to include current convo.
/undead	/resurrect	Soft alias. Both accepted.
“spawn new conv”, “hand off”, “continue in a new conv”, “fresh context”	/spawn	Natural-language triggers when intent is unambiguous.

v1 → v2 changelog

Audit results (2026-04-18). Previous version had 16 commands; current has 14 + 1 alias.

change	what	why
removed	/ascend	Redundant with `/rite`. Light mode folded into `/rite` with auto-detection on artifact count.
renamed	/undead → /resurrect	Imperative verb matches rest of framework. `/undead` kept as soft alias.
added	/profile	Discoverable management of `agent-project-profile.md` (omissions/stubs).
behavior	/kill	Auto-chains `/reap` (confidence ≥60%, non-destructive) on UNPERSISTED. Saves one round-trip on dirty exits.
behavior	/rite	Auto-selects light (2–3 calls) vs full (6–8). `--deep` forces full. Absorbs `/ascend`.
access	/inhale	RO → RW-project+mem. Was mislabeled; writes 4 mirror files and touches memory.
access	/reap	RW-project/repo → RW-project/repo/mem. Was missing memory scope (erase/edit entries).
budget	/compact, /transcend, /review, /reap	“varies” replaced with typical-range + scaling notation.
doc	state machine section	Explicit state transitions at the top of `agent-commands.md`.
doc	cheatsheet modal	Click any command for full spec; keyboard nav.
doc	analysis page	This page.