Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/coding-agent/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,14 @@

## [Unreleased]

### Breaking Changes

- Changed the bundled builtin `open-claude-design` workflow's inputs: removed `reference`, `output_type`, and `design_system` in favor of a new `discovery` interview stage that asks for the output type and references. Inputs are now `prompt`, `discover_references`, and `max_refinements`. Drop those removed arguments from existing invocations and let discovery ask (or describe them in `prompt`).

### Added

- Restructured the bundled builtin `open-claude-design` workflow around the accessible `impeccable` skill. It now opens with a `discovery` stage (`/skill:impeccable shape`) that interviews you for a confirmed brief, the output type, and the references to emulate (references take precedence over `DESIGN.md`/`PRODUCT.md`); then **always** runs an `init` stage (`/skill:impeccable init`) that creates `PRODUCT.md`/`DESIGN.md` when missing and reconciles existing files against the brief (reusing the discovery answers); then a **single combined context phase** that concurrently runs design-system onboarding, the gated gallery `reference-discovery` pass (Awwwards, recent.design, Dribbble, Monet, Motionsites via `playwright-cli` — clicking into standout work to record a scroll-through video of each real design page so animations are captured, with a full-page screenshot fallback plus the real URLs, with a web-search fallback), and per-reference import before synthesizing the design system; then generation and impeccable `live`-driven in-browser refinement (`preview-display-*` drive `/skill:impeccable live`, capturing accepted variants and notes; degrades to `playwright-cli show --annotate`). A `discover_references` input (default `true`) gates the gallery pass. Updated the bundled workflow docs to describe the discovery interview, the trimmed input set, the always-run init, the combined context phase, references precedence, and live QA.

- Added the bundled builtin `goal` workflow's safe-by-default `create_pr` toggle and final `pull-request` stage. Goal now mirrors Ralph's PR handoff behavior: omitted or `false` skips PR/MR/review creation and omits `pr_report`, while strict `create_pr=true` authorizes only the final stage after reviewer quorum plus reducer approval to inspect the goal ledger, worker receipts, reviewer artifacts, final report, repository state, and provider credentials before attempting a provider-appropriate PR/MR/review request. Intermediate Goal worker/reviewer prompts now tell stages to ignore PR-creation requests so PR handoff stays confined to the final stage. Updated the bundled workflow docs, quickstart, README, and `/atomic` guide copy to describe the opt-in behavior.

## [0.9.0-alpha.3] - 2026-06-21
Expand Down
33 changes: 24 additions & 9 deletions packages/coding-agent/docs/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
| `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
| `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report → optional final-stage PR handoff after approval. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, name the validation that proves it is done, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true` after Goal reaches `complete`. |
| `ralph` | Prompt-refinement → research-prompt-refinement → codebase/online research → sub-agent orchestration → multi-model parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, and multi-package changes where you want Atomic to refine the prompt for clarity, transform it into a research question, research the codebase before implementing, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
| `open-claude-design` | Discovery interview (`/skill:impeccable shape`) → project-context setup (`/skill:impeccable init`, always — creates missing `PRODUCT.md`/`DESIGN.md`, reconciles existing) → a combined context phase (design-system onboarding + curated gallery reference-discovery + user-reference import, run concurrently) → HTML generation → impeccable `live`-driven interactive refinement → quality gate → rich HTML handoff. The discovery stage asks what to build, the output type, and which references to emulate (references take precedence over `DESIGN.md`/`PRODUCT.md`). Renders a live `preview.html` you can iterate against in the browser (opens through impeccable `live` / the `playwright-cli` skill when available). | UI, page, component, theme, or design-token work that benefits from a guided brief, beautiful references, and generation + critique loops. |

### `deep-research-codebase`

Expand Down Expand Up @@ -304,18 +304,18 @@ Inputs:

| Input | Type | Required | Default | Description |
|---|---|---|---|---|
| `prompt` | text | yes | — | What to design (dashboard, page, component, prototype, …). |
| `reference` | text | no | — | URL, file path, screenshot path, or design doc to import as a reference. |
| `output_type` | select | no | `prototype` | One of `prototype`, `wireframe`, `page`, `component`, `theme`, `tokens`. |
| `design_system` | text | no | — | Path(s) or description of an existing design system (e.g. `DESIGN.md`, `PRODUCT.md`). Skips onboarding when provided. |
| `prompt` | text | yes | — | What to design (dashboard, page, component, prototype, …). The discovery stage refines this into a confirmed brief and asks for the output type and references. |
| `discover_references` | boolean | no | `true` | Discover beautiful, current reference designs (Awwwards, recent.design, Dribbble, Monet, Motionsites) and feed them to generation. Set `false` to skip the network/browser reference pass. |
| `max_refinements` | number | no | `3` | Maximum critique/apply refinement iterations. |

The output type (`prototype`, `wireframe`, `page`, `component`, `theme`, `tokens`) and any reference designs are **not** inputs — the discovery stage asks for them. There is no `design_system` input; the project's `DESIGN.md`/`PRODUCT.md` are established/loaded automatically.

Result fields:

| Field | Meaning |
|---|---|
| `output_type` | Kind of design artifact produced. |
| `design_system` | Design system source used for generation: supplied input or project-derived design system. |
| `output_type` | Kind of design artifact produced (chosen during the discovery interview). |
| `design_system` | Design system source used for generation: the project-derived design system. |
| `artifact` | Latest final design summary from the approved preview artifact. |
| `handoff` | Final rich HTML spec and implementation handoff summary. |
| `approved_for_export` | Whether refinement completed before the final export gate. |
Expand All @@ -331,14 +331,29 @@ Result fields:

`open-claude-design` has no `result` output; it exposes only the declared fields listed above. Use the declared `artifact` and `handoff` fields for generated content.

**Discovery interview.** The workflow's first stage runs `/skill:impeccable shape` to interview you (via the structured question tool) about what you want to build, the **output type** (`prototype`, `wireframe`, `page`, `component`, `theme`, or `tokens`), and which **references** to emulate (URLs, local file paths, screenshots, or design docs). It produces a confirmed design brief; the references you name take **precedence over `DESIGN.md`/`PRODUCT.md`** during generation (the design system fills gaps the references don't cover, and `PRODUCT.md` still governs strategic register/voice). Headless runs infer a defensible brief, output type, and references rather than blocking.

**Project design context (init).** After discovery, the workflow **always** runs an `init` stage that invokes `/skill:impeccable init` (reusing the discovery answers so it doesn't re-ask). It deterministically detects whether `PRODUCT.md` and `DESIGN.md` exist (project root, `.agents/context/`, or `docs/`, case-insensitive): it **creates** whichever is missing (capturing register, users/purpose, brand personality, anti-references, and accessibility needs) and **reconciles** any that already exist against the discovery brief, refreshing only genuine gaps and never clobbering them. This step is best-effort and never blocks the run.

**Combined context phase.** Onboarding, gallery reference discovery, and user-reference import all run **concurrently in a single fan-out**, then the design-system synthesis closes it out:

- *Design-system onboarding* — three parallel passes (`ds-locator` / `ds-analyzer` / `ds-patterns`) extract the project's design-system evidence, which `design-system-builder` synthesizes into the working design system.
- *Reference discovery* (gated by `discover_references=true`, the default) — the `reference-discovery` stage uses the `playwright-cli` skill to browse five curated galleries — [Awwwards](https://www.awwwards.com/websites/), [recent.design](https://recent.design/), [Dribbble recents](https://dribbble.com/shots/recent), [Monet](https://www.monet.design/c), and [Motionsites](https://motionsites.ai/) — then **clicks into the standout work** and, ideally, **records a scroll-through video of each real design page so its animations are captured** (with a full-page screenshot as a supplement/fallback) plus the real destination URL (it does not just screenshot the gallery thumbnails; web-search fallback when the browser is unavailable), persists the curated **references brief** to `<artifact_dir>/references.md`, and threads it into the generator (`reference_inspiration`) and refinement. Set `discover_references=false` to skip it.
- *Reference import* — each reference the discovery interview collected is imported (`web-capture-<n>` for URLs, `file-parser-<n>` for files/screenshots); the extracted requirements feed the generator and **take precedence over `DESIGN.md`/`PRODUCT.md`**.

**Interactive live QA.** The `preview-display-*` stages drive `/skill:impeccable live` against the static `preview.html`: you pick elements in the browser, annotate them, and compare three on-brand variants, accepting one that is written into the preview in place. Accepted variants and your notes are captured (`live_changes` / `user_notes` / `annotated_snapshot`) and threaded through the refinement loop as the **primary** signal: the `user-feedback-*` stage receives them in a dedicated `user_annotations` block (and will not approve export while honest feedback is unaddressed), and the `apply-changes-*` stage consumes a merged refinement brief that orders your annotations and accepted live edits **above** the internal critique and screenshot/visual-QA findings. When `/skill:impeccable live` cannot boot, the stage degrades to `playwright-cli show --annotate`, then to a manual file path. Captured feedback is persisted as durable artifacts under `<artifact_dir>/feedback/iteration-<n>.md` / `.json` (plus a best-effort copy of the annotated snapshot). If a preview captured notes but they fail to thread into the apply stage, the run fails loudly rather than silently refining from internal critique alone.

Run examples:

```text
/workflow open-claude-design prompt="Refresh the settings page hierarchy"
/workflow open-claude-design prompt="Design a billing page" reference=https://stripe.com/billing output_type=page
/workflow open-claude-design prompt="Generate spacing and color tokens" output_type=tokens design_system=./DESIGN.md
/workflow open-claude-design prompt="Design a billing page like Stripe's"
/workflow open-claude-design prompt="Generate spacing and color tokens"
/workflow open-claude-design prompt="Design a marketing landing page" discover_references=false
```

The discovery interview asks for the output type and any reference URLs/files, so you no longer pass `output_type`, `reference`, or `design_system` on the command line.

### Launching with natural language

You can also kick off a built-in workflow by describing the task in chat. Atomic picks the matching workflow and fills in inputs from your request:
Expand Down
11 changes: 11 additions & 0 deletions packages/workflows/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

### Breaking Changes

- Restructured the builtin `open-claude-design` workflow's input contract. Removed the `reference`, `output_type`, and `design_system` inputs; the workflow now gathers those through a new `discovery` interview stage instead. The remaining inputs are `prompt`, `discover_references`, and `max_refinements`. Existing invocations that passed `reference=…`, `output_type=…`, or `design_system=…` should drop those arguments and let the discovery stage ask for the output type and references (or describe them in `prompt`).

### Added

- Restructured the builtin `open-claude-design` workflow around the accessible `impeccable` skill (`/skill:impeccable …`). The new phase order is: (1) **discovery** — a `discovery` stage runs `/skill:impeccable shape` to interview the user (via the structured question tool) for a confirmed design brief, the output type (`prototype`/`wireframe`/`page`/`component`/`theme`/`tokens`), and the references to emulate (URLs/files/screenshots/design docs), returning a structured `{ brief, output_type, references }`; (2) **init (always runs)** — `ensureProjectDesignContext` invokes `/skill:impeccable init` on every run, reusing the discovery answers; it detects `PRODUCT.md`/`DESIGN.md` (root, `.agents/context/`, or `docs/`, case-insensitive), creates whichever is missing, and reconciles existing files against the brief without clobbering them; (3) **a single combined context phase** — one concurrent `ctx.parallel` fan-out runs design-system onboarding (`ds-locator`/`ds-analyzer`/`ds-patterns`), the gated gallery **reference-discovery** (Awwwards, recent.design, Dribbble, Monet, Motionsites via `playwright-cli` — clicking into standout work to record a scroll-through video of each real design page so its animations are captured, with a full-page screenshot as a supplement/fallback and the real destination URL, not just the gallery thumbnails — with a web-search fallback, persisted to `<artifact_dir>/references.md`), and per-reference **import** (`web-capture-<n>` / `file-parser-<n>`) together, after which `design-system-builder` synthesizes the design system; (4) **generation**; (5) **live-driven refinement**; (6) export. User-provided references take **precedence over `DESIGN.md`/`PRODUCT.md`** (a shared `REFERENCE_PRECEDENCE` note is threaded into the import, generator, and apply-changes prompts; `DESIGN.md` fills gaps the references don't cover, `PRODUCT.md` still governs strategic register/voice). The `preview-display-*` stages drive `/skill:impeccable live` against the static `preview.html` for in-browser element-level variant QA, capturing accepted variants via a new `live_changes` field threaded through the refinement feedback; live degrades to `playwright-cli show --annotate` then a manual file path. New logic lives in `open-claude-design-setup.ts` (`runDiscovery`, `detectDesignContextFiles`, `ensureProjectDesignContext`, `buildReferenceDiscoveryPrompt`, `persistReferencesBrief`, `buildLivePreviewDisplayPrompt`) and `open-claude-design-utils.ts` (`discoveryDecisionSchema`, `discoveryDecisionFromResult`, `REFERENCE_PRECEDENCE`) to keep the runner and phases files under the 500-line file-length gate. Added unit coverage for the discovery schema/parse, discovery prompt, always-run init + reconcile + discovery-context threading, the combined context fan-out, reference-discovery prompt/persist, the live-QA prompt, the trimmed input contract, a full-run `init` path, and `live_changes` capture/threading/persistence.

- Added a safe-by-default `create_pr` toggle to the builtin `goal` workflow, matching Ralph's final-stage PR handoff behavior. Goal now skips PR/MR/review creation unless `create_pr=true` **and** reviewer quorum plus the reducer mark the run `complete` within the turn budget, omits `pr_report` when disabled or not approved, and runs a provider-aware `pull-request` stage only at the end when explicitly authorized. The final stage reads the goal ledger, worker receipts, latest review artifact, final report, and sanitized `base_branch` before attempting GitHub, Azure Repos, GitLab, Bitbucket, Sapling, or Phabricator handoff tooling. Goal worker/reviewer prompts now include an intermediate-stage guardrail telling them to ignore PR-creation requests because only the final `pull-request` stage may attempt that handoff.

### Fixed

- Fixed the builtin `open-claude-design` workflow dropping interactive Playwright annotation feedback between the `preview-display-*` stages and the downstream `user-feedback-*` / `apply-changes-*` refinement stages, so a user could annotate a preview and watch the next iteration apply only internal critique while the design stayed visually unchanged ([#1464](https://github.com/bastani-inc/atomic/issues/1464)). The initial and per-iteration `preview-display-*` results are now captured instead of awaited-and-discarded, parsed for the user's `user_notes` / `annotated_snapshot` (tolerant of heading/bullet/bold/backtick label styles and placeholder values), and carried through the refinement loop as a `previewFeedbackHistory` so every later iteration honors earlier annotations. `user-feedback-*` now receives the captured annotations as the PRIMARY signal in a dedicated `<user_annotations>` block (and is told not to approve export while honest user feedback is unaddressed); `apply-changes-*` now consumes a single merged refinement brief built by the new `open-claude-design-feedback.ts` helper that orders **user annotations above** the reviewer decision, impeccable critique, and screenshot/visual-QA findings, with a prompt contract requiring each annotation to be visibly addressed or explicitly explained as a DESIGN.md conflict. Captured annotations are also persisted as durable workflow artifacts under `<artifact_dir>/feedback/iteration-<n>.md` / `.json` (and a best-effort copy of the annotated snapshot `.png`/`.yaml`). A guardrail runs before each apply stage: if a `preview-display-*` stage captured `user_notes` but they did not thread into the apply prompt, the workflow now fails loudly instead of silently refining without user feedback. Added regression coverage that a `preview-display-*` annotation result threads verbatim into both `user-feedback-*` and `apply-changes-*` (ordered above internal critique) plus unit coverage for the parser, merged-brief ordering, guardrail, fallback, and artifact persistence.
- Fixed the builtin `open-claude-design` workflow polluting the project's `specs/design/` tree with per-run artifact folders during automated test runs; `prepareArtifactDir` now writes to the OS tmpdir when `NODE_ENV=test`.

## [0.9.0-alpha.3] - 2026-06-21

### Added
Expand Down
Loading
Loading