agentleFS
davidmatousekdavidmatousek/tachi/.claude/skills/aod-foundation/SKILL.md

aod-foundation

Skill95 starsChanged 37 days agoApache-2.0View on GitHub

Guided post-init workshop that helps new AOD Kit adopters establish product vision and design identity. Two-part flow: Part 1 (Vision) asks 5 guided questions to populate product-vision.md; Part 2 (Design) browses archetypes to generate brand files (brand.md, tokens.css, anti-patterns.md). Supports --vision and --design flags for partial execution. Use when a developer invokes /aod.foundation after running make init.

The file

Show its rules and text

We split this skill into the rules it gives an agent

63 rules. About 0 are common, 37 are distinctive, and 26 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈37

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 26

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run after make init to replace placeholder markers with real content.

    line 19
  2. Very specific:

    If arguments contain --vision:

    line 27
  3. Distinctive:

    If neither flag is present:

    line 33
  4. Distinctive:

    If both flags are present:

    line 35
  5. Very specific:

    Treat as run_both = true (equivalent to no flags)

    line 36
  6. Very specific:

    Use this ordered fallback to determine {project-name}:

    line 46
  7. Very specific:

    Repository directory name: Run basename $(git rev-parse --show-toplevel) — use this if it yields a non-empty value

    line 48
  8. Very specific:

    CLAUDE.md PROJECT_NAME: Read CLAUDE.md, grep for a line matching PROJECT_NAME that does NOT contain {{PROJECT_NAME}} (the un-replaced …

    line 49
  9. Distinctive:

    AskUserQuestion fallback: If neither source yields a usable name, ask: "What is your project name?" with a text input.

    line 50
  10. Very specific:

    If the file does not exist: Set vision_state = "missing" — Part 1 will create from scratch

    line 60
  11. Very specific:

    If the file contains [To be refined or [To be defined: Set vision_state = "placeholder" — Part 1 activates normally

    line 61
  12. Very specific:

    If the file exists with no placeholder markers: Set vision_state = "populated" — Part 1 enters re-run mode

    line 62
  13. Very specific:

    Check for brand directories under brands/:

    line 66
  14. Very specific:

    If no brand directory found (only _example): Set design_state = "missing" — Part 2 activates normally

    line 69
  15. Very specific:

    If a brand directory exists: Set design_state = "populated" — Part 2 enters re-run mode

    line 70
  16. Very specific:

    If vision_only: Part 1 → completion summary → end

    line 93
  17. Very specific:

    If run_both: Part 1 → "Part 1 complete.

    line 95
  18. Very specific:

    Part 2: only brands/{project_name}/ directory (brand.md, tokens.css, anti-patterns.md, reference/)

    line 103
  19. Distinctive:

    After generating any file content, display it for user review before writing to disk.

    line 122
  20. Distinctive:

    Use AskUserQuestion with options:

    line 125
  21. Distinctive:

    Only write to disk on explicit "Write to file" confirmation

    line 129
  22. Distinctive:

    If "Edit a section": loop back to step 1 after applying changes

    line 130
  23. Distinctive:

    When existing populated content is detected (vision_state = "populated" or design_state = "populated"):

    line 134
  24. Distinctive:

    If "Keep current": proceed to next part without modifying files

    line 141
  25. Distinctive:

    If "Update specific sections": present only the selected sections for re-answering, merge with existing content

    line 142
  26. Distinctive:

    If "Replace entirely": run the normal first-run flow

    line 143
  27. Distinctive:

    Default suggestion: Derive from CLAUDE.md description if available, otherwise: "Developers and small teams building software products"

    line 157
  28. Distinctive:

    Default suggestion: "They lack a structured approach to [domain]"

    line 164
  29. Distinctive:

    Default suggestion: Derive from CLAUDE.md description if available

    line 171
  30. Distinctive:

    Default suggestion: "It takes a [specific approach] that existing solutions don't"

    line 178
  31. Distinctive:

    Default suggestion: "User adoption, engagement frequency, and [domain-specific outcome]"

    line 185
  32. Distinctive:

    If all 5 questions are skipped: display warning — "All questions were skipped.

    line 201
  33. Distinctive:

    After all 5 questions are answered (or skipped), generate the product-vision.md content.

    line 205
  34. Very specific:

    When running the full workshop (run_both = true) and vision_state is "placeholder" or "missing":

    line 271
  35. Distinctive:

    After displaying the state summary (Step 1d), before starting questions, offer:

    line 273
  36. Distinctive:

    Use AskUserQuestion: "Ready to start the Vision Workshop (5 questions)?"

    line 274
  37. Very specific:

    When vision_only = true: do NOT offer skip — proceed directly to questions.

    line 278
  38. Very specific:

    When vision_state = "populated" (no placeholder markers):

    line 282
  39. Very specific:

    Read existing product-vision.md and extract current values for each section

    line 284
  40. Distinctive:

    If "Update specific sections": present checkboxes for which sections to update, then ask only the corresponding questions

    line 296
  41. Distinctive:

    If "Replace entirely": run the full 5-question flow, overwriting the entire file

    line 297
  42. Very specific:

    When design_state = "populated" (brand directory already exists):

    line 305
  43. Very specific:

    Read existing brands/{project_name}/brand.md and extract: archetype name (from tagline or heading), heading font, body font, primary color

    line 307
  44. Distinctive:

    If "Keep current": skip Part 2 entirely, preserve all brand files

    line 317
  45. Distinctive:

    If "Update specific sections": allow modifying individual brand file sections, merge with existing

    line 318
  46. Distinctive:

    If "Replace entirely": run the full archetype selection flow below

    line 319
  47. Very specific:

    If no files found: display warning — "No design archetypes found in .claude/design/archetypes/.

    line 326
  48. Distinctive:

    If numbered option: store the archetype name, read the full archetype file for value extraction

    line 348
  49. Distinctive:

    If "Custom": proceed to Step 2c

    line 349
  50. Distinctive:

    When the user selects "Custom" (no archetype):

    line 353
  51. Distinctive:

    Ask: "What is your primary brand color?

    line 355
  52. Distinctive:

    Ask: "What font style fits your brand?

    line 359
  53. Distinctive:

    Ask: "What is the overall visual mood?

    line 363
  54. Very specific:

    Create directory brands/{project_name}/ (if not exists)

    line 371
  55. Very specific:

    Create empty brands/{project_name}/reference/ directory

    line 372
  56. Distinctive:

    Read the selected archetype's sections:

    line 392
  57. Distinctive:

    Read the file and extract the active pack name

    line 476
  58. Distinctive:

    If no stack pack is active: skip silently.

    line 479
  59. Distinctive:

    After generating all three files:

    line 483
  60. Distinctive:

    Only write to disk on explicit "Write all files" confirmation

    line 502
  61. Very specific:

    Missing archetypes directory: If .claude/design/archetypes/ has no .md files, warn and offer only the Custom design option (Step 2c)

    line 509
  62. Very specific:

    Missing product-vision.md: When vision_state = "missing", create from scratch using the full 5-question flow — do not read or parse a …

    line 510
  63. Distinctive:

    After all parts complete, display a summary table:

    line 519

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/aod.foundation Skill

Purpose

Guided post-init workshop with two parts:

  • Part 1 (Vision): 5 storytelling-arc questions that populate product-vision.md
  • Part 2 (Design): Archetype browser that generates brands/{project-name}/ files

Run after make init to replace placeholder markers with real content.


Step 0: Parse Flags

Parse --vision and --design flags from the user's arguments.

  1. If arguments contain --vision:
    • Set vision_only = true
    • Strip --vision from arguments
  2. If arguments contain --design:
    • Set design_only = true
    • Strip --design from arguments
  3. If neither flag is present:
    • Set run_both = true (full workshop)
  4. If both flags are present:
    • Treat as run_both = true (equivalent to no flags)

Step 1: State Detection

Detect the current project state to determine which parts to activate and whether this is a first-run or re-run.

1a: Derive Project Name

Use this ordered fallback to determine {project-name}:

  1. Repository directory name: Run basename $(git rev-parse --show-toplevel) — use this if it yields a non-empty value
  2. CLAUDE.md PROJECT_NAME: Read CLAUDE.md, grep for a line matching PROJECT_NAME that does NOT contain {{PROJECT_NAME}} (the un-replaced placeholder). Extract the value.
  3. AskUserQuestion fallback: If neither source yields a usable name, ask: "What is your project name?" with a text input.

Sanitize the derived name to kebab-case: lowercase, replace spaces/underscores with hyphens, strip non-alphanumeric/non-hyphen characters.

Store as project_name for use throughout the workshop.

1b: Check Vision State

Read docs/product/01_Product_Vision/product-vision.md:

  • If the file does not exist: Set vision_state = "missing" — Part 1 will create from scratch
  • If the file contains [To be refined or [To be defined: Set vision_state = "placeholder" — Part 1 activates normally
  • If the file exists with no placeholder markers: Set vision_state = "populated" — Part 1 enters re-run mode

1c: Check Design State

Check for brand directories under brands/:

  • Glob brands/*/brand.md excluding brands/_example/brand.md
  • If no brand directory found (only _example): Set design_state = "missing" — Part 2 activates normally
  • If a brand directory exists: Set design_state = "populated" — Part 2 enters re-run mode

1d: Determine Flow

vision_onlydesign_onlyrun_bothAction
truefalsefalseExecute Part 1 only, skip Part 2
falsetruefalseExecute Part 2 only, skip Part 1
falsefalsetrueExecute Part 1, then Part 2

Display state summary:

Foundation Workshop
  Project: {project_name}
  Vision:  {vision_state} → {Part 1 will: create/update/offer re-edit}
  Design:  {design_state} → {Part 2 will: create/offer re-edit}
  Mode:    {Full workshop | Vision only | Design only}

1e: Execution Flow

Based on flag state, execute parts in order:

  1. If vision_only: Part 1 → completion summary → end
  2. If design_only: Part 2 → completion summary → end
  3. If run_both: Part 1 → "Part 1 complete. Moving to Design Identity." → Part 2 → completion summary → end

At each part entry, check the state for re-run handling. If user chooses "Keep current" during re-run detection, skip that part and advance to the next step in the flow. Choosing "Keep current" for Part 1 proceeds directly to Part 2 (if run_both). Choosing "Keep current" for Part 2 proceeds to the completion summary.

1f: Modification Isolation

Each part writes to independent file paths:

  • Part 1: only docs/product/01_Product_Vision/product-vision.md
  • Part 2: only brands/{project_name}/ directory (brand.md, tokens.css, anti-patterns.md, reference/)

Modifying vision leaves brand files untouched. Modifying design leaves product-vision.md untouched. "Keep current" means zero writes to that part's files.


Shared Patterns

Progress Announcements

Display progress at every transition point. Format:

  • During vision questions: "Vision: Question {N}/5 — {question_title}"
  • Between parts: "Part 1 complete. Moving to Design Identity."
  • During design: "Design: {step_description}"
  • At completion: "Workshop complete. {N} file(s) created/updated."

Show-Before-Write

After generating any file content, display it for user review before writing to disk.

  1. Display the generated content (full file or relevant section)
  2. Use AskUserQuestion with options:
    • "Write to file" — Write the content to disk, continue
    • "Edit a section" — Ask which section to change, apply edit, re-display
    • "Cancel" — Skip writing this file, continue to next step
  3. Only write to disk on explicit "Write to file" confirmation
  4. If "Edit a section": loop back to step 1 after applying changes

Re-Run Detection

When existing populated content is detected (vision_state = "populated" or design_state = "populated"):

  1. Display current content summary (key values, not full file)
  2. Use AskUserQuestion with options:
    • "Keep current" — Skip this part entirely, preserve existing content
    • "Update specific sections" — Show sections, let user pick which to re-answer
    • "Replace entirely" — Run the full creation flow from scratch
  3. If "Keep current": proceed to next part without modifying files
  4. If "Update specific sections": present only the selected sections for re-answering, merge with existing content
  5. If "Replace entirely": run the normal first-run flow

Part 1: Vision Workshop

Vision Questions

Present these 5 questions sequentially, following a storytelling arc from audience to measurement.

Question 1 — "Who is this for?"

  • Arc position: Setting the scene
  • Prompt: "Who is the primary user of your product? Describe them in 1-2 sentences — their role, context, and what makes them your target audience."
  • Example: "Spotify targets music listeners who want personalized discovery without manual playlist curation."
  • Default suggestion: Derive from CLAUDE.md description if available, otherwise: "Developers and small teams building software products"
  • Maps to: Target Users section

Question 2 — "What problem do they have?"

  • Arc position: The conflict
  • Prompt: "What specific problem or frustration does your target user face today? What are they struggling with or missing?"
  • Example: "Notion users struggled with scattered notes, docs, and project boards across multiple disconnected tools."
  • Default suggestion: "They lack a structured approach to [domain]"
  • Maps to: Problem Statement section

Question 3 — "What does your product do?"

  • Arc position: The solution
  • Prompt: "In 1-2 sentences, what does your product do to solve that problem? Focus on the core action, not features."
  • Example: "Linear provides a streamlined issue tracker that's fast enough to feel invisible, so engineering teams focus on building, not managing tools."
  • Default suggestion: Derive from CLAUDE.md description if available
  • Maps to: Core Value Proposition + Mission Statement + Core Capabilities

Question 4 — "How is it different?"

  • Arc position: The twist
  • Prompt: "What makes your approach unique? How is it different from alternatives or the status quo?"
  • Example: "Unlike traditional CRMs, HubSpot started free and grew with the customer — the product itself was the sales pitch."
  • Default suggestion: "It takes a [specific approach] that existing solutions don't"
  • Maps to: Vision Statement

Question 5 — "How will you know it's working?"

  • Arc position: The resolution
  • Prompt: "What 2-3 metrics or signals would tell you the product is succeeding? Think about what you'd check after launch."
  • Example: "Figma tracks multiplayer sessions (collaboration), time-to-first-design (activation), and team plan upgrades (revenue)."
  • Default suggestion: "User adoption, engagement frequency, and [domain-specific outcome]"
  • Maps to: Success Metrics

Question Presentation Flow

For each of the 5 questions:

  1. Display progress: "Vision: Question {N}/5 — {question_title}"
  2. Display the question prompt text
  3. Display the example (italicized)
  4. Use AskUserQuestion with:
    • A text input for the user's answer
    • A "Skip" option that marks the field as [To be defined]
  5. Validate: if answer is empty and not skipped, re-prompt once
  6. Store the answer for document generation

If all 5 questions are skipped: display warning — "All questions were skipped. The vision file will contain only placeholder markers. Downstream governance (/aod.define) may flag incomplete vision."

Vision Document Generation

After all 5 questions are answered (or skipped), generate the product-vision.md content.

Section mapping (answer → document section):

AnswerDocument SectionGeneration Rule
Q1 (Who)Target UsersUse answer directly. If skipped: [To be defined]
Q2 (Problem)Problem StatementUse answer directly. If skipped: [To be defined]
Q3 (What)Mission StatementCondense to 1 sentence if longer. If skipped: [To be defined]
Q3 (What)Core Value PropositionUse full answer. If skipped: [To be defined]
Q3 (What)Core CapabilitiesExtract key capabilities as a table. If skipped: [To be defined]
Q4 (Different)Vision StatementFrame as forward-looking "In a world where..." narrative. If skipped: [To be defined]
Q5 (Metrics)Success MetricsFormat as a table with Metric and Target columns. If skipped: [To be defined]

Document structure — follow the existing product-vision.md format:

# Product Vision — {project_name}

**Last Updated**: {YYYY-MM-DD}
**Owner**: Product Manager (product-manager)
**Status**: Active

---

## Mission Statement
{derived from Q3}

## Vision Statement
{derived from Q4}

## Problem Statement
{derived from Q2}

## Core Value Proposition
{derived from Q3}

## Core Capabilities

| Capability | Description |
|---|---|
{derived from Q3 — extract 2-4 key capabilities}

## Target Users

### Primary: {derived from Q1}
{expand Q1 answer into user persona description}

## Success Metrics

| Metric | Target |
|---|---|
{derived from Q5 — format each metric as a row}

---

**Maintained By**: Product Manager (product-manager)

After generation:

  1. Display the full generated document
  2. Apply show-before-write pattern
  3. Write to docs/product/01_Product_Vision/product-vision.md

Skip Part 1 Entirely

When running the full workshop (run_both = true) and vision_state is "placeholder" or "missing":

After displaying the state summary (Step 1d), before starting questions, offer:

  • Use AskUserQuestion: "Ready to start the Vision Workshop (5 questions)?"
    • "Start" — Begin Question 1
    • "Skip to Design" — Skip Part 1 entirely, proceed to Part 2 without modifying product-vision.md

When vision_only = true: do NOT offer skip — proceed directly to questions.

Vision Re-Run Handling

When vision_state = "populated" (no placeholder markers):

  1. Read existing product-vision.md and extract current values for each section
  2. Display summary:
    Current Vision:
      Mission:    {first 80 chars}...
      Vision:     {first 80 chars}...
      Problem:    {first 80 chars}...
      Value Prop: {first 80 chars}...
      Users:      {first 80 chars}...
      Metrics:    {count} defined
  3. Apply re-run detection pattern (Keep current / Update specific sections / Replace entirely)
  4. If "Update specific sections": present checkboxes for which sections to update, then ask only the corresponding questions
  5. If "Replace entirely": run the full 5-question flow, overwriting the entire file

Part 2: Design Identity Workshop

Design Re-Run Handling

When design_state = "populated" (brand directory already exists):

  1. Read existing brands/{project_name}/brand.md and extract: archetype name (from tagline or heading), heading font, body font, primary color
  2. Display summary:
    Current Design Identity:
      Archetype:   {name or "Custom"}
      Fonts:       {heading font} + {body font}
      Primary:     {color value}
      Temperature: {warm/cool/neutral}
  3. Apply re-run detection pattern (Keep current / Update specific sections / Replace entirely)
  4. If "Keep current": skip Part 2 entirely, preserve all brand files
  5. If "Update specific sections": allow modifying individual brand file sections, merge with existing
  6. If "Replace entirely": run the full archetype selection flow below

Step 2a: Archetype Discovery

Discover available archetypes at runtime:

  1. Glob .claude/design/archetypes/*.md
  2. If no files found: display warning — "No design archetypes found in .claude/design/archetypes/. Check your installation." Offer only the Custom option (skip to Step 2c).
  3. For each archetype file, parse:
    • Name: Derive from filename, title-cased (e.g., precision.md → "Precision")
    • Tagline: First blockquote line (> ...) after the # {Name} Archetype heading
    • Font pairing: Extract Headings and Body font names from the "Font Pairing" table's Font column
    • Color temperature: Extract from the **Temperature**: line under "Color Palette Strategy"

Step 2b: Archetype Browser

Present discovered archetypes as a numbered selection list via AskUserQuestion.

Display "Design: Archetype Selection" as progress announcement.

Format per archetype:

{N}. {Name} — "{Tagline (first ~60 chars)}"
   Fonts: {Heading Font} + {Body Font} | Temperature: {temperature}

AskUserQuestion options: numbered options "1" through "{N}" for each archetype, plus "Custom".

After selection:

  • If numbered option: store the archetype name, read the full archetype file for value extraction
  • If "Custom": proceed to Step 2c

Step 2c: Custom Design Flow

When the user selects "Custom" (no archetype):

  1. Ask: "What is your primary brand color? (e.g., 'deep blue', '#1a365d', 'warm terracotta')"
    • AskUserQuestion with text input
    • Store as custom_primary_color
  2. Ask: "What font style fits your brand? (e.g., 'clean and modern', 'editorial serif', 'technical monospace')"
    • AskUserQuestion with text input
    • Store as custom_font_style
  3. Ask: "What is the overall visual mood? (e.g., 'professional and minimal', 'warm and inviting', 'bold and energetic')"
    • AskUserQuestion with text input
    • Store as custom_mood

Generate brand files using these custom inputs. Select appropriate fonts, colors, radius, and shadow values that match the described mood and font style. Use design knowledge to produce a coherent set of tokens.

Step 2d: Brand Directory and brand.md Generation

  1. Create directory brands/{project_name}/ (if not exists)
  2. Create empty brands/{project_name}/reference/ directory
  3. Generate brand.md following the structure from brands/_example/brand.md:

    Replacements from archetype (or custom inputs):

    • {{BRAND_NAME}} → {project_name} in title case
    • {{BRAND_TAGLINE}} → archetype tagline (or custom mood description)
    • Primary Colors table → from archetype's --color-primary, --color-primary-light, --color-accent values with hex + oklch
    • Secondary Colors table → from archetype's --color-secondary, --color-accent, and a neutral derived from palette
    • Semantic Colors table → from archetype's success/warning/error/info values
    • {{HEADING_FONT}} → archetype heading font name
    • {{BODY_FONT}} → archetype body font name
    • {{MONO_FONT}} → JetBrains Mono (default for all)
    • Personality / Voice → derive from archetype description and character notes
    • Visual Tone → derive from archetype's Layout Philosophy and overall description
    • Usage Notes → adapt from archetype's guidelines and constraints

Step 2e: Anti-Patterns Generation

Generate brands/{project_name}/anti-patterns.md from archetype constraints:

  1. Read the selected archetype's sections:
    • "Usage Notes" → "Avoid {archetype} for" items and accessibility considerations
    • "Shadow Depth" → guidelines (e.g., "Avoid lg shadows" for precision)
    • "Border Radius" → guidelines (e.g., "Never exceed --radius-lg" for precision, "Sharp corners never used" for warmth)
    • "Motion Style" → guidelines (e.g., "Avoid bounce effects" for precision)
    • "Layout Philosophy" → patterns and constraints
  2. Generate anti-patterns following brands/_example/anti-patterns.md structure with these categories:
    • Visual Constraints: From radius, shadow, and spacing guidelines
    • Typography Constraints: From font pairing rationale and weight guidance
    • Motion / Animation Constraints: From motion style guidelines
    • Layout Constraints: From layout philosophy
    • Color Constraints: From palette approach and accessibility notes
  3. Each constraint MUST be specific and actionable:
    • Good: "Avoid border-radius larger than 6px on rectangular elements" (precision)
    • Good: "Never use sharp corners on any element" (warmth)
    • Bad: "Keep it clean" (not actionable)

Step 2f: Token Mapping and tokens.css Generation

Generate brands/{project_name}/tokens.css with all 19 semantic tokens.

  1. Read the canonical mapping from .claude/skills/aod-foundation/references/token-mapping.md
  2. Extract values from the selected archetype's markdown tables:
    • Color Palette Strategy table → color values (hsl/oklch format)
    • Font Pairing table → font family names and fallbacks
    • Border Radius table → radius values
    • Shadow Depth table → shadow values
  3. Apply rename layer (archetype name → tokens.css name):
    • --color-error → --color-destructive
    • --color-surface → --color-background (and also informs --color-muted)
    • Body font → --font-sans
    • Heading font → --font-heading
  4. Apply derivation rules for missing tokens:
    • --color-secondary if absent: primary hue + 30 degrees
    • --color-muted if absent: primary at 10% saturation, 95% lightness
    • --shadow-lg if absent (precision, technical): derive from --shadow-md with 2.5x spread/offset, 1.25x opacity
    • --radius-lg if absent: --radius-md * 1.5
    • --font-mono: always "JetBrains Mono", "Fira Code", monospace
  5. Generate single-layer :root {} block:
/**
 * Brand Tokens — {project_name}
 * Generated by /aod.foundation from {archetype_name} archetype
 */

:root {
  /* --- Colors --- */
  --color-primary:     {value};
  --color-secondary:   {value};
  --color-accent:      {value};
  --color-muted:       {value};
  --color-destructive: {value};
  --color-success:     {value};
  --color-warning:     {value};
  --color-info:        {value};
  --color-background:  {value};
  --color-foreground:  {value};

  /* --- Typography --- */
  --font-sans:    "{body font}", {fallbacks};
  --font-heading: "{heading font}", {fallbacks};
  --font-mono:    "JetBrains Mono", "Fira Code", monospace;

  /* --- Border Radius --- */
  --radius-sm: {value};
  --radius-md: {value};
  --radius-lg: {value};

  /* --- Shadows --- */
  --shadow-sm: {value};
  --shadow-md: {value};
  --shadow-lg: {value};
}

Total: 19 individual tokens (10 color + 3 font + 3 radius + 3 shadow).

Step 2g: Stack Pack Compatibility Check

If .aod/stack-active.json exists:

  1. Read the file and extract the active pack name
  2. Display note: "Note: Stack pack '{pack_name}' is active. Generated tokens use standard CSS custom property names compatible with the pack's scaffold."

If no stack pack is active: skip silently.

Step 2h: Preview and Write All Brand Files

After generating all three files:

  1. Display each file's content with progress announcements:
    Design: Preview — brand.md
    {full content}
    
    Design: Preview — tokens.css
    {full content}
    
    Design: Preview — anti-patterns.md
    {full content}
  2. Apply show-before-write pattern for ALL files together:
    • "Write all files" — Write all three to brands/{project_name}/
    • "Edit a section" — Ask which file and section to change, apply edit, re-display
    • "Cancel" — Skip writing brand files entirely
  3. Only write to disk on explicit "Write all files" confirmation
  4. After writing: "Design: Brand files written to brands/{project_name}/"

Edge Cases

  • Missing archetypes directory: If .claude/design/archetypes/ has no .md files, warn and offer only the Custom design option (Step 2c)
  • Missing product-vision.md: When vision_state = "missing", create from scratch using the full 5-question flow — do not read or parse a nonexistent file
  • Special characters in project name: Step 1a sanitization handles this — always use the kebab-case project_name for directory and file paths
  • All vision questions skipped: Warning displayed per Question Presentation Flow. Still proceed to Part 2 if run_both = true — skipping vision does not block design
  • All of Part 2 skipped during full workshop: Display completion summary with design artifacts marked "Skipped"

Workshop Completion Summary

After all parts complete, display a summary table:

Foundation Workshop Complete

| Artifact | Path | Status |
|----------|------|--------|
| Product Vision | docs/product/01_Product_Vision/product-vision.md | {Created/Updated/Skipped} |
| Brand Identity | brands/{project-name}/brand.md | {Created/Updated/Skipped} |
| Design Tokens | brands/{project-name}/tokens.css | {Created/Updated/Skipped} |
| Anti-Patterns | brands/{project-name}/anti-patterns.md | {Created/Updated/Skipped} |

{count} file(s) created, {count} file(s) updated, {count} file(s) skipped.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.