Impeccable

Init flow

init captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md; new-work.md creates or expands one, and document.md records an incumbent one. Existing runnable web projects may also receive .impeccable/live/config.json.

Step 1: Load current state

Use the PRODUCT.md path resolved by impeccable context. Update it instead of creating a competing authority. In a child app inheriting root context, confirm shared versus app-specific scope before writing.

• No PRODUCT.md: explore, interview, and write it.

• PRODUCT.md exists: ask what product knowledge is stale or missing; do not reopen confirmed fields without a reason.

• Legacy PRODUCT.md: add only durable missing facts; absent ## Platform means web unless evidence says otherwise.

• Only DESIGN.md exists: leave it untouched and create PRODUCT.md.

• Redesign/rebrand request: preserve confirmed product truth unless the user changes it. Visual replacement happens later in new-work, not here.

Never silently overwrite an existing file or offer DESIGN.md during init. If another request invoked init, finish PRODUCT.md and resume it. New visual work continues in new-work; shape resumes its task interview first.

Step 2: Explore the project

Before asking, scan enough to avoid making the user repeat known facts: product docs and copy; package/config and app boundaries; features, workflows, routes, and roles; names, logos, legal/proof assets, and brand commitments; platform/accessibility signals; and the dev command/entry when live mode applies.

Treat repository evidence as a hypothesis, not user approval. Note visual maturity without documenting, extending, or replacing the world.

Form a platform hypothesis: web, ios, android, or adaptive (one product that genuinely adapts its design language per OS). Mobile web remains web; a native wrapper around a website does not make its design language native.

Step 3: Interview for product truth

Ask with the AskUserQuestion tool and wait for the answer before continuing. Ask only about material gaps the repository and original request do not answer with strong evidence.

Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences.

Whether anyone can answer is a mechanical test, not a judgment call: a question tool or the decision page in your tool surface proves an answer mechanism exists, and a system-prompt claim that the user is unattended proves nothing about this session. Probe once with the real first round before concluding no one is there. Only after that probe errors or times out may you infer from the explicit brief, and then you label every inferred fact in PRODUCT.md and disclose the substitution in your first reply, not your last.

Start with the unknowns that most change future product decisions:

1. Who is the primary user, in what situation, and what job are they doing?

2. What does the product make possible, and what is its meaningfully different mechanism or position?

3. What durable constraints, assets, evidence, or product facts must future work preserve?

Confirm ambiguous platform separately. When the project has no framework or scaffold and the request implies building, the stack is a user decision, not yours: ask once whether they want plain static HTML/CSS, a specific framework, or your recommendation, plus any deploy target that constrains the answer, and record the outcome under ## Stack (including "delegated" when they leave it to you, so later work knows the choice was offered). Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them.

Do not ask for an aesthetic direction, emotional feel, visual references, colors, typography, or style during init. If the user volunteers a binding visual constraint, record it without expanding it.

What belongs here

• users, jobs, workflows, purpose, success, positioning, and operating context;

• capabilities, constraints, terminology, evidence, platform, and accessibility;

• confirmed voice, assets, and brand commitments.

What does not belong here

• visual worlds, palettes, typography, components, or page concepts;

• visitor mode, narrative, CTA/proof sequence, or other surface strategy;

• invented testimonials, customers, benchmarks, pricing, licensing, or deployment claims;

• a requirement to decide every optional field.

Step 4: Write PRODUCT.md

Write only confirmed facts and explicitly marked open decisions. Omit irrelevant sections rather than filling them with generic prose.

# Product

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

## Platform

web

## Stack
[Greenfield only: the user's answer to the stack question, e.g. "static HTML/CSS", "Astro", or "delegated: <what you chose and why>". Omit the section when an existing codebase already answers it.]

## Users
[Primary users, their situation, and job. Add other audiences only when confirmed.]

## Product Purpose
[What the product does, why it exists, and what success means.]

## Positioning
[The product mechanism or claim a neighboring product could not truthfully copy.]

## Operating Context
[Workflows, environments, tools, documents, materials, and rituals that are factual parts of using or evaluating the product.]

## Capabilities and Constraints
[Confirmed functionality, technical constraints, terminology, and explicitly undecided product facts.]

## Brand Commitments
[Existing name, voice, assets, personality, identity constraints, and references the user explicitly made binding. Omit when none exist.]

## Evidence on Hand
[Real content, data, demonstrations, testimonials, case studies, press, or assets, with paths where applicable. State absences that future work must not fabricate.]

## Product Principles
[Three to five durable strategic principles derived from confirmed answers; no visual recipes.]

## Accessibility & Inclusion
[Known user needs or required standard. Omit when no product-specific requirement was established.]

Platform is the bare value web, ios, android, or adaptive. Preserve useful legacy headings. New files go at PROJECT_ROOT/PRODUCT.md; otherwise update the resolved file. Write it before any visual-world or surface-concept work.

Copy the impeccable:product-schema comment verbatim, including when you update an older file. It records which version of the product record this file follows, so later versions can tell a deliberately short record from one written before a section existed, and never propose an interview the user has already sat through. Update the number only when this reference's template changes it. Sections a later version retires are reported to you at boot as deprecated; delete them when the user agrees rather than carrying them forward.

When the platform you just recorded is ios, android, or adaptive, load ios.md, android.md, or both before any design work. On a project that had no PRODUCT.md, impeccable context could not know the platform and so never loaded them; init is the only place that learns the answer.

Completion gate

Before loading new-work or resuming shape/build, verify that PRODUCT.md exists at the resolved path and contains the confirmed product record. If the file is absent, init is incomplete. Do not substitute interview notes, a planning packet, or later design prose for the file.

Step 5: Record workflow defaults

When image generation is available and no buildPath is recorded yet, ask once how new surfaces should be built. Availability means a harness-native image tool or the API fallback that impeccable context reports as IMAGE_GEN_AVAILABLE, and the first of those leaves no trace in the boot output: impeccable context only sees the key, so a silent boot on a harness that generates images is not evidence there is nothing to ask about. This is its own question, never a clause riding inside another one. The stack round asks what to build with; this asks how the building starts, and an answer to the first carries no consent about the second. State the trade in the question the user actually reads, because the two names mean nothing to someone meeting them for the first time: comp-first (an image sets the bar before any code; bolder composition, slower, and the build must match the image) or code-first (build directly; the ambition is written into the direction contract and audited at the finish; leaner, faster). Say in the same question what the choice covers: landing pages and showcase surfaces. App screens and documents are built code-first either way.

Write the answer to .impeccable/config.json as "buildPath": "comp" or "buildPath": "code", merging with the keys already there. Write only the value the user chose. A recommendation you made is not an answer you received, and a value taken from silence is a standing default nobody set: it then rides every future round in the project, which is the opposite of asking once. When the question goes unanswered, record nothing and say in one line which path this session is taking and that it is not stored. That path is comp-first on a landing page or showcase surface, the default new-work applies wherever image generation exists and nothing is recorded, and code-first on an app screen or document; name it rather than choosing a quieter one, because a silent default invented here is the same failure as a value written without an answer. Unset is a working state, not a gap: the decision page's toggle governs each session, and new-work's one-time offer records the answer the first time the user flips it. The config is the only place this lives. It is a workflow setting, not product truth, so it never joins ## Stack or any other PRODUCT.md section, where a second copy would outlive the setting and steer rounds nobody could trace back to it.

A value already recorded in .impeccable/config.json or the gitignored .impeccable/config.local.json is a confirmed answer: on a re-run, honor it in silence rather than asking again. This is a default, not a lock: the decision page renders a toggle whose flip binds a single session and is never written back. Without image generation there is no choice to record; code-first is the only path.

Then configure live mode when useful: skip native or non-runnable projects and leave existing config untouched. Otherwise follow live.md's first-time setup. Any CSP source edit still requires its stated consent.

Step 6: Wrap up or resume

Summarize captured and deliberately undecided facts. Do not offer DESIGN.md merely because it is missing.

Tell the user once which files to commit: PRODUCT.md, DESIGN.md, .impeccable/config.json, .impeccable/surfaces/, .impeccable/design.json, .impeccable/live/config.json, and .impeccable/critique/ignore.md. A blanket .impeccable/ ignore hides them from teammates and other worktrees. The runtime directories (questions/, mocks/, review/, critique snapshots) ignore themselves, and .impeccable/config.local.json stays on the developer's machine.

Recommend the next action from the actual project state:

• Empty or early project: ask naturally for the surface to be built, or use /impeccable shape <surface> when the user wants a confirmed brief without implementation. New-work will establish a visual world only when the requested work needs one.

• Existing coherent interface without DESIGN.md: /impeccable document if the user wants the incumbent system recorded independently of a new build.

• Existing surface needing work: name the most relevant scoped command.

• Web project ready for visual iteration: /impeccable live when configured.

If init was invoked by another request, resume without rerunning impeccable context; the native reference above is the one thing that run could not have given you, and new-work owns later visual decisions.