qualia-framework 3.2.1 → 3.3.1

package/skills/qualia-optimize/SKILL.md

@@ -367,7 +367,7 @@ status: {clean|needs_attention|critical_issues}
 
 Commit:
 ```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: optimization report ({mode} mode, {critical} critical)" --files .planning/OPTIMIZE.md
+git add .planning/OPTIMIZE.md && git commit -m "docs: optimization report ({mode} mode, {critical} critical)"
 ```
 
 **Present results:**

package/skills/qualia-plan/SKILL.md

@@ -1,101 +1,206 @@
 ---
 name: qualia-plan
-description: "Plan the current phase — spawns planner agent in fresh context. Use when ready to plan a phase."
+description: "Plan the current phase — spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase."
 ---
 
 # /qualia-plan — Plan a Phase
 
-Spawn a planner agent to break the current phase into executable tasks.
+Spawn a planner agent to break the current phase into executable tasks, then validate the plan with a checker (up to 3 revision cycles) before routing to build.
 
 ## Usage
+
 `/qualia-plan` — plan the next unplanned phase
-`/qualia-plan {N}` — plan specific phase
+`/qualia-plan {N}` — plan specific phase N
 `/qualia-plan {N} --gaps` — plan fixes for verification failures
+`/qualia-plan {N} --skip-check` — skip the plan-checker validation loop (not recommended)
 
 ## Process
 
-### 1. Determine Phase & Load Knowledge
+### 1. Determine Phase & Load Context
 
 ```bash
 cat .planning/STATE.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/PROJECT.md 2>/dev/null
 cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
 cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
 ```
 
 If no phase number given, use the current phase from STATE.md.
-If any learned patterns apply to this phase's work, pass them to the planner in the spawn prompt under a `## Relevant Learnings` section.
-If this is a client project and `client-prefs.md` has an entry for the client, include those preferences in the planner context.
 
-### 2. Spawn Planner (Fresh Context)
+**Read phase-specific context if it exists:**
+```bash
+cat .planning/phase-{N}-context.md 2>/dev/null   # from /qualia-discuss
+cat .planning/phase-{N}-research.md 2>/dev/null  # from /qualia-research
+```
+
+### 2. Optional: Suggest Deeper Prep
+
+**If ROADMAP.md marked this phase as a "research flag" AND no phase-{N}-research.md exists:**
+
+- header: "Research first?"
+- question: "This phase was flagged for deeper research. Run /qualia-research {N} first?"
+- options:
+  - "Yes, research first" — Run /qualia-research {N} inline, then continue
+  - "Skip, plan directly" — I know enough
+
+**If phase involves compliance/regulatory/architectural stakes AND no phase-{N}-context.md exists:**
+
+Briefly suggest: *"Want to run /qualia-discuss {N} first to lock decisions? Optional."*
+
+Don't force it. Some phases don't need it.
+
+### 3. Spawn Planner (Fresh Context)
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from STATE.md}"
+node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
 node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
 ```
 
-Spawn a subagent with `agents/planner.md` instructions:
+Spawn the planner:
 
 ```
 Agent(prompt="
-Read your role: @agents/planner.md
+Read your role: @~/.claude/agents/planner.md
 
-Project context:
+<project_context>
 @.planning/PROJECT.md
+</project_context>
 
-Current state:
+<current_state>
 @.planning/STATE.md
+</current_state>
+
+<phase_details>
+Phase {N} from ROADMAP.md:
+@.planning/ROADMAP.md
 
-Phase {N} goal: {goal from STATE.md roadmap}
-Phase {N} success criteria: {criteria from STATE.md}
+Goal: {goal from ROADMAP.md}
+Requirements: {REQ-IDs from ROADMAP.md}
+Success criteria: {success criteria from ROADMAP.md}
+</phase_details>
 
-{If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix}
+<locked_decisions>
+{if phase-{N}-context.md exists, inline its Locked Decisions section; else 'none'}
+</locked_decisions>
 
-Create the plan file at .planning/phase-{N}-plan.md
+<research_findings>
+{if phase-{N}-research.md exists, inline its recommendation; else 'none'}
+</research_findings>
+
+{If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix. Create gap-closure plan.}
+
+<relevant_learnings>
+{inline any applicable patterns from knowledge/learned-patterns.md}
+</relevant_learnings>
+
+Create the plan at .planning/phase-{N}-plan.md (or .planning/phase-{N}-gaps-plan.md for --gaps).
 ", subagent_type="qualia-planner", description="Plan phase {N}")
 ```
 
-### 3. Review Plan
+### 4. Validate the Plan (unless --skip-check)
+
+Read the generated plan. Spawn the plan-checker:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/plan-checker.md
+
+<plan_path>.planning/phase-{N}-plan.md</plan_path>
+<phase_goal>{goal from ROADMAP.md}</phase_goal>
+<success_criteria>{criteria from ROADMAP.md}</success_criteria>
+<project_context>@.planning/PROJECT.md</project_context>
+
+Validate against the 7 rules. Return PASS or REVISE with structured issues.
+", subagent_type="qualia-plan-checker", description="Check plan phase {N}")
+```
 
-Read the generated plan. Present the summary using the UI helpers:
+**Revision loop (max 3 iterations):**
+
+- Iteration 1: Check → if REVISE, re-spawn planner with checker issues
+- Iteration 2: Re-check → if REVISE, re-spawn planner with new issues
+- Iteration 3: Final check → if REVISE or BLOCKED, escalate to user
+
+For each revision:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/planner.md
+
+<revision_mode>true</revision_mode>
+<current_plan>@.planning/phase-{N}-plan.md</current_plan>
+<checker_feedback>
+{inline REVISE output from plan-checker}
+</checker_feedback>
+
+Revise the plan in place. Address every issue. Do NOT add new tasks or change scope
+— only fix what the checker flagged.
+", subagent_type="qualia-planner", description="Revise plan phase {N}")
+```
+
+After revision, spawn the checker again. Max 3 total revision cycles.
+
+**If checker returns BLOCKED after 3 cycles:**
+
+```bash
+node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 3 revisions"
+```
+
+Show the remaining issues. Ask:
+- "Skip validation and proceed anyway" (use `--skip-check`)
+- "Adjust the roadmap" (phase scope may be wrong)
+- "Adjust the phase goal" (success criteria may be under-specified)
+
+### 5. Present Final Plan
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
 node ~/.claude/bin/qualia-ui.js ok "Plan ready: {count} tasks across {count} waves"
 ```
 
-Then, for each wave, print:
-
+For each wave:
 ```bash
-node ~/.claude/bin/qualia-ui.js wave {wave_num} {wave_total} {task_count_in_wave}
+node ~/.claude/bin/qualia-ui.js wave {wave_num} {wave_total} {task_count}
 node ~/.claude/bin/qualia-ui.js task 1 "{task title}"
 node ~/.claude/bin/qualia-ui.js task 2 "{task title}"
 ```
 
-End with an approval prompt (plain text, no UI helper): *"Approve? (yes / adjust)"*
+End with plain text: *"Approve? (yes / adjust)"*
 
-If "adjust" — get feedback, re-spawn planner with revision context.
+If "adjust" — get feedback, re-spawn planner with revision context, re-validate.
 
-### 4. Update State
+### 6. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to planned --phase {N}
 ```
-If state.js returns an error, show it to the employee and stop.
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+If state.js returns an error, show it and stop. Do NOT manually edit STATE.md or tracking.json.
+
+### 7. Route
 
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
 ```
 
-### Gap Closure Mode (`--gaps`)
+## Gap Closure Mode (`--gaps`)
 
 When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
 
 1. Read `.planning/phase-{N}-verification.md` — extract ONLY the FAIL items
 2. For each FAIL item, create a targeted fix task:
-   - **Files:** The specific files that failed verification
-   - **Action:** The specific fix needed (not "fix auth" — "add session persistence check in `src/lib/auth.ts` signIn function")
-   - **Done when:** The exact verification criterion that previously failed, restated
+   - **Files:** specific files that failed verification
+   - **Action:** specific fix (not "fix auth" — "add session persistence check in src/lib/auth.ts signIn function")
+   - **Done when:** the exact verification criterion that previously failed, restated
 3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
 4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
 5. All gap tasks are Wave 1 (parallel) unless they share files
+6. Plan-checker still validates the gap plan — same 7 rules apply
+
+## Rules
+
+1. **Plan-checker is mandatory by default.** Only skip with `--skip-check`, and only if you know what you're doing.
+2. **Max 3 revision cycles.** After 3 failed checks, escalate — the phase scope is probably wrong.
+3. **Honor locked decisions.** If phase-{N}-context.md exists, its locked decisions are non-negotiable.
+4. **One plan file per phase.** Don't create phase-1-plan.md AND phase-1-plan-v2.md. Edit in place.
+5. **Revision is surgical.** When revising, only fix what the checker flagged — no scope creep.

package/skills/qualia-research/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: qualia-research
+description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+---
+
+# /qualia-research — Per-Phase Deep Research
+
+Runs targeted research on a domain, library, or integration that a specific phase depends on. Distinct from `/qualia-new` research (which covers 4 dimensions project-wide) — this one is narrow and phase-scoped.
+
+## When to Use
+
+- A phase touches a library you've never used
+- A phase integrates with a niche API (FHIR, legal forms, payment gateways)
+- SUMMARY.md marked this phase as a "Research flag"
+- You're about to plan and realize you don't know the current best practice
+
+## Usage
+
+`/qualia-research {N}` — research the current phase or phase N
+
+## Process
+
+### 1. Determine Phase
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Use phase N from args, or current phase from STATE.md.
+
+### 2. Load Context
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/phase-{N}-context.md 2>/dev/null  # if /qualia-discuss was run first
+```
+
+Identify what this phase needs to know.
+
+### 3. Ask the User What to Research
+
+Inline free text:
+
+**"I'm about to research Phase {N}: {phase name}. What specifically do you want me to dig into? Library, domain, integration, pattern?"**
+
+Wait for their answer. Their answer defines the research question.
+
+### 4. Spawn the Researcher
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>phase-specific</dimension>
+
+<question>
+{user's research question}
+</question>
+
+<phase_context>
+Phase: {N}
+Goal: {phase goal from ROADMAP.md}
+Requirements: {REQ-IDs covered by this phase}
+</phase_context>
+
+<project_context>
+{PROJECT.md summary}
+</project_context>
+
+<output_path>
+.planning/phase-{N}-research.md
+</output_path>
+
+Research using Context7 first, then WebFetch, then WebSearch. Be specific and concrete.
+Include: recommendation, rationale, version numbers (if applicable), code examples,
+alternatives considered, what to avoid, sources.
+", subagent_type="qualia-researcher", description="Phase {N} research")
+```
+
+### 5. Review Output
+
+Read `.planning/phase-{N}-research.md`. Present the key findings:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Research complete"
+```
+
+Show:
+- Recommendation
+- Confidence
+- Top 3 key findings
+- Sources used
+
+### 6. User Confirms or Asks More
+
+- header: "Enough?"
+- question: "Is this enough research, or should I dig deeper?"
+- options:
+  - "Enough" — Move to planning
+  - "Dig deeper" — I have more questions
+
+If "Dig deeper" — ask what they want, re-spawn the researcher with additional questions.
+
+### 7. Commit
+
+```bash
+git add .planning/phase-{N}-research.md
+git commit -m "docs(phase-{N}): research findings"
+```
+
+### 8. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
+```
+
+## Rules
+
+1. **One research session per run.** Don't try to research phases 1 through 5 in one call.
+2. **Must produce a file.** The research is worthless if it only lives in conversation context.
+3. **Honor locked decisions from phase-{N}-context.md.** Don't research alternatives to something already locked.
+4. **Context7 first.** Always try Context7 MCP before WebFetch — it's fastest and most current for known libraries.

package/templates/phase-context.md

@@ -0,0 +1,48 @@
+---
+phase: {N}
+captured: {date}
+---
+
+# Phase {N} Context: {Phase Name}
+
+Captured during `/qualia-discuss {N}` — decisions, trade-offs, and constraints that must inform planning.
+
+## Goal Restatement
+
+{What this phase must achieve, in one sentence}
+
+## Locked Decisions
+
+Non-negotiable choices. Planner must honor these exactly.
+
+| Decision | Rationale | Source |
+|----------|-----------|--------|
+| {e.g., "Use Supabase RLS for authorization, not middleware"} | {e.g., "Client compliance requires database-level checks"} | {who/when} |
+
+## Discretion (Planner Chooses)
+
+Things the planner can decide based on research and best practice.
+
+- {area where planner has freedom}
+- {area where planner has freedom}
+
+## Deferred Ideas
+
+Good ideas that are NOT in this phase. Captured so they don't get lost.
+
+- {deferred idea} — defer to {Phase N+1 / v2 / out of scope}
+
+## Risk Flags
+
+Things to watch out for during planning and building.
+
+- **{risk}** — {mitigation approach}
+
+## Questions Pending Answer
+
+Things we haven't decided yet. Must be resolved before `/qualia-plan {N}`.
+
+- [ ] {open question}
+
+---
+*Read by `/qualia-plan {N}` as locked planner input*

package/templates/projects/ai-agent.md

@@ -0,0 +1,55 @@
+# Project Template: AI Agent / Chatbot
+
+Typical phase structure for a chatbot, AI assistant, tool-calling agent, or RAG system.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Next.js 16 + Supabase + OpenRouter (or direct provider) + Vercel AI SDK
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Project skeleton with Supabase wired, OpenRouter API configured, base chat page rendering.
+
+**Typical success criteria:**
+1. Site loads on Vercel preview URL
+2. Chat page renders with input box
+3. Environment variables configured (`OPENROUTER_API_KEY`)
+
+### Phase 2: Core Agent Logic
+
+**Goal:** Agent responds to messages with streaming.
+
+**Requirements covered:** System prompt, chat completion, streaming response, message history display.
+
+### Phase 3: Tool Calling (if needed)
+
+**Goal:** Agent can invoke tools (search, database, APIs) and return results.
+
+**Requirements covered:** Tool definitions, tool execution, multi-step agent loop.
+
+### Phase 4: Memory & Persistence
+
+**Goal:** Conversations persist across sessions, user can see history.
+
+**Requirements covered:** Database schema for conversations, load/save, conversation list.
+
+### Phase 5: Polish & Guardrails
+
+**Goal:** Rate limiting, error handling, content moderation, cost tracking.
+
+**Requirements covered:** Rate limits per user, graceful errors, abuse prevention, usage analytics.
+
+## Common Requirements Categories
+
+- **AGENT** — core agent logic and prompting
+- **TOOL** — tool calling and integrations
+- **CONV** — conversations and history
+- **RATE** — rate limiting and abuse prevention
+- **AUTH** — authentication
+
+## Research Flags
+
+- **Domain-specific prompting** (legal, medical, financial advice) → run `/qualia-research` for the prompt engineering phase
+- **RAG over specific datasets** (vector DB, chunking strategy) → `/qualia-discuss` before planning
+- **Multi-step agent orchestration** → `/qualia-discuss` to lock tool boundaries before planning

package/templates/projects/mobile-app.md

@@ -0,0 +1,56 @@
+# Project Template: Mobile App
+
+Typical phase structure for a React Native / Expo app, iOS + Android.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Expo SDK + React Native + TypeScript + Supabase + Expo Application Services (EAS)
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Expo project scaffolded, Supabase wired, auth flow working on both iOS and Android simulators.
+
+**Typical success criteria:**
+1. App runs in Expo Go on iOS simulator
+2. App runs in Expo Go on Android emulator
+3. User can sign up + log in
+4. Session persists across app restart
+
+### Phase 2: Navigation & Core Screens
+
+**Goal:** Main screens exist with navigation (Expo Router), each renders its placeholder state.
+
+**Requirements covered:** Home, Profile, Settings, main feature screen.
+
+### Phase 3: Core Feature
+
+**Goal:** The primary user capability works end-to-end on mobile.
+
+**Requirements covered:** Feature-specific (depends on app — camera, map, list, etc.)
+
+### Phase 4: Native Integrations
+
+**Goal:** Native features wired — push notifications, camera, location, secure storage.
+
+**Requirements covered:** Push notifications (FCM/APNs), camera/gallery access, location, SecureStore for tokens.
+
+### Phase 5: Build & Submit
+
+**Goal:** Production builds for iOS and Android, submitted to stores.
+
+**Requirements covered:** EAS build profiles, app icons, splash screens, App Store Connect setup, Google Play Console setup.
+
+## Common Requirements Categories
+
+- **AUTH** — authentication
+- **NAV** — navigation and screens
+- **CORE** — core feature
+- **NAT** — native integrations (notifications, camera, location)
+- **BUILD** — EAS build and store submission
+
+## Research Flags
+
+- **App Store compliance** (in-app purchases, privacy, age ratings) → `/qualia-discuss` to lock scope
+- **Native module choices** (notifications, maps, camera) → `/qualia-research` per phase
+- **Deep linking and universal links** → `/qualia-discuss` before navigation phase

package/templates/projects/voice-agent.md

@@ -0,0 +1,55 @@
+# Project Template: Voice Agent
+
+Typical phase structure for a phone agent, VAPI bot, Retell agent, or call handling system.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Next.js 16 + Supabase + Retell AI / ElevenLabs / VAPI + Telnyx (phone numbers) + Vercel
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Webhook endpoint for voice provider, Supabase wired, base call logging working.
+
+**Typical success criteria:**
+1. Webhook endpoint deployed and reachable
+2. Supabase schema for `calls`, `transcripts`, `contacts` exists
+3. Provider credentials configured (`RETELL_API_KEY`, `ELEVENLABS_API_KEY`, `TELNYX_API_KEY`)
+
+### Phase 2: Agent Configuration
+
+**Goal:** Voice agent answers calls with correct prompt and voice.
+
+**Requirements covered:** Provider agent setup, system prompt, voice selection, greeting.
+
+### Phase 3: Call Flow
+
+**Goal:** Agent handles conversation, captures data, transfers when needed.
+
+**Requirements covered:** Conversation state, data capture (name, email, appointment), transfer to human.
+
+### Phase 4: Integrations
+
+**Goal:** Post-call actions fire — CRM sync, Slack notification, email confirmation.
+
+**Requirements covered:** CRM webhook, Slack bot, transactional email.
+
+### Phase 5: Polish & Monitoring
+
+**Goal:** Low latency, graceful errors, call quality monitoring, cost tracking.
+
+**Requirements covered:** Latency optimization, silent call recovery, cost per call tracking, dashboard.
+
+## Common Requirements Categories
+
+- **CALL** — call handling and routing
+- **CONV** — conversation flow
+- **INTG** — external integrations (CRM, Slack, email)
+- **MON** — monitoring and cost tracking
+- **PROV** — voice provider configuration
+
+## Research Flags
+
+- **Provider choice** (Retell vs VAPI vs ElevenLabs direct) → `/qualia-research 1` to compare for this specific use case
+- **Telephony setup** (DIDs, porting, SIP) → `/qualia-discuss` to lock decisions before wiring
+- **Prompt engineering for voice** → `/qualia-research` for the agent config phase

package/templates/projects/website.md

@@ -0,0 +1,58 @@
+# Project Template: Website / Web App
+
+Typical phase structure for a client website, SaaS landing page, dashboard, or marketing site.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Next.js 16 + React 19 + TypeScript + Supabase + Vercel
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Project skeleton exists on Vercel with Supabase wired, auth working, and base layout rendering.
+
+**Requirements covered:** Auth (sign up / log in / log out / session persistence), base layout, deploy pipeline.
+
+**Typical success criteria:**
+1. Site loads on Vercel preview URL
+2. User can sign up with email + password
+3. User can log in and stay logged in across refresh
+4. Base layout renders with nav + footer
+
+### Phase 2: Core Feature (primary)
+
+**Goal:** The main value-delivering feature works end-to-end.
+
+**Requirements covered:** Primary user capability (depends on project — posting, booking, searching, etc.)
+
+### Phase 3: Core Feature (secondary)
+
+**Goal:** Supporting features that make the primary feature usable.
+
+**Requirements covered:** Profile, settings, admin panel, etc.
+
+### Phase 4: Content & Marketing
+
+**Goal:** Marketing pages, copy, images, SEO meta tags.
+
+**Requirements covered:** Homepage hero, features section, pricing, about, contact.
+
+### Phase 5: Polish & Launch
+
+**Goal:** Site is production-ready.
+
+**Requirements covered:** Responsive (mobile / tablet / desktop), animations, error states, empty states, a11y, SEO, analytics.
+
+## Common Requirements Categories
+
+- **AUTH** — authentication and sessions
+- **PROF** — user profiles
+- **CONT** — content / primary feature
+- **ADMIN** — admin panel
+- **MARK** — marketing pages
+- **SEO** — SEO, sitemaps, analytics
+
+## Research Flags
+
+- **Niche domain integrations** (e.g., legal compliance, medical records, financial regulations) → run `/qualia-research N` before planning that phase
+- **Complex auth** (SSO, multi-tenant, RBAC) → run `/qualia-discuss N` first