qualia-framework 2.5.1 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +63 -0
- package/README.md +108 -30
- package/agents/builder.md +110 -0
- package/agents/planner.md +186 -0
- package/agents/qa-browser.md +186 -0
- package/agents/verifier.md +369 -0
- package/bin/cli.js +706 -417
- package/bin/install.js +622 -0
- package/bin/qualia-ui.js +284 -0
- package/bin/state.js +824 -0
- package/bin/statusline.js +252 -0
- package/docs/erp-contract.md +161 -0
- package/guide.md +63 -0
- package/hooks/auto-update.js +117 -0
- package/hooks/block-env-edit.js +52 -0
- package/hooks/branch-guard.js +68 -0
- package/hooks/migration-guard.js +83 -0
- package/hooks/pre-compact.js +52 -0
- package/hooks/pre-deploy-gate.js +149 -0
- package/hooks/pre-push.js +53 -0
- package/hooks/session-start.js +126 -0
- package/package.json +31 -17
- package/rules/design-reference.md +179 -0
- package/rules/frontend.md +126 -0
- package/rules/infrastructure.md +87 -0
- package/skills/qualia/SKILL.md +88 -0
- package/skills/qualia-build/SKILL.md +115 -0
- package/skills/qualia-debug/SKILL.md +87 -0
- package/skills/qualia-design/SKILL.md +99 -0
- package/skills/qualia-handoff/SKILL.md +66 -0
- package/skills/qualia-help/SKILL.md +60 -0
- package/skills/qualia-idk/SKILL.md +8 -0
- package/skills/qualia-learn/SKILL.md +111 -0
- package/skills/qualia-new/SKILL.md +323 -0
- package/skills/qualia-pause/SKILL.md +63 -0
- package/skills/qualia-plan/SKILL.md +101 -0
- package/skills/qualia-polish/SKILL.md +207 -0
- package/skills/qualia-quick/SKILL.md +37 -0
- package/skills/qualia-report/SKILL.md +114 -0
- package/skills/qualia-resume/SKILL.md +49 -0
- package/skills/qualia-review/SKILL.md +161 -0
- package/skills/qualia-ship/SKILL.md +90 -0
- package/skills/qualia-skill-new/SKILL.md +167 -0
- package/skills/qualia-task/SKILL.md +91 -0
- package/skills/qualia-test/SKILL.md +134 -0
- package/skills/qualia-verify/SKILL.md +113 -0
- package/templates/DESIGN.md +475 -0
- package/templates/help.html +476 -0
- package/templates/plan.md +42 -0
- package/templates/project.md +22 -0
- package/templates/state.md +27 -0
- package/templates/tracking.json +20 -0
- package/tests/bin.test.sh +687 -0
- package/tests/hooks.test.sh +384 -0
- package/tests/runner.js +1956 -0
- package/tests/state.test.sh +713 -0
- package/tests/statusline.test.sh +243 -0
- package/bin/collect-metrics.sh +0 -62
- package/framework/.claudeignore +0 -51
- package/framework/CLAUDE.md +0 -51
- package/framework/MCP_SETUP.md +0 -229
- package/framework/agents/architecture-strategist.md +0 -53
- package/framework/agents/backend-agent.md +0 -150
- package/framework/agents/code-simplicity-reviewer.md +0 -86
- package/framework/agents/frontend-agent.md +0 -111
- package/framework/agents/kieran-typescript-reviewer.md +0 -96
- package/framework/agents/performance-oracle.md +0 -111
- package/framework/agents/qualia-codebase-mapper.md +0 -761
- package/framework/agents/qualia-debugger.md +0 -1204
- package/framework/agents/qualia-executor.md +0 -882
- package/framework/agents/qualia-integration-checker.md +0 -424
- package/framework/agents/qualia-phase-researcher.md +0 -457
- package/framework/agents/qualia-plan-checker.md +0 -700
- package/framework/agents/qualia-planner.md +0 -1245
- package/framework/agents/qualia-project-researcher.md +0 -603
- package/framework/agents/qualia-research-synthesizer.md +0 -200
- package/framework/agents/qualia-roadmapper.md +0 -606
- package/framework/agents/qualia-verifier.md +0 -686
- package/framework/agents/red-team-qa.md +0 -130
- package/framework/agents/security-auditor.md +0 -72
- package/framework/agents/team-orchestrator.md +0 -229
- package/framework/agents/teams/framework-audit-team.md +0 -66
- package/framework/agents/teams/full-stack-team.md +0 -48
- package/framework/agents/teams/optimize-team.md +0 -53
- package/framework/agents/teams/review-team.md +0 -70
- package/framework/agents/teams/ship-team.md +0 -86
- package/framework/agents/test-agent.md +0 -182
- package/framework/hooks/auto-format.sh +0 -54
- package/framework/hooks/block-env-edit.sh +0 -42
- package/framework/hooks/branch-guard.sh +0 -43
- package/framework/hooks/confirm-delete.sh +0 -59
- package/framework/hooks/migration-validate.sh +0 -77
- package/framework/hooks/notification-speak.sh +0 -16
- package/framework/hooks/pre-commit.sh +0 -100
- package/framework/hooks/pre-compact.sh +0 -56
- package/framework/hooks/pre-deploy-gate.sh +0 -160
- package/framework/hooks/qualia-colors.sh +0 -32
- package/framework/hooks/retention-cleanup.sh +0 -62
- package/framework/hooks/save-session-state.sh +0 -185
- package/framework/hooks/session-context-loader.sh +0 -96
- package/framework/hooks/session-learn.sh +0 -32
- package/framework/hooks/skill-announce.sh +0 -123
- package/framework/hooks/tool-error-announce.sh +0 -27
- package/framework/install.ps1 +0 -323
- package/framework/install.sh +0 -313
- package/framework/qualia-framework/VERSION +0 -1
- package/framework/qualia-framework/assets/qualia-logo.png +0 -0
- package/framework/qualia-framework/bin/collect-metrics.sh +0 -67
- package/framework/qualia-framework/bin/generate-report-docx.py +0 -429
- package/framework/qualia-framework/bin/qualia-tools.js +0 -2201
- package/framework/qualia-framework/bin/qualia-tools.test.js +0 -1054
- package/framework/qualia-framework/references/checkpoints.md +0 -775
- package/framework/qualia-framework/references/completion-checklists.md +0 -359
- package/framework/qualia-framework/references/continuation-format.md +0 -249
- package/framework/qualia-framework/references/continuation-prompt.md +0 -97
- package/framework/qualia-framework/references/decimal-phase-calculation.md +0 -65
- package/framework/qualia-framework/references/design-quality.md +0 -56
- package/framework/qualia-framework/references/employee-guide.md +0 -167
- package/framework/qualia-framework/references/git-integration.md +0 -254
- package/framework/qualia-framework/references/git-planning-commit.md +0 -50
- package/framework/qualia-framework/references/model-profile-resolution.md +0 -32
- package/framework/qualia-framework/references/model-profiles.md +0 -73
- package/framework/qualia-framework/references/phase-argument-parsing.md +0 -61
- package/framework/qualia-framework/references/planning-config.md +0 -195
- package/framework/qualia-framework/references/questioning.md +0 -141
- package/framework/qualia-framework/references/tdd.md +0 -263
- package/framework/qualia-framework/references/ui-brand.md +0 -160
- package/framework/qualia-framework/references/verification-patterns.md +0 -612
- package/framework/qualia-framework/templates/DEBUG.md +0 -159
- package/framework/qualia-framework/templates/DESIGN.md +0 -81
- package/framework/qualia-framework/templates/UAT.md +0 -247
- package/framework/qualia-framework/templates/codebase/architecture.md +0 -255
- package/framework/qualia-framework/templates/codebase/concerns.md +0 -310
- package/framework/qualia-framework/templates/codebase/conventions.md +0 -307
- package/framework/qualia-framework/templates/codebase/integrations.md +0 -280
- package/framework/qualia-framework/templates/codebase/stack.md +0 -186
- package/framework/qualia-framework/templates/codebase/structure.md +0 -285
- package/framework/qualia-framework/templates/codebase/testing.md +0 -480
- package/framework/qualia-framework/templates/config.json +0 -35
- package/framework/qualia-framework/templates/context.md +0 -283
- package/framework/qualia-framework/templates/continue-here.md +0 -78
- package/framework/qualia-framework/templates/debug-subagent-prompt.md +0 -91
- package/framework/qualia-framework/templates/discovery.md +0 -146
- package/framework/qualia-framework/templates/lab-notes.md +0 -16
- package/framework/qualia-framework/templates/milestone-archive.md +0 -123
- package/framework/qualia-framework/templates/milestone.md +0 -115
- package/framework/qualia-framework/templates/phase-prompt.md +0 -567
- package/framework/qualia-framework/templates/planner-subagent-prompt.md +0 -117
- package/framework/qualia-framework/templates/project.md +0 -184
- package/framework/qualia-framework/templates/projects/ai-agent.md +0 -156
- package/framework/qualia-framework/templates/projects/mobile-app.md +0 -181
- package/framework/qualia-framework/templates/projects/voice-agent.md +0 -134
- package/framework/qualia-framework/templates/projects/website.md +0 -137
- package/framework/qualia-framework/templates/requirements.md +0 -231
- package/framework/qualia-framework/templates/research-project/ARCHITECTURE.md +0 -204
- package/framework/qualia-framework/templates/research-project/FEATURES.md +0 -147
- package/framework/qualia-framework/templates/research-project/PITFALLS.md +0 -200
- package/framework/qualia-framework/templates/research-project/STACK.md +0 -120
- package/framework/qualia-framework/templates/research-project/SUMMARY.md +0 -170
- package/framework/qualia-framework/templates/research.md +0 -552
- package/framework/qualia-framework/templates/roadmap.md +0 -206
- package/framework/qualia-framework/templates/state.md +0 -179
- package/framework/qualia-framework/templates/summary-complex.md +0 -59
- package/framework/qualia-framework/templates/summary-minimal.md +0 -41
- package/framework/qualia-framework/templates/summary-standard.md +0 -48
- package/framework/qualia-framework/templates/summary.md +0 -246
- package/framework/qualia-framework/templates/user-setup.md +0 -311
- package/framework/qualia-framework/templates/verification-report.md +0 -322
- package/framework/qualia-framework/workflows/add-phase.md +0 -179
- package/framework/qualia-framework/workflows/add-todo.md +0 -157
- package/framework/qualia-framework/workflows/audit-milestone.md +0 -241
- package/framework/qualia-framework/workflows/check-todos.md +0 -176
- package/framework/qualia-framework/workflows/complete-milestone.md +0 -858
- package/framework/qualia-framework/workflows/diagnose-issues.md +0 -219
- package/framework/qualia-framework/workflows/discovery-phase.md +0 -289
- package/framework/qualia-framework/workflows/discuss-phase.md +0 -534
- package/framework/qualia-framework/workflows/execute-phase.md +0 -559
- package/framework/qualia-framework/workflows/execute-plan.md +0 -438
- package/framework/qualia-framework/workflows/help.md +0 -470
- package/framework/qualia-framework/workflows/insert-phase.md +0 -220
- package/framework/qualia-framework/workflows/list-phase-assumptions.md +0 -178
- package/framework/qualia-framework/workflows/map-codebase.md +0 -327
- package/framework/qualia-framework/workflows/new-milestone.md +0 -363
- package/framework/qualia-framework/workflows/new-project.md +0 -982
- package/framework/qualia-framework/workflows/pause-work.md +0 -122
- package/framework/qualia-framework/workflows/plan-milestone-gaps.md +0 -256
- package/framework/qualia-framework/workflows/plan-phase.md +0 -422
- package/framework/qualia-framework/workflows/progress.md +0 -389
- package/framework/qualia-framework/workflows/quick.md +0 -252
- package/framework/qualia-framework/workflows/remove-phase.md +0 -326
- package/framework/qualia-framework/workflows/research-phase.md +0 -74
- package/framework/qualia-framework/workflows/resume-project.md +0 -306
- package/framework/qualia-framework/workflows/set-profile.md +0 -80
- package/framework/qualia-framework/workflows/settings.md +0 -145
- package/framework/qualia-framework/workflows/transition.md +0 -556
- package/framework/qualia-framework/workflows/update.md +0 -197
- package/framework/qualia-framework/workflows/verify-phase.md +0 -195
- package/framework/qualia-framework/workflows/verify-work.md +0 -625
- package/framework/rules/context7.md +0 -14
- package/framework/rules/frontend.md +0 -33
- package/framework/rules/speed.md +0 -23
- package/framework/scripts/__pycache__/say.cpython-314.pyc +0 -0
- package/framework/scripts/apply-retention.sh +0 -120
- package/framework/scripts/bootstrap-pop-os.sh +0 -354
- package/framework/scripts/claude-voice +0 -13
- package/framework/scripts/cleanup.sh +0 -131
- package/framework/scripts/cowork-mode.sh +0 -141
- package/framework/scripts/generate-project-claude-md.sh +0 -153
- package/framework/scripts/load-test-webhook.js +0 -172
- package/framework/scripts/say.py +0 -236
- package/framework/scripts/showcase-video-recorder/ffmpeg-builder.js +0 -167
- package/framework/scripts/showcase-video-recorder/playwright-helpers.js +0 -216
- package/framework/scripts/speak.py +0 -55
- package/framework/scripts/speak.sh +0 -18
- package/framework/scripts/status.sh +0 -138
- package/framework/scripts/sync-to-framework.sh +0 -65
- package/framework/scripts/voice-hotkey.py +0 -227
- package/framework/scripts/voice-input.sh +0 -51
- package/framework/skills/animate/SKILL.md +0 -202
- package/framework/skills/bolder/SKILL.md +0 -144
- package/framework/skills/browser-qa/SKILL.md +0 -536
- package/framework/skills/clarify/SKILL.md +0 -179
- package/framework/skills/client-handoff/SKILL.md +0 -135
- package/framework/skills/collab-onboard/SKILL.md +0 -111
- package/framework/skills/colorize/SKILL.md +0 -170
- package/framework/skills/critique/SKILL.md +0 -126
- package/framework/skills/deep-research/SKILL.md +0 -240
- package/framework/skills/delight/SKILL.md +0 -329
- package/framework/skills/deploy/SKILL.md +0 -261
- package/framework/skills/deploy-verify/SKILL.md +0 -377
- package/framework/skills/deploy-verify/scripts/canary-check.sh +0 -206
- package/framework/skills/deploy-verify/scripts/check-console-errors.js +0 -147
- package/framework/skills/deploy-verify/scripts/check-cwv.js +0 -139
- package/framework/skills/deploy-verify/scripts/project-detect.sh +0 -84
- package/framework/skills/deploy-verify/scripts/verify.sh +0 -548
- package/framework/skills/design-quieter/SKILL.md +0 -130
- package/framework/skills/distill/SKILL.md +0 -149
- package/framework/skills/docs-lookup/SKILL.md +0 -79
- package/framework/skills/fcm-notifications/SKILL.md +0 -125
- package/framework/skills/financial-ledger/SKILL.md +0 -1039
- package/framework/skills/frontend-master/NOTICE.md +0 -4
- package/framework/skills/frontend-master/SKILL.md +0 -127
- package/framework/skills/frontend-master/reference/color-and-contrast.md +0 -132
- package/framework/skills/frontend-master/reference/interaction-design.md +0 -123
- package/framework/skills/frontend-master/reference/motion-design.md +0 -99
- package/framework/skills/frontend-master/reference/responsive-design.md +0 -114
- package/framework/skills/frontend-master/reference/spatial-design.md +0 -100
- package/framework/skills/frontend-master/reference/typography.md +0 -131
- package/framework/skills/frontend-master/reference/ux-writing.md +0 -107
- package/framework/skills/harden/SKILL.md +0 -357
- package/framework/skills/i18n-rtl/SKILL.md +0 -752
- package/framework/skills/learn/SKILL.md +0 -95
- package/framework/skills/memory/SKILL.md +0 -50
- package/framework/skills/mobile-expo/SKILL.md +0 -977
- package/framework/skills/mobile-expo/references/store-checklist.md +0 -550
- package/framework/skills/nestjs-backend/README.md +0 -73
- package/framework/skills/nestjs-backend/SKILL.md +0 -446
- package/framework/skills/nestjs-backend/references/templates.md +0 -1173
- package/framework/skills/normalize/SKILL.md +0 -79
- package/framework/skills/onboard/SKILL.md +0 -242
- package/framework/skills/openrouter-agent/SKILL.md +0 -922
- package/framework/skills/polish/SKILL.md +0 -209
- package/framework/skills/pr/SKILL.md +0 -66
- package/framework/skills/qualia/SKILL.md +0 -199
- package/framework/skills/qualia-add-todo/SKILL.md +0 -68
- package/framework/skills/qualia-audit-milestone/SKILL.md +0 -95
- package/framework/skills/qualia-check-todos/SKILL.md +0 -55
- package/framework/skills/qualia-complete-milestone/SKILL.md +0 -134
- package/framework/skills/qualia-debug/SKILL.md +0 -149
- package/framework/skills/qualia-design/SKILL.md +0 -203
- package/framework/skills/qualia-discuss-phase/SKILL.md +0 -72
- package/framework/skills/qualia-evolve/SKILL.md +0 -200
- package/framework/skills/qualia-execute-phase/SKILL.md +0 -89
- package/framework/skills/qualia-framework-audit/SKILL.md +0 -604
- package/framework/skills/qualia-guide/SKILL.md +0 -32
- package/framework/skills/qualia-help/SKILL.md +0 -114
- package/framework/skills/qualia-idk/SKILL.md +0 -352
- package/framework/skills/qualia-list-phase-assumptions/SKILL.md +0 -67
- package/framework/skills/qualia-new-milestone/SKILL.md +0 -72
- package/framework/skills/qualia-new-project/SKILL.md +0 -232
- package/framework/skills/qualia-optimize/SKILL.md +0 -417
- package/framework/skills/qualia-pause-work/SKILL.md +0 -96
- package/framework/skills/qualia-plan-milestone-gaps/SKILL.md +0 -57
- package/framework/skills/qualia-plan-phase/SKILL.md +0 -104
- package/framework/skills/qualia-production-check/SKILL.md +0 -0
- package/framework/skills/qualia-progress/SKILL.md +0 -53
- package/framework/skills/qualia-quick/SKILL.md +0 -89
- package/framework/skills/qualia-report/SKILL.md +0 -166
- package/framework/skills/qualia-research-phase/SKILL.md +0 -88
- package/framework/skills/qualia-resume-work/SKILL.md +0 -62
- package/framework/skills/qualia-review/SKILL.md +0 -263
- package/framework/skills/qualia-start/SKILL.md +0 -161
- package/framework/skills/qualia-verify-work/SKILL.md +0 -132
- package/framework/skills/rag/SKILL.md +0 -750
- package/framework/skills/responsive/SKILL.md +0 -231
- package/framework/skills/retro/SKILL.md +0 -284
- package/framework/skills/sakani-conventions/SKILL.md +0 -136
- package/framework/skills/sakani-conventions/evals/evals.json +0 -23
- package/framework/skills/sakani-conventions/references/entities.md +0 -365
- package/framework/skills/sakani-conventions/references/error-codes.md +0 -95
- package/framework/skills/seo-master/SKILL.md +0 -490
- package/framework/skills/seo-master/references/checklist.md +0 -199
- package/framework/skills/seo-master/references/structured-data.md +0 -609
- package/framework/skills/ship/SKILL.md +0 -239
- package/framework/skills/stack-researcher/SKILL.md +0 -215
- package/framework/skills/status/SKILL.md +0 -154
- package/framework/skills/status/scripts/health-check.sh +0 -562
- package/framework/skills/subscription-payments/SKILL.md +0 -250
- package/framework/skills/supabase/SKILL.md +0 -973
- package/framework/skills/supabase/references/templates.md +0 -159
- package/framework/skills/team/SKILL.md +0 -67
- package/framework/skills/test-runner/SKILL.md +0 -202
- package/framework/skills/voice-agent/SKILL.md +0 -1312
- package/framework/skills/zoho-workflow/SKILL.md +0 -51
- package/framework/statusline-command.sh +0 -117
- package/framework/teams/default/inboxes/plan-04.json +0 -9
- package/framework/teams/review-team.md +0 -75
- package/framework/teams/ship-team.md +0 -86
- package/profiles/fawzi.json +0 -16
- package/profiles/hasan.json +0 -16
- package/profiles/moayad.json +0 -16
- package/templates/CLAUDE-owner.md +0 -52
- package/templates/CLAUDE.md.hbs +0 -58
- package/templates/env.claude.template +0 -12
- package/templates/settings.json +0 -172
- /package/{framework/rules → rules}/deployment.md +0 -0
- /package/{framework/rules → rules}/security.md +0 -0
|
@@ -1,232 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: qualia-new-project
|
|
3
|
-
description: "Initialize a new Qualia workflow project from scratch — questioning, research, requirements, roadmap, environment setup, design context. 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 workflow. Also trigger when user mentions setting up .planning directory, creating a roadmap, or starting fresh on a new client project."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Qualia New Project — Full Project Initialization
|
|
7
|
-
|
|
8
|
-
Initialize a new project with the complete Qualia workflow: questioning → research → requirements → roadmap → environment → design context. Produces everything needed for an employee to start building and carry through to client handoff.
|
|
9
|
-
|
|
10
|
-
## Usage
|
|
11
|
-
|
|
12
|
-
`/qualia-new-project` — Start new project initialization
|
|
13
|
-
`/qualia-new-project "Build AI chatbot for client X"` — Start with initial description
|
|
14
|
-
|
|
15
|
-
## Process
|
|
16
|
-
|
|
17
|
-
Reference: `~/.claude/qualia-framework/workflows/new-project.md` (the full 1000+ line workflow — follow it exactly)
|
|
18
|
-
|
|
19
|
-
### 0. Pre-flight
|
|
20
|
-
|
|
21
|
-
**Initialize context:**
|
|
22
|
-
```bash
|
|
23
|
-
INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-project)
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `project_exists`, `has_existing_code`, `needs_codebase_map`, `has_git`.
|
|
27
|
-
|
|
28
|
-
- If `project_exists` is true → Error: "Project already initialized. Run `/qualia-progress` to see status."
|
|
29
|
-
- If `has_git` is false → `git init`
|
|
30
|
-
|
|
31
|
-
**Scan for uploaded files** (PDFs, docs, images). If they mention a non-Qualia stack, ask:
|
|
32
|
-
> "The document mentions {stack}. Use the Qualia stack (Next.js + Supabase + Vercel) or the document's stack?"
|
|
33
|
-
|
|
34
|
-
**Brownfield detection:** If existing code found without a codebase map, scan the codebase structure before proceeding.
|
|
35
|
-
|
|
36
|
-
### 1. Deep Questioning
|
|
37
|
-
|
|
38
|
-
Reference: `~/.claude/qualia-framework/references/questioning.md`
|
|
39
|
-
|
|
40
|
-
**Start open:** "What do you want to build?"
|
|
41
|
-
|
|
42
|
-
Then follow threads — dig into what they said. This is dream extraction, not an interview. Ask about:
|
|
43
|
-
- What is it? Who is it for?
|
|
44
|
-
- What problem does it solve?
|
|
45
|
-
- What does "done" look like?
|
|
46
|
-
- What are the constraints (timeline, budget, existing systems)?
|
|
47
|
-
|
|
48
|
-
Use AskUserQuestion with concrete options to help them think. Challenge vagueness. Make abstract things concrete ("walk me through using this").
|
|
49
|
-
|
|
50
|
-
**Decision gate:** When you have enough to write PROJECT.md, ask:
|
|
51
|
-
> "I think I understand. Ready to create PROJECT.md, or want to explore more?"
|
|
52
|
-
|
|
53
|
-
### 2. Detect Project Type & Load Template
|
|
54
|
-
|
|
55
|
-
Based on questioning answers, detect the project type:
|
|
56
|
-
|
|
57
|
-
| Signal | Type | Template |
|
|
58
|
-
|--------|------|----------|
|
|
59
|
-
| website, landing page, marketing, SaaS | `website` | `templates/projects/website.md` |
|
|
60
|
-
| chatbot, AI assistant, chat agent | `ai-agent` | `templates/projects/ai-agent.md` |
|
|
61
|
-
| voice agent, phone agent, call bot, Retell | `voice-agent` | `templates/projects/voice-agent.md` |
|
|
62
|
-
| mobile app, iOS, Android, Expo | `mobile-app` | `templates/projects/mobile-app.md` |
|
|
63
|
-
|
|
64
|
-
**Always load the matching template.** Read it from `~/.claude/qualia-framework/templates/projects/{type}.md`. This gives you the standard phase structure for this project type — the roadmap will use it as a scaffold.
|
|
65
|
-
|
|
66
|
-
Ask the employee to confirm:
|
|
67
|
-
> "This looks like a {type} project. I'll use the {type} template for the phase structure. Sound right?"
|
|
68
|
-
|
|
69
|
-
If no type detected, build the roadmap from scratch.
|
|
70
|
-
|
|
71
|
-
### 3. Write PROJECT.md
|
|
72
|
-
|
|
73
|
-
Template: `~/.claude/qualia-framework/templates/project.md`
|
|
74
|
-
|
|
75
|
-
Synthesize all context into `.planning/PROJECT.md`:
|
|
76
|
-
- Project name, description, client
|
|
77
|
-
- Core Value (the ONE thing that must work)
|
|
78
|
-
- Requirements (Active = hypotheses until shipped)
|
|
79
|
-
- Context, Constraints, Key Decisions
|
|
80
|
-
- Tech stack decisions
|
|
81
|
-
- Deploy target
|
|
82
|
-
|
|
83
|
-
**Commit immediately:**
|
|
84
|
-
```bash
|
|
85
|
-
mkdir -p .planning
|
|
86
|
-
node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### 4. Workflow Preferences
|
|
90
|
-
|
|
91
|
-
Use sensible defaults. Only ask ONE question:
|
|
92
|
-
|
|
93
|
-
```
|
|
94
|
-
"Use recommended settings? (Interactive mode, standard depth, all quality agents, balanced profile)"
|
|
95
|
-
→ Yes (Recommended) — use all defaults
|
|
96
|
-
→ Customize — show individual options
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
**Defaults** (written to `.planning/config.json`):
|
|
100
|
-
- Mode: Interactive
|
|
101
|
-
- Depth: Standard (5-8 phases)
|
|
102
|
-
- Execution: Parallel
|
|
103
|
-
- Researcher: enabled
|
|
104
|
-
- Plan Checker: enabled
|
|
105
|
-
- Verifier: enabled
|
|
106
|
-
- Model Profile: Balanced
|
|
107
|
-
|
|
108
|
-
**If "Customize":** Show the individual options as AskUserQuestion. Otherwise skip straight to config.json creation.
|
|
109
|
-
|
|
110
|
-
Write `.planning/config.json` with all settings.
|
|
111
|
-
|
|
112
|
-
**Commit:**
|
|
113
|
-
```bash
|
|
114
|
-
node ~/.claude/qualia-framework/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
### 5. Research Phase (if selected)
|
|
118
|
-
|
|
119
|
-
Spawn 4 parallel research agents:
|
|
120
|
-
1. **Stack research** → `.planning/research/STACK.md`
|
|
121
|
-
2. **Features research** → `.planning/research/FEATURES.md`
|
|
122
|
-
3. **Architecture research** → `.planning/research/ARCHITECTURE.md`
|
|
123
|
-
4. **Pitfalls research** → `.planning/research/PITFALLS.md`
|
|
124
|
-
|
|
125
|
-
Then spawn synthesizer → `.planning/research/SUMMARY.md`
|
|
126
|
-
|
|
127
|
-
Present key findings to employee before moving on.
|
|
128
|
-
|
|
129
|
-
### 6. Define Requirements
|
|
130
|
-
|
|
131
|
-
Load context from PROJECT.md and research (if exists).
|
|
132
|
-
|
|
133
|
-
**If research exists:** Present features by category (table stakes vs differentiators). Let employee scope each category for v1 using AskUserQuestion with multiSelect.
|
|
134
|
-
|
|
135
|
-
**If no research:** Gather requirements conversationally.
|
|
136
|
-
|
|
137
|
-
Generate `.planning/REQUIREMENTS.md` with:
|
|
138
|
-
- v1 Requirements grouped by category (with REQ-IDs like AUTH-01, CONT-02)
|
|
139
|
-
- v2 Requirements (deferred)
|
|
140
|
-
- Out of Scope (with reasons)
|
|
141
|
-
- Traceability section (filled by roadmap)
|
|
142
|
-
|
|
143
|
-
**Show full requirements list for approval.** Loop until employee confirms.
|
|
144
|
-
|
|
145
|
-
**Commit:**
|
|
146
|
-
```bash
|
|
147
|
-
node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
### 7. Create Roadmap
|
|
151
|
-
|
|
152
|
-
Spawn qualia-roadmapper agent with PROJECT.md, REQUIREMENTS.md, research, config, and the project type template.
|
|
153
|
-
|
|
154
|
-
**Roadmap contains FEATURE PHASES ONLY.** Do NOT add review, deploy, or handoff phases to the roadmap. The finish line system (`/qualia-complete-milestone` → polish → review → PR → deploy → handoff) handles the 70%-to-100% journey automatically after all feature phases are done. Adding them to the roadmap would cause employees to do them twice.
|
|
155
|
-
|
|
156
|
-
**If using a project type template:** Use its phases as the feature scaffold.
|
|
157
|
-
|
|
158
|
-
**Present roadmap to employee for approval.** Show phase table with goals, requirements mapped, and success criteria. Loop until approved.
|
|
159
|
-
|
|
160
|
-
**Commit:**
|
|
161
|
-
```bash
|
|
162
|
-
node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
### 8. Environment Setup
|
|
166
|
-
|
|
167
|
-
Detect what's needed from PROJECT.md and stack:
|
|
168
|
-
|
|
169
|
-
- **Supabase** → Link or create project, init schema
|
|
170
|
-
- **Vercel** → Link project
|
|
171
|
-
- **Environment variables** → Create `.env.local` with placeholders
|
|
172
|
-
- **External services** → Note which API keys are needed (Stripe, Retell, OpenRouter, etc.)
|
|
173
|
-
|
|
174
|
-
Walk the employee through setup. If they want to skip: note `env_setup: pending` in STATE.md.
|
|
175
|
-
|
|
176
|
-
**Starter template:** If a matching starter exists at `~/Projects/qualia-erp/templates/{type}-starter/`, offer to scaffold from it.
|
|
177
|
-
|
|
178
|
-
### 9. Design Context (frontend projects)
|
|
179
|
-
|
|
180
|
-
If the project involves frontend work (detected from roadmap or project type), create `.planning/DESIGN.md` with a brief design consultation:
|
|
181
|
-
|
|
182
|
-
Ask the employee 3 questions using AskUserQuestion:
|
|
183
|
-
1. **Aesthetic direction** — "What feel should this project have?" (options: Clean/minimal, Bold/striking, Warm/friendly, Corporate/professional)
|
|
184
|
-
2. **Color palette** — "Any brand colors or preferences?" (freeform — or offer to pick based on aesthetic)
|
|
185
|
-
3. **Reference sites** — "Any websites you'd like it to look/feel like?" (freeform)
|
|
186
|
-
|
|
187
|
-
Write `.planning/DESIGN.md` with the answers. This is read by the frontend guard before any UI work.
|
|
188
|
-
|
|
189
|
-
**Do NOT run `/critique` here** — there's no code to critique yet. Design consultation creates the brief; `/critique` reviews implemented UI later.
|
|
190
|
-
|
|
191
|
-
### 10. Done — Present Summary
|
|
192
|
-
|
|
193
|
-
```
|
|
194
|
-
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
195
|
-
Qualia ► PROJECT INITIALIZED ✓
|
|
196
|
-
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
197
|
-
|
|
198
|
-
**[Project Name]** — [type] project for [client]
|
|
199
|
-
|
|
200
|
-
| Artifact | Location |
|
|
201
|
-
|----------------|-----------------------------|
|
|
202
|
-
| Project | .planning/PROJECT.md |
|
|
203
|
-
| Config | .planning/config.json |
|
|
204
|
-
| Research | .planning/research/ |
|
|
205
|
-
| Requirements | .planning/REQUIREMENTS.md |
|
|
206
|
-
| Roadmap | .planning/ROADMAP.md |
|
|
207
|
-
| State | .planning/STATE.md |
|
|
208
|
-
| Design | .planning/DESIGN.md |
|
|
209
|
-
|
|
210
|
-
**[N] phases** | **[X] requirements** | Ready to build ✓
|
|
211
|
-
|
|
212
|
-
## The Full Journey
|
|
213
|
-
|
|
214
|
-
Phase 1-{N}: Feature phases (build the product)
|
|
215
|
-
↓ after all phases verified
|
|
216
|
-
Finish Line: Polish → Review → PR → Deploy → Handoff (automated by /qualia)
|
|
217
|
-
|
|
218
|
-
## ▶ Next
|
|
219
|
-
|
|
220
|
-
Run `/qualia-plan-phase 1` to plan the first phase.
|
|
221
|
-
(Or `/qualia-discuss-phase 1` to discuss approach first.)
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
### Agents Used
|
|
225
|
-
| Agent | File | Role |
|
|
226
|
-
|-------|------|------|
|
|
227
|
-
| `qualia-project-researcher` | `~/.claude/agents/qualia-project-researcher.md` | Domain ecosystem research (4 parallel) |
|
|
228
|
-
| `qualia-research-synthesizer` | `~/.claude/agents/qualia-research-synthesizer.md` | Synthesizes parallel research |
|
|
229
|
-
| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md with feature phases |
|
|
230
|
-
|
|
231
|
-
---
|
|
232
|
-
> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`
|
|
@@ -1,417 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: qualia-optimize
|
|
3
|
-
description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Qualia Optimize — Deep Codebase + Planning Optimization
|
|
7
|
-
|
|
8
|
-
Comprehensive optimization that reads BOTH `.planning/` docs AND the actual codebase. Never analyze one without the other.
|
|
9
|
-
|
|
10
|
-
## Usage
|
|
11
|
-
|
|
12
|
-
- `/qualia-optimize` — Full optimization (all 6 dimensions)
|
|
13
|
-
- `/qualia-optimize --perf` — Performance only (queries, bundle, render, latency)
|
|
14
|
-
- `/qualia-optimize --ui` — Frontend/design/UI only
|
|
15
|
-
- `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge functions)
|
|
16
|
-
- `/qualia-optimize --alignment` — Planning-code alignment check only
|
|
17
|
-
- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM findings from existing OPTIMIZE.md
|
|
18
|
-
|
|
19
|
-
## Process
|
|
20
|
-
|
|
21
|
-
### Step 1: Parse Arguments
|
|
22
|
-
|
|
23
|
-
Extract mode from $ARGUMENTS. Default to `full`.
|
|
24
|
-
|
|
25
|
-
Supported modes: `full`, `perf`, `ui`, `backend`, `alignment`, `fix`.
|
|
26
|
-
|
|
27
|
-
If `--fix`: skip to Step 9 (requires existing `.planning/OPTIMIZE.md`).
|
|
28
|
-
|
|
29
|
-
### Step 2: Load Planning Context (MANDATORY — never skip)
|
|
30
|
-
|
|
31
|
-
Read ALL of these (skip silently if file doesn't exist, but always attempt):
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
cat .planning/REQUIREMENTS.md 2>/dev/null || echo "NO_REQUIREMENTS"
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
```bash
|
|
46
|
-
cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Also read the rules:
|
|
54
|
-
```bash
|
|
55
|
-
cat ~/.claude/rules/frontend.md 2>/dev/null
|
|
56
|
-
cat ~/.claude/rules/security.md 2>/dev/null
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Store all content — you will inline it into agent prompts.
|
|
60
|
-
|
|
61
|
-
**If NO planning docs exist at all**: warn the user but proceed. The optimization still works on raw codebase — it just can't check alignment.
|
|
62
|
-
|
|
63
|
-
### Step 3: Discover Codebase
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
pwd && node -e "try{const p=require('./package.json');console.log(JSON.stringify({name:p.name,deps:Object.keys(p.dependencies||{}),devDeps:Object.keys(p.devDependencies||{})}))}catch(e){console.log('{}')}" 2>/dev/null
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
git log --oneline -15 2>/dev/null
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
git diff --stat HEAD~10..HEAD 2>/dev/null | tail -5
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
# Project structure
|
|
79
|
-
ls -d app/ src/ pages/ components/ lib/ actions/ hooks/ supabase/ types/ 2>/dev/null
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
Classify project type: `web` | `voice` | `mobile` | `agent` | `edge-functions` | `unknown`
|
|
83
|
-
|
|
84
|
-
### Step 4: Spawn Wave 1 Agents (parallel)
|
|
85
|
-
|
|
86
|
-
Based on mode, spawn agents in a **single message** with multiple Agent() calls.
|
|
87
|
-
|
|
88
|
-
| Mode | Agents |
|
|
89
|
-
|------|--------|
|
|
90
|
-
| `full` | frontend-agent + backend-agent + performance-oracle (3 parallel) |
|
|
91
|
-
| `perf` | performance-oracle only |
|
|
92
|
-
| `ui` | frontend-agent only |
|
|
93
|
-
| `backend` | backend-agent only |
|
|
94
|
-
| `alignment` | general-purpose with alignment prompt |
|
|
95
|
-
|
|
96
|
-
**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Agent() boundaries.
|
|
97
|
-
|
|
98
|
-
#### Frontend Agent Prompt
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
Agent(
|
|
102
|
-
prompt="You are optimizing a project's frontend. Read the planning docs and codebase rules below, then analyze the actual code.
|
|
103
|
-
|
|
104
|
-
<planning>
|
|
105
|
-
{PROJECT.md content}
|
|
106
|
-
{REQUIREMENTS.md content}
|
|
107
|
-
{DESIGN.md content}
|
|
108
|
-
</planning>
|
|
109
|
-
|
|
110
|
-
<rules>
|
|
111
|
-
{rules/frontend.md content}
|
|
112
|
-
</rules>
|
|
113
|
-
|
|
114
|
-
<task>
|
|
115
|
-
Analyze the frontend codebase for issues in these categories:
|
|
116
|
-
|
|
117
|
-
1. **UI Quality**
|
|
118
|
-
- Loading states: every async operation should show a loading indicator
|
|
119
|
-
- Error states: every data-fetching component should handle errors gracefully
|
|
120
|
-
- Empty states: lists/tables should handle zero items with helpful messaging
|
|
121
|
-
- Responsive: check for fixed pixel widths on containers, missing breakpoint handling
|
|
122
|
-
- Accessibility: alt text on images, ARIA labels on interactive elements, keyboard navigation
|
|
123
|
-
|
|
124
|
-
2. **Design Alignment**
|
|
125
|
-
- Compare actual components against DESIGN.md decisions (colors, typography, spacing)
|
|
126
|
-
- Check rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids or blue-purple gradients?
|
|
127
|
-
- Consistency: are the same patterns used throughout? (button styles, spacing, color usage)
|
|
128
|
-
|
|
129
|
-
3. **Frontend Performance**
|
|
130
|
-
- Bundle: large library imports that could be tree-shaken or dynamically imported
|
|
131
|
-
- Images: using next/image? width/height set? lazy loading below fold?
|
|
132
|
-
- Fonts: using next/font? No render-blocking font loads?
|
|
133
|
-
- CSS: unused Tailwind classes? conflicting styles?
|
|
134
|
-
- Rendering: unnecessary re-renders, missing React.memo on list items, heavy computations in render
|
|
135
|
-
|
|
136
|
-
For EVERY finding, output in this exact format:
|
|
137
|
-
- **What**: [description]
|
|
138
|
-
- **Where**: [file:line]
|
|
139
|
-
- **Why**: [impact on users/performance]
|
|
140
|
-
- **Fix**: [concrete fix suggestion]
|
|
141
|
-
- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
|
|
142
|
-
</task>",
|
|
143
|
-
subagent_type="frontend-agent",
|
|
144
|
-
description="Frontend optimization analysis"
|
|
145
|
-
)
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
#### Backend Agent Prompt
|
|
149
|
-
|
|
150
|
-
```
|
|
151
|
-
Agent(
|
|
152
|
-
prompt="You are optimizing a project's backend. Read the planning docs and security rules below, then analyze the actual code.
|
|
153
|
-
|
|
154
|
-
<planning>
|
|
155
|
-
{PROJECT.md content}
|
|
156
|
-
{REQUIREMENTS.md content}
|
|
157
|
-
</planning>
|
|
158
|
-
|
|
159
|
-
<rules>
|
|
160
|
-
{rules/security.md content}
|
|
161
|
-
</rules>
|
|
162
|
-
|
|
163
|
-
<task>
|
|
164
|
-
Analyze the backend codebase for issues:
|
|
165
|
-
|
|
166
|
-
1. **Security**
|
|
167
|
-
- RLS: every Supabase table must have ROW LEVEL SECURITY enabled with policies
|
|
168
|
-
- Service role: grep for service_role key usage in client-side code (app/, components/, src/) — should be ZERO
|
|
169
|
-
- Auth: all mutations use server-side auth check (supabase.auth.getUser())
|
|
170
|
-
- Validation: input validated with Zod before database operations
|
|
171
|
-
- No dangerouslySetInnerHTML or eval()
|
|
172
|
-
|
|
173
|
-
2. **Data Access Patterns**
|
|
174
|
-
- Server actions vs client mutations: data writes should use 'use server' actions, not direct Supabase client calls
|
|
175
|
-
- Proper error handling: try/catch with meaningful error messages
|
|
176
|
-
- Revalidation: revalidatePath/revalidateTag after mutations
|
|
177
|
-
|
|
178
|
-
3. **Edge Functions** (if supabase/functions/ exists)
|
|
179
|
-
- Cold start optimization: bundle size, dependency count
|
|
180
|
-
- Error handling and logging
|
|
181
|
-
- CORS configuration
|
|
182
|
-
- Timeout protection (maxDuration)
|
|
183
|
-
|
|
184
|
-
4. **API Quality**
|
|
185
|
-
- Rate limiting on public endpoints
|
|
186
|
-
- Proper HTTP status codes
|
|
187
|
-
- Consistent error response format
|
|
188
|
-
|
|
189
|
-
For EVERY finding, output:
|
|
190
|
-
- **What**: [description]
|
|
191
|
-
- **Where**: [file:line]
|
|
192
|
-
- **Why**: [impact]
|
|
193
|
-
- **Fix**: [concrete suggestion]
|
|
194
|
-
- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
|
|
195
|
-
</task>",
|
|
196
|
-
subagent_type="backend-agent",
|
|
197
|
-
description="Backend optimization analysis"
|
|
198
|
-
)
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
#### Performance Oracle Prompt
|
|
202
|
-
|
|
203
|
-
```
|
|
204
|
-
Agent(
|
|
205
|
-
prompt="You are analyzing cross-cutting performance issues. Read the project context, then analyze the codebase.
|
|
206
|
-
|
|
207
|
-
<planning>
|
|
208
|
-
{PROJECT.md content}
|
|
209
|
-
</planning>
|
|
210
|
-
|
|
211
|
-
<task>
|
|
212
|
-
Analyze for performance issues across the full stack:
|
|
213
|
-
|
|
214
|
-
1. **Database Queries**
|
|
215
|
-
- N+1 queries: Supabase .from() calls inside loops or .map()
|
|
216
|
-
- Missing indexes: .eq()/.filter()/.order() columns without corresponding indexes in migrations
|
|
217
|
-
- Sequential queries that could be parallel (Promise.all)
|
|
218
|
-
- Over-fetching: SELECT * when only specific columns needed
|
|
219
|
-
|
|
220
|
-
2. **API Latency**
|
|
221
|
-
- Sequential API calls from client that could be batched
|
|
222
|
-
- Missing caching (SWR/React Query stale times, HTTP cache headers)
|
|
223
|
-
- Large payloads without pagination
|
|
224
|
-
|
|
225
|
-
3. **Bundle Size**
|
|
226
|
-
- Barrel exports (index.ts re-exporting everything) preventing tree-shaking
|
|
227
|
-
- Large libraries imported for single functions (lodash, moment)
|
|
228
|
-
- Missing dynamic imports for heavy components (charts, editors, maps)
|
|
229
|
-
|
|
230
|
-
4. **Render Performance**
|
|
231
|
-
- Expensive computations in render path without useMemo
|
|
232
|
-
- Event handlers recreated on every render without useCallback
|
|
233
|
-
- Large lists without virtualization
|
|
234
|
-
- Context providers causing unnecessary re-renders
|
|
235
|
-
|
|
236
|
-
For EVERY finding, output:
|
|
237
|
-
- **What**: [description]
|
|
238
|
-
- **Where**: [file:line]
|
|
239
|
-
- **Why**: [performance impact, quantified if possible]
|
|
240
|
-
- **Fix**: [concrete suggestion]
|
|
241
|
-
- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
|
|
242
|
-
</task>",
|
|
243
|
-
subagent_type="performance-oracle",
|
|
244
|
-
description="Performance optimization analysis"
|
|
245
|
-
)
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
### Step 5: Spawn Wave 2 Agent (after Wave 1 completes)
|
|
249
|
-
|
|
250
|
-
After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
|
|
251
|
-
|
|
252
|
-
```
|
|
253
|
-
Agent(
|
|
254
|
-
prompt="You are synthesizing optimization findings from 3 specialist agents. Look for cross-cutting architectural issues.
|
|
255
|
-
|
|
256
|
-
<wave1_findings>
|
|
257
|
-
{All findings from frontend-agent, backend-agent, performance-oracle}
|
|
258
|
-
</wave1_findings>
|
|
259
|
-
|
|
260
|
-
<planning>
|
|
261
|
-
{PROJECT.md content}
|
|
262
|
-
{REQUIREMENTS.md content}
|
|
263
|
-
</planning>
|
|
264
|
-
|
|
265
|
-
<task>
|
|
266
|
-
1. Identify patterns across findings — recurring issues that point to a structural problem
|
|
267
|
-
2. Find coupling issues between frontend and backend
|
|
268
|
-
3. Check for inconsistent patterns (e.g., some routes use server actions, others use API routes)
|
|
269
|
-
4. Identify missing abstractions (same pattern repeated 3+ times)
|
|
270
|
-
5. Check for dead code and unused exports
|
|
271
|
-
|
|
272
|
-
Output:
|
|
273
|
-
- **Structural findings** (architectural issues, not covered by Wave 1)
|
|
274
|
-
- **Pattern consolidation** (where Wave 1 findings share a root cause)
|
|
275
|
-
- Each finding in the same format: What/Where/Why/Fix/Severity
|
|
276
|
-
</task>",
|
|
277
|
-
subagent_type="architecture-strategist",
|
|
278
|
-
description="Architecture synthesis"
|
|
279
|
-
)
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
**Skip Wave 2 for single-mode runs** (`--perf`, `--ui`, `--backend`). Only run for `full` mode.
|
|
283
|
-
|
|
284
|
-
### Step 6: Alignment Check (always runs in `full` and `alignment` modes)
|
|
285
|
-
|
|
286
|
-
For `alignment` mode, this is the sole analysis. For `full` mode, run alongside Wave 1.
|
|
287
|
-
|
|
288
|
-
Read REQUIREMENTS.md and ROADMAP.md. For each requirement marked "Complete" or mapped to a completed phase:
|
|
289
|
-
|
|
290
|
-
```bash
|
|
291
|
-
# Find completed requirements
|
|
292
|
-
grep -E "Complete|✓" .planning/REQUIREMENTS.md 2>/dev/null
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
For each completed requirement:
|
|
296
|
-
- Grep the codebase for evidence it actually exists (routes, components, API endpoints)
|
|
297
|
-
- If not found: flag as "Claimed complete but not implemented"
|
|
298
|
-
|
|
299
|
-
Then scan for orphan features:
|
|
300
|
-
```bash
|
|
301
|
-
# Find all routes/pages
|
|
302
|
-
find app -name "page.tsx" -o -name "route.ts" 2>/dev/null
|
|
303
|
-
# Find all API routes
|
|
304
|
-
find app/api -name "route.ts" 2>/dev/null
|
|
305
|
-
```
|
|
306
|
-
|
|
307
|
-
Cross-reference with REQUIREMENTS.md — any route/feature NOT in requirements is flagged as "Undocumented feature".
|
|
308
|
-
|
|
309
|
-
### Step 7: Collect and Score Findings
|
|
310
|
-
|
|
311
|
-
After all agents return:
|
|
312
|
-
1. Deduplicate (same file:line from multiple agents → keep the most detailed one)
|
|
313
|
-
2. Sort by severity: CRITICAL first
|
|
314
|
-
3. Group by dimension: Performance, Design Alignment, UI Quality, Backend, Frontend, Planning-Code Alignment, Architecture
|
|
315
|
-
|
|
316
|
-
Count totals per severity.
|
|
317
|
-
|
|
318
|
-
### Step 8: Write OPTIMIZE.md and Present Results
|
|
319
|
-
|
|
320
|
-
Write to `.planning/OPTIMIZE.md`:
|
|
321
|
-
|
|
322
|
-
```markdown
|
|
323
|
-
---
|
|
324
|
-
date: {YYYY-MM-DD HH:MM}
|
|
325
|
-
mode: {full|perf|ui|backend|alignment}
|
|
326
|
-
critical: {N}
|
|
327
|
-
high: {N}
|
|
328
|
-
medium: {N}
|
|
329
|
-
low: {N}
|
|
330
|
-
status: {clean|needs_attention|critical_issues}
|
|
331
|
-
---
|
|
332
|
-
|
|
333
|
-
# Optimization Report
|
|
334
|
-
|
|
335
|
-
**Project:** {name} | **Mode:** {mode} | **Date:** {date}
|
|
336
|
-
|
|
337
|
-
## Summary
|
|
338
|
-
|
|
339
|
-
{2-3 sentence overview}
|
|
340
|
-
|
|
341
|
-
{If status is clean: "No critical issues found. Project is in good shape."}
|
|
342
|
-
|
|
343
|
-
## Critical Issues
|
|
344
|
-
|
|
345
|
-
| # | Dimension | Finding | Location | Fix |
|
|
346
|
-
|---|-----------|---------|----------|-----|
|
|
347
|
-
{findings}
|
|
348
|
-
|
|
349
|
-
## High Priority
|
|
350
|
-
|
|
351
|
-
| # | Dimension | Finding | Location | Fix |
|
|
352
|
-
|---|-----------|---------|----------|-----|
|
|
353
|
-
{findings}
|
|
354
|
-
|
|
355
|
-
## Medium Priority
|
|
356
|
-
|
|
357
|
-
| # | Dimension | Finding | Location | Fix |
|
|
358
|
-
|---|-----------|---------|----------|-----|
|
|
359
|
-
{findings}
|
|
360
|
-
|
|
361
|
-
## Low Priority
|
|
362
|
-
|
|
363
|
-
| # | Dimension | Finding | Location | Fix |
|
|
364
|
-
|---|-----------|---------|----------|-----|
|
|
365
|
-
{findings}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
Commit:
|
|
369
|
-
```bash
|
|
370
|
-
node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: optimization report ({mode} mode, {critical} critical)" --files .planning/OPTIMIZE.md
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
**Present results:**
|
|
374
|
-
|
|
375
|
-
If CRITICAL findings exist:
|
|
376
|
-
```
|
|
377
|
-
{critical} critical issues found. Options:
|
|
378
|
-
|
|
379
|
-
1. Create a fix phase in ROADMAP.md for critical + high findings
|
|
380
|
-
2. Auto-fix LOW/MEDIUM findings: /qualia-optimize --fix
|
|
381
|
-
3. Review full report: cat .planning/OPTIMIZE.md
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
If no CRITICAL:
|
|
385
|
-
```
|
|
386
|
-
Optimization complete. {total} findings ({high} high, {medium} medium, {low} low).
|
|
387
|
-
Report: .planning/OPTIMIZE.md
|
|
388
|
-
|
|
389
|
-
Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
### Step 9: --fix Mode
|
|
393
|
-
|
|
394
|
-
When `--fix` is provided:
|
|
395
|
-
|
|
396
|
-
1. Read existing `.planning/OPTIMIZE.md` — if not found, error: "Run /qualia-optimize first"
|
|
397
|
-
2. Filter to LOW and MEDIUM findings only
|
|
398
|
-
3. For each finding with a clear, safe fix:
|
|
399
|
-
- Read the target file
|
|
400
|
-
- Apply the fix
|
|
401
|
-
- Verify it doesn't break (npx tsc --noEmit if TypeScript)
|
|
402
|
-
4. Update OPTIMIZE.md: mark fixed findings, recount severities
|
|
403
|
-
5. Commit changes
|
|
404
|
-
6. Report what was fixed and what remains
|
|
405
|
-
|
|
406
|
-
**Never auto-fix CRITICAL or HIGH** — those require human judgment.
|
|
407
|
-
|
|
408
|
-
### Step 10: Gap Phase Creation (if user selects option 1 from Step 8)
|
|
409
|
-
|
|
410
|
-
If user wants a fix phase for critical issues:
|
|
411
|
-
|
|
412
|
-
1. Read ROADMAP.md, find current phase number
|
|
413
|
-
2. Insert a decimal phase: `Phase {N}.1: Optimization Fixes (INSERTED)`
|
|
414
|
-
3. Map CRITICAL and HIGH findings as success criteria
|
|
415
|
-
4. Update STATE.md
|
|
416
|
-
5. Commit
|
|
417
|
-
6. Suggest: "Fix phase created. Run `/qualia-plan-phase {N}.1`"
|