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
quickstart
Use the skills-only plugin for an existing Claude Code repository. Use the full template for a new repository or Codex support.
existing repository · Claude Code plugin
Run these commands inside Claude Code:
/plugin marketplace add ryanportfolio/Harness-Firmware
/plugin install claude-starter@claude-starter
Then try /claude-starter:recall or /claude-starter:brainstorming plan the next feature. Plugin skills use the claude-starter namespace.
new repository · full template
Create a repository with the kernel, hooks, committed memory, skills, and synchronization tools:
- GitHub: select Use this template, clone the new repository, then run Claude Code's
/init-project command or ask Codex to use the init-project skill.
- From a cloned Harness Firmware checkout on macOS or Linux:
bash bootstrap/new-claude-project.sh --name my-app --dest ~/code
- From a cloned checkout on Windows: double-click
bootstrap/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
what the firmware adds
| 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.
the repository feedback loop
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.
two runtimes, explicit ownership
51 Claude Code skills · 47 Codex skills · 47 native Codex workflows
- Claude Code: reads
CLAUDE.md, .claude/skills/, and hooks for canonical playbooks and Claude-specific startup behavior.
- Codex: reads
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/.
51 workflows, loaded when called
8 core · 17 discipline · 26 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.
core workflows · 8
init-project · Configure a starter project on setup request: detected project facts, only necessary user questions.recall · Before unfamiliar project-area work; retrieve project decisions or pitfalls; save authorized durable fact; quirk just cost retry, backed-out change, or user correction → pitfalls.addskill · Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.sync-starter · Pull template improvements into a spawned repo, compare starter drift, or push a generic improvement back to the starter.optimize-context · Cut per-turn context or token load: trim kernels, skills, connectors; push generic context optimization to starter.refine · Explicit workflow-improvement review; user preferences → rules or skill; recurring task friction justifying a narrow skill or reference change; unattended weekly review (/refine weekly).adopt-repo · Mirror external repo privately under user's account + overlay firmware: clone, strip template-only files, privacy-sweep, init-project. Use: /adopt-repo , 'pull this repo into our firmware'.apply-firmware · /apply-firmware, or bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.
quality disciplines · 17
brainstorming · Brainstorm or design product, interface, workflow, architecture, or behavior change with unresolved goals or material tradeoffs. Skip routine or fully specified work.deep-plan · /deep-plan: interview a loose idea in short decision rounds; stop for explicit go before anything is built.writing-plans · Clear task needing a multi-step implementation plan, dependency ordering, or durable handoff. Skip routine changes doable directly.impartial-review · Review, audit, or stress-test recent code changes with fresh independent agents. Needs exposed multi-agent tools or authed Codex CLI.perf-loop · Measured optimization rounds with independent review: FPS, loading, latency, throughput, resources; no named target → triage every dimension first. Use: /perf-loop, broad perf requests. Skip isolated fixes.security-loop · Whole-repo security audit or pen-test in independently verified runs → fix owner's picks → rerun until nothing new. Use: /security-loop, 'security-audit / pen-test this codebase'. One diff or question → security-review.long-horizon · Work too big for one context window: long multi-step tasks, progress lost to compaction or failed retries, work spanning hours or sessions, /long-horizon, or 'run in verified rounds'.- · Long-horizon rounds via Workflow tool: 1 script per batch, fresh baseline, candidate executors, blind pick, independent judges each round, schema verdicts, run journal. Use: /long-horizon-workflows, big task in Workflow-audited rounds. Claude Code only.
specialist tools · 26
fable-mode · Hard multi-step work, uncertain diagnoses, repeated failures, 'did it work/is it fixed/prove it', or tasks needing careful verification + handoff. Skip routine changes.wow-loop · Evidence-gated review + repair loop, one deliverable or set of like items. Use: /wow-loop, wow factor, 'dial it to 11', target score ('get it to 8/10', 'bring everything under 6 up to 6+'), substantial visual work (3D, animation, UI, rendered docs) needing reference fidelity or repeated correction. Skip routine cosmetic edits + talk about the skill itself.showpiece · Push an artifact past what people expect of its kind, any medium. Use: /showpiece, ambitious creative direction, portfolio-quality work, replacing generic AI styling. Not quiet or faithful work (forms, dashboards, exact recreations, brand matching) → ui-quality, frontend-design or project UI skill. Skip routine edits unless 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. 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 → design-prototypes.conversion-ux · Audit, design conversion flows stage by stage (arrive to exit): each element asks easier, honest question. Paywalls, pricing, trials, sign-up, onboarding, checkout, forms, filters, booking. Use: /conversion-ux, 'why doesn't this convert', 'audit this flow'. Visual concepts → redesign-concepts; copy polish → writing.
checked on every change
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.mjs
documentation
