qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/templates/codebase/stack.md

@@ -1,186 +0,0 @@
-# Technology Stack Template
-
-Template for `.planning/codebase/STACK.md` - captures the technology foundation.
-
-**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
-
----
-
-## File Template
-
-```markdown
-# Technology Stack
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Languages
-
-**Primary:**
-- [Language] [Version] - [Where used: e.g., "all application code"]
-
-**Secondary:**
-- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
-
-## Runtime
-
-**Environment:**
-- [Runtime] [Version] - [e.g., "Node.js 20.x"]
-- [Additional requirements if any]
-
-**Package Manager:**
-- [Manager] [Version] - [e.g., "npm 10.x"]
-- Lockfile: [e.g., "package-lock.json present"]
-
-## Frameworks
-
-**Core:**
-- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
-
-**Testing:**
-- [Framework] [Version] - [e.g., "Jest for unit tests"]
-- [Framework] [Version] - [e.g., "Playwright for E2E"]
-
-**Build/Dev:**
-- [Tool] [Version] - [e.g., "Vite for bundling"]
-- [Tool] [Version] - [e.g., "TypeScript compiler"]
-
-## Key Dependencies
-
-[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
-
-**Critical:**
-- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
-- [Package] [Version] - [Why it matters]
-
-**Infrastructure:**
-- [Package] [Version] - [e.g., "Express for HTTP routing"]
-- [Package] [Version] - [e.g., "PostgreSQL client"]
-
-## Configuration
-
-**Environment:**
-- [How configured: e.g., ".env files", "environment variables"]
-- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
-
-**Build:**
-- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
-
-## Platform Requirements
-
-**Development:**
-- [OS requirements or "any platform"]
-- [Additional tooling: e.g., "Docker for local DB"]
-
-**Production:**
-- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
-- [Version requirements]
-
----
-
-*Stack analysis: [date]*
-*Update after major dependency changes*
-```
-
-<good_examples>
-```markdown
-# Technology Stack
-
-**Analysis Date:** 2025-01-20
-
-## Languages
-
-**Primary:**
-- TypeScript 5.3 - All application code
-
-**Secondary:**
-- JavaScript - Build scripts, config files
-
-## Runtime
-
-**Environment:**
-- Node.js 20.x (LTS)
-- No browser runtime (CLI tool only)
-
-**Package Manager:**
-- npm 10.x
-- Lockfile: `package-lock.json` present
-
-## Frameworks
-
-**Core:**
-- None (vanilla Node.js CLI)
-
-**Testing:**
-- Vitest 1.0 - Unit tests
-- tsx - TypeScript execution without build step
-
-**Build/Dev:**
-- TypeScript 5.3 - Compilation to JavaScript
-- esbuild - Used by Vitest for fast transforms
-
-## Key Dependencies
-
-**Critical:**
-- commander 11.x - CLI argument parsing and command structure
-- chalk 5.x - Terminal output styling
-- fs-extra 11.x - Extended file system operations
-
-**Infrastructure:**
-- Node.js built-ins - fs, path, child_process for file operations
-
-## Configuration
-
-**Environment:**
-- No environment variables required
-- Configuration via CLI flags only
-
-**Build:**
-- `tsconfig.json` - TypeScript compiler options
-- `vitest.config.ts` - Test runner configuration
-
-## Platform Requirements
-
-**Development:**
-- macOS/Linux/Windows (any platform with Node.js)
-- No external dependencies
-
-**Production:**
-- Distributed as npm package
-- Installed globally via npm install -g
-- Runs on user's Node.js installation
-
----
-
-*Stack analysis: 2025-01-20*
-*Update after major dependency changes*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in STACK.md:**
-- Languages and versions
-- Runtime requirements (Node, Bun, Deno, browser)
-- Package manager and lockfile
-- Framework choices
-- Critical dependencies (limit to 5-10 most important)
-- Build tooling
-- Platform/deployment requirements
-
-**What does NOT belong here:**
-- File structure (that's STRUCTURE.md)
-- Architectural patterns (that's ARCHITECTURE.md)
-- Every dependency in package.json (only critical ones)
-- Implementation details (defer to code)
-
-**When filling this template:**
-- Check package.json for dependencies
-- Note runtime version from .nvmrc or package.json engines
-- Include only dependencies that affect understanding (not every utility)
-- Specify versions only when version matters (breaking changes, compatibility)
-
-**Useful for phase planning when:**
-- Adding new dependencies (check compatibility)
-- Upgrading frameworks (know what's in use)
-- Choosing implementation approach (must work with existing stack)
-- Understanding build requirements
-</guidelines>

package/framework/qualia-framework/templates/codebase/structure.md

@@ -1,285 +0,0 @@
-# Structure Template
-
-Template for `.planning/codebase/STRUCTURE.md` - captures physical file organization.
-
-**Purpose:** Document where things physically live in the codebase. Answers "where do I put X?"
-
----
-
-## File Template
-
-```markdown
-# Codebase Structure
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Directory Layout
-
-[ASCII box-drawing tree of top-level directories with purpose - use ├── └── │ characters for tree structure only]
-
-```
-[project-root]/
-├── [dir]/          # [Purpose]
-├── [dir]/          # [Purpose]
-├── [dir]/          # [Purpose]
-└── [file]          # [Purpose]
-```
-
-## Directory Purposes
-
-**[Directory Name]:**
-- Purpose: [What lives here]
-- Contains: [Types of files: e.g., "*.ts source files", "component directories"]
-- Key files: [Important files in this directory]
-- Subdirectories: [If nested, describe structure]
-
-**[Directory Name]:**
-- Purpose: [What lives here]
-- Contains: [Types of files]
-- Key files: [Important files]
-- Subdirectories: [Structure]
-
-## Key File Locations
-
-**Entry Points:**
-- [Path]: [Purpose: e.g., "CLI entry point"]
-- [Path]: [Purpose: e.g., "Server startup"]
-
-**Configuration:**
-- [Path]: [Purpose: e.g., "TypeScript config"]
-- [Path]: [Purpose: e.g., "Build configuration"]
-- [Path]: [Purpose: e.g., "Environment variables"]
-
-**Core Logic:**
-- [Path]: [Purpose: e.g., "Business services"]
-- [Path]: [Purpose: e.g., "Database models"]
-- [Path]: [Purpose: e.g., "API routes"]
-
-**Testing:**
-- [Path]: [Purpose: e.g., "Unit tests"]
-- [Path]: [Purpose: e.g., "Test fixtures"]
-
-**Documentation:**
-- [Path]: [Purpose: e.g., "User-facing docs"]
-- [Path]: [Purpose: e.g., "Developer guide"]
-
-## Naming Conventions
-
-**Files:**
-- [Pattern]: [Example: e.g., "kebab-case.ts for modules"]
-- [Pattern]: [Example: e.g., "PascalCase.tsx for React components"]
-- [Pattern]: [Example: e.g., "*.test.ts for test files"]
-
-**Directories:**
-- [Pattern]: [Example: e.g., "kebab-case for feature directories"]
-- [Pattern]: [Example: e.g., "plural names for collections"]
-
-**Special Patterns:**
-- [Pattern]: [Example: e.g., "index.ts for directory exports"]
-- [Pattern]: [Example: e.g., "__tests__ for test directories"]
-
-## Where to Add New Code
-
-**New Feature:**
-- Primary code: [Directory path]
-- Tests: [Directory path]
-- Config if needed: [Directory path]
-
-**New Component/Module:**
-- Implementation: [Directory path]
-- Types: [Directory path]
-- Tests: [Directory path]
-
-**New Route/Command:**
-- Definition: [Directory path]
-- Handler: [Directory path]
-- Tests: [Directory path]
-
-**Utilities:**
-- Shared helpers: [Directory path]
-- Type definitions: [Directory path]
-
-## Special Directories
-
-[Any directories with special meaning or generation]
-
-**[Directory]:**
-- Purpose: [e.g., "Generated code", "Build output"]
-- Source: [e.g., "Auto-generated by X", "Build artifacts"]
-- Committed: [Yes/No - in .gitignore?]
-
----
-
-*Structure analysis: [date]*
-*Update when directory structure changes*
-```
-
-<good_examples>
-```markdown
-# Codebase Structure
-
-**Analysis Date:** 2025-01-20
-
-## Directory Layout
-
-```
-qualia-framework/
-├── bin/                # Executable entry points
-├── commands/           # Slash command definitions
-│   └── qualia/           # Qualia-specific commands
-├── qualia-framework/     # Skill resources
-│   ├── references/    # Principle documents
-│   ├── templates/     # File templates
-│   └── workflows/     # Multi-step procedures
-├── src/               # Source code (if applicable)
-├── tests/             # Test files
-├── package.json       # Project manifest
-└── README.md          # User documentation
-```
-
-## Directory Purposes
-
-**bin/**
-- Purpose: CLI entry points
-- Contains: install.js (installer script)
-- Key files: install.js - handles npx installation
-- Subdirectories: None
-
-**skills/qualia/**
-- Purpose: Slash command definitions for Claude Code
-- Contains: *.md files (one per command)
-- Key files: new-project.md, plan-phase.md, execute-plan.md
-- Subdirectories: None (flat structure)
-
-**qualia-framework/references/**
-- Purpose: Core philosophy and guidance documents
-- Contains: principles.md, questioning.md, plan-format.md
-- Key files: principles.md - system philosophy
-- Subdirectories: None
-
-**qualia-framework/templates/**
-- Purpose: Document templates for .planning/ files
-- Contains: Template definitions with frontmatter
-- Key files: project.md, roadmap.md, plan.md, summary.md
-- Subdirectories: codebase/ (new - for stack/architecture/structure templates)
-
-**qualia-framework/workflows/**
-- Purpose: Reusable multi-step procedures
-- Contains: Workflow definitions called by commands
-- Key files: execute-plan.md, research-phase.md
-- Subdirectories: None
-
-## Key File Locations
-
-**Entry Points:**
-- `bin/install.js` - Installation script (npx entry)
-
-**Configuration:**
-- `package.json` - Project metadata, dependencies, bin entry
-- `.gitignore` - Excluded files
-
-**Core Logic:**
-- `bin/install.js` - All installation logic (file copying, path replacement)
-
-**Testing:**
-- `tests/` - Test files (if present)
-
-**Documentation:**
-- `README.md` - User-facing installation and usage guide
-- `CLAUDE.md` - Instructions for Claude Code when working in this repo
-
-## Naming Conventions
-
-**Files:**
-- kebab-case.md: Markdown documents
-- kebab-case.js: JavaScript source files
-- UPPERCASE.md: Important project files (README, CLAUDE, CHANGELOG)
-
-**Directories:**
-- kebab-case: All directories
-- Plural for collections: templates/, commands/, workflows/
-
-**Special Patterns:**
-- {command-name}.md: Slash command definition
-- *-template.md: Could be used but templates/ directory preferred
-
-## Where to Add New Code
-
-**New Slash Command:**
-- Primary code: `skills/qualia/{command-name}.md`
-- Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
-- Documentation: Update `README.md` with new command
-
-**New Template:**
-- Implementation: `qualia-framework/templates/{name}.md`
-- Documentation: Template is self-documenting (includes guidelines)
-
-**New Workflow:**
-- Implementation: `qualia-framework/workflows/{name}.md`
-- Usage: Reference from command with `@/home/qualia/.claude/qualia-framework/workflows/{name}.md`
-
-**New Reference Document:**
-- Implementation: `qualia-framework/references/{name}.md`
-- Usage: Reference from commands/workflows as needed
-
-**Utilities:**
-- No utilities yet (`install.js` is monolithic)
-- If extracted: `src/utils/`
-
-## Special Directories
-
-**qualia-framework/**
-- Purpose: Resources installed to /home/qualia/.claude/
-- Source: Copied by bin/install.js during installation
-- Committed: Yes (source of truth)
-
-**commands/**
-- Purpose: Slash commands installed to /home/qualia/.claude/commands/
-- Source: Copied by bin/install.js during installation
-- Committed: Yes (source of truth)
-
----
-
-*Structure analysis: 2025-01-20*
-*Update when directory structure changes*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in STRUCTURE.md:**
-- Directory layout (ASCII box-drawing tree for structure visualization)
-- Purpose of each directory
-- Key file locations (entry points, configs, core logic)
-- Naming conventions
-- Where to add new code (by type)
-- Special/generated directories
-
-**What does NOT belong here:**
-- Conceptual architecture (that's ARCHITECTURE.md)
-- Technology stack (that's STACK.md)
-- Code implementation details (defer to code reading)
-- Every single file (focus on directories and key files)
-
-**When filling this template:**
-- Use `tree -L 2` or similar to visualize structure
-- Identify top-level directories and their purposes
-- Note naming patterns by observing existing files
-- Locate entry points, configs, and main logic areas
-- Keep directory tree concise (max 2-3 levels)
-
-**Tree format (ASCII box-drawing characters for structure only):**
-```
-root/
-├── dir1/           # Purpose
-│   ├── subdir/    # Purpose
-│   └── file.ts    # Purpose
-├── dir2/          # Purpose
-└── file.ts        # Purpose
-```
-
-**Useful for phase planning when:**
-- Adding new features (where should files go?)
-- Understanding project organization
-- Finding where specific logic lives
-- Following existing conventions
-</guidelines>