Project artifacts

HelmIt keeps project context in files so that decisions and proof do not depend on one conversation’s memory. Most live under .helmit/. You can inspect them, but let HelmIt skills update the workflow files. To resume, ask for /helmit:next; you do not have to read every file at the start of each session.

Files shared with the project

These files are versioned in Git. They let someone else continue with the same product definition, decisions, and delivery history.

File under .helmit/	What it is for
SPEC.md	Defines the product as a whole: what to build and why. It is created during project preparation.
ROADMAP.md	Lists delivery phases, their order and dependencies. It shows what has shipped.
REQUIREMENTS.md	Records requirements with stable IDs such as REQ-021, and whether they still need work or have been proven.
STATE.md	Keeps a short position for resumption: current work, next step, blockers, and pending decisions. It does not duplicate plans or proof.
KEEL.md	Holds project rules, architecture decisions, and test, build, and lint commands. The agent reads it at session start.
config.json	Holds languages and settings that HelmIt commands need to read.
INBOX.md	Captures findings outside the current work and their triage destination. Resolved items move to versioned history in history/.
CHANGES.md	Records localized changes with a CHG-NNN ID and their completion. A CHG need not become a phase.
spec-sources.json	When a spec uses external documents as sources, records which ones and allows later changes to be detected.

INBOX.md holds the observation before deciding what to do; CHANGES.md holds the localized change once it has a route. Read Inbox and changes for the triage process.

Files for each phase

Each delivery has its own directory at .helmit/phases/<id>/:

File	When it appears and what it records
SPEC.md	Defines that phase’s outcome and acceptance criteria. It is distinct from the product spec.
CHART.md	Breaks the delivery into tasks, links them to requirements, and states how to verify completion. implement can create or adapt this plan before building; chart lets you inspect it separately if you want.
VALIDATION.md	Records final delivery proof and anything still awaiting human evaluation. ship uses it to close the phase.

A small, well-defined correction follows the CHG route outside phases. It does not acquire a phase SPEC.md, CHART.md, and VALIDATION.md just to fit the process. See the phase lifecycle for a full delivery.

Files local to this machine

These files stay outside Git. They help track sessions, execution, and costs, but they are not the contract shared with someone cloning the project. Setup configures .gitignore to keep them local.

File under .helmit/	What it is for
lock.json and executor-lease.json	Coordinate writes and signal recent activity from a task executor.
session-activity/	Keeps short-lived, per-session host activity signals without claiming a task or phase.
run.jsonl	Records task, session, and gate events; helps recognize and reconcile an interruption.
metrics.jsonl	Stores available token-usage captures, including those used by the dashboard.
HANDOFF.md	Leaves narrative context for the next session; current facts are checked again on resumption.
dashboard.html	Shows a generated view of the artifacts and can be recreated.
quality-receipt.json	Keeps local full-suite proof that can be reused if the verified code and commands are still the same.
yolo.json	Holds a mandate for this machine when you have enabled one.
map/	Holds the optional, rebuildable repository map.
proof-worktrees/	Temporarily holds Git copies used to run proof against the exact version under evaluation.

For example, when you return to a project after a few days, /helmit:next uses the shared position and available local records to suggest the next step. If work was interrupted, it may ask for reconciliation before continuing. You do not need to reconstruct the flow one file at a time.

To interpret the generated figures, read Dashboard. For how proof is recorded, read Testing.