@hustle-together/api-dev-tools 3.12.16 → 4.5.3

package/.skills/docs-update/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: docs-update
+description: Ensure README, CHANGELOG, and docs stay current with features
+tools: Read, Write, Edit, Glob, Grep, Task, TodoWrite
+model: sonnet
+---
+
+# Documentation Update Skill
+
+Automatically maintains documentation consistency when features are added or changed. This skill is invoked by the `docs-update-check.py` hook after significant changes.
+
+## Philosophy
+
+> **README is the single source of truth** - It should provide a comprehensive overview
+> without becoming too long. Detailed docs live in `/docs/*.md`.
+
+### Update Rules
+
+1. **README.md** - Update only when:
+   - New major feature added (new skill, new workflow)
+   - Links section needs new doc reference
+   - Counts change (skills, hooks, agents)
+   - Version number changes
+   - Never let it exceed ~500 lines
+
+2. **CHANGELOG.md** - Always update when:
+   - New features added
+   - Breaking changes
+   - Bug fixes
+   - Version bump
+
+3. **docs/*.md** - Create/update when:
+   - New feature needs detailed explanation
+   - Existing doc is out of date
+   - Command signature changes
+
+## When This Skill Runs
+
+Triggered by `docs-update-check.py` hook when:
+- New skill created in `.skills/`
+- New hook added to `hooks/`
+- New agent defined in `.claude/agents/`
+- New doc created in `docs/`
+- registry.json sections added/changed
+
+## Execution Flow
+
+### Step 1: Detect What Changed
+
+```bash
+# Get recently modified files
+git diff --name-only HEAD~1 HEAD
+
+# Or for uncommitted changes
+git status --porcelain
+```
+
+### Step 2: Categorize Changes
+
+| File Pattern | Category | Action |
+|--------------|----------|--------|
+| `.skills/*/SKILL.md` | New Skill | Update README skills count, add to docs/SKILLS.md |
+| `hooks/*.py` | New Hook | Update README hooks count, add to docs/HOOKS.md |
+| `.claude/agents/*.md` | New Agent | Update README agents count, add to docs/AGENTS.md |
+| `docs/*.md` | New Doc | Add to README Documentation section |
+| `templates/*.tsx` | New Template | Consider dashboard integration |
+
+### Step 3: Update README Links
+
+Check if new docs need to be linked:
+
+```markdown
+## Documentation
+
+### Core Reference
+
+| Document | Purpose |
+| -------- | ------- |
+| **[docs/NEW_DOC.md](./docs/NEW_DOC.md)** | Description here |
+```
+
+### Step 4: Update CHANGELOG
+
+Add entry under current version or create new version:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- **`/new-skill`** - Description of what it does
+```
+
+### Step 5: Update Feature Doc
+
+If change affects an existing command, update its doc:
+
+```bash
+# Map skill to doc
+/api-create → docs/API-CREATE.md
+/hustle-ui-create → docs/HUSTLE-UI-CREATE.md
+/test-review → docs/SKILLS.md (test skills section)
+```
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════════
+                    DOCUMENTATION UPDATE
+═══════════════════════════════════════════════════════════════
+
+Changes Detected:
+  • New skill: /docs-update
+  • New doc: docs/PARALLEL_AUTONOMOUS_WORKFLOW.md
+  • Modified: .skills/hustle-build/SKILL.md
+
+Updates Made:
+  ✅ README.md - Added parallel workflow to docs section
+  ✅ CHANGELOG.md - Added v4.3.0 entry
+  ✅ docs/SKILLS.md - Added docs-update skill reference
+  ⏭️  docs/HOOKS.md - No changes needed
+
+Verification:
+  • README length: 516 lines (target: <600)
+  • All new docs linked: Yes
+  • CHANGELOG has entry: Yes
+
+═══════════════════════════════════════════════════════════════
+```
+
+## Decision Tree
+
+```
+New Feature Added?
+    │
+    ├─► Is it a major workflow change?
+    │       │
+    │       ├─► YES: Create new doc in docs/
+    │       │        Update README links
+    │       │        Update CHANGELOG
+    │       │
+    │       └─► NO: Is it an enhancement to existing command?
+    │               │
+    │               ├─► YES: Update that command's doc
+    │               │        Update CHANGELOG
+    │               │
+    │               └─► NO: Is it a minor fix?
+    │                       │
+    │                       └─► YES: Update CHANGELOG only
+    │
+    └─► Removing a feature?
+            │
+            ├─► WARNING: Removal requires justification
+            │   Only remove if:
+            │   - Feature never worked
+            │   - Replaced by better feature
+            │   - Security issue
+            │
+            └─► Update CHANGELOG with [BREAKING] if public API
+```
+
+## README Structure Limits
+
+| Section | Max Lines | Current |
+|---------|-----------|---------|
+| Header/Banner | 30 | - |
+| Quick Start | 20 | - |
+| Workflows | 50 | - |
+| Phases Diagram | 30 | - |
+| What Gets Installed | 20 | - |
+| Subagents | 20 | - |
+| Commands | 40 | - |
+| Documentation Links | 60 | - |
+| FAQ | 150 | - |
+| **Total** | **~500** | - |
+
+If README exceeds 600 lines, move content to dedicated docs.
+
+## Commands
+
+```bash
+# Run documentation update check
+/docs-update
+
+# Check what would be updated (dry run)
+/docs-update --dry-run
+
+# Force update all docs
+/docs-update --force
+
+# Update specific doc only
+/docs-update --target README
+```
+
+## Integration
+
+This skill integrates with:
+- `docs-update-check.py` hook (PostToolUse on Write/Edit)
+- Phase 13 (Documentation) of all workflows
+- `/commit` skill (suggests doc updates before commit)
+
+## See Also
+
+- [docs/SKILLS.md](../../docs/SKILLS.md) - All skills reference
+- [docs/HOOKS.md](../../docs/HOOKS.md) - All hooks reference
+- [CHANGELOG.md](../../CHANGELOG.md) - Version history

package/.skills/hustle-brand/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: hustle-brand
+description: Create and edit comprehensive brand guide with interview-driven discovery
+tools: Bash, Read, Write, Glob, Grep, Task, AskUserQuestion, TodoWrite
+model: sonnet
+---
+
+# Hustle Brand - Brand Guide Creator
+
+Create a comprehensive brand guide through interview-driven discovery. The brand guide becomes the single source of truth for all UI development, ensuring consistency across every component, page, and interaction.
+
+## Why This Matters
+
+> **Without a brand guide**, every AI-generated component looks slightly different.
+> Colors drift, fonts vary, animations feel inconsistent.
+> **With a brand guide**, every element feels like it belongs.
+
+## When to Use
+
+- During initial project setup (Installation Wizard Phase 3)
+- Anytime with `/hustle-brand` to create or edit
+- Before any UI development work
+- When rebranding or updating visual identity
+
+## What Gets Created
+
+### 1. Brand Guide Document (`.claude/BRAND_GUIDE.md`)
+
+The comprehensive brand specification including:
+- Colors (primary, secondary, accent, semantic, gradients)
+- Typography (fonts, sizes, weights, line heights)
+- Spacing system (consistent padding/margins)
+- Border radius conventions
+- Shadows and elevation
+- Animation principles (timing, easing, motion style)
+- Voice and tone guidelines
+- Terminology dictionary
+- Do's and Don'ts
+
+### 2. Brand Page (`src/app/brand/page.tsx`)
+
+A living showcase of your brand including:
+- Color palette with copy-to-clipboard
+- Typography scale demonstration
+- Button states (default, hover, active, disabled, loading)
+- Form elements (inputs, selects, checkboxes, radios)
+- Card variations
+- Animation examples (GSAP, Framer Motion, CSS)
+- Custom elements from interview (Three.js, terminal effects, etc.)
+- Voice examples
+
+### 3. ShadCN Theme (`src/lib/theme.ts`)
+
+All brand values as CSS variables for ShadCN:
+```css
+:root {
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  /* ... full theme */
+}
+```
+
+### 4. Registry Entry
+
+Brand tracked in `registry.json`:
+```json
+{
+  "brand_guide": {
+    "created_at": "2025-12-29T10:00:00Z",
+    "last_updated": "2025-12-29T10:00:00Z",
+    "version": 1,
+    "interview_completed": true,
+    "sections": ["colors", "typography", "animations", "voice"],
+    "custom_elements": ["terminal-animation", "gradient-text"]
+  }
+}
+```
+
+## Interview Flow
+
+### Phase 1: Foundation
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        BRAND GUIDE CREATOR                                   │
+│                                                                              │
+│  Let's create your brand guide. This will be the foundation for all UI.     │
+│                                                                              │
+│  You can either:                                                             │
+│  [1] Answer interview questions (Recommended)                                │
+│  [2] Fill out a quick form (faster, uses defaults)                          │
+│  [3] Import from Figma/existing brand kit                                   │
+│                                                                              │
+│  Choice? >                                                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Phase 2: Visual Identity
+
+**Colors:**
+- What's your primary brand color? (hex or description)
+- What mood should the secondary colors convey? (professional, playful, bold)
+- Do you want gradients? What style? (subtle, vibrant, aurora)
+- Dark mode: mirror light, or distinct personality?
+
+**Typography:**
+- What font family? (Inter, system fonts, custom Google Font)
+- What's the personality? (modern, classic, technical, friendly)
+- Do you need code/monospace fonts?
+
+**Spacing & Sizing:**
+- Prefer compact or spacious layouts?
+- Border radius style? (sharp, subtle, fully rounded)
+- Shadow depth? (flat, subtle, elevated)
+
+### Phase 3: Motion & Animation
+
+**Animation Style:**
+- What's the motion personality? (snappy, smooth, bouncy, minimal)
+- Preferred library? (CSS, Framer Motion, GSAP, none)
+- Special effects wanted? (parallax, 3D, particles, terminal)
+
+**Loading States:**
+- Skeleton loaders or spinners?
+- Progress bars style?
+- Micro-interactions level? (subtle, noticeable, delightful)
+
+### Phase 4: Voice & Tone
+
+**Share of Voice:**
+```
+How should the UI communicate?
+
+[1] Professional & Informative (Recommended)
+    "Your report is ready for download."
+
+[2] Friendly & Casual
+    "Hey! Your report's all done. Grab it here!"
+
+[3] Technical & Precise
+    "Report generated. 847 records processed. Download available."
+
+[4] Playful & Character-driven
+    "Beep boop! I crunched those numbers for you!"
+
+[5] Custom (describe your voice)
+```
+
+**Terminology:**
+- What do you call your users? (users, members, customers, friends)
+- CTA language preference? (Get Started, Begin, Let's Go, Start Free)
+- Error tone? (apologetic, matter-of-fact, helpful)
+
+### Phase 5: Custom Elements
+
+Based on your answers, I'll suggest custom elements:
+
+```
+Based on your "technical + snappy" preferences, consider:
+
+[x] Terminal-style code animations
+[x] Typing effect for hero text
+[ ] Matrix rain background
+[x] Syntax-highlighted code blocks
+[ ] ASCII art elements
+[ ] Glitch effects
+
+Select the ones you want (comma-separated): > 1,2,4
+```
+
+### Phase 6: Generation
+
+After interview completion:
+
+1. Generate `BRAND_GUIDE.md` with all specifications
+2. Create Brand Page with live examples
+3. Configure ShadCN theme variables
+4. Update registry with brand metadata
+5. Add to dashboard navigation
+
+## Brand Page Structure
+
+```tsx
+// src/app/brand/page.tsx
+export default function BrandPage() {
+  return (
+    <div className="container py-12 space-y-16">
+      {/* Header */}
+      <BrandHeader />
+
+      {/* Color Palette */}
+      <ColorPalette />
+
+      {/* Typography Scale */}
+      <TypographyShowcase />
+
+      {/* Components */}
+      <section>
+        <h2>Components</h2>
+        <ButtonStates />
+        <FormElements />
+        <CardVariations />
+        <NavigationExamples />
+      </section>
+
+      {/* Animations */}
+      <section>
+        <h2>Motion</h2>
+        <AnimationExamples />
+        <LoadingStates />
+        <MicroInteractions />
+      </section>
+
+      {/* Custom Elements */}
+      <section>
+        <h2>Custom Elements</h2>
+        {/* Based on interview: terminal, gradients, etc. */}
+        <CustomElementShowcase />
+      </section>
+
+      {/* Voice Examples */}
+      <section>
+        <h2>Voice & Tone</h2>
+        <VoiceExamples />
+        <TerminologyGuide />
+        <DosAndDonts />
+      </section>
+    </div>
+  );
+}
+```
+
+## ShadCN Integration
+
+All UI uses ShadCN components configured with brand values:
+
+```bash
+# Initialize ShadCN with brand theme
+npx shadcn@latest init
+
+# Components auto-use brand colors
+npx shadcn@latest add button input card
+```
+
+Theme enforced via `tailwind.config.ts`:
+```ts
+theme: {
+  extend: {
+    colors: {
+      // Generated from brand interview
+      primary: "hsl(var(--primary))",
+      secondary: "hsl(var(--secondary))",
+      accent: "hsl(var(--accent))",
+    },
+    fontFamily: {
+      // From brand interview
+      sans: ["var(--font-sans)", ...defaultTheme.fontFamily.sans],
+    },
+    animation: {
+      // Brand-specific animations
+      "fade-in": "fadeIn var(--animation-duration) var(--animation-easing)",
+    }
+  }
+}
+```
+
+## Freshness & Updates
+
+Brand guide tracked with freshness:
+- Last updated timestamp in registry
+- `/hustle-brand` shows time since last update
+- Prompts for review if >30 days old
+- Version history for rollback
+
+## Commands
+
+```bash
+# Create new brand guide (full interview)
+/hustle-brand
+
+# Quick edit specific section
+/hustle-brand --edit colors
+/hustle-brand --edit typography
+/hustle-brand --edit voice
+
+# View current brand summary
+/hustle-brand --status
+
+# Export brand kit
+/hustle-brand --export
+
+# Reset and start over
+/hustle-brand --reset
+```
+
+## Dashboard Integration
+
+Brand page linked from Hustle Dev Dashboard:
+- "Brand Guide" card with last updated date
+- Quick preview of primary colors
+- Link to full brand page
+- Edit button launching `/hustle-brand --edit`
+
+## Installation Wizard Integration
+
+During initial setup:
+
+```
+═══════════════════════════════════════════════════════════════════
+                    HUSTLE DEV TOOLS - SETUP
+═══════════════════════════════════════════════════════════════════
+
+Step 3 of 8: Brand Guide Setup
+
+  A brand guide ensures all AI-generated UI looks consistent.
+  This is HIGHLY RECOMMENDED but can be done later.
+
+  [1] Create brand guide now (5-10 min interview)
+  [2] Use defaults (can customize later with /hustle-brand)
+  [3] Skip for now (warning: UI may be inconsistent)
+
+  Choice? >
+═══════════════════════════════════════════════════════════════════
+```
+
+## Example Output
+
+After completing the interview:
+
+```
+═══════════════════════════════════════════════════════════════════
+                    BRAND GUIDE CREATED
+═══════════════════════════════════════════════════════════════════
+
+Files Created:
+  ✅ .claude/BRAND_GUIDE.md (comprehensive spec)
+  ✅ src/app/brand/page.tsx (live showcase)
+  ✅ src/lib/theme.ts (ShadCN config)
+  ✅ src/styles/brand.css (CSS variables)
+
+Brand Summary:
+───────────────────────────────────────
+  Primary:     #6366F1 (Indigo)
+  Secondary:   #F1F5F9 (Slate)
+  Font:        Inter
+  Motion:      Snappy (200ms ease-out)
+  Voice:       Professional & Helpful
+───────────────────────────────────────
+
+Custom Elements Included:
+  • Terminal-style code animations
+  • Gradient text effects
+  • Skeleton loaders
+
+Quick Links:
+  📖 Brand Page:  http://localhost:3000/brand
+  📝 Edit Brand:  /hustle-brand --edit
+  🎨 Dashboard:   http://localhost:3000/hustle-dev-dashboard
+
+═══════════════════════════════════════════════════════════════════
+```
+
+## See Also
+
+- `/hustle-ui-create` - Uses brand guide for components
+- `/hustle-ui-create-page` - Uses brand guide for pages
+- `/shadcn` - ShadCN documentation and component installation