catalyst-os 1.0.0 → 1.1.1

package/.claude/agents/alchemist.md

@@ -57,9 +57,18 @@ Before reporting task completion to the orchestrator, review your own work:
 - Did I follow existing naming conventions?
 - Are foreign keys properly cascaded?
 
+**Existing Schema Reality Check (BEFORE designing):**
+- Did I query the actual database schema for all tables this feature touches?
+- Did I document real column names, types, and constraints (not code aliases)?
+- Did I verify foreign key relationships and join paths?
+- Did I check what SQL functions/stored procedures already exist that this feature will call?
+- Did I verify that API endpoints actually persist all fields the spec assumes they do?
+
 **Verification:**
 - Did I run the migration? Does it ACTUALLY succeed? (See: `.claude/skills/verification-before-completion/SKILL.md`)
 - Did I run the tests? Do they ACTUALLY pass?
+- Did I verify the actual database state matches what I intended? (Query `information_schema.columns` or equivalent)
+- Did I test the end-to-end data path? (API call → database write → database read → API response)
 
 If you find issues during self-review, fix them before reporting.
 

package/.claude/agents/catalyst.md

@@ -42,6 +42,7 @@ Before any action, load `.claude/skills/using-skills/SKILL.md` and check which s
 
 1. **Understand**: Ask clarifying questions to understand the feature request
 2. **Research**: Gather context from codebase, documentation, and external sources
+   - **If the feature touches database operations**: Instruct Seer to run the "Database Schema Reality Check" (see seer.md). Seer must query the actual database — not just read code files — and document real column names, types, join paths, and API endpoint schemas. Past spec failures all traced to trusting code abstractions over the real schema.
 3. **Synthesize**: Combine findings into coherent requirements
 4. **Document**: Create a structured specification with acceptance criteria
 5. **Validate**: Confirm understanding with the user

package/.claude/agents/forge-master.md

@@ -114,11 +114,23 @@ Spawn: Forger
 Wait: tasks.md with Build DAG created
 ```
 
-### 2. Test Writing (Sequential)
+### 2. Test Writing (Sequential) — RED PHASE
 ```
 Spawn: Enforcer
 Input: All tasks from DAG
-Wait: All tests written and FAILING (Red Phase)
+Wait: All tests written and FAILING
+```
+
+### HARD GATE: Red Phase Commit
+```
+BLOCKING — DO NOT PROCEED WITHOUT THIS:
+
+  1. Run ALL tests → every test must FAIL
+  2. If any test passes → STOP, fix the test
+  3. COMMIT: "test({scope}): write failing tests for {spec}"
+
+This commit is PROOF that red phase happened.
+No commit = no implementation. No exceptions.
 ```
 
 ### 3. Foundation Phase (Sequential)
@@ -151,7 +163,18 @@ for task in parallel_tasks:
 # Spawn ALL ready tasks in ONE message
 Spawn: smith-1, smith-2, shaper-1, shaper-2, shaper-3 (parallel)
 Wait: ALL parallel tasks complete
-Gate: All parallel tests PASS
+```
+
+### HARD GATE: Green Phase Commit
+```
+BLOCKING — DO NOT PROCEED WITHOUT THIS:
+
+  1. Run ALL tests → every test must PASS
+  2. If any test fails → fix before continuing
+  3. COMMIT: "feat({scope}): implement {spec}"
+
+This commit is PROOF that green phase happened.
+No commit = no integration. No exceptions.
 ```
 
 ### 6. Integration Phase (Sequential)

package/.claude/agents/seer.md

@@ -90,6 +90,40 @@ Scribe will compile this into `research.md`.
 | Known issues | `concerns.md` |
 | Fragile areas | `concerns.md` → Fragile Areas |
 
+## Database Schema Reality Check
+
+**CRITICAL**: When the feature touches database operations (CRUD, queries, joins, migrations), do NOT trust column names found in application code. Code uses aliases, joins, computed fields, and abstractions that obscure the real schema.
+
+### Mandatory Steps for Data-Touching Features:
+
+1. **Query the actual schema** — use the project's database tool (Supabase MCP, `prisma db pull`, `information_schema`, etc.) to get real table definitions
+2. **Document actual column names, types, and constraints** — not what the code *calls* them, but what the database *has*
+3. **Trace joins and relationships** — if code references `contact.company_name`, find whether that's a direct column or a join through a foreign key
+4. **Map code abstractions to real schema** — document the mapping between application-level field names and actual database columns
+5. **Verify API request/response schemas** — check what fields endpoints actually accept and persist vs. what the spec assumes
+
+### Output Format (add to your analysis):
+
+```
+### Database Schema (Verified)
+Tables touched: [list]
+
+| Table | Column | Type | Nullable | Notes |
+|-------|--------|------|----------|-------|
+| contacts | primary_email | varchar | no | Code refers to this as "email" |
+| companies | company_name | varchar | no | Accessed via contacts.company_id join |
+
+### Code-to-Schema Mapping
+- `contact.company_name` → JOIN companies ON contacts.company_id = companies.id → companies.company_name
+- `contact.email` → contacts.primary_email
+
+### API Endpoint Gaps
+- POST /campaigns/update-basic-info accepts: [actual fields from request schema]
+- Fields NOT persisted by endpoint: [list any that are accepted but ignored]
+```
+
+**Why this matters**: Every spec gap in past projects came from trusting code abstractions over the actual database. Wrong column names, missing endpoint fields, and broken integration paths all stem from skipping this step.
+
 ## Analysis Areas
 
 1. **Structure**: Project organization, module boundaries
@@ -97,6 +131,7 @@ Scribe will compile this into `research.md`.
 3. **Conventions**: Naming, formatting, code style
 4. **Dependencies**: Libraries, frameworks, integrations
 5. **Data Flow**: How data moves through the system
+6. **Data Schema**: Actual database structure for data-touching features (see Database Schema Reality Check above)
 
 ## Output
 

package/.claude/commands/approve-spec.md

@@ -1,6 +1,12 @@
 # /approve-spec
 
-Accept the implementation and archive the spec.
+Accept a **fully built and validated** implementation — commit, archive, and propagate learnings.
+
+> **Lifecycle position:** This is the FINAL step. Only use after `/build-spec` and `/validate-spec` have completed successfully.
+>
+> **Flow:** `/catalyze-spec` → `/build-spec` → `/validate-spec` → **`/approve-spec`**
+>
+> **This is NOT for approving a spec/plan before building.** There is no "approve plan" step — after catalyzing, you go straight to `/build-spec`.
 
 ## Usage
 

package/.claude/skills/build-orchestration/SKILL.md

@@ -117,19 +117,25 @@ Spawn Forger → creates `tasks.md` with Build DAG including phases, scope bound
 
 Spawn Enforcer → writes failing tests for ALL tasks. Run tests to confirm all FAIL.
 
-### GATE 1: Red Phase Verification
+### GATE 1: Red Phase Verification — BLOCKING
 
-```bash
-# Run all tests — they MUST fail
-# Expected: Tests: 0 passed, N failed
+```
+THIS IS A HARD GATE. DO NOT PROCEED UNTIL ALL 3 STEPS COMPLETE:
+
+  1. RUN all tests → confirm every test FAILS
+  2. If ANY test passes → STOP and fix before continuing
+  3. COMMIT the failing tests → this is the checkpoint
+
+COMMIT: "test({scope}): write failing tests for {spec}"
+
+Only AFTER this commit exists may implementation begin.
+No commit = no implementation. No exceptions.
 ```
 
 - Every task has at least one test
 - All tests executed
-- All tests FAIL
-- If ANY test passes → STOP and investigate
-
-**Commit:** `test({scope}): write failing tests for {spec}`
+- All tests FAIL (for the right reasons — missing feature, not import errors)
+- Commit is the proof that red phase happened
 
 ### Phase 3-4: Foundation & Contracts
 
@@ -146,14 +152,19 @@ Each agent prompt includes:
 - Test references
 ```
 
-### GATE 2: Green Phase Verification
+### GATE 2: Green Phase Verification — BLOCKING
 
-```bash
-# Run all tests — they MUST pass
-# Expected: Tests: N passed, 0 failed
 ```
+THIS IS A HARD GATE. DO NOT PROCEED UNTIL ALL 3 STEPS COMPLETE:
+
+  1. RUN all tests → confirm every test PASSES
+  2. If ANY test fails → fix before continuing
+  3. COMMIT the implementation → this is the checkpoint
 
-**Commit:** `feat({scope}): implement {spec}`
+COMMIT: "feat({scope}): implement {spec}"
+
+Only AFTER this commit exists may integration begin.
+```
 
 ### Phase 6: Integration
 

package/.claude/skills/spec-approval/SKILL.md

@@ -12,10 +12,16 @@ Final verification, git commit, spec archival, self-documentation (propagate lea
 - `verification-before-completion` — Final TDD compliance check
 - `agent-delegation` — Scribe delegation for library extraction
 
-## Prerequisites
+## Prerequisites — HARD GATES
 
-- Validation must be complete
-- `validation.md` must show all checks passed
+> **This skill is the FINAL step in the spec lifecycle.** It runs ONLY after build and validation are complete.
+> **Flow:** `/catalyze-spec` → `/build-spec` → `/validate-spec` → **`/approve-spec`** (you are here)
+>
+> If the spec has not been built yet, STOP and tell the user to run `/build-spec` first.
+> If the spec has not been validated yet, STOP and tell the user to run `/validate-spec` first.
+
+- `/build-spec` must have been completed (tasks.md exists with completed tasks)
+- Validation must be complete (`validation.md` must show all checks passed)
 - `handoff.md` must exist
 - TDD compliance verified
 

package/.claude/skills/spec-shaping/SKILL.md

@@ -173,5 +173,9 @@ REMINDER: /build-spec follows strict TDD
   3. Then implement (Builders)
   4. Tests must PASS (green phase)
 
-Next: Run /build-spec @YYYY-MM-DD-{slug} to implement.
+Next steps:
+- /build-spec @YYYY-MM-DD-{slug} to start TDD build
+- Or /iterate-spec if you want changes first
 ```
+
+**IMPORTANT: Do NOT suggest `/approve-spec` after spec shaping.** `/approve-spec` is only for accepting a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → `/build-spec` → `/validate-spec` → `/approve-spec`.

package/.claude/skills/spec-validation/SKILL.md

@@ -86,6 +86,14 @@ Spawn all Guardians in parallel:
 - Secret scanning
 - Input validation checks
 
+**Alchemist** (Schema Integrity — only for specs touching database):
+- Query actual database schema for all tables the spec touches
+- Verify column names in spec/code match real database columns
+- Verify all foreign keys and constraints exist in the actual DB
+- Verify API endpoints persist all fields the spec expects (end-to-end trace)
+- Verify any SQL functions/stored procedures the feature depends on actually exist
+- Check for missing sequences, triggers, or DB-level defaults the feature assumes
+
 ### Phase 5: Compile Results (Arbiter)
 
 Create `validation.md` with results from all Guardians.
@@ -126,6 +134,12 @@ If all validation passes, create handoff.md with:
 - Secrets: status
 - Inputs: status
 
+### Schema Integrity (Alchemist) — if spec touches database
+- Column names match: status
+- Constraints verified: status
+- API end-to-end trace: status
+- DB functions/sequences: status
+
 ## Overall Status: PASS/FAIL
 
 ## Issues Found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "scripts": {
     "postinstall": "node .catalyst/bin/install.js"
   },