create-bashi-starter 1.0.0

package/template/.claude/skills/deployment/SKILL.md

@@ -0,0 +1,301 @@
+---
+id: SKL-0021
+name: Deployment
+description: |
+  Ship workflow: merge main, run tests, review diff, auto-changelog, bisectable
+  commits, push, and create PR. Use this skill when deployment is requested,
+  a release is ready to ship, or the user says "ship it."
+version: 3.0
+owner: builder
+triggers:
+  - DEPLOYMENT_REQUESTED
+  - SHIP_REQUESTED
+inputs:
+  - Task description (from active task or event)
+  - .claude/project/STATE.md
+  - .claude/project/knowledge/DECISIONS.md
+  - TODOS.md (if exists)
+  - CHANGELOG.md (if exists)
+  - VERSION (if exists)
+outputs:
+  - Code committed, pushed, and PR created
+  - CHANGELOG.md updated
+  - VERSION bumped
+  - TODOS.md updated (completed items marked)
+  - .claude/project/STATE.md (updated)
+tags:
+  - deployment
+  - release
+  - ship
+---
+
+# Skill: Deployment & Ship
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | SKL-0021 |
+| **Version** | 3.0 |
+| **Owner** | builder |
+| **Inputs** | Task description, STATE.md, DECISIONS.md, TODOS.md |
+| **Outputs** | Commits, PR, CHANGELOG, VERSION, TODOS.md, STATE.md |
+| **Triggers** | `DEPLOYMENT_REQUESTED`, `SHIP_REQUESTED` |
+
+---
+
+## Purpose
+
+Take code from a feature branch and land it: merge main, test, review, version bump, changelog, commit, push, PR.
+
+---
+
+## Cognitive Mode
+
+**Release Engineer.** You are methodical, cautious, and thorough. Every step has a reason. Tests must pass. Reviews must clear. Nothing ships without evidence it works.
+
+---
+
+## Ship Mode
+
+> The user said "ship it" or triggered `SHIP_REQUESTED`. Run straight through. Only stop for blockers.
+
+**Only stop for:**
+- On `main` branch (abort)
+- Merge conflicts that can't be auto-resolved
+- Test failures
+- CRITICAL review findings where user chooses to fix
+- MINOR/MAJOR version bump decisions
+
+**Never stop for:**
+- Uncommitted changes (include them)
+- CHANGELOG content (auto-generate)
+- Commit message approval (auto-commit)
+
+---
+
+## Ship Procedure
+
+### Step 1 --- Pre-flight
+
+1. Check the current branch. If on `main`, **abort**: "You're on main. Ship from a feature branch."
+2. Run `git status` (never use `-uall`). Uncommitted changes are always included.
+3. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what's being shipped.
+
+---
+
+### Step 2 --- Merge origin/main
+
+Fetch and merge so tests run against the merged state:
+
+```bash
+git fetch origin main && git merge origin/main --no-edit
+```
+
+**If merge conflicts:** Try to auto-resolve simple ones (VERSION, CHANGELOG ordering). If complex, **STOP** and show them.
+
+**If already up to date:** Continue silently.
+
+---
+
+### Step 3 --- Run Tests
+
+Detect and run the project's test suite:
+
+```bash
+# Detect test runner
+if [ -f "package.json" ]; then npm test 2>&1 | tee /tmp/ship_tests.txt; fi
+if [ -f "pytest.ini" ] || [ -f "setup.py" ]; then pytest 2>&1 | tee /tmp/ship_tests.txt; fi
+if [ -f "Gemfile" ]; then bundle exec rspec 2>&1 | tee /tmp/ship_tests.txt; fi
+```
+
+If no test runner is detected, note it and continue (many early projects don't have tests yet).
+
+**If any test fails:** Show the failures and **STOP**. Do not proceed.
+
+**If all pass:** Note the counts briefly and continue.
+
+---
+
+### Step 4 --- Pre-Landing Review
+
+Run a lightweight review of the diff:
+
+1. Run `git diff origin/main` to get the full diff.
+2. Apply a two-pass review:
+   - **Pass 1 (CRITICAL):** Security vulnerabilities, hardcoded secrets, data safety issues, trust boundary violations
+   - **Pass 2 (INFORMATIONAL):** Code quality, consistency, test gaps
+
+3. Output: `Pre-Landing Review: N issues (X critical, Y informational)`
+
+4. **If CRITICAL issues found:** For EACH, present individually with:
+   - Problem + recommended fix
+   - Options: A) Fix it now, B) Acknowledge and ship anyway, C) False positive
+   - If user chose A on any: apply fixes, commit them, then **re-run tests** (Step 3) before continuing.
+
+5. **If no critical issues:** Continue.
+
+---
+
+### Step 5 --- Version Bump
+
+**If a VERSION file exists:**
+
+1. Read the current version.
+2. Auto-decide bump level:
+   - Count lines changed: `git diff origin/main...HEAD --stat | tail -1`
+   - **PATCH** (default): Most changes --- bug fixes, small-medium features
+   - **MINOR**: Ask the user --- only for major features or significant changes
+   - **MAJOR**: Ask the user --- only for milestones or breaking changes
+3. Write the new version to VERSION.
+
+**If no VERSION file exists:** Skip this step.
+
+---
+
+### Step 6 --- Auto-Generate CHANGELOG
+
+1. Read `CHANGELOG.md` header (if exists) to match format. If no CHANGELOG exists, create one.
+2. Generate entry from all commits on the branch:
+   - `git log main..HEAD --oneline` for commit history
+   - `git diff main...HEAD` for the full diff
+3. Categorize changes:
+   - `### Added` --- new features
+   - `### Changed` --- changes to existing functionality
+   - `### Fixed` --- bug fixes
+   - `### Removed` --- removed features
+4. Write concise, descriptive bullet points.
+5. Insert after the file header, dated today.
+6. Format: `## [version] - YYYY-MM-DD` (use version from Step 5, or "Unreleased" if no VERSION file).
+
+**Do NOT ask the user to describe changes.** Infer from the diff and commits.
+
+---
+
+### Step 7 --- TODOS.md Cross-Reference
+
+If `TODOS.md` exists:
+
+1. Read the file.
+2. Use the diff and commit history to detect completed TODOs:
+   - Match commit messages against TODO descriptions
+   - Check if files referenced in TODOs appear in the diff
+   - **Be conservative** --- only mark as complete with clear evidence
+3. Move completed items to the `## Completed` section with: `**Completed:** vX.Y.Z (YYYY-MM-DD)`
+4. Output: `TODOS.md: N items marked complete. M items remaining.`
+
+If `TODOS.md` doesn't exist, skip silently.
+
+---
+
+### Step 8 --- Commit (Bisectable Chunks)
+
+**Goal:** Create small, logical commits that work with `git bisect`.
+
+1. Analyze the diff and group changes into logical commits. Each commit = one coherent change (not one file, one logical unit).
+
+2. **Commit ordering** (earlier first):
+   - **Infrastructure:** migrations, config, routes
+   - **Core logic:** models, services, utilities (with their tests)
+   - **UI/presentation:** controllers, views, components (with their tests)
+   - **Metadata:** VERSION + CHANGELOG (always the final commit)
+
+3. **Rules:**
+   - A module and its test file go in the same commit
+   - Each commit must be independently valid --- no broken imports
+   - If total diff is small (<50 lines across <4 files), a single commit is fine
+   - Order commits so dependencies come first
+
+4. Compose commit messages:
+   - First line: `<type>: <summary>` (type = feat/fix/chore/refactor/docs)
+   - Only the **final commit** (VERSION + CHANGELOG) gets the co-author trailer:
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: bump version and changelog (vX.Y.Z)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Step 9 --- Push
+
+```bash
+git push -u origin <branch-name>
+```
+
+**Never force push.**
+
+---
+
+### Step 10 --- Create PR
+
+```bash
+gh pr create --title "<type>: <summary>" --body "$(cat <<'EOF'
+## Summary
+<bullet points from CHANGELOG>
+
+## Pre-Landing Review
+<findings from Step 4, or "No issues found.">
+
+## TODOS
+<completed items, or "No TODO items completed in this PR.">
+
+## Test plan
+- [x] All tests pass
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+**Output the PR URL** --- this is the final output.
+
+---
+
+### Step 11 --- Update STATE.md
+
+Record: version shipped, PR URL, files changed, TODOS completed.
+
+---
+
+## Constraints
+
+- Never force pushes
+- Never commits secrets or real env var values
+- Never ships without running tests
+- Never skips the pre-landing review
+- Ship Mode is non-interactive by default --- only stops for blockers
+
+---
+
+## Primary Agent
+
+builder
+
+---
+
+## Definition of Done
+
+- [ ] Pre-flight check passed (not on main, diff exists)
+- [ ] origin/main merged
+- [ ] Tests pass
+- [ ] Pre-landing review completed
+- [ ] VERSION bumped (if VERSION file exists)
+- [ ] CHANGELOG generated
+- [ ] TODOS.md cross-referenced
+- [ ] Commits are bisectable and logically grouped
+- [ ] Pushed to remote
+- [ ] PR created with summary
+- [ ] STATE.md updated
+
+## Output Contract
+
+| Field | Value |
+|-------|-------|
+| **Artifacts** | Commits pushed, PR created, `CHANGELOG.md` updated, `VERSION` bumped |
+| **State Update** | `.claude/project/STATE.md` --- mark task complete, log files modified |
+| **Handoff Event** | `TASK_COMPLETED` (terminal step in pipeline) |

package/template/.claude/skills/frontend-dev/SKILL.md

@@ -0,0 +1,192 @@
+---
+id: SKL-0005
+name: Frontend Development
+description: |
+  Build web UI components, pages, and styling. Includes a mandatory Visual
+  Polish pass that adds scroll animations, micro-interactions, typography
+  rhythm, and design depth. Use this skill when a frontend task is ready for
+  implementation, including React components, CSS, layouts, and responsive design.
+version: 2.0
+owner: builder
+triggers:
+  - FRONTEND_TASK_READY
+inputs:
+  - Task description (from STATE.md)
+  - .claude/project/knowledge/DECISIONS.md
+  - Existing frontend files
+  - docs/PRD.md (for brand/tone context)
+outputs:
+  - Frontend component/page files
+  - .claude/project/STATE.md (updated)
+tags:
+  - building
+  - frontend
+  - ui
+---
+
+# Skill: Frontend Development
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | SKL-0005 |
+| **Version** | 2.0 |
+| **Owner** | builder |
+| **Inputs** | Task description, DECISIONS.md, existing frontend files, PRD |
+| **Outputs** | Frontend files, STATE.md updated |
+| **Triggers** | `FRONTEND_TASK_READY` |
+
+---
+
+## Purpose
+
+Build user interfaces that work correctly AND look exceptional. Correctness (responsive, accessible, all states handled) is the floor, not the ceiling. Every page and component must pass a Visual Polish check before it's considered done.
+
+---
+
+## Procedure
+
+### Step 1 --- Read Context
+
+1. **Read DECISIONS.md** --- identify framework (React/Next.js, Vue, Astro, vanilla), styling approach (Tailwind, CSS modules), component library (shadcn/ui, Radix, etc.).
+2. **Read PRD** --- extract brand tone, target audience, and visual expectations.
+3. **Scan existing code** --- identify conventions, color tokens, font choices, animation patterns already in use.
+
+### Step 2 --- Understand the Task
+
+- What does this UI do? Who uses it? What data does it display or collect?
+- What is the emotional tone? (professional, playful, luxurious, minimal, bold)
+- Is this a hero page (high visual impact) or a utility screen (functional first)?
+
+### Step 3 --- Build the Component/Page
+
+Core implementation:
+- Match existing file structure and naming conventions
+- Mobile-first responsive design
+- Accessible markup (semantic HTML, ARIA labels, keyboard navigation)
+- No hardcoded data --- use props, state, or labeled placeholders
+- Handle all states: loading, error, empty, populated
+
+### Step 4 --- Visual Polish Pass (Mandatory)
+
+After the component works correctly, apply these checks. **This step is not optional.**
+
+#### 4A. Typography Rhythm
+
+| Check | What to Do |
+|-------|-----------|
+| Font pairing | Use a deliberate serif + sans-serif pairing OR a single family with weight contrast. Never rely on system defaults alone. |
+| Size scale | Headings should have clear hierarchy --- at least 3 distinct sizes with noticeable jumps (not 16px -> 18px -> 20px). |
+| Line height | Body text: 1.5-1.7. Headings: 1.1-1.3. Tight headings + relaxed body creates rhythm. |
+| Letter spacing | Uppercase labels need positive tracking (0.05-0.15em). Large headings can use slight negative tracking. |
+| One "wow" text moment | At least one headline, quote, or stat should be oversized, italic, or styled distinctly to break the grid. |
+
+#### 4B. Scroll Animations
+
+| Check | What to Do |
+|-------|-----------|
+| Section reveals | Content sections should animate in on scroll --- fade-up, slide-in, or scale. Use Framer Motion, AOS, or CSS `@keyframes` with Intersection Observer. |
+| Staggered children | Lists, grids, and card groups should stagger their entrance (50-100ms delay between items). |
+| Parallax (optional) | Hero images or background elements can scroll at a different rate for depth. Use sparingly --- one parallax element max. |
+| Respect `prefers-reduced-motion` | Wrap all animations in a motion-preference check. Users who disable motion see instant renders. |
+
+#### 4C. Micro-Interactions
+
+| Check | What to Do |
+|-------|-----------|
+| Button hover | Buttons should have a visible hover state beyond color change --- slight scale (1.02-1.05), shadow lift, or fill animation. |
+| Image hover | Gallery/portfolio images should respond to hover --- zoom, overlay fade, or caption reveal. |
+| Focus indicators | Interactive elements need visible focus rings that match the design language (not default browser blue). |
+| Transitions | All state changes (hover, active, focus, open/close) should use `transition-all duration-200` minimum. No instant snaps. |
+| Cursor | Consider `cursor-pointer` on all clickable non-link elements. |
+
+#### 4D. Visual Depth
+
+| Check | What to Do |
+|-------|-----------|
+| Layering | At least one section should have overlapping elements --- a card that bleeds over a section boundary, text over an image, or a floating accent. |
+| Shadows | Cards and elevated elements need subtle shadows (`shadow-sm` to `shadow-lg`). Avoid flat designs where everything is on the same plane. |
+| Gradients | Use subtle background gradients to separate sections instead of hard color blocks. Gradient overlays on hero images add depth. |
+| Texture (optional) | Subtle noise/grain overlay, dot patterns, or background shapes can add personality. Don't overdo it --- one texture element per page. |
+| Whitespace | Generous padding between sections (py-16 to py-24). Tight spacing looks cheap; breathing room looks premium. |
+
+#### 4E. Color & Contrast
+
+| Check | What to Do |
+|-------|-----------|
+| Limited palette | 1 primary, 1 accent, 2-3 neutrals. More than 5 colors looks chaotic. |
+| Contrast ratio | Text on backgrounds must meet WCAG 2.1 AA (4.5:1 normal, 3:1 large). |
+| Dark sections | At least one section should use an inverted color scheme (dark background, light text) for visual variety. |
+| Accent usage | The accent color should appear sparingly --- CTAs, highlights, decorative elements. Not on large surfaces. |
+
+#### 4F. Component Library
+
+When a project uses shadcn/ui, Radix, or a similar component library:
+- **Use it.** Don't rebuild what exists.
+- Customize through the theme/token layer, not by overriding styles.
+- When no library is specified, **suggest shadcn/ui for React/Next.js projects** --- it provides beautiful defaults with Tailwind customization. Log this to DECISIONS.md.
+
+### Step 5 --- Final Quality Check
+
+Before marking done, verify:
+- Does the page look good at 320px, 768px, and 1440px?
+- Does it look polished in both light and dark modes (if applicable)?
+- Is there at least one visual "moment" that makes someone pause? (a hero animation, a beautiful card grid, an unexpected typographic treatment)
+- Would you screenshot this and put it in a portfolio?
+
+### Step 6 --- Update STATE.md
+
+Record files created and note the visual approach taken (for consistency across future pages).
+
+---
+
+## Constraints
+
+- Never modifies backend, API, or database files
+- Never hardcodes data that should come from an API or prop
+- Always logs new framework/library decisions to DECISIONS.md
+- Visual Polish (Step 4) is mandatory --- never skip it, even for "simple" pages
+- Respect existing design language --- polish should enhance the current direction, not introduce a conflicting aesthetic
+- Animations must respect `prefers-reduced-motion`
+
+---
+
+## Deployment Reference
+
+| Target | Tool | Notes |
+|--------|------|-------|
+| Static/SPA | Vercel | Zero config for React/Next.js |
+| Static/SPA | Netlify | Drag and drop or Git deploy |
+| Next.js/SSR | Vercel | Native support |
+
+---
+
+## Primary Agent
+
+builder
+
+---
+
+## Definition of Done
+
+- [ ] Framework and styling confirmed from DECISIONS.md
+- [ ] Component handles loading, error, empty, populated states
+- [ ] Mobile-first responsive layout (tested at 320px, 768px, 1440px)
+- [ ] Accessible markup (semantic HTML, ARIA, keyboard nav, focus indicators)
+- [ ] Matches existing project conventions
+- [ ] **Typography rhythm applied** (hierarchy, pairing, one "wow" moment)
+- [ ] **Scroll animations added** (section reveals, staggered children, reduced-motion respected)
+- [ ] **Micro-interactions present** (button hover, image hover, transitions on all state changes)
+- [ ] **Visual depth achieved** (shadows, layering, gradients, generous whitespace)
+- [ ] **Color palette limited and contrast-checked**
+- [ ] At least one visual moment that would make someone pause
+- [ ] STATE.md updated
+
+## Output Contract
+
+| Field | Value |
+|-------|-------|
+| **Artifacts** | Frontend component/page files (components, pages, styles, assets) |
+| **State Update** | `.claude/project/STATE.md` --- mark task complete, log files modified |
+| **Handoff Event** | `TASK_COMPLETED` (ready for code review) |

package/template/.claude/skills/plan-from-idea/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: SKL-0001
+name: Plan From Idea
+description: |
+  Transform a captured project idea into an actionable plan with PRD and task
+  breakdown. Use this skill when a new idea has been captured and needs to be
+  developed into a structured project plan.
+version: 1.0
+owner: Orchestrator
+triggers:
+  - IDEA_CAPTURED
+inputs:
+  - Idea description (from event or user input)
+outputs:
+  - docs/PRD.md
+  - .claude/project/STATE.md (Next Task Queue updated)
+tags:
+  - planning
+  - ideation
+---
+
+# Skill: Plan From Idea
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | SKL-0001 |
+| **Version** | 1.0 |
+| **Owner** | Orchestrator |
+| **Inputs** | Idea description (from event or user input) |
+| **Outputs** | PRD stub (`docs/PRD.md` or equivalent), initial task queue items |
+| **Triggers** | `IDEA_CAPTURED` |
+
+---
+
+## Purpose
+
+Turn a rough idea into a structured plan. This skill takes a freeform idea description and produces:
+1. A short PRD (Product Requirements Document) stub.
+2. An initial set of tasks added to the Next Task Queue in STATE.md.
+
+---
+
+## Procedure
+
+1. **Read the idea** from the event description or user input.
+2. **Create a PRD stub** at `docs/PRD.md` (or the project's preferred location) with:
+   - Project name
+   - One-sentence summary
+   - Target audience
+   - Core features (3-5 bullet points)
+   - Out of scope (2-3 items)
+   - Success criteria
+3. **Generate 3-5 initial tasks** based on the PRD and add them to the Next Task Queue in `STATE.md`. Use the canonical task format from `.claude/project/knowledge/TASK-FORMAT.md`: `| # | Task | Priority | Skill |`. Assign Skill IDs by cross-referencing `REGISTRY.md` (use `---` if no skill clearly applies).
+4. **Log a decision** in `DECISIONS.md` noting the project direction chosen.
+5. **Update STATE.md** with outputs produced and files modified.
+
+---
+
+## Primary Agent
+
+Orchestrator
+
+## Review
+
+None required for v1. The user reviews the PRD and task queue after execution.
+
+---
+
+## Definition of Done
+
+- [ ] PRD stub exists at `docs/PRD.md` (or equivalent project brief)
+- [ ] At least 3 tasks are added to the Next Task Queue
+- [ ] STATE.md is updated with outputs and files modified
+- [ ] Decision logged in DECISIONS.md
+
+## Output Contract
+
+| Field | Value |
+|-------|-------|
+| **Artifacts** | Actionable plan in `.claude/project/STATE.md` (Next Task Queue seeded), PRD stub at `docs/PRD.md`, event emitted |
+| **State Update** | `.claude/project/STATE.md` --- mark task complete, log files modified |
+| **Decision Log** | `.claude/project/knowledge/DECISIONS.md` --- project direction chosen |
+| **Handoff Event** | `PRD_CREATION_REQUESTED` (triggers PRD writing via SKL-0004) |