# Instantiate a project from experimplate

> **experimplate** is a reusable project skeleton that carries a proven agent-built working
> style: requirement traceability that gates the build, just-in-time planning, a
> grill-the-plan-against-the-docs loop, release + changelog discipline, and same-repo
> published docs. You copy it, fill the placeholders, acquire two external tools, and start.
>
> The scaffolding is **meta-process** — copying it does not leak any source project's
> internals, so a consumer under a "public-surface-only" constraint may still instantiate
> from it.

## What you get

| File | Role |
|---|---|
| `AGENTS.md` | Canonical, harness-agnostic working rules (source of truth). |
| `CLAUDE.md` | One line (`@AGENTS.md`) bridging the rules into Claude Code. |
| `traceable-reqs.toml` | Empty `REQ-*` registry seed + activation model in the header. |
| `docs/TRACEABILITY.md` | The doc→impl→unit→int contract and how it gates CI. |
| `docs/DOCS-STRATEGY.md` | Same-repo `docs-site/` → GitHub Pages, dual-audience, CI-gated. |
| `docs/KNOWN-HAZARDS.md` | Hazard-as-`REQ-HAZARD-*` skeleton. |
| `docs/RELEASE-RUNBOOK.md` | Generic release shape (changelog · bump · tag · release · docs publish). |
| `CONTEXT.md` | Glossary stub — authoritative for meaning (grill-with-docs convention). |
| `docs/adr/`, `docs/formats/` | ADR template + ADR/CONTEXT authoring-format guides. |
| `docs/CI.md` | The agent-driven, autonomous, no-LLM-in-the-loop CI pattern. |
| `docs-site/theme/` | Shared mdBook theme (transferable styling). |

## Steps

### 1. Copy the skeleton

Copy every file EXCEPT `PLAN.md` (experimplate's own authoring plan) and `.git/` into your
new repo. `git init` if needed.

### 2. Fill the placeholders

Search the tree for `<` and replace every `<PLACEHOLDER>`:
- `<PROJECT>` — the project name.
- `<one-line description …>` — what the project is.
- `<orientation docs>` — the docs an agent must read first (PRD, ROADMAP, SPEC … whatever
  this project keeps).
- the **wire/schema copy-verbatim** note in `AGENTS.md` — keep it if you copy a stable
  format from an upstream, else delete it.
- the **commit co-author trailer** — keep if built by live agents, else delete the line.
- `[scan].roots` in `traceable-reqs.toml` — this project's real evidence dirs.
- the docs-site project name/title.

### 3. Acquire `traceable-reqs` (required — the build gate)

It is a released binary, not a crate/package dependency. Download the build for your runner
+ dev machines:

```sh
# Linux x86_64
gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64' \
  --output traceable-reqs && chmod +x traceable-reqs
# Windows
gh release download --repo BigscreenVR/traceable-reqs --pattern '*windows*.exe' \
  --output traceable-reqs.exe
```

Put it on `PATH` (dev) and install it in CI the same way (see `docs/CI.md` and the snippet
in `docs/TRACEABILITY.md`). Then validate the seed:

```sh
traceable-reqs check        # green on the empty seed (nothing activated yet)
```

### 4. Acquire the `grill-with-docs` skill (recommended — the planning loop)

`grill-with-docs` stress-tests a plan against this project's own domain model and updates
`CONTEXT.md` + ADRs inline as decisions crystallize. It is an agent skill: install it into
your harness's skill directory (for Claude Code, drop it under `~/.claude/skills/` or add
the marketplace that ships it), then invoke it whenever you plan a milestone. The ADR and
CONTEXT **format guides** it expects already live in `docs/formats/`.

### 5. Wire CI

Adopt the agent-driven autonomous pattern in `docs/CI.md` (git-hook trigger → a fleet
runner-agent runs the deterministic gates → reports over your messaging bus). The
deterministic gates are: build, unit tests, `traceable-reqs check`, and the docs-drift
check. A hosted-runner workflow is an optional fallback — `docs/TRACEABILITY.md` carries a
ready GitHub Actions snippet.

### 6. Seed the project's own meaning

- Write `CONTEXT.md` — the glossary is authoritative for what each term means.
- Record your first decisions as ADRs in `docs/adr/` (copy `docs/adr/0000-template.md`).
- Write your first JIT `*-PLAN.md` and start the first milestone: add its requirements to
  `traceable-reqs.toml`, activate their stages, and tag evidence as it lands.

### 7. First commit

Land the instantiated skeleton (placeholders filled, `traceable-reqs check` green) as the
project's first commit, then begin milestone work.