qualia-framework 2.6.0 → 3.1.0

package/framework/qualia-framework/templates/context.md

@@ -1,283 +0,0 @@
-# Phase Context Template
-
-Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
-
-**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
-
-**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
-
-**Downstream consumers:**
-- `qualia-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
-- `qualia-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
-
----
-
-## File Template
-
-```markdown
-# Phase [X]: [Name] - Context
-
-**Gathered:** [date]
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### [Area 1 that was discussed]
-- [Specific decision made]
-- [Another decision if applicable]
-
-### [Area 2 that was discussed]
-- [Specific decision made]
-
-### [Area 3 that was discussed]
-- [Specific decision made]
-
-### Claude's Discretion
-[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
-
-[If none: "No specific requirements — open to standard approaches"]
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
-
-[If none: "None — discussion stayed within phase scope"]
-
-</deferred>
-
----
-
-*Phase: XX-name*
-*Context gathered: [date]*
-```
-
-<good_examples>
-
-**Example 1: Visual feature (Post Feed)**
-
-```markdown
-# Phase 3: Post Feed - Context
-
-**Gathered:** 2025-01-20
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### Layout style
-- Card-based layout, not timeline or list
-- Each card shows: author avatar, name, timestamp, full post content, reaction counts
-- Cards have subtle shadows, rounded corners — modern feel
-
-### Loading behavior
-- Infinite scroll, not pagination
-- Pull-to-refresh on mobile
-- New posts indicator at top ("3 new posts") rather than auto-inserting
-
-### Empty state
-- Friendly illustration + "Follow people to see posts here"
-- Suggest 3-5 accounts to follow based on interests
-
-### Claude's Discretion
-- Loading skeleton design
-- Exact spacing and typography
-- Error state handling
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
-- Cards should feel like Linear's issue cards — clean, not cluttered
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- Commenting on posts — Phase 5
-- Bookmarking posts — add to backlog
-
-</deferred>
-
----
-
-*Phase: 03-post-feed*
-*Context gathered: 2025-01-20*
-```
-
-**Example 2: CLI tool (Database backup)**
-
-```markdown
-# Phase 2: Backup Command - Context
-
-**Gathered:** 2025-01-20
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### Output format
-- JSON for programmatic use, table format for humans
-- Default to table, --json flag for JSON
-- Verbose mode (-v) shows progress, silent by default
-
-### Flag design
-- Short flags for common options: -o (output), -v (verbose), -f (force)
-- Long flags for clarity: --incremental, --compress, --encrypt
-- Required: database connection string (positional or --db)
-
-### Error recovery
-- Retry 3 times on network failure, then fail with clear message
-- --no-retry flag to fail fast
-- Partial backups are deleted on failure (no corrupt files)
-
-### Claude's Discretion
-- Exact progress bar implementation
-- Compression algorithm choice
-- Temp file handling
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-- "I want it to feel like pg_dump — familiar to database people"
-- Should work in CI pipelines (exit codes, no interactive prompts)
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- Scheduled backups — separate phase
-- Backup rotation/retention — add to backlog
-
-</deferred>
-
----
-
-*Phase: 02-backup-command*
-*Context gathered: 2025-01-20*
-```
-
-**Example 3: Organization task (Photo library)**
-
-```markdown
-# Phase 1: Photo Organization - Context
-
-**Gathered:** 2025-01-20
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### Grouping criteria
-- Primary grouping by year, then by month
-- Events detected by time clustering (photos within 2 hours = same event)
-- Event folders named by date + location if available
-
-### Duplicate handling
-- Keep highest resolution version
-- Move duplicates to _duplicates folder (don't delete)
-- Log all duplicate decisions for review
-
-### Naming convention
-- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
-- Preserve original filename as suffix for searchability
-- Handle name collisions with incrementing suffix
-
-### Claude's Discretion
-- Exact clustering algorithm
-- How to handle photos with no EXIF data
-- Folder emoji usage
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-- "I want to be able to find photos by roughly when they were taken"
-- Don't delete anything — worst case, move to a review folder
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- Face detection grouping — future phase
-- Cloud sync — out of scope for now
-
-</deferred>
-
----
-
-*Phase: 01-photo-organization*
-*Context gathered: 2025-01-20*
-```
-
-</good_examples>
-
-<guidelines>
-**This template captures DECISIONS for downstream agents.**
-
-The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
-
-**Good content (concrete decisions):**
-- "Card-based layout, not timeline"
-- "Retry 3 times on network failure, then fail"
-- "Group by year, then by month"
-- "JSON for programmatic use, table for humans"
-
-**Bad content (too vague):**
-- "Should feel modern and clean"
-- "Good user experience"
-- "Fast and responsive"
-- "Easy to use"
-
-**After creation:**
-- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
-- `qualia-phase-researcher` uses decisions to focus investigation
-- `qualia-planner` uses decisions + research to create executable tasks
-- Downstream agents should NOT need to ask the user again about captured decisions
-</guidelines>

package/framework/qualia-framework/templates/continue-here.md

@@ -1,78 +0,0 @@
-# Continue-Here Template
-
-Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
-
-```yaml
----
-phase: XX-name
-task: 3
-total_tasks: 7
-status: in_progress
-last_updated: 2025-01-15T14:30:00Z
----
-```
-
-```markdown
-<current_state>
-[Where exactly are we? What's the immediate context?]
-</current_state>
-
-<completed_work>
-[What got done this session - be specific]
-
-- Task 1: [name] - Done
-- Task 2: [name] - Done
-- Task 3: [name] - In progress, [what's done on it]
-</completed_work>
-
-<remaining_work>
-[What's left in this phase]
-
-- Task 3: [name] - [what's left to do]
-- Task 4: [name] - Not started
-- Task 5: [name] - Not started
-</remaining_work>
-
-<decisions_made>
-[Key decisions and why - so next session doesn't re-debate]
-
-- Decided to use [X] because [reason]
-- Chose [approach] over [alternative] because [reason]
-</decisions_made>
-
-<blockers>
-[Anything stuck or waiting on external factors]
-
-- [Blocker 1]: [status/workaround]
-</blockers>
-
-<context>
-[Mental state, "vibe", anything that helps resume smoothly]
-
-[What were you thinking about? What was the plan?
-This is the "pick up exactly where you left off" context.]
-</context>
-
-<next_action>
-[The very first thing to do when resuming]
-
-Start with: [specific action]
-</next_action>
-```
-
-<yaml_fields>
-Required YAML frontmatter:
-
-- `phase`: Directory name (e.g., `02-authentication`)
-- `task`: Current task number
-- `total_tasks`: How many tasks in phase
-- `status`: `in_progress`, `blocked`, `almost_done`
-- `last_updated`: ISO timestamp
-</yaml_fields>
-
-<guidelines>
-- Be specific enough that a fresh Claude instance understands immediately
-- Include WHY decisions were made, not just what
-- The `<next_action>` should be actionable without reading anything else
-- This file gets DELETED after resume - it's not permanent storage
-</guidelines>

package/framework/qualia-framework/templates/debug-subagent-prompt.md

@@ -1,91 +0,0 @@
-# Debug Subagent Prompt Template
-
-Template for spawning qualia-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
-
----
-
-## Template
-
-```markdown
-<objective>
-Investigate issue: {issue_id}
-
-**Summary:** {issue_summary}
-</objective>
-
-<symptoms>
-expected: {expected}
-actual: {actual}
-errors: {errors}
-reproduction: {reproduction}
-timeline: {timeline}
-</symptoms>
-
-<mode>
-symptoms_prefilled: {true_or_false}
-goal: {find_root_cause_only | find_and_fix}
-</mode>
-
-<debug_file>
-Create: .planning/debug/{slug}.md
-</debug_file>
-```
-
----
-
-## Placeholders
-
-| Placeholder | Source | Example |
-|-------------|--------|---------|
-| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` |
-| `{issue_summary}` | User description | `Auth screen is too dark` |
-| `{expected}` | From symptoms | `See logo clearly` |
-| `{actual}` | From symptoms | `Screen is dark` |
-| `{errors}` | From symptoms | `None in console` |
-| `{reproduction}` | From symptoms | `Open /auth page` |
-| `{timeline}` | From symptoms | `After recent deploy` |
-| `{goal}` | Orchestrator sets | `find_and_fix` |
-| `{slug}` | Generated | `auth-screen-dark` |
-
----
-
-## Usage
-
-**From /qualia:debug:**
-```python
-Task(
-  prompt=filled_template,
-  subagent_type="qualia-debugger",
-  description="Debug {slug}"
-)
-```
-
-**From diagnose-issues (UAT):**
-```python
-Task(prompt=template, subagent_type="qualia-debugger", description="Debug UAT-001")
-```
-
----
-
-## Continuation
-
-For checkpoints, spawn fresh agent with:
-
-```markdown
-<objective>
-Continue debugging {slug}. Evidence is in the debug file.
-</objective>
-
-<prior_state>
-Debug file: @.planning/debug/{slug}.md
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-
-<mode>
-goal: {goal}
-</mode>
-```

package/framework/qualia-framework/templates/discovery.md

@@ -1,146 +0,0 @@
-# Discovery Template
-
-Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions.
-
-**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
-
-For deep ecosystem research ("how do experts build this"), use `/qualia:research-phase` which produces RESEARCH.md.
-
----
-
-## File Template
-
-```markdown
----
-phase: XX-name
-type: discovery
-topic: [discovery-topic]
----
-
-<session_initialization>
-Before beginning discovery, verify today's date:
-!`date +%Y-%m-%d`
-
-Use this date when searching for "current" or "latest" information.
-Example: If today is 2025-11-22, search for "2025" not "2024".
-</session_initialization>
-
-<discovery_objective>
-Discover [topic] to inform [phase name] implementation.
-
-Purpose: [What decision/implementation this enables]
-Scope: [Boundaries]
-Output: DISCOVERY.md with recommendation
-</discovery_objective>
-
-<discovery_scope>
-<include>
-- [Question to answer]
-- [Area to investigate]
-- [Specific comparison if needed]
-</include>
-
-<exclude>
-- [Out of scope for this discovery]
-- [Defer to implementation phase]
-</exclude>
-</discovery_scope>
-
-<discovery_protocol>
-
-**Source Priority:**
-1. **Context7 MCP** - For library/framework documentation (current, authoritative)
-2. **Official Docs** - For platform-specific or non-indexed libraries
-3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
-
-**Quality Checklist:**
-Before completing discovery, verify:
-- [ ] All claims have authoritative sources (Context7 or official docs)
-- [ ] Negative claims ("X is not possible") verified with official documentation
-- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
-- [ ] WebSearch findings cross-checked with authoritative sources
-- [ ] Recent updates/changelogs checked for breaking changes
-- [ ] Alternative approaches considered (not just first solution found)
-
-**Confidence Levels:**
-- HIGH: Context7 or official docs confirm
-- MEDIUM: WebSearch + Context7/official docs confirm
-- LOW: WebSearch only or training knowledge only (mark for validation)
-
-</discovery_protocol>
-
-
-<output_structure>
-Create `.planning/phases/XX-name/DISCOVERY.md`:
-
-```markdown
-# [Topic] Discovery
-
-## Summary
-[2-3 paragraph executive summary - what was researched, what was found, what's recommended]
-
-## Primary Recommendation
-[What to do and why - be specific and actionable]
-
-## Alternatives Considered
-[What else was evaluated and why not chosen]
-
-## Key Findings
-
-### [Category 1]
-- [Finding with source URL and relevance to our case]
-
-### [Category 2]
-- [Finding with source URL and relevance]
-
-## Code Examples
-[Relevant implementation patterns, if applicable]
-
-## Metadata
-
-<metadata>
-<confidence level="high|medium|low">
-[Why this confidence level - based on source quality and verification]
-</confidence>
-
-<sources>
-- [Primary authoritative sources used]
-</sources>
-
-<open_questions>
-[What couldn't be determined or needs validation during implementation]
-</open_questions>
-
-<validation_checkpoints>
-[If confidence is LOW or MEDIUM, list specific things to verify during implementation]
-</validation_checkpoints>
-</metadata>
-```
-</output_structure>
-
-<success_criteria>
-- All scope questions answered with authoritative sources
-- Quality checklist items completed
-- Clear primary recommendation
-- Low-confidence findings marked with validation checkpoints
-- Ready to inform PLAN.md creation
-</success_criteria>
-
-<guidelines>
-**When to use discovery:**
-- Technology choice unclear (library A vs B)
-- Best practices needed for unfamiliar integration
-- API/library investigation required
-- Single decision pending
-
-**When NOT to use:**
-- Established patterns (CRUD, auth with known library)
-- Implementation details (defer to execution)
-- Questions answerable from existing project context
-
-**When to use RESEARCH.md instead:**
-- Niche/complex domains (3D, games, audio, shaders)
-- Need ecosystem knowledge, not just library choice
-- "How do experts build this" questions
-- Use `/qualia:research-phase` for these
-</guidelines>

package/framework/qualia-framework/templates/lab-notes.md

@@ -1,16 +0,0 @@
-# Lab Notes — [Project Name]
-
-> What failed, why it failed, and what worked instead.
-> Read by planners and researchers to avoid repeating dead-end approaches.
-> Updated via `/learn` or manually during debugging sessions.
-
----
-
-<!-- Entry format:
-### Phase N: [Phase Title]
-
-**Tried:** [approach that was attempted]
-**Failed because:** [root cause — be specific]
-**Better approach:** [what actually worked, or what to try next]
-**Date:** YYYY-MM-DD
--->