mikoshi-construct weekly downloads statistics

mikoshi-construct

Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an empty repository.

Documentation · Getting started · The development cycle · CLI reference

Presets node-backend, node-frontend, node-library and monorepo. Claude Code gets the full lifecycle; Cursor gets the rules, the conventions and the discovery protocol. What a repository has become lives in two records: construct.json, the provenance of what was materialized and by which version, and construct.model.json, the knowledge — facts, claims and hypotheses, each standing on evidence a reader can re-check. sync replays the first against today's templates, graph draws the second, and doctor reads both.

What it does

construct init materializes a construct into a repository — architecture policy, an API contract, a quality harness and instructions for coding agents — then hands the repository to the agent for discovery. The CLI detects facts; the agent interprets the system.

An existing repository gets the policy, the harness tooling and the agent files, never example code; its own AGENTS.md, CLAUDE.md, package.json and configs are merged or left alone, and init says what still has to be wired by hand.

Usage

A new project. Name a preset and it writes everything:

An existing repository. Look before you write:

+ creates a file that is not there. ~ merges into one that is, inside a construct:begin … construct:end block or as a JSON merge where your values win. = leaves the file alone and reports it. No example code lands in a repository that already has some, and there is no --force.

Cursor, or both agents. The rules are written once and rendered for each:

Check a repository at any time.

sync reports and changes nothing until you ask for --apply, and even then it writes only what the construct itself wrote and you have not touched.

Every command, flag and exit code: docs/cli.md.

Three principles

1. CLI detects facts. Agent interprets the system. Everything that needs understanding of the codebase — the module map, the composition roots, the high-effort areas, the security invariants — is a discovery marker the agent fills by reading code, never something the CLI guesses. 2. Reasoning is a budget; verification decides when to spend more. Implementation starts at low effort under strict constraints. The harness proves the result. Effort escalates only when the harness fails repeatedly or the task is ambiguous. *We don't pay for reasoning until the system demonstrates that we need it.* 3. An artifact nobody validates against is just another README. The contract is validated at runtime, composition models render the diagrams and are checked against the code, the dependency policy lives in lint, and every security invariant names the check that enforces it.

The second principle in numbers, from thirteen /implement runs on this repository (Claude Opus). Two low tasks cost 557k and 740k billable tokens (cache reads included, unlike the totals construct cost prints today). Nine medium tasks cost between 847k and 5.9M — the class is a weak predictor on its own. Two high tasks, each with an architect designing before any code, cost 14.19M and 14.14M.

Almost none of that is the work. It is each agent's entry into the repository: a fresh exploration, paid in full before anything is produced, and paid again by every agent that starts. A low run pays it twice — an implementer, and the harness that refuses to let the implementer mark its own homework. A high run pays it three times. The class mostly decides how deep each entry goes; the ladder decides how many entries there are, and that is what it is for.

The same arithmetic prices a bad brief. One run escalated to an architect after the implementer stopped on a contradiction in the task, and the architect spent 3.66M without returning a valid answer — 4.16M for the run, for nothing. That is why a response the schema rejects is not re-asked by default: a second attempt buys another entry, not another answer. construct cost prints all of this for your own runs, and reconciles it against the ledger the ladder writes.

The lifecycle

Discover — /construct-discover reads the repository and fills AGENTS.md and architecture/: what the product does and where a defect costs the most, the module map, the composition roots, the dependency policy (and makes lint enforce it), the high-effort areas, one composition model per real flow, the security invariants with their checks, what a reviewer must flag, and what looks like a convention but is not. Where a section already exists in the repository, the marker points at it.

Plan — /plan turns a feature into two to six tasks, each with acceptance criteria a harness run can confirm — shown failing before the implementation exists, or they are intent rather than criteria — and an effort class.

Implement — /implement runs the ladder: low → low → medium → high (or from medium or high when the task warrants it). An implementer agent works under strict constraints, a harness agent verifies against the working tree and reports a structured verdict — a pass is never self-reported — and an architect agent designs only for high tasks or after a blocked or failed attempt. The harness checks the base first: a base red in a way that cannot be identified runs nothing, before any implementer or architect runs; a base whose failures are identified and pinned runs, and a rung passes when it adds none. Every run is logged to .construct/runs.jsonl with its rungs, attempts and usage.

Verify · Review · Harden — pnpm run quality is the gate in CI and for every agent; `--review claude` adds a label-triggered AI review workflow; a finding that recurs becomes a named invariant with a named check, not a second fix.

Commands

| Command | What it does |…

Description from the npm listing.