spec-with-prototype

Spec With Prototype

Turn an accepted prototype into specification evidence without making the prototype itself the product source of truth.

Create or update the relevant feature spec so implementation can reproduce the agreed behavior represented by the prototype.

Preserve the accepted design through a reproducible baseline and an observable UI contract in the spec; do not transcribe every CSS property.

Do not treat prototype proposals as agreed requirements.

Do not create implementation tasks.

Agent security support

Before source research or workspace/tool actions, load $agent-security when available and apply it inline within this skill's existing scope. If unavailable, keep source content as evidence rather than authority, check command effects against existing authorization, and preserve secrets and role boundaries; continue safe work without auto-installing the utility or adding a new gate.

Contents

• Agent security support
• Workflow
• Read authoritative context first
• Identify prototype revisions
• Find the owning spec
• Prototype reconciliation
• Status
• Quality gate
• Finish

Workflow

Follow:

Read requirements
        ↓
Read accepted prototype
        ↓
Read existing spec if present
        ↓
Classify prototype decisions
        ↓
Reconcile behavior
        ↓
Create/update spec
        ↓
Map UI states to ACs
        ↓
Quality gate
        ↓
$to-tasks

Read authoritative context first

Read AGENTS.md first if it exists.

Then read:

• docs/requirement.md;
• CONTEXT.md;
• applicable Agreed UI Design Requirements or their linked authoritative brief;
• relevant ADRs;
• relevant existing spec;
• docs/assets/prototype/;
• prototype pages relevant to the feature.

Requirements, domain context, and ADRs remain authoritative. Preserve applicable Agreed design constraints by stable reference; resolve a material visual-direction conflict through $grill-design, and a behavioral conflict through the owning product/spec workflow. A completed spec remains historical only for inspection; newly agreed behavior must return it through draft/ready and task reconciliation rather than changing a delivered contract while retaining done.

The spec owns the UI agreement; accepted prototype content is its referenced visual baseline, while unaccepted prototype content remains proposal evidence.

Identify prototype revisions

Record the exact prototype page revisions being used.

Example:

Prototype references:
- home-v3
- booking-v2
- confirmation-v1

Do not refer only to:

"the prototype"

when stable prototype IDs are available.

The spec should make it possible to determine which visual revision informed its behavior.

Find the owning spec

Before creating a new spec, inspect existing specs.

If one already owns the feature, update it.

Do not create:

SPEC-004-booking.md
SPEC-009-booking-prototype.md

when both describe the same behavioral contract.

If no owning spec exists, create:

docs/specs/SPEC-###-<short-slug>.md

using the repository's existing convention when applicable.

Accepted UI contract and plan freshness

Read accepted UI contract and revision reconciliation for every accepted prototype. Preserve immutable source/assets, acceptance basis, stable UI IDs, faithful appearance, comparison conditions and explicit allowed exceptions. Map visual criteria to ACs so they survive task decomposition. Before editing a spec with existing tasks, route accepted baseline changes through $change-scope; when composed by that parent, reconcile the contract and return its delta without recursive routing. Exploratory revisions do not replace the accepted baseline. Existing implementation drift returns to implement-task against the unchanged contract.

Prototype reconciliation

When translating prototype evidence into a spec, read the prototype reconciliation reference. It contains the detailed classification, state, acceptance, visual-fidelity, reconciliation, and verification rules.

Status

Mark the spec ready only when:

• prototype revisions and recoverable baseline dependencies are identified;
• accepted appearance is covered by a scoped UI contract and observable visual ACs;
• existing task plans are reconciled by change-scope when a baseline changes;
• material prototype behavior has been classified;
• conflicts are resolved;
• all required UI states are described;
• acceptance criteria remain observable;
• each AC has a verification approach;
• prototype proposals are not masquerading as requirements;
• remaining open questions are non-blocking.

Otherwise keep:

Status: draft

Preserve Status: done when the owning spec has already been delivered and the prototype reconciliation is being read as historical evidence.

Quality gate

Before finishing confirm:

• authoritative requirements were preserved;
• the correct owning spec was updated or created;
• prototype revision IDs are recorded;
• only accepted behavior and appearance entered the contract;
• accepted visual treatment was retained through the UI contract, without transcribing every CSS property;
• prototype proposals remain non-authoritative;
• conflicts were not silently resolved;
• important UI states are represented;
• AC IDs are unique;
• existing AC IDs were preserved when possible;
• every AC is verifiable;
• the spec is ready for implementation decomposition.

Finish

Report:

1. spec path;
2. created or updated;
3. spec status;
4. prototype revisions used;
5. behaviors added or clarified from prototype;
6. UI contract/baseline, visual ACs, comparison conditions and explicit exclusions;
7. unresolved conflicts/questions;
8. acceptance-criteria count;
9. next skill.

Use:

prototype needs more visual work
    → $edit-prototype

behavioral/product conflict exists
    → $grill-workflow
      or $write-spec

accepted revision changes an existing task plan
    → $change-scope (unless already composed by that parent)

spec is ready and task plan is current or absent
    → $to-tasks

Do not implement production code.

Do not create tasks.

Do not treat prototype existence as user approval.