popilot 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "popilot",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Multi-agent PO/PM system scaffold for Claude Code",
   "type": "module",
   "bin": {

package/scaffold/.claude/commands/poc.md

@@ -0,0 +1,69 @@
+# /poc — Idea to Working PoC
+
+Build a working proof-of-concept from a one-line idea.
+No PO knowledge needed. No complex setup. Just describe what you want.
+
+## How it works
+
+This skill chains 4 phases automatically:
+1. **Scope** — Narrow the idea to 3 buildable features
+2. **Spec** — Write implementation-ready stories with ACs
+3. **Build** — Generate working Vue 3 code in spec-site
+4. **Verify** — Type-check, build, and launch preview
+
+## Execution
+
+### If `.context/poc/pipeline.yaml` does NOT exist:
+
+Create it:
+
+```yaml
+idea: "$ARGUMENTS"
+created_at: "[today's date]"
+status: scoping
+tech_stack: vue
+
+phases:
+  scope:
+    status: in-progress
+    output: scope.md
+  spec:
+    status: pending
+    output: stories/
+  build:
+    status: pending
+    total_stories: 0
+    current_story: 0
+    output: spec-site/src/pages/poc/
+  verify:
+    status: pending
+```
+
+Then read `.context/poc/_skills/scope.md` and execute Phase 1.
+
+### If `.context/poc/pipeline.yaml` EXISTS:
+
+Read it and resume from the current status:
+
+| `status` value | Action |
+|----------------|--------|
+| `scoping`      | Read and execute `_skills/scope.md` |
+| `speccing`     | Read and execute `_skills/spec.md` |
+| `building`     | Read and execute `_skills/build.md` (resume from `current_story`) |
+| `verifying`    | Read and execute `_skills/verify.md` |
+| `done`         | Report: "PoC already complete. Delete `.context/poc/pipeline.yaml` to start fresh." |
+
+### Resume behavior
+
+If the user runs `/poc` with no arguments and pipeline.yaml exists,
+resume from where it left off. This makes the pipeline crash-safe.
+
+If the user runs `/poc [new idea]` and pipeline.yaml exists for a
+different idea, ask: "A PoC for '[old idea]' is in progress. Replace it?"
+
+## Important
+
+- Do NOT stop between phases. Run all 4 phases in one session.
+- Do NOT ask the user for confirmation between phases. Be proactive.
+- If a phase fails, attempt to fix it. Only stop if unrecoverable.
+- All generated code must compile (`vue-tsc --noEmit` pass).

package/scaffold/.context/poc/_skills/build.md

@@ -0,0 +1,79 @@
+# Phase 3: Build
+
+You are implementing PoC stories as working Vue 3 code inside the spec-site scaffold.
+
+## Input
+
+- Read `.context/poc/pipeline.yaml` to find `current_story`
+- Read the corresponding `.context/poc/stories/S-{NN}.md`
+- Read `.context/poc/scope.md` for context (mock data strategy)
+
+## Target
+
+All generated code goes into `spec-site/src/pages/poc/`.
+Shared composables go into `spec-site/src/composables/poc/`.
+
+## Rules
+
+### Code Style
+1. **Vue 3 `<script setup lang="ts">`** — no Options API.
+2. **Composition API** with `ref`, `computed`, `watch`.
+3. **Scoped CSS** in every component. Use CSS variables from `spec-site/src/styles/variables.css`.
+4. **No external dependencies**. Only use what's already in spec-site's package.json (vue, vue-router, marked).
+5. **TypeScript strict**. No `any`. Define interfaces from the story's Data Model.
+
+### Data
+6. **Mock data only**. Use `ref()` with hardcoded initial data or localStorage.
+7. If the story says localStorage, use a consistent key prefix: `poc-{feature}-`.
+
+### Structure
+8. **One page component** per story that composes smaller components.
+9. **One composable** per story for state management.
+10. **Register route** in `spec-site/src/router.ts` under `/poc/` prefix.
+
+### Quality
+11. Every AC must be verifiable by viewing the page and interacting with it.
+12. Transitions/animations: use simple CSS transitions only. No animation libraries.
+13. Responsive: must look acceptable at 375px and 1280px widths.
+
+## Implementation Steps (per story)
+
+```
+1. Create composable: src/composables/poc/use{Feature}Store.ts
+   - Define interfaces from Data Model
+   - Implement reactive state + actions
+   - Add localStorage persistence if specified
+
+2. Create components: src/pages/poc/{Component}.vue
+   - Follow UI Components table from story
+   - Import and use the composable
+   - Implement all AC interactions
+
+3. Create page: src/pages/poc/{Feature}Page.vue
+   - Compose all components
+   - Handle layout
+
+4. Register route in src/router.ts
+   - Lazy import: () => import('@/pages/poc/{Feature}Page.vue')
+   - Path: /poc/{path} as specified in story
+
+5. Update pipeline.yaml
+   - Increment current_story
+   - If all stories done: set phases.build.status = done
+```
+
+## After ALL stories are built
+
+Update `.context/poc/pipeline.yaml`:
+- Set `phases.build.status: done`
+- Set `status: verifying`
+
+Then immediately proceed to Phase 4 (read `.context/poc/_skills/verify.md`).
+
+## On build error
+
+If `vue-tsc` or `vite build` fails:
+1. Read the error
+2. Fix it
+3. Retry (max 3 attempts per story)
+4. If still failing, add `error: "[message]"` to pipeline.yaml under that story and move on

package/scaffold/.context/poc/_skills/scope.md

@@ -0,0 +1,50 @@
+# Phase 1: Scope
+
+You are scoping a PoC (Proof of Concept) from a one-line idea.
+Your job is to produce a tight, buildable scope — NOT a full PRD.
+
+## Input
+
+Read the `idea` field from `.context/poc/pipeline.yaml`.
+
+## Rules
+
+1. **Max 3 features**. A PoC proves a concept, not ships a product.
+2. **No real backends**. All data is mock/local. No API keys, no databases.
+3. **Name concrete UI elements**. "Dashboard" is vague. "3-column kanban board with drag-and-drop cards" is buildable.
+4. **Explicitly list Out of Scope** to prevent creep.
+
+## Output
+
+Write `.context/poc/scope.md` in this exact format:
+
+```markdown
+# PoC Scope
+
+## Problem
+[1-2 sentences: what pain point does this solve?]
+
+## Target User
+[1 sentence: who is this for?]
+
+## Core Features
+1. **[Feature Name]** — [One sentence description with specific UI element]
+2. **[Feature Name]** — [One sentence description with specific UI element]
+3. **[Feature Name]** — [One sentence description with specific UI element]
+
+## Mock Data Strategy
+[What fake data will be used? localStorage? Hardcoded JSON? In-memory state?]
+
+## Out of Scope
+- [Thing that might seem needed but isn't for PoC]
+- [Another thing]
+- [Another thing]
+```
+
+## After completion
+
+Update `.context/poc/pipeline.yaml`:
+- Set `phases.scope.status: done`
+- Set `status: speccing`
+
+Then immediately proceed to Phase 2 (read `.context/poc/_skills/spec.md`).

package/scaffold/.context/poc/_skills/spec.md

@@ -0,0 +1,80 @@
+# Phase 2: Spec
+
+You are writing implementation-ready story specs from a PoC scope.
+Each story maps 1:1 to a Core Feature in scope.md.
+
+## Input
+
+Read `.context/poc/scope.md` (Phase 1 output).
+
+## Rules
+
+1. **One story per feature**. No splitting. PoC stories are small by design.
+2. **AC must be testable by eyeball**. "Given X, When Y, Then Z is visible on screen."
+3. **UI Components section is mandatory**. List every .vue file that will be created.
+4. **Data Model section is mandatory**. Define TypeScript interfaces for all state.
+5. **Route section is mandatory**. Exact path for vue-router.
+6. Each story must be self-contained — implementable without other stories being done first.
+
+## Output
+
+For each Core Feature, write `.context/poc/stories/S-{NN}.md`:
+
+```markdown
+# S-{NN}: [Feature Name]
+
+## AC (Acceptance Criteria)
+
+1. Given [precondition]
+   When [user action]
+   Then [visible result]
+
+2. Given [precondition]
+   When [user action]
+   Then [visible result]
+
+3. Given [precondition]
+   When [user action]
+   Then [visible result]
+
+## UI Components
+
+| Component | File | Description |
+|-----------|------|-------------|
+| [Name] | `src/pages/poc/[Name].vue` | [What it renders] |
+| [Name] | `src/pages/poc/[Name].vue` | [What it renders] |
+
+## Data Model
+
+```typescript
+interface [ModelName] {
+  id: string
+  // ...fields
+}
+```
+
+## State Management
+
+```typescript
+// Describe the composable: useXxxStore
+// - What reactive state it holds
+// - What actions it exposes
+// - Where data persists (localStorage key, in-memory, etc.)
+```
+
+## Route
+
+| Path | Component | Description |
+|------|-----------|-------------|
+| `/poc/[path]` | `[Component].vue` | [What this page shows] |
+```
+
+## After completion
+
+Update `.context/poc/pipeline.yaml`:
+- Set `phases.spec.status: done`
+- Set `status: building`
+- Set `phases.build.total_stories: [count]`
+- Set `phases.build.current_story: 1`
+
+Then immediately proceed to Phase 3 (read `.context/poc/_skills/build.md`).

package/scaffold/.context/poc/_skills/verify.md

@@ -0,0 +1,60 @@
+# Phase 4: Verify
+
+You are verifying the PoC builds and runs correctly.
+
+## Steps
+
+### 1. Type Check
+
+```bash
+cd spec-site && npx vue-tsc --noEmit
+```
+
+If errors exist, fix them. Max 3 retry cycles.
+
+### 2. Build
+
+```bash
+cd spec-site && npx vite build
+```
+
+If build fails, fix and retry. Max 3 cycles.
+
+### 3. Add PoC Entry Point
+
+If not already present, add a link to the PoC pages from the spec-site index.
+Add a simple navigation component at `src/pages/poc/PocIndex.vue` that lists
+all PoC routes with links.
+
+Register `/poc` route in router.ts pointing to PocIndex.vue.
+
+### 4. Launch Preview
+
+```bash
+cd spec-site && npx vite preview &
+```
+
+### 5. Report
+
+Output to the user:
+
+```
+PoC complete!
+
+Routes:
+- /poc           — PoC Index
+- /poc/[route1]  — [Feature 1 name]
+- /poc/[route2]  — [Feature 2 name]
+- /poc/[route3]  — [Feature 3 name]
+
+Preview: http://localhost:4173/poc
+
+Stories built: N/N
+Build status: success | partial (list failures)
+```
+
+## After completion
+
+Update `.context/poc/pipeline.yaml`:
+- Set `phases.verify.status: done`
+- Set `status: done`