{"id":16186,"library":"qualia-framework","title":"Qualia Framework","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/Qualiasolutions/qualia-framework","tags":["javascript","claude-code","claude","ai","framework","workflow","qualia","agents","automation"],"install":[{"cmd":"npm install qualia-framework","lang":"bash","label":"npm"},{"cmd":"yarn add qualia-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add qualia-framework","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"# Install the Qualia Framework globally using npx.\n# It's crucial to use '@latest' to prevent npx from running a stale, cached version.\nnpx qualia-framework@latest install\n\n# When prompted during installation, you will need to enter your team code (e.g., from 'Fawzi').\n\n# Navigate to your project directory where you want to start a new AI-assisted project.\ncd my-new-ai-project\n\n# Within Claude Code, initiate a new project in fully automatic mode.\n# This command orchestrates the entire project journey from kickoff to client handoff,\n# automatically chaining planning, building, and verification phases per milestone.\n# Human approval is typically required only at the project start and at each milestone boundary.\n/qualia-new --auto\n\n# If you need to diagnose the current state or understand the next steps within Claude Code:\n/qualia-idk\n\n# To check the installed Qualia Framework version or for updates outside of Claude Code:\nnpx qualia-framework@latest version","lang":"bash","description":"Demonstrates the initial installation, team code requirement, and a full automatic project setup within Claude Code."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<18.0.0 (Node.js)"},{"fix":"Contact Qualia Solutions or the designated team lead (e.g., 'Fawzi') to acquire the necessary team code before attempting installation.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The framework's core files in `~/.claude/` are missing, damaged, or the initial installation failed.","error":"Error: `qualia-framework` is not installed or `~/.claude/` directory is corrupted."},{"fix":"Re-run the installation `npx qualia-framework@latest install` and ensure you accurately enter the valid team code when prompted.","cause":"The installer prompted for a team code, but no input was provided or an invalid code was entered.","error":"Error: Team code required for installation. Please provide your team code."},{"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.","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.","error":"Phase N failed: Gap-cycle limit exceeded."}],"ecosystem":"npm"}