qualia-framework 4.5.0 → 5.3.0

package/skills/qualia-zoom/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: qualia-zoom
+description: "Zoom out and map an unfamiliar code area in domain-glossary terms — list the modules, who calls them, what they hide, and the smallest safe edit window. User-fired only (never auto). Use when you don't know an area of code well, before editing an unfamiliar file, or when the user says 'zoom out', 'map this area', 'show me the bigger picture', 'I don't know this code'."
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# /qualia-zoom — Map an Unfamiliar Area
+
+I don't know this area of code well. Go up a layer of abstraction.
+
+Give me a map of:
+
+1. **Modules** in this area — what they expose, what they hide
+2. **Callers** — who uses these modules and from where
+3. **Dependencies** — what these modules pull in
+4. **Domain terms involved** — quoted from `.planning/CONTEXT.md` if it exists
+
+Use the **vocabulary in `.planning/CONTEXT.md`** wherever applicable. If a term in this code conflicts with the glossary, flag it for `/qualia-discuss` (which now grills + updates CONTEXT.md inline).
+
+## Output format
+
+```
+## Where you are
+{file or path being zoomed out from}
+
+## Module map
+- {module/file} — exposes: {x} — hides: {y}
+- ...
+
+## Caller map
+- {caller} → {module} (used for {purpose})
+- ...
+
+## Domain terms
+- {term from glossary} — appears in {files}
+- {term NOT in glossary but present in code} — flag for /qualia-discuss
+
+## Smallest safe edit window
+{which files form the natural unit for this change}
+```
+
+## Rules
+
+- Keep the report under **50 lines**. Orient, don't refactor.
+- **Don't propose changes** — that's the next skill's job.
+- Read `.planning/CONTEXT.md` first if it exists. Use its language.
+- If the area is huge, pick the entry point the user named and zoom from there.

package/skills/zoho-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zoho-workflow
-description: Zoho Invoice and Mail operations - create invoices, send emails, manage contacts. Use when Fawzi mentions invoicing, email, or Zoho.
+description: "Zoho Invoice and Mail operations via ERP-first routing. Creates invoices from templates, sends cover emails, manages contacts, reads inbox, and handles payment reminders. Use when the user says 'invoice this client', 'send an email', 'check inbox', 'create a Zoho contact', 'send payment reminder', or mentions invoicing, billing, or Zoho."
 tags: [zoho, invoice, email, billing, crm]
 ---
 

package/templates/CONTEXT.md

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} — Domain Glossary
+
+<!-- Domain glossary. Loaded by every road agent. Update via /qualia-discuss. Keep entries terse (1 sentence + Avoid line). -->
+
+## Language
+
+### Term Name
+One-sentence definition. Use the term consistently in code, comments, commits, and conversation.
+**Avoid:** alternative terms that mean the same thing but aren't this one.
+
+### {{Add terms as the project clarifies them. Examples below.}}
+
+### User
+**Avoid until disambiguated.** Currently overloaded — see "Flagged ambiguities" below.
+
+### Phase
+A unit of work inside a milestone. 2–5 tasks. Ends in a verification gate.
+**Avoid:** epic, story, ticket, sprint.
+
+### Task
+A single commit-sized unit with one verification contract.
+**Avoid:** subtask, chore, todo.
+
+## Relationships
+- Project holds many Milestones
+- Milestone holds many Phases
+- Phase holds many Tasks
+- Task carries one Verification Contract
+- {{add domain-specific relationships, e.g. "Customer holds many Orders"}}
+
+## Flagged ambiguities
+
+### "User" → AuthUser vs Customer
+- **AuthUser** = the row in `auth.users` (Supabase)
+- **Customer** = the profile row owned by an AuthUser (1:1)
+- {{replace with real ambiguities as they appear}}

package/templates/decisions/ADR-template.md

@@ -0,0 +1,30 @@
+# ADR-{{NNNN}} — {{Decision title in present tense}}
+
+- **Date:** {{YYYY-MM-DD}}
+- **Phase:** {{N}} — {{phase name}}
+- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
+- **Domain terms:** {{any new/affected terms — also update CONTEXT.md}}
+
+## Context
+What is the situation that requires a decision? Why are we deciding this now? What constraints apply (regulatory, performance, team skill, deadlines)?
+
+## Decision
+What we are doing. State it as a single declarative sentence first, then expand.
+
+## Consequences
+- **What becomes easier:** ...
+- **What becomes harder:** ...
+- **What is now load-bearing on this decision:** ...
+
+## Alternatives considered
+Why each alternative was rejected — keep this honest. Future-you will read it.
+
+- **Alt A** — {{rejected because…}}
+- **Alt B** — {{rejected because…}}
+
+## Notes
+Any non-obvious context, links to discussion threads, related issues. Optional.
+
+---
+
+**When to write an ADR (per Matt Pocock's rule):** only when the decision is hard-to-reverse, surprising-without-context, AND involves real trade-offs. If any of those three is missing, just put it in CONTEXT.md or a phase plan instead. ADRs are scarce on purpose.