Registry / llm-agents / qualia-framework-v2

qualia-framework-v2

library3.0.0jsnpmunverified

Qualia Framework v3 is a harness engineering framework designed to structure and enhance AI-assisted development workflows within Claude Code. It provides an opinionated layer for planning, execution, verification, and deployment, moving beyond simple code generation to a structured project lifecycle. Currently at version 3.0.0, the framework integrates concepts from Anthropic's "Harness Design for Long-Running Apps," focusing on goal-backward verification, distinct agent separation (planner, builder, verifier), and robust Node.js-based hooks. It is not an application framework like Next.js; rather, it directs Claude's actions via a set of 19 slash commands ("skills") and manages project state, telemetry, and team interactions. Its release cadence follows major architectural improvements, with v3 incorporating significant lessons from prior iterations. Key differentiators include its verification contracts, agent-specific contexts to prevent "God prompt" issues, and cross-platform compatibility for its Node.js hooks. It runs on Node.js 18+.

llm-agents devops workflow

npm install qualia-framework-v2

INSTALL

IMPORT

SIG · QUALIA-FRAMEWORK-V

qualia-framework-v2

llm-agentsjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Installs the Qualia Framework CLI tool and explains how to interact with it via slash commands within Claude Code.

npx qualia-framework-v2 install # Follow prompts for team code. # After installation, open Claude Code in any project directory # and use the framework's slash commands directly in Claude's chat interface: # # /qualia-new # Set up a new project # /qualia-plan # Plan the current phase # /qualia-build # Build it (parallel tasks) # /qualia-verify # Verify it actually works

qualia --version

Debug

Known issues

gotchaQualia Framework v3 is a workflow layer for Claude Code, not an application framework like Next.js or Rails. It does not generate code, run servers, or process data directly, but rather orchestrates Claude's development process.

fix

Understand its role as an orchestration tool within Claude Code for structured AI-assisted development.

affects: >=3.0.0

breakingThe framework requires Node.js version 18 or higher. Installations on older Node.js versions will fail or result in unexpected behavior.

fix

Ensure Node.js v18 or newer is installed. Use `node -v` to check your version and upgrade if necessary.

affects: <3.0.0 (for Node versions <18)

gotchaThis framework is a companion to the Claude Code application and requires it to be installed and accessible. Without Claude Code, the framework's core slash commands are non-functional.

fix

Install and configure Claude Code according to Anthropic's documentation before using the Qualia Framework.

affects: >=3.0.0

gotchaThe framework installs its core components into the `~/.claude/` directory rather than a standard `node_modules` location. This is by design for integration with Claude Code.

fix

Be aware of the installation path; do not manually delete or move files within `~/.claude/` unless using `npx qualia-framework-v2 uninstall`.

affects: >=3.0.0

gotchaInitial installation via `npx qualia-framework-v2 install` requires a 'team code' for authentication and configuration. This code is usually provided by your organization (e.g., from 'Fawzi' as per the README).

fix

Obtain the correct team code from your administrator or team lead before attempting installation.

affects: >=3.0.0

gotchaThe primary interaction with the framework's 'skills' (e.g., `/qualia-new`, `/qualia-plan`) occurs as slash commands directly within the Claude Code chat interface, not as terminal commands in your shell.

fix

After installation, open Claude Code in your project directory and type the slash commands directly into its input field.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Minimum Node.js version not met. Expected >=18, got vX.Y.Z

Running the CLI tool with an unsupported Node.js version.

fix

Upgrade your Node.js environment to version 18 or newer (e.g., using `nvm install 18 && nvm use 18`).

Command failed: /bin/bash -c 'claude-code verify --version' (or similar error related to 'claude-code')

The Qualia Framework cannot detect or communicate with the Claude Code application.

fix

Ensure Claude Code is correctly installed and configured on your system's PATH. Restart your terminal or IDE.

Invalid team code. Please check your input and try again.

An incorrect or expired team code was entered during the `npx qualia-framework-v2 install` process.

fix

Re-run the installation command and enter the exact team code provided by your administrator. Verify its validity.

bash: /qualia-new: command not found (or similar for other /qualia- commands)

Attempting to run a Qualia Framework slash command directly in your operating system's terminal.

fix

These commands are internal to Claude Code. Open Claude Code in your project and type the `/qualia-command` directly into its chat interface.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.