catalyst-os 0.1.2 → 0.1.3

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

@@ -2,6 +2,36 @@
 
 Implement a specification using **strict TDD**.
 
+---
+
+## FORGE-MASTER BEHAVIORAL RULES
+
+**You are an ORCHESTRATOR. You coordinate work, you do NOT do work.**
+
+```
+BEFORE writing ANY code or test:
+  → STOP
+  → Ask yourself: "Should a specialized agent do this?"
+  → If YES: Use Task tool with appropriate subagent_type
+  → If NO: You're probably wrong. Use the Task tool.
+
+You may ONLY:
+  ✓ Read files to understand context
+  ✓ Use Task tool to spawn agents (forger, enforcer, smith, shaper, alchemist)
+  ✓ Run test commands to verify gates
+  ✓ Report status to user
+
+You may NEVER:
+  ✗ Write code (use smith or shaper)
+  ✗ Write tests (use enforcer)
+  ✗ Create task breakdowns (use forger)
+  ✗ Write database schemas (use alchemist)
+
+IF YOU ARE ABOUT TO USE Edit/Write TOOL ON A .py/.ts/.js FILE → STOP → SPAWN AN AGENT
+```
+
+---
+
 ## Usage
 
 ```
@@ -23,17 +53,17 @@ Implement a specification using **strict TDD**.
 
   The build MUST follow this exact sequence:
 
-  1. Forger    -> Create tasks.md
-  2. Enforcer  -> Write ALL tests (must FAIL)         <- GATE 1
-  3. Verify    -> Run tests, confirm RED              <- GATE 2
-  4. Builders  -> Implement until GREEN               <- Only after
+  1. Task(subagent_type="forger")    -> Create tasks.md
+  2. Task(subagent_type="enforcer")  -> Write ALL tests (must FAIL)
+  3. Verify                          -> Run tests, confirm RED
+  4. Task(subagent_type="smith/shaper/alchemist") -> Implement until GREEN
 ```
 
 ---
 
 ## ORCHESTRATION MODE
 
-**IMPORTANT**: This command operates in orchestration mode. The main agent DELEGATES work to specialized sub-agents.
+Forge-Master spawns specialized agents using the **Task tool**. Each phase is a separate agent.
 
 ### Output Location
 
@@ -109,7 +139,7 @@ The **Forge-Master** agent orchestrates the Technologists.
 
 ### Phase 1: Task Breakdown (Forger)
 
-**Spawn Forger agent**:
+**Spawn Forger agent** using `Task` tool with `subagent_type="forger"`:
 
 ```
 "Break down spec.md into implementable tasks with Build DAG. Write to:
@@ -118,6 +148,8 @@ The **Forge-Master** agent orchestrates the Technologists.
 Include: phases, scope boundaries, dependencies, parallel opportunities."
 ```
 
+**WAIT for Forger to complete and return before proceeding to Phase 2.**
+
 Forger creates `tasks.md` with **Build DAG**:
 
 ```markdown
@@ -163,7 +195,7 @@ Forger creates `tasks.md` with **Build DAG**:
 
 **CRITICAL: This phase MUST complete before ANY implementation starts.**
 
-**Spawn Enforcer agent**:
+**Spawn Enforcer agent** using `Task` tool with `subagent_type="enforcer"`:
 
 ```
 "Write failing tests for ALL tasks in tasks.md.
@@ -171,6 +203,8 @@ Tests go in project test folders (src/__tests__/, tests/, etc.).
 Update tasks.md Progress section with test file locations."
 ```
 
+**WAIT for Enforcer to complete and return before proceeding to Gate 1.**
+
 Enforcer will:
 1. For EVERY task, write failing tests in project test folders
 2. Update `tasks.md` Progress section with test locations
@@ -204,7 +238,7 @@ npm test  # or appropriate test command
 
 **Only start this phase AFTER Gate 1 (Red Phase) passes!**
 
-**Spawn Alchemist** (foundation):
+**Spawn Alchemist** using `Task` tool with `subagent_type="alchemist"`:
 
 ```
 "Implement db-schema task.
@@ -212,7 +246,9 @@ SCOPE (write): prisma/*, src/db/*
 Run tests after to verify progress."
 ```
 
-**Spawn Smith** (contracts - after foundation completes):
+**WAIT for Alchemist to complete before spawning Smith.**
+
+**Spawn Smith** using `Task` tool with `subagent_type="smith"`:
 
 ```
 "Implement api-types task.
@@ -220,38 +256,42 @@ SCOPE (write): src/types/api.ts
 Defines shared types for all parallel agents."
 ```
 
+**WAIT for Smith to complete before proceeding to Phase 5.**
+
 ---
 
 ### Phase 5: Parallel Implementation (DAG-Driven)
 
 **Only start AFTER contracts phase completes!**
 
-**Spawn ALL ready agents in ONE message with scope boundaries:**
+**Spawn ALL ready agents in ONE message** using multiple `Task` tool calls:
 
 ```
-Smith-1: "Implement api-auth task.
+Task(subagent_type="smith", prompt="Implement api-auth task.
          SCOPE (write): src/api/auth/**, tests/api/auth/**
          READS (no modify): src/types/**
-         Run tests after each change."
+         Run tests after each change.")
 
-Smith-2: "Implement api-billing task.
+Task(subagent_type="smith", prompt="Implement api-billing task.
          SCOPE (write): src/api/billing/**, tests/api/billing/**
          READS (no modify): src/types/**
-         Run tests after each change."
+         Run tests after each change.")
 
-Shaper-1: "Implement ui-pricing task.
+Task(subagent_type="shaper", prompt="Implement ui-pricing task.
           SCOPE (write): src/pages/pricing/**, src/components/pricing/**
           READS (no modify): src/types/**, src/components/shared/**
-          Run tests after each change."
+          Run tests after each change.")
 
-Shaper-2: "Implement ui-dashboard task.
+Task(subagent_type="shaper", prompt="Implement ui-dashboard task.
           SCOPE (write): src/pages/dashboard/**, src/components/dashboard/**
           READS (no modify): src/types/**, src/components/shared/**
-          Run tests after each change."
+          Run tests after each change.")
 ```
 
 **CRITICAL**: Include scope in every agent prompt. Agents must NOT modify files outside their scope.
 
+**WAIT for ALL parallel agents to complete before proceeding to Phase 6.**
+
 Each builder updates `tasks.md` Progress section as they complete tasks.
 
 ---
@@ -260,7 +300,7 @@ Each builder updates `tasks.md` Progress section as they complete tasks.
 
 **Only start AFTER all parallel tasks complete!**
 
-**Spawn Enforcer**:
+**Spawn Enforcer** using `Task` tool with `subagent_type="enforcer"`:
 
 ```
 "Run integration tests for cross-boundary functionality.

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

@@ -12,9 +12,9 @@ Initialize the project foundation. Always creates all 6 documents.
 
 ## Process
 
-### Phase 1: Detection
+### Phase 1: Detection (Silent)
 
-Scan the project to determine if greenfield or brownfield:
+**Do not announce this phase to the user.** Silently scan the project to determine if greenfield or brownfield:
 
 | Signal | Greenfield | Brownfield |
 |--------|------------|------------|
@@ -23,6 +23,8 @@ Scan the project to determine if greenfield or brownfield:
 | Git history | < 10 commits | > 10 commits |
 | Lines of code | < 500 | > 500 |
 
+Run these checks in the background and proceed directly to Phase 2 based on the result.
+
 ### Phase 2: Gather Information
 
 **If Greenfield** - Heavy questioning via Oracle:
@@ -37,12 +39,12 @@ Scan the project to determine if greenfield or brownfield:
 8. What's the timeline pressure?
 9. Are there similar products to reference?
 
-**If Brownfield** - Heavy scanning via 3 parallel Explore agents:
+**If Brownfield** - Heavy scanning via 3 parallel Seer agents (subagent_type="seer"):
 
 ```
-Agent 1: Architecture + Tech Stack
-Agent 2: Conventions + Patterns
-Agent 3: Concerns + TODOs
+Seer 1: Architecture + Tech Stack
+Seer 2: Conventions + Patterns
+Seer 3: Concerns + TODOs
 ```
 
 Then ask only what can't be inferred:

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

@@ -251,13 +251,11 @@ Action: Run /build-spec @2025-11-29-stripe-integration
 ```
 Validation failed!
 
-Spec: 2025-11-29-stripe-integration
-
-Failed Checks:
+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
-```
+```

package/package.json

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

package/.catalyst/standards/coding.md

@@ -1,187 +0,0 @@
-# Coding Standards
-
-Project-wide coding conventions and style guidelines.
-
-## General Principles
-
-### Code Style
-- **Clarity over cleverness** - Write code that's easy to understand
-- **Consistency** - Follow existing patterns in the codebase
-- **Self-documenting** - Good names reduce need for comments
-- **Small functions** - Single responsibility, easy to test
-
-### Naming Conventions
-
-| Type | Convention | Example |
-|------|------------|---------|
-| Variables | camelCase | `userName`, `isActive` |
-| Constants | UPPER_SNAKE | `MAX_RETRIES`, `API_URL` |
-| Functions | camelCase | `getUserById`, `validateInput` |
-| Classes | PascalCase | `UserService`, `PaymentHandler` |
-| Files | kebab-case | `user-service.ts`, `payment-handler.py` |
-| Components | PascalCase | `UserProfile.tsx`, `Button.tsx` |
-
-### File Organization
-
-```
-src/
-├── components/     # UI components
-├── hooks/          # Custom React hooks
-├── services/       # Business logic
-├── utils/          # Utility functions
-├── types/          # Type definitions
-└── api/            # API routes/handlers
-```
-
-## TypeScript/JavaScript
-
-### Prefer
-```typescript
-// Type interfaces for objects
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-// Const over let
-const user = getUser()
-
-// Async/await over promises
-const data = await fetchData()
-
-// Optional chaining
-const name = user?.profile?.name
-
-// Nullish coalescing
-const value = input ?? defaultValue
-```
-
-### Avoid
-```typescript
-// var keyword
-var user = getUser()  // ❌
-
-// any type
-const data: any = {}  // ❌
-
-// Nested callbacks
-getData(result => {
-  process(result, processed => {  // ❌
-    save(processed)
-  })
-})
-```
-
-## Python
-
-### Style
-- Follow PEP 8
-- Use type hints
-- Docstrings for public functions
-
-```python
-def get_user_by_id(user_id: str) -> User | None:
-    """
-    Retrieve a user by their ID.
-    
-    Args:
-        user_id: The unique identifier for the user
-        
-    Returns:
-        User object if found, None otherwise
-    """
-    return db.users.find_one({"id": user_id})
-```
-
-## React Components
-
-### Function Components
-```tsx
-interface ButtonProps {
-  variant: 'primary' | 'secondary'
-  children: React.ReactNode
-  onClick?: () => void
-}
-
-export function Button({ variant, children, onClick }: ButtonProps) {
-  return (
-    <button className={styles[variant]} onClick={onClick}>
-      {children}
-    </button>
-  )
-}
-```
-
-### Hooks Rules
-- Only call at top level
-- Only call from React functions
-- Custom hooks start with `use`
-
-## Error Handling
-
-### Do
-```typescript
-try {
-  const result = await riskyOperation()
-  return result
-} catch (error) {
-  logger.error('Operation failed', { error })
-  throw new AppError('OPERATION_FAILED', 'Meaningful message')
-}
-```
-
-### Don't
-```typescript
-try {
-  const result = await riskyOperation()
-} catch (e) {
-  console.log(e)  // ❌ Silent failure
-}
-```
-
-## Comments
-
-### When to Comment
-- Complex algorithms
-- Non-obvious business logic
-- Workarounds with context
-- Public API documentation
-
-### When NOT to Comment
-```typescript
-// Get the user  ❌ (obvious)
-const user = getUser()
-
-// Increment counter ❌ (obvious)
-counter++
-```
-
-## Imports
-
-### Order
-1. External packages
-2. Internal modules
-3. Relative imports
-4. Types/interfaces
-
-```typescript
-// External
-import React from 'react'
-import { useQuery } from '@tanstack/react-query'
-
-// Internal
-import { useAuth } from '@/hooks/useAuth'
-import { Button } from '@/components/ui/Button'
-
-// Relative
-import { formatDate } from './utils'
-
-// Types
-import type { User } from '@/types'
-```
-
----
-
-*Update this file to match your project's specific standards.*
-

package/.catalyst/standards/git-workflow.md

@@ -1,181 +0,0 @@
-# Git Workflow
-
-Branch management and commit conventions.
-
-## Branch Strategy
-
-### Main Branches
-- `main` - Production-ready code
-- `develop` - Integration branch (optional)
-
-### Feature Branches
-```
-feature/{spec-name}
-feature/2025-11-29-stripe-integration
-```
-
-### Other Branches
-```
-fix/{issue-number}-description
-hotfix/{issue-number}-description
-refactor/{description}
-```
-
-## Commit Messages
-
-### Conventional Commits
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer]
-```
-
-### Types
-| Type | Use |
-|------|-----|
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `docs` | Documentation |
-| `style` | Formatting |
-| `refactor` | Code restructure |
-| `test` | Tests |
-| `chore` | Maintenance |
-
-### Examples
-
-```bash
-# Feature
-feat(subscriptions): add stripe checkout integration
-
-# Fix
-fix(auth): resolve token refresh race condition
-
-# With body
-feat(pricing): implement dynamic pricing page
-
-- Add plan comparison table
-- Implement feature tooltips
-- Add annual/monthly toggle
-
-Spec: 2025-11-29-pricing
-```
-
-## Workflow
-
-### Starting Work
-
-```bash
-# Update main
-git checkout main
-git pull
-
-# Create feature branch
-git checkout -b feature/2025-11-29-stripe-integration
-```
-
-### During Development
-
-```bash
-# Commit often
-git add .
-git commit -m "feat(stripe): add subscription service"
-
-# Keep updated with main
-git fetch origin
-git rebase origin/main
-```
-
-### Completing Work
-
-```bash
-# Ensure tests pass
-npm test
-
-# Push branch
-git push origin feature/2025-11-29-stripe-integration
-
-# Create PR or merge
-```
-
-## Code Review
-
-### PR Requirements
-- [ ] Tests pass
-- [ ] Linting clean
-- [ ] Spec reference in description
-- [ ] Changes documented
-
-### PR Template
-
-```markdown
-## Description
-Brief description of changes
-
-## Spec Reference
-.catalyst/specs/2025-11-29-stripe-integration
-
-## Changes
-- Added subscription service
-- Created checkout flow
-- Added webhook handlers
-
-## Testing
-- [ ] Unit tests added
-- [ ] E2E tests added
-- [ ] Manual testing done
-
-## Screenshots
-(if UI changes)
-```
-
-## Merge Strategy
-
-### Squash Merge (Recommended)
-- Clean history
-- One commit per feature
-- Easy revert
-
-### Merge Commit
-- Preserve full history
-- See individual commits
-- More verbose
-
-## Tagging Releases
-
-```bash
-# Semantic versioning
-git tag -a v1.0.0 -m "Release 1.0.0"
-git push origin v1.0.0
-```
-
-## Emergency Hotfix
-
-```bash
-# Branch from main
-git checkout main
-git checkout -b hotfix/critical-auth-fix
-
-# Fix, test, commit
-git commit -m "fix(auth): patch critical vulnerability"
-
-# Merge directly to main
-git checkout main
-git merge hotfix/critical-auth-fix
-git push
-```
-
-## Don'ts
-
-- ❌ Commit directly to main
-- ❌ Force push to shared branches
-- ❌ Commit secrets or credentials
-- ❌ Large commits without description
-- ❌ Merge without tests passing
-
----
-
-*Adjust branch naming and merge strategy for your team.*
-

package/.catalyst/standards/testing.md

@@ -1,185 +0,0 @@
-# Testing Standards
-
-Guidelines for writing and organizing tests.
-
-## Philosophy
-
-**TDD is mandatory** - Tests are written BEFORE implementation.
-
-```
-1. Write test → ❌ FAIL (Red)
-2. Write minimal code → ✅ PASS (Green)
-3. Refactor → ✅ PASS (Refactor)
-```
-
-## Test Types
-
-### Unit Tests
-- Test individual functions/components in isolation
-- Mock external dependencies
-- Fast execution
-- High coverage
-
-### Integration Tests
-- Test multiple units together
-- Real database (test instance)
-- API endpoint testing
-- Moderate coverage
-
-### E2E Tests
-- Test complete user flows
-- Real browser automation
-- Critical paths only
-- Selective coverage
-
-## Test Structure
-
-### Arrange-Act-Assert
-```typescript
-it('should calculate total with discount', () => {
-  // Arrange
-  const items = [{ price: 100 }, { price: 50 }]
-  const discount = 0.1
-  
-  // Act
-  const total = calculateTotal(items, discount)
-  
-  // Assert
-  expect(total).toBe(135)
-})
-```
-
-### Descriptive Names
-```typescript
-// Good
-describe('UserService', () => {
-  describe('createUser', () => {
-    it('should create user with valid data', () => {})
-    it('should throw on duplicate email', () => {})
-    it('should hash password before saving', () => {})
-  })
-})
-
-// Bad
-describe('tests', () => {
-  it('test 1', () => {})  // ❌
-  it('works', () => {})   // ❌
-})
-```
-
-## Test Organization
-
-### File Location
-```
-src/
-├── services/
-│   ├── user.ts
-│   └── user.test.ts      # Co-located
-└── __tests__/            # Or centralized
-    └── services/
-        └── user.test.ts
-```
-
-### Naming
-- `*.test.ts` for unit tests
-- `*.spec.ts` for integration tests
-- `*.e2e.ts` for end-to-end tests
-
-## Mocking Guidelines
-
-### When to Mock
-- External APIs
-- Database (for unit tests)
-- Time-dependent functions
-- Random values
-
-### When NOT to Mock
-- Internal business logic
-- Simple utility functions
-- Integration test boundaries
-
-### Mock Example
-```typescript
-import { vi } from 'vitest'
-
-// Mock external service
-vi.mock('@/services/stripe', () => ({
-  createSubscription: vi.fn().mockResolvedValue({ id: 'sub_123' }),
-}))
-
-// Reset between tests
-beforeEach(() => {
-  vi.clearAllMocks()
-})
-```
-
-## Fixtures and Factories
-
-### Factory Pattern
-```typescript
-// factories/user.ts
-export function createUser(overrides: Partial<User> = {}): User {
-  return {
-    id: faker.string.uuid(),
-    email: faker.internet.email(),
-    name: faker.person.fullName(),
-    ...overrides,
-  }
-}
-```
-
-### Database Seeding
-```typescript
-// fixtures/seed.ts
-export async function seedTestData(db: Database) {
-  const users = await db.users.createMany([
-    createUser({ email: 'admin@test.com' }),
-    createUser({ email: 'user@test.com' }),
-  ])
-  return { users }
-}
-```
-
-## Coverage Requirements
-
-| Type | Target |
-|------|--------|
-| Unit Tests | 80% |
-| Integration | Critical paths |
-| E2E | Happy paths |
-
-## Test Commands
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm test -- --coverage
-
-# Run specific file
-npm test -- user.test.ts
-
-# Run in watch mode
-npm test -- --watch
-
-# Run E2E
-npm run test:e2e
-```
-
-## CI Integration
-
-```yaml
-test:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - run: npm ci
-    - run: npm test -- --coverage
-    - run: npm run test:e2e
-```
-
----
-
-*Update coverage targets and commands for your project.*
-