catalyst-os 0.1.3 → 0.2.0

package/.catalyst/main/project-config.yaml

@@ -9,3 +9,24 @@ generated_files:
   roadmap.md: "Development phases"
   tech-stack.md: "Technology decisions"
 
+# Git Configuration
+git:
+  # Base branch for spec development (checkout from this branch)
+  # Common names: "development", "develop", "staging", "testing", "pre-prod"
+  # This is set during /catalyze-project based on user preference
+  development_branch: "development"
+
+  # Branch prefix for spec feature branches
+  # Example: "feat" creates branches like "feat/2026-01-11-supabase-auth"
+  branch_prefix: "feat"
+
+  # Protected branches (cannot commit directly)
+  protected_branches:
+    - "main"
+    - "master"
+
+  # Commit message templates
+  commit_templates:
+    red_phase: "test({scope}): write failing tests for {spec}"
+    green_phase: "feat({scope}): implement {spec}"
+

package/.catalyst/specs/spec-config.yaml

@@ -43,6 +43,11 @@ structure:
       owner: any
       description: "Images, diagrams, visual references"
 
+    references/:
+      owner: any
+      optional: true
+      description: "Screenshots, evidence, proof of issues (user-created)"
+
   # Completed specs location
   completed: "completed/"
 

package/.claude/agents/scribe.md

@@ -27,20 +27,36 @@ You create and maintain project documentation within the structured spec folder
 
 **CRITICAL: All documentation goes to `.catalyst/specs/YYYY-MM-DD-{slug}/`**
 
+### STRICT ALLOWLIST
+
+Spec folders may **ONLY** contain these files:
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `spec.md` | Scribe | Requirements + frontmatter |
+| `research.md` | Scribe | Compiled research findings |
+| `tasks.md` | Forger | Build DAG + progress |
+| `validation.md` | Arbiter | Test results |
+| `handoff.md` | Arbiter | Human-readable summary |
+| `assets/` | Any | Images, diagrams |
+| `references/` | Any | (Optional) Screenshots, evidence, proof |
+
+**ANY OTHER FILE IS FORBIDDEN.**
+
 ```
-.catalyst/specs/YYYY-MM-DD-{slug}/
-├── spec.md           # Requirements + frontmatter (YOU OWN THIS)
-├── research.md       # Append research findings here
-├── tasks.md          # DAG + progress + decisions (Forger owns)
-├── handoff.md        # Human-readable summary (YOU + Arbiter)
-├── validation.md     # Test results (Arbiter owns)
-└── assets/           # Images, diagrams
+DO NOT CREATE:
+  ✗ README.md
+  ✗ notes.md
+  ✗ implementation/
+  ✗ Any other .md file
+  ✗ Any other folder
 ```
 
 **Rules:**
 1. **UPDATE > CREATE** — Always update existing files, never create new random .md files
 2. **No orphan docs** — Every document belongs to a spec folder
 3. **Append to research.md** — Don't create separate research files
+4. **DENY by default** — If it's not in the allowlist above, don't create it
 
 ## Your Responsibilities
 

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

@@ -46,6 +46,30 @@ IF YOU ARE ABOUT TO USE Edit/Write TOOL ON A .py/.ts/.js FILE → STOP → SPAWN
 
 ---
 
+## GIT WORKFLOW
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  GIT CHECKPOINTS                                                │
+│  ───────────────                                                │
+│                                                                 │
+│  PHASE 0: Setup                                                 │
+│  ├── Read .catalyst/main/project-config.yaml                    │
+│  ├── Checkout to development_branch (default: main)             │
+│  └── Create branch: {branch_prefix}/{spec-slug}                 │
+│                                                                 │
+│  GATE 1: RED FLAG                                               │
+│  └── Commit: "test({scope}): write failing tests for {spec}"    │
+│                                                                 │
+│  GATE 2: GREEN FLAG                                             │
+│  └── Commit: "feat({scope}): implement {spec}"                  │
+│                                                                 │
+│  Then: User runs /validate-spec and /approve-spec               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
 ## TDD IS MANDATORY - NO EXCEPTIONS
 
 ```
@@ -137,6 +161,41 @@ forger -> enforcer -> GATE -> alchemist -> contracts -> [smith-1 + smith-2 + sha
 
 The **Forge-Master** agent orchestrates the Technologists.
 
+### Phase 0: Git Setup
+
+**Before any work begins, set up the git branch for this spec.**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  📍 GIT SETUP                                                   │
+│  ───────────                                                    │
+│                                                                 │
+│  1. Read git config from project-config.yaml:                   │
+│     $ cat .catalyst/main/project-config.yaml                    │
+│                                                                 │
+│     Extract:                                                    │
+│     - development_branch (default: "main")                      │
+│     - branch_prefix (default: "feat")                           │
+│                                                                 │
+│  2. Checkout to development branch:                             │
+│     $ git checkout {development_branch}                         │
+│     $ git pull origin {development_branch}                      │
+│                                                                 │
+│  3. Create spec feature branch:                                 │
+│     $ git checkout -b {branch_prefix}/{spec-slug}               │
+│                                                                 │
+│     Example: git checkout -b feat/2026-01-11-stripe-integration │
+│                                                                 │
+│  4. Confirm branch creation to user:                            │
+│     "Created branch: feat/{spec-slug} from {development_branch}"│
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**WAIT for git setup to complete before proceeding to Phase 1.**
+
+---
+
 ### Phase 1: Task Breakdown (Forger)
 
 **Spawn Forger agent** using `Task` tool with `subagent_type="forger"`:
@@ -212,7 +271,7 @@ Enforcer will:
 
 ---
 
-### GATE 1: Red Phase Verification
+### GATE 1: Red Phase Verification (RED FLAG)
 
 **STOP! Before proceeding to implementation:**
 
@@ -232,6 +291,28 @@ npm test  # or appropriate test command
 
 **If ANY test passes -> STOP and investigate**
 
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🚩 RED FLAG COMMIT                                             │
+│  ─────────────────                                              │
+│                                                                 │
+│  After Gate 1 passes, commit the test suite:                    │
+│                                                                 │
+│  $ git add .                                                    │
+│  $ git commit -m "test({scope}): write failing tests for {spec}"│
+│                                                                 │
+│  Example:                                                       │
+│  git commit -m "test(auth): write failing tests for supabase-auth"
+│                                                                 │
+│  This checkpoint captures:                                      │
+│  - All test files                                               │
+│  - tasks.md with test locations                                 │
+│  - Any test fixtures or mocks                                   │
+│                                                                 │
+│  ✅ Checkpoint saved. Proceeding to implementation.             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
 ---
 
 ### Phase 3-4: Foundation & Contracts (Sequential)
@@ -329,7 +410,7 @@ NEVER modify files outside your SCOPE
 
 ---
 
-### GATE 2: Green Phase Verification
+### GATE 2: Green Phase Verification (GREEN FLAG)
 
 **Before completing build:**
 
@@ -342,6 +423,28 @@ npm test
 # Status: GREEN
 ```
 
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🟢 GREEN FLAG COMMIT                                           │
+│  ───────────────────                                            │
+│                                                                 │
+│  After Gate 2 passes, commit the implementation:                │
+│                                                                 │
+│  $ git add .                                                    │
+│  $ git commit -m "feat({scope}): implement {spec}"              │
+│                                                                 │
+│  Example:                                                       │
+│  git commit -m "feat(auth): implement supabase-auth"            │
+│                                                                 │
+│  This checkpoint captures:                                      │
+│  - All implementation files                                     │
+│  - Updated tasks.md with progress                               │
+│  - Any configuration changes                                    │
+│                                                                 │
+│  ✅ Implementation committed. Ready for validation.             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
 ---
 
 ## Output
@@ -350,6 +453,13 @@ npm test
 Build complete!
 
 Spec: 2025-11-29-stripe-integration
+Branch: feat/2025-11-29-stripe-integration
+
+Git Commits:
+┌────────────────────────────────────────────────────────────────┐
+│ 🚩 abc1234 test(payment): write failing tests for stripe-integration
+│ 🟢 def5678 feat(payment): implement stripe-integration
+└────────────────────────────────────────────────────────────────┘
 
 TDD Compliance: VERIFIED
 - Red Phase: 45 tests written, all failed
@@ -368,6 +478,7 @@ Scope Violations: 0
 Updated: .catalyst/specs/2025-11-29-stripe-integration/tasks.md
 
 Next: Run /validate-spec @2025-11-29-stripe-integration
+      Then /approve-spec for final review and merge
 ```
 
 ---

package/.claude/commands/catalyze-project.md

@@ -1,6 +1,6 @@
 # /catalyze-project
 
-Initialize the project foundation. Always creates all 6 documents.
+Initialize the project foundation. Creates project config and all 6 foundation documents.
 
 ## Usage
 
@@ -51,9 +51,55 @@ Then ask only what can't be inferred:
 1. What's the project's mission? (if no README)
 2. What are the current priorities?
 
-### Phase 3: Generate All 6 Documents
+### Phase 3: Git Branch Setup
 
-Always create all documents in `.catalyst/main/`:
+**Ask the user about their development branch preference:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🙋 ASK USER: Development Branch                                │
+│  ───────────────────────────────                                │
+│                                                                 │
+│  "What should we name the development branch for spec work?"    │
+│                                                                 │
+│  Options:                                                       │
+│  ○ development (Recommended)                                    │
+│  ○ develop                                                      │
+│  ○ staging                                                      │
+│  ○ Other (custom name)                                          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**After user responds:**
+
+1. Check if branch exists:
+   ```bash
+   git branch --list {branch_name}
+   ```
+
+2. If branch doesn't exist, create it from main:
+   ```bash
+   git checkout -b {branch_name}
+   git push -u origin {branch_name}  # Optional: ask user if they want to push
+   git checkout main  # Return to main for now
+   ```
+
+3. Store preference in `project-config.yaml`:
+   ```yaml
+   git:
+     development_branch: "{user_choice}"
+   ```
+
+---
+
+### Phase 4: Generate Config and Documents
+
+Always create in `.catalyst/main/`:
+
+| File | Source |
+|------|--------|
+| `project-config.yaml` | User preferences from Phase 3 |
 
 | Document | Greenfield Source | Brownfield Source |
 |----------|-------------------|-------------------|
@@ -68,6 +114,9 @@ Always create all documents in `.catalyst/main/`:
 
 ## Templates
 
+Located at `.catalyst/main/`:
+- `project-config.yaml` (git and project settings template)
+
 Located at `.catalyst/main/temp/`:
 - `temp-mission.md`
 - `temp-roadmap.md`
@@ -82,6 +131,7 @@ Located at `.catalyst/main/temp/`:
 
 ```
 .catalyst/main/
+├── project-config.yaml
 ├── mission.md
 ├── roadmap.md
 ├── tech-stack.md
@@ -93,7 +143,12 @@ Located at `.catalyst/main/temp/`:
 ```
 ✅ Project initialized!
 
-Created 6 documents in .catalyst/main/
+Git Setup:
+- Development branch: {branch_name} (created/verified)
+- Feature branches will be: feat/{spec-slug}
+
+Created 7 files in .catalyst/main/
+- project-config.yaml: Git workflow settings
 - Architecture: [summary]
 - Conventions: [count] patterns
 - Concerns: [count] issues

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

@@ -253,9 +253,5 @@ Validation failed!
 
 Spec: 2025-11-29-stripe-integrationFailed Checks:
 - E2E Tests: 2 failures
-- Security: 1 vulnerability found
-
-Created: .catalyst/specs/{slug}/validation.md (with details)
-
-Action: Fix issues and re-run /validate-spec
+- Security: 1 vulnerability foundCreated: .catalyst/specs/{slug}/validation.md (with details)Action: Fix issues and re-run /validate-spec
 ```

package/AGENTS.md

@@ -157,25 +157,29 @@ Scribe is the gatekeeper. This ensures:
 - Consistent formatting
 - No orphan documents
 
-### Quick Reference
+### STRICT ALLOWLIST
 
-```
-.catalyst/specs/YYYY-MM-DD-{slug}/
-├── spec.md        → Scribe owns (requirements + frontmatter)
-├── research.md    → Scribe compiles (researchers hand off findings)
-├── tasks.md       → Forger owns (THE living document)
-├── validation.md  → Arbiter owns
-├── handoff.md     → Scribe owns (human-readable summary)
-└── assets/        → Any agent
-```
+Spec folders may **ONLY** contain:
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `spec.md` | Scribe | Requirements + frontmatter |
+| `research.md` | Scribe | Compiled research findings |
+| `tasks.md` | Forger | Build DAG + progress |
+| `validation.md` | Arbiter | Test results |
+| `handoff.md` | Arbiter | Human-readable summary |
+| `assets/` | Any | Images, diagrams |
+| `references/` | Any | (Optional) Screenshots, evidence |
+
+**ANY OTHER FILE IS FORBIDDEN.** No README.md, no notes.md, no implementation/.
 
 ### Rules
 
 1. **Scribe is gatekeeper** — All .md writes in specs go through Scribe
-2. **Researchers hand off** — Scout/Seer/Oracle give findings to Scribe, don't write directly
-3. **tasks.md is THE living document** — ONE file to read when resuming work
-4. **handoff.md is colleague summary** — Human-readable walkthrough, finalized at end
-5. **See spec-structure.yaml** — For full structure details
+2. **DENY by default** — If not in allowlist, don't create it
+3. **Researchers hand off** — Scout/Seer/Oracle give findings to Scribe, don't write directly
+4. **tasks.md is THE living document** — ONE file to read when resuming work
+5. **handoff.md is colleague summary** — Human-readable walkthrough, finalized at end
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "AI-native spec-driven development framework for Claude Code",
   "bin": {
     "catalyst-os": "bin/install.js"