scene-capability-engine 3.6.64 → 3.6.67

package/docs/integration-modes.md

@@ -1,529 +1,113 @@
-# Integration Modes Guide
+# Integration Modes
 
-> Three ways to integrate sce with your AI coding tools
+> Choose the mode based on how much direct control your AI runtime has inside the repository.
 
 ---
 
-**Version**: 1.42.0  
-**Last Updated**: 2026-02-11  
-**Audience**: Intermediate  
-**Estimated Time**: 8 minutes
+## Mode 1: Takeover Mode
 
----
-
-## Overview
-
-sce supports three integration modes to work with different AI coding tools. Each mode offers different levels of automation and suits different workflows.
-
-```mermaid
-graph TD
-    A[sce Integration] --> B[Native Integration]
-    A --> C[Manual Export]
-    A --> D[Watch Mode]
-    B --> E[AI IDE]
-    C --> F[Cursor/Claude/VS Code]
-    D --> G[All Tools]
-```
-
----
-
-## Mode 1: Native Integration ⭐
-
-**Best for:** AI IDE users  
-**Automation Level:** Fully Automatic  
-**Setup Complexity:** None (built-in)
-
-### How It Works
-
-With native integration, the AI tool directly accesses sce without any manual steps. The AI can read Specs, export context, and update tasks automatically.
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant AI Tool
-    participant sce
-    
-    User->>AI Tool: "Implement user login"
-    AI Tool->>sce: Read Spec files directly
-    sce->>AI Tool: Spec content
-    AI Tool->>AI Tool: Generate code
-    AI Tool->>sce: Update task status
-    AI Tool->>User: Code generated
-```
-
-### Supported Tools
-
-- **AI IDE** - Full native support
-
-### Workflow Example
-
-```
-You: "Implement the user login feature"
-
-SCE AI: 
-  [Automatically reads .sce/specs/01-00-user-login/]
-  [Understands requirements and design]
-  [Generates code]
-  [Updates tasks.md automatically]
-  
-  ✓ Implemented AuthController
-  ✓ Implemented AuthService
-  ✓ Updated task 1.1 to complete
-```
-
-### Advantages
-
-- ✅ **Zero manual steps** - AI handles everything
-- ✅ **Always up-to-date** - AI reads latest Spec files
-- ✅ **Automatic task tracking** - AI updates task status
-- ✅ **Seamless workflow** - No context switching
-
-### Limitations
-
-- ❌ **Tool-specific** - Only works with AI IDE currently
-- ❌ **Requires compatible AI** - AI must support file system access
-
----
-
-## Mode 2: Manual Export
-
-**Best for:** Claude Code, ChatGPT, Cursor, VS Code + Copilot  
-**Automation Level:** AI-Driven (for tools with command execution) or Semi-Manual (for web tools)  
-**Setup Complexity:** Low
-
-### How It Works
-
-The AI tool can directly call sce commands during your conversation. You stay in your familiar AI tool interface - the AI handles sce interaction automatically.
+This is the preferred mode.
 
-```mermaid
-sequenceDiagram
-    participant User
-    participant AI Tool
-    participant sce
-    
-    User->>AI Tool: "Implement user login feature"
-    AI Tool->>sce: sce context export user-login
-    sce->>AI Tool: context-export.md content
-    AI Tool->>AI Tool: Generate code based on Spec
-    AI Tool->>User: Here's the implementation
-    AI Tool->>sce: Update tasks.md
-```
-
-**Note:** For AI tools without command execution (like ChatGPT web), you can manually export and paste as a fallback.
-
-### Supported Tools
-
-- **Claude Code** - Large context window, excellent understanding
-- **ChatGPT** - Good for conversational development
-- **Cursor** - IDE integration with AI pair programming
-- **VS Code + Copilot** - Inline suggestions with context
-- **Any AI tool** - Works with any tool that accepts text input
+Use it when the AI runtime can read files, execute commands, and write changes in the repo.
 
-### Workflow Example
+### Characteristics
 
-**With AI tools that can execute commands (Cursor, Windsurf, Claude Desktop):**
+- SCE takes over the project with `sce adopt`
+- AI reads `.sce/README.md`, steering, and active Spec files
+- work is staged through `studio`, `spec`, `task`, `project`, and `semantic` commands
+- artifacts are written under governed Spec directories
 
-```
-You: "I have a Spec for user login at 01-00-user-login. 
-     Please implement task 1.1: Create AuthController"
-
-AI Tool: 
-  [Executes: sce context export 01-00-user-login]
-  [Reads the exported context]
-  [Generates AuthController code]
-  [Updates tasks.md automatically]
-  
-  ✓ Created AuthController with login/logout methods
-  ✓ Updated task 1.1 to complete
-```
-
-**With web-based AI tools (ChatGPT, Claude web):**
+### Typical Commands
 
 ```bash
-# You run this once
-sce context export 01-00-user-login
-cat .sce/specs/01-00-user-login/context-export.md | pbcopy
-
-# Then paste into AI tool
-You: "Here's my Spec context: [paste]
-     Please implement task 1.1: Create AuthController"
-
-AI: [Generates code based on your Spec]
-
-# You update tasks manually
-# Edit .sce/specs/01-00-user-login/tasks.md
+sce status
+sce studio plan --goal "continue current work" --json
+sce spec bootstrap --name 01-00-example --scene scene.example --non-interactive
+sce spec pipeline run --spec 01-00-example --scene scene.example
+sce spec gate run --spec 01-00-example --scene scene.example --json
 ```
 
-### Advantages
-
-- ✅ **Works with any AI tool** - Universal compatibility
-- ✅ **AI can call sce directly** - For tools with command execution
-- ✅ **Fallback to manual** - Copy-paste for web-based tools
-- ✅ **Simple setup** - No configuration needed
-- ✅ **Reliable** - No dependencies on special integrations
-
-### Limitations
+### Use This For
 
-- ❌ **Varies by tool** - Command execution depends on AI tool capabilities
-- ❌ **Manual fallback** - Web-based tools require copy-paste
-- ❌ **Context refresh** - May need to re-export after Spec changes (unless using Watch Mode)
-
-### Optimization Tips
-
-**Create shell aliases for faster export:**
-
-```bash
-# Add to ~/.bashrc or ~/.zshrc
-alias sce-clip='sce context export $1 && cat .sce/specs/$1/context-export.md | pbcopy && echo "✅ Context copied to clipboard"'
-
-# Usage
-sce-clip 01-00-user-login
-# Now just paste into your AI tool
-```
-
-**Generate task-specific prompts:**
-```bash
-# Instead of exporting entire Spec
-sce prompt generate 01-00-user-login 1.1
-
-# Generates focused prompt for just task 1.1
-```
+- Codex CLI
+- Claude Code
+- Kiro
+- shell-capable IDE assistants
 
 ---
 
-## Mode 3: Watch Mode 🔄
-
-**Best for:** Frequent Spec changes, team collaboration  
-**Automation Level:** Automatic (after setup)  
-**Setup Complexity:** Medium
-
-### How It Works
-
-sce monitors your Spec files for changes and automatically re-exports context. Your AI tool can always access the latest context without manual export.
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant sce Watch
-    participant Spec Files
-    participant AI Tool
-    
-    User->>Spec Files: Edit requirements.md
-    Spec Files->>sce Watch: File changed event
-    sce Watch->>sce Watch: Auto-export context
-    sce Watch->>Spec Files: Update context-export.md
-    User->>AI Tool: Use latest context
-    AI Tool->>Spec Files: Read context-export.md
-```
+## Mode 2: Compatibility Export Mode
 
-### Supported Tools
+Use this only when the AI runtime cannot reliably execute SCE inside the repo.
 
-- **All tools** - Works with any AI tool
-- **Best with:** Windsurf, Cline (can execute commands)
-- **Good with:** Cursor, Claude (manual context refresh)
+### Characteristics
 
-### Setup
+- operator exports governed context manually
+- AI works from exported context blocks
+- final repo state still returns to SCE governance
 
-**1. Initialize watch mode:**
-```bash
-sce watch init
-```
+### Typical Commands
 
-**2. Install auto-export preset:**
 ```bash
-sce watch install context-export
+sce context export 01-00-example
+sce prompt generate 01-00-example 1.1
 ```
 
-**3. Start watching:**
-```bash
-sce watch start
-```
+### Use This For
 
-**4. Verify it's running:**
-```bash
-sce watch status
-```
-
-Expected output:
-```
-Watch Mode: Active
-Watching: .sce/specs/**/*.md
-Actions: context-export
-Last execution: 2 minutes ago
-```
-
-### Workflow Example
-
-**With watch mode running:**
-
-1. **Edit your Spec** (e.g., add a new requirement)
-   ```bash
-   # Edit .sce/specs/01-00-user-login/requirements.md
-   ```
-
-2. **sce automatically detects the change**
-   ```
-   [Watch Mode] Detected change: requirements.md
-   [Watch Mode] Exporting context for 01-00-user-login...
-   [Watch Mode] ✓ Context exported
-   ```
-
-3. **Use updated context immediately**
-   ```bash
-   # Context is already up-to-date
-   cat .sce/specs/01-00-user-login/context-export.md | pbcopy
-   ```
-
-### Advantages
-
-- ✅ **Always up-to-date** - Context auto-updates on Spec changes
-- ✅ **No manual export** - Set it and forget it
-- ✅ **Great for iteration** - Refine Specs without re-exporting
-- ✅ **Team-friendly** - Everyone gets latest context
-
-### Limitations
-
-- ❌ **Requires setup** - Initial configuration needed
-- ❌ **Background process** - Must keep watch mode running
-- ❌ **Resource usage** - Monitors file system continuously
-
-### Advanced Configuration
-
-**Custom watch patterns:**
-```json
-{
-  "patterns": [
-    ".sce/specs/**/requirements.md",
-    ".sce/specs/**/design.md",
-    ".sce/specs/**/tasks.md"
-  ],
-  "actions": [
-    {
-      "name": "auto-export",
-      "command": "sce context export ${spec-name}"
-    }
-  ]
-}
-```
-
-**Multiple actions:**
-```bash
-# Install multiple presets
-sce watch install context-export
-sce watch install prompt-regen
-sce watch install auto-sync
-```
+- read-only chat tools
+- restricted enterprise assistants
+- temporary fallback during tool onboarding
 
 ---
 
-## Choosing the Right Mode
+## Mode 3: Native Runtime Mode
 
-### Decision Matrix
+This is the long-term direction SCE is actively building toward.
 
-| Factor | Native | Manual Export | Watch Mode |
-|--------|--------|---------------|------------|
-| **Setup Time** | None | None | 5 minutes |
-| **Automation** | Full | None | Partial |
-| **Tool Support** | SCE only | All tools | All tools |
-| **Context Freshness** | Always fresh | Manual refresh | Auto-refresh |
-| **Task Tracking** | Automatic | Manual | Manual |
-| **Best For** | SCE users | Quick start | Active development |
+### Characteristics
 
-### Recommendations by Tool
+- less dependency on host-tool-specific workflows
+- SCE-native semantic observation, replay, evaluation, and backflow
+- operator control plane and shared-source governance move into SCE-owned surfaces
 
-**AI IDE:**
-- ✅ Use **Native Integration** (built-in)
-- No setup needed, fully automatic
+### Use This For
 
-**Windsurf / Cline:**
-- ✅ Use **Manual Export** initially
-- ⭐ Upgrade to **Watch Mode** for active projects
-- These tools can execute sce commands directly
-
-**Claude Code / ChatGPT:**
-- ✅ Use **Manual Export**
-- Create shell aliases for faster workflow
-- Use task-specific prompts for large Specs
-
-**Cursor:**
-- ✅ Use **Manual Export** with prompt generation
-- ⭐ Consider **Watch Mode** for frequently changing Specs
-- Cursor can read updated context files automatically
-
-**VS Code + Copilot:**
-- ✅ Use **Manual Export**
-- Reference Spec files in code comments
-- Copilot reads project files automatically
-
-**Generic AI Tools:**
-- ✅ Use **Manual Export**
-- Universal compatibility
-- Simple copy-paste workflow
+- projects investing in SCE as the long-term control plane
+- scenarios where host tool behavior should become an interchangeable shell
 
 ---
 
-## Hybrid Approaches
+## Mode Selection Rule
 
-### Manual Export + Watch Mode
+Choose the strongest mode your environment supports:
 
-Use watch mode to keep context fresh, but still manually provide context to AI:
+1. `Takeover Mode`
+2. `Compatibility Export Mode`
+3. `Native Runtime Mode` as features become available in your rollout path
 
-```bash
-# Terminal 1: Keep watch mode running
-sce watch start
-
-# Terminal 2: Work normally
-# Edit Specs, context auto-updates
-# Copy latest context when needed
-cat .sce/specs/01-00-user-login/context-export.md | pbcopy
-```
-
-**Benefits:**
-- Context always fresh
-- Full control over when to provide context to AI
-- Best of both worlds
-
-### Native + Manual Export
-
-Use native integration primarily, but export for sharing:
-
-```bash
-# Work with AI IDE (native integration)
-# When sharing with team member using different tool:
-sce context export 01-00-user-login
-# Send context-export.md to teammate
-```
-
-**Benefits:**
-- Seamless personal workflow
-- Easy collaboration with non-SCE users
+Do not default backward to compatibility mode when direct governed execution is available.
 
 ---
 
-## Context Flow Visualization
-
-### Complete Context Flow
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant sce as sce
-    participant Spec as Spec Files
-    participant AI as AI Tool
-    
-    Dev->>sce: Create Spec
-    sce->>Spec: Generate requirements.md, design.md, tasks.md
-    Dev->>Spec: Edit Spec files
-    
-    alt Native Integration
-        AI->>Spec: Read files directly
-        AI->>Dev: Generate code
-        AI->>Spec: Update tasks.md
-    else Manual Export
-        Dev->>sce: sce context export
-        sce->>Spec: Generate context-export.md
-        Dev->>AI: Provide context
-        AI->>Dev: Generate code
-        Dev->>Spec: Update tasks.md
-    else Watch Mode
-        Spec->>sce: File change event
-        sce->>Spec: Auto-generate context-export.md
-        Dev->>AI: Provide context
-        AI->>Dev: Generate code
-        Dev->>Spec: Update tasks.md
-    end
-```
-
----
-
-## Best Practices
-
-### For All Modes
-
-1. **Keep Specs updated** - Outdated Specs lead to incorrect code
-2. **Use version control** - Commit Spec changes
-3. **Review AI output** - AI follows Spec, but verify correctness
-4. **Update tasks promptly** - Track progress accurately
-
-### For Manual Export
+## Shared Rules Across All Modes
 
-1. **Create aliases** - Speed up export workflow
-2. **Use task-specific prompts** - For large Specs
-3. **Re-export after changes** - Keep context fresh
-4. **Include steering rules** - For consistent AI behavior
-
-### For Watch Mode
-
-1. **Start watch at project start** - Make it part of your routine
-2. **Check watch status** - Ensure it's running
-3. **Monitor logs** - Catch any export errors
-4. **Stop when not needed** - Save system resources
-
----
-
-## Troubleshooting
-
-### Native Integration Issues
-
-**Problem:** AI doesn't see Spec files  
-**Solution:** Ensure `.sce/specs/` directory exists and has correct permissions
-
-### Manual Export Issues
-
-**Problem:** Context file too large for AI tool  
-**Solution:** Use task-specific prompts:
-```bash
-sce prompt generate spec-name task-id
-```
-
-**Problem:** AI doesn't follow Spec  
-**Solution:** Be explicit in prompt: "Strictly follow the design document"
-
-### Watch Mode Issues
-
-**Problem:** Watch mode not detecting changes  
-**Solution:** 
-```bash
-sce watch stop
-sce watch start
-```
-
-**Problem:** Context not updating  
-**Solution:** Check watch logs:
-```bash
-sce watch logs
-```
-
----
-
-## Related Documentation
-
-- **[Quick Start Guide](quick-start.md)** - Get started with sce
-- **[Tool-Specific Guides](tools/)** - Detailed guides for each AI tool
-- **[Spec Workflow](spec-workflow.md)** - Understanding Specs
-- **[Command Reference](command-reference.md)** - All sce commands
+- `Four Teachings + Little Nine` remain the supreme execution baseline
+- the project may host multiple collaboration channels in parallel
+- `CURRENT_CONTEXT.md` is summary-only
+- generated artifacts default to the active Spec subtree
+- if no active Spec exists yet, create or route through a governed general Spec
+- repeated failed localization attempts must move into errorbook + bisection-style debug convergence
 
 ---
 
-## Summary
-
-**Three Integration Modes:**
-
-1. **Native Integration** - Fully automatic (AI IDE)
-2. **Manual Export** - Universal compatibility (all tools)
-3. **Watch Mode** - Auto-refresh context (all tools)
+## Related Docs
 
-**Choose based on:**
-- Your AI tool's capabilities
-- Your workflow preferences
-- Project activity level
-
-**Start simple, upgrade as needed:**
-```
-Manual Export → Watch Mode → Native Integration
-```
+- [Quick Start with AI Tools](./quick-start-with-ai-tools.md)
+- [Integration Philosophy](./integration-philosophy.md)
+- [Command Reference](./command-reference.md)
 
 ---
 
-**Version**: 1.42.0  
-**Last Updated**: 2026-02-11
+**Version**: 3.6.67
+**Last Updated**: 2026-03-29