Qualia Framework v6.2.7

A harness engineering framework for Claude Code and OpenAI Codex. It installs into ~/.claude/ and/or ~/.codex/ and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.

It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."

v6.2.7 — Codex runtime compatibility. The installer now writes Codex-native hooks, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config under ~/.codex/, not just AGENTS.md.

The v5 line (preserved):

• v5.0, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, /qualia-zoom, /qualia-issues, /qualia-triage, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
• v5.1, autonomous visual-polish loop. Screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
• v5.2, polish-loop reliability. --reduced-motion capture flag, --routes URL1,URL2 multi-route mode, first supervised end-to-end run.
• v5.3, Matt Pocock gaps closed. /qualia-hook-gen (CLAUDE.md instruction to deterministic Claude Code hook), /qualia-optimize --deepen Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
• v5.4-5.5, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
• v5.6, Demo vs Full Project gate at kickoff. Mandatory discovery interview via /qualia-discuss in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in /qualia-milestone for client-signs-after-demo conversion.
• v5.7, /qualia-feature consolidates /qualia-quick + /qualia-task into one auto-scoped command.
• v5.8, surface cleanup. /qualia-polish --loop replaces /qualia-polish-loop. /qualia-quick, /qualia-task, and /qualia-prd removed (deprecated in v5.7).
• v5.9, deep-research fixes. Surface-drift test (tests/refs.test.sh) catches dead command references on every release. ERP report retry queue (bin/erp-retry.js) replaces the v5.8 lying retry message with a real persistent queue. Four structured agents (verifier, plan-checker, roadmapper, qa-browser) move to Sonnet for ~40% per-phase cost cut. Verifier downgrades to FAIL on any INSUFFICIENT EVIDENCE line, closing the false-pass vector.
• v5.9.1, kickoff UX fix. /qualia-new now opens with the Demo/Full/Quick gate as Step 1 (AskUserQuestion), then exactly one free-text pitch question, then mandatory hand-off to /qualia-discuss — no ad-hoc clarification questioning between them. The shape gate drives the whole downstream interview, so it must come first.
• v5.9.2, hook ordering + ERP payload fixes. pre-push.js self-gates against branch-guard.js so a blocked-push no longer leaves an orphan bot commit in local history. qualia-report ERP payload omits empty ISO datetime fields (session_started_at, last_pushed_at) instead of sending '', which the ERP validator rejected as 422.
• v6.0.0, audit + cleanup pass. See CHANGELOG for the full list. Highlights: uninstall/migrate manifests fixed, silent hook catch{} blocks now traced, phantom rules/frontend.md references replaced, /qualia-learn and /qualia-map declare their actually-used tools, /qualia-plan revision-cycle contradiction reconciled (max 2), agents/planner.md and agents/qa-browser.md MCP tools declared in frontmatter, rules/trust-boundary.md extracted, hardcoded /tmp paths replaced with mktemp, fail-collect test runner, pre-v4 CHANGELOG archived.
• v6.1.0, /qualia-vibe adds a fast layout-preserving design pivot path and strengthens design-surface guards.
• v6.2.0, removes hook-created bot commits. The ERP/report contract is /qualia-report POSTs, not passive git scraping of tracking.json.
• v6.2.1, active-surface drift guard. README, guide, onboarding, ERP contract, road, milestone, polish, verify, and roadmapper wording now align with v6.2 behavior; refs tests fail on the stale claims.
• v6.2.2, Framework/Memory/ERP clarity. ERP can hand a work packet into Framework sessions, reports can carry ERP-native IDs, and public npm install proof is a first-class release smoke.
• v6.2.3, ERP ID guard. ERP-native IDs are UUID-only in report payloads; slugs remain in project_id/team_id.
• v6.2.4, report payload contract. The ERP payload builder is now a shipped, tested script instead of shell-embedded inline code.
• v6.2.5, project snapshot export. Framework can write .planning/snapshots/project-snapshot-*.json for explicit ERP/admin import.
• v6.2.6, project snapshot upload. Framework can POST that project snapshot directly to ERP's project snapshot intake.
• v6.2.7, Codex runtime compatibility. Codex installs now get native hooks.json, agents/*.toml, runtime scripts, rules, skills, templates, knowledge, guide, and config under ~/.codex/.

The Full Journey architecture carries forward: /qualia-new maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in --auto mode with only two human gates per project.

Don't run Claude's /init in a Qualia project

Claude Code's built-in /init generates a bloated CLAUDE.md summary that consumes instruction budget on every future session and rots within a sprint. Qualia takes the opposite approach (per Matt Pocock's Never run /init): keep the global system prompt minimal, push steering into discoverable skills, push procedural rules into hooks. Use /qualia-new for a greenfield project or /qualia-map to onboard an existing brownfield repo. Do not run Claude's /init afterward — it will overwrite the slim template with sprawl.

Install

npx qualia-framework@latest install

Enter your team code when prompted. Get your code from Fawzi.

Why @latest? npx caches packages at ~/.npm/_npx/ and has no time-based TTL — npx qualia-framework install (without @latest) will silently run whatever version you happened to fetch the first time, even if a newer one shipped. Always pin @latest when installing or upgrading. If a stale cache still bites you: npx clear-npx-cache then re-run.

Other commands:

npx qualia-framework@latest version    # Check installed version + updates
npx qualia-framework@latest update     # Update to latest (remembers your code)
npx qualia-framework@latest uninstall  # Clean removal from installed Claude/Codex homes
npx qualia-framework@latest team list  # Show team members
npx qualia-framework@latest team add   # Add a team member
npx qualia-framework@latest traces     # View recent hook telemetry

Usage

Open Claude Code or Codex in any project directory.

New to Qualia? Open docs/onboarding.html in a browser for a one-page roadmap of the golden path. Best file to send a new hire.

The Road — guided mode (default)

/qualia-new         # Set up a project: questioning + research + JOURNEY.md with all milestones → Handoff
/qualia-plan N      # Plan phase N of the current milestone (story-file format, plan-checker validation loop)
/qualia-build N     # Build phase N (builder subagents with pre-inlined context, wave-based parallel tasks)
/qualia-verify N    # Verify phase N works (goal-backward + per-task acceptance criteria + browser QA)
...repeat plan/build/verify per phase...
/qualia-milestone   # Close current milestone, open next (loads next scope from JOURNEY.md)
...repeat per milestone until the final "Handoff" milestone...
/qualia-polish      # Design pass — flexible scope: component, route, app, redesign, critique, quick
/qualia-ship        # Deploy to production
/qualia-handoff     # Enforce the 4 mandatory handoff deliverables
/qualia-report      # Mandatory shift report + ERP upload before clock-out

The Road — auto mode

/qualia-new --auto

Research runs automatically. User approves the full journey once. Framework chains plan → build → verify → (next phase) → ... → milestone boundary. User approves continuation per milestone. Framework resumes, eventually reaches the Handoff milestone's last phase → ship → handoff → report. Done.

Two human gates per project. One halt case (gap-cycle limit exceeded on a failing phase).

Phase-specific depth (optional)

/qualia-discuss N   # Capture decisions before planning a complex phase (locks constraints for the planner)
/qualia-research N  # Deep-research a niche phase (Context7/WebFetch/WebSearch)
/qualia-map         # Map existing codebase (brownfield projects — run before /qualia-new)

Navigation & state

/qualia           # Mechanical state router — "what's my next command?"
/qualia-idk       # Diagnostic — "what's actually going on?" Two isolated scans (planning / codebase), then a plain-language explanation
/qualia-pause     # Save session, continue later
/qualia-resume    # Pick up where you left off

Quality & shortcuts

/qualia-debug         # Structured debugging
/qualia-review        # Production audit (scored diagnostics)
/qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
/qualia-feature       # Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files)
/qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
/qualia-zoom          # Focus on a single file or function with full context
/qualia-issues        # Break a phase plan into vertical-slice GitHub issues
/qualia-triage        # Triage open issues through the ready-for-agent state machine
/qualia-road          # View and navigate the project road (journey/milestone/phase status)
/qualia-polish --loop # Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat
/qualia-vibe          # Fast aesthetic pivot (~3 min): swap design tokens, keep layout. Supports --extract URL (reverse-engineer DESIGN.md) and --sync (code → DESIGN.md back-sync)
/qualia-hook-gen      # Convert a CLAUDE.md/rules instruction into a deterministic hook

Knowledge & meta

/qualia-learn      # Save a pattern, fix, or client pref to the active install home's knowledge/
/qualia-flush      # Promote daily-log raw entries into curated knowledge concepts
/qualia-postmortem # Self-heal — when verification fails, propose rule/skill deltas
/qualia-skill-new  # Author a new Qualia skill or agent
/qualia-help       # Open the framework reference in your browser

Team-specific

/zoho-workflow    # Zoho Invoice + Mail integration (internal Qualia Solutions ops)

See guide.md for the full developer guide.

The Full Journey

Every project has a .planning/JOURNEY.md — the North Star document that maps the entire arc from kickoff to client handoff.

Project
└─ Journey (all milestones defined upfront)
   └─ Milestone (a release — 2-5 total, Handoff is always last)
      └─ Phase (a feature-sized deliverable, 2-5 internal tasks)
         └─ Task (framework-internal unit, one commit, one verification contract)

Hard rules:

• Hard floor: 2 milestones. Hard ceiling: 5.
• Final milestone is always literally named "Handoff" with 4 fixed phases (Polish, Content + SEO, Final QA, Handoff).
• Every non-Handoff milestone needs ≥ 2 phases (enforced by state.js close-milestone).
• Milestone numbering is contiguous.

Why it matters: non-technical team members can follow the ladder from any entry point. /qualia and /qualia-milestone render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.

What's Inside (v6.2.7)

• 33 skills, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with --deepen parallel-interface design, feature, test, zoom, issues, triage), design (qualia-polish --loop, qualia-vibe for fast aesthetic pivots), deterministic enforcement (qualia-hook-gen), and meta (learn, skill-new, flush, postmortem)
• 9 agents (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
• 11 hooks (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
• 7 always-loaded rules + 1 lazy-loaded (rules/): grounding, security, infrastructure, deployment, speed (CLI-first / MCP tier-list), architecture (deep modules / scout-for-shallow-code), trust-boundary (shared injection-defence — extracted from agents in v6.0). Lazy-loaded by design-adjacent skills: one-opinion (EventMaster discipline — propose ONE direction, never a menu; new in v6.1)
• 6 lazy-loaded design files (qualia-design/): design-laws, design-brand, design-product, design-rubric, design-reference, frontend — Read on demand by design-aware skills/agents only, ~22 KB recovered from the always-loaded budget
• 25 template files: project.md, journey.md, plan.md (story-file format), state.md, DESIGN.md, CONTEXT.md (domain glossary), work-packet.md (ERP-approved session context), decisions/ADR-template.md, tracking.json (with milestone_name + milestones[]), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
• 1 reference — questioning.md methodology for deep project initialization
• Codex-native install surface — ~/.codex/AGENTS.md, hooks.json, hooks/, agents/*.toml, bin/, rules/, skills/, qualia-design/, qualia-templates/, knowledge/, and qualia-guide.md.

Supported Platforms

Works on Windows 10/11, macOS, and Linux. Requires Node.js 18+ and Claude Code or OpenAI Codex.

• Every hook and the status line are pure Node.js — no external bash, jq, or GNU coreutils required.
• Skills are installed as Markdown instructions with Node.js helpers; Claude and Codex each receive paths native to their own home directory.
• Codex installs use Codex-native hook status messages and agent TOML files; Codex does not expose a Claude-style global statusLine setting, so statusline.js is installed as a shared renderer/helper instead of a fake config key.
• Tested on Fedora, EndeavourOS, macOS, and Windows 10/11.

Why It Works

Full Journey

/qualia-new maps every milestone from kickoff to handoff. Team members see the entire ladder before climbing. No improvising the next chunk after each ship. The final milestone is always "Handoff" with 4 mandatory deliverables (verified production URL, updated docs, archived client assets, final ERP report) — so the path to "shipped" is visible from day 1.

Auto-Chain End-to-End

--auto mode chains /qualia-plan → /qualia-build → /qualia-verify → … without re-typing commands. The framework pauses only at real decisions: journey approval at kickoff, each milestone boundary, and one halt on gap-cycle-limit failures. Everything in between runs on rails.

Goal-Backward Verification

Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier scores on 4 dimensions (Correctness, Completeness, Wiring, Quality), each 1–5, with a hard threshold at 3. It doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports, and walks each task's observable Acceptance Criteria.

Story-File Plans (Plans Are Prompts)

Plan files aren't documents that get translated into prompts — they ARE the prompts. Every task carries inline Why (rationale), Acceptance Criteria (observable user behaviors), Depends on (explicit ordering), and Validation (self-check commands) before the builder touches code. @file references tell the orchestrator what to pre-inline into the builder's prompt, saving 3-5 orientation Read calls per task.

Agent Separation

Splitting planner, builder, and verifier into separate agents with separate contexts prevents the "God prompt" problem. Each agent gets fresh context. Task 50 gets the same quality as task 1.

Production-Grade Hooks

All 11 hooks are real ops engineering, not theoretical:

• Pre-deploy gate — TypeScript, lint, tests, build, and service_role leak scan before vercel --prod
• Session start — Shows project state, next command, update notices, and health warnings at session start
• Auto-update — Daily update check with cached failures so offline/npm issues do not slow every command
• Git guardrails — Blocks destructive git operations like force-push to main/master, git clean -fd, and rm -rf .git
• Branch guard — Role-aware: owner can push to main, employees can't (parses refspec so feature/x:main bypass is blocked)
• Migration guard — Catches DROP TABLE without IF EXISTS, DELETE/UPDATE without WHERE, CREATE TABLE without RLS, GRANT ... TO PUBLIC, ALTER TABLE ... DROP COLUMN
• Pre-push — Stamps tracking.json locally for statusline, stop-session-log, and /qualia-report; does not create commits
• Stop-session log — Writes lightweight daily session checkpoints into the knowledge layer
• Vercel account guard — Verifies the correct Vercel account is active before deploy
• Env-empty guard — Catches empty or placeholder environment variables before they reach production
• Supabase destructive guard — Blocks destructive Supabase commands (DROP, TRUNCATE) without safety clauses

Enforced State Machine

Every workflow step calls state.js — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. Milestone readiness guards ensure close-milestone refuses to close a milestone with unverified phases or < 2 phases (unless --force), and appends a summary to tracking.json.milestones[] for local status, reports, and future explicit integrations.

Wave-Based Parallelization

Plans are grouped into waves for parallel execution. No fancy DAG solver — the planner assigns wave numbers, the orchestrator spawns agents per wave. Pragmatic over clever.

Diagnostic Intelligence

/qualia-idk is a real diagnostician (not a router alias). When the user's confusion is about understanding the situation, it spawns two isolated scans in parallel — one reads only .planning/, the other reads only source code — then synthesizes a plain-language "What I see / What I think is happening / What to do next" diagnosis. Catches plan↔code drift that a state-only router can't see.

Architecture

npx qualia-framework@latest install
     |
     v
~/.claude/ and/or ~/.codex/
  ├── skills/             33 slash commands (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
  ├── agents/             9 agent definitions (Claude .md, Codex .toml)
  ├── hooks/              11 Node.js hooks — cross-platform (no bash dependency)
  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + plan-contract.js + agent-runs.js + ERP/report helpers
  ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md, daily-log/
  ├── rules/              grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, one-opinion
  ├── qualia-design/      lazy-loaded design substrate — read on demand
  ├── qualia-templates/   project, journey, plan, state, DESIGN, CONTEXT, work-packet, decisions, tracking, requirements, roadmap, research, help
  ├── qualia-references/  questioning.md (deep project initialization methodology)
  ├── CLAUDE.md or AGENTS.md
  └── settings.json or hooks.json wired for native hooks/status messages

For Qualia Solutions Team

Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLabs, Telnyx. AI: OpenRouter. Compute: Railway (agents/background jobs).

Changelog

See CHANGELOG.md for the full version history.

Built by Qualia Solutions — Nicosia, Cyprus.