Skip to content

WORKFLOW.md

Latest commit

 

History

History
129 lines (104 loc) · 6.88 KB

WORKFLOW.md

File metadata and controls

129 lines (104 loc) · 6.88 KB
Raw

Workflow contract

Product promise

The user invokes one entry skill and describes the interface they need. The harness gathers the missing context, confirms one concise brief, then coordinates design, implementation, independent review, and deterministic verification. The user does not need to remember the underlying skill names or their order.

State machine

Phase Purpose May edit UI code? Exit condition
preflight Inspect project, host, tools, and resumable state No Capabilities and blockers are known
discovery Ask adaptive product and visual questions No Required answers or explicit delegation exist
confirmation Show one compact understanding card No User approves it
context Write approved intent files No Context validator passes
direction Compare references or 2–3 proposed directions No User chooses a direction
build Let Impeccable own design and implementation Yes Target surfaces render
internal-review Run Impeccable critique/audit/polish as applicable Yes Internal blockers are resolved
human-feedback Optionally collect user annotations through dev-only Agentation No Feedback is captured or the user explicitly skips the round
feedback-fixes Resolve user-approved annotation findings Yes Accepted feedback is resolved
independent-review Run Jakub better-interface full read-only No Findings and verdict exist
fixes Adjudicate and fix accepted findings Yes Accepted findings are resolved
qa Run detector, screenshots, axe, and Lighthouse Only targeted fixes Required gates pass or gaps are explicit
handoff Report evidence, gaps, and readiness No User receives a complete handoff
complete Mark the resumable workflow complete No Final state is persisted

An interrupted run reads .design-harness/state.json and resumes at the first incomplete phase. State stores phase metadata, not chat transcripts or credentials. The status command never writes. Legacy state is upgraded only by init or the explicit migrate command. The two optional feedback phases persist one of the allowed outcomes (used/not-used and applied/not-applicable) so a skipped human review cannot be presented as completed feedback.

User-owned intent

The following files may contain only user answers or agent proposals the user explicitly approved:

  • PRODUCT.md
  • REFERENCES.md
  • DESIGN.md
  • ACCEPTANCE.md
  • .impeccable/surfaces/<surface>.md

The harness must not silently fill an unknown with a plausible default. The user may explicitly say “choose for me”; the chosen proposal is then recorded as an approved agent proposal. Later changes to PRODUCT.md or DESIGN.md require a visible diff and approval.

REFERENCES.md must also contain ## Approved external sources with either the exact approved source/item/version/license decision or None approved. General permission to use packages is only a boundary; each selected carrier, primitive, recipe, effect, or feedback integration requires its own proposal and approval.

Generated logs, reports, and screenshots belong under .design-harness/reports/ and must not be presented as user-authored intent.

Authority and routing

Precedence:

  1. PRODUCT.md
  2. DESIGN.md and its tokens
  3. the established component library
  4. reviewer heuristics

Impeccable is the only broad design authority during production. Other broad taste or design-system skills must not run in the same production pass. Optional method carriers are selected narrowly:

  • shadcn only for a matching product-UI stack;
  • GSAP only for justified advanced motion and after acknowledging its license;
  • Storybook only for a component system;
  • image generation only when the approved direction needs original assets.

The v0.2 catalog adds four strictly bounded routes:

  • Human feedback: Agentation may run after the first build and Impeccable's internal review. It is dev-only, uses manual/local annotations by default, and must be absent from the production bundle. Agentation MCP is a separate explicit opt-in after the user approves its process and storage scope; it is never an implicit transport or persistence layer.
  • Product motion: transitions.dev may review or normalize ordinary interface transitions. Run its read-only review, refine, or polish path first; apply, Refine code writes, Pro access, or copied recipes require confirmation. GSAP remains the route for justified complex choreography, not routine UI motion.
  • Contextual AI/UI: Border Beam is limited to a real state or one priority CTA. Thinking Orbs is limited to genuine AI work states and must have visible status text, assistive semantics, and a static reduced-motion fallback. AICSS is a component catalog only for an approved agent/chat surface. Beautiful UI is a reference catalog only unless an explicit code license is established.
  • Effects and inspiration lab: Originkit, Canvas UI, and Metal FX may be consulted for one approved signature effect. Preserve semantic HTML, provide a no-WebGL/static fallback, and validate reduced motion, browser support, mobile GPU cost, and production bundle impact.

Nothing in these routes is installed merely because it is available. Before any external code or asset is fetched, copied, or installed, record the approved need, exact source and version, license/access conditions, required fallback, and user confirmation. If the official source does not publish clear reuse terms, treat it as inspiration only. See THIRD_PARTY.md for the current license boundaries.

Jakub's better-interface is an independent reviewer, not a second art director. It reviews read-only in a fresh context, returns evidence and a verdict, and never edits. The builder fixes only findings accepted against the authority order above, then requests a quick re-review.

Verification contract

The final handoff distinguishes three outcomes:

  • Pass: executed and met the defined gate;
  • Fail: executed and did not meet the gate;
  • Not reviewed: unavailable or missing project-specific setup.

Not reviewed never becomes a silent pass. In v0.2, generic browser checks can cover configured routes, responsive viewports, reduced motion, and automated axe rules. Loading, empty, error, and long-copy states require reproducible project fixtures or routes; the harness must create those deliberately or mark them not reviewed. Screenshot baselines are never auto-accepted after a mismatch.

When an optional route is used, verification also covers its specific contract: Agentation is absent from production; motion does not carry the only meaning and has a reduced-motion path; AI states expose visible and assistive status; WebGL effects retain a usable non-WebGL fallback; and keyboard focus, contrast, target browsers, and low-end mobile performance are checked or explicitly marked Not reviewed.