qualia-framework 2.5.1 → 3.1.0

package/framework/qualia-framework/references/decimal-phase-calculation.md

@@ -1,65 +0,0 @@
-# Decimal Phase Calculation
-
-Calculate the next decimal phase number for urgent insertions.
-
-## Using qualia-tools
-
-```bash
-# Get next decimal phase after phase 6
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js phase next-decimal 6
-```
-
-Output:
-```json
-{
-  "found": true,
-  "base_phase": "06",
-  "next": "06.1",
-  "existing": []
-}
-```
-
-With existing decimals:
-```json
-{
-  "found": true,
-  "base_phase": "06",
-  "next": "06.3",
-  "existing": ["06.1", "06.2"]
-}
-```
-
-## Extract Values
-
-```bash
-DECIMAL_INFO=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js phase next-decimal "${AFTER_PHASE}")
-DECIMAL_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.next')
-BASE_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.base_phase')
-```
-
-Or with --raw flag:
-```bash
-DECIMAL_PHASE=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js phase next-decimal "${AFTER_PHASE}" --raw)
-# Returns just: 06.1
-```
-
-## Examples
-
-| Existing Phases | Next Phase |
-|-----------------|------------|
-| 06 only | 06.1 |
-| 06, 06.1 | 06.2 |
-| 06, 06.1, 06.2 | 06.3 |
-| 06, 06.1, 06.3 (gap) | 06.4 |
-
-## Directory Naming
-
-Decimal phase directories use the full decimal number:
-
-```bash
-SLUG=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js generate-slug "$DESCRIPTION" --raw)
-PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
-mkdir -p "$PHASE_DIR"
-```
-
-Example: `.planning/phases/06.1-fix-critical-auth-bug/`

package/framework/qualia-framework/references/design-quality.md

@@ -1,56 +0,0 @@
-<design_quality>
-
-## Design Quality Standards for Frontend Execution
-
-When building frontend components (.tsx, .jsx, .css, .scss, styled-components, Tailwind classes), apply these standards **during implementation**, not as a separate pass.
-
-### Build-Time Standards (apply while coding)
-
-**From `frontend-master` skill:**
-- Distinctive fonts (not Inter/Arial/system defaults)
-- Cohesive color palette with sharp accents
-- Layered backgrounds, subtle gradients
-- Avoid: card grids, generic heroes, blue-purple gradients
-
-**From `/normalize`:**
-- Consistent spacing (8px grid or project's spacing scale)
-- Consistent border-radius, shadow, and color tokens across components
-- Typography hierarchy (h1-h6, body, caption) using project's type scale
-
-**From `/harden`:**
-- Text overflow handling (truncate or wrap, never break layout)
-- Empty states for lists, tables, data displays
-- Loading states for async content
-- Error states with clear recovery actions
-- Long content resilience (test with 2x expected text length)
-
-**From `/animate`:**
-- CSS transitions on interactive elements (buttons, cards, links) — 150-300ms
-- Staggered entrance animations for lists and grids
-- Smooth page/section transitions
-- Purposeful motion that guides attention, not decorative
-
-**From `/clarify`:**
-- Button labels describe actions ("Save changes" not "Submit")
-- Error messages explain what went wrong AND how to fix it
-- Form labels are descriptive, not just field names
-- Placeholder text is example content, not instructions
-
-### Per-Task Checklist (mental, not written)
-
-For each frontend task, before committing ask:
-1. Does it look distinctive or generic?
-2. Are spacing/colors consistent with surrounding components?
-3. What happens with no data? Too much data? An error?
-4. Is the copy clear to a first-time user?
-5. Are interactive elements (hover, focus, active, disabled) styled?
-6. Are CSS transitions present on interactions (150-300ms)?
-
-### Detection
-
-A plan involves frontend work if ANY of these are true:
-- Plan files include `.tsx`, `.jsx`, `.css`, `.scss` in `files_modified`
-- Plan objective mentions: UI, page, component, layout, dashboard, form, modal, navigation, landing
-- Plan tags include: `frontend`, `ui`, `design`, `components`, `pages`
-
-</design_quality>

package/framework/qualia-framework/references/employee-guide.md

@@ -1,167 +0,0 @@
-# How Qualia Works — Developer Guide
-
-> This is everything you need to know. Follow the flow, type the commands. The framework handles the rest.
-
----
-
-## The Big Picture
-
-Every project follows one path:
-
-```
-Start → Build → Polish → Review → PR → Deploy → Handoff
-         70%                    100%
-```
-
-The framework tells you what to do at every step. When in doubt, type `/qualia` — it reads your project state and tells you the exact next command.
-
----
-
-## Starting a Project
-
-You get assigned a project. Here's what you do:
-
-```
-/qualia-new-project          ← answers questions, sets everything up
-```
-
-This creates a `.planning/` folder with your roadmap, requirements, and phases. You don't need to understand the files — the framework reads them for you.
-
----
-
-## The Build Cycle (repeat for each phase)
-
-Your roadmap has phases (Phase 1, Phase 2, etc.). For each one:
-
-```
-/qualia-plan-phase 1         ← creates the plan
-/qualia-execute-phase 1      ← builds it
-/qualia-verify-work 1        ← tests it
-```
-
-Then move to the next phase. The framework tells you when to move on.
-
-**Don't memorize this.** After each command finishes, it tells you what's next. Or type `/qualia` anytime.
-
----
-
-## The Finish Line (this is where most people stall)
-
-When all phases are done, you're about 70% done. The framework now guides you through:
-
-```
-  ✓ Build phases       ← you already did this
-  ✓ Milestone audit    ← framework runs this
-  ✓ Milestone archived ← framework does this
-  ▶ Design polish      ← /critique → /polish → /harden
-  · Code review        ← /qualia-review --web
-  · Pull request       ← /pr
-  · Deploy             ← Fawzi handles this
-  · Client handoff     ← /client-handoff
-```
-
-The framework walks you through each step. Just keep typing `/qualia` to see what's next.
-
----
-
-## The 10 Commands That Matter
-
-| When | Command | What it does |
-|------|---------|-------------|
-| **Starting** | `/qualia-new-project` | Sets up everything from scratch |
-| **Building** | `/qualia-plan-phase N` | Plans a phase |
-| | `/qualia-execute-phase N` | Builds it |
-| | `/qualia-verify-work N` | Tests it |
-| **Polishing** | `/critique` | Reviews the design |
-| | `/polish` | Fixes spacing, alignment, details |
-| | `/harden` | Handles edge cases, errors, overflow |
-| **Shipping** | `/qualia-review --web` | Code quality + security audit |
-| | `/pr` | Creates a pull request |
-| **Anytime** | `/qualia` | "What should I do next?" |
-
-Everything else is optional. These 10 get the job done.
-
----
-
-## When You're Stuck
-
-```
-/qualia           ← "what's next?" — reads state, tells you the command
-/qualia-idk       ← "I'm lost" — analyzes everything, suggests a path
-/qualia-debug     ← "something is broken" — structured debugging
-/qualia-progress  ← "where am I?" — full progress report
-```
-
-If none of those help, paste the error and ask Claude directly. If Claude can't fix it, escalate to Fawzi.
-
----
-
-## Session Start / End
-
-**Every session starts the same way.** Claude automatically runs `/qualia-start` which shows you:
-- What project you're in
-- What branch you're on
-- System health
-- What to do next
-
-**When you're done for the day:**
-```
-/qualia-pause-work    ← saves your context for next time
-/qualia-report        ← logs what you did (Fawzi reviews these)
-```
-
-**When you come back:**
-```
-/qualia-resume-work   ← picks up where you left off
-```
-
----
-
-## Rules (non-negotiable)
-
-1. **Feature branches only** — never push to main. The framework blocks it automatically.
-2. **Read before write** — don't edit files you haven't read.
-3. **MVP first** — build what's asked, nothing extra.
-4. **Push to GitHub** — you push code. Fawzi deploys to production.
-5. **`/qualia` is your friend** — lost? type it. It always knows what's next.
-
----
-
-## What the Framework Does Behind the Scenes
-
-You don't need to understand this, but if you're curious:
-
-- **Hooks** run automatically on certain actions (commits, deploys, file writes). They enforce rules like "no pushing to main" and "no editing .env files." If a hook blocks you, it tells you why and how to fix it.
-- **Skills** are the `/commands` you type. They're like recipes — each one does a specific thing.
-- **Agents** are AI workers that skills spawn to do heavy lifting (research, verification, code review). You don't interact with them directly.
-- **`.planning/`** is where the framework tracks everything about your project. Don't edit these files manually — the framework manages them.
-
----
-
-## Quick Reference Card
-
-```
-◆ QUALIA DEVELOPER FLOW
-
-  /qualia-new-project
-       ↓
-  For each phase:
-    /qualia-plan-phase N
-    /qualia-execute-phase N
-    /qualia-verify-work N
-       ↓
-  /qualia-complete-milestone
-       ↓
-  FINISH LINE:
-    /critique → /polish → /harden
-    /qualia-review --web
-    /pr
-       ↓
-  Fawzi deploys
-       ↓
-  /client-handoff
-       ↓
-  Done.
-
-  Lost? Type /qualia
-```

package/framework/qualia-framework/references/git-integration.md

@@ -1,254 +0,0 @@
-<overview>
-Git integration for Qualia framework.
-</overview>
-
-<core_principle>
-
-**Commit outcomes, not process.**
-
-The git log should read like a changelog of what shipped, not a diary of planning activity.
-</core_principle>
-
-<commit_points>
-
-| Event                   | Commit? | Why                                              |
-| ----------------------- | ------- | ------------------------------------------------ |
-| BRIEF + ROADMAP created | YES     | Project initialization                           |
-| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
-| RESEARCH.md created     | NO      | Intermediate                                     |
-| DISCOVERY.md created    | NO      | Intermediate                                     |
-| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
-| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
-| Handoff created         | YES     | WIP state preserved                              |
-
-</commit_points>
-
-<git_check>
-
-```bash
-[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
-```
-
-If NO_GIT: Run `git init` silently. Qualia projects always get their own repo.
-</git_check>
-
-<commit_formats>
-
-<format name="initialization">
-## Project Initialization (brief + roadmap together)
-
-```
-docs: initialize [project-name] ([N] phases)
-
-[One-liner from PROJECT.md]
-
-Phases:
-1. [phase-name]: [goal]
-2. [phase-name]: [goal]
-3. [phase-name]: [goal]
-```
-
-What to commit:
-
-```bash
-git add .planning/
-git commit
-```
-
-</format>
-
-<format name="task-completion">
-## Task Completion (During Plan Execution)
-
-Each task gets its own commit immediately after completion.
-
-```
-{type}({phase}-{plan}): {task-name}
-
-- [Key change 1]
-- [Key change 2]
-- [Key change 3]
-```
-
-**Commit types:**
-- `feat` - New feature/functionality
-- `fix` - Bug fix
-- `test` - Test-only (TDD RED phase)
-- `refactor` - Code cleanup (TDD REFACTOR phase)
-- `perf` - Performance improvement
-- `chore` - Dependencies, config, tooling
-
-**Examples:**
-
-```bash
-# Standard task
-git add src/api/auth.ts src/types/user.ts
-git commit -m "feat(08-02): create user registration endpoint
-
-- POST /auth/register validates email and password
-- Checks for duplicate users
-- Returns JWT token on success
-"
-
-# TDD task - RED phase
-git add src/__tests__/jwt.test.ts
-git commit -m "test(07-02): add failing test for JWT generation
-
-- Tests token contains user ID claim
-- Tests token expires in 1 hour
-- Tests signature verification
-"
-
-# TDD task - GREEN phase
-git add src/utils/jwt.ts
-git commit -m "feat(07-02): implement JWT generation
-
-- Uses jose library for signing
-- Includes user ID and expiry claims
-- Signs with HS256 algorithm
-"
-```
-
-</format>
-
-<format name="plan-completion">
-## Plan Completion (After All Tasks Done)
-
-After all tasks committed, one final metadata commit captures plan completion.
-
-```
-docs({phase}-{plan}): complete [plan-name] plan
-
-Tasks completed: [N]/[N]
-- [Task 1 name]
-- [Task 2 name]
-- [Task 3 name]
-
-SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
-```
-
-What to commit:
-
-```bash
-git add .planning/phases/XX-name/{phase}-{plan}-PLAN.md
-git add .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
-git add .planning/STATE.md
-git add .planning/ROADMAP.md
-git commit
-```
-
-**Note:** Code files NOT included - already committed per-task.
-
-</format>
-
-<format name="handoff">
-## Handoff (WIP)
-
-```
-wip: [phase-name] paused at task [X]/[Y]
-
-Current: [task name]
-[If blocked:] Blocked: [reason]
-```
-
-What to commit:
-
-```bash
-git add .planning/
-git commit
-```
-
-</format>
-</commit_formats>
-
-<example_log>
-
-**Old approach (per-plan commits):**
-```
-a7f2d1 feat(checkout): Stripe payments with webhook verification
-3e9c4b feat(products): catalog with search, filters, and pagination
-8a1b2c feat(auth): JWT with refresh rotation using jose
-5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
-2f4a8d docs: initialize ecommerce-app (5 phases)
-```
-
-**New approach (per-task commits):**
-```
-# Phase 04 - Checkout
-1a2b3c docs(04-01): complete checkout flow plan
-4d5e6f feat(04-01): add webhook signature verification
-7g8h9i feat(04-01): implement payment session creation
-0j1k2l feat(04-01): create checkout page component
-
-# Phase 03 - Products
-3m4n5o docs(03-02): complete product listing plan
-6p7q8r feat(03-02): add pagination controls
-9s0t1u feat(03-02): implement search and filters
-2v3w4x feat(03-01): create product catalog schema
-
-# Phase 02 - Auth
-5y6z7a docs(02-02): complete token refresh plan
-8b9c0d feat(02-02): implement refresh token rotation
-1e2f3g test(02-02): add failing test for token refresh
-4h5i6j docs(02-01): complete JWT setup plan
-7k8l9m feat(02-01): add JWT generation and validation
-0n1o2p chore(02-01): install jose library
-
-# Phase 01 - Foundation
-3q4r5s docs(01-01): complete scaffold plan
-6t7u8v feat(01-01): configure Tailwind and globals
-9w0x1y feat(01-01): set up Prisma with database
-2z3a4b feat(01-01): create Next.js 15 project
-
-# Initialization
-5c6d7e docs: initialize ecommerce-app (5 phases)
-```
-
-Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
-
-</example_log>
-
-<anti_patterns>
-
-**Still don't commit (intermediate artifacts):**
-- PLAN.md creation (commit with plan completion)
-- RESEARCH.md (intermediate)
-- DISCOVERY.md (intermediate)
-- Minor planning tweaks
-- "Fixed typo in roadmap"
-
-**Do commit (outcomes):**
-- Each task completion (feat/fix/test/refactor)
-- Plan completion metadata (docs)
-- Project initialization (docs)
-
-**Key principle:** Commit working code and shipped outcomes, not planning process.
-
-</anti_patterns>
-
-<commit_strategy_rationale>
-
-## Why Per-Task Commits?
-
-**Context engineering for AI:**
-- Git history becomes primary context source for future Claude sessions
-- `git log --grep="{phase}-{plan}"` shows all work for a plan
-- `git diff <hash>^..<hash>` shows exact changes per task
-- Less reliance on parsing SUMMARY.md = more context for actual work
-
-**Failure recovery:**
-- Task 1 committed ✅, Task 2 failed ❌
-- Claude in next session: sees task 1 complete, can retry task 2
-- Can `git reset --hard` to last successful task
-
-**Debugging:**
-- `git bisect` finds exact failing task, not just failing plan
-- `git blame` traces line to specific task context
-- Each commit is independently revertable
-
-**Observability:**
-- Solo developer + Claude workflow benefits from granular attribution
-- Atomic commits are git best practice
-- "Commit noise" irrelevant when consumer is Claude, not humans
-
-</commit_strategy_rationale>

package/framework/qualia-framework/references/git-planning-commit.md

@@ -1,50 +0,0 @@
-# Git Planning Commit
-
-Check whether to commit planning artifacts, then commit if enabled.
-
-## Check Configuration
-
-```bash
-# Check config.json first
-COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
-
-# Auto-detect gitignored (overrides config)
-git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
-```
-
-Default: `true` if not set or config missing.
-
-## Conditional Commit
-
-Only run git operations if `COMMIT_PLANNING_DOCS=true`:
-
-```bash
-if [ "$COMMIT_PLANNING_DOCS" = "true" ]; then
-  git add .planning/STATE.md .planning/ROADMAP.md
-  git commit -m "$(cat <<'EOF'
-docs({scope}): {description}
-
-{optional body}
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-EOF
-)"
-fi
-```
-
-## Commit Message Patterns
-
-| Command | Scope | Example |
-|---------|-------|---------|
-| plan-phase | phase | `docs(phase-03): create authentication plans` |
-| execute-phase | phase | `docs(phase-03): complete authentication phase` |
-| new-milestone | milestone | `docs: start milestone v1.1` |
-| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
-
-## When to Skip
-
-- `commit_docs: false` in config
-- `.planning/` is gitignored
-- No changes to commit (check with `git status --porcelain .planning/`)

package/framework/qualia-framework/references/model-profile-resolution.md

@@ -1,32 +0,0 @@
-# Model Profile Resolution
-
-Resolve model profile once at the start of orchestration, then use it for all Task spawns.
-
-## Resolution Pattern
-
-```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
-```
-
-Default: `balanced` if not set or config missing.
-
-## Lookup Table
-
-@/home/qualia/.claude/qualia-framework/references/model-profiles.md
-
-Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
-
-```
-Task(
-  prompt="...",
-  subagent_type="qualia-planner",
-  model="{resolved_model}"  # e.g., "opus" for quality profile
-)
-```
-
-## Usage
-
-1. Resolve once at orchestration start
-2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call

package/framework/qualia-framework/references/model-profiles.md

@@ -1,73 +0,0 @@
-# Model Profiles
-
-Model profiles control which Claude model each Qualia agent uses. This allows balancing quality vs token spend.
-
-## Profile Definitions
-
-| Agent | `quality` | `balanced` | `budget` |
-|-------|-----------|------------|----------|
-| qualia-planner | opus | opus | sonnet |
-| qualia-roadmapper | opus | sonnet | sonnet |
-| qualia-executor | opus | sonnet | sonnet |
-| qualia-phase-researcher | opus | sonnet | haiku |
-| qualia-project-researcher | opus | sonnet | haiku |
-| qualia-research-synthesizer | sonnet | sonnet | haiku |
-| qualia-debugger | opus | sonnet | sonnet |
-| qualia-codebase-mapper | sonnet | haiku | haiku |
-| qualia-verifier | sonnet | sonnet | haiku |
-| qualia-plan-checker | sonnet | sonnet | haiku |
-| qualia-integration-checker | sonnet | sonnet | haiku |
-
-## Profile Philosophy
-
-**quality** - Maximum reasoning power
-- Opus for all decision-making agents
-- Sonnet for read-only verification
-- Use when: quota available, critical architecture work
-
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
-- Use when: normal development, good balance of quality and cost
-
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
-- Use when: conserving quota, high-volume work, less critical phases
-
-## Resolution Logic
-
-Orchestrators resolve model before spawning:
-
-```
-1. Read .planning/config.json
-2. Get model_profile (default: "balanced")
-3. Look up agent in table above
-4. Pass model parameter to Task call
-```
-
-## Switching Profiles
-
-Runtime: `/qualia:set-profile <profile>`
-
-Per-project default: Set in `.planning/config.json`:
-```json
-{
-  "model_profile": "balanced"
-}
-```
-
-## Design Rationale
-
-**Why Opus for qualia-planner?**
-Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
-
-**Why Sonnet for qualia-executor?**
-Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
-
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
-
-**Why Haiku for qualia-codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.