chati-dev 1.4.0 → 2.0.2

package/framework/migrations/v2.0-to-v2.0.1.yaml

@@ -0,0 +1,132 @@
+# Migration: v2.0.0 → v2.0.1
+# chati.dev Modular CLAUDE.md Pattern
+# Run: npx chati-dev upgrade
+
+from_version: "2.0.0"
+to_version: "2.0.1"
+created_at: "2026-02-13"
+description: "Modular CLAUDE.md — .claude/rules/chati/ auto-loading, CLAUDE.local.md for runtime state"
+
+# Pre-conditions
+preconditions:
+  - check: version_gte
+    value: "2.0.0"
+    message: "Must be on v2.0.0+ to upgrade to v2.0.1"
+  - check: constitution_articles
+    value: 17
+    message: "Constitution must have 17 articles (v2.0.0)"
+
+# Backup these before proceeding
+backup:
+  directories:
+    - chati.dev/
+    - .chati/
+  files:
+    - CLAUDE.md
+    - CLAUDE.local.md
+
+# Operations (executed in order)
+operations:
+  # 1. Create context directory
+  - type: create_directory
+    paths:
+      - chati.dev/context
+
+  # 2. Copy context source files
+  - type: copy_directory
+    source: framework/context
+    destination: chati.dev/context
+    strategy: replace
+    description: "Install context source files (root.md, governance.md, protocols.md, quality.md)"
+
+  # 2b. Deploy context files to .claude/rules/chati/ (auto-loaded by Claude Code)
+  - type: create_directory
+    paths:
+      - .claude/rules/chati
+
+  - type: copy_directory
+    source: framework/context
+    destination: .claude/rules/chati
+    strategy: replace
+    description: "Deploy context files for Claude Code auto-loading (no @ imports needed)"
+
+  # 3. Create CLAUDE.local.md (runtime state)
+  - type: create_file
+    path: CLAUDE.local.md
+    content: |
+      # chati.dev Runtime State
+
+      ## Session Lock
+      **Status: INACTIVE** — Type `/chati` to activate.
+
+      <!-- SESSION-LOCK:INACTIVE -->
+
+      ## Current State
+      - **Agent**: None (ready to start)
+      - **Pipeline**: Pre-start
+      - **Mode**: interactive
+
+      ## Recent Decisions
+      _No decisions yet. Start with /chati._
+
+      ---
+      _Auto-updated by chati.dev orchestrator_
+    condition: not_exists
+
+  # 4. Migrate CLAUDE.md to minimal version (no @ imports — rules auto-loaded)
+  - type: update_file
+    path: CLAUDE.md
+    strategy: replace
+    description: "Replace bloated CLAUDE.md with minimal version (framework rules auto-loaded from .claude/rules/chati/)"
+
+  # 5. Update orchestrator (session lock → CLAUDE.local.md)
+  - type: copy_file
+    source: framework/orchestrator/chati.md
+    destination: chati.dev/orchestrator/chati.md
+    strategy: replace
+    description: "Update orchestrator to reference CLAUDE.local.md instead of CLAUDE.md for session lock"
+
+  # 6. Update config version
+  - type: update_yaml
+    path: chati.dev/config.yaml
+    changes:
+      version: "2.0.1"
+      updated_at: "auto"
+      installer_version: "2.0.1"
+
+  # 7. Update .gitignore for CLAUDE.local.md
+  - type: append_file
+    path: .gitignore
+    content: |
+      # chati.dev v2.0.1 — runtime state (not committed)
+      CLAUDE.local.md
+    condition: not_contains
+    check_string: "CLAUDE.local.md"
+
+# Post-migration validation
+validation:
+  - check: file_exists
+    path: chati.dev/context/root.md
+  - check: file_exists
+    path: chati.dev/context/governance.md
+  - check: file_exists
+    path: chati.dev/context/protocols.md
+  - check: file_exists
+    path: chati.dev/context/quality.md
+  - check: file_exists
+    path: CLAUDE.local.md
+  - check: file_exists
+    path: .claude/rules/chati/root.md
+  - check: file_exists
+    path: .claude/rules/chati/governance.md
+  - check: yaml_field
+    path: chati.dev/config.yaml
+    field: version
+    value: "2.0.1"
+
+# Rollback instructions
+rollback:
+  description: "Restore from .chati/backup-{timestamp}/ created during upgrade"
+  steps:
+    - "npx chati-dev upgrade --rollback"
+    - "Or manually: cp -r .chati/backup-{timestamp}/CLAUDE.md CLAUDE.md"

package/framework/orchestrator/chati.md

@@ -518,14 +518,14 @@ Once `/chati` is invoked and a session is active, the orchestrator LOCKS the ses
 When /chati is invoked:
   1. Load session state (Step 1-2 above)
   2. SET session lock = ACTIVE
-  3. Update CLAUDE.md with Session Lock block (see template below)
+  3. Update CLAUDE.local.md with Session Lock block (see template below)
   4. ALL subsequent messages are intercepted by the orchestrator
   5. Messages are routed to current_agent
 ```
 
-### Session Lock Block (CLAUDE.md)
+### Session Lock Block (CLAUDE.local.md)
 
-When the session is active, CLAUDE.md MUST contain this block:
+When the session is active, CLAUDE.local.md MUST contain this block:
 
 ```markdown
 ## ⚠️ Session Lock — ACTIVE
@@ -541,7 +541,8 @@ When the session is active, CLAUDE.md MUST contain this block:
 6. The ONLY way to exit is via explicit exit commands (see below)
 ```
 
-This block is injected into CLAUDE.md when the session starts and removed when the user exits.
+This block is injected into CLAUDE.local.md when the session starts and removed when the user exits.
+CLAUDE.local.md is auto-gitignored — runtime state is never committed.
 
 ### Message Routing (while locked)
 
@@ -598,7 +599,7 @@ When exit is triggered:
      - Decisions made this session
      - Current progress and partial work
      - Pending items
-  3. Update CLAUDE.md:
+  3. Update CLAUDE.local.md:
      - REMOVE Session Lock block
      - UPDATE project status with current state
      - ADD resume instructions:
@@ -617,7 +618,7 @@ When exit is triggered:
 When user types /chati after a previous exit:
   -> Normal Step 5 (Session Resume) flow
   -> Session Lock is RE-ACTIVATED
-  -> CLAUDE.md lock block is RE-INJECTED
+  -> CLAUDE.local.md lock block is RE-INJECTED
   -> User is back in the system seamlessly
 ```
 
@@ -652,6 +653,283 @@ If agent fails repeatedly:
 
 ---
 
+## Authority Boundaries
+
+### Exclusive (only the orchestrator can do this)
+- Route user messages to agents
+- Activate/deactivate agents
+- Execute mode transitions (clarity -> build -> validate -> deploy)
+- Manage session lock (activate/deactivate)
+- Handle deviations and re-routing
+- Manage backlog items
+- Spawn parallel terminals for agents
+- Decide execution mode (human-in-the-loop vs autonomous)
+
+### Allowed (orchestrator may also do this)
+- Read any file in the project (for state detection)
+- Write to .chati/session.yaml (session state)
+- Write to CLAUDE.md (session lock block)
+- Present status dashboards
+- Generate session digests
+
+### Blocked (orchestrator must NEVER do this)
+- Write code or implementation files
+- Write specification documents (artifacts)
+- Modify constitution or config files
+- Make architectural decisions -> redirect to architect agent
+- Write tests -> redirect to dev agent
+- Deploy or configure infrastructure -> redirect to devops agent
+- Modify user's source code in any way
+
+### Redirect Messages
+```
+If user asks for code: "I'll route this to the Dev agent who handles implementation."
+If user asks about architecture: "Let me activate the Architect agent for this."
+If user asks about testing: "The QA agent handles test strategy. Routing now."
+If user asks about deployment: "DevOps agent manages deployment. Routing now."
+```
+
+---
+
+## Task Registry
+
+| Task ID | Description | Trigger | Parallelizable |
+|---------|-------------|---------|----------------|
+| orchestrator-route | Route user intent to correct agent | Every user message | No |
+| orchestrator-resume | Resume session from saved state | /chati or /chati resume | No |
+| orchestrator-status | Display project dashboard | /chati status | No |
+| orchestrator-handoff | Execute agent-to-agent handoff | Agent completion | No |
+| orchestrator-deviation | Handle deviation from pipeline order | Agent deviation signal | No |
+| orchestrator-escalate | Escalate after 3+ agent failures | Repeated failure | No |
+| orchestrator-mode-switch | Execute mode transition | Quality gate pass | No |
+| orchestrator-health | Run framework health check | /chati health or periodic | No |
+| orchestrator-suggest-mode | Suggest execution mode | Post-Brief completion | No |
+| orchestrator-spawn-terminal | Open parallel terminal for agent | Parallelizable task detected | No |
+
+---
+
+## Context Requirements
+
+```yaml
+prism_layers:
+  required: [L0, L1]          # Always need constitution + global rules
+  conditional:
+    L2: true                    # Agent domain (own domain for routing rules)
+    L3: true                    # Workflow (pipeline position awareness)
+    L4: false                   # No task-level context needed for routing
+domains:
+  required:
+    - constitution.yaml         # For enforcement
+    - global.yaml               # For mode governance
+  optional:
+    - agents/*.yaml             # When evaluating agent authority
+    - workflows/*.yaml          # When determining pipeline position
+```
+
+---
+
+## Handoff Protocol
+
+### Receiving Handoffs (from agents)
+```
+Pre-conditions:
+  - Agent self-validation score >= 95%
+  - Handoff file exists at chati.dev/artifacts/handoffs/{agent}-handoff.md
+  - session.yaml updated with agent completion data
+
+On receive:
+  1. Parse handoff file for: score, artifacts_produced, blockers, recommendations
+  2. Update session.yaml: mark agent as completed
+  3. Evaluate next agent in pipeline
+  4. Check if mode transition is triggered
+  5. Prepare context package for next agent
+```
+
+### Sending Handoffs (to agents)
+```
+Context package includes:
+  - Previous agent's handoff summary
+  - Relevant artifacts references
+  - Pipeline position and remaining agents
+  - User level and language
+  - Execution mode (interactive/autonomous)
+  - Backlog items relevant to this agent
+
+Post-conditions:
+  - session.yaml: current_agent updated
+  - CLAUDE.md: current state updated
+  - Agent file loaded and activated
+```
+
+---
+
+## Quality Criteria
+
+Self-validation checklist for orchestrator decisions:
+
+1. **Routing accuracy**: Is the selected agent correct for the user's intent?
+2. **Mode compliance**: Does the operation respect current mode restrictions?
+3. **Pipeline integrity**: Does the routing follow the defined pipeline order?
+4. **Deviation handling**: Was the deviation properly logged and context preserved?
+5. **Session consistency**: Is session.yaml in sync with actual state?
+6. **Language consistency**: Are all interactions in the user's chosen language?
+7. **Constitution compliance**: Has no constitutional article been violated?
+8. **Handoff completeness**: Does the handoff contain all required data?
+9. **Backlog accuracy**: Are all captured items properly categorized?
+10. **User level adaptation**: Is guidance depth appropriate for user level?
+
+Score threshold: 95% (same as agents)
+
+---
+
+## Model Assignment
+
+```yaml
+default: sonnet
+upgrade_to: opus
+upgrade_conditions:
+  - Complex deviation requiring multi-agent re-routing
+  - Backward transition analysis (identifying root cause from QA findings)
+  - Mode override evaluation (assessing risk of skipping phases)
+  - Multi-terminal orchestration (coordinating parallel agents)
+downgrade_to: haiku
+downgrade_conditions:
+  - Simple status queries (/chati status)
+  - Direct pipeline continuation (no deviation, no branching)
+```
+
+---
+
+## Recovery Protocol
+
+```
+Level 1 - Retry:
+  Condition: Agent fails once
+  Action: Re-activate same agent with additional context
+  Max retries: 2
+
+Level 2 - Escalate:
+  Condition: Agent fails 3 consecutive times
+  Action:
+    1. Log failure pattern in session.yaml
+    2. Present options to user:
+       a. Retry with different approach
+       b. Skip agent (document risk)
+       c. Return to previous agent
+    3. If autonomous mode: auto-select safest option
+
+Level 3 - Session Recovery:
+  Condition: session.yaml corrupted or inconsistent
+  Action:
+    1. Attempt reconstruction from CLAUDE.md + artifacts
+    2. Validate reconstructed state against filesystem
+    3. If reconstruction fails: start fresh session preserving artifacts
+
+Level 4 - Graceful Degradation:
+  Condition: Critical system error
+  Action:
+    1. Save current state to .chati/recovery/emergency-{timestamp}.yaml
+    2. Notify user with recovery instructions
+    3. Preserve all artifacts produced so far
+```
+
+---
+
+## Domain Rules
+
+1. **Single Entry Point**: The orchestrator is the ONLY way users interact with chati.dev. No agent is directly accessible.
+2. **Transparent Routing**: Users should understand which agent is active and why, but never need to manage agents directly.
+3. **State Preservation**: Every state change is logged in session.yaml. No action is lossy.
+4. **Fail-Safe Defaults**: When uncertain, default to the most restrictive mode (clarity) and the safest agent.
+5. **Progressive Disclosure**: Show complexity only when the user needs it. Start simple, reveal depth on demand.
+6. **Pipeline Respect**: Never skip pipeline steps without explicit user consent and documented risk.
+7. **Language Fidelity**: Interaction always in user's language. Artifacts always in English. No exceptions.
+8. **Constitution First**: Constitutional rules override all other logic. If there's a conflict, the constitution wins.
+
+---
+
+## Autonomous Behavior
+
+### Human-in-the-Loop Mode
+```
+- Present status and options at each transition
+- Wait for user confirmation before mode transitions
+- Show quality gate results and ask for approval
+- Present deviation analysis and let user decide
+- Verbose logging of all decisions
+```
+
+### Autonomous Mode
+```
+- Execute pipeline transitions silently when gates pass (score >= 95%)
+- Auto-resolve simple deviations (redirect to correct agent)
+- Pause only on:
+  - Quality gate failure (score < 95%)
+  - Critical blockers (C01-C14)
+  - Mode override requests
+  - 3+ consecutive agent failures
+- Report progress periodically (after each agent completion)
+- Batch backlog items for review at quality gates
+```
+
+### Mode Suggestion Logic
+```
+After Brief agent completes, analyze:
+  - Project type: greenfield (suggest human-in-the-loop) | brownfield-known (suggest autonomous)
+  - Complexity: high (> 10 tasks estimated) -> human-in-the-loop
+  - Risk level: high (infra, security, DB) -> human-in-the-loop
+  - User history: first time -> human-in-the-loop | experienced -> autonomous
+  - Recent gotchas in this domain -> human-in-the-loop
+
+Present suggestion with reasoning. User always has final say.
+```
+
+---
+
+## Parallelization Hints
+
+### Parallelizable Agent Groups
+```
+Group 1 (post-Brief):
+  - Detail + Architect + UX
+  - Can run in 3 parallel terminals
+  - Each writes to isolated artifact directories
+  - Orchestrator collects and merges results
+
+Group 2 (Dev tasks):
+  - Independent dev tasks can run in N parallel terminals
+  - Each terminal has isolated write scope
+  - Orchestrator monitors and collects results
+
+NOT parallelizable:
+  - WU (needs user interaction)
+  - Brief (needs user interaction)
+  - Phases (depends on Detail + Architect + UX)
+  - Tasks (depends on Phases)
+  - QA-Planning (validates everything)
+  - QA-Implementation (validates everything)
+  - DevOps (deployment is sequential)
+```
+
+### Terminal Spawning Protocol
+```
+1. Identify parallelizable tasks in current pipeline position
+2. For each parallel task:
+   a. Create isolated write scope mapping
+   b. Prepare PRISM context with agent-specific domain
+   c. Spawn terminal with: agent file + context + write scope
+3. Monitor all terminals for:
+   - Completion (success/failure)
+   - Blocker detection (pause all if critical)
+   - Progress updates
+4. When all terminals complete:
+   a. Collect handoff files from all agents
+   b. Merge results into unified context
+   c. Continue pipeline with merged context
+```
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/tasks/architect-api-design.md

@@ -0,0 +1,63 @@
+---
+id: architect-api-design
+agent: architect
+trigger: architect-stack-selection
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [api-design.yaml]
+handoff_to: architect-db-design
+autonomous_gate: true
+criteria:
+  - All API endpoints specified with request/response schemas
+  - RESTful conventions followed
+  - Error responses documented
+---
+# Design API Contracts
+
+## Purpose
+Design complete API contracts with detailed request/response specifications.
+
+## Steps
+Define endpoints:
+- POST /api/auth/register
+- POST /api/auth/login
+- GET /api/posts
+- POST /api/posts
+- GET /api/posts/:id
+- PUT /api/posts/:id
+- DELETE /api/posts/:id
+- GET /api/search
+
+For each: method, path, auth required, request schema, response schema, error codes.
+
+Use OpenAPI/Swagger format.
+
+## Output Format
+```yaml
+# api-design.yaml
+openapi: 3.0.0
+paths:
+  /api/auth/register:
+    post:
+      summary: Register new user
+      requestBody:
+        schema:
+          type: object
+          properties:
+            email: {type: string, format: email}
+            password: {type: string, minLength: 8}
+          required: [email, password]
+      responses:
+        201:
+          description: User created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user: {type: object}
+                  token: {type: string}
+        400: {description: Validation error}
+        409: {description: Email already exists}
+```

package/framework/tasks/architect-consolidate.md

@@ -0,0 +1,47 @@
+---
+id: architect-consolidate
+agent: architect
+trigger: architect-security-review
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [architecture-final.yaml]
+handoff_to: phases
+autonomous_gate: true
+criteria:
+  - All architecture artifacts consolidated
+  - Architecture Decision Records documented
+  - Complete architecture package ready
+---
+# Consolidate Architecture Documentation
+
+## Purpose
+Merge all architecture artifacts into final comprehensive architecture document.
+
+## Steps
+Combine: architecture.yaml, stack-selection.yaml, api-design.yaml, db-design.yaml, security-review.yaml
+
+Add:
+- System architecture diagram
+- Deployment architecture
+- ADRs for major decisions
+
+## Output Format
+```yaml
+# architecture-final.yaml
+timestamp: 2026-02-13T16:30:00Z
+completeness: 100%
+[All architecture details consolidated]
+architecture_decisions:
+  - id: ADR-001
+    title: Use Supabase as Backend-as-a-Service
+    decision: Use Supabase instead of custom Node.js backend
+    rationale: Team lacks backend expertise, Supabase provides auth, database, storage
+    status: accepted
+  - id: ADR-002
+    title: Use TanStack Query for server state
+    decision: Use TanStack Query instead of Redux
+    rationale: Server state caching, automatic refetching, simpler than Redux
+    status: accepted
+next_phase: phases
+```

package/framework/tasks/architect-db-design.md

@@ -0,0 +1,73 @@
+---
+id: architect-db-design
+agent: architect
+trigger: architect-api-design
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [db-design.yaml]
+handoff_to: architect-security-review
+autonomous_gate: true
+criteria:
+  - Database schema defined with all tables and relationships
+  - Indexes specified for query optimization
+  - Constraints documented
+---
+# Design Database Schema
+
+## Purpose
+Create complete database schema with tables, relationships, indexes, and constraints.
+
+## Steps
+Define tables:
+- users (id, email, password_hash, created_at, updated_at)
+- posts (id, user_id, title, content, tags, image_urls, published_at, created_at, updated_at)
+
+Define indexes:
+- users.email (unique)
+- posts.user_id (foreign key, indexed)
+- posts.published_at (for sorting)
+- posts.tags (GIN index for array search in PostgreSQL)
+
+Document relationships and cascade rules.
+
+## Output Format
+```yaml
+# db-design.yaml
+tables:
+  users:
+    columns:
+      id: uuid PRIMARY KEY DEFAULT gen_random_uuid()
+      email: text UNIQUE NOT NULL
+      password_hash: text NOT NULL
+      created_at: timestamp with time zone DEFAULT now()
+      updated_at: timestamp with time zone DEFAULT now()
+    indexes:
+      - name: idx_users_email
+        columns: [email]
+        unique: true
+  posts:
+    columns:
+      id: uuid PRIMARY KEY DEFAULT gen_random_uuid()
+      user_id: uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE
+      title: text NOT NULL CHECK (length(title) <= 200)
+      content: text NOT NULL
+      tags: text[] DEFAULT '{}'
+      image_urls: text[] DEFAULT '{}'
+      published_at: timestamp with time zone
+      created_at: timestamp with time zone DEFAULT now()
+      updated_at: timestamp with time zone DEFAULT now()
+    indexes:
+      - name: idx_posts_user_id
+        columns: [user_id]
+      - name: idx_posts_published_at
+        columns: [published_at]
+      - name: idx_posts_tags
+        columns: [tags]
+        type: GIN
+relationships:
+  - from: posts.user_id
+    to: users.id
+    type: many_to_one
+    on_delete: CASCADE
+```