Qualia Framework

4.1.0 · active · verified Tue Apr 21

Qualia Framework, currently at version 4.1.0, is a specialized harness engineering framework designed to structure and streamline AI-assisted development workflows, specifically with Claude Code. It installs into the user's `~/.claude/` directory and acts as an opinionated workflow layer, guiding Claude through a complete project lifecycle from initial concept to client handoff. Unlike traditional application frameworks, Qualia Framework does not generate code, run servers, or process data; instead, it focuses on enforcing a structured process of planning, execution, verification, and deployment. Version 4, dubbed the 'Full Journey release,' introduces end-to-end project mapping from kickoff to handoff, allowing for highly automated workflows with minimal human intervention, often requiring only two human gates per project in `--auto` mode. Key features include a story-file plan format, goal-backward verification, and a 4-dimension scoring rubric. While a specific release cadence isn't published, its reliance on `npx @latest` for updates suggests an active development cycle. The framework differentiates itself by providing a robust, opinionated scaffolding for managing complex AI development projects, emphasizing process over code generation.

Common errors

```
Error: `qualia-framework` is not installed or `~/.claude/` directory is corrupted.
```
cause The framework's core files in `~/.claude/` are missing, damaged, or the initial installation failed.

fix Re-run the installation command: `npx qualia-framework@latest install`. If the issue persists, consider `npx qualia-framework@latest uninstall` followed by a fresh install.
```
Error: Team code required for installation. Please provide your team code.
```
cause The installer prompted for a team code, but no input was provided or an invalid code was entered.

fix Re-run the installation `npx qualia-framework@latest install` and ensure you accurately enter the valid team code when prompted.
```
Phase N failed: Gap-cycle limit exceeded.
```
cause During `--auto` mode execution, the AI agent repeatedly failed to resolve issues or meet acceptance criteria for a specific phase (N), hitting an internal retry limit.

fix This indicates a significant blockage or misunderstanding for the AI. Switch to guided mode to manually debug the problematic phase. Use `/qualia-discuss N` to capture new constraints, `/qualia-debug` for structured diagnostics, or `/qualia-plan N` to replan more carefully.

Warnings

gotcha When using `npx` to install or run `qualia-framework` commands, always explicitly include `@latest` (e.g., `npx qualia-framework@latest install`). Npm's `npx` cache does not have a time-based TTL and can silently run an outdated version if `@latest` is omitted, even if a newer version exists.
Fix: Always append `@latest` to your `npx` commands (e.g., `npx qualia-framework@latest install`). If a stale cache persists, clear it with `npx clear-npx-cache` before re-running.
gotcha The framework requires Node.js version 18 or newer to operate correctly, as specified by its `engines` field. Running on older Node.js versions may lead to unexpected errors or installation failures.
Fix: Ensure your Node.js environment is updated to version 18 or greater. You can use a tool like `nvm` to manage multiple Node.js versions.
gotcha Installation of the Qualia Framework requires a 'team code'. This code is not publicly available and must be obtained from the Qualia Solutions team (e.g., 'Fawzi'), acting as a gate for access.
Fix: Contact Qualia Solutions or the designated team lead (e.g., 'Fawzi') to acquire the necessary team code before attempting installation.

Install

npm install qualia-framework npm
yarn add qualia-framework yarn
pnpm add qualia-framework pnpm

Quickstart

Demonstrates the initial installation, team code requirement, and a full automatic project setup within Claude Code.

# Install the Qualia Framework globally using npx.
# It's crucial to use '@latest' to prevent npx from running a stale, cached version.
npx qualia-framework@latest install

# When prompted during installation, you will need to enter your team code (e.g., from 'Fawzi').

# Navigate to your project directory where you want to start a new AI-assisted project.
cd my-new-ai-project

# Within Claude Code, initiate a new project in fully automatic mode.
# This command orchestrates the entire project journey from kickoff to client handoff,
# automatically chaining planning, building, and verification phases per milestone.
# Human approval is typically required only at the project start and at each milestone boundary.
/qualia-new --auto

# If you need to diagnose the current state or understand the next steps within Claude Code:
/qualia-idk

# To check the installed Qualia Framework version or for updates outside of Claude Code:
npx qualia-framework@latest version

view raw JSON →