brandspec 0.1.0

package/workshop/SKILL.md

@@ -0,0 +1,218 @@
+# brandspec workshop
+
+A Brand Identity forge. Through dialogue — pressure, refinement, and sharpening — produce a complete `brand.yaml` and brand assets.
+
+Compatible spec: brandspec v0.x
+
+## Related Resources
+
+- Repository: https://github.com/brandspec/brandspec
+- SaaS: https://brandspec.tools
+
+## Specification Knowledge (MUST READ)
+
+The following files define how `brand.yaml` works. Read these before facilitating:
+
+- `../schema/spec/core.md` — Core fields: essence, tagline, personality, voice structure (tone + principles)
+- `../schema/spec/tokens.md` — Token format, color system (oklch, variants, dark mode), typography, spacing, radius, export mapping
+- `../schema/spec/assets.md` — Asset structure, roles, variants, file naming, logo system patterns
+- `../schema/spec/guidelines.md` — Guidelines structure, linting rules, severity levels
+- `../schema/v0.1.0.yaml` — JSON Schema for validation
+
+## Purpose
+
+Brand Forger — forge a Brand Identity through dialogue with the user, producing a standalone brandspec repository.
+
+The workshop is a forge. Apply pressure to raw material, refine it, put an edge on it. The resulting `brand.yaml` becomes a SSoT of Consistent Polymorphism — ensuring the same brand appears with different faces at every touchpoint.
+
+## Deliverables
+
+The workshop populates the `brandspec/` directory created by `brandspec init`.
+
+```
+brandspec/                      ← inside your project
+├── brand.yaml              # SSoT — everything expands polymorphically from here
+├── assets/                     # brand assets (logos, icons, etc.)
+└── _workshop/                  # process records (keep for AI resumability)
+    ├── decisions.yml
+    ├── memo.md
+    └── session.md
+```
+
+## Flow
+
+4 phases. See [`flow.md`](flow.md) for details.
+
+```
+Discovery → Concept → Visual Identity → Documentation
+```
+
+## Activation Triggers
+
+Activate this skill on utterances like:
+
+- "I want to create a brand identity"
+- "Let's define a brand"
+- "I want to create a brandspec"
+- "Let's decide on colors and logo"
+- "I want to define the brand direction"
+
+## Initialization Sequence
+
+1. **Ask session language**: Ask the user which language they prefer for the workshop session. Record as the first decision (`session_language`). Conduct the entire session in that language from this point forward.
+2. Confirm brand name
+3. Read `_workshop/position.yml` to determine current position
+4. Load the corresponding phase `.md`
+
+## Session Language
+
+The workshop supports any language. The session language is determined at initialization and recorded in `decisions.yml`:
+
+```yaml
+- id: "d001"
+  timestamp: "..."
+  phase: 0
+  step: "init"
+  key: "session_language"
+  value: "en"          # or "ja", "zh", "ko", "fr", etc.
+  rationale: "User preference"
+```
+
+**Rules:**
+- All facilitator dialogue, questions, and explanations MUST be in the session language
+- `brand.yaml` field keys remain English (they are part of the spec)
+- `brand.yaml` values (essence, tagline, personality, etc.) are written in the session language unless the user prefers otherwise
+- `decisions.yml` values follow the session language
+- On session resume, read `session_language` from decisions and continue in that language
+
+## State Management
+
+```
+_workshop/
+├── position.yml    # current phase/step
+├── decisions.yml   # confirmed decisions (append-only)
+├── memo.md         # working notes (overwritable)
+└── session.md      # session handoff summary
+```
+
+### position.yml
+
+```yaml
+phase: 1              # 1-4
+step: "product"       # step within phase
+mode: "facilitation"  # facilitation | execution
+revision: 1           # +1 when backtracking
+updated: ""
+completed_at: null     # ISO date when workshop finishes
+```
+
+### decisions.yml
+
+```yaml
+decisions: []
+# Decision schema:
+#   - id: "d001"
+#     timestamp: "ISO 8601"
+#     phase: 1
+#     step: "product"
+#     key: "product_essence"
+#     value: "..."
+#     rationale: "..."
+#     supersedes: null    # or "d00X" if overriding a previous decision
+```
+
+## Operating Modes
+
+| Mode | AI Role | When |
+|------|---------|------|
+| facilitation | Present options, user decides | Exploring, direction unclear |
+| execution | AI works autonomously | Direction is clear |
+
+Switch via user utterance:
+- "Show me options" / "Let me decide" → facilitation
+- "You decide" / "Just do it" → execution
+
+## Phase Details
+
+See files in `phases/`:
+
+- [`phases/01-discovery.md`](phases/01-discovery.md) — Discovery
+- [`phases/02-concept.md`](phases/02-concept.md) — Concept
+- [`phases/03-visual.md`](phases/03-visual.md) — Visual Identity
+- [`phases/04-documentation.md`](phases/04-documentation.md) — Documentation
+
+## Key Rules
+
+1. **Record all decisions in decisions.yml** (use `supersedes` to reference overridden decisions)
+2. **Update position.yml at each step completion**
+3. **Use memo.md for working hypotheses and candidates (overwrite OK)**
+4. **Update session.md at session end (for handoff)**
+5. **Never advance phases without user approval**
+6. **Increment revision in position.yml when backtracking**
+
+## Flow Control Guidance
+
+### Phase 3.2 Colors: Progressive Defaults
+
+Colors is the most complex step. To reduce user burden, use a progressive approach:
+
+1. Ask the user to decide only the primary and secondary direction
+2. AI auto-generates the rest (surfaces, semantics, destructive) from the primary hue
+3. Present the full palette: "Does this look right? Anything to adjust?"
+4. Handle individual adjustments if needed, otherwise proceed
+
+Only walk through subsections 3.2.1–3.2.5 if the user requests detailed control.
+
+## Session Resume Algorithm
+
+When context is lost (new session, different AI, long gap), fully restore using this procedure:
+
+```
+1. Read position.yml → get current phase / step / mode / revision
+2. Read decisions.yml → load all decisions
+3. Resolve supersedes chains:
+   - Collect decisions where supersedes != null
+   - For each key, keep only the latest (non-superseded) decision
+4. Reconstruct current state from active decisions:
+   - Phase 1 complete? → product_essence, primary_user, positioning
+   - Phase 2 complete? → personality, voice, name, tagline
+   - Phase 3 complete? → mood, colors, typography, logo
+5. Check session_language decision → continue session in that language
+6. Read session.md for supplementary context (not required)
+7. Present state summary to user:
+   "Restored your previous session.
+    Current: Phase {N}, Step {step}
+    Confirmed: {summary of active decisions}
+    Next action: {step description}
+    Continue?"
+```
+
+This algorithm enables full restoration from `decisions.yml` + `position.yml` alone. `session.md` is supplementary context, not required.
+
+## Session Start Example
+
+```
+Let's start the brandspec workshop.
+
+First — what language would you like to use for this session?
+(e.g. English, 日本語, 中文, etc.)
+```
+
+After language is confirmed:
+
+```
+Great. Let's forge your brand.
+
+Current status:
+- Phase: Discovery
+- Step: product
+
+Tell me about your product.
+What are you building? What problem does it solve?
+```
+
+## Session End
+
+1. Record progress summary in `session.md`
+2. Note next actions clearly
+3. Report completion to user

package/workshop/flow.md

@@ -0,0 +1,181 @@
+# Workshop Flow
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       brandspec workshop                        │
+├─────────────┬─────────────┬─────────────────┬───────────────────┤
+│  Phase 1    │  Phase 2    │    Phase 3      │    Phase 4        │
+│  Discovery  │  Concept    │ Visual Identity │  Documentation    │
+├─────────────┼─────────────┼─────────────────┼───────────────────┤
+│ • product   │ • personality│ • mood         │ • defaults confirm│
+│ • users     │ • voice     │ • colors        │ • yaml generation │
+│ • context   │ • naming    │ • typography    │ • final review    │
+│             │ • tagline   │ • logo          │                   │
+└─────────────┴─────────────┴─────────────────┴───────────────────┘
+```
+
+## Output
+
+Workshop populates the `brandspec/` directory created by `brandspec init`:
+
+```
+brandspec/
+├── brand.yaml              # source of truth
+├── assets/                     # brand assets
+└── _workshop/                  # process records
+    ├── position.yml
+    ├── decisions.yml
+    ├── memo.md
+    └── session.md
+```
+
+## [Phase 1: Discovery](phases/01-discovery.md)
+
+**Goal**: Understand what we're branding
+
+### Steps
+
+1. **product** - What is the product? What problem does it solve?
+2. **users** - Who are the users? What do they need?
+3. **context** - Market position, competitors, constraints
+
+### Outputs
+
+- Product essence statement
+- User personas (brief)
+- Competitive insights
+
+### Complete When
+
+- [ ] Product can be explained in one sentence
+- [ ] Target user is clearly defined
+- [ ] Market position is understood
+
+---
+
+## [Phase 2: Concept](phases/02-concept.md)
+
+**Goal**: Define brand personality and voice
+
+### Steps
+
+1. **personality** - Brand personality traits (3-5 adjectives)
+2. **voice** - Tone, principles, examples
+3. **naming** - Brand name (if not decided)
+4. **tagline** - Tagline or slogan
+
+### Outputs
+
+- Personality traits
+- Voice & tone guidelines
+- Name (confirmed)
+- Tagline options → final selection
+
+### Complete When
+
+- [ ] Personality traits selected
+- [ ] Voice principles documented
+- [ ] Name confirmed
+- [ ] Tagline selected
+
+---
+
+## [Phase 3: Visual Identity](phases/03-visual.md)
+
+**Goal**: Create visual language
+
+### Steps
+
+1. **mood** - Visual direction, references, mood
+2. **colors** - Color palette (primary, secondary, etc.)
+3. **typography** - Font selection
+4. **logo** - Logo direction/concept
+
+### Outputs
+
+- Mood references
+- Color palette (oklch values)
+- Typography selection
+- Logo brief (actual logo creation may be external)
+
+### Complete When
+
+- [ ] Color palette finalized
+- [ ] Typography selected
+- [ ] Logo direction documented
+
+---
+
+## [Phase 4: Documentation](phases/04-documentation.md)
+
+**Goal**: Generate final deliverables into brandspec repository
+
+### Steps
+
+1. **defaults** - Confirm standard spacing/radius (customize if needed)
+2. **yaml** - Generate `brand.yaml` (+ register assets if any)
+3. **review** - Final review and approval
+
+### Outputs
+
+- `brand.yaml` - Machine-readable spec (brandspec directory root)
+- `assets/` - Brand assets (if any)
+- `_workshop/` - Process records (decisions.yml, memo.md, session.md)
+
+### Complete When
+
+- [ ] `brand.yaml` generated and valid
+- [ ] User has reviewed and approved
+
+---
+
+## State Transitions
+
+```
+Discovery ──[all steps complete]──> Concept
+Concept   ──[all steps complete]──> Visual Identity
+Visual    ──[all steps complete]──> Documentation
+Documentation ──[approved]──────> COMPLETE
+```
+
+### Backtracking Rules
+
+Going back to a previous phase is allowed. When backtracking:
+
+1. Increment `revision` in `position.yml` by 1
+2. New decisions MUST include `supersedes` referencing the previous decision ID
+3. When generating YAML in Phase 4, use only the latest (non-superseded) decisions
+4. Superseded decisions remain in `decisions.yml` (append-only is preserved)
+
+## Operating Modes
+
+### Facilitation Mode (Default)
+
+AI presents options, user decides.
+
+```
+AI: "Here are 3 personality directions:
+     a) Professional & Trustworthy
+     b) Playful & Approachable  
+     c) Bold & Innovative
+     Which resonates?"
+
+User: "b"
+
+AI: [Records decision, moves forward]
+```
+
+### Execution Mode
+
+AI makes decisions autonomously.
+
+```
+User: "Just create a brand for a productivity app"
+
+AI: [Runs through all phases]
+    [Presents complete brandspec for review]
+```
+
+Switch with: "Let me decide" / "You decide"

package/workshop/phases/01-discovery.md

@@ -0,0 +1,156 @@
+# Phase 1: Discovery
+
+## Goal
+
+Understand what we're branding before we brand it.
+
+## Steps
+
+### 1.1 Product
+
+**Questions to answer:**
+
+- What is the product/service/company?
+- What problem does it solve?
+- What makes it unique?
+- What's the core value proposition?
+
+**Facilitation prompts:**
+
+```
+Describe your product in one sentence.
+What would users miss most if it disappeared?
+How is this different from alternatives?
+```
+
+**Output: Product Essence**
+
+A single sentence capturing the core of what this is.
+
+```yaml
+# Example
+product_essence: "AI-powered writing assistant that helps non-native speakers write confidently"
+```
+
+---
+
+### 1.2 Users
+
+**Questions to answer:**
+
+- Who is the primary user?
+- What are their goals?
+- What are their pain points?
+- What's their context (B2B/B2C, technical level, etc.)?
+
+**Facilitation prompts:**
+
+```
+Who uses this? Paint a picture of your ideal user.
+What's frustrating them right now?
+Where do they encounter your product?
+```
+
+**Output: User Definition**
+
+```yaml
+# Example
+primary_user:
+  who: "Non-native English speakers in professional settings"
+  goals:
+    - "Write emails that sound natural"
+    - "Avoid embarrassing mistakes"
+  pain_points:
+    - "Unsure if their writing sounds professional"
+    - "Existing tools feel like cheating"
+  context: "B2C, used during work hours"
+```
+
+---
+
+### 1.3 Context
+
+**Questions to answer:**
+
+- Who are the competitors?
+- What's the market position?
+- Are there constraints (regulatory, technical, budget)?
+- What's the timeline/stage?
+
+**Facilitation prompts:**
+
+```
+What alternatives do users have today?
+Where do you want to position relative to competitors?
+Any constraints I should know about?
+```
+
+**Output: Market Context**
+
+```yaml
+# Example
+competitors:
+  - name: "Grammarly"
+    position: "Mass market, feature-heavy"
+  - name: "Hemingway"
+    position: "Simplicity-focused"
+    
+positioning: "Premium feel, focused on confidence not correction"
+
+constraints:
+  - "Launch in 3 months"
+  - "Small team, can't maintain complex brand"
+```
+
+---
+
+## Phase Complete Checklist
+
+- [ ] Product essence defined (one sentence)
+- [ ] Primary user identified
+- [ ] Competitive context understood
+- [ ] All recorded in `decisions.yml`
+
+## Transition to Phase 2
+
+When all items are checked:
+
+```yaml
+# Update position.yml
+phase: 2
+step: "personality"
+mode: "facilitation"
+```
+
+## Example Session
+
+```
+AI: Let's start with Discovery. Tell me about your product.
+    What are you building?
+
+User: It's a SaaS for managing Brand Identity files.
+
+AI: Interesting! What problem does this solve? Why would someone 
+    choose this over just using Google Drive?
+
+User: Designers hand off brand assets but they get lost, 
+    outdated versions get used, there's no single source of truth.
+
+AI: Got it. So the core value is "Single source of truth for brand assets."
+    Let me capture that:
+    
+    Product essence: "Single source of truth for Brand Identity 
+    that ensures teams always use the right assets."
+    
+    Does that capture it?
+
+User: Yes, but also add that it works with their existing tools.
+
+AI: Updated:
+    "Single source of truth for Brand Identity that integrates 
+    with existing design and development workflows."
+    
+    [Records to decisions.yml]
+    
+    Now let's talk about users. Who's buying and who's using?
+```