catalyst-os 0.1.0

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

@@ -0,0 +1,11 @@
+# Project Foundation Configuration
+
+# Command to initialize project foundation
+command: "/catalyze-project"
+
+# Generated files
+generated_files:
+  mission.md: "Project vision and goals"
+  roadmap.md: "Development phases"
+  tech-stack.md: "Technology decisions"
+

package/.catalyst/spec-structure.yaml

@@ -0,0 +1,241 @@
+# Spec Folder Structure
+# Single source of truth - all agents and commands reference this file
+
+version: 3
+
+folder_pattern: ".catalyst/specs/YYYY-MM-DD-{slug}/"
+
+files:
+  spec.md:
+    owner: scribe
+    purpose: Requirements + frontmatter (context assembly metadata)
+    created: catalyze-spec
+    updated_by: [scribe, arbiter]
+    note: |
+      Frontmatter enables cross-spec context assembly.
+      Body contains requirements and acceptance criteria.
+
+  research.md:
+    owner: scribe
+    purpose: All research findings (append-only)
+    created: catalyze-spec
+    updated_by: [scout, seer, oracle, scribe]
+    pattern: append
+
+  tasks.md:
+    owner: forger
+    purpose: DAG + progress + decisions + session context (THE living doc)
+    created: build-spec
+    updated_by: [forger, forge-master, builders]
+    pattern: living
+    note: |
+      ONE FILE to read when resuming work.
+      Contains everything about execution state.
+
+  handoff.md:
+    owner: scribe
+    purpose: Human-readable summary (colleague walkthrough)
+    created: build-spec (started), validate-spec (finalized)
+    updated_by: [scribe, arbiter]
+    pattern: narrative
+    note: |
+      Written like explaining to a colleague.
+      5 minutes to read, not 50.
+
+  validation.md:
+    owner: arbiter
+    purpose: Test results, quality checks
+    created: validate-spec
+    updated_by: [arbiter, enforcer, sentinel, inquisitor, watcher]
+
+  assets/:
+    owner: any
+    purpose: Images, diagrams, mockups
+    created: as-needed
+
+statuses:
+  - DRAFT
+  - IN_PROGRESS
+  - VALIDATING
+  - COMPLETE
+
+rules:
+  - spec.md has frontmatter for context assembly
+  - tasks.md is THE living document during build
+  - handoff.md is human-first, no heavy YAML
+  - One file to resume = tasks.md
+
+# =============================================================================
+# SPEC.MD SCHEMA
+# Requirements + frontmatter for context assembly
+# =============================================================================
+
+spec_schema:
+  frontmatter:
+    required:
+      spec: string          # YYYY-MM-DD-slug
+      status: enum          # draft | in_progress | validating | complete
+      domain: string        # auth, payments, ui, api, database, etc.
+
+    context_assembly:
+      provides:             # What this spec creates
+        - type: string
+      requires:             # Dependencies on other specs
+        - spec: string
+          needed: string
+      affects:              # What future work this impacts
+        - type: string
+
+    knowledge:
+      patterns_established: # Technical decisions (filled during/after build)
+        - type: string
+      key_files:            # Important files created
+        - type: string
+      key_decisions:        # Strategic choices with rationale
+        - type: string
+
+  example: |
+    ---
+    spec: 2025-01-11-user-auth
+    status: complete
+    domain: auth
+
+    provides:
+      - User model with password hashing
+      - JWT middleware
+      - Login/signup endpoints
+
+    requires: []
+
+    affects:
+      - All routes needing auth
+      - User-related features
+
+    patterns_established:
+      - argon2 for password hashing (not bcrypt)
+      - jose library for JWT
+      - httpOnly cookies for tokens
+
+    key_files:
+      - src/middleware/auth.ts
+      - src/api/auth/login.ts
+
+    key_decisions:
+      - JWT over sessions (stateless scaling)
+    ---
+
+    # User Authentication
+
+    ## Overview
+    ...requirements here...
+
+# =============================================================================
+# TASKS.MD SCHEMA
+# The ONE file to read when resuming - DAG + progress + decisions + context
+# =============================================================================
+
+tasks_schema:
+  sections:
+    - "## Build DAG"           # Task breakdown with phases
+    - "## Progress"            # Status table
+    - "## Current Session"     # Where we are, what's next
+    - "## Decisions"           # Decisions made during build
+
+  example: |
+    # Tasks: User Authentication
+
+    ## Build DAG
+
+    ### Phase 1: Red (enforcer)
+    | ID | Agent | Scope | Depends On |
+    |----|-------|-------|------------|
+    | tests-auth | enforcer | tests/api/auth/** | - |
+
+    ### Phase 2: Foundation (alchemist)
+    | ID | Agent | Scope | Depends On |
+    |----|-------|-------|------------|
+    | db-schema | alchemist | prisma/schema.prisma | tests-auth |
+
+    ### Phase 3: Parallel Backend (smith × 2)
+    | ID | Agent | Scope | Reads | Depends On |
+    |----|-------|-------|-------|------------|
+    | api-auth | smith-1 | src/api/auth/** | src/types/** | db-schema |
+    | api-user | smith-2 | src/api/user/** | src/types/** | db-schema |
+
+    ## Progress
+
+    | Task | Status | Tests | Commit | Notes |
+    |------|--------|-------|--------|-------|
+    | tests-auth | ✓ Done | 12 failing | a1b2c3d | RED phase complete |
+    | db-schema | ✓ Done | 12 passing | e4f5g6h | |
+    | api-auth | ⚡ Active | 8/12 | - | Working on refresh |
+    | api-user | ⏳ Waiting | - | - | Blocked by api-auth |
+
+    ## Current Session
+
+    **Phase:** 3 - Parallel Backend
+    **Active:** api-auth (smith-1)
+    **Working on:** Refresh token rotation
+    **File:** `src/api/auth/refresh.ts:45`
+    **Next:** Finish refresh, then api-user can start
+
+    ## Decisions
+
+    - **JWT over sessions** - Stateless for horizontal scaling
+    - **15-min access token** - Balance security vs UX
+    - **argon2 over bcrypt** - Better GPU resistance
+
+# =============================================================================
+# HANDOFF.MD TEMPLATE
+# Human-readable - colleague explaining over coffee
+# =============================================================================
+
+handoff_template: |
+  # Handoff: {Spec Name}
+
+  > Status: {status}
+
+  ## TL;DR
+
+  {One paragraph - what was built}
+
+  ## What Changed
+
+  - Change 1
+  - Change 2
+
+  ## Key Decisions
+
+  **Why X over Y?**
+  Rationale here.
+
+  ## How to Test
+
+  1. Step 1
+  2. Step 2
+
+  ## What's Next
+
+  - [ ] Next item
+
+  ## Gotchas
+
+  - Thing that might trip you up
+
+# =============================================================================
+# CONTEXT ASSEMBLY
+# =============================================================================
+
+context_assembly:
+  source: spec.md  # Read frontmatter from spec.md
+
+  on_new_spec:
+    - Scan .catalyst/specs/*/spec.md
+    - Parse YAML frontmatter only
+    - Match by: new spec domain vs existing "affects"
+    - Load: patterns_established, key_files, key_decisions
+    - Inject into agent prompts
+
+  on_resume:
+    - Read tasks.md "## Current Session" section
+    - Continue from recorded position

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

@@ -0,0 +1,109 @@
+# Specifications Configuration
+
+# Command to create a new spec
+command: "/catalyze-spec \"description\""
+
+# Spec folder structure
+structure:
+  root: "specs/"
+  pattern: "YYYY-MM-DD-{slug}"
+
+  # Files in each spec folder
+  files:
+    spec.md:
+      owner: scribe
+      description: "Main specification document"
+      created_by: "/catalyze-spec"
+
+    research.md:
+      owner: scribe
+      description: "Compiled research findings"
+      created_by: "/catalyze-spec"
+
+    tasks.md:
+      owner: forger
+      description: "Build DAG with task breakdown"
+      created_by: "/build-spec"
+      structure:
+        - "Build DAG (phases, scope, dependencies)"
+        - "Task details"
+        - "Progress tracking"
+
+    validation.md:
+      owner: arbiter
+      description: "Quality validation results"
+      created_by: "/validate-spec"
+
+    handoff.md:
+      owner: arbiter
+      description: "Living document, completion summary"
+      created_by: "/validate-spec"
+
+    assets/:
+      owner: any
+      description: "Images, diagrams, visual references"
+
+  # Completed specs location
+  completed: "completed/"
+
+# Pattern library for reusable implementations
+library:
+  root: "library/"
+  description: "Reusable patterns extracted from completed specs"
+  created_by: "/approve-spec (optional)"
+
+  # Auto-detect patterns by keywords
+  pattern_detection:
+    payment-integration.md:
+      keywords: [stripe, payment, billing, subscription, checkout]
+    authentication.md:
+      keywords: [auth, oauth, login, sso, jwt, session]
+    file-storage.md:
+      keywords: [upload, s3, storage, file, media, image]
+    real-time-communication.md:
+      keywords: [websocket, realtime, socket, live, push]
+    notifications.md:
+      keywords: [email, notification, smtp, push, alert]
+    search-implementation.md:
+      keywords: [search, elasticsearch, algolia, fulltext]
+    caching-strategy.md:
+      keywords: [cache, redis, memcached, performance]
+    background-jobs.md:
+      keywords: [queue, job, worker, bull, async, cron]
+
+# Build DAG structure (used by Forger)
+build_dag:
+  phases:
+    foundation:
+      agent: alchemist
+      sequential: true
+      description: "Database schema, core setup"
+
+    contracts:
+      agent: smith
+      sequential: true
+      description: "Shared types/interfaces before parallel work"
+
+    parallel:
+      agents: [smith, shaper]
+      multi_instance: true
+      description: "Scope-isolated parallel implementation"
+      rules:
+        - "Each agent has exclusive write scope"
+        - "Agents can read but not modify shared files"
+        - "No overlapping scopes between parallel tasks"
+
+    integration:
+      agent: enforcer
+      sequential: true
+      description: "Cross-boundary testing"
+
+  task_fields:
+    - id          # Unique identifier
+    - agent       # Which agent type (with instance: smith-1, shaper-2)
+    - scope       # Files with exclusive write access
+    - reads       # Files with read-only access
+    - depends_on  # Task IDs that must complete first
+    - blocks      # Task patterns this blocks (e.g., api-*, ui-*)
+    - acceptance  # How to verify completion
+    - estimate    # Time estimate (< 2 hours)

package/.catalyst/standards/coding.md

@@ -0,0 +1,187 @@
+# 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.*
+