popilot 0.2.0

package/scaffold/.context/oscar/workflows/tracking.md

@@ -0,0 +1,118 @@
+# Work Tracking & Session Management (Oscar Module)
+
+> Referenced at session start/save, when work tracking is needed
+
+---
+
+## 1. Incomplete Work Tracking (Sisyphus Mode)
+
+> *"Half-done is undone"* — Track started work to completion
+
+### Tracking Targets
+
+| Work Type | Completion Criteria | Incomplete Notification |
+|-----------|-------------------|------------------------|
+| **PRD Writing** | One Question, OMTM, hypothesis all defined | "OMTM is missing from the PRD" |
+| **Hypothesis Validation** | Before/After collected + judgment complete | "Validation period ended but no judgment" |
+| **Sprint** | All KR measurements complete | "KR3 still not started" |
+| **Handoff** | Checklist 100% complete | "3 items incomplete on handoff checklist" |
+| **Retrospective** | Learnings + next actions derived | "Next actions missing from retrospective" |
+
+### Notification Timing
+
+- **Immediate**: Work interruption detected (topic switch), incomplete items exist before session end
+- **Periodic**: Previous incomplete items briefed at session start, D-7/D-3/D-1 deadline alerts
+- **Proactive**: "You stopped writing the PRD — would you like to continue?"
+
+### Work Completion Enforcement
+
+Oscar verifies whether work is "truly complete":
+
+```
+User: "I'm done with the PRD"
+
+🎩 Oscar: Let me verify PRD completion.
+✅ One Question defined
+✅ Hypothesis written
+⚠️ OMTM not defined
+⚠️ Guard Rail not set
+
+🟡 Partially complete - 2 items need to be added
+```
+
+---
+
+## 2. Session Context Management
+
+Automatically suggests context cleanup when sessions get long.
+
+### Trigger Conditions
+
+| Condition | Suggestion |
+|-----------|------------|
+| 20+ conversation turns | "The session is getting long. Shall I clean up?" |
+| 3+ topic switches | "We've covered multiple topics. Shall I distill the key points?" |
+| New work started after task completion | "Shall I clean up the previous work and start fresh?" |
+| Before session end | "Shall I save today's content? (`/save`)" |
+
+### Preservation Priority
+
+```
+🔴 Must Preserve
+├─ Current sprint goals/KR
+├─ In-progress work + status
+├─ Incomplete work list
+├─ Today's decisions
+└─ Next action items
+
+🟡 Preserve Summary (key points only)
+├─ Analysis results (conclusions focused)
+├─ Key discussion points
+└─ Inter-agent handoff content
+
+🟢 Can Omit
+├─ Detailed intermediate processes
+├─ Exploration/investigation processes
+└─ Trial-and-error/revision processes
+```
+
+---
+
+## 3. Proactive Daily Log Intervention
+
+> *"Important things must be recorded. Oscar suggests first."*
+
+### Recording Suggestion Triggers
+
+| Importance | Situation | Oscar Action |
+|------------|-----------|-------------|
+| **High** | Policy decision, spec finalization, key insight | Immediately suggest "Shall I record this?" |
+| **Medium** | Feature commit, epic/story creation, analysis complete | Suggest |
+| **Low** | Typo fix, formatting, refactoring | Do not record |
+
+### Commit Auto-filtering
+
+- **Record**: feat: / fix: / docs: (policy changes, spec additions)
+- **Skip**: chore: / style: / refactor: / docs: (simple typos)
+
+### Log Types
+
+| type | Description | Detection Pattern |
+|------|-------------|-------------------|
+| `decision` | Policy/direction decision | "decided to...", "let's go with..." |
+| `commit` | Git commit | feat/fix/docs commit completed |
+| `insight` | Data insight | "discovered that...", "the key is..." |
+| `deploy` | Deployment complete | Deployment success message |
+| `spec` | Spec finalized | Epic/Story finalized |
+| `handoff` | Handoff | Inter-agent handover complete |
+
+### Log Addition Logic
+
+1. Read `.context/daily/{today's date}.yaml` (create if doesn't exist)
+2. Find the entry for the current session ID
+3. Append to `logs` array: `{time, type, content, context}`
+4. Update `_meta` and save
+
+### Natural Language Invocation Detection
+
+"Organize what I did today", "daily work summary", "daily log" → Route to `/daily` skill

package/scaffold/.context/project.yaml.example

@@ -0,0 +1,102 @@
+# Project Configuration - Generated/updated through Oscar Setup interview
+# This file contains the core context of the project.
+# The Setup Wizard (/start) automatically generates this file through an interview.
+
+# ============================================================
+# Project Basic Information
+# ============================================================
+project:
+  name: ""           # {{project.name}}
+  tagline: ""        # {{project.tagline}}
+  type: ""           # brownfield | greenfield
+
+# ============================================================
+# Problem & Market
+# ============================================================
+problem:
+  core: ""
+  target: ""
+  alternatives: []
+  timing: ""
+
+# ============================================================
+# Solution & Differentiation
+# ============================================================
+solution:
+  approach: ""
+  differentiation: ""
+  outcome: []
+
+# ============================================================
+# Current State
+# ============================================================
+current_state:
+  stage: ""          # idea | prototype | mvp | launched | pmf | growth
+  focus: ""
+  uncertainty: ""
+  next_milestone: ""
+
+# ============================================================
+# Validation & Learning
+# ============================================================
+validation:
+  confirmed: []
+  unknown: []
+  customer_feedback: ""
+
+# ============================================================
+# Operations Settings
+# ============================================================
+operations:
+  sprint:
+    enabled: true
+    current: 1
+    duration_weeks: 2
+    d_day: ""
+
+  domains: []
+  # Example:
+  # - { id: growth, name: "Growth", path: "domains/growth/" }
+  # - { id: marketing, name: "Marketing", path: "domains/marketing/" }
+
+  integrations:
+    ga4:
+      enabled: false
+      property_id: ""          # {{integrations.ga4.property_id}}
+    notion:
+      enabled: false
+      workspace: ""
+      daily_page_id: ""
+    channel_io:
+      enabled: false
+    prod_db:
+      enabled: false
+      mcp_name: ""             # {{integrations.prod_db.mcp_name}}
+      snapshot_mcp_name: ""    # {{integrations.prod_db.snapshot_mcp_name}}
+      caution: []              # {{#each integrations.prod_db.caution}}
+      rules: ""
+      tunnel_script: ""
+    notebooklm:
+      enabled: false
+      notebook_name: ""        # {{integrations.notebooklm.notebook_name}}
+    corti:
+      enabled: false
+      workspace_id: ""         # {{integrations.corti.workspace_id}}
+      default_domain: ""       # {{integrations.corti.default_domain}}
+
+  dev_scope:
+    repo_name: ""              # {{dev_scope.repo_name}}
+    service_repo: ""           # {{dev_scope.service_repo}}
+
+  spec_site:
+    title: ""                  # {{spec_site.title}}
+    deploy_url: ""             # {{spec_site.deploy_url}}
+
+# ============================================================
+# Metadata
+# ============================================================
+_meta:
+  created_at: ""
+  created_by: "Oscar (Setup Wizard)"
+  last_interview: null
+  version: "1.0.0"

package/scaffold/.context/templates/dev-guide.md

@@ -0,0 +1,217 @@
+# Developer Agent Guide
+
+> Development workflow guide for AI Agent Driven Development
+
+---
+
+## Overview
+
+This guide defines the workflow that AI development agents (Claude Code, etc.) must follow when performing story-based development.
+
+---
+
+## Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Dev Agent Workflow                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load Story                                                   │
+│     └─→ Check for ready-for-dev in sprint-status.yaml           │
+│                                                                 │
+│  2. Understand Context                                           │
+│     ├─→ Understand user story                                    │
+│     ├─→ Review acceptance criteria                               │
+│     └─→ Study Dev Notes                                          │
+│                                                                 │
+│  3. Review References                                            │
+│     ├─→ Check PRD                                                │
+│     ├─→ Check design                                             │
+│     └─→ Review existing implementations                          │
+│                                                                 │
+│  4. Check Conflict Detection                                     │
+│     └─→ Resolve ⚠️ items first                                   │
+│                                                                 │
+│  5. Implement Tasks in Order                                     │
+│     └─→ Update checkboxes on subtask completion                  │
+│                                                                 │
+│  6. Completion Processing                                        │
+│     ├─→ Update Dev Agent Record                                  │
+│     ├─→ Record modified file list                                │
+│     └─→ Change status to review                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Detailed Steps
+
+### Step 1: Load Story
+
+1. Check `sprint-status.yaml` file
+2. Select a story with `status: ready-for-dev`
+3. Load the story document
+
+```yaml
+# sprint-status.yaml example
+- id: E-01-S-01
+  title: "Landing page redesign"
+  status: ready-for-dev  # ← Select this story
+  assignee: null
+```
+
+### Step 2: Understand Context
+
+**Required checks**:
+
+| Section | What to Check |
+|---------|--------------|
+| User Story | Understand role, feature, value |
+| Acceptance Criteria | Understand Given-When-Then conditions |
+| Dev Notes | Verify architecture pattern, tech stack |
+| Task Breakdown | Determine implementation order |
+
+### Step 3: Review References
+
+Check and understand all reference documents:
+
+- **PRD**: Original business requirements
+- **Design**: UI/UX details
+- **Existing Implementation**: Code with similar patterns
+
+### Step 4: Check Conflict Detection
+
+Check the "Conflict Detection" section in Dev Notes:
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| ✅ None | No conflicts | Proceed |
+| ⚠️ Caution | Potential conflict | **Resolve first, then proceed** |
+
+### Step 5: Implement Tasks in Order
+
+**Rules**:
+
+1. **Do not change task order** - Dependencies have been considered
+2. **Do not add features beyond acceptance criteria** - Prevent scope creep
+3. **Update checkboxes on each subtask completion**
+
+```markdown
+### Task 1: Implement API endpoint `AC-01`
+- [x] **1.1**: Create Controller  ← Check on completion
+- [x] **1.2**: Implement Service logic
+- [ ] **1.3**: Connect Repository   ← In progress
+```
+
+### Step 6: Completion Processing
+
+1. **Update Dev Agent Record**
+
+```markdown
+## Dev Agent Record
+
+| Item | Value |
+|------|-------|
+| Created By Agent | Claude Opus 4.5 |
+| Created Date | 2026-01-24 |
+| Last Modified | 2026-01-24 |
+
+### Completion Notes
+- Notable items: Maintained compatibility with existing API schema
+- Changed parts: Added method to UserController
+- Additional considerations: Cache invalidation logic needed
+```
+
+2. **Record modified file list**
+
+```markdown
+### Modified File List
+- src/controllers/UserController.ts
+- src/services/UserService.ts
+- src/repositories/UserRepository.ts
+- tests/UserController.test.ts (new)
+```
+
+3. **Change status**
+
+Change status to `review` in `sprint-status.yaml`:
+
+```yaml
+- id: E-01-S-01
+  status: review  # ready-for-dev → review
+```
+
+---
+
+## Precautions
+
+### DO
+
+- ✅ Implement tasks in order
+- ✅ Only implement features defined in acceptance criteria
+- ✅ Resolve conflict detection items first
+- ✅ Record all modified files
+- ✅ Write tests (when specified in Dev Notes)
+- ✅ Follow code style guide
+
+### DON'T
+
+- ❌ Change task order
+- ❌ Add features beyond acceptance criteria
+- ❌ Proceed ignoring ⚠️ conflicts
+- ❌ Skip Dev Agent Record update
+- ❌ Skip file list recording
+- ❌ Skip status change
+
+---
+
+## Error Handling
+
+### When a Blocker Occurs During Implementation
+
+1. Revert story status to `backlog`
+2. Record blocker details in Dev Agent Record
+3. Notify PO/responsible person
+
+```markdown
+### Completion Notes
+- Blocker: External API authentication key required
+- Required action: Request API key from DevOps team
+- Estimated resolution time: 1 day
+```
+
+### When Acceptance Criteria Are Unclear
+
+1. Stop implementation
+2. Request clarification via AskUserQuestion
+3. Update story document then proceed
+
+---
+
+## Quality Criteria
+
+Pre-completion checks:
+
+- [ ] All acceptance criteria met
+- [ ] All task checkboxes completed
+- [ ] Tests written and passing (if applicable)
+- [ ] No linting errors
+- [ ] Event logging verified (if applicable)
+- [ ] Dev Agent Record updated
+- [ ] Modified file list recorded
+
+---
+
+## Related Documents
+
+| Document | Location |
+|----------|----------|
+| Story Template | `.context/templates/story-v2.md` |
+| Sprint Status | `.context/sprints/s[N]/sprint-status.yaml` |
+| Handoff Checklist | `.context/templates/handoff-checklist.md` |
+
+---
+
+*Last updated: 2026-01-19*

package/scaffold/.context/templates/epic-spec.md

@@ -0,0 +1,225 @@
+# Epic Spec Template
+
+> Detailed epic specification written by the PO
+> This document must be finalized before Story creation
+
+---
+
+## [Epic ID]: [Epic Name]
+
+### Meta
+
+| Item | Value |
+|------|-------|
+| **Epic ID** | E-XX |
+| **Sprint** | SXX |
+| **Status** | `draft` / `review` / `approved` |
+| **PO Approval Date** | YYYY-MM-DD |
+| **Assigned Developer** | - |
+
+---
+
+## 1. WHY: Why is this feature needed?
+
+### Problem Definition
+
+[What problem are we trying to solve? Describe the specific situation]
+
+```
+[Example]
+Currently, users cannot determine "whether this is good or bad" even after viewing dashboard metrics.
+They cannot tell what their key metrics look like relative to their goals, preventing them from making appropriate decisions.
+```
+
+### Supporting Data
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| [Problem severity metric] | [Value] | [GA4/DB/VOC] |
+
+```
+[Example]
+| Metric | Value | Source |
+|--------|-------|--------|
+| No action after entering detail page | 64% | GA4 |
+| "Don't understand what the metrics mean" VOC | 12/month | Channel.io |
+```
+
+### Expected Outcome
+
+[What changes are expected when this feature is deployed?]
+
+---
+
+## 2. WHAT: Detailed Requirements
+
+### Core Features
+
+| # | Feature | Description | Required |
+|---|---------|-------------|----------|
+| 1 | [Feature name] | [Description] | Required/Optional |
+| 2 | [Feature name] | [Description] | Required/Optional |
+
+### Business Logic
+
+#### [Logic 1: Name]
+
+```
+[Detailed formulas/rules/conditions]
+
+Example:
+Conversion rate = (Conversions / Visits) × 100
+Goal achievement rate = (Current value / Target value) × 100
+
+Conditions:
+- If no target value → Show "Set a goal for more accuracy" guidance
+- If achievement rate is below threshold → Show "Warning", red color
+```
+
+#### [Logic 2: Name]
+
+```
+[Detailed formulas/rules/conditions]
+```
+
+### User Scenarios
+
+```
+[Concrete usage flow]
+
+1. User enters the dashboard page
+2. Sees "75% of goal achieved" displayed next to 15% conversion rate on the "Item A" card
+3. User understands "I have 25% left to reach my goal"
+4. ...
+```
+
+---
+
+## 3. HOW: Flow & Screens
+
+### User Flow
+
+```
+[Start] → [Step 1] → [Step 2] → [Branch] → [Complete]
+                              ↓
+                           [Exception]
+```
+
+### Wireframe
+
+```
+[ASCII or Figma link]
+
+┌────────────────────────────────────────┐
+│ Item A                      🟢 Good    │
+├────────────────────────────────────────┤
+│                                        │
+│ Conversion Rate 15%                    │
+│ ───────────────────────                │
+│ 📊 75% of goal achieved               │
+│                                        │
+│ [View Details →]                       │
+└────────────────────────────────────────┘
+```
+
+### Design Requirements
+
+| Item | Content |
+|------|---------|
+| Tone & Manner | [e.g., Friendly and easy expressions] |
+| Colors | [e.g., Positive=green, Negative=red] |
+| Reference Design | [Link] |
+
+---
+
+## 4. EDGE: Exceptions & Edge Cases
+
+### Data Exceptions
+
+| Situation | Handling Method |
+|-----------|----------------|
+| Required input missing | [How to handle?] |
+| Data value is 0 | [How to handle?] |
+| No data available | [How to handle?] |
+
+### User Exceptions
+
+| Situation | Handling Method |
+|-----------|----------------|
+| [Exception scenario] | [Handling method] |
+
+### System Exceptions
+
+| Situation | Handling Method |
+|-----------|----------------|
+| API failure | [How to handle?] |
+| Timeout | [How to handle?] |
+
+---
+
+## 5. Success Metrics
+
+### Success Criteria for This Epic
+
+| Metric | Before | Target | Measurement Method |
+|--------|--------|--------|-------------------|
+| [Metric 1] | [Current value] | [Target value] | [Method] |
+| [Metric 2] | [Current value] | [Target value] | [Method] |
+
+### GA4 Event Definitions
+
+| Event Name | Trigger | Parameters |
+|------------|---------|------------|
+| [event_name] | [When] | [What] |
+
+---
+
+## 6. Dependencies & Constraints
+
+### Technical Dependencies
+
+| Dependency | Status | Notes |
+|-----------|--------|-------|
+| [API/Data/Feature] | Confirmed/Unconfirmed | [Description] |
+
+### Constraints
+
+- [Constraint 1: e.g., Maintain existing UI layout]
+- [Constraint 2: e.g., No mobile support]
+
+---
+
+## 7. Story List (Planned)
+
+> To be broken down by 📋 Penny after Epic Spec is finalized
+
+| Story ID | Title | Size | Status |
+|----------|-------|------|--------|
+| E-XX-S-01 | [Title] | S/M/L | draft |
+| E-XX-S-02 | [Title] | S/M/L | draft |
+
+---
+
+## Checklist
+
+### Pre-PO Approval Check
+
+- [ ] Is the problem definition clear?
+- [ ] Is the business logic specific? (formulas, conditions, etc.)
+- [ ] Is there a wireframe/flow?
+- [ ] Are edge cases defined?
+- [ ] Are success metrics measurable?
+- [ ] Are technical dependencies confirmed?
+
+### Approval
+
+| Item | Confirmation |
+|------|-------------|
+| PO Approval | ☐ |
+| Approval Date | YYYY-MM-DD |
+| Notes | - |
+
+---
+
+*Created: YYYY-MM-DD*
+*Last Modified: YYYY-MM-DD*