@seanyao/roll 0.5.0

package/skills/roll-spar/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: roll-spar
+description: Adversarial TDD mode with Attacker/Defender agents. Attacker writes tests to break the system, Defender writes minimal code to pass. Use for high-risk logic like auth, payments, data integrity, or complex state machines.
+---
+
+# Spar
+
+Adversarial TDD: two agents collaborate in attack-and-defend mode to build a more robust system.
+
+## When to Use
+
+**Manual trigger:**
+- User explicitly requests `$roll-spar`
+- Involves core business logic requiring higher quality assurance
+
+**Auto trigger (agent judgment):** Recommend enabling when any of these conditions are met
+- Involves authentication / authorization / security
+- Involves money / payments / billing
+- Involves data integrity (writes are irreversible)
+- Complex state machines / concurrency logic
+- Module has had previous bugs (BACKLOG has related FIX records)
+
+**Do not use for:**
+- UI styling adjustments, copy changes
+- Simple CRUD
+- Configuration changes
+- Small tasks not worth the overhead of two-agent collaboration
+
+## Roles
+
+### Attacker (Red Agent)
+
+**Goal: Find weaknesses in the code and write tests that break the system.**
+
+- Think about boundary conditions, invalid inputs, concurrency scenarios, state inconsistencies
+- Write the trickiest test cases possible
+- Don't care about implementation difficulty — only care about "can the system handle this scenario"
+- Write at least 1 RED test per round, can write multiple
+
+### Defender (Green Agent)
+
+**Goal: Make all tests pass with the simplest, most robust code possible.**
+
+- Cannot modify tests written by the Attacker (unless the test itself has a bug)
+- Aim for minimal implementation, avoid over-engineering
+- Make all tests GREEN each round, then commit
+- May refactor, but must stay GREEN
+
+## Workflow
+
+```
+User: "$roll-spar implement transfer logic" or agent auto-triggers
+    │
+    ▼
+┌─────────────────────────────────────┐
+│ 0. Setup                            │
+│    - Define feature scope and AC    │
+│    - Create test file skeleton      │
+│    - Context brief for Attacker     │
+│      and Defender                    │
+└─────────────┬───────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────┐
+│ Spar Loop (repeat until converged)  │
+│                                     │
+│  ┌───────────────────────────────┐  │
+│  │ 🔴 Attacker Turn             │  │
+│  │    - Analyze current code/API │  │
+│  │    - Write 1+ RED tests      │  │
+│  │    - State attack intent:     │  │
+│  │      "Test balance consistency│  │
+│  │       during concurrent       │  │
+│  │       transfers"              │  │
+│  └──────────────┬────────────────┘  │
+│                 │                    │
+│                 ▼                    │
+│  ┌───────────────────────────────┐  │
+│  │ 🟢 Defender Turn             │  │
+│  │    - Read Attacker's tests   │  │
+│  │    - Write minimal code to   │  │
+│  │      make tests pass         │  │
+│  │    - Run all tests → GREEN   │  │
+│  │    - git commit              │  │
+│  └──────────────┬────────────────┘  │
+│                 │                    │
+│                 ▼                    │
+│  ┌───────────────────────────────┐  │
+│  │ 🔴 Attacker Turn (again)     │  │
+│  │    - Review Defender's impl  │  │
+│  │    - Find new weaknesses,    │  │
+│  │      write new RED tests     │  │
+│  │    - Or: "No new weaknesses  │  │
+│  │      found"                  │  │
+│  └──────────────┬────────────────┘  │
+│                 │                    │
+│        ┌────────┴────────┐          │
+│        │                 │          │
+│   Has new tests    No new tests     │
+│   → Continue loop  → Exit Spar      │
+│                                     │
+└─────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────┐
+│ Wrap-up                             │
+│    - Attacker summarizes attack     │
+│      coverage                       │
+│    - Defender summarizes defense    │
+│      strategy                       │
+│    - Merged report                  │
+│    - Continue normal story-build    │
+│      flow                           │
+│      (push → CI → deploy → verify)  │
+└─────────────────────────────────────┘
+```
+
+## Spar Convergence Conditions
+
+Attacker declares completion when any of these are met:
+- Cannot write a new RED test for 2 consecutive rounds
+- Already covered: happy path + boundary values + invalid inputs + concurrency/race conditions + state consistency
+- Reached the agreed maximum number of rounds (default: 5 rounds)
+
+## Agent Context Brief
+
+### Attacker Brief Template
+
+```markdown
+## Role: Attacker (Red Agent)
+
+Your goal is to find weaknesses in this code.
+
+### Feature Description
+{Feature AC and interface definition}
+
+### Current Implementation
+{Defender's latest code, or "not yet implemented"}
+
+### Existing Tests
+{Currently existing test cases}
+
+### Your Task
+Write 1+ new test cases that make the current implementation fail (RED).
+Directions to explore:
+- Boundary values (0, -1, MAX_INT, empty string, null)
+- Exception flows (network disconnect, timeout, duplicate requests)
+- Concurrency (two requests arriving simultaneously)
+- State consistency (is system state clean after mid-process failure)
+
+### Output Format
+For each test, state the attack intent:
+  "Attack: {scenario description} — expected system behavior: {expected behavior}"
+```
+
+### Defender Brief Template
+
+```markdown
+## Role: Defender (Green Agent)
+
+Your goal is to make all tests pass with the simplest implementation.
+
+### Feature Description
+{Feature AC and interface definition}
+
+### Current Code
+{Your previously written code, or empty}
+
+### New RED Tests
+{Tests written by the Attacker this round}
+
+### Your Task
+Modify/add code to make all tests (including previous ones) pass.
+Rules:
+- Cannot modify tests written by the Attacker
+- Aim for minimal changes
+- Keep the code clear
+- Commit after all tests are GREEN
+```
+
+## Status Report
+
+Report to the user after each round:
+
+```
+⚔️ Spar Round {N}
+
+  🔴 Attacker:
+     Attack: {scenario 1} — {result}
+     Attack: {scenario 2} — {result}
+
+  🟢 Defender:
+     Defense strategy: {brief description of how it was defended}
+     Test status: {passed}/{total} ✅
+
+  📊 Cumulative: {total tests} tests, {total rounds} rounds
+  🔄 Next round: Attacker continues looking for weaknesses...
+```
+
+## Hard Rules
+
+1. **Attacker does not write implementation code** — only writes tests and attack analysis
+2. **Defender does not modify tests** — unless the test itself has a bug (must explain the reason)
+3. **Must commit each round** — Defender commits immediately after making tests GREEN, keeping the repo clean
+4. **Attack intent must be explained** — cannot just write tests without explaining "why this scenario matters"
+5. **Maximum round limit** — default 5 rounds, prevents infinite loops
+
+## Integration with story-build
+
+Spar replaces steps 4-5 in story-build (Test Design + TCR Implementation):
+
+```
+story-build normal flow:
+  1. Clarify Story
+  2. Split Actions
+  3. Define verification
+  ──────────────────────
+  4. Test Design Review    ← Spar replaces this step
+  5. TCR Implementation    ← and this step
+  ──────────────────────
+  6. Local CI check        ← Back to normal flow
+  7. Quality Review
+  ...
+```
+
+**Auto-switching from story-build to Spar:**
+
+When the agent assesses an Action as high-risk at step 3:
+```
+⚔️ High-risk Action detected: {description}
+   Risk factors: {auth/payment/data integrity/...}
+   Recommend enabling Spar mode — confirm? [Y/n]
+```
+
+After user confirms, enter Spar. Once complete, return to story-build step 6 to continue.
+
+## Example
+
+```
+User: "$roll-spar implement user balance transfer"
+
+⚔️ Spar: User Balance Transfer
+
+── Round 1 ──
+
+🔴 Attacker:
+   Attack 1: Transfer amount is 0 — should reject
+   Attack 2: Transfer amount is negative — should reject
+   Attack 3: Transfer amount exceeds balance — should reject and keep balance unchanged
+
+🟢 Defender:
+   Implementation: transfer(from, to, amount) basic validation
+   Tests: 3/3 ✅
+   commit: "tcr: transfer basic validation"
+
+── Round 2 ──
+
+🔴 Attacker:
+   Attack 4: Transfer to self — should reject
+   Attack 5: Two concurrent transfers whose total exceeds balance — only one should succeed
+
+🟢 Defender:
+   Implementation: add self-transfer check + optimistic lock
+   Tests: 5/5 ✅
+   commit: "tcr: transfer self-check and concurrency lock"
+
+── Round 3 ──
+
+🔴 Attacker:
+   Attack 6: Database error mid-transfer — both balances should remain unchanged (atomicity)
+   Attack 7: Recipient account does not exist — should reject and keep sender's balance
+
+🟢 Defender:
+   Implementation: database transaction wrapper + recipient existence check
+   Tests: 7/7 ✅
+   commit: "tcr: transfer atomicity and recipient validation"
+
+── Round 4 ──
+
+🔴 Attacker:
+   No new weaknesses found. Covered: input validation, self-transfer, concurrency, atomicity, related accounts.
+
+⚔️ Spar Complete!
+   📊 4 rounds, 7 tests, 3 commits
+   🔴 Attack coverage: input boundaries + business rules + concurrency + atomicity
+   🟢 Defense strategy: upfront validation + optimistic lock + transactions
+```

package/template/.env.example

@@ -0,0 +1,47 @@
+# ============================================
+# AI Services
+# ============================================
+# Moonshot AI (Kimi) - content generation
+KIMI_API_KEY=sk-your-kimi-api-key
+KIMI_BASE_URL=https://api.moonshot.cn/v1
+
+# OpenAI (fallback)
+OPENAI_API_KEY=sk-your-openai-key
+
+# Alibaba DashScope - image/voice generation
+DASHSCOPE_API_KEY=sk-your-dashscope-key
+
+# ============================================
+# Cloud Storage (OSS)
+# ============================================
+# Aliyun OSS
+OSS_ACCESS_KEY_ID=your-access-key
+OSS_ACCESS_KEY_SECRET=your-secret
+OSS_BUCKET=your-bucket
+OSS_REGION=oss-cn-hangzhou
+OSS_ENDPOINT=https://your-bucket.oss-cn-hangzhou.aliyuncs.com
+
+# ============================================
+# Deployment
+# ============================================
+# Vercel (auto-injected, not needed for local dev)
+# VERCEL_URL=https://your-app.vercel.app
+
+# ============================================
+# Database (if needed)
+# ============================================
+# Supabase / PostgreSQL
+DATABASE_URL=postgresql://user:pass@host:5432/db
+
+# Redis (cache)
+REDIS_URL=redis://localhost:6379
+
+# ============================================
+# Auth (if needed)
+# ============================================
+# Google OAuth
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-secret
+
+# JWT Secret
+JWT_SECRET=your-jwt-secret-key

package/template/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Lint
+        run: npm run lint
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Test
+        run: npm run test -- --run

package/template/.github/workflows/sentinel.yml

@@ -0,0 +1,26 @@
+name: Sentinel Patrol
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'  # patrol every 6 hours
+  workflow_dispatch:       # support manual trigger
+
+jobs:
+  patrol:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Sentinel Patrol
+        run: |
+          echo "🔍 Running sentinel patrol..."
+          # Integrate actual sentinel check scripts here
+          npm run test:e2e:smoke || true
+        env:
+          APP_URL: ${{ secrets.APP_URL }}

package/template/AGENTS.md

@@ -0,0 +1,80 @@
+# Project Agents Configuration
+
+## Workspace Configuration
+
+### Plan Documents Location
+**All Plan documents must be stored under the project directory. Writing to the `.kimi/` directory is prohibited.**
+
+```yaml
+# Plan file storage configuration
+plans:
+  base_dir: docs/plans/          # Relative to the project root
+  auto_create: true              # Auto-create directory if it doesn't exist
+  naming_convention: "{topic}.md" # Naming convention
+```
+
+**Rules:**
+1. **Preferred location**: `{project_root}/docs/plans/`
+2. **Auto-create**: If `docs/plans/` doesn't exist, create the directory automatically
+3. **Prohibited location**: Absolutely no writing to `~/.kimi/` or any global config directory
+4. **Non-project Plans**: Only allowed to use a temporary location when there is no project context
+
+**Examples:**
+- ✅ `my-project/docs/plans/auth-system.md`
+- ✅ `my-project/docs/plans/api-redesign.md`
+- ❌ `~/.kimi/skills/some-plan.md`
+- ❌ Any global location outside the project
+
+## Workflow
+
+### Design → $roll-design
+- Solution exploration, architecture design
+- Split into Stories
+- Write to BACKLOG.md
+
+### Build → $roll-build / $roll-fix
+- Read BACKLOG and execute
+- TCR development (independent Actions auto-parallelized + Worktree isolation)
+- CI/CD deployment
+
+### Check → $roll-sentinel / $roll-debug
+- Sentinel: Scheduled patrol
+- $roll-debug: Deep diagnosis
+
+### Fix → $roll-fix / $roll-design
+- Fix issues
+- Or re-plan
+
+## Architecture Constraints
+
+### Agent First
+- System designed for AI Agents
+- Agent is the primary user
+- UI is only a supplementary interface
+
+### Data Schema
+- Clear data structure definitions
+- Type/Schema is the contract between humans and Agents
+- Define Schema first, then write business logic
+
+### Domain Driven
+- Model by business domain
+- Not database table design
+- Help Agents understand the business
+
+### Decoupling Rules
+- UI layer only handles rendering; logic lives in Hooks
+- API calls encapsulated in services/
+- Shared types placed in shared/types/
+
+### Testing Requirements
+- All business logic must have unit tests
+- APIs have integration tests
+- Critical flows have E2E tests
+- Sentinel runs periodic regression tests
+
+## Conventions
+
+- All work tracked in BACKLOG.md
+- Sentinel patrols every 6 hours
+- TCR required for all changes

package/template/BACKLOG.md

@@ -0,0 +1,42 @@
+# Project Backlog
+
+> Task index - all work is tracked here
+
+## 🎯 Active
+
+Stories in the current iteration
+
+| ID | Title | Status | Priority | Est |
+|----|-------|--------|----------|-----|
+| INIT-001 | Project initialization | ✅ | P0 | 1d |
+
+## 📋 Todo
+
+Ready for development, already planned
+
+<!-- $roll-design will create new Stories here -->
+
+## 🔄 In Progress
+
+<!-- $roll-build will update here -->
+
+## ✅ Completed
+
+- **INIT-001** Project initialization - {date}
+
+## 🐛 Bug Fixes
+
+| ID | Problem | Status | Source |
+|----|---------|--------|--------|
+
+## 🔍 Sentinel Findings
+
+| ID | Issue | Severity | Status |
+|----|-------|----------|--------|
+
+## 📈 Stats
+
+- Total Stories: 1
+- Completed: 1
+- Active: 0
+- Sentinel Coverage: 0%

package/template/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "test": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:smoke": "playwright test smoke.spec.ts",
+    "ci:local": "npm run lint && npm run build && npm run test -- --run"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.20.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "tailwind-merge": "^2.0.0",
+    "lucide-react": "^0.294.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.37",
+    "@types/react-dom": "^18.2.15",
+    "@typescript-eslint/eslint-plugin": "^6.10.0",
+    "@typescript-eslint/parser": "^6.10.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "@playwright/test": "^1.40.0",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.53.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.4",
+    "postcss": "^8.4.31",
+    "prettier": "^3.1.0",
+    "tailwindcss": "^3.3.5",
+    "typescript": "^5.2.2",
+    "vite": "^5.0.0",
+    "vitest": "^0.34.6"
+  }
+}