@seanyao/roll 0.5.0

package/conventions/templates/fullstack/AGENTS.md

@@ -0,0 +1,87 @@
+# Project Conventions — Fullstack Web
+
+> Project-type-specific conventions — reference material for skills.
+> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+
+## Frontend
+
+- Stack: React 18+ / TypeScript / Vite / Tailwind CSS / shadcn/ui / Lucide React
+- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
+- `src/components/ui/` is shadcn-generated — never edit manually.
+- `src/components/[feature]/` for custom feature components.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+- Organize by domain: `src/domains/{domain}/components/`, `hooks/`, `services/`, `types.ts`
+- Shared utilities in `src/shared/` (api/, types/, utils/, hooks/).
+
+## Backend
+
+- RESTful API conventions. Consistent URL structure: `/api/{resource}/{id}`.
+- Structured error responses: `{ error: string, code: string, details?: object }`.
+- Environment-based config via `.env`. Never hardcode secrets.
+- Folder structure:
+  - `src/routes/` or `api/routes/` — route handlers
+  - `src/services/` or `api/services/` — business logic
+  - `src/models/` or `api/models/` — data models and schemas
+- Health check endpoint: `GET /api/health`
+- Authentication: JWT in httpOnly cookies.
+
+## Architecture
+
+- **Domain Driven Design**: organize code by business domain, not technical layer.
+- **Clean Architecture**: UI → Application (hooks) → Domain (services) → Infrastructure (API/DB).
+- **Decoupling**: UI renders only, logic lives in hooks. API calls wrapped in services.
+- **Data Schema First**: define types/schemas before writing business logic.
+- **Frontend-Backend Contract**: API changes must sync `shared/types/`. Errors use unified format.
+
+## Project Structure
+
+```
+src/
+├── components/ui/        # shadcn/ui (generated, don't edit)
+├── domains/              # DDD by business domain
+│   └── {domain}/
+│       ├── components/   # domain-specific UI
+│       ├── hooks/        # domain logic
+│       ├── services/     # API calls
+│       └── types.ts      # domain types
+├── shared/
+│   ├── api/              # HTTP client, interceptors
+│   ├── types/            # shared type definitions
+│   └── utils/            # utility functions
+├── App.tsx
+└── main.tsx
+
+api/
+├── routes/               # RESTful route handlers
+├── services/             # business logic
+├── models/               # data models
+└── types.ts              # API contract types
+
+schema/                   # data contract definitions
+tests/
+├── unit/                 # Vitest
+├── e2e/                  # Playwright
+└── regression/           # Sentinel regression
+```
+
+## Development Discipline
+
+- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
+- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
+- **Verification Gate**: Before marking done, provide fresh evidence (test output, screenshot, curl). "I confirmed it works" is not evidence.
+- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
+
+## Testing Requirements
+
+- All business logic must have unit tests (coverage >80%).
+- All API endpoints must have integration tests — no DB mocks, use real database.
+- Critical user flows must have E2E tests (Playwright).
+- New architecture introductions (State/Cache/EventBus) must have data flow integration tests.
+- Sentinel will periodically regression-test completed Stories.
+
+## Workspace Structure
+
+- `BACKLOG.md` = index table, one-line summary per story only.
+- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
+- `docs/features/<feature>-plan.md` = architecture design doc (optional).
+- Never write project docs to `~/.kimi/` or any global config directory.

package/conventions/templates/fullstack/CLAUDE.md

@@ -0,0 +1,17 @@
+# Project Preferences — Fullstack Web (Claude Code)
+
+> Extends global CLAUDE.md + project AGENTS.md.
+
+## Stack
+
+- Frontend: React + shadcn/ui + Tailwind CSS + Vite
+- Backend: Node.js API (Express/Hono/Fastify)
+- Testing: Vitest (unit) + Playwright (E2E)
+- Deploy: Vercel (frontend) + Railway/Fly.io (backend)
+
+## Claude Code Notes
+
+- Use `$roll-design` to plan features that span frontend and backend.
+- When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
+- Use worktree isolation for parallel frontend/backend Actions in `$roll-story-build`.
+- Run `npm run build` to verify both frontend and backend compile before pushing.

package/conventions/templates/fullstack/GEMINI.md

@@ -0,0 +1,15 @@
+# Project Preferences — Fullstack Web (Gemini CLI)
+
+> Extends global GEMINI.md + project AGENTS.md.
+
+## Stack
+
+- Frontend: React + shadcn/ui + Tailwind CSS + Vite
+- Backend: Node.js API (Express/Hono/Fastify)
+- Testing: Vitest (unit) + Playwright (E2E)
+
+## Gemini Notes
+
+- When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
+- Run `npm run build` to verify both frontend and backend compile before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@seanyao/roll",
+  "version": "0.5.0",
+  "description": "Roll — Roll out features with AI agents",
+  "scripts": {
+    "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "development-workflow",
+    "skills",
+    "agent-first"
+  ],
+  "homepage": "https://github.com/seanyao/roll",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seanyao/roll.git"
+  },
+  "bin": {
+    "roll": "./bin/roll"
+  },
+  "license": "MIT",
+  "author": "Sean Yao <seanyao@gmail.com>",
+  "files": [
+    "bin/",
+    "conventions/",
+    "skills/",
+    "tools/",
+    "template/",
+    "README.md"
+  ]
+}

package/skills/roll-.changelog/SKILL.md

@@ -0,0 +1,79 @@
+---
+hidden: true
+name: roll-.changelog
+description: After build completion, extracts completed Stories from BACKLOG.md to generate CHANGELOG.md. Auto-triggered after successful deploy, keeping the external changelog in sync with the internal backlog.
+---
+
+# WK Generate Changelog
+
+After successful Build & Deploy, extracts completed Stories from BACKLOG.md to generate a user-friendly `CHANGELOG.md`.
+
+## When Triggered
+
+- **Auto-triggered**: After successful deploy of `$roll-story` or `$roll-fix`
+- **Manual trigger**: When user requests "update changelog" or "generate release notes"
+
+## Workflow
+
+### 1. Read BACKLOG.md
+
+```
+Read BACKLOG.md from the project root directory.
+Extract Stories with status ✅ Completed / Done.
+```
+
+### 2. Filter for External Content
+
+**Remove internal information:**
+- Progress tables, completion percentages
+- "As a / I can / So that" format
+- Detailed AC checklists
+- Technical debt, internal file paths
+- Test case counts, architecture diagrams
+
+**Keep user-facing value:**
+- New features (one-sentence description)
+- Bug fixes (user-visible impact)
+- UX improvements (layout, interaction enhancements)
+- Performance/reliability improvements
+
+### 3. Version Number Format
+
+```
+YYYY.MM.DD
+YYYY.MM.DD-1  (multiple releases on the same day)
+YYYY.MM.DD-2
+```
+
+### 4. Generate CHANGELOG.md
+
+```markdown
+# Changelog
+
+## 2026.04.03
+- **Added**: <completed feature extracted from BACKLOG>
+- **Fixed**: <resolved bug>
+- **Improved**: <UX/performance optimization>
+
+## 2026.04.01
+- ...
+```
+
+**Ordering**: Most recent version first (reverse chronological)
+
+### 5. Commit Update
+
+```bash
+git add CHANGELOG.md
+git commit -m "docs: update changelog for release $(date +%Y.%m.%d)"
+git push
+```
+
+## Integration
+
+After successful deploy in `$roll-story` / `$roll-fix` / `$roll-fly`:
+
+```markdown
+**Post-Deploy:**
+- `$roll-.changelog` - Sync external changelog
+```

package/skills/roll-.clarify/SKILL.md

@@ -0,0 +1,59 @@
+---
+hidden: true
+name: roll-.clarify
+description: |
+  Passive scope-clarification skill. Auto-triggers when roll-build receives vague or under-specified input in Fly mode. Summarizes intent and asks 3–5 targeted questions to establish boundaries before planning or coding.
+  This is a passive skill. Never announce "I'm using roll-.clarify." Just do it naturally: summarize, ask, wait.
+---
+
+# roll-.clarify
+
+> Understand first, build second.
+
+## Trigger
+
+Auto-invoked by `roll-build` (Fly mode) when the user input is:
+- A single vague sentence
+- Missing clear boundaries (what/who/when/where)
+- Contains ambiguous terms like "优化一下", "改一下", "加个东西"
+- Could be interpreted in multiple ways
+
+**Do NOT activate when:**
+- Intent is already clear and actionable
+- User gives a specific command with a skill trigger (e.g. `$roll-jot ...`)
+- User is answering a clarification question you just asked
+- The task is simple enough that misinterpretation risk is negligible
+
+## Behavior
+
+1. **Summarize** the user's intent in 1–2 sentences.
+2. **Assess complexity** (small / medium / large).
+3. **Ask 3–5 targeted questions** to fill the biggest gaps. Focus on:
+   - Scope: what exactly is in / out?
+   - User: who is the actor?
+   - Data: what changes or persists?
+   - Edge cases: what could go wrong?
+   - Verification: how will we know it's done?
+
+## Output format
+
+```
+🎯 Clarified Intent: {1-2 sentences}
+
+📏 Complexity: {small|medium|large}
+
+❓ Open Questions:
+1. {question 1}
+2. {question 2}
+3. {question 3}
+...
+
+➡️  Please answer the questions above and I'll proceed to planning / building.
+```
+
+## Rules
+
+- Do **not** start coding or planning until the user replies.
+- Questions must be concrete and answerable in one sentence each.
+- If the input is already clear enough, silently return and let `roll-build` continue.
+- Never announce "I'm using roll-.clarify."

package/skills/roll-.echo/SKILL.md

@@ -0,0 +1,113 @@
+---
+hidden: true
+name: roll-.echo
+description: |
+  Passive intent clarification skill. Automatically activates when user input is vague, rambling, contradictory, or unclear. Restates the user's intent in structured, concise form and confirms before proceeding. Does NOT activate when intent is already clear — in that case, just execute directly.
+  This is a passive skill. Never announce "I'm using roll-.echo." Just do it naturally: restate, confirm, proceed.
+---
+
+# Echo
+
+> Passive intent clarification — restate messy thoughts as clear intent, confirm, then act.
+
+## When to Activate
+
+This skill fires **automatically** when the AI detects unclear intent. It should feel natural — not like a skill invocation, but like a thoughtful colleague saying "let me make sure I got that right."
+
+**Activation signals** (any of these):
+- Input is long and rambling (>3 sentences without a clear ask)
+- Multiple ideas tangled together with no clear priority
+- Contradictory statements ("I want X but also not-X")
+- Hedging language: "maybe", "sort of", "I think", "not sure but", "something like"
+- Vague scope: "make it better", "fix this area", "do something about"
+- The intent could reasonably be interpreted in 2+ very different ways
+
+**Do NOT activate when**:
+- Intent is already clear and actionable ("add a login button to the header")
+- User gives a specific command with a skill trigger ("$roll-story US-001")
+- User is answering a question you asked (they're clarifying, not initiating)
+- The task is simple enough that misinterpretation risk is negligible
+
+**When in doubt**: If you're 80%+ confident you understand correctly, just execute. Echo is for the 50/50 situations where getting it wrong would waste real effort.
+
+## How to Echo
+
+### Step 1: Listen completely
+
+Let the user finish. Don't interrupt a stream of consciousness — the clearest signal often comes at the end.
+
+### Step 2: Distill
+
+Extract the core intent from the noise. Structure it as:
+
+```
+What I'm hearing:
+- **Goal**: {what they want to achieve — one sentence}
+- **Scope**: {what's in / what's out}
+- **Priority**: {if multiple things mentioned, which comes first}
+- **Constraints**: {any specific requirements or limitations mentioned}
+```
+
+Only include fields that are relevant. A simple clarification might just be:
+
+```
+So you want: {one clear sentence restating the intent}
+```
+
+### Step 3: Surface ambiguity (if any)
+
+If there are genuine decision points the user needs to resolve:
+
+```
+One thing I want to confirm: {the specific ambiguity, with 2-3 concrete options}
+```
+
+Don't manufacture ambiguity. If you understood fine, skip this.
+
+### Step 4: Confirm and proceed
+
+End with a natural confirmation prompt, then act on the response:
+- If confirmed → route to the appropriate skill or start working
+- If corrected → update understanding, optionally echo again if the correction introduces new ambiguity
+
+## Style
+
+- **Be brief.** The echo should be shorter than the original input, not longer.
+- **Be concrete.** Replace vague language with specific interpretations. "Make it better" → "Improve the search response time" or "Redesign the search UI."
+- **Be natural.** This is a conversation, not a form. Don't use the template rigidly.
+- **No jargon.** Mirror the user's vocabulary, not technical framework terms.
+- **No patronizing.** Don't echo things that are already obvious. The user will feel like you're not listening.
+
+## Anti-Patterns
+
+- Echoing when intent is already clear (wastes the user's time)
+- Echoing every single message (becomes annoying fast)
+- Adding your own ideas to the echo (scope creep — echo is for understanding, not suggesting)
+- Using the echo as a stall tactic when you should just do the work
+- Turning a simple ask into a complex questionnaire
+
+## Examples
+
+### Good Echo (vague input)
+
+**User**: "I've been thinking about the search, it's kind of slow and the results aren't great, maybe we need elasticsearch or something, and also the UI is weird on mobile, the filters don't work right, I don't know, just... it needs work"
+
+**Echo**: "Got it — sounds like two separate issues: (1) search quality and performance (results aren't relevant + slow), and (2) mobile UI broken filters. Want me to tackle them as two separate stories, or is one more urgent?"
+
+### Good Echo (contradictory input)
+
+**User**: "Make the dashboard simpler, but also add the analytics charts we discussed, and the export feature, oh and notifications"
+
+**Echo**: "Those pull in opposite directions — simpler dashboard vs. adding 3 new features. Which do you mean: strip the current dashboard down and then selectively add these features? Or keep what's there and add the new stuff on top?"
+
+### No Echo Needed (clear input)
+
+**User**: "Add a dark mode toggle to the settings page"
+
+*→ Just do it. No echo needed.*
+
+### No Echo Needed (skill trigger)
+
+**User**: "$roll-design search improvements"
+
+*→ Route to roll-design. No echo needed.*

package/skills/roll-.qa/SKILL.md

@@ -0,0 +1,204 @@
+---
+hidden: true
+name: roll-.qa-cover
+description: QA coverage reference for build skills. Defines test pyramid (unit/E2E/visual/smoke), coverage requirements, and CI gates. Ensures quality assurance across all testing layers.
+---
+
+# QA Cover
+
+This is a **reference skill** used by `roll-story`, `roll-fix`, and `roll-fly` for quality assurance and test coverage.
+
+## When to Apply
+
+Any product with a user interface (Web, Desktop, Mobile) must follow these testing standards.
+
+## Required Testing Levels
+
+### 1. Unit Tests (Logic)
+- **Tool**: Vitest / Jest
+- **Coverage**: Business logic, utilities, hooks
+- **Run**: `npm run test`
+
+### 2. E2E Tests (User Flows)
+- **Tool**: **Playwright** (default)
+- **Coverage**: Critical user paths, interactions
+- **Run**: `npm run test:e2e`
+
+### 3. Visual Regression (UI Stability)
+- **Tool**: Playwright screenshot testing
+- **Coverage**: Key UI states
+- **Run**: Part of E2E tests
+- **Baseline**: Stored in `e2e/__snapshots__/`
+
+### 4. Smoke Tests (Post-deploy)
+- **Tool**: Playwright
+- **Coverage**: Core functionality on production
+- **Run**: `npm run test:e2e:smoke`
+
+## Playwright Setup
+
+### Installation
+```bash
+npm install -D @playwright/test
+npx playwright install chromium
+```
+
+### Configuration (playwright.config.ts)
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});
+```
+
+### Required Test Files
+
+**e2e/smoke.spec.ts** (Deployment verification)
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('app loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('#app')).toBeVisible();
+});
+```
+
+**e2e/interaction.spec.ts** (User flows)
+```typescript
+test('user can complete core flow', async ({ page }) => {
+  await page.goto('/');
+  // Test critical user journey
+});
+```
+
+**e2e/visual.spec.ts** (Visual regression)
+```typescript
+test('homepage visual', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png');
+});
+```
+
+### Package.json Scripts
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:smoke": "playwright test smoke.spec.ts",
+    "test:all": "npm run test && npm run test:e2e"
+  }
+}
+```
+
+## Visual Regression Workflow
+
+### 1. Create Baseline (First Time)
+```bash
+npx playwright test --update-snapshots
+```
+
+### 2. Commit Baseline
+```bash
+git add e2e/__snapshots__/
+git commit -m "chore: add visual regression baselines"
+```
+
+### 3. Subsequent Runs (Compare)
+```bash
+npm run test:e2e
+# Fails if screenshots differ beyond threshold
+```
+
+### 4. Update Baseline (Intentional UI Change)
+```bash
+npx playwright test --update-snapshots
+git add e2e/__snapshots__/
+git commit -m "chore: update visual baseline for new design"
+```
+
+## CI/CD Integration
+
+### Local Pre-push Checklist
+- [ ] `npm run test` passes
+- [ ] `npm run test:e2e` passes
+- [ ] No unexpected visual regressions
+
+### Post-deploy Smoke Test
+```bash
+# Against production URL
+PLAYWRIGHT_BASE_URL=https://your-app.com npm run test:e2e:smoke
+```
+
+## Common Patterns
+
+### Testing Canvas/Game Rendering
+```typescript
+test('game renders', async ({ page }) => {
+  await page.goto('/');
+  const canvas = page.locator('#gameCanvas');
+  await expect(canvas).toBeVisible();
+  
+  // Visual regression for canvas
+  await expect(page).toHaveScreenshot('game-initial.png', {
+    maxDiffPixels: 100,
+  });
+});
+```
+
+### Testing Responsive Layouts
+```typescript
+test('responsive design', async ({ page }) => {
+  await page.setViewportSize({ width: 375, height: 667 });
+  await page.goto('/');
+  await expect(page.locator('.mobile-menu')).toBeVisible();
+});
+```
+
+### Testing Voice/Audio Features
+```typescript
+test('voice button toggles', async ({ page }) => {
+  await page.goto('/');
+  const btn = page.locator('#voiceBtn');
+  await btn.click();
+  await expect(btn).toHaveClass(/active/);
+});
+```
+
+## Failure Handling
+
+### Flaky Tests
+- Add `test.fixme()` to skip temporarily
+- Increase `timeout` for slow operations
+- Use `retries` in config for network-dependent tests
+
+### Visual Regression Failures
+1. Check if change is intentional
+2. If yes: `npx playwright test --update-snapshots`
+3. If no: fix the code
+
+### Missing Test Infrastructure
+If project lacks Playwright setup:
+1. Install dependencies
+2. Create config
+3. Add basic smoke test
+4. Run to create baseline
+5. Commit as separate "test infrastructure" change
+
+## References
+
+- [Playwright Docs](https://playwright.dev/)
+- [Visual Regression Guide](https://playwright.dev/docs/test-snapshots)
+- Example implementation: `seanyao/kids-game/e2e/`