Skip to content

Worked example: agentic design development reference mining

Generated by the agentic-design-development route (skills/website-improvement, skills/design-system-builder, skills/handoff-spec). Demonstrates how external references become internal design-ai skill and feature work without copying visuals, code, or proprietary workflows.

Brief: Use OpenTag, Open Design, WWIT, and React Bits references to develop internal design-ai skills, SDK workflows, MCP feature surfaces, and approval-gated previews.

Grounding: cite knowledge/PRINCIPLES.md, knowledge/patterns/agentic-design-workflows.md, knowledge/patterns/design-system-qa.md, knowledge/patterns/technical-writing.md, docs/AGENT-DEVELOPMENT.md, docs/SDK.md, and docs/MCP-INTEGRATION.md before implementing this plan.

# Agentic design development plan

## 1. Artifact contract

| Field | Decision |
| --- | --- |
| Mode | Internal design-ai feature slice and skill-playbook update |
| Source of truth | `knowledge/patterns/agentic-design-workflows.md`, `docs/AGENT-DEVELOPMENT.md`, `docs/SDK.md`, `docs/MCP-INTEGRATION.md`, and the current route/check/test code |
| Output | Markdown plan, route/check implementation, SDK/MCP surface notes, and regression tests |
| Preview surface | CLI `route`, `prompt`, `examples`, and `check --examples --all-routes`; MCP clients consume the same route catalog through `design_ai_route` |
| Mutation boundary | Local repo writes only. No target-repo mutation, GitHub issue creation, Slack post, Notion page, npm publish, or deployment happens without a separate human approval gate. |
| Verification | `node --test` for route/prompt/check/example behavior, `design-ai check --examples --route agentic-design-development --strict --json`, `npm run audit:strict`, and `git diff --check` |

## 2. Reference mining

| Reference | Pattern extracted | Internal mapping | Do-not-copy boundary |
| --- | --- | --- | --- |
| OpenTag | Rich inline agent results and approval before external writes | Add route checklist language for human approval gate, structured preview, and post-decision evidence | Do not copy Slack UI, exact copy, or CopilotKit implementation details |
| Open Design | Agent-native studio with design contracts, local preview, plugin packaging, and MCP install path | Map to `DESIGN.md` brand contract guidance, SDK/MCP surface notes, and package-readiness checks | Do not copy brand templates, screenshots, plugin manifests, or repo-specific file structure |
| WWIT | Korean app pattern taxonomy by category, flow, and component | Use as a taxonomy pass before designing Korean consumer flows; compare at least three examples before claiming a convention | Do not copy app screenshots or treat one app as a market rule |
| React Bits | Animated component categories, variants, dependency disclosure, and copy-ready adoption | Add an animated component adoption gate: intent, dependency, customization, reduced motion, performance, ownership, and verification command | Do not copy code without license review or install a dependency for decorative motion only |

Ownership and license check: every adopted pattern is paraphrased into local rules. Code copying requires a license review, attribution decision, maintenance owner, and package-size review before implementation.

## 3. Internal feature slice

### Route

- Add or update an `agentic-design-development` route for briefs that mention internal skill development, design-ai feature development, reference mining, artifact contract, approval gate, MCP tool, SDK surface, or plugin surface.
- Curated files: `knowledge/patterns/agentic-design-workflows.md`, `knowledge/patterns/design-system-qa.md`, `knowledge/patterns/technical-writing.md`, `docs/AGENT-DEVELOPMENT.md`, `docs/SDK.md`, and `docs/MCP-INTEGRATION.md`.
- Verification command: `node cli/bin/design-ai.mjs route "internal skill development with reference mining and MCP feature surface" --limit 1 --json`.

### Prompt plan

- Prompt checklist must separate reference mining from implementation changes.
- Each adopted pattern maps to a skill/playbook, CLI/SDK/MCP surface, verification command, rollout boundary, reviewer-facing evidence, and human approval gate.
- Verification command: `node cli/bin/design-ai.mjs prompt "Use OpenTag and React Bits to develop internal design-ai features" --json`.

### Check and example QA

- Add route-specific checks for artifact contract, source of truth, mutation boundary, reference mining, do-not-copy boundary, license or ownership, CLI/SDK/MCP surface, verification command, and human approval gate.
- Canonical example: this file.
- Verification command: `node cli/bin/design-ai.mjs check --examples --route agentic-design-development --limit 1 --strict --json`.

### Skill proposal loop

- Repeated `check:agentic-design-development` captures should propose an internal agentic-development checkpoint, not a generic workflow note.
- The proposed instruction must include skill delta, CLI/SDK/MCP surface, verification command, rollout boundary, human approval gate, and do-not-copy/licensing note.
- Verification command: `node --test cli/lib/learn-skill-proposals.test.mjs`.

## 4. Approval gates

| Action | Human approval gate | Evidence after decision |
| --- | --- | --- |
| Create GitHub/Linear/Notion/Slack task | Show destination, title, body summary, owner/priority if present, and Create/Cancel choice | Link or explicit skipped status in the handoff log |
| Edit a target repo | Show repo intake, changed files, diff preview, test command, and rollback note before mutation | Commit/PR link or local diff summary |
| Publish npm package or deploy docs | Show version, target, environment, changelog scope, rollback path, and verification plan | Release run, registry smoke, or deployment URL |
| Install animation dependency | Show product intent, bundle risk, reduced-motion behavior, ownership, and license note | Dependency diff, package check, and accessibility verification |

## 5. Accessibility and UI preview requirements

- Contrast: any preview card or structured table must maintain at least 4.5:1 contrast for body text and visible focus outlines.
- Keyboard: action previews expose a keyboard-reachable primary action, secondary cancel action, Escape behavior for modal previews, and `focus-visible` styling.
- Screen reader: status cards use semantic headings, action buttons have explicit labels, table headers use `scope="col"`, and approval state changes are announced with `aria-live="polite"`.
- Responsive behavior: desktop can show a two-column evidence table; tablet keeps the table readable; mobile collapses each row into a stacked card with the action and verification command still visible.
- Reduced motion: animated component previews respect `prefers-reduced-motion`; looped decorative motion provides pause/stop/hide behavior or is disabled.

## 6. Done when

- `route` selects `agentic-design-development` for internal skill and design-ai feature development briefs.
- `prompt` includes the agentic workflow knowledge, SDK/MCP docs, and approval-gate checklist.
- `examples --route agentic-design-development` returns this canonical worked example.
- `check --examples --route agentic-design-development --strict` passes with route-specific requirements.
- `learn --propose-skills` maps repeated captures to an internal agentic-development checkpoint.
- README and roadmap describe the new route honestly as unreleased local work until a versioned release ships.

## Don't

- Do not copy visual assets, screenshots, UI copy, repo structure, or code from external references without license review.
- Do not let reference mining become a vague inspiration note; every adopted pattern needs a local mapping and verification command.
- Do not create external tasks, publish packages, deploy docs, or mutate a target repo without a visible human approval gate.
- Avoid adding animation libraries for one hover state; adapt motion into the existing token and reduced-motion system first.
- Do not claim Korean-market convention from a single WWIT example; compare multiple examples and mark the conclusion as judgment when evidence is thin.

Why this is a good agentic-development example

  • It starts with an artifact contract: source of truth, preview surface, mutation boundary, and verification are explicit before any implementation.
  • Reference mining is taxonomy extraction, not cloning: each reference has a local mapping and a do-not-copy boundary.
  • The internal feature slice names the exact design-ai surfaces: route, prompt, check, examples, SDK, MCP, and skill proposal loop.
  • Human approval gates are visible for external writes, target repo edits, npm publish/deploy actions, and dependency adoption.
  • Accessibility is operational: contrast 4.5:1, keyboard/focus behavior, screen reader semantics, responsive behavior, and reduced motion are all stated.

Cross-reference