qualia-framework 3.3.2 → 3.6.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.
Files changed (26) hide show
  1. package/bin/cli.js +13 -2
  2. package/bin/install.js +28 -5
  3. package/bin/state.js +363 -43
  4. package/bin/statusline.js +40 -20
  5. package/docs/erp-contract.md +40 -1
  6. package/hooks/auto-update.js +54 -70
  7. package/hooks/branch-guard.js +64 -6
  8. package/hooks/migration-guard.js +85 -10
  9. package/hooks/pre-compact.js +28 -4
  10. package/hooks/pre-deploy-gate.js +46 -6
  11. package/hooks/pre-push.js +94 -27
  12. package/hooks/session-start.js +6 -0
  13. package/package.json +1 -1
  14. package/skills/qualia-build/SKILL.md +1 -1
  15. package/skills/qualia-map/SKILL.md +4 -4
  16. package/skills/qualia-milestone/SKILL.md +14 -2
  17. package/skills/qualia-optimize/SKILL.md +4 -4
  18. package/skills/qualia-quick/SKILL.md +2 -2
  19. package/skills/qualia-report/SKILL.md +38 -7
  20. package/skills/qualia-task/SKILL.md +1 -1
  21. package/skills/qualia-verify/SKILL.md +2 -2
  22. package/templates/help.html +98 -31
  23. package/templates/tracking.json +17 -1
  24. package/tests/runner.js +395 -0
  25. package/tests/state.test.sh +232 -4
  26. package/skills/qualia-idk/SKILL.md +0 -8
package/templates/help.html CHANGED
@@ -37,6 +37,22 @@
37
37
  -webkit-font-smoothing: antialiased;
38
38
  }
39
39
 
40
+ /* ─── Version Pill (top-right) ───────────── */
41
+ .version-pill {
42
+ position: fixed;
43
+ top: 1rem;
44
+ right: 1rem;
45
+ z-index: 10;
46
+ padding: 0.3rem 0.75rem;
47
+ background: var(--bg-card);
48
+ border: 1px solid var(--border);
49
+ border-radius: 999px;
50
+ font-family: var(--font-mono);
51
+ font-size: 0.7rem;
52
+ color: var(--teal);
53
+ letter-spacing: 0.04em;
54
+ }
55
+
40
56
  /* ─── Header ─────────────────────────────── */
41
57
  .header {
42
58
  padding: clamp(2rem, 6vw, 4rem) clamp(1.5rem, 5vw, 4rem);
@@ -134,6 +150,12 @@
134
150
  color: var(--text-subtle);
135
151
  margin-bottom: 0.75rem;
136
152
  }
153
+ .cmd-group-note {
154
+ font-size: 0.78rem;
155
+ color: var(--text-subtle);
156
+ margin: -0.5rem 0 0.75rem 0;
157
+ font-style: italic;
158
+ }
137
159
  .cmd {
138
160
  display: flex;
139
161
  gap: 1rem;
@@ -150,7 +172,7 @@
150
172
  font-size: 0.85rem;
151
173
  color: var(--teal);
152
174
  white-space: nowrap;
153
- min-width: 160px;
175
+ min-width: 200px;
154
176
  }
155
177
  .cmd-desc {
156
178
  font-size: 0.85rem;
@@ -244,6 +266,14 @@
244
266
  color: var(--text-subtle);
245
267
  }
246
268
  .footer strong { color: var(--teal); font-weight: 500; }
269
+ .footer-version {
270
+ display: block;
271
+ margin-top: 0.5rem;
272
+ font-family: var(--font-mono);
273
+ font-size: 0.7rem;
274
+ color: var(--text-subtle);
275
+ letter-spacing: 0.04em;
276
+ }
247
277
 
248
278
  /* ─── Responsive ─────────────────────────── */
249
279
  @media (max-width: 640px) {
@@ -251,6 +281,7 @@
251
281
  .cmd-name { min-width: unset; }
252
282
  .road { flex-direction: column; align-items: flex-start; }
253
283
  .road-arrow { display: none; }
284
+ .version-pill { top: 0.5rem; right: 0.5rem; font-size: 0.65rem; }
254
285
  }
255
286
 
256
287
  @media (prefers-reduced-motion: reduce) {
@@ -260,11 +291,13 @@
260
291
  </head>
261
292
  <body>
262
293
 
294
+ <div class="version-pill">v3.6.0</div>
295
+
263
296
  <div class="header">
264
297
  <div class="header-content">
265
298
  <h1><span>Qualia</span> Framework</h1>
266
299
  <p>Plan, build, verify, ship. The AI-powered workflow for Qualia Solutions.</p>
267
- <div class="version">v{{VERSION}}</div>
300
+ <div class="version">v3.6.0 &middot; 26 skills</div>
268
301
  </div>
269
302
  </div>
270
303
 
@@ -293,73 +326,106 @@
293
326
  </div>
294
327
  </section>
295
328
 
296
- <!-- Commands -->
329
+ <!-- Skills -->
297
330
  <section>
298
- <h2>Commands</h2>
331
+ <h2>Skills (26)</h2>
299
332
 
333
+ <!-- Road (core flow) -->
300
334
  <div class="cmd-group">
301
- <h3>Navigation</h3>
335
+ <h3>Road &mdash; Core Flow</h3>
336
+ <p class="cmd-group-note">The seven steps every project walks through.</p>
337
+ <div class="commands">
338
+ <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Set up a new project from scratch &mdash; deep questioning, parallel research, REQUIREMENTS.md, ROADMAP.md, approval gate. Use when starting any new client project.</span></div>
339
+ <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
340
+ <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Execute the current phase &mdash; spawns builder subagents per task with wave-based parallelization. Fresh context per task.</span></div>
341
+ <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Goal-backward verification &mdash; checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent.</span></div>
342
+ <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
343
+ <div class="cmd"><span class="cmd-name">/qualia-ship</span><span class="cmd-desc">Deploy to production &mdash; quality gates, commit, push, deploy, verify. Use when ready to go live.</span></div>
344
+ <div class="cmd"><span class="cmd-name">/qualia-handoff</span><span class="cmd-desc">Client delivery &mdash; credentials, handover doc, final update. Use after shipping.</span></div>
345
+ </div>
346
+ </div>
347
+
348
+ <!-- Phase Depth (optional) -->
349
+ <div class="cmd-group">
350
+ <h3>Phase Depth &mdash; Optional</h3>
351
+ <p class="cmd-group-note">Used before / around /qualia-plan when a phase needs deeper context.</p>
302
352
  <div class="commands">
303
- <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">What should I do next? Reads project state, tells you the exact command.</span></div>
304
- <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Same as /qualia. For when you're stuck.</span></div>
305
- <div class="cmd"><span class="cmd-name">/qualia-resume</span><span class="cmd-desc">Pick up where you left off from a previous session.</span></div>
306
- <div class="cmd"><span class="cmd-name">/qualia-pause</span><span class="cmd-desc">Save progress. Creates .continue-here.md for next session.</span></div>
353
+ <div class="cmd"><span class="cmd-name">/qualia-discuss</span><span class="cmd-desc">Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input.</span></div>
354
+ <div class="cmd"><span class="cmd-name">/qualia-research</span><span class="cmd-desc">Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md.</span></div>
355
+ <div class="cmd"><span class="cmd-name">/qualia-map</span><span class="cmd-desc">Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects &mdash; run BEFORE /qualia-new so Validated requirements get inferred from existing code.</span></div>
356
+ <div class="cmd"><span class="cmd-name">/qualia-milestone</span><span class="cmd-desc">Close out a completed milestone and prep the next one. Archives the current milestone's artifacts, updates REQUIREMENTS.md to mark v1 requirements Complete, and creates the next milestone roadmap.</span></div>
307
357
  </div>
308
358
  </div>
309
359
 
360
+ <!-- Quality -->
310
361
  <div class="cmd-group">
311
- <h3>Project Setup</h3>
362
+ <h3>Quality</h3>
363
+ <p class="cmd-group-note">Diagnose, audit, optimize, polish, test.</p>
312
364
  <div class="commands">
313
- <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Interactive wizard. Asks about client, scope, design, stack. Creates everything.</span></div>
365
+ <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken'.</span></div>
366
+ <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check'.</span></div>
367
+ <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep optimization pass &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Supports --perf, --ui, --backend, --alignment, --fix flags.</span></div>
368
+ <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
369
+ <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'test coverage'.</span></div>
314
370
  </div>
315
371
  </div>
316
372
 
373
+ <!-- Quick Paths -->
317
374
  <div class="cmd-group">
318
- <h3>Build Loop</h3>
375
+ <h3>Quick Paths</h3>
376
+ <p class="cmd-group-note">Lightweight alternatives when the full road is overkill.</p>
319
377
  <div class="commands">
320
- <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase. AI generates tasks with success criteria.</span></div>
321
- <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Build it. Fresh AI agent per task, parallel waves.</span></div>
322
- <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Verify it actually works. Greps code, scores on 4 dimensions.</span></div>
378
+ <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Fast path for small tasks &mdash; bug fixes, tweaks, hot fixes. Skips full phase planning.</span></div>
379
+ <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">Build a single task &mdash; more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task.</span></div>
380
+ <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design transformation &mdash; critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional.</span></div>
323
381
  </div>
324
382
  </div>
325
383
 
384
+ <!-- Knowledge -->
326
385
  <div class="cmd-group">
327
- <h3>Quick Work</h3>
386
+ <h3>Knowledge</h3>
387
+ <p class="cmd-group-note">Persist learnings and log work.</p>
328
388
  <div class="commands">
329
- <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Skip planning. For bug fixes, tweaks, hot fixes under 1 hour.</span></div>
330
- <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">One focused task. More structured than quick, lighter than build.</span></div>
389
+ <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions.</span></div>
390
+ <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Generate session report and commit to repo. Mandatory before clock-out.</span></div>
331
391
  </div>
332
392
  </div>
333
393
 
394
+ <!-- Session -->
334
395
  <div class="cmd-group">
335
- <h3>Design & Quality</h3>
396
+ <h3>Session</h3>
397
+ <p class="cmd-group-note">Hand off and resume context cleanly.</p>
336
398
  <div class="commands">
337
- <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design fix. Reads DESIGN.md, kills AI slop, makes it professional.</span></div>
338
- <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Full design pass. Typography, color, states, motion, a11y, responsive, hardening.</span></div>
339
- <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit. Security, performance, reliability. Scored diagnostics.</span></div>
399
+ <div class="cmd"><span class="cmd-name">/qualia-pause</span><span class="cmd-desc">Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off.</span></div>
400
+ <div class="cmd"><span class="cmd-name">/qualia-resume</span><span class="cmd-desc">Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action.</span></div>
340
401
  </div>
341
402
  </div>
342
403
 
404
+ <!-- Navigation -->
343
405
  <div class="cmd-group">
344
- <h3>Ship & Deliver</h3>
406
+ <h3>Navigation</h3>
407
+ <p class="cmd-group-note">When you don't know what to do next.</p>
345
408
  <div class="commands">
346
- <div class="cmd"><span class="cmd-name">/qualia-ship</span><span class="cmd-desc">Quality gates, commit, push, deploy to Vercel, post-deploy verification.</span></div>
347
- <div class="cmd"><span class="cmd-name">/qualia-handoff</span><span class="cmd-desc">Client delivery. Credentials, docs, handover package.</span></div>
348
- <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Log your session. Mandatory before clock-out. Uploads to ERP.</span></div>
409
+ <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">Smart router &mdash; reads project state, classifies your situation, tells you the exact next command. Use whenever you're unsure about your next step.</span></div>
410
+ <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations.</span></div>
411
+ <div class="cmd"><span class="cmd-name">/qualia-help</span><span class="cmd-desc">Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road.</span></div>
349
412
  </div>
350
413
  </div>
351
414
 
415
+ <!-- Meta -->
352
416
  <div class="cmd-group">
353
- <h3>Debugging & Learning</h3>
417
+ <h3>Meta</h3>
418
+ <p class="cmd-group-note">Extend the framework itself.</p>
354
419
  <div class="commands">
355
- <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging. Symptom &rarr; diagnosis &rarr; root cause &rarr; fix.</span></div>
356
- <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a pattern, fix, or client preference to the knowledge base.</span></div>
357
- <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests. Auto-detects framework.</span></div>
420
+ <div class="cmd"><span class="cmd-name">/qualia-skill-new</span><span class="cmd-desc">Author a new Qualia skill or agent. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo.</span></div>
358
421
  </div>
359
422
  </div>
423
+ </section>
360
424
 
425
+ <!-- CLI -->
426
+ <section>
427
+ <h2>CLI (Terminal)</h2>
361
428
  <div class="cmd-group">
362
- <h3>CLI (Terminal)</h3>
363
429
  <div class="commands">
364
430
  <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
365
431
  <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
@@ -470,6 +536,7 @@
470
536
  <div class="footer">
471
537
  <strong>Welcome to the future with Qualia.</strong><br>
472
538
  Qualia Solutions &mdash; Nicosia, Cyprus
539
+ <span class="footer-version">qualia-framework v3.6.0 &middot; 26 skills</span>
473
540
  </div>
474
541
 
475
542
  </body>
package/templates/tracking.json CHANGED
@@ -3,6 +3,10 @@
3
3
  "client": "",
4
4
  "type": "",
5
5
  "assigned_to": "",
6
+ "team_id": "",
7
+ "project_id": "",
8
+ "git_remote": "",
9
+ "milestone": 1,
6
10
  "phase": 0,
7
11
  "phase_name": "",
8
12
  "total_phases": 0,
@@ -13,8 +17,20 @@
13
17
  "verification": "pending",
14
18
  "gap_cycles": {},
15
19
  "blockers": [],
20
+ "session_started_at": "",
16
21
  "last_updated": "",
22
+ "last_pushed_at": "",
17
23
  "last_commit": "",
24
+ "build_count": 0,
25
+ "deploy_count": 0,
18
26
  "deployed_url": "",
19
- "notes": ""
27
+ "notes": "",
28
+ "submitted_by": "",
29
+ "lifetime": {
30
+ "tasks_completed": 0,
31
+ "phases_completed": 0,
32
+ "milestones_completed": 0,
33
+ "total_phases": 0,
34
+ "last_closed_milestone": 0
35
+ }
20
36
  }