{"id":15170,"library":"qualia-framework-v2","title":"Qualia Framework v3 for Claude Code","description":"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+.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Qualiasolutions/qualia-framework-v2","tags":["javascript","claude-code","claude","ai","framework","workflow","qualia","agents","automation"],"install":[{"cmd":"npm install qualia-framework-v2","lang":"bash","label":"npm"},{"cmd":"yarn add qualia-framework-v2","lang":"bash","label":"yarn"},{"cmd":"pnpm add qualia-framework-v2","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"npx qualia-framework-v2 install\n# Follow prompts for team code.\n\n# After installation, open Claude Code in any project directory \n# and use the framework's slash commands directly in Claude's chat interface:\n#\n# /qualia-new       # Set up a new project\n# /qualia-plan      # Plan the current phase\n# /qualia-build     # Build it (parallel tasks)\n# /qualia-verify    # Verify it actually works","lang":"javascript","description":"Installs the Qualia Framework CLI tool and explains how to interact with it via slash commands within Claude Code."},"warnings":[{"fix":"Understand its role as an orchestration tool within Claude Code for structured AI-assisted development.","message":"Qualia 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure Node.js v18 or newer is installed. Use `node -v` to check your version and upgrade if necessary.","message":"The framework requires Node.js version 18 or higher. Installations on older Node.js versions will fail or result in unexpected behavior.","severity":"breaking","affected_versions":"<3.0.0 (for Node versions <18)"},{"fix":"Install and configure Claude Code according to Anthropic's documentation before using the Qualia Framework.","message":"This 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Be aware of the installation path; do not manually delete or move files within `~/.claude/` unless using `npx qualia-framework-v2 uninstall`.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Obtain the correct team code from your administrator or team lead before attempting installation.","message":"Initial 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).","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"After installation, open Claude Code in your project directory and type the slash commands directly into its input field.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or newer (e.g., using `nvm install 18 && nvm use 18`).","cause":"Running the CLI tool with an unsupported Node.js version.","error":"Error: Minimum Node.js version not met. Expected >=18, got vX.Y.Z"},{"fix":"Ensure Claude Code is correctly installed and configured on your system's PATH. Restart your terminal or IDE.","cause":"The Qualia Framework cannot detect or communicate with the Claude Code application.","error":"Command failed: /bin/bash -c 'claude-code verify --version' (or similar error related to 'claude-code')"},{"fix":"Re-run the installation command and enter the exact team code provided by your administrator. Verify its validity.","cause":"An incorrect or expired team code was entered during the `npx qualia-framework-v2 install` process.","error":"Invalid team code. Please check your input and try again."},{"fix":"These commands are internal to Claude Code. Open Claude Code in your project and type the `/qualia-command` directly into its chat interface.","cause":"Attempting to run a Qualia Framework slash command directly in your operating system's terminal.","error":"bash: /qualia-new: command not found (or similar for other /qualia- commands)"}],"ecosystem":"npm"}