Registry / llm-agents / qualia-framework

qualia-framework

JSON →
library4.1.0jsnpmunverified

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.

npm install qualia-framework
INSTALL
IMPORT
SIG · QUALIA-FRAMEWORK
Q
qualia-framework
llm-agentsjavascriptv4.1.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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
Debug
Known issues
gotchaWhen 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.
affects: >=1.0.0
gotchaThe 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.
affects: <18.0.0 (Node.js)
gotchaInstallation 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: `qualia-framework` is not installed or `~/.claude/` directory is corrupted.
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.
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.
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.
Upgrade
Version history
4.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
1
Resources
qualia-framework — npm install qualia-framework · libregistry