qualia-framework 2.6.0 → 3.1.0

package/framework/skills/polish/SKILL.md

@@ -1,209 +0,0 @@
----
-name: polish
-description: Final quality pass before shipping. Fixes alignment, spacing, consistency, and detail issues that separate good from great.
-user-invokable: true
-args:
-  - name: target
-    description: The feature or area to polish (optional)
-    required: false
----
-
-**First**: Use the frontend-master skill for design principles and anti-patterns.
-
-**Then**: Read the project's design decisions:
-
-```bash
-cat .planning/DESIGN.md 2>/dev/null
-```
-
-If DESIGN.md exists, use it as the authoritative source for this project's design tokens, spacing, and typography. Verify consistency against DESIGN.md decisions during polish (e.g., "DESIGN.md specifies 8px grid — this 13px gap violates the system"). If DESIGN.md does not exist, proceed with general design principles from frontend-master.
-
-Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
-
-## Pre-Polish Assessment
-
-Understand the current state and goals:
-
-1. **Review completeness**:
-   - Is it functionally complete?
-   - Are there known issues to preserve (mark with TODOs)?
-   - What's the quality bar? (MVP vs flagship feature?)
-   - When does it ship? (How much time for polish?)
-
-2. **Identify polish areas**:
-   - Visual inconsistencies
-   - Spacing and alignment issues
-   - Interaction state gaps
-   - Copy inconsistencies
-   - Edge cases and error states
-   - Loading and transition smoothness
-
-**CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
-
-## Polish Systematically
-
-Work through these dimensions methodically:
-
-### Visual Alignment & Spacing
-
-- **Pixel-perfect alignment**: Everything lines up to grid
-- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)
-- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)
-- **Responsive consistency**: Spacing and alignment work at all breakpoints
-- **Grid adherence**: Elements snap to baseline grid
-
-**Check**:
-- Enable grid overlay and verify alignment
-- Check spacing with browser inspector
-- Test at multiple viewport sizes
-- Look for elements that "feel" off
-
-### Typography Refinement
-
-- **Hierarchy consistency**: Same elements use same sizes/weights throughout
-- **Line length**: 45-75 characters for body text
-- **Line height**: Appropriate for font size and context
-- **Widows & orphans**: No single words on last line
-- **Hyphenation**: Appropriate for language and column width
-- **Kerning**: Adjust letter spacing where needed (especially headlines)
-- **Font loading**: No FOUT/FOIT flashes
-
-### Color & Contrast
-
-- **Contrast ratios**: All text meets WCAG standards
-- **Consistent token usage**: No hard-coded colors, all use design tokens
-- **Theme consistency**: Works in all theme variants
-- **Color meaning**: Same colors mean same things throughout
-- **Accessible focus**: Focus indicators visible with sufficient contrast
-- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)
-- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency
-
-### Interaction States
-
-Every interactive element needs all states:
-
-- **Default**: Resting state
-- **Hover**: Subtle feedback (color, scale, shadow)
-- **Focus**: Keyboard focus indicator (never remove without replacement)
-- **Active**: Click/tap feedback
-- **Disabled**: Clearly non-interactive
-- **Loading**: Async action feedback
-- **Error**: Validation or error state
-- **Success**: Successful completion
-
-**Missing states create confusion and broken experiences**.
-
-### Micro-interactions & Transitions
-
-- **Smooth transitions**: All state changes animated appropriately (150-300ms)
-- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
-- **No jank**: 60fps animations, only animate transform and opacity
-- **Appropriate motion**: Motion serves purpose, not decoration
-- **Reduced motion**: Respects `prefers-reduced-motion`
-
-### Content & Copy
-
-- **Consistent terminology**: Same things called same names throughout
-- **Consistent capitalization**: Title Case vs Sentence case applied consistently
-- **Grammar & spelling**: No typos
-- **Appropriate length**: Not too wordy, not too terse
-- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
-
-### Icons & Images
-
-- **Consistent style**: All icons from same family or matching style
-- **Appropriate sizing**: Icons sized consistently for context
-- **Proper alignment**: Icons align with adjacent text optically
-- **Alt text**: All images have descriptive alt text
-- **Loading states**: Images don't cause layout shift, proper aspect ratios
-- **Retina support**: 2x assets for high-DPI screens
-
-### Forms & Inputs
-
-- **Label consistency**: All inputs properly labeled
-- **Required indicators**: Clear and consistent
-- **Error messages**: Helpful and consistent
-- **Tab order**: Logical keyboard navigation
-- **Auto-focus**: Appropriate (don't overuse)
-- **Validation timing**: Consistent (on blur vs on submit)
-
-### Edge Cases & Error States
-
-- **Loading states**: All async actions have loading feedback
-- **Empty states**: Helpful empty states, not just blank space
-- **Error states**: Clear error messages with recovery paths
-- **Success states**: Confirmation of successful actions
-- **Long content**: Handles very long names, descriptions, etc.
-- **No content**: Handles missing data gracefully
-- **Offline**: Appropriate offline handling (if applicable)
-
-### Responsiveness
-
-- **All breakpoints**: Test mobile, tablet, desktop
-- **Touch targets**: 44x44px minimum on touch devices
-- **Readable text**: No text smaller than 14px on mobile
-- **No horizontal scroll**: Content fits viewport
-- **Appropriate reflow**: Content adapts logically
-
-### Performance
-
-- **Fast initial load**: Optimize critical path
-- **No layout shift**: Elements don't jump after load (CLS)
-- **Smooth interactions**: No lag or jank
-- **Optimized images**: Appropriate formats and sizes
-- **Lazy loading**: Off-screen content loads lazily
-
-### Code Quality
-
-- **Remove console logs**: No debug logging in production
-- **Remove commented code**: Clean up dead code
-- **Remove unused imports**: Clean up unused dependencies
-- **Consistent naming**: Variables and functions follow conventions
-- **Type safety**: No TypeScript `any` or ignored errors
-- **Accessibility**: Proper ARIA labels and semantic HTML
-
-## Polish Checklist
-
-Go through systematically:
-
-- [ ] Visual alignment perfect at all breakpoints
-- [ ] Spacing uses design tokens consistently
-- [ ] Typography hierarchy consistent
-- [ ] All interactive states implemented
-- [ ] All transitions smooth (60fps)
-- [ ] Copy is consistent and polished
-- [ ] Icons are consistent and properly sized
-- [ ] All forms properly labeled and validated
-- [ ] Error states are helpful
-- [ ] Loading states are clear
-- [ ] Empty states are welcoming
-- [ ] Touch targets are 44x44px minimum
-- [ ] Contrast ratios meet WCAG AA
-- [ ] Keyboard navigation works
-- [ ] Focus indicators visible
-- [ ] No console errors or warnings
-- [ ] No layout shift on load
-- [ ] Works in all supported browsers
-- [ ] Respects reduced motion preference
-- [ ] Code is clean (no TODOs, console.logs, commented code)
-
-**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
-
-**NEVER**:
-- Polish before it's functionally complete
-- Spend hours on polish if it ships in 30 minutes (triage)
-- Introduce bugs while polishing (test thoroughly)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
-- Perfect one thing while leaving others rough (consistent quality level)
-
-## Final Verification
-
-Before marking as done:
-
-- **Use it yourself**: Actually interact with the feature
-- **Test on real devices**: Not just browser DevTools
-- **Ask someone else to review**: Fresh eyes catch things
-- **Compare to design**: Match intended design
-- **Check all states**: Don't just test happy path
-
-Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.

package/framework/skills/pr/SKILL.md

@@ -1,66 +0,0 @@
----
-name: pr
-description: "Create a GitHub Pull Request with auto-generated title and description from current branch changes. Use this skill whenever the user mentions PR, pull request, wants to submit code for review, or says things like 'open a PR', 'create PR', 'submit for review', 'push and PR', or 'quick-pr'. Also trigger when user has finished work on a branch and wants to share it."
----
-
-# Quick PR — Auto-Generate Pull Requests
-
-Create a GitHub Pull Request for the current branch with an intelligently generated title and description based on actual code changes.
-
-## Process
-
-### 1. Analyze Changes
-
-Gather all the context needed to write a good PR description:
-
-```bash
-git status
-git diff main...HEAD
-git log main..HEAD --oneline
-```
-
-If the base branch isn't `main`, check for `master` or ask the user.
-
-### 2. Generate PR Content
-
-From the diff and commit history, produce:
-
-- **Title**: Clear, imperative mood, under 72 chars (e.g., "Add user authentication with JWT tokens")
-- **Summary**: What this PR does and why — 1-3 sentences
-- **Key changes**: Bullet list of the most important modifications
-- **Breaking changes**: Flag anything that could break existing functionality
-- **Migration notes**: If schema, config, or API changes need action
-
-### 3. Create the PR
-
-```bash
-gh pr create --title "title" --body "$(cat <<'EOF'
-## Summary
-[What this PR does and why]
-
-## Changes
-- [Key change 1]
-- [Key change 2]
-
-## Testing
-- [ ] Tested locally
-- [ ] Tests pass
-
-## Notes
-[Any additional context, breaking changes, migration needs]
-EOF
-)"
-```
-
-### 4. Return the PR URL
-
-After creation, display the PR URL so the user can share it or continue working.
-
-## Arguments
-
-If the user provides arguments (e.g., a target branch, reviewers, labels), incorporate them into the `gh pr create` command:
-
-- `--base <branch>` for target branch
-- `--reviewer <user>` for reviewers
-- `--label <label>` for labels
-- `--draft` for draft PRs

package/framework/skills/qualia/SKILL.md

@@ -1,199 +0,0 @@
----
-name: qualia
-description: "Mechanical state router — reads STATE.md and tells you the exact next command to run. No analysis, no advice, just routing. Use this skill whenever the user says 'qualia', 'next', 'route me', or wants to know the immediate next command without context. For advice when stuck, use /qualia-idk instead. For progress overview, use /qualia-progress."
-tags: [qualia, workflow, auto-route]
----
-
-# Qualia Smart Router
-
-Single entry point that reads project state and routes to the appropriate Qualia action.
-
-## How It Works
-
-1. Detect if we're in a Qualia project (has .planning/)
-2. Read STATE.md to find current position
-3. Analyze what's needed next
-4. Route to the correct /qualia: command OR execute directly
-
-## Execution
-
-### Step 1: Detect Project State
-
-```bash
-# Check if .planning exists
-if [ ! -d ".planning" ]; then
-  echo "NO_PROJECT"
-  exit 0
-fi
-
-# Check for STATE.md
-if [ -f ".planning/STATE.md" ]; then
-  cat .planning/STATE.md
-fi
-
-# Check for ROADMAP.md
-if [ -f ".planning/ROADMAP.md" ]; then
-  cat .planning/ROADMAP.md
-fi
-
-# List phase directories
-ls -la .planning/phases/ 2>/dev/null || echo "NO_PHASES"
-```
-
-### Step 2: Parse Current Position
-
-From STATE.md, extract:
-- `current_phase`: Which phase number we're on
-- `phase_status`: planning | executing | verifying | complete
-- `blockers`: Any blockers or decisions needed
-
-From ROADMAP.md, extract:
-- Total phases
-- Which phases are complete
-- Next phase info
-
-### Step 3: Route Decision Tree
-
-```
-NO .planning/ directory?
-  → "No Qualia project. Run /qualia-new-project to initialize."
-
-Has .planning/ but no STATE.md?
-  → "Project initialized but no state. Run /qualia-progress to diagnose."
-
-STATE.md exists:
-
-  phase_status = "needs_discussion"?
-    → Route to: /qualia-discuss-phase {current_phase}
-
-  phase_status = "discussed" or "needs_planning"?
-    → Route to: /qualia-plan-phase {current_phase}
-
-  phase_status = "planned" or "needs_execution"?
-    → Route to: /qualia-execute-phase {current_phase}
-
-  phase_status = "executed" or "needs_verification"?
-    → Route to: /qualia-verify-work {current_phase}
-
-  phase_status = "verified" or "complete"?
-    → Check if more phases exist in ROADMAP.md
-    → If yes: increment phase, route to plan
-      "Phase {N} done! Next: Phase {N+1} — {name}. Run /qualia-plan-phase {N+1}"
-    → If no phases remain AND no milestone audit exists:
-      "All phases complete! Run /qualia-audit-milestone to verify the milestone."
-    → If no phases remain AND audit exists AND passed:
-      "Milestone audit passed! Run /qualia-complete-milestone to archive and tag."
-
-    ─── FINISH LINE (post-milestone, 70% → 100%) ───
-
-    → If milestone is completed AND no finish_line in STATE.md:
-      Set finish_line: "needs_polish" in STATE.md.
-      "Milestone archived! Now let's get this client-ready."
-      "Features are ~70% of a project. Time for the finish line."
-      Route to: /critique (then /polish, then /harden)
-
-    → If finish_line = "needs_polish":
-      "Run /critique to review the design, then /polish and /harden."
-      (Skip this step if project has no frontend — set finish_line to "needs_review")
-
-    → If finish_line = "needs_review":
-      "Design polished. Now run /qualia-review --web to audit code quality and security."
-
-    → If finish_line = "needs_pr":
-      "Review passed. Push your branch and create a PR:"
-      "Run /pr to create a pull request for Fawzi to review."
-
-    → If finish_line = "ready_for_deploy":
-      "PR created! Fawzi will review and deploy to production."
-      "Once deployed, run /client-handoff to prepare the delivery document."
-
-    → If finish_line = "deployed":
-      "Run /client-handoff to prepare the client delivery document."
-
-  blockers exist?
-    → Show blockers, ask user how to proceed
-```
-
-### Step 4: Execute or Prompt
-
-**If clear next action:**
-Invoke the appropriate skill directly using:
-```
-Skill(skill="qualia-{action}", args="{phase_number}")
-```
-
-**If ambiguous:**
-Present options to user:
-```
-Current: Phase {N} - {status}
-
-Options:
-1. Continue with {recommended_action}
-2. Check progress (/qualia-progress)
-3. Quick task (/qualia-quick)
-```
-
-## Output Format
-
-**During phases (building features):**
-```
-◆ Qualia Status
-
-  Project   {name}
-  Phase     {N} of {total} — {phase_name}
-  Status    {status_description}
-
-  Next → /qualia-{action} {phase}
-```
-
-**During finish line (70% → 100%):**
-```
-◆ Qualia Status
-
-  Project   {name}
-  Phases    {total}/{total} complete
-  Stage     FINISH LINE — {step_name}
-
-  ── Progress to Client-Ready ──────────
-  ✓ Build phases       complete
-  ✓ Milestone audit    passed
-  ✓ Milestone archived
-  ▶ Design polish      ← you are here
-  · Code review
-  · Pull request
-  · Deploy (Fawzi)
-  · Client handoff
-
-  Next → /critique
-```
-
-## Status Markers
-
-- `✓` — Done
-- `▶` — Current step (you are here)
-- `·` — Not yet
-- `✗` — Failed / blocked
-
-## Quick Actions
-
-If user provides argument:
-
-- `/qualia plan` → Route to /qualia-plan-phase for current phase
-- `/qualia exec` → Route to /qualia-execute-phase for current phase
-- `/qualia verify` → Route to /qualia-verify-work for current phase
-- `/qualia next` → Move to next phase
-- `/qualia quick {description}` → Pass to /qualia-quick
-- `/qualia optimize` → Route to /qualia-optimize (full optimization pass)
-- `/qualia idk` → Route to /qualia-idk (what should I do next?)
-
-## No Project Fallback
-
-If no .planning/ exists:
-
-```
-No Qualia project detected in current directory.
-
-Options:
-1. /qualia-new-project - Initialize new project with full workflow
-2. /qualia-quick - Run a quick task without project setup
-```

package/framework/skills/qualia-add-todo/SKILL.md

@@ -1,68 +0,0 @@
----
-name: qualia-add-todo
-description: "Capture ideas and tasks as structured todos in the .planning system. Use this skill whenever the user says 'add todo', 'remember this', 'note this down', 'add task', 'todo', or wants to capture an idea or task for later without acting on it now. Also trigger when user mentions 'backlog item', 'future task', or needs to save something for later in a structured way."
----
-
-# Qualia Add Todo — Structured Task Capture
-
-Capture ideas and tasks as structured todo files in the `.planning/todos/` directory.
-
-## Usage
-
-`/qualia-add-todo "Add dark mode support"` — Capture a new todo
-`/qualia-add-todo "Optimize image loading" --area=performance` — With explicit area
-
-## Process
-
-### 1. Setup
-
-Ensure the todos directory exists:
-```bash
-mkdir -p .planning/todos
-```
-
-Reference: `~/.claude/qualia-framework/workflows/add-todo.md`
-
-### 2. Extract Content
-
-Parse the user's input to determine:
-- **Title** — Short description of the task
-- **Details** — Any additional context provided
-- **Area** — Infer from content if not specified (e.g., "dark mode" → `ui`, "API rate limiting" → `backend`, "fix typo" → `content`)
-
-### 3. Check for Duplicates
-
-Scan existing todos in `.planning/todos/` for similar items. If a near-duplicate exists, tell the user and ask if they want to update the existing one or create a new one.
-
-### 4. Create Todo File
-
-Write to `.planning/todos/{slug}.md`:
-
-```markdown
----
-title: "{title}"
-area: "{area}"
-priority: normal
-status: pending
-created: {YYYY-MM-DD}
----
-
-# {title}
-
-{details and context}
-```
-
-### 5. Update STATE.md
-
-Add entry to the todos section of `.planning/STATE.md` (create section if it doesn't exist).
-
-### 6. Commit
-
-```bash
-git add .planning/todos/{slug}.md .planning/STATE.md
-git commit -m "todo: add {title}"
-```
-
-### 7. Confirm
-
-> "Todo captured: {title}. Run `/qualia-check-todos` to review your backlog."

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

@@ -1,95 +0,0 @@
----
-name: qualia-audit-milestone
-description: "Verify milestone definition of done — aggregate verification results, check tech debt, run integration tests. Use this skill whenever the user says 'audit milestone', 'check milestone', 'milestone review', 'are we done', or wants to verify that all phases of a milestone meet the definition of done before completing it. Also trigger when user mentions 'milestone audit', 'definition of done check', or needs to validate overall milestone readiness."
----
-
-# Qualia Audit Milestone — Milestone Verification
-
-Orchestrate a full audit of the current milestone to verify all requirements are met before completion.
-
-## Usage
-
-`/qualia-audit-milestone` — Audit current milestone
-
-## Process
-
-### 1. Load Context
-
-Read all project files:
-- `.planning/PROJECT.md`
-- `.planning/REQUIREMENTS.md` — Definition of Done
-- `.planning/ROADMAP.md` — All phases
-- `.planning/config.json`
-
-Reference: `~/.claude/qualia-framework/workflows/audit-milestone.md`
-
-### 2. Read Verification Results
-
-For each completed phase, read its VERIFICATION.md or UAT.md files. Aggregate results:
-- How many phases verified passing
-- How many have outstanding issues
-- What gaps remain
-
-### 3. Check Requirements
-
-Walk through every item in REQUIREMENTS.md Definition of Done:
-- Is each requirement addressed by a completed phase?
-- Is each requirement verified as working?
-- Flag any unmet requirements
-
-### 4. Tech Debt Aggregation
-
-Scan phase summaries and verification files for noted tech debt, workarounds, or deferred items. Compile a tech debt list.
-
-### 5. Shipping Checklist Audit
-
-Run the full shipping checklist from `~/.claude/qualia-framework/references/completion-checklists.md` as part of the audit.
-
-Detect project type from `.planning/PROJECT.md` and load the matching checklist:
-- **website** → "Website-Specific Checklist" + "Universal Checklist"
-- **agent** → "AI Agent Checklist" + "Universal Checklist"
-- **voice** → "Voice Agent Checklist" + "Universal Checklist"
-- **mobile** → "Mobile App Checklist" + "Universal Checklist"
-- **platform** → "Platform with LLM Checklist" + "Universal Checklist"
-
-For every checklist item, run automated verification where possible. Include a "Shipping Checklist" section in the audit report with PASS/WARN/FAIL per item. FAIL items contribute to the overall PASS/FAIL decision.
-
-### 6. Integration Check
-
-Spawn an integration checker to verify cross-phase functionality:
-- Do features from different phases work together?
-- Are there any conflicts or regressions?
-- End-to-end user flows work?
-
-### 7. Produce Audit Report
-
-Write `v{version}-MILESTONE-AUDIT.md`:
-
-```markdown
-# Milestone v{version} Audit
-
-## Requirements Status
-| Requirement | Phase | Verified | Status |
-|------------|-------|----------|--------|
-| ... | ... | ... | ✅/❌ |
-
-## Gaps
-- List of unmet requirements or failing tests
-
-## Tech Debt
-- Items deferred during implementation
-
-## Integration Results
-- Cross-phase test outcomes
-
-## Overall: PASS / FAIL
-```
-
-### 8. Route
-
-**If PASS**: "Milestone audit passed. Run `/qualia-complete-milestone` to archive and tag."
-
-**If FAIL**: "Audit found gaps. Run `/qualia-plan-milestone-gaps` to create fix phases."
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-check-todos/SKILL.md

@@ -1,55 +0,0 @@
----
-name: qualia-check-todos
-description: "List and manage pending todos with filtering and interactive routing. Use this skill whenever the user says 'check todos', 'show todos', 'what todos', 'backlog', 'pending tasks', or wants to review their captured todo items. Also trigger when user mentions 'todo list', 'what's in the backlog', or needs to pick a todo to work on."
----
-
-# Qualia Check Todos — Todo Review & Routing
-
-List pending todos with area filtering, interactive selection, and action routing.
-
-## Usage
-
-`/qualia-check-todos` — Show all pending todos
-`/qualia-check-todos --area=ui` — Filter by area
-`/qualia-check-todos --priority=high` — Filter by priority
-
-## Process
-
-### 1. Load Todos
-
-Read all files in `.planning/todos/`. Parse frontmatter for status, area, priority, created date.
-
-Also read `.planning/STATE.md` and `.planning/ROADMAP.md` for project context.
-
-Reference: `~/.claude/qualia-framework/workflows/check-todos.md`
-
-### 2. Display List
-
-Show todos grouped by area, sorted by priority then date:
-
-```
-## UI (3 pending)
-1. Add dark mode support [normal] — 2026-03-10
-2. Improve mobile nav [high] — 2026-03-08
-3. Loading skeleton screens [low] — 2026-03-12
-
-## Backend (1 pending)
-4. API rate limiting [high] — 2026-03-09
-```
-
-Apply filters if specified.
-
-### 3. Interactive Selection
-
-Ask the user which todo they want to act on (by number).
-
-### 4. Route to Action
-
-For the selected todo, offer actions:
-
-- **Work now** — Execute the todo as a quick task: `/qualia-quick "{todo title}"`
-- **Add to phase** — Incorporate into an upcoming phase in the roadmap
-- **Brainstorm** — Discuss the todo further to flesh out details
-- **Create phase** — If the todo is big enough, create a new roadmap phase for it
-
-Load the full todo file content to provide context for whichever action is chosen.