Features · Specs 001–005

Core Foundation

Everything else in misterspec — the CLI, the Context Engine, every agent integration — is built on five small, read-heavy packages that establish one thing: the project's own deterministic ground truth, computed from the filesystem, never stored separately.

001 · Core Repository Foundation

What it is: Three packages — project, artifacts, ids — with no CLI, no writing, no TUI.

Why it exists: Every later feature needs the same three answers: is this an initialized misterspec project? what canonical path does this artifact live at? what's the next free ID for a new entity? Answering these by scanning the filesystem (never a stored counter) is what Constitution Principle III actually requires.

Example — detecting a project and its config:

misterspec internal status --dir .
{"ok":true,"counts":{...},"structural_errors":0}

002 · Read-Only Deterministic Operations

What it is: internal/operations — Resolve, Inspect, Parent, Children, Inventory, Fingerprint.

Why it exists: Composes 001's own primitives into the actual questions an agent asks: "where exactly is SPEC-014?", "what are FEAT-004's own children?", "has this file changed since it was last indexed?" — building directly on 001, before anything is allowed to write.

Example:

misterspec internal resolve SPEC-014
{"ok":true,"id":"SPEC-014","path":"ai/programs/PRG-001/features/FEAT-004/specs/SPEC-014/spec.md"}

003 · Atomic Entity Creation

What it is: Create and CreateArtifact, protected by a short-lived, stale-recoverable lock.

Why it exists: The first feature that writes to disk — Constitution Principle II requires ID allocation and initial artifact creation to be one atomic step, never a split "get next ID" followed by "write the file," which would race under concurrent use.

Example:

misterspec internal create spec --parent FEAT-004
{"ok":true,"id":"SPEC-015","path":"ai/.../specs/SPEC-015/spec.md"}

004 · Structural Validation & Project Status

What it is: internal/validation plus operations.Status — every structural anomaly collected as data, never stopping at the first.

Why it exists: Completes the read-only side of 002: a fast, whole-project health check (status) and a specific, itemized structural audit (validate) — exactly what /mister-plan, /mister-tasks, and /mister-implement all call after every mutation.

Example:

misterspec internal validate SPEC-014
{"ok":true,"valid":true,"findings":[]}

005 · Embedded Kit & Resource Installer

What it is: kit (embedded templates/Skills via go:embed) and internal/installer (atomic, no-silent-overwrite materialization).

Why it exists: misterspec ships as one static binary with zero network dependency at install time — every artifact template and canonical Skill file lives inside the compiled binary itself, and installer.Install is the one, generic, agent-agnostic primitive every later adapter (006) reuses rather than reimplementing atomic writes a second time.

Example — what a template scaffold looks like once materialized by internal create (004's own example, above), sourced from this feature's own embedded kit/templates/spec.md.tmpl:

---
id: SPEC-015
type: spec
status: draft
parent: FEAT-004
---
## Intent