# Blueprint

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-big-emotion-agent-atelier-blueprint`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [big-emotion](https://agentstack.voostack.com/s/big-emotion)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [big-emotion](https://github.com/big-emotion)
- **Source:** https://github.com/big-emotion/agent-atelier/tree/main/plugins/frontend-fidelity/skills/blueprint

## Install

```sh
agentstack add skill-big-emotion-agent-atelier-blueprint
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Blueprint — Frontend Spec Pipeline

Extract a complete `specs/` directory from any frontend codebase. Covers all 12 axes needed to rebuild or migrate a frontend app. Produces ~80% quality on first pass, refined to ~95% through guided iteration.

**Input:** `$ARGUMENTS` = ` [options]`

Commands:
- `discover` — Scan codebase, create `specs/_pipeline.md`
- `scope` — Interactive: select views and axes to spec
- `extract [--view ] [--axis ]` — Extract specs (all, or resume one)
- `incorporate [--dir ]` — Analyze screenshots against visual specs
- `refine [--fix ]` — Quality audit, generate checklist
- `finalize` — Cross-references, known-gaps, rebuild-readiness
- `run` — Auto-advance state machine through all phases

Examples:
- `/blueprint run` — full pipeline from scratch (pauses at scope)
- `/blueprint discover` — scan only, create `_pipeline.md`
- `/blueprint scope` — select views interactively
- `/blueprint extract` — extract all pending axes
- `/blueprint extract --view home` — re-extract one view's functional spec
- `/blueprint extract --axis types` — re-extract just the types axis
- `/blueprint incorporate` — analyze screenshots in `specs/baseline/`
- `/blueprint refine` — run quality audit
- `/blueprint refine --fix RF-03` — address one checklist item
- `/blueprint finalize` — generate cross-refs + meta docs

---

## Phase 0: Parse `$ARGUMENTS`

Read `$ARGUMENTS`. The first token is the command. Parse as follows:

```
If $ARGUMENTS is empty or missing:
  → Print usage help (command list + examples above) and stop.

Commands:
  discover    → Jump to Phase 1
  scope       → Jump to Phase 2
  extract     → Jump to Phase 3
    Flags: --view   (extract only the named view's functional + visual specs)
           --axis   (extract only the named axis)
  incorporate → Jump to Phase 4
    Flags: --dir   (custom screenshot directory; default: specs/baseline/)
  refine      → Jump to Phase 5
    Flags: --fix   (address a specific checklist item only)
  finalize    → Jump to Phase 6
  run         → Jump to Orchestrator

Unknown command:
  → Print "Unknown command: {token}. Valid commands: run, discover, scope, extract, incorporate, refine, finalize." and stop.
```

---

## Phase 1: Discover (autonomous)

**Goal:** Scan the codebase. Build the inventory. Write `specs/_pipeline.md`.

### Step 1.1 — Detect framework

Read `package.json` (in the current working directory). Check `dependencies` and `devDependencies`:

| Dependency | Framework | Component glob |
|-----------|-----------|---------------|
| `react` or `react-dom` | React | `**/*.{tsx,jsx}` |
| `vue` | Vue | `**/*.vue` |
| `svelte` | Svelte | `**/*.svelte` |
| `@angular/core` | Angular | `**/*.component.ts`, `**/*.component.html` |
| `astro` | Astro | `**/*.astro` |

If none match, set framework = "Unknown" and continue.

### Step 1.2 — Detect styling approach

- If `tailwind.config.ts` or `tailwind.config.js` exists → Tailwind
- If `*.scss` files exist → SCSS
- If `*.module.css` files exist → CSS Modules
- If `styled-components` in deps → styled-components
- May be multiple (e.g., Tailwind + SCSS)

### Step 1.3 — Component inventory

Glob for component files using the framework-specific pattern. Exclude:
- `node_modules/**`
- `dist/**`, `build/**`, `.next/**`, `.nuxt/**`
- `**/*.test.*`, `**/*.spec.*`, `**/*.stories.*`

Count total components found.

### Step 1.4 — View detection

A "view" is a component that represents a route or page. Look for:
- Files in `pages/`, `views/`, `routes/`, `app/` directories
- Files matching `*Page.tsx`, `*View.tsx`, `*Screen.tsx`, `+page.svelte`
- Components referenced directly in a router config (``, `createBrowserRouter`, `createRouter`, `RouterModule`)
- The app entry point: `App.tsx`, `main.ts`, `app.component.ts`, `App.svelte`

For each detected view, record: view name (slug-friendly), component file path.

### Step 1.5 — Service layer detection

Glob for:
- `**/*{service,api,store,hook,composable}*`
- Files importing from `openai`, `@anthropic-ai/sdk`, `@google/generative-ai`, `cohere`, `mistralai`

If AI/LLM service files exist → mark `prompts` axis as applicable.

### Step 1.6 — Determine applicable axes

All projects: functional (per view), visual-foundations, visual-per-view, animations, interactions, i18n, types, assets, edge-cases, visual-mobile.

Optional (if detected):
- `prompts` — if AI service files found
- `known-gaps` — always generated in finalize (not extracted)

### Step 1.7 — Create `specs/_pipeline.md`

Run: `mkdir -p specs/baseline`

Write `specs/_pipeline.md`:

```markdown
# Blueprint Pipeline

## Meta

| Field | Value |
|-------|-------|
| Framework | {detected framework} |
| Styling | {detected styling} |
| Source root | {detected root, e.g., src/} |
| Created | {ISO timestamp} |
| Last phase | discover |
| Last run | {ISO timestamp} |

## Views

| View | Component | Status |
|------|-----------|--------|
{one row per detected view, Status = pending}

## Axes

| Axis | Output file | Status | Notes |
|------|------------|--------|-------|
| functional | {view}.md (per view) | pending | |
| visual-foundations | visual-foundations.md | pending | |
| visual-per-view | visual-{view}.md (per view) | pending | |
| animations | animation-trace.md | pending | |
| interactions | interaction-catalog.md | pending | |
| i18n | i18n.md | pending | |
| types | types.md | pending | |
| assets | assets.md | pending | |
| edge-cases | edge-cases.md | pending | |
| visual-mobile | visual-mobile.md | pending | |
{if prompts detected:}
| prompts | prompts.md | pending | |

## Screenshots

| File | Matched to | Status |
|------|-----------|--------|
(none yet)

## Refine Checklist

(not yet run)
```

### Step 1.8 — Report to user

```
Blueprint Discover complete.

Framework: {framework}
Styling: {styling}
Views found: {N} ({view-name-1}, {view-name-2}, ...)
Components found: {N}
Axes applicable: {N}
Prompts axis: {applicable/not applicable}

Created: specs/_pipeline.md
Created: specs/baseline/ (drop screenshots here for /blueprint incorporate)

Next step: Run /blueprint scope to select which views to spec.
```

---

## Phase 2: Scope (human input required)

**Goal:** Human narrows which views and axes to spec. Update `_pipeline.md`.

### Step 2.1 — Read current state

Read `specs/_pipeline.md`. Extract the Views table and Axes table.

### Step 2.2 — Present views for selection

Output:
```
Views discovered:

{numbered list of views with component file}

Which views do you want to spec?
- Type view names separated by commas (e.g., home, ideation)
- Or press Enter to spec ALL views
- Or type "skip: {names}" to exclude specific views
```

Wait for user response. Update Views table:
- Selected views → Status: `scoped`
- Skipped views → Status: `skipped`

### Step 2.3 — Present axes for selection

Output:
```
Axes that will be extracted:

{list of applicable axes with output file}

All axes are selected by default. Skip any? (type axis names to skip, or Enter to keep all)
```

Wait for user response. Update Axes table:
- Kept axes → Status: `pending`
- Skipped axes → Status: `skipped`

### Step 2.4 — Screenshot reminder

Output:
```
Screenshot integration:
- If you have screenshots of the app, drop PNGs into specs/baseline/
- Run /blueprint incorporate after /blueprint extract to match them against visual specs
- Screenshots are optional — you can skip incorporate and go straight to refine
```

### Step 2.5 — Update `_pipeline.md`

Update Last phase → `scope`. Update Last run timestamp.

Output:
```
Scope saved. {N} views scoped, {M} axes selected.

Next step: Run /blueprint extract to begin extraction.
```

---

## Phase 3: Extract (autonomous, resumable)

**Goal:** For each pending axis, read source, write spec file. Honor dependency order.

### Step 3.1 — Read state

Read `specs/_pipeline.md`. Get scoped views, pending axes.

If `--view ` flag: only process functional + visual axes for that view.
If `--axis ` flag: only process that specific axis.

### Step 3.2 — Dependency order

Run axes in this order (skip skipped axes, skip done axes):

**Group 1 — Independent (run first):**
1. `types` → `types.md`
2. `i18n` → `i18n.md`
3. `assets` → `assets.md`
4. `functional` → `{view}.md` for each scoped view (can run per-view in order)

**Group 2 — Depends on Group 1:**
5. `visual-foundations` → `visual-foundations.md`
6. `interactions` → `interaction-catalog.md`
7. `prompts` (if applicable) → `prompts.md`

**Group 3 — Depends on Groups 1+2:**
8. `visual-per-view` → `visual-{view}.md` for each scoped view
9. `animations` → `animation-trace.md`
10. `edge-cases` → `edge-cases.md`
11. `visual-mobile` → `visual-mobile.md`

### Step 3.3 — Per-axis extraction process

For each axis to process:

1. Read the corresponding template from `references/axis-templates.md` (the section matching the axis name)
2. Glob and read the source files specified in the template's "What to read" section
3. Extract content following the template's "What to extract" bullet list
4. Write the output file to `specs/{output-file}` using the template's "Output structure"
5. Apply the template's "Quality rules" — especially verbatim requirements
6. Update `_pipeline.md`: set axis Status → `done`

**If the extraction cannot be completed** (source files not found, framework unclear):
- Set axis Status → `partial` with a note in the Notes column
- Continue to next axis

### Step 3.4 — Key extraction rules (always enforced)

These rules apply regardless of which template is being used:

- **Verbatim over paraphrase:** Prompts, schemas, GLSL shaders, SVG paths, translation strings, type definitions — include the actual source code, never summarize
- **Line references:** Cite source as `Component.tsx:108-117` style for every specific finding
- **Companion docs line:** Every spec file opens with a `**Companion docs:**` line linking to related specs
- **Observations section:** Every spec ends with 3-5 non-obvious insights discovered during extraction

### Step 3.5 — Progress reporting

After each axis completes, output one line:
```
✓ {axis-name} → specs/{output-file} ({line-count} lines)
```

After all axes complete:
```
Extraction complete. {N} spec files written to specs/.

{list of output files with line counts}

Next steps:
- Drop screenshots in specs/baseline/ then run /blueprint incorporate
- Or skip to: /blueprint refine
```

Update `_pipeline.md` Last phase → `extract`, Last run → now.

---

## Phase 4: Incorporate (needs screenshots)

**Goal:** Compare screenshots against visual specs. Flag discrepancies.

### Step 4.1 — Check for screenshots

Glob `specs/baseline/*.png` (or custom `--dir` path).

If no PNGs found:
```
No screenshots found in specs/baseline/.

Add PNG screenshots to specs/baseline/ and re-run /blueprint incorporate.
Alternatively, proceed to /blueprint refine to audit spec quality without screenshot validation.
```

Update `_pipeline.md` with note: "No screenshots provided. Visual accuracy unverified." Stop.

### Step 4.2 — Match screenshots to specs

For each PNG file, attempt to match to a visual spec:
- Filename heuristic: `home-idle.png` → look for `visual-home.md`
- `ideation-loading.png` → look for `visual-ideation.md`
- Strips state suffixes: `-idle`, `-loading`, `-hover`, `-empty`, `-error`, `-mobile`
- If no match found, note as unmatched in `_pipeline.md` Screenshots table

### Step 4.3 — Visual comparison (per matched screenshot)

For each matched pair (screenshot → spec):

1. Read the screenshot image (multimodal read)
2. Read the corresponding `visual-{view}.md`
3. Compare what is visible in the screenshot against what the spec describes
4. Identify discrepancies:
   - Elements visible in screenshot but not mentioned in spec
   - Spec describes elements not visible in screenshot
   - Color/typography/spacing appears to differ from spec description
   - Layout differs from spec description

### Step 4.4 — Write corrections

For each spec with discrepancies, append:

```markdown
## Screenshot Corrections

*Source: specs/baseline/{filename}.png*

### Added (visible in screenshot, missing from spec)
- [description of element and where to add it in the spec]

### Removed (in spec but not visible in screenshot)
- [description of element that should be removed or marked uncertain]

### Corrections
- [spec says X, screenshot shows Y — update to reflect screenshot]
```

### Step 4.5 — Update `_pipeline.md`

Update Screenshots table with match status and correction summary.
Update Last phase → `incorporate`, Last run → now.

```
Screenshot incorporation complete.

{N} screenshots matched to specs
{M} discrepancies found across {K} specs
{P} screenshots unmatched

Specs updated with ## Screenshot Corrections sections.

Next step: /blueprint refine
```

---

## Phase 5: Refine (re-runnable quality audit)

**Goal:** Run all 6 quality checks. Generate a prioritized `RF-NN` checklist.

If `--fix ` flag: read `_pipeline.md` to find the item, address only that item, re-run that check category only.

### Step 5.1 — Read quality checklist

Read `references/quality-checklist.md`. The 6 checks are:
1. Verbatim Completeness
2. Cross-Reference Completeness
3. Interaction Completeness
4. Edge Case Completeness
5. Responsive Completeness
6. File Completeness

### Step 5.2 — Run each check

For each check, follow the instructions in `references/quality-checklist.md` exactly:
- Grep the appropriate files with the specified patterns
- Cross-reference findings against the specs
- Classify failures by severity (Fatal / High / Medium)
- Generate `RF-NN` items using the specified item format

Assign sequential IDs starting at `RF-01` across all checks. Fatal items first, then High, then Medium.

### Step 5.3 — Update `_pipeline.md`

Replace the `## Refine Checklist` section with:

```markdown
## Refine Checklist

*Last run: {ISO timestamp}*
*{N} total items: {F} Fatal, {H} High, {M} Medium*

### Fatal (blocks rebuild fidelity)
- [ ] `RF-01` ...
- [ ] `RF-02` ...

### High (degrades quality)
- [ ] `RF-03` ...

### Medium (nice to have)
- [ ] `RF-04` ...
```

If zero items:
```markdown
## Refine Checklist

*Last run: {ISO timestamp}*
*All checks passed. 0 items.*
```

Update Last phase → `refine`, Last run → now.

### Step 5.4 — Report to user

```
Refine complete.

{N} items found: {F} Fatal, {H} High, {M} Medium

{if Fatal items:}
Fatal items must be resolved before /blueprint finalize:
{list RF-NN items with description}

{if no Fatal items:}
No fatal items. Ready to run /blueprint finalize.

To fix a specific item: /blueprint refine --fix RF-NN
To fix all and re-audit: edit specs, then re-run /blueprint refine
```

---

## Phase 6: Finalize (autonomous)

**Goal:** Add cross-references, generate `known-gaps.md` and `rebuild-readiness.md`.

### Step 6.1 — Cross-references pass

Read all spec files in `specs/`. For each spec, check the `**Companion docs:**` line against the required cross-references defined in `references/quality-checklist.md` (Check 2 table).

Add any missing companion doc links to the appropriate spec file's Companion docs line. Do not remove existing links.

### Step 6.2 — Generate `known-gaps.md`

Scan all spec files for:
- The word "unclear"
- The phrase "not documented"
- Paraphrase signals: "similar to", "appears to", "roughly", "approximately"
- Empty sections in specs (heading present but no content below it)
- `## Screenshot Corrections` sections (indicates visual inaccuracies)
- Axes with Status = `partial` in `_pipeline.md`

Write `specs/known-gaps.md` following the template in `references/axis-templates.md` (Axis 12).

### Step 6.3 — Generate `rebuild-readiness.md`

Read `specs/_pipeline.md` Refine Checklist. Count items per axis.

Assign confidence per axis:

| Condition | Confidence |
|-----------|-----------|
| No items, no gaps | High |
| 1-2 Medium items only | High |
| 1-2 High items | Medium |
| Any Fatal items | Low |
| Axis not extracted (skipped/partial) | Low |

Write `specs/rebuild-readiness.md`:

```mar

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [big-emotion](https://github.com/big-emotion)
- **Source:** [big-emotion/agent-atelier](https://github.com/big-emotion/agent-atelier)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-big-emotion-agent-atelier-blueprint
- Seller: https://agentstack.voostack.com/s/big-emotion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.