qualia-framework 2.1.0

package/framework/skills/qualia-idk/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: qualia-idk
+description: "Intelligent 'what should I do next?' advisor. Reads .planning/ AND codebase, understands session context, suggests smart next actions. Use this skill whenever the user says 'idk', 'what now', 'what should I do', 'I'm stuck', 'what next', 'help me decide', 'I don't know', 'not sure', 'lost', 'confused', 'qualia-idk', or seems frustrated, stuck, or unsure about their next step. Also trigger when user has been debugging the same issue repeatedly, or when all work appears complete and user asks 'now what'."
+---
+
+# Qualia IDK — Intelligent Next-Step Advisor
+
+When you don't know what to do next, this skill reads BOTH `.planning/` AND the codebase, understands your session context, and gives you the smartest recommendation.
+
+**This is NOT a status report.** It's a senior dev advisor that understands your situation and tells you what to do.
+
+## Usage
+
+`/qualia-idk` — Analyze situation and recommend next action
+
+No flags. No modes. Just ask.
+
+## Process
+
+### Step 1: Gather Context (always — run all in parallel)
+
+```bash
+cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
+```
+
+```bash
+cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
+```
+
+```bash
+# Recent phase work
+ls -t .planning/phases/*/*-SUMMARY.md 2>/dev/null | head -3 | while read f; do echo "=== $f ==="; head -20 "$f"; done
+```
+
+```bash
+# Git state
+git status --short 2>/dev/null | head -10
+git log --oneline -5 2>/dev/null
+```
+
+```bash
+# Active debug sessions
+ls .planning/debug/*.md 2>/dev/null 2>&1 | head -3
+```
+
+```bash
+# Handoff file
+test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"
+```
+
+```bash
+# Check project type and health
+test -f package.json && echo "HAS_PACKAGE" || echo "NO_PACKAGE"
+test -d .planning && echo "HAS_PLANNING" || echo "NO_PLANNING"
+test -f .planning/OPTIMIZE.md && echo "HAS_OPTIMIZE" && head -10 .planning/OPTIMIZE.md || echo "NO_OPTIMIZE"
+test -f .planning/REVIEW.md && echo "HAS_REVIEW" || echo "NO_REVIEW"
+```
+
+Also read the **conversation history** from this session — what has the user been doing, what errors occurred, what commands were run. This is implicit (you have the conversation context).
+
+Read the most recent SUMMARY.md files (up to 3) fully to understand what was just built.
+
+### Step 2: Classify Situation
+
+Based on gathered data, classify into ONE primary situation:
+
+| Situation | How to Detect |
+|-----------|--------------|
+| `no-project` | No `.planning/` directory |
+| `fresh-session` | STATE.md exists but no work done this session, no conversation context |
+| `handoff` | `.continue-here.md` exists |
+| `mid-work` | Uncommitted git changes, phase "in progress" |
+| `phase-just-completed` | Phase status "executed" or "verified", next phase exists |
+| `phase-blocked` | STATE.md lists blockers, or phase depends on incomplete phase |
+| `bug-loop` | 3+ debug/fix attempts on same issue in conversation, or `.planning/debug/` has active sessions |
+| `all-phases-done` | All phases in current milestone complete |
+| `all-milestones-done` | No upcoming milestones, all phases across all milestones done |
+| `frustrated` | Multiple errors in conversation, same files edited repeatedly, user expressing frustration |
+
+### Step 3: Generate Recommendations
+
+Based on classification, present **1 primary recommendation** and **2-3 alternatives**.
+
+---
+
+#### If `no-project`:
+
+**Primary:** "No Qualia project here. What are you working on?"
+
+**Options:**
+1. `/qualia-new-project` — Start fresh with full planning workflow
+2. `/qualia-quick [description]` — Quick task, no project setup
+3. `/qualia-new-milestone` — Add structure to existing codebase
+
+---
+
+#### If `fresh-session`:
+
+**Primary:** Show where things stand from STATE.md, route to the logical next action.
+
+If `.continue-here.md` exists: "You left a handoff note last session. Read it first."
+
+Otherwise: read STATE.md phase status and route like the `/qualia` smart router.
+
+---
+
+#### If `handoff`:
+
+**Primary:** "Previous session left a handoff. Here's what happened:"
+
+Read and summarize `.continue-here.md`:
+- What was done (branch, commits)
+- What's uncommitted
+- Dead-ends to avoid
+- Suggested next steps
+
+---
+
+#### If `mid-work`:
+
+**Primary:** "You have work in progress:"
+- Show uncommitted files from git status
+- Show what phase/task was being worked on from STATE.md
+
+**Options:**
+1. Continue where you left off
+2. Commit progress: suggest a commit message based on changes
+3. `/qualia-pause-work` — Save context and come back later
+
+---
+
+#### If `phase-just-completed`:
+
+**Primary:** Route to the natural next step.
+
+If phase was executed but NOT verified:
+> "Phase N is built. Verify it: `/qualia-verify-work N`"
+
+If phase was verified:
+> "Phase N is done. Next: Phase N+1 — {name}. Run `/qualia-plan-phase N+1`"
+
+If phase was verified but has warnings:
+> "Phase N passed with warnings. Review them or continue to Phase N+1?"
+
+**Options:**
+1. Verify/continue (the primary)
+2. `/qualia-optimize` — Quick optimization check before moving on
+3. `/qualia-progress` — See the full picture
+
+---
+
+#### If `phase-blocked`:
+
+This is where the skill earns its keep. **Analyze WHY the phase is blocked.**
+
+Read STATE.md blockers section. Read ROADMAP.md dependencies. Then:
+
+**If blocked by dependency (another phase not done):**
+> "Phase N depends on Phase M which isn't complete. But Phase K has no blockers and could run first."
+
+Suggest reordering if safe — check that Phase K doesn't depend on Phase N.
+
+**If blocked by technical issue:**
+> "Phase N is blocked by {issue}. I can research a workaround. Want me to investigate?"
+
+Offer to spawn a research agent.
+
+**If blocked by external factor:**
+> "This needs {external thing} before it can proceed. While waiting, here's what you can work on: {independent phases/tasks}"
+
+**If blocked by unclear requirements:**
+> "The scope isn't clear enough to plan. Run `/qualia-discuss-phase N` to work through the gray areas."
+
+**Options always include:**
+1. The specific unblocking suggestion
+2. Skip this phase (if non-critical) — flag as deferred in ROADMAP.md
+3. Readjust milestone — rethink the phase order
+4. `/qualia-debug` — If it's a bug causing the block
+
+---
+
+#### If `bug-loop`:
+
+Detect: same error appearing multiple times in conversation, same files being edited 3+ times, user expressing frustration.
+
+**Primary:** "You've been working on this for a while. Let's try a different angle."
+
+Analyze what has been tried and suggest an ALTERNATIVE approach — not the same thing again.
+
+**Options:**
+1. Different approach: {specific alternative based on conversation context}
+2. Step back: verify assumptions with a minimal reproduction
+3. `/qualia-debug --error-analysis` — Systematic root cause analysis
+4. **[EMPLOYEE ONLY]:** "This might benefit from Fawzi's input — want to flag it?"
+
+---
+
+#### If `all-phases-done`:
+
+**Primary:** "All phases in this milestone are complete! Time to verify and ship."
+
+**Options:**
+1. `/qualia-audit-milestone` — Full milestone audit (recommended)
+2. `/qualia-optimize` — Optimization sweep before shipping
+3. `/qualia-review` — Production readiness review
+4. `/ship` — Deploy now (if you're confident)
+
+---
+
+#### If `all-milestones-done`:
+
+**Trigger Layer 3: Platform Gap Detection** (see Step 4).
+
+---
+
+#### If `frustrated`:
+
+Acknowledge without being condescending. Do NOT say "I understand your frustration" or similar platitudes.
+
+**Primary:** "Let's step back. What's the ONE thing you need working right now?"
+
+Focus the conversation on the single most important issue. Offer:
+
+1. Reset context: `/clear` and start fresh on the specific problem
+2. Research: "I can investigate {specific aspect} — want me to dig in?"
+3. Different approach: suggest an alternative to what they've been trying
+4. **[EMPLOYEE ONLY]:** "Want to get Fawzi's eyes on this?"
+
+---
+
+### Step 4: Platform Gap Detection (Layer 3)
+
+**Only runs when `all-milestones-done` is detected.**
+
+Scan the codebase for missing common functionality. For each category, check if it exists:
+
+```bash
+# Auth flows
+find app -name "*.tsx" -path "*/login*" -o -path "*/signup*" -o -path "*/reset*" 2>/dev/null | head -3
+```
+
+```bash
+# Error pages
+test -f app/not-found.tsx && echo "HAS_404" || echo "MISSING_404"
+test -f app/error.tsx && echo "HAS_ERROR_BOUNDARY" || echo "MISSING_ERROR_BOUNDARY"
+```
+
+```bash
+# SEO
+grep -l "metadata\|generateMetadata" app/layout.tsx app/page.tsx 2>/dev/null | head -3
+test -f public/sitemap.xml && echo "HAS_SITEMAP" || echo "MISSING_SITEMAP"
+test -f public/robots.txt && echo "HAS_ROBOTS" || echo "MISSING_ROBOTS"
+```
+
+```bash
+# Legal
+find app -name "page.tsx" -path "*privacy*" -o -path "*terms*" 2>/dev/null | head -3
+```
+
+```bash
+# Analytics & Monitoring
+grep -rl "analytics\|gtag\|plausible\|posthog\|sentry\|LogRocket" app/ lib/ 2>/dev/null | head -3
+```
+
+```bash
+# Accessibility basics
+grep -rl "aria-label\|aria-describedby\|role=" app/ components/ 2>/dev/null | wc -l
+```
+
+Compile missing items and score by priority:
+- **HIGH** — Users will notice immediately (error pages, auth flows, mobile responsiveness)
+- **MEDIUM** — Affects quality/discoverability (SEO, analytics, monitoring)
+- **LOW** — Nice to have (PWA, advanced accessibility, legal pages)
+
+**Present as a suggested next milestone:**
+
+```
+All milestones complete! Here's what I'd suggest for the next milestone:
+
+## Suggested: v{X+1}.0 — Polish & Production Readiness
+
+HIGH priority (users notice these):
+- Missing 404 page
+- No error boundaries
+- {other HIGH items}
+
+MEDIUM priority:
+- No sitemap.xml
+- Analytics not configured
+- {other MEDIUM items}
+
+Want me to:
+1. Start this milestone: /qualia-new-milestone
+2. Research best practices for any of these
+3. Just pick the top 3 and build them as quick tasks
+```
+
+### Step 5: Escalation Logic (Layer 4 — employees only)
+
+**Check the role** from `~/.claude/CLAUDE.md`:
+
+```bash
+grep -m1 "^## Role:" ~/.claude/CLAUDE.md 2>/dev/null
+```
+
+- If `Role: OWNER` — skip ALL escalation. Fawzi doesn't need to review with himself.
+- If `Role: DEVELOPER` or `Role: EMPLOYEE`:
+
+**Escalate when:**
+- Situation is `bug-loop` (3+ attempts) → "Want to get Fawzi's input?"
+- Situation is `frustrated` → "This might be worth reviewing with Fawzi"
+- Work involves: data migration, auth system changes, production database, payment logic → "This is high-risk. Consider reviewing with Fawzi first."
+- Phase is blocked with no clear path forward → "Might be worth flagging to Fawzi"
+
+**Escalation is always a suggestion, never forced.** Present it as one of the options, not the primary recommendation.
+
+### Step 6: Present Response
+
+Output as **direct conversational text**. No file creation. No YAML. No persistence.
+
+Format:
+
+```
+## Where You Are
+
+{1-2 sentence context from STATE.md / git / conversation}
+
+## I Recommend
+
+**{Top recommendation}** — {why, 1 sentence}
+{Copy-paste command if applicable}
+
+## Other Options
+
+1. **{Option}** — {what, why} _{scope: quick/medium/deep}_
+2. **{Option}** — {what, why} _{scope}_
+3. **{Option}** — {what, why} _{scope}_
+
+{If escalation applies: suggestion here, as option 4}
+```
+
+### Step 7: Handle Follow-ups
+
+The user may respond with:
+- A number ("2") → act on that option
+- "tell me more about 2" → explain in detail
+- "research option 1" → spawn a research agent for that topic
+- "just do it" → execute the primary recommendation
+- "skip it" → move to the next logical action
+- Any natural language → respond conversationally
+
+Follow the thread naturally. This is a conversation, not a form.

package/framework/skills/qualia-list-phase-assumptions/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: qualia-list-phase-assumptions
+description: "Surface hidden assumptions before phase planning begins — technical approach, implementation order, scope, risks, dependencies. Use this skill whenever the user says 'list assumptions', 'what assumptions', 'phase assumptions', 'before we plan', or wants to explicitly check what they're assuming about a phase before committing to a plan. Also trigger when user mentions 'hidden assumptions', 'what are we taking for granted', or needs a pre-planning sanity check."
+---
+
+# Qualia List Phase Assumptions — Assumption Surfacing
+
+Surface hidden assumptions across 5 areas before phase planning begins. Conversational output only — no files created.
+
+## Usage
+
+`/qualia-list-phase-assumptions 3` — List assumptions for phase 3
+`/qualia-list-phase-assumptions` — Auto-detect next phase to analyze
+
+## Process
+
+### 1. Load Context
+
+Read:
+- `.planning/ROADMAP.md` — Phase description
+- `.planning/PROJECT.md` — Tech stack and constraints
+- `.planning/REQUIREMENTS.md` — Related requirements
+- Phase RESEARCH.md if it exists
+
+Reference: `~/.claude/qualia-engine/workflows/list-phase-assumptions.md`
+
+### 2. Analyze 5 Areas
+
+For each area, identify what's being assumed without being stated:
+
+#### Technical Approach
+- What tech/libraries are we assuming we'll use?
+- Are we assuming a specific architecture pattern?
+- Are we assuming certain APIs or services are available?
+
+#### Implementation Order
+- Are we assuming certain things should be built first?
+- Are we assuming a specific development sequence?
+- Could a different order be more efficient?
+
+#### Scope
+- Are we assuming certain things are in/out of this phase?
+- Are we assuming a level of polish or completeness?
+- Are there edge cases we're assuming we don't need to handle?
+
+#### Risks
+- What could go wrong that we haven't considered?
+- Are we assuming things will "just work"?
+- What if a key assumption turns out to be wrong?
+
+#### Dependencies
+- Are we assuming other phases are complete?
+- Are we assuming access to certain APIs/services/data?
+- Are we assuming team availability or skills?
+
+### 3. Present Findings
+
+Present assumptions conversationally, grouped by area. For each assumption, note:
+- What's being assumed
+- Why it matters if wrong
+- How confident we should be
+
+### 4. Close
+
+End with: "What do you think? Any of these surprise you or seem risky?"
+
+No files are created — this is a conversational exercise to inform planning.

package/framework/skills/qualia-new-milestone/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: qualia-new-milestone
+description: "Start a new milestone on an existing project — brownfield initialization with questioning, optional research, requirements, and roadmap. Use this skill whenever the user says 'new milestone', 'next milestone', 'start v2', 'milestone 2', or wants to begin a new phase of work on a project that already has a .planning directory. Also trigger when user mentions 'next version', 'new feature set', or needs to plan the next iteration of an existing project."
+---
+
+# Qualia New Milestone — Brownfield Milestone Start
+
+Start a new milestone on an existing project. Similar to new-project but preserves existing project context.
+
+## Usage
+
+`/qualia-new-milestone` — Start new milestone interactively
+`/qualia-new-milestone "v2: Add analytics dashboard"` — With initial description
+
+## Prerequisites
+
+Project must already have `.planning/` directory. If not, use `qualia-new-project` instead.
+
+## Process
+
+### 1. Load Existing Context
+
+Read:
+- `.planning/PROJECT.md` — Current project state
+- `.planning/milestones/` — Previous milestone archives (if any)
+- `.planning/STATE.md` — Current state
+
+Reference: `~/.claude/qualia-engine/workflows/new-milestone.md`
+
+### 2. Questioning Phase
+
+Reference: `~/.claude/qualia-engine/references/questioning.md`
+
+Ask targeted questions building on existing project knowledge:
+- What's the goal of this milestone?
+- What new features or improvements?
+- Any tech stack changes or additions?
+- What's the timeline?
+- Lessons from the previous milestone to apply?
+
+### 3. Research (Optional)
+
+If the milestone involves new tech or unfamiliar territory, conduct research.
+Otherwise, skip — the project already has established patterns.
+
+### 4. Create/Update Files
+
+#### Update PROJECT.md
+Add new milestone section to existing PROJECT.md (don't overwrite).
+
+#### Create REQUIREMENTS.md
+Fresh requirements for this milestone:
+Template: `~/.claude/qualia-engine/templates/requirements.md`
+- Milestone definition (v{next_version})
+- Functional requirements
+- Non-functional requirements
+- Definition of Done
+
+#### Create ROADMAP.md
+Fresh roadmap for this milestone's phases. Previous roadmap is archived in milestones/.
+
+#### Update STATE.md
+Reset phase tracking for the new milestone while preserving project-level info.
+
+#### Research (if conducted)
+Save to `.planning/research/` directory.
+
+UI/brand reference: `~/.claude/qualia-engine/references/ui-brand.md`
+
+### 5. Next Step
+
+> "Milestone v{version} initialized with {N} phases. Run `/qualia-plan-phase 1` to start planning."

package/framework/skills/qualia-new-project/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: qualia-new-project
+description: "Initialize a new Qualia workflow project from scratch — questioning, research, requirements, roadmap. Use this skill whenever the user says 'new project', 'start project', 'init project', 'qualia new', or wants to begin a brand new project with the Qualia qualia-engine workflow. Also trigger when user mentions setting up .planning directory, creating a roadmap, or starting fresh on a new client project."
+---
+
+# Qualia New Project — Project Initialization
+
+Initialize a new project with the full Qualia qualia-engine workflow: questioning → research → requirements → roadmap.
+
+## Usage
+
+`/qualia-new-project` — Start new project initialization
+`/qualia-new-project "Build AI chatbot for client X"` — Start with initial description
+
+## Process
+
+### 1. Questioning Phase
+
+Run the questioning workflow to understand the project deeply before any planning.
+
+Reference: `~/.claude/qualia-engine/references/questioning.md`
+
+Ask targeted questions covering:
+- What is the project? Who is it for?
+- What problem does it solve?
+- What are the key features?
+- What tech stack preferences exist?
+- What are the constraints (timeline, budget, existing systems)?
+- What does success look like?
+
+### 2. Research Phase
+
+Based on answers, conduct research on:
+- Similar solutions and competitors
+- Best tech stack choices for the requirements
+- Potential challenges and pitfalls
+- UI/brand considerations per `~/.claude/qualia-engine/references/ui-brand.md`
+
+### 3. Create Project Structure
+
+Create the `.planning/` directory with all required files:
+
+```bash
+mkdir -p .planning/research .planning/phases .planning/quick .planning/debug
+```
+
+#### PROJECT.md
+Template from `~/.claude/qualia-engine/templates/project.md`:
+- Project name, description, client
+- Tech stack decisions
+- Deploy target
+- Key URLs and credentials references
+
+#### config.json
+```json
+{
+  "project": "<name>",
+  "version": "1.0",
+  "deploy": { "platform": "vercel", "domain": "" },
+  "stack": { "framework": "next", "db": "", "auth": "" }
+}
+```
+
+#### REQUIREMENTS.md
+Template from `~/.claude/qualia-engine/templates/requirements.md`:
+- Milestone definition (v1.0)
+- Functional requirements (categorized)
+- Non-functional requirements
+- Definition of Done checklist
+
+#### ROADMAP.md
+- Break requirements into sequential phases
+- Each phase: number, name, description, status, dependencies
+- Phases should be small enough to complete in 1-2 sessions
+
+#### STATE.md
+- Current milestone, current phase
+- Phase status table
+- Quick tasks completed table
+- Session log
+
+### 4. Next Step
+
+After initialization, tell the user:
+> "Project initialized. Next: run `/qualia-plan-phase 1` to plan the first phase."
+
+### Agents Used
+| Agent | File | Role |
+|-------|------|------|
+| `qualia-project-researcher` | `~/.claude/agents/qualia-project-researcher.md` | Domain ecosystem research |
+| `qualia-research-synthesizer` | `~/.claude/agents/qualia-research-synthesizer.md` | Synthesizes parallel research |
+| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md |