popilot 0.2.0

package/scaffold/.context/WORKFLOW.md.hbs

@@ -0,0 +1,332 @@
+# PO Workflow
+
+> Oscar-centric operations, agent routing, proactive alerts, etc. — see `agents/orchestrator.md`
+> Session management — see `{{COMMAND_DIR}}start.md`, `save.md`
+
+---
+
+## Codebase Context Analysis
+
+{{#if dev_scope.service_repo}}
+### Repository Separation (Important)
+
+The Oscar system and service codebase are in **separate Git repositories**:
+
+| Repository | Path | Contents |
+|------------|------|----------|
+| **Oscar System** | Current directory | Agents, context, workflows, sessions |
+| **Service Code** | `~/{{dev_scope.service_repo}}/` | Frontend, backend |
+
+**Important:**
+- Codebase analysis results are stored in `.context/global/product/`
+- When analyzing service code, navigate to `~/{{dev_scope.service_repo}}/`
+- The two repositories have completely independent commit histories
+{{/if}}
+
+### When Is Analysis Needed?
+
+| Situation | Required Analysis |
+|-----------|-------------------|
+| Starting a new domain spec discussion | Full FE/BE analysis for that domain |
+| Discussing modifications to existing features | Related component/service analysis |
+| Identifying bug causes | Detailed logic analysis |
+| Checking API specs | Controller/DTO analysis |
+
+### Storing Analysis Results
+
+```
+.context/global/product/{domain}.md
+```
+
+{{#if domains}}
+### Per-Domain Context Files
+
+| Domain | Context File |
+|--------|-------------|
+{{#each domains}}
+| **{{name}}** | `global/product/{{id}}.md` |
+{{/each}}
+{{/if}}
+
+---
+
+## Agent Handoff Flow
+
+```
+                       🎩 Oscar
+                  (Routing & Coordination)
+                         │
+       ┌─────────────────┼─────────────────┐
+       │                 │                 │
+       ▼                 ▼                 ▼
+   🎯 Simon ◄──────► 📈 Danny ◄──────► 🎤 Rita
+       │                 │
+       ▼                 │
+   📋 Penny              │
+       │                 │
+       ▼                 │
+   📊 Vicky ◄────────────┘
+       │
+       ▼
+   🎯 Simon (next hypothesis)
+```
+
+| From | To | Situation | Oscar's Role |
+|------|-----|-----------|-------------|
+| 🎯 Simon | 📋 Penny | PRD completed | Handoff check |
+| 📋 Penny | 📊 Vicky | Development completed | Confirm validation readiness |
+| 📊 Vicky | 🎯 Simon | Validation completed | Prompt learning summary |
+| 📊 Vicky | 📈 Danny | Anomaly detected | Request deep analysis |
+| 📈 Danny | 🎯 Simon | Insight discovered | Suggest strategic connection |
+| 🎤 Rita | 🎯 Simon | VOC analysis done | Suggest hypothesis connection |
+
+---
+
+## Sprint Transition Workflow
+
+At sprint end:
+```
+1. Write results.md in the current sprint folder
+2. Create new sprint folder (e.g., sprints/s{N+1}/)
+3. Initialize context.md (goals, KRs, key tasks)
+4. Move previous sprint to _archive/ if needed
+```
+
+---
+
+## Planning → Development Workflow
+
+> Complete document hierarchy from PO detailed planning to developer handoff
+
+### Document Hierarchy
+
+```
+Level 1: Sprint PRD (Sprint level)
+   └─→ One Question, hypothesis, OMTM
+   └─→ Owner: 🎯 Simon / Template: templates/prd.md
+
+Level 2: Epic Spec (Epic level) ⭐ Core
+   └─→ WHY, WHAT, HOW (overview), EDGE
+   └─→ Owner: PO (🎯 Simon support) / Template: templates/epic-spec.md
+
+Level 3: Story (Story level)
+   └─→ Based on Epic Spec, AC (Given-When-Then), task breakdown
+   └─→ Owner: 📋 Penny / Template: templates/story-v2.md
+```
+
+### Order Is Mandatory
+
+```
+No Story writing before Epic Spec is finalized!
+
+[Correct order]
+Sprint PRD → Epic Spec (PO finalized) → Story breakdown → Development
+
+[Prohibited]
+Sprint PRD → (without Epic Spec) Story writing ❌
+```
+
+### 5-Stage Story Status
+
+```
+draft → backlog → ready-for-dev → in-progress → review → done
+```
+
+| Status | Meaning | Entry Condition |
+|--------|---------|-----------------|
+| `draft` | Draft (Epic Spec not finalized) | — |
+| `backlog` | Epic Spec finalized | Epic Spec completed |
+| `ready-for-dev` | Handoff completed | Story verification passed |
+| `in-progress` | In development | — |
+| `done` | Completed | 📊 Vicky validation |
+
+### Workflow Stages
+
+**Phase 1: Planning (PO-led)**
+1. Write Sprint PRD (🎯 Simon)
+2. Write Epic Spec (PO) → ✅ Proceed after PO approval
+
+**Phase 2: Handoff (📋 Penny)**
+3. Story breakdown (templates/story-v2.md)
+4. Screen spec — for UI Epics (templates/screen-spec.md)
+5. Quality verification (templates/handoff-checklist.md) → Status: ready-for-dev
+
+**Phase 3: Development (AI Agent)**
+6. Implement story tasks in order
+7. Review & complete → done
+
+### Disaster Prevention Analysis (5 checks)
+
+Must check before handoff:
+1. **Feature duplication** — Similar functionality in existing code?
+2. **Technical errors** — Library versions, API contracts
+3. **File structure** — Conventions, build process
+4. **Regression errors** — Existing tests, side effects
+5. **Implementation ambiguity** — Edge cases, error handling
+
+---
+
+## spec-site: Interactive Spec Tool
+
+spec-site is a Vue 3 + Vite based interactive spec viewer.
+It provides dynamic mockups and scenario-based specs instead of static markdown.
+
+### Page Addition Pattern
+
+1. Create `src/pages/{feature}/` folder
+2. Write 3 files:
+   - `{feature}Data.ts` — Scenarios, spec areas, version info
+   - `{Feature}Mockup.vue` — Interactive mockup
+   - `{Feature}SpecPanel.vue` — Spec document panel
+3. Register in `wireframeRegistry.ts`
+4. Add to `navigation.ts`
+
+### Layout Standard: SplitPaneLayout
+
+Left: Interactive mockup / Right: Spec panel (draggable)
+
+```
+┌────────────────────────────────────────────────┐
+│                   AppHeader                     │
+├─────────────────────┬──────────────────────────┤
+│                     │                          │
+│    MockupShell      │     SpecPanel            │
+│    (per-scenario    │     (spec document)      │
+│     mockup)         │                          │
+│                     │                          │
+│                     │                          │
+├─────────────────────┴──────────────────────────┤
+│              ScenarioSwitcher                   │
+└────────────────────────────────────────────────┘
+```
+
+### Scenario System
+
+ScenarioSwitcher enables mockup switching by user type / state.
+Each scenario is defined in `{feature}Data.ts` and provided/injected via `useScenario` composable.
+
+### Data File Structure
+
+```typescript
+// {feature}Data.ts
+import type { Scenario, SpecArea, PageVersion } from '../data/types'
+
+export const scenarios: Scenario<FeatureState>[] = [
+  { id: 'default', label: 'Default', state: { /* ... */ } },
+  { id: 'empty', label: 'Empty state', state: { /* ... */ } },
+]
+
+export const specAreas: SpecArea[] = [
+  { id: 'layout', label: 'Layout' },
+  { id: 'components', label: 'Component Details' },
+]
+
+export const version: PageVersion = {
+  sprint: 's1',
+  status: 'dev',
+  updatedAt: '2026-01-01'
+}
+```
+
+### Epic Spec Integration
+
+Epic Specs are written in markdown at `.context/sprints/s{N}/epic-specs/E-XX.md`.
+They are automatically rendered on spec-site's PolicyIndex / PolicyDetail pages.
+
+### Retrospective Tool (RetroPage)
+
+Turso (LibSQL) based team retrospective board. Route: `/retro`.
+- Category-based cards (went well / needs improvement / action items)
+- Sprint-based filtering
+
+---
+
+## Checklists
+
+### PRD Completeness
+- [ ] One Question defined
+- [ ] OMTM set
+- [ ] Hypothesis/validation method clear
+- [ ] Guard Rail metrics present
+
+### Sprint Ready
+- [ ] KRs quantified
+- [ ] Dev spec document linked
+- [ ] Baseline data secured
+
+### Hypothesis Validation
+- [ ] Before data collection complete
+- [ ] Measurement period set
+- [ ] Success/failure criteria clear
+
+---
+
+## Templates
+
+### Planning (PO-led)
+
+| Template | Owner | File | Order |
+|----------|-------|------|-------|
+| Sprint PRD | 🎯 Simon | `templates/prd.md` | 1 |
+| Epic Spec | PO | `templates/epic-spec.md` | 2 |
+
+### Handoff (📋 Penny-led)
+
+| Template | File | Order |
+|----------|------|-------|
+| Story v2 | `templates/story-v2.md` | 3 |
+| Screen Spec | `templates/screen-spec.md` | 4 |
+| Handoff Checklist | `templates/handoff-checklist.md` | 5 |
+| Sprint Status | `templates/sprint-status.yaml` | — |
+| Dev Guide | `templates/dev-guide.md` | — |
+
+### Validation/Retrospective
+
+| Template | Owner | File |
+|----------|-------|------|
+| Validation Report | 📊 Vicky | `templates/validation-report.md` |
+| Guard Rail | 📊 Vicky | `templates/guardrail.md` |
+| Retrospective | Penny + Vicky | `templates/retrospective.md` |
+
+---
+
+---
+
+## Document Management Tool Roles
+
+### spec-site — Interactive Specs + Epic Spec Viewing
+
+| Document | Path |
+|----------|------|
+| Sprint documents | `.context/sprints/s{N}/` |
+| Epic Specs | `.context/sprints/s{N}/epic-specs/` |
+| Interactive mockups | `spec-site/src/pages/` |
+| Retro board | spec-site `/retro` |
+{{#if spec_site.deploy_url}}
+
+**Deploy URL**: {{spec_site.deploy_url}}
+{{/if}}
+
+{{#if capabilities.pm_tool}}
+### PM Tool — Project Management
+
+| Purpose | Description |
+|---------|-------------|
+| Kanban board | Task status tracking, assignee management |
+| Sprint management | Progress, workload monitoring |
+| Meeting notes / Roadmap | Meeting records, OKR |
+{{/if}}
+
+### Metrics Data
+
+**Location:** `.context/metrics/`
+
+| File | Contents | Frequency |
+|------|----------|-----------|
+| `business.yaml` | MRR, ARPU, funnel | Monthly |
+| `segments.yaml` | Per-segment metrics | Monthly |
+| `team.yaml` | Team/member info | At sprint start |
+
+---
+
+{{INTEGRATION_WORKFLOW_RULES}}

package/scaffold/.context/agents/TEMPLATE.md

@@ -0,0 +1,115 @@
+# Agent Prompt Universal Template v1.0
+
+> Every agent persona file in the Oscar system must follow this template.
+> Incorporates 10 quality patterns from the OMX (oh-my-codex) reference.
+
+---
+
+## Mandatory Structure (in order)
+
+```markdown
+---
+name: "{Name}"
+role: "{One-line role}"
+icon: "{emoji}"
+effort: "low | medium | high"          # Default reasoning intensity
+model_tier: "opus | sonnet | haiku"    # Recommended model
+read_only: true | false                # Whether this agent can modify files
+---
+```
+
+### 1. Identity
+- Name, role, icon, tagline
+
+### 2. Persona
+- Background (2-3 sentences)
+- Communication style
+- Speech examples (2-3)
+
+### 3. Negative Scope (MANDATORY)
+- "What I Do NOT Do" table: `| Task | Responsible Agent | Reason |`
+- "Boundary Violations to Reject" — 3+ example requests with redirect responses
+- Clear redirect phrasing when boundary is crossed
+
+### 4. Core Principles
+- 3-5 principles (one line each)
+
+### 5. Success Criteria (MANDATORY)
+- 5-7 measurable bullet points defining "done well"
+- At least 1 must be quantitative
+
+### 6. Activation Triggers
+- Keyword / situation matching table
+
+### 7. Workflow Menu
+- Trigger code | Function | Deliverable
+
+### 8. MCP Tool Usage (if applicable)
+- Per-tool: purpose, usage, constraints
+- Use `{{INTEGRATION_PROMPTS}}` marker for hydration-injected content
+
+### 9. Handoff Protocol
+- Outbound handoff: format + required fields
+- Inbound handoff: verification checklist
+
+### 10. Failure Modes to Avoid (MANDATORY)
+- Minimum 4 named anti-patterns
+- Each: Name, BAD example, GOOD example, FIX one-liner
+
+### 11. Few-shot Examples (MANDATORY)
+- Minimum 2 Good/Bad pairs
+- Good: specific, evidence-based, structured response
+- Bad: vague, ungrounded, unstructured response
+
+### 12. Final Checklist (MANDATORY)
+- 5-7 Yes/No verification questions before delivering output
+- If any answer is No, revise before submitting
+
+### 13. Evidence Principle (MANDATORY)
+- "No evidence = no claim" declaration
+- Definition of evidence (file:line, data, URL, etc.)
+- BAD → GOOD transformation example
+
+### 14. Context Budget (MANDATORY)
+- Files to skip
+- Reading strategy by file size (200+ lines → partial read)
+- Max files per turn
+
+### 15. Auto Context Load
+- Files to load automatically on activation
+
+---
+
+## Quality Gate
+
+| Section | Minimum Requirement | Gate |
+|---------|-------------------|------|
+| Negative Scope | 3+ "don't do" items with responsible agent named | Must redirect to a specific agent |
+| Success Criteria | 5+ criteria | At least 1 quantitative |
+| Failure Modes | 4+ anti-patterns | Each must have BAD/GOOD/FIX |
+| Few-shot Examples | 2+ Good/Bad pairs | Bad must be a realistic failure, not a strawman |
+| Final Checklist | 5-7 Yes/No items | Answerable without additional context |
+| Evidence Principle | Declaration + 1 example | Must include BAD→GOOD transformation |
+| Context Budget | 3+ rules | Must include "what to skip" guidance |
+
+---
+
+## Optional Sections (when applicable)
+
+- **Read-Only Constraint**: For agents that must not modify files
+- **Circuit Breaker**: Stop/escalation rules after 3 consecutive same-approach failures
+- **Extension Modules**: References to conditionally loaded modules
+- **Domain Knowledge**: Domain-specific knowledge references
+
+---
+
+## Naming Conventions
+
+- Agent names: English first names (Oscar, Simon, Penny, ...)
+- File names: `{role-english}.md.hbs` (orchestrator.md.hbs, strategist.md.hbs, ...)
+- Icons: 1 emoji per agent, fixed
+
+---
+
+*Version*: v1.0
+*Applies to*: All 14 agents in the Oscar system