Agent Workflows6 min read

Spec Bootstrap

Generate a deeplink-strict project wiki with self-audits

Spec Bootstrap (📚 in the mode dropdown) is Nexgile Code’s documentation-first mode for brand-new projects. It interviews you, then generates a deeplink-strict wiki under docs/wiki/ that other AI agents — and humans — can implement code against. The premise is blunt: vague specs cause hallucinations. An agent told to “build the user API” invents fields; an agent told to “implement wiki/api/users.md#create-user exactly” ships working code. Spec Bootstrap forces every page to be concrete enough to implement, linked enough to navigate, and verifiable enough to trust.

Use it before asking other modes to write code — the wiki is the contract. For projects that already have a wiki and need updates from new commits, use Spec Sync instead.

What it can touch

Spec Bootstrap’s edit access is deliberately narrow: the docs/, sources/, spec/, and scripts/ subtrees, plus .nexgilerules (and .nexgilerules-<mode> variants) at the project root. Your application code is out of reach. It can run commands — that is how it executes its self-audits.

The 10-question intake interview

Before writing a single file, the mode asks ten questions and waits for every answer. It does not infer and does not proceed with gaps:

#	Question	Example answer
Q1	`PROJECT_NAME` — one word, used in package names	`acme`
Q2	`ONE_LINE_PURPOSE` — “X is a Y that Z”	“acme is a customer-feedback tool that aggregates support tickets”
Q3	`ARCHITECTURE` — exactly one of: single-app, monolith, modular-monorepo, microservices	monolith
Q4	`PRIMARY_STACK`	“Next.js 15 + FastAPI + Postgres 16”
Q5	`AUTH_MODEL` — JWT bearer, session cookie, OAuth provider, none-yet, other	JWT bearer
Q6	`DATABASE` and ORM	Postgres / SQLModel
Q7	`DEPLOYABLE_UNITS` — each named	“frontend, api”
Q8	`ROADMAP_PHASES`	“MVP, v1”
Q9	`EXTERNAL_READERS` — does anyone outside the team read these docs?	no
Q10	`SPEC_INPUT` — existing spec, brief, or PRD? Where?	`SPEC.md` at repo root

After the answers, the agent echoes back a 10-line scope contract and requires you to reply confirmed before any file is written. Your verbatim answers are persisted to docs/sources/transcripts/<date>-bootstrap-interview.md — every wiki page that cites “interview Q3” must resolve to that file, so the provenance trail is checkable.

The wiki output

After confirmation, the mode scaffolds and then fills a structured tree (adapted to your Q3 architecture — microservices projects get per-service folders instead of flat api/ and data/):

docs/
  log.md                  # append-only operations log
  roadmap.md              # planned but NOT yet specced
  wiki/
    00-INDEX.md           # a routing table, not a list
    glossary.md
    data/                 # one file per table
    auth/                 # roles, scope catalog
    api/                  # one file per endpoint
    ui/                   # one file per route
    integrations/
    ops/                  # env-vars, runbooks
    test/                 # strategy + fixtures
  sources/                # APPEND-ONLY: decisions/ research/ transcripts/ external/
.nexgilerules              # at the PROJECT ROOT

Content is generated bottom-up in dependency order — glossary → data model → auth → events → API contracts → service map → UI flows → integrations → operations — so each layer references only layers below it and circular references cannot creep in.

Every page obeys a hard 300-line cap (200 for catalogs and glossaries). Long topics split into subpages instead of growing.

The page rules: Concrete, Linkable, Verifiable

Every page must satisfy all three properties; a page that fails any is rejected and rewritten.

Concrete — schemas as schemas, endpoints as endpoints, field tables with (type, required, constraints, default) for every field. No vague verbs: “handles authentication” is banned; “validates Authorization: Bearer <jwt>, rejects 401 on missing token, 403 on insufficient scope” is the required shape. Unknowns are tagged [GAP-XX-NN], never “TODO: decide later”.
Linkable — every cross-reference is exact: wiki/api/users.md#create-user or apps/backend/src/routes/users.ts:24-58. Never “see the API docs”. Each referenced section carries an explicit <a id="..."> anchor; paths that don’t exist yet are tagged [planned]. No fact is duplicated across pages — one source of truth, everywhere else links.
Verifiable — every page ends with a ## Verify block containing one runnable shell or curl command that checks the page’s claims. If no verify command can be written, the page is too abstract and gets rewritten until one can.

Each page also opens with a provenance header:

> **Sources** — interview Q3, Q5; `apps/backend/src/schemas/user.ts:15-30`
> **Status** — [spec] (no code yet) | [code] (implemented) | [drift] (code diverges)
> **Page-size budget** — used 142 / 300 lines

A page with no sources is treated as hallucination and blocked.

`.nexgilerules` — the operating contract

Phase 5 writes a .nexgilerules file at the project root — the rules file Nexgile Code injects into every future task in this project. It contains a one-paragraph project summary, a “what to read before starting any task” table (change a table → read docs/wiki/data/<table>.md; add an endpoint → read the endpoint page plus the scope catalog), and hard rules: never edit a wiki page without updating its Sources line, never add a TODO without a [GAP-XX-NN] id, never exceed 300 lines, every PR cites the wiki sections it implements. The wiki teaches the spec; .nexgilerules makes every later agent respect it.

The self-audits

Before it will say “done”, the mode runs its self-check battery against the whole wiki. The five core audits:

Audit	Catches
Deeplink	Cross-references to pages, anchors, or `path:line` targets that don’t exist (untagged)
Page-size	Any page over its line cap
Orphan	Pages no other page links to
Forbidden-pattern	`TODO`/`TBD`/`FIXME`, vague verbs, “in the future” scope creep without a `[GAP]` id
Provenance	Pages missing the Sources / Status / Page-size header

The full battery goes further — page anatomy (exactly one H1, anchors before every H2, a Verify block on every page), the operational files (.nexgilerules, docs/log.md with a [bootstrap] entry, docs/roadmap.md, the interview transcript), and interview-citation resolution. When the project contains scripts/spec-audit.mjs, one command runs everything:

node scripts/spec-audit.mjs

If any audit fails, the agent fixes and re-runs the battery. It does not declare the bootstrap complete until every check returns empty.

Example walkthrough

A condensed session for a small API project:

You:   (switch to 📚 Spec Bootstrap) Bootstrap the documentation wiki for this project.
Agent: Q1. PROJECT_NAME? … Q10. SPEC_INPUT?
You:   notesapi / "notesapi is a REST service that stores personal notes" /
       single-app / "FastAPI + Postgres 16" / JWT bearer / Postgres + SQLModel /
       api / "MVP" / no / none
Agent: SCOPE CONTRACT — please confirm with "confirmed" or correct: …
You:   confirmed
Agent: (writes transcript → scaffolds docs/ tree → generates glossary, data,
        auth, api, ops, test layers → writes .nexgilerules, log.md, roadmap.md
        → runs the audit battery)
Agent: Bootstrap complete. 23 pages, all audits passed. Index: docs/wiki/00-INDEX.md.

The result: docs/wiki/00-INDEX.md is a routing table (“I need to add an endpoint → api/00-overview.md”), each endpoint page specifies full request/response schemas with every error code, and docs/log.md records a [bootstrap] entry ending in Last-synced commit: <sha> — the baseline Spec Sync will pick up later.

Tips

Answer precisely. Interview answers become cited sources; “Postgres 16” beats “some SQL database” forever after.
Greenfield pages start as [spec] with [planned] file paths — their Verify commands describe how to check the claim once implemented. Spec Sync flips them to [code] as commits land.
Don’t hand-edit the append-only zones. docs/sources/ and docs/log.md only grow; corrections happen through new entries and ADRs.
Implement against the wiki. When you start Code-mode tasks afterwards, point them at pages: “Implement docs/wiki/api/notes/create-note.md exactly.”
Then keep it honest with Spec Sync after code lands.