qualia-framework 2.5.1 → 3.1.0

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

@@ -1,114 +0,0 @@
----
-name: qualia-help
-description: "Display the complete Qualia command reference — all available skills and their usage. Use this skill whenever the user says 'help', 'qualia help', 'what commands', 'what can you do', 'show commands', or wants to see all available Qualia workflow commands. Also trigger when user seems lost or unsure which command to use next."
----
-
-# Qualia Help — Command Reference
-
-Display the complete reference of all available Qualia workflow skills, organized by situation.
-
-## Usage
-
-`/qualia-help` — Show all commands
-
-## Output
-
-Display the command reference below. Organized in two sections: **Essential** (the commands you actually use) and **Advanced** (everything else).
-
----
-
-```
-◆ QUALIA COMMAND REFERENCE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### ESSENTIAL — The commands you need every day
-
-| Command | What it does |
-|---------|-------------|
-| `/qualia` | **"What do I do next?"** — reads state, tells you the exact next command |
-| `/qualia-new-project` | Start a new project from scratch |
-| `/qualia-plan-phase N` | Plan a phase |
-| `/qualia-execute-phase N` | Build a phase |
-| `/qualia-verify-work N` | Test a phase |
-| `/critique` | Review the design |
-| `/polish` | Fix spacing, alignment, details |
-| `/harden` | Handle edge cases, errors |
-| `/qualia-review --web` | Code quality + security audit |
-| `/pr` | Create a pull request |
-
-### NAVIGATION — When you're lost or stuck
-
-| Command | What it does |
-|---------|-------------|
-| `/qualia-guide` | **New to the framework?** Shows how everything works |
-| `/qualia-idk` | **Stuck?** Analyzes your situation, suggests what to do |
-| `/qualia-progress` | See how far along the project is |
-| `/qualia-debug` | Structured debugging when something is broken |
-
-### SESSION — Starting and ending your day
-
-| Command | What it does |
-|---------|-------------|
-| `/qualia-report` | Log what you did today (Fawzi reviews these) |
-| `/qualia-pause-work` | Save context before ending session |
-| `/qualia-resume-work` | Pick up where you left off |
-
----
-
-<details>
-<summary>ADVANCED — Full command reference (you rarely need these)</summary>
-
-### Planning
-| Command | What it does |
-|---------|-------------|
-| `/qualia-discuss-phase` | Clarify decisions before planning |
-| `/qualia-list-phase-assumptions` | Surface hidden assumptions |
-| `/qualia-research-phase` | Research a topic before planning |
-| `/qualia-quick` | Quick one-off tasks without full workflow |
-
-### Quality & Design
-| Command | What it does |
-|---------|-------------|
-| `/qualia-design` | One-shot design fix (critique + polish + harden + responsive) |
-| `/qualia-optimize` | Find perf, design, and code issues |
-| `/qualia-production-check` | Final audit before client handoff |
-
-### Milestone Lifecycle
-| Command | What it does |
-|---------|-------------|
-| `/qualia-audit-milestone` | Verify all requirements met |
-| `/qualia-complete-milestone` | Archive milestone, tag release |
-| `/qualia-plan-milestone-gaps` | Create fix phases from audit gaps |
-| `/qualia-new-milestone` | Start next milestone on existing project |
-| `/client-handoff` | Generate client delivery document |
-
-### Deploy (Fawzi only)
-| Command | What it does |
-|---------|-------------|
-| `/ship` | Full deploy pipeline with quality gates |
-| `/deploy` | Quick deploy without gates |
-| `/deploy-verify` | Post-deploy verification |
-
-### Specialized Builders
-| Command | What it does |
-|---------|-------------|
-| `/frontend-master` | Premium UI components |
-| `/voice-agent` | Retell AI + ElevenLabs voice agent |
-| `/openrouter-agent` | AI chatbot with OpenRouter |
-| `/mobile-expo` | React Native / Expo mobile app |
-| `/supabase` | Database, auth, edge functions, RLS |
-| `/seo-master` | SEO audit and optimization |
-
-### Notes & Memory
-| Command | What it does |
-|---------|-------------|
-| `/qualia-add-todo` | Capture a task for later |
-| `/qualia-check-todos` | Review pending todos |
-| `/learn` | Save a lesson from a mistake |
-
-</details>
-
----
-
-**Tip:** Most of the time, just describe what you want in plain language. Or type `/qualia` — it always knows what's next.

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

@@ -1,352 +0,0 @@
----
-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

@@ -1,67 +0,0 @@
----
-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-framework/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

@@ -1,72 +0,0 @@
----
-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-framework/workflows/new-milestone.md`
-
-### 2. Questioning Phase
-
-Reference: `~/.claude/qualia-framework/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-framework/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-framework/references/ui-brand.md`
-
-### 5. Next Step
-
-> "Milestone v{version} initialized with {N} phases. Run `/qualia-plan-phase 1` to start planning."