# Initialize product context

> Run init to interview and write PRODUCT.md (including Platform), optionally document DESIGN.md from code, configure live when useful, and verify completion gates.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `skill/reference/init.md`
- `skill/reference/document.md`
- `skill/scripts/context.mjs`
- `skill/scripts/lib/artifact-schema.mjs`
- `skill/scripts/lib/design-parser.mjs`
- `skill/scripts/command-metadata.json`

---

---
title: "Initialize product context"
description: "Run init to interview and write PRODUCT.md (including Platform), optionally document DESIGN.md from code, configure live when useful, and verify completion gates."
---

`/impeccable init` captures durable product truth in `PRODUCT.md` (including bare `## Platform`). It never invents a visual world and never writes `DESIGN.md`. Optional `/impeccable document` records an incumbent system as root `DESIGN.md` plus `.impeccable/design.json`. Runnable web projects may also receive `.impeccable/live/config.json` during init wrap-up. Session boot runs `node <skill>/scripts/context.mjs` once; missing product context emits `NO_PRODUCT_MD` / `PRODUCT_INIT_REQUIRED` / `BUILD_INIT_REQUIRED` directives that divert build and shape work into init.

## Commands

| Command | Metadata | Writes | Does not write |
|---|---|---|---|
| `init` (`teach` alias) | Capture product context | `PRODUCT.md` (schema stamp), optional live config | `DESIGN.md`, surface briefs, visual worlds |
| `document` | Capture visual system | `DESIGN.md`, `.impeccable/design.json` (scan mode) | Product truth; seed mode skips the sidecar |
| `document --seed` | Pre-code world seed | Seed `DESIGN.md` only (requires `PRODUCT.md`) | Token frontmatter, sidecar |

Invoke as `/impeccable init` or `/impeccable document` (provider prefix may be `$` on some harnesses). `craft` is a deprecated alias for ordinary new-work, not for init.

## Prerequisites

- Skills installed for the active harness (project or global scope).
- Working directory at the user project root (or monorepo child that owns product context).
- An answer mechanism for interviews (structured question tool, decision page, or live human). Unattended inference is allowed only after a real probe fails; label every inferred fact in `PRODUCT.md`.

## Init workflow

<Steps>
<Step title="Load current state">
Use the `PRODUCT.md` path resolved by `context.mjs`. Update that file; do not create a competing authority. In a nested app inheriting root context, confirm shared versus app-specific scope before writing.

| Existing state | Action |
|---|---|
| No `PRODUCT.md` | Explore, interview, write |
| `PRODUCT.md` exists | Ask what is stale or missing; do not reopen confirmed fields without reason |
| Legacy file, no `## Platform` | Default platform is `web` unless evidence says otherwise |
| Only `DESIGN.md` | Leave design file untouched; create `PRODUCT.md` |
| Redesign/rebrand | Preserve confirmed product truth; visual replacement is later new-work |
</Step>

<Step title="Explore the project">
Scan product docs and copy; package/config boundaries; features, workflows, routes, roles; names, logos, legal assets; platform/a11y signals; and the dev entry when live mode may apply. Treat repository evidence as hypothesis, not approval. Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive`. Mobile web and native wrappers around websites stay `web`.
</Step>

<Step title="Interview for product truth">
Ask only material gaps. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new `PRODUCT.md`. Priority unknowns:

1. Primary user, situation, and job
2. What the product makes possible and its differentiated mechanism
3. Durable constraints, assets, evidence, and facts future work must preserve

Confirm ambiguous platform separately. On greenfield builds without a scaffold, ask once for stack (static HTML/CSS, named framework, or delegated recommendation plus deploy constraints) and record under `## Stack`. Do not ask for aesthetic direction, palette, or typography during init.
</Step>

<Step title="Write PRODUCT.md">
Write confirmed facts and explicitly marked open decisions. Omit irrelevant sections. New files go at `PROJECT_ROOT/PRODUCT.md`; otherwise update the resolved path. Include the provenance stamp verbatim:

```markdown
# Product

<!-- impeccable:product-schema 1 -->

## Platform

web
```

Bare platform values: `web` | `ios` | `android` | `adaptive`. When the recorded platform is native, load `reference/ios.md`, `reference/android.md`, or both before design work (context could not have loaded them before the stamp existed).
</Step>

<Step title="Configure live when useful">
Skip native and non-runnable projects. Leave existing live config untouched. For runnable web apps, follow live first-time setup (`.impeccable/live/config.json`, inject targets, CSP consent). Any CSP source edit still requires explicit consent.
</Step>

<Step title="Verify completion and resume">
**Completion gate:** `PRODUCT.md` must exist at the resolved path with the confirmed product record. Interview notes, planning packets, or design prose are not substitutes. Then resume the original request without rerunning `context.mjs`.
</Step>
</Steps>

### PRODUCT.md section map

| Section | Required content |
|---|---|
| `## Platform` | Bare `web` / `ios` / `android` / `adaptive` |
| `## Stack` | Greenfield only; omit when the codebase already answers |
| `## Users` | Primary users, situation, job |
| `## Product Purpose` | What it does, why it exists, success |
| `## Positioning` | Differentiated mechanism or claim |
| `## Operating Context` | Workflows, tools, materials, rituals |
| `## Capabilities and Constraints` | Functionality, tech constraints, undecided facts |
| `## Brand Commitments` | Name, voice, assets, binding identity; omit if none |
| `## Evidence on Hand` | Real content/data/assets and paths; state absences not to fabricate |
| `## Product Principles` | Three to five strategic principles (not visual recipes) |
| `## Accessibility & Inclusion` | Known needs or standard; omit if none |

Schema constant: `PRODUCT_SCHEMA_VERSION = 1` in `skill/scripts/lib/artifact-schema.mjs`. Stamp readers: `readProductSchemaVersion`, `stampProductSchema`, `productStampLine`.

Deprecated heading `## Register` is no longer read (visitor modes live per surface brief). Doctor/boot may report it; delete when the user agrees rather than carrying it forward.

### What belongs vs does not

| Belongs in `PRODUCT.md` | Does not belong |
|---|---|
| Users, jobs, purpose, positioning, constraints | Visual worlds, palettes, type, components |
| Platform, a11y needs, evidence, brand commitments | Visitor mode, CTA/proof sequence, surface strategy |
| Confirmed voice and assets | Invented testimonials, pricing, or deployment claims |

## Document workflow

Run when you need a portable visual system for agents (or the live design panel). Paths:

| Mode | When | Outputs |
|---|---|---|
| **Scan** (default) | Tokens, components, or rendered UI exist | Full `DESIGN.md` (YAML frontmatter + up to eight sections) and `.impeccable/design.json` (`schemaVersion: 2`) |
| **Seed** | Pre-implementation; no extractable system | Seed `DESIGN.md` with `<!-- SEED: ... -->` marker; minimal frontmatter (`name`, `description`); no sidecar |

Scan extracts from CSS custom properties, Tailwind theme, CSS-in-JS themes, design-token files, component libraries, global styles, and optional browser computed styles. Then confirm qualitative language (north star, color character, elevation and component philosophy) in short structured rounds.

Canonical body sections (omit empty; keep order): Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Frontmatter holds normative tokens (`colors`, `typography`, `rounded`, `spacing`, `components`); shadows, motion, breakpoints, HTML/CSS snippets, and narrative live only in the sidecar.

<Warning>
Do not silently overwrite an existing `DESIGN.md`. Confirm refresh, overwrite, or merge. Seed mode does not authorize replacing a coherent incumbent system; route identity replacement through new-work.
</Warning>

`DESIGN.md` carries **no** product-schema stamp (external design.md / Stitch compatibility). Sidecar version constant: `DESIGN_SIDECAR_SCHEMA_VERSION = 2`.

## Context resolution and boot directives

`context.mjs` path order (first match wins):

1. Active project root (`PRODUCT.md` / `DESIGN.md`; `--target` selects monorepo child or nearest owner)
2. Active project `.agents/context/`, then `docs/`
3. Repo root fallback for nested monorepo apps
4. `$IMPECCABLE_CONTEXT_DIR` when defaults are empty
5. Active project root as empty default

Platform parse: first non-empty line under `## Platform`. Valid: `web`, `ios`, `android`, `adaptive`. A line naming both native targets (for example `ios, android`) becomes `adaptive`. Unrecognized values fall back to `web` and emit a `WARNING` naming the bad value.

Key directives when product context is missing:

| Directive | Meaning |
|---|---|
| `NO_PRODUCT_MD` | No product file; init/teach/shape/new surface require `reference/init.md` |
| `PRODUCT_INIT_REQUIRED` | No product or visual authority; builds need init then new-work |
| `BUILD_INIT_REQUIRED` | Shape / new-surface / redesign must capture product first |
| `SCOPED_EXISTING_ALLOWED` | Narrow refinements may use code as authority and offer init later |
| `EXISTING_VISUAL_SYSTEM` | Code/assets are design authority; missing `DESIGN.md` is documentation gap |
| `INCUMBENT_WORLD_UNDOCUMENTED` | Product exists, design missing, code has visual decisions |
| `WORLD_DISCOVERY_REQUIRED` | Product exists; no design file and no visual implementation |

After init writes `PRODUCT.md`, resume without rerunning `context.mjs`. Init loads native platform references itself for `ios` / `android` / `adaptive`.

## Completion gates and verification

<Check>
**Init complete when:** resolved `PRODUCT.md` exists, includes `<!-- impeccable:product-schema 1 -->`, records bare `## Platform`, and holds confirmed product sections (not empty placeholders for required truths).
</Check>

<Check>
**Document (scan) complete when:** root `DESIGN.md` follows canonical section order with normative frontmatter tokens, and `.impeccable/design.json` has `schemaVersion: 2` with extensions and component snippets as applicable.
</Check>

<Check>
**Document (seed) complete when:** seed marker is present, world invariants are committed without fake tokens, and the user is told to re-run document once code exists.
</Check>

Optional follow-up check: `node <skill>/scripts/context.mjs` in a **new** session should print `# PRODUCT.md` content (and design / native refs when present) without `NO_PRODUCT_MD`. For schema/config drift later, use doctor; do not repair drift as a side effect of design work unless the finding is severity `auto`.

## Recommended next actions after init

| Project state | Next command |
|---|---|
| Empty or early | Natural build request, or `/impeccable shape <surface>` for a confirmed brief |
| Coherent UI, no `DESIGN.md` | `/impeccable document` (optional, independent of a build) |
| Existing surface needing work | Scoped refine/evaluate command for that target |
| Web project, live configured | `/impeccable live` |

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Agent designs without `PRODUCT.md` | Scoped command path; init not required for narrow polish | Explicit `/impeccable init` before new surfaces/redesigns |
| Platform refs missing after first init | Session resumed without native load | Init must load `ios.md` / `android.md` when platform is native |
| Unrecognized platform treated as web | Typo or toolchain name (`flutter`, etc.) | Set bare design-language value: `web` / `ios` / `android` / `adaptive` |
| Init offered `DESIGN.md` | Incorrect flow | Init never writes design; use document or new-work |
| Live inject fails / CSP | Config missing or CSP blocks localhost | First-time live setup + CSP consent (`cspChecked`) |
| Seed without product | Seed requires product truth | Finish init first |
| Duplicate product files | Nested monorepo writes | Use context-resolved path; confirm shared vs app-specific scope |

## Related pages

<CardGroup>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md, DESIGN.md, design.json, surface briefs, stamps, and resolution order.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Visitor modes and platform values, native refs, web-only live/detect bounds.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live config, poll contract, inject, and carbonize cleanup.
  </Card>
  <Card title="Doctor" href="/doctor">
    Schema, config, and truth-drift findings for product and design artifacts.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First successful session from install through init and a scoped command.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, craft-floor gate, and when init is required vs optional.
  </Card>
</CardGroup>