smart-compact
/smart-compact: write custom /compact instructions from the session, then compact with them
newcommandstatusmodeltimer
/smart-compact: write custom /compact instructions from the session, then compact with them
<!-- generated by scripts/readme/build.mjs. do not edit by hand. -->
<img alt="Harness Firmware boots with 41 skills, 6 project-memory files, and 2 runtime boundaries ready." src="assets/readme/boot-light.svg" width="100%">
A repository starter for Claude Code and Codex. Harness Firmware gives both agents versioned instructions, durable project memory, reusable skills, and workflows for testing and independent review.
Keep project decisions and pitfalls with the code. Carry useful lessons into the next session. Review changes before carrying them into another repository.
Install the skills or start a repository · Visit harnessfirmware.com
Use the skills-only plugin for an existing Claude Code repository. Use the full template for a new repository or Codex support.
Run these commands inside Claude Code:
/plugin marketplace add ryanportfolio/Harness-Firmware
/plugin install claude-starter@claude-starterThen try /claude-starter:recall or /claude-starter:brainstorming plan the next feature. Plugin skills use the claude-starter namespace.
Create a repository with the kernel, hooks, committed memory, skills, and synchronization tools:
/init-project command or ask Codex to use the init-project skill.bash bootstrap/new-claude-project.sh --name my-app --dest ~/codebootstrap/New-ClaudeProject.cmd.In the created repository, run node .claude/scripts/doctor.mjs. Success means the doctor reports no failures. Then ask Claude Code or Codex to use recall before the first unfamiliar change.
Open the complete setup guide · View validation runs
| Need | Workflow built into the repository |
|---|---|
| Remember the project | recall loads relevant committed facts, decisions, and pitfalls before unfamiliar work |
| Finish sustained work | long-horizon records progress and evidence across bounded rounds, with fresh audit context |
| Challenge a result | Independent and cross-vendor review skills check work through available agents or authenticated CLIs |
| Verify a claim | fable-mode separates current-state, change, and causal claims and returns a verdict; perf-loop measures optimization against a baseline |
| Maintain skills | addskill handles creating, importing, updating, and installing skills with the resources each runtime needs |
| Improve the workflow | refine captures observed friction; sync-starter carries selected generic fixes between repositories |
These are agent instructions and supporting tools. Structural checks validate the package; actual execution still needs the appropriate model, tools, credentials, and evidence.
<img alt="Recall, work, verify, refine, and a reviewed repository change form a local loop. A separate human-approved sync can carry generic changes into future repositories." src="assets/readme/feedback-light.svg" width="100%">
The everyday loop is recall → work → verify → refine → reviewed repository change → next task. Project facts load before unfamiliar work. Verification captures evidence. refine turns observed friction into a small, reviewable change that strengthens the repository before the next task begins.
The dotted branch is separate: after human review, sync-starter can move a generic improvement into the template so future repositories begin with it. Keeping the lesson local remains the default.
<img alt="41 Claude Code skills and 38 Codex skills share project memory. Codex has 38 native workflows." src="assets/readme/runtime-light.svg" width="100%">
41 Claude Code skills · 38 Codex skills · 38 native Codex workflows
CLAUDE.md, .claude/skills/, and hooks for canonical playbooks and Claude-specific startup behavior.AGENTS.md and .agents/skills/ for standalone Codex workflows with explicit capability and safety boundaries; every Claude skill has a maintained native Codex version or is disabled for Codex. Skill ownership and personal copies explains how they are maintained.Both runtimes read the committed project topics under .claude/reference/. Shared workflows live under .claude/skills/; standalone Codex workflows live under .agents/skills/.
7 core · 15 discipline · 19 specialist
Only names and routing descriptions sit in the repository's generated skill index. Full workflow bodies stay on demand. The diagram's byte figures are a repository source-file estimate, not total runtime context; the guide documents the measurement.
<img alt="A memory map of 41 on-demand workflows grouped into 7 core, 15 discipline, and 19 specialist skills." src="assets/readme/skills-light.svg" width="100%">
<!-- skill-list:start -->
init-project · Configure a starter project when setup is requested, using detected project facts and only necessary user questions.recall · Use before unfamiliar project-area work, when retrieving project decisions or pitfalls, when saving an authorized durable fact, or when a quirk just cost a retry, a backed-out change, or a user correction and belongs in pitfalls.addskill · Create, import, update, or install repository or personal skills; includes runtime ownership, resources, and discovery validation.sync-starter · Use when the user asks to pull template improvements into a spawned repo, compare starter drift, or push a generic improvement back to the starter.optimize-context · Use when the user asks to reduce per-turn context or token load, trim kernels, skills, or connectors, or propagate a generic context optimization to the starter.refine · Use for an explicit workflow-improvement review, turning the user's preferences into rules or a skill, recurring task friction that may justify a narrow change to skills or project references, or the unattended weekly review (/refine weekly).adopt-repo · Mirror an existing external repo privately under the user's account and overlay the firmware: clone upstream, strip template-only files, privacy-sweep, run init-project. Use on /adopt-repo <url> or 'pull this repo into our firmware'.brainstorming · Use when brainstorming or designing a product, interface, workflow, architecture, or behavior change with unresolved goals or material tradeoffs; not for routine or fully specified work.deep-plan · Use for /deep-plan: interview a loose idea in short rounds of decisions and stop for an explicit go before anything is built.writing-plans · Use when a clear task needs a multi-step implementation plan, dependency ordering, or a durable handoff. Skip for routine changes that can be executed directly.impartial-review · Use when the user asks to review, audit, or stress-test recent code changes with fresh independent agents; requires exposed multi-agent tools or an authenticated Codex CLI.perf-loop · Run measured optimization rounds with independent review for FPS, loading, latency, throughput, and resource use; with no named target, triage every dimension first. Use for /perf-loop or broad performance requests; skip isolated fixes.long-horizon · Use for work too big for one context window: long multi-step tasks, progress lost to compaction or failed retries, work spanning hours or sessions, or when the user says /long-horizon or asks to run a task in verified rounds.long-horizon-workflows · Long-horizon rounds run through the Workflow tool: one script per batch, with a fresh baseline, candidate executors, a blind pick, and independent judges for every round, schema verdicts and a run journal. Use on /long-horizon-workflows or to run a big task in Workflow-audited rounds. Claude Code only.babysit-ci · Watches a PR's checks and fixes failures. Use for /babysit-ci, "watch CI", "fix CI", "get checks green", or a PR with failing or pending checks; not a bare merge request.codex-review · Cross-vendor second-opinion review. Drives OpenAI Codex CLI (codex exec review, gpt-6.1-sol, high reasoning) over a PR, branch, commit, or uncommitted diff, then verifies each finding. Trigger: /codex-review, "have Codex/Sol review this".astra-review · Cross-vendor review configured for gpt-6-astra at medium reasoning. Same verified CLI lifecycle as codex-review. Use for /astra-review or 'have Astra review this'.codex-fullreview · Full multi-agent Codex review: codex exec runs $impartial-review as Manager with fresh-context sub-reviewers (gpt-6.1-sol, high), then each finding is verified. Trigger: /codex-fullreview, "full Codex review with sub-reviewers".astra-fullreview · Full multi-agent Codex review on gpt-6-astra at medium reasoning. Same verified lifecycle as codex-fullreview. Use for /astra-fullreview or 'full Astra review with sub-reviewers'.merge · Merge PRs through a Codex review loop: /codex-fullreview, fix, then /codex-review reruns (3 max) until clean, then CI and squash-merge. Runs only when the user types /merge; from then on, every PR in the session goes through the same loop and merges.claude-review · Use when the user says /claude-review, asks Claude or Fable to review code written in Codex, or requests a cross-vendor review through Claude CLI.dare · Use for /dare, first principles, or questioning the problem: four fresh stages decompose, audit, recombine and test, preserving immutable goals and constraints.fable-mode · Use for difficult multi-step work, uncertain diagnoses, repeated failures, 'did it work/is it fixed/prove it' questions, or tasks where verification and handoff need particular care. Skip routine changes.wow-loop · Evidence-gated review and repair loop for one deliverable or a set of like items. Use on /wow-loop, requests for wow factor or dial it to 11, a target score to reach ("get it to 8/10", "bring everything under 6 up to 6+"), or substantial visual work (3D, animation, UI, rendered documents) that needs reference fidelity or repeated visual correction. Skip routine cosmetic edits and discussion of the skill itself.showpiece · Push an artifact past what people expect from its kind, in any medium. Use for /showpiece, ambitious creative direction, portfolio-quality work, or replacing generic AI styling. Not for quiet or faithful work such as forms, dashboards, exact recreations or brand matching; use frontend-design or the project's UI skill. Skip routine edits unless explicitly invoked.design-prototypes · Brief → distinct image concepts (sections, features, interactions, branding) → compare → refine pick, before build. Use: /design-prototypes, prototype visual directions, compare design options, refine chosen concept. Built UI → redesign-concepts.redesign-concepts · Built UI → screenshots → Codex image_gen → 10 redesign concepts → owner picks → build plan. Use: /redesign-concepts, "show what we have to Codex, get 10 better versions", "prototype improvements to current UI". Brief only, nothing built → design-prototypes.codex-image-gen · Image asset needed (icon, sprite, texture, splash, logo, marketing art, illustration) from inside Claude Code → drive Codex image_gen via codex exec. Use: "generate an image", "make an icon", "use gpt-image / my Codex sub", placeholder asset → real art.arena · Builds parallel attempts at one task, judges them blind, and grafts the best ideas onto the strongest. Use for /arena, "try a few approaches", "build me options", bakeoffs, competing versions, or a stalled long-horizon or wow-loop step.lab · Use when the user explicitly asks to lab or prototype a visual, UI, motion, or game-feel element with live tuning before production implementation.advocate · Use only when the user explicitly invokes /advocate to challenge a change just made before it lands. Do not trigger from natural-language requests.why · Pressure-test a recommendation with one fresh reviewer. Use when the user types /why, or before you present your own weighty recommendation (hard to undo, two or more real options, or real time or money at stake). Never trigger from ordinary why questions or paraphrases.enhance-prompt · Use when the user asks for a rewritten, copy-ready prompt for another agent or session. Produce the prompt without executing its task.handoff-audit · Draft a self-contained audit prompt for a separate fresh session, with exact scope and falsifiable checks. Does not run the audit.writing · Write or edit audience-facing prose: docs, UI copy, emails, release notes, and application answers. Use also for voice matching, clarity review, or AI-tell cleanup. Ordinary session replies follow session conventions.forge-repo-ui-skill · Use when the user wants a repository-specific UI or design skill synthesized from current agent skills; not for ordinary UI implementation or backend-only work.caveman · Use for every session reply to the user: concise Caveman prose with built-in Unslop. User-facing deliverables use Writing instead.bro · Plain-language restatement. Use on /bro anywhere in a message, "plain english", "plain language", "dumb it down", "I don't understand", or "what does that mean".session-hub · Coordinate parallel Claude Code sessions via a shared append-only HTML hub. Use on /session-hub, 'run parallel sessions on this', joining a hub, or proactively when edits or commits this session did not make appear in the checkout.servers · Use on /servers, after starting a dev server, or when the user asks what is running, which port is which, why browsers are open, or to close old servers and browsers.wrapup · Use on /wrapup or when the user asks if a session is done, good to archive, or what is left: one verdict from git, the PR, scratch files and running servers or browsers.<!-- skill-list:end -->
The validation workflow checks shell and PowerShell entry points, Codex skill registration and drift from the Claude source, native skill propagation, linked skill resources, retired entrypoints, the Windows project generator, and this README's generated facts and assets. Inspect the CI runs.
.agents/skill-modes.json records which skills have a native Codex version and which are disabled for Codex. Maintenance guidance covers native updates, disabled skills, and personal copies.
Run the local health check:
node .claude/scripts/doctor.mjshooks/register.ts 86 lines1import type { EngineInterface, Register } from 'claude-code'
2
3// Asked of a fork of the session, which sees the whole transcript. Its answer is
4// passed to /compact as the custom instructions the summarizer follows.
5const REVIEW_PROMPT = `Review this whole conversation so far and write the custom instructions to pass to /compact. The summarizer reads them as directions for what to keep, so write imperatives to it.
6
7Keep, in priority order:
8
91. The user's goal for the session and any standing instructions or preferences they gave in it (style, scope limits, things to never do).
102. Current state: repo, branch, worktree path, PR URL, last commit SHA, deploy or preview URL, files created or changed.
113. Decisions made and the reason for each, including options the user rejected.
124. What is verified and how, and what is still unverified.
135. Open work: the next concrete step, pending questions to the user, background tasks still running.
146. Failed approaches and gotchas that would otherwise be retried.
157. Exact identifiers to keep verbatim: paths, commands, error strings, IDs, numbers.
16
17Tell the summarizer to drop resolved tangents, raw tool output, superseded plans, and anything re-readable from files or CLAUDE.md. Never invent a fact; if a state item is unknown, leave it out. Keep the block under about 300 words; cut from the bottom of the priority list first.
18
19Return exactly one fenced \`text\` block and nothing else. When the session's replies follow a named style or output style (caveman ultra, for example), make the first line \`Always use <that style>.\` so it survives the compaction; otherwise leave that line out.
20
21\`\`\`text
22Always use <reply style>.
23Goal: <one line>.
24Keep: <standing user instructions>.
25State: <branch, worktree, PR, SHA, files>.
26Decisions: <decision, why>; ...
27Verified: <what, how>. Unverified: <what>.
28Next: <next step>; open questions: <...>.
29Don't retry: <failed approach, cause>.
30Verbatim: <paths, commands, errors>.
31Drop tool output, resolved tangents, and superseded plans.
32\`\`\`
33
34Omit any line with nothing to say.`
35
36// The fork answers with one fenced `text` block; take its body.
37const fencedBody = (reply: string) => {
38 const match = reply.match(/```(?:text)?\r?\n([\s\S]*?)\r?\n```/)
39 return (match ? match[1] : reply).trim()
40}
41
42export const register: Register = on => {
43 on('session.start', async ($, e, next) => {
44 await $.command.register({
45 name: 'smart-compact',
46 description: 'Write custom /compact instructions from this session, then compact with them',
47 })
48 return next(e)
49 })
50
51 on('command.run', { command: 'smart-compact' }, async $ => {
52 $.ui.status('smart-compact: writing instructions')
53 const reply = await $.model.fork({ prompt: REVIEW_PROMPT })
54 if (!reply.isAnswered) {
55 $.ui.status(undefined)
56 return { text: `review failed (${reply.reason}); nothing compacted. Run /compact yourself.` }
57 }
58
59 const instructions = fencedBody(reply.text)
60 $.ui.status('smart-compact: compacting')
61 // The engine refuses to run a command from inside this hook, which still
62 // holds the command's turn; run it from a timer once the command finishes.
63 $.clock.after(500, () => void compactWhenIdle($, instructions, 10))
64
65 return { text: `compacting with these instructions:\n\n${instructions}` }
66 })
67}
68
69const compactWhenIdle = async ($: EngineInterface, instructions: string, triesLeft: number) => {
70 try {
71 // `$.session.compact` is refused in SDK sessions (the desktop app's Code
72 // tab); running `/compact` itself works in those and in the terminal.
73 await $.command.run({ command: 'compact', args: instructions })
74 $.ui.status(undefined)
75 } catch (err) {
76 // Retry only the refusal for a command run from inside a hook that still
77 // holds the turn; a cancelled or interrupted /compact stays cancelled.
78 if (triesLeft > 1 && /hook/i.test(String(err))) {
79 $.clock.after(1000, () => void compactWhenIdle($, instructions, triesLeft - 1))
80 return
81 }
82 $.ui.status(undefined)
83 $.ui.log(`smart-compact: compaction failed (${String(err)}). Paste the instructions above after /compact.`)
84 }
85}
86