Extract high-value design workflow patterns from nexu-io/open-design

[ramsani]

Intent

Extract the highest-value workflow, quality, exploration, contribution, and artifact-control patterns from nexu-io/open-design into html-explainer without copying its product scope, runtime architecture, UI, or design-system library.

The goal is protocol extraction, not product cloning.

Reference repo:

https://github.com/nexu-io/open-design

Core thesis

The valuable substance in Open Design is not simply visual design. It is a control system for agent-produced artifacts:

brief -> discovery -> mode/pattern -> skill context -> references/checklist -> artifact -> preview/export -> persistence -> re-entry

The equivalent for html-explainer should become:

user intent -> decision gate -> artifact direction -> pattern -> evidence/fact sheet -> checklist -> HTML artifact -> local artifact memory -> actionable knowledge base -> re-entry prompt

User outcome

After this work, future agents should generate better html-explainer artifacts because they have:

• stronger discovery before generation;
• deterministic artifact directions;
• mode-level routing above individual patterns;
• package-like pattern conventions;
• P0/P1/P2 gates;
• anti-slop rules;
• honest placeholders;
• preview/export/archive rules;
• knowledge-base re-entry hooks;
• clear contribution units.

What to extract and adapt

1. Discovery gate before artifact generation

Open Design uses discovery before generation.

Adaptation for html-explainer:

Create a stronger pre-artifact intake model for complex cases.

Inputs should include:

• artifact surface/type;
• audience;
• decision the user needs;
• available evidence;
• missing evidence;
• freshness risk;
• privacy risk;
• desired action after artifact;
• whether interaction/export is justified;
• whether artifact memory entry is justified.

Potential output:

docs/ARTIFACT_DISCOVERY_GATE.md

Only update docs/DECISION_GATE.md if the change is surgical and consistent.

2. Deterministic artifact directions

Open Design uses curated directions instead of letting the model freestyle.

Adaptation for html-explainer:

Define deterministic cognitive/visual directions for decision surfaces.

Candidate directions:

• evidence-first audit;
• decision deck;
• risk map;
• implementation control panel;
• knowledge card explorer;
• workflow debugger;
• prompt behavior tuner;
• repo re-entry map;
• comparison matrix;
• incident timeline.

Potential output:

docs/ARTIFACT_DIRECTIONS.md

Purpose: reduce generic dashboards and model freestyle.

3. Artifact modes above patterns

Open Design distinguishes modes as workflow containers.

Adaptation for html-explainer:

Define modes above the 21 patterns:

• explain: concept or research explainer;
• review: plan, diff, PR, artifact audit;
• map: repo, module, architecture, workflow;
• decide: comparison, decision deck, trade-off map;
• tune: prompt, agent, skill, rubric;
• remember: artifact memory, knowledge base, re-entry.

Potential output:

docs/ARTIFACT_MODES.md

4. Skills/patterns as portable capability folders

Open Design treats skills as atomic folders with instructions, assets, references, and examples.

Adaptation for html-explainer:

Define a future pattern package protocol.

A mature pattern package may contain:

PATTERN.md
checklist.md
example.html
metadata.json
assets/
references/

Do not migrate all patterns now. First define the convention.

Potential output:

docs/PATTERN_PACKAGE_PROTOCOL.md

5. Extended metadata/frontmatter for patterns

Open Design uses structured skill metadata.

Adaptation for html-explainer:

Patterns should eventually declare machine-readable intent and constraints.

Example metadata:

pattern: 17-project-recap
mode: map
artifact_type: project-recap
recommended_budget: standard
supports_interaction: false
requires_evidence:
  - README
  - entry points
  - scripts
  - CI
outputs:
  primary: html
  secondary:
    - handoff_prompt
    - artifact_metadata
quality_gates:
  - evidence_visible
  - risk_visible
  - next_action_visible
memory:
  default_validity: replaceable
  freshness_risk: medium

This would improve routing, validation, and artifact memory.

6. P0 / P1 / P2 artifact quality gates

Open Design uses hard gates.

Adaptation for html-explainer:

Split quality into:

• P0: must pass or do not deliver;
• P1: required for serious work;
• P2: polish if budget allows.

P0 examples:

• primary intent visible above the fold;
• evidence basis visible;
• facts/inferences/unknowns separated;
• no fake metrics;
• no unsupported repo claims;
• recommendation visible;
• next prompt copy-ready;
• HTML advantage explicit.

Potential output:

docs/ARTIFACT_CHECKLISTS.md

Update docs/QUALITY_BAR.md only if small and directly helpful.

7. Anti-slop rules for decision HTML

Open Design bans common AI slop.

Adaptation for html-explainer:

Create operational anti-slop rules:

• no generic dashboard when the user needs a decision;
• no fake scores unless derived from visible rubric;
• no risk colors without stated basis;
• no empty charts;
• no decorative interactivity;
• no hidden uncertainty;
• no long visual intro before the conclusion;
• no current-status claim without source context;
• no saving low-value artifacts into memory;
• no HTML when Markdown is enough.

Potential output:

docs/ANTI_SLOP.md

8. Honest placeholders instead of fake certainty

Open Design prefers labelled placeholders over invented precision.

Adaptation for html-explainer:

Add formal placeholder language:

unknown
not inspected
not verified
not enough evidence
stale risk
requires refresh
source missing

Use these in artifacts, fact sheets, and artifact memory metadata.

Potential output:

• update docs/FACT_SHEET.md;
• add examples in docs/ANTI_SLOP.md.

9. Preview / export / persistence as one delivery contract

Open Design links preview, export, and persistence.

Adaptation for html-explainer:

Every serious artifact should answer:

• where was it saved?
• is it worth archiving?
• what metadata should accompany it?
• what should be exported?
• what prompt continues the work?
• should it enter the knowledge base?

Potential output:

• update docs/DELIVERY.md;
• align with docs/ARTIFACT_MEMORY.md.

10. Local working-directory discipline

Open Design keeps local runtime state local and warns not to commit it.

Adaptation for html-explainer:

Document local output discipline:

~/.claude/html-explainer/outputs/

Rules:

• never commit generated user outputs;
• keep outputs local by default;
• allow user-controlled alternate output root later;
• keep metadata free of secrets;
• add .gitignore guidance for users who copy outputs into projects.

11. Read-only MCP future option

Open Design exposes local generated context through read-only MCP.

Adaptation for html-explainer:

Do not implement MCP now, but design future read-only access to the local knowledge base.

Possible read-only tools:

search_artifacts
get_artifact_metadata
get_artifact_summary
get_reentry_prompt
get_related_artifacts
get_review_queue

Boundaries:

• read-only first;
• local-only;
• no write/delete through MCP until file model is stable.

Potential output:

docs/FUTURE_MCP_READONLY.md

or a focused section inside docs/ACTIONABLE_KNOWLEDGE_BASE.md.

12. Agent runtime portability

Open Design supports multiple agent/runtime paths.

Adaptation for html-explainer:

Keep Claude Code as the primary target, but avoid unnecessary Claude-only assumptions in docs and conventions.

Future-compatible agents may include Codex CLI, Gemini CLI, Cursor, OpenCode, or other agent CLIs that can use similar files, commands, or skills.

Potential output:

• add portability notes;
• avoid hardcoding behavior that only Claude Code can interpret unless explicitly required.

13. Contribution units

Open Design makes contribution shapes concrete.

Adaptation for html-explainer:

Define contribution types:

• add a pattern package;
• add a checklist;
• add a demo artifact;
• add a template;
• add a scenario test;
• add a knowledge-base metadata example;
• improve artifact explorer;
• add anti-slop example;
• add artifact mode/direction.

Potential output:

• update CONTRIBUTING.md in a future PR.

What not to copy

Do not copy Open Design's full product scope.

Out of scope:

• no daemon architecture;
• no full app shell;
• no desktop app;
• no media generation pipeline;
• no huge design-system catalog;
• no BYOK proxy;
• no database;
• no cloud/Vercel deployment layer;
• no visual clone of Open Design;
• no agent CLI auto-detection in this first implementation;
• no MCP implementation in this first implementation.

html-explainer should remain a small, local, evidence-first HTML decision workflow layer.

Suggested first implementation path

Create these docs:

docs/OPEN_DESIGN_LEARNINGS.md
docs/ARTIFACT_DISCOVERY_GATE.md
docs/ARTIFACT_DIRECTIONS.md
docs/ARTIFACT_MODES.md
docs/ARTIFACT_CHECKLISTS.md
docs/ANTI_SLOP.md
docs/PATTERN_PACKAGE_PROTOCOL.md

Then only update existing docs if the change is surgical:

docs/QUALITY_BAR.md
docs/FACT_SHEET.md
docs/DELIVERY.md
docs/ACTIONABLE_KNOWLEDGE_BASE.md

Do not change installer behavior in the first PR.

P0 acceptance criteria

• docs/OPEN_DESIGN_LEARNINGS.md clearly states what is being adapted and what is not.
• Anti-slop rules are concrete and operational.
• P0/P1/P2 gates are explicit.
• Artifact directions reduce model freestyle.
• Artifact modes sit above existing patterns without replacing them.
• The pattern package protocol is documented as future convention, not forced migration.
• No installer, command, pattern, script, or CI behavior is broken.

P1 acceptance criteria

• Docs cross-reference DECISION_GATE, QUALITY_BAR, FACT_SHEET, DELIVERY, and artifact memory where relevant.
• Honest placeholders are documented.
• Preview/export/archive expectations are documented.
• Future read-only MCP possibility is preserved but not implemented.
• Contribution units are clearer.

P2 polish

• Add one small before/after example showing anti-slop improvement.
• Add one example checklist for a high-value pattern.
• Add README pointer only if it helps adoption and does not clutter the main page.

Verification

• Review new docs against existing docs/DECISION_GATE.md, docs/QUALITY_BAR.md, docs/FACT_SHEET.md, docs/DELIVERY.md, and docs/ARTIFACT_MEMORY.md.
• Confirm the adaptation strengthens decision clarity, evidence quality, artifact usefulness, and re-entry.
• Confirm the PR avoids copying Open Design's runtime/product scope.
• Confirm no new runtime dependencies are added.
• Confirm the work helps a future agent generate better HTML artifacts with less ambiguity.

Success definition

This issue succeeds if html-explainer gains a stronger artifact-generation protocol without becoming Open Design:

discovery -> mode -> direction -> pattern -> evidence -> checklist -> artifact -> archive decision -> re-entry

[ramsani]

Deep extraction pass — stronger adaptation targets

After a deeper review of nexu-io/open-design, the first issue body is directionally right, but we should treat the repo as more than a source of visual-design ideas.

The real substance to extract is a control system for agent-produced artifacts:

brief -> discovery -> mode/pattern -> skill context -> references/checklist -> artifact -> preview/export -> persistence -> re-entry

For html-explainer, the equivalent should be:

user intent -> decision gate -> artifact direction -> pattern -> evidence/fact sheet -> checklist -> HTML artifact -> local artifact memory -> actionable knowledge base -> re-entry prompt

High-value findings to add to the implementation plan

1. Skills as portable capability folders

Open Design treats a skill as an atomic folder:

SKILL.md
assets/
references/
example.html

What to adapt:

• html-explainer patterns can evolve toward the same structure.
• Each serious pattern should eventually have:
  • pattern instructions;
  • reference checklist;
  • example artifact;
  • optional template asset;
  • failure modes;
  • acceptance criteria.

Do not convert everything immediately. First define the convention.

Potential doc:

docs/PATTERN_PACKAGE_PROTOCOL.md

2. Extended frontmatter / metadata for patterns

Open Design extends SKILL.md frontmatter with fields for mode, preview, design system needs, typed inputs, parameters, outputs, and capabilities.

Adaptation for html-explainer:

Patterns should eventually declare metadata, for example:

pattern: 17-project-recap
artifact_type: project-recap
recommended_budget: standard
supports_interaction: false
requires_evidence:
  - README
  - entry points
  - scripts
  - CI
outputs:
  primary: html
  secondary:
    - handoff_prompt
    - artifact_metadata
quality_gates:
  - evidence_visible
  - risk_visible
  - next_action_visible
memory:
  default_validity: replaceable
  freshness_risk: medium

This would make pattern routing and artifact memory more deterministic.

3. Mode thinking, not only pattern thinking

Open Design separates modes: prototype, deck, template, design-system. Modes are workflow containers, not pricing tiers or UI decoration.

Adaptation for html-explainer:

Define modes for decision artifacts:

• explain: concept or research explainer;
• review: plan, diff, PR, artifact audit;
• map: repo, module, architecture, workflow;
• decide: comparison, decision deck, trade-off map;
• tune: prompt, agent, skill, rubric;
• remember: artifact memory / knowledge base / re-entry.

This gives the system a higher-level router above the 21 patterns.

Potential doc:

docs/ARTIFACT_MODES.md

4. Template mode as quality floor

Open Design distinguishes generative mode from template mode. Template mode is faster and safer because layout decisions are pre-made.

Adaptation for html-explainer:

For recurring artifacts, create starter templates instead of asking the model to invent structure each time.

Candidate templates:

• artifact explorer;
• repo recap;
• diff review;
• prompt tuner;
• architecture map;
• ticket triage;
• decision deck.

This reduces variability and raises baseline quality.

Potential output:

templates/repo-recap.html
templates/diff-review.html
templates/prompt-tuner.html

Do not create many templates at once. Start with the explorer and one more high-value pattern.

5. References/checklists as mandatory side files

Open Design requires references/checklist.md for merge-quality skills, especially P0 gates.

Adaptation for html-explainer:

Each high-value pattern should have a compact checklist that the agent must use before delivery.

Example:

patterns/17-project-recap.checklist.md
patterns/03-annotated-pr-diff-review.checklist.md
patterns/20-prompt-agent-behavior-tuner.checklist.md

Or, more scalable:

checklists/project-recap.md
checklists/diff-review.md
checklists/prompt-tuner.md

6. P0/P1/P2 merge bar for artifacts

Open Design's contribution bar is practical: P0 gates must pass before artifact emission.

Adaptation for html-explainer:

Split quality into:

• P0: block delivery;
• P1: required for serious work;
• P2: polish.

P0 example:

• primary intent visible above fold;
• evidence basis visible;
• facts/inferences/unknowns separated;
• no fake metrics;
• no unsupported repo claims;
• recommendation visible;
• next prompt copy-ready;
• HTML advantage explicit.

7. Anti-slop should be operational, not aesthetic only

Open Design's anti-slop rules are not just about ugly visuals. They prevent model defaults, fake certainty, invented stats, vague design language, and generic outputs.

Adaptation for html-explainer:

Define anti-slop for decision HTML:

• no generic dashboard when the user needs a decision;
• no fake scores unless derived from rubric;
• no risk colors without stated basis;
• no empty charts;
• no decorative interactivity;
• no hidden uncertainty;
• no long visual intro before the conclusion;
• no current-status claim without source context;
• no saving low-value artifacts into memory.

8. Honest placeholders as a formal rule

Open Design explicitly prefers labelled placeholders over fake stats.

Adaptation for html-explainer:

Add formal placeholder language:

unknown
not inspected
not verified
not enough evidence
stale risk
requires refresh
source missing

This should be integrated into FACT_SHEET.md and artifact memory metadata.

9. Preview/export/persistence as one delivery contract

Open Design links preview, export, and persistence. The artifact is not just shown; it becomes a file with future affordances.

Adaptation for html-explainer:

Every serious artifact should answer:

• where was it saved?
• is it worth archiving?
• what metadata should accompany it?
• what should be exported?
• what prompt continues the work?
• should it enter the knowledge base?

This connects DELIVERY.md with ARTIFACT_MEMORY.md.

10. Local working directory discipline

Open Design keeps local runtime state under .od/ and warns not to commit it.

Adaptation for html-explainer:

Our equivalent is:

~/.claude/html-explainer/outputs/

We should also document:

• never commit generated user outputs;
• keep outputs local;
• allow user-controlled alternate output root;
• keep metadata free of secrets;
• add .gitignore guidance for users who copy outputs into projects.

11. MCP read-only is more important than first issue stated

Open Design's MCP lets other agents inspect local design projects without export/attach loops.

Adaptation for html-explainer:

This should be treated as a future capability of the knowledge base:

search_artifacts
get_artifact_metadata
get_artifact_summary
get_reentry_prompt
get_related_artifacts
get_review_queue

Boundary:

• read-only first;
• local-only;
• no write/delete through MCP until the file model is stable.

12. Contribution model should become sharper

Open Design makes contribution units small and concrete.

Adaptation for html-explainer:

Define contribution types:

• add a pattern package;
• add a checklist;
• add a demo artifact;
• add a template;
• add a scenario test;
• add a knowledge-base metadata example;
• improve artifact explorer.

This should eventually update CONTRIBUTING.md.

Stronger first implementation path

Revise the suggested first PR from the issue body to include these docs:

docs/OPEN_DESIGN_LEARNINGS.md
docs/ARTIFACT_DIRECTIONS.md
docs/ARTIFACT_MODES.md
docs/ARTIFACT_CHECKLISTS.md
docs/ANTI_SLOP.md
docs/PATTERN_PACKAGE_PROTOCOL.md

Then only update existing docs if the change is surgical:

docs/QUALITY_BAR.md
docs/FACT_SHEET.md
docs/DELIVERY.md
docs/ACTIONABLE_KNOWLEDGE_BASE.md

What this should not become

Still do not copy:

• daemon architecture;
• full app shell;
• media pipeline;
• database;
• BYOK proxy;
• desktop app;
• full design-system catalog;
• visual clone of Open Design.

The correct adaptation is not product copying. It is protocol extraction.

Revised success definition

This work succeeds if a future agent can generate better html-explainer artifacts because it has:

• a discovery gate;
• deterministic artifact directions;
• mode-level routing;
• package-like pattern conventions;
• P0/P1/P2 gates;
• anti-slop rules;
• honest placeholders;
• preview/export/archive rules;
• knowledge-base re-entry hooks;
• clear contribution units.

This is the deeper substance worth extracting.

[ramsani]

Completed in main. Added the extracted protocol layer: docs/OPEN_DESIGN_LEARNINGS.md, ARTIFACT_DIRECTIONS.md, ARTIFACT_MODES.md, ARTIFACT_CHECKLISTS.md, ANTI_SLOP.md, and PATTERN_PACKAGE_PROTOCOL.md. This incorporates the useful workflow ideas without copying product architecture.