qualia-framework 3.2.0 → 3.3.0

package/skills/qualia-map/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: qualia-map
+description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+---
+
+# /qualia-map — Codebase Mapping (Brownfield)
+
+Scans an existing repo and produces `.planning/codebase/` — architecture, stack, conventions, concerns. Used by `/qualia-new` to infer what's already built and seed Validated requirements.
+
+## When to Use
+
+- Taking over an existing client project
+- Adding features to a repo you didn't build
+- Before `/qualia-new` on any directory that already has code
+
+## Usage
+
+`/qualia-map` — scan the current working directory
+
+## Process
+
+### 1. Check for Existing Code
+
+```bash
+ls -la 2>/dev/null
+test -f package.json && echo "HAS_PACKAGE"
+test -d .git && echo "HAS_GIT"
+test -d .planning/codebase && echo "ALREADY_MAPPED"
+```
+
+If `ALREADY_MAPPED`, ask:
+- header: "Re-map?"
+- question: "Codebase already mapped. Re-scan?"
+- options:
+  - "Re-scan" — overwrite existing map
+  - "Skip" — use existing map
+
+### 2. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner map
+```
+
+### 3. Spawn Parallel Mapper Agents
+
+Map 4 dimensions in parallel for speed. Each writes one file in `.planning/codebase/`:
+
+```
+Agent 1: Architecture scanner
+  Task(prompt="
+  Scan the current codebase and produce .planning/codebase/architecture.md.
+  Identify: entry points, folder structure, module boundaries, data flow.
+  Focus on WHAT the codebase does, not HOW to fix it.
+  ", subagent_type="general-purpose", description="Architecture scan")
+
+Agent 2: Stack detector
+  Task(prompt="
+  Detect the tech stack. Read package.json, requirements.txt, Gemfile, etc.
+  Produce .planning/codebase/stack.md listing: runtime, framework, key libraries,
+  database, hosting, CI. Include version numbers.
+  ", subagent_type="general-purpose", description="Stack detection")
+
+Agent 3: Conventions analyzer
+  Task(prompt="
+  Analyze code style and conventions. Sample 10-15 files across the codebase.
+  Produce .planning/codebase/conventions.md listing: naming, component patterns,
+  file organization, import style, test style, commit message format.
+  ", subagent_type="general-purpose", description="Conventions analysis")
+
+Agent 4: Concerns scanner
+  Task(prompt="
+  Scan for code quality concerns — NOT to fix, just to document.
+  Look for: TODO/FIXME, deprecated APIs, outdated dependencies, missing tests,
+  security smells (hardcoded secrets, no input validation).
+  Produce .planning/codebase/concerns.md.
+  ", subagent_type="general-purpose", description="Concerns scan")
+```
+
+### 4. Wait for All 4
+
+After all 4 agents complete, read the 4 output files.
+
+### 5. Synthesize
+
+Create `.planning/codebase/README.md` — one-page summary linking to the 4 dimension files.
+
+```markdown
+# Codebase Map
+
+**Scanned:** {date}
+**Repo:** {name}
+**LOC:** {lines of code from wc -l}
+
+## At a Glance
+
+- **Stack:** {from stack.md — one line}
+- **Architecture:** {from architecture.md — one sentence}
+- **Conventions:** {from conventions.md — one sentence}
+- **Concerns:** {count of concerns found}
+
+## Validated Capabilities (Inferred)
+
+Based on existing code, this project already does:
+- {capability 1} (evidence: {file path})
+- {capability 2} (evidence: {file path})
+- {capability 3} (evidence: {file path})
+
+These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
+
+## Dimension Details
+
+- [Architecture](./architecture.md)
+- [Stack](./stack.md)
+- [Conventions](./conventions.md)
+- [Concerns](./concerns.md)
+```
+
+### 6. Commit
+
+```bash
+git add .planning/codebase/
+git commit -m "docs: map existing codebase"
+```
+
+### 7. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
+```
+
+## What `/qualia-new` Does With This
+
+When `/qualia-new` runs AFTER `/qualia-map`, it:
+1. Reads `.planning/codebase/README.md`
+2. Extracts Validated capabilities
+3. Pre-populates PROJECT.md with Validated requirements section
+4. Skips questions about things already built
+5. Focuses questioning on NEW capabilities being added
+
+## Rules
+
+1. **Non-destructive.** This skill only READS code, never modifies it.
+2. **Four parallel agents.** Don't sequential-scan — parallel is ~4x faster.
+3. **Dimension files are structured.** The orchestrator downstream (`/qualia-new`) reads them programmatically.
+4. **Concerns ≠ fixes.** This skill documents concerns. It does NOT fix them. Use `/qualia-optimize` for that.

package/skills/qualia-milestone/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: qualia-milestone
+description: "Close out a completed milestone and prep the next one. Archives the current milestone's artifacts, updates REQUIREMENTS.md to mark v1 requirements Complete, and creates the next milestone roadmap."
+---
+
+# /qualia-milestone — Milestone Closeout
+
+Use when all feature phases in the current milestone are verified. Archives artifacts, marks requirements Complete, opens a new milestone for the next release.
+
+## When to Use
+
+- After `/qualia-verify N` passes on the LAST phase of a milestone
+- Before starting a v1.5 / v2.0 cycle
+- NOT for individual phase completions — use `/qualia-verify N` for that
+
+## Usage
+
+`/qualia-milestone` — close the current milestone, open the next
+
+## Process
+
+### 1. Validate Readiness
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Check:
+- All phases in STATE.md are `status: verified`
+- `verification: pass` for every phase
+- No open blockers
+
+If not ready:
+```bash
+node ~/.claude/bin/qualia-ui.js fail "Milestone not ready — {reason}"
+```
+Exit.
+
+### 2. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner milestone
+```
+
+### 3. Confirm Closeout
+
+Show:
+- Milestone name (e.g., "v1 — Launch")
+- Phases completed
+- Requirements delivered
+
+- header: "Close milestone?"
+- question: "Close {milestone name} and move to the next milestone?"
+- options:
+  - "Close it" — Archive and open next
+  - "Not yet" — I want to add more first
+
+### 4. Archive Current Milestone
+
+```bash
+mkdir -p .planning/archive
+cp .planning/ROADMAP.md .planning/archive/{milestone_slug}-ROADMAP.md
+cp .planning/STATE.md .planning/archive/{milestone_slug}-STATE.md
+cp -r .planning/phases .planning/archive/{milestone_slug}-phases
+```
+
+### 5. Update REQUIREMENTS.md
+
+Open `.planning/REQUIREMENTS.md` and:
+- Mark every v1 requirement as Complete in the traceability table
+- Move the `## v1 Requirements` section content to `## Completed (v1)` at the top (for historical reference)
+- Elevate `## v2 Requirements` → `## v1 Requirements` (next milestone's scope)
+
+### 6. Ask About Next Milestone
+
+- header: "Next milestone"
+- question: "What's the next milestone called?"
+- options (dynamic):
+  - "v1.5 — {suggested name based on v2 requirements}"
+  - "v2.0 — {bigger rewrite}"
+  - "Custom name" — let me type it
+
+### 7. Create New Roadmap
+
+Spawn the roadmapper to create a new ROADMAP.md for the next milestone:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/qualia-roadmapper.md
+
+<task>
+Create a new ROADMAP.md for the next milestone.
+
+Milestone name: {milestone name}
+Milestone number: {M+1}
+
+The new v1 requirements (just promoted from old v2) are in .planning/REQUIREMENTS.md.
+The previous milestone's archive is at .planning/archive/.
+
+Build phases for the new milestone scope. Do NOT plan for already-completed requirements.
+", subagent_type="qualia-roadmapper", description="Create next milestone roadmap")
+```
+
+### 8. Reset STATE.md via state.js
+
+```bash
+node ~/.claude/bin/state.js init \
+  --project "{project name}" \
+  --client "{client}" \
+  --type "{type}" \
+  --phases '{JSON from new roadmap}' \
+  --total_phases {new N}
+```
+
+### 9. Commit
+
+```bash
+git add .planning/
+git commit -m "feat({milestone_slug}): close milestone, open {next milestone}"
+```
+
+### 10. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "MILESTONE {closed} CLOSED" "/qualia-plan 1"
+```
+
+## What Stays, What Changes
+
+**Stays:**
+- `.planning/PROJECT.md` — the project doesn't change
+- `.planning/archive/` — historical milestones preserved
+- Git history — every commit preserved
+
+**Changes:**
+- `.planning/REQUIREMENTS.md` — Completed section grows, v1 scope shifts
+- `.planning/ROADMAP.md` — new phases for the new milestone
+- `.planning/STATE.md` — reset to Phase 1 of new milestone
+
+**Discarded (but archived):**
+- `.planning/phases/` — the old phase folders move to archive
+
+## Rules
+
+1. **Don't close early.** All phases must be `verified` with `pass`. No partial milestones.
+2. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
+3. **New milestone = new phase numbering.** The next phase is Phase 1 of the new milestone, not Phase {N+1} of the old.
+4. **ERP sync aware.** The ERP reads ROADMAP.md — after milestone close, push to GitHub so the ERP picks up the new phase structure.