feature docs

Getting started

First green suite in minutes.

The loop is spec → generate → implement → run, with feat verify locked around it. This page walks it once, end to end.

1 · Install and init

$ npm i -D @mmmnt/feature
$ npx feat init
  ✓ feat.config.json written · adapters: handler, fs

feat.config.json names your services and binds each to an adapter. Service keys are yours — the spec references them, and an unknown key is a validation error.

{
"response": { "adapter": "@mmmnt/feat-adapter-handler" },
"services": {
"database": { "adapter": "@mmmnt/feat-adapter-fs", "consistency": "acid" }
}
}

2 · Write a spec

A minimal .feat file needs a header, one construct directive, one enforce directive, one contract reference, and one scenario with a prediction. No escape hatches. See the language guide for the full grammar.

3 · Generate, fail, implement, pass

$ npx feat generate
  ✓ 1 suite derived · inputs sha256 in the header · commit it
$ npx feat run
  ✕ 2 failed — hand the construct block to your agent, implement, re-run
$ npx feat run
  ✓ 2 passed · standard Vitest — coverage and reporters work unchanged

Generated suites are committed and versioned like any other code. They are never hand-edited — the header says so, and feat verify enforces it.

4 · Lock it in CI

# ci.yml — the whole integration
- run: npx feat verify # drift is a build failure
- run: npx feat run --reporter junit

The CLI surface

feat parse Parse and validate specs; errors carry hints and spec coordinates.
feat generate Derive complete Vitest suites. Deterministic — same spec, same bytes.
feat verify Re-derive and byte-compare committed suites. The CI drift gate.
feat run Execute suites via Vitest; JUnit report with --reporter junit.
feat audit Cross-check specs, suites, and config for closure.
feat lint Semantic checks — unused declarations, two-way rejection lint.
feat fmt Conservative canonical formatting; --check for CI.
feat watch Regenerate on spec change during authoring.
feat diff IR-level spec diff against a git ref — what changed, semantically.