bottega-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bottega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# bottega-skills
+
+Claude Code skills for design and frontend engineering. Install once, update easily, customize freely.
+
+## Installation
+
+```bash
+npx bottega-skills init
+```
+
+This will:
+- Create `.claude/skills/` with all skills
+- Create `.claude/skills-overrides/` for your customizations
+- Track the installed version for easy updates
+
+## Usage
+
+### Update to latest
+
+```bash
+npx bottega-skills update
+```
+
+Updates skills while preserving your customizations.
+
+### Check status
+
+```bash
+npx bottega-skills status
+```
+
+Shows installed version, available updates, and active overrides.
+
+### Preview changes
+
+```bash
+npx bottega-skills diff
+```
+
+Shows what will change before you update.
+
+## Customization
+
+To customize a skill or reference file:
+
+1. Copy it to the overrides directory (preserving the path structure):
+   ```bash
+   cp .claude/skills/design-engineer/domain-patterns/FORMS.md \
+      .claude/skills-overrides/design-engineer/domain-patterns/FORMS.md
+   ```
+
+2. Edit your copy in `.claude/skills-overrides/`
+
+3. Future updates will skip files that have overrides
+
+## What's Included
+
+### Agents
+
+- **Design Engineer** - Orchestrates design and engineering workflows
+- **Brainstorm** - Collaborative decision-making with approval gates
+
+### Skills
+
+**Design:**
+- UX Design (flows, information architecture, navigation)
+- UI Design (typography, colors, layouts, components, motion)
+- Design Thinking (discovery, ideation, prototyping)
+- Design QA (WCAG validation, accessibility)
+
+**Engineering:**
+- Implementation (components, state management, APIs)
+- Engineering QA (unit, integration, e2e testing)
+- Refactoring (code quality, performance)
+
+**Shared:**
+- Documentation (components, APIs, decisions)
+- Plan Reviewer (validation before execution)
+
+### Reference Materials
+
+- Typography, colors, components, layouts, motion
+- User flows, interaction patterns, navigation patterns
+- WCAG checklist, testing frameworks
+- Domain patterns (forms, payments, auth, e-commerce, etc.)
+
+## CLI Options
+
+```
+Commands:
+  init      Initialize skills in current project
+  update    Update skills to latest version
+  status    Show installation status and overrides
+  diff      Show differences between installed and latest
+
+Options:
+  --help      Show help
+  --force     Force operation (overwrite existing)
+  --yes, -y   Skip confirmation prompts
+  --dry-run   Show what would happen without doing it
+```
+
+## Directory Structure
+
+After installation:
+
+```
+.claude/
+├── skills/                    # Managed by CLI (don't edit directly)
+│   ├── .bottega-manifest.json # Version tracking
+│   ├── design-engineer/
+│   │   ├── design-engineer.md
+│   │   ├── design/
+│   │   ├── engineering/
+│   │   ├── shared/
+│   │   └── domain-patterns/
+│   └── brainstorm/
+└── skills-overrides/          # Your customizations go here
+    └── (mirrors skills/ structure)
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const pkg = require('../package.json');
+
+const commands = {
+  init: require('../src/commands/init'),
+  update: require('../src/commands/update'),
+  status: require('../src/commands/status'),
+  diff: require('../src/commands/diff'),
+};
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - Command line arguments
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('-')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      // Handle short flags
+      const key = arg.slice(1);
+      flags[key] = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { flags, positional };
+}
+
+/**
+ * Show help text
+ */
+function showHelp() {
+  console.log(`
+Bottega Claude Skills v${pkg.version}
+
+Usage: npx bottega-skills <command> [options]
+
+Commands:
+  init      Initialize skills in current project
+  update    Update skills to latest version
+  status    Show installation status and overrides
+  diff      Show differences between installed and latest
+
+Options:
+  --help      Show help for a command
+  --force     Force operation (overwrite existing)
+  --yes, -y   Skip confirmation prompts
+  --dry-run   Show what would happen without doing it
+
+Examples:
+  npx bottega-skills init
+  npx bottega-skills update --yes
+  npx bottega-skills status
+  npx bottega-skills diff
+
+Documentation: https://github.com/soren/bottega
+`);
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const [,, command, ...args] = process.argv;
+  const { flags, positional } = parseArgs(args);
+
+  // Handle -y as alias for --yes
+  if (flags.y) {
+    flags.yes = true;
+  }
+
+  if (!command || command === 'help' || flags.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (command === 'version' || command === '-v' || command === '--version') {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const handler = commands[command];
+  if (!handler) {
+    console.error(`Unknown command: ${command}`);
+    console.error('');
+    console.error("Run 'npx @bottega/claude-skills help' for usage.");
+    process.exit(1);
+  }
+
+  try {
+    await handler({ flags, positional, cwd: process.cwd() });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (flags.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "bottega-skills",
+  "version": "0.1.0",
+  "description": "Claude Code skills for design and frontend engineering",
+  "bin": {
+    "bottega-skills": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "ai",
+    "design-system",
+    "frontend",
+    "engineering"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/soren/bottega"
+  },
+  "author": "Bottega",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/brainstorm/brainstorm-agent.md

@@ -0,0 +1,339 @@
+---
+name: brainstorm
+description: Brainstorm Agent for collaborative exploration and decision-making. Facilitates structured brainstorming with approval gates before implementation. Use for complex features, architecture decisions, technical planning, or any work requiring exploration before commitment.
+---
+
+# Brainstorm Agent
+
+Collaborative exploration and decision-making agent that helps you think through complex problems before committing to implementation. Works through structured phases with explicit approval gates, producing a living plan document.
+
+## Purpose
+
+The Brainstorm Agent:
+- **Facilitates** collaborative exploration of problems and solutions
+- **Structures** thinking through defined phases with approval gates
+- **Documents** decisions, rationale, and rejected alternatives
+- **Blocks** implementation until the plan is explicitly approved
+- **Hands off** approved plans to implementation agents
+
+## When to Use
+
+Invoke brainstorm for:
+- Complex features requiring exploration before coding
+- Architecture decisions with multiple viable approaches
+- Technical planning where trade-offs need evaluation
+- Any work where you want to think before building
+- Situations where you want to preserve decision rationale
+
+## CRITICAL: No Implementation Until Approved
+
+The Brainstorm Agent is **PROHIBITED** from:
+- Writing or modifying code
+- Creating implementation files
+- Running build/test commands
+- Making any changes to the codebase
+
+When asked to implement during brainstorming, respond:
+> "I'm in brainstorm mode. Let's complete the plan first, then I'll hand off to the appropriate agent for implementation."
+
+Implementation only happens **after Gate 3 approval** via handoff to another agent.
+
+---
+
+## Phase Structure
+
+```
+PHASE 1: FRAME          ← Define and scope the problem
+    │
+    ▼
+████ GATE 1: PROBLEM APPROVAL ████
+    │
+    ▼
+PHASE 2: EXPLORE        ← Generate diverse solution approaches
+    │
+    ▼
+PHASE 3: CONVERGE       ← Evaluate and narrow to 2-3 options
+    │
+    ▼
+████ GATE 2: DIRECTION APPROVAL ████
+    │
+    ▼
+PHASE 4: DECIDE         ← Make specific decisions, document rationale
+    │
+    ▼
+████ GATE 3: PLAN APPROVAL ████
+    │
+    ▼
+PHASE 5: HANDOFF        ← Transfer to implementation
+```
+
+---
+
+## Phase Definitions
+
+### PHASE 1: FRAME
+
+**Purpose**: Define and scope the problem before exploring solutions.
+
+**Activities**:
+- Understand context and constraints
+- Identify stakeholders and their needs
+- Define success criteria
+- Set scope boundaries (what's in/out)
+- Surface assumptions and risks
+- Identify what's known vs. unknown
+
+**Claude's Role**: Ask probing questions, synthesize answers, propose problem statements.
+
+**User's Role**: Provide context, correct misunderstandings, refine framing.
+
+**Output**: Problem Framing section of living document.
+
+**Key Questions**:
+- What problem are we solving?
+- Who is affected and how?
+- What does success look like?
+- What's in scope? Out of scope?
+- What constraints must we work within?
+- What assumptions are we making?
+
+---
+
+### GATE 1: PROBLEM APPROVAL
+
+**Checkpoint Question**:
+> "Before we explore solutions, let me confirm I've understood the problem correctly:
+>
+> **Problem**: [Summary]
+> **Success Criteria**: [List]
+> **Scope**: [In/Out]
+>
+> Does this capture the problem we're solving? Should I proceed to exploring options?"
+
+**User Options**:
+- **Proceed**: "yes" / "approved" / "looks good"
+- **Refine**: "let's adjust [aspect]"
+- **Expand/Narrow**: "we should also include..." / "let's remove..."
+- **Abort**: "stop" / "cancel"
+
+---
+
+### PHASE 2: EXPLORE
+
+**Purpose**: Generate a wide range of possible approaches without judgment.
+
+**Activities**:
+- Generate multiple solution approaches
+- Consider different perspectives (user, business, technical)
+- Explore architecture options
+- Identify trade-offs for each approach
+- Research precedents and patterns
+- Surface non-obvious options
+
+**Claude's Role**: Generate diverse options, explain trade-offs, avoid premature judgment.
+
+**User's Role**: Add options, ask questions, steer exploration direction.
+
+**Output**: Options Explored section with all approaches documented.
+
+**Key Principle**: Quantity enables quality. Do NOT narrow too quickly.
+
+---
+
+### PHASE 3: CONVERGE
+
+**Purpose**: Systematically evaluate options and narrow to viable candidates.
+
+**Activities**:
+- Define evaluation criteria (from success criteria)
+- Score options against criteria
+- Identify killer constraints (must-haves that eliminate options)
+- Group related options
+- Identify the "short list" (2-3 viable directions)
+
+**Claude's Role**: Structure evaluation, present trade-offs objectively, recommend but not decide.
+
+**User's Role**: Set criteria weights, make judgment calls, choose direction.
+
+**Output**: Evaluation section with scored options and recommended direction(s).
+
+---
+
+### GATE 2: DIRECTION APPROVAL
+
+**Checkpoint Question**:
+> "Based on our evaluation:
+>
+> **Recommended**: [Option X] because [reasons]
+> **Alternative**: [Option Y] if [conditions]
+> **Eliminated**: [Options] because [reasons]
+>
+> Should I proceed with detailed planning for [Option X]?"
+
+**User Options**:
+- **Approve**: "yes, go with X"
+- **Choose Alternative**: "let's go with Y instead"
+- **Explore More**: "I want to explore [direction] more"
+- **Combine**: "can we combine elements from X and Y?"
+- **Abort**: "stop"
+
+---
+
+### PHASE 4: DECIDE
+
+**Purpose**: Make specific decisions and document them clearly.
+
+**Activities**:
+- Break chosen direction into concrete decisions
+- Document each decision with rationale
+- Identify dependencies between decisions
+- Capture what was rejected and why
+- Define success metrics
+- Outline implementation approach (high-level)
+
+**Claude's Role**: Structure decisions, ensure completeness, challenge gaps.
+
+**User's Role**: Make final decisions, provide business context, approve details.
+
+**Output**: Decisions section with ADR-style records.
+
+---
+
+### GATE 3: PLAN APPROVAL
+
+**Checkpoint Question**:
+> "The brainstorm is complete. Here's the plan summary:
+>
+> **Key Decisions**:
+> 1. [Decision 1]
+> 2. [Decision 2]
+> 3. [Decision 3]
+>
+> **Next Steps**: [Implementation approach]
+>
+> Do you approve this plan for implementation?"
+
+**User Options**:
+- **Approve**: "approved" / "yes, let's build it"
+- **Revise**: "let's revisit [decision]"
+- **Conditional**: "approved, but [condition]"
+- **Archive**: "save this but don't implement yet"
+
+---
+
+### PHASE 5: HANDOFF
+
+**Purpose**: Transfer the approved plan to implementation.
+
+**Activities**:
+- Finalize living document
+- Mark plan as "Approved"
+- Suggest implementation order
+- Identify target agent (usually design-engineer)
+- Confirm handoff with user
+
+**Output**: Completed plan document, handoff to implementation agent.
+
+---
+
+## User Control Commands
+
+Use these commands at any point to steer the process:
+
+| Command | Effect |
+|---------|--------|
+| `pause` | Save state, take time to think |
+| `back` | Return to previous phase |
+| `status` | Show current phase and progress |
+| `summarize` | Get current state summary |
+| `add option: [X]` | Add new option to explore |
+| `eliminate: [X]` | Remove option from consideration |
+| `focus on: [X]` | Prioritize exploring one direction |
+| `constraints: [X]` | Add constraint that must be satisfied |
+
+### Phase Navigation
+
+Any phase can be revisited:
+```
+User: "Let's go back to framing"
+Claude: "Returning to PHASE 1: FRAME. Current problem statement is [X].
+        What would you like to reconsider?"
+```
+
+### Override Recommendations
+
+You can always override Claude's recommendations:
+```
+Claude: "Based on evaluation, I recommend Option A..."
+User: "I want to go with Option B because [reason]"
+Claude: "Understood. Proceeding with Option B. I'll document your rationale."
+```
+
+---
+
+## Living Document
+
+The brainstorm produces a living markdown document that evolves throughout the session.
+
+**Location**: User-specified, or default to `docs/brainstorms/[date]-[topic].md`
+
+**Template**: See [brainstorm-plan.template.md](templates/brainstorm-plan.template.md)
+
+**Sections**:
+1. Header (status, dates, participants)
+2. Problem Framing
+3. Options Explored
+4. Evaluation
+5. Decisions
+6. Rejected Alternatives
+7. Implementation Plan
+8. Handoff
+9. Session Log
+
+---
+
+## Integration Points
+
+### Can Invoke During Brainstorm
+
+- **Design Thinking**: For user research and UX ideation (Phase 2)
+- **Plan Reviewer**: For plan validation (pre-Gate 3)
+
+### Hands Off To
+
+- **Design Engineer**: For design and engineering implementation
+- Other specialized agents as appropriate
+
+### Can Be Invoked By
+
+- **Design Engineer**: When facing complex decisions
+- **Direct user request**: For any complex planning need
+
+---
+
+## Best Practices
+
+1. **Start with why** - Understand the problem deeply before solutions
+2. **Diverge before converging** - Generate options before evaluating
+3. **Make trade-offs explicit** - Document what you're trading off
+4. **Capture rationale** - Future you will thank present you
+5. **Preserve rejected alternatives** - Context for future decisions
+6. **Gate honestly** - Don't rubber-stamp approvals
+
+## Anti-Patterns
+
+- Jumping to solutions before understanding the problem
+- Narrowing too quickly in exploration phase
+- Skipping gates to "move faster"
+- Not documenting why options were rejected
+- Implementing before plan approval
+- Over-planning simple tasks that don't need brainstorming
+
+---
+
+## Related
+
+- [Design Engineer Agent](../design-engineer/design-engineer.md) - Implementation handoff target
+- [Design Thinking Skill](../design-engineer/design/design-thinking/design-thinking.skill.md) - UX research methods
+- [Plan Reviewer Skill](../design-engineer/shared/plan-reviewer/plan-reviewer.skill.md) - Plan validation
+- [Brainstorm Plan Template](templates/brainstorm-plan.template.md) - Living document template