@aithr-ai/mcp-server 1.1.7 → 1.2.1

package/index.js

@@ -61,6 +61,12 @@
  * - aether_orchestra_resume: Resume execution
  * - aether_complete_orchestra: Mark complete, generate summary
  * - aether_edit_orchestra: Edit plan without restarting (add/remove/split tasks)
+ * - aether_create_contract: Generate Source of Truth contract before coding
+ *
+ * Workflow Enforcement (v1.2.0):
+ * - aether_orchestra_validate: Check workflow state, prevent skipped steps
+ * - aether_orchestra_checkpoint: Quality gate between phases
+ * - aether_orchestra_guide: Smart guidance on next action to take
  */
 
 const readline = require('readline');
@@ -1099,6 +1105,85 @@ class MCPServer {
           required: ['sessionId', 'action'],
         },
       },
+      {
+        name: 'aether_create_contract',
+        description: 'Generate a Source of Truth contract for the orchestra session. This defines ALL types, schemas, API endpoints, and components BEFORE any code is written. CRITICAL: Run this AFTER setting the plan but BEFORE executing tasks. The contract ensures all agents work from the same definitions and prevents inconsistencies.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            requirements: {
+              type: 'string',
+              description: 'Full project requirements (PRD, feature description, etc.). Be comprehensive - the contract will define everything upfront.',
+            },
+            existingCodeSummary: {
+              type: 'string',
+              description: 'Optional: Summary of existing codebase patterns (auth system, ORM, styling framework) if brownfield project.',
+            },
+          },
+          required: ['sessionId', 'requirements'],
+        },
+      },
+      {
+        name: 'aether_orchestra_validate',
+        description: 'Validate orchestra session state and return required next steps. CALL THIS BEFORE taking any action to ensure you are following the correct workflow. Returns errors if prerequisites are missing and provides the exact tool to call next.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID (optional - uses latest if not provided)',
+            },
+            intendedAction: {
+              type: 'string',
+              enum: ['execute_task', 'approve', 'complete', 'any'],
+              description: 'What you intend to do next. Validation will check if prerequisites are met.',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_orchestra_checkpoint',
+        description: 'Create a quality checkpoint to validate phase completion before proceeding. Checks that all tasks in the phase are complete, artifacts exist, and contract compliance is verified. Returns blockers if validation fails.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            phaseNumber: {
+              type: 'number',
+              description: 'Phase number to validate (optional - validates current phase if not provided)',
+            },
+            validateContract: {
+              type: 'boolean',
+              description: 'Check artifacts for contract compliance (default: true)',
+            },
+            autoAdvance: {
+              type: 'boolean',
+              description: 'Automatically advance to next phase if checkpoint passes (default: false)',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_orchestra_guide',
+        description: 'Get intelligent guidance on what to do next in the orchestra workflow. Returns the exact tool to call, required parameters, and explanation. USE THIS when you are unsure what step comes next.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID (optional - uses latest if not provided)',
+            },
+          },
+        },
+      },
     ];
   }
 
@@ -1277,6 +1362,18 @@ class MCPServer {
         case 'aether_edit_orchestra':
           result = await this.editOrchestra(args);
           break;
+        case 'aether_create_contract':
+          result = await this.createContract(args);
+          break;
+        case 'aether_orchestra_validate':
+          result = await this.orchestraValidate(args);
+          break;
+        case 'aether_orchestra_checkpoint':
+          result = await this.orchestraCheckpoint(args);
+          break;
+        case 'aether_orchestra_guide':
+          result = await this.orchestraGuide(args);
+          break;
         default:
           return this.errorResponse(id, -32602, `Unknown tool: ${name}`);
       }
@@ -3467,6 +3564,63 @@ class MCPServer {
     }
   }
 
+  async createContract(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, requirements, existingCodeSummary } = args;
+
+    if (!sessionId || !requirements) {
+      return { error: 'sessionId and requirements are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/contract`,
+        'POST',
+        {
+          sessionId,
+          requirements,
+          existingCodeSummary,
+        }
+      );
+
+      if (!data.success) {
+        return {
+          success: false,
+          error: data.error || 'Failed to generate contract',
+        };
+      }
+
+      // Summarize what was generated
+      const contract = data.contract || {};
+      const summary = {
+        types: Object.keys(contract.types?.entities || {}).length,
+        tables: Object.keys(contract.schema?.tables || {}).length,
+        endpoints: Object.keys(contract.api?.endpoints || {}).length,
+        components: Object.keys(contract.components?.components || {}).length,
+      };
+
+      return {
+        success: true,
+        sessionId,
+        contractVersion: data.contractVersion || 1,
+        summary: {
+          ...summary,
+          total: summary.types + summary.tables + summary.endpoints + summary.components,
+        },
+        tokensUsed: data.tokensUsed || 0,
+        message: `Contract generated with ${summary.types} types, ${summary.tables} tables, ${summary.endpoints} endpoints, ${summary.components} components`,
+        hint: 'The contract is now stored in the session. All agents will receive relevant contract sections when executing tasks. Use aether_orchestra_approve to begin execution.',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
   async editOrchestra(args) {
     const projectId = config.projectId;
 
@@ -3575,6 +3729,380 @@ class MCPServer {
     }
   }
 
+  /**
+   * Validate orchestra session state and ensure correct workflow
+   */
+  async orchestraValidate(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, intendedAction } = args;
+
+    try {
+      // Get current session status
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'status',
+          sessionId: sessionId || undefined,
+        }
+      );
+
+      if (!data || data.error) {
+        return {
+          valid: false,
+          error: data?.error || 'No orchestra session found',
+          nextStep: {
+            tool: 'aether_start_orchestra',
+            reason: 'Start a new orchestra session first',
+          },
+        };
+      }
+
+      const session = data;
+      const status = session.status;
+      const hasContract = !!session.contract || session.contractVersion > 0;
+      const hasPlan = session.totalTasks > 0;
+
+      // Define the workflow state machine
+      const workflow = {
+        planning: {
+          required: [],
+          missing: !hasPlan ? ['Plan not set'] : [],
+          nextTool: !hasPlan ? 'aether_set_orchestra_plan' : 'aether_create_contract',
+          nextReason: !hasPlan
+            ? 'Set the development plan with phases and tasks'
+            : 'Generate Source of Truth contract before executing',
+        },
+        awaiting_approval: {
+          required: ['plan'],
+          missing: !hasContract ? ['Contract not generated (RECOMMENDED)'] : [],
+          nextTool: hasContract ? 'aether_orchestra_approve' : 'aether_create_contract',
+          nextReason: hasContract
+            ? 'Approve the plan to begin execution'
+            : 'Generate contract for consistent types/schemas across agents (recommended but optional)',
+          canSkipContract: true,
+        },
+        running: {
+          required: ['plan', 'approval'],
+          missing: [],
+          nextTool: 'aether_orchestra_next',
+          nextReason: 'Get next ready tasks to execute',
+        },
+        paused: {
+          required: [],
+          missing: [],
+          nextTool: 'aether_orchestra_resume',
+          nextReason: 'Resume execution to continue',
+        },
+        completed: {
+          required: [],
+          missing: [],
+          nextTool: 'aether_start_orchestra',
+          nextReason: 'Session complete. Start a new session if needed.',
+        },
+      };
+
+      const currentState = workflow[status] || workflow.planning;
+
+      // Validate intended action
+      let actionValid = true;
+      let actionError = null;
+
+      if (intendedAction) {
+        switch (intendedAction) {
+          case 'execute_task':
+            if (status !== 'running') {
+              actionValid = false;
+              actionError = `Cannot execute tasks in "${status}" state. Session must be "running".`;
+            }
+            break;
+          case 'approve':
+            if (status !== 'awaiting_approval' && status !== 'planning') {
+              actionValid = false;
+              actionError = `Cannot approve in "${status}" state. Session must be "awaiting_approval".`;
+            }
+            if (!hasPlan) {
+              actionValid = false;
+              actionError = 'Cannot approve without a plan. Call aether_set_orchestra_plan first.';
+            }
+            break;
+          case 'complete':
+            if (status === 'completed') {
+              actionValid = false;
+              actionError = 'Session is already completed.';
+            }
+            break;
+        }
+      }
+
+      return {
+        valid: actionValid && currentState.missing.length === 0,
+        sessionId: session.sessionId,
+        status,
+        hasPlan,
+        hasContract,
+        totalTasks: session.totalTasks || 0,
+        completedTasks: session.completedTasks || 0,
+        warnings: currentState.missing,
+        intendedAction: intendedAction || 'any',
+        actionValid,
+        actionError,
+        nextStep: {
+          tool: currentState.nextTool,
+          reason: currentState.nextReason,
+          canSkip: currentState.canSkipContract || false,
+        },
+        workflow: `
+📋 ORCHESTRA WORKFLOW:
+1. aether_start_orchestra        → Creates session (status: planning)
+2. aether_set_orchestra_plan     → Defines phases/tasks (status: awaiting_approval)
+3. aether_create_contract        → Generates type contracts [RECOMMENDED]
+4. aether_orchestra_approve      → Begins execution (status: running)
+5. aether_orchestra_next         → Get ready tasks
+6. aether_trigger_generation     → Execute task
+7. aether_report_to_orchestrator → Report completion
+8. Repeat 5-7 until done
+9. aether_complete_orchestra     → Finalize session
+
+Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
+        `.trim(),
+      };
+    } catch (e) {
+      return { valid: false, error: e.message };
+    }
+  }
+
+  getWorkflowStep(status, hasPlan, hasContract) {
+    if (status === 'planning' && !hasPlan) return '1-2 (need plan)';
+    if (status === 'planning' && hasPlan) return '2-3 (plan set, need contract)';
+    if (status === 'awaiting_approval' && !hasContract) return '3 (awaiting contract)';
+    if (status === 'awaiting_approval' && hasContract) return '4 (ready to approve)';
+    if (status === 'running') return '5-8 (executing tasks)';
+    if (status === 'paused') return '5-8 (paused)';
+    if (status === 'completed') return '9 (done)';
+    return '?';
+  }
+
+  /**
+   * Quality checkpoint between phases
+   */
+  async orchestraCheckpoint(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, phaseNumber, validateContract, autoAdvance } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/checkpoint`,
+        'POST',
+        {
+          sessionId,
+          phaseNumber,
+          validateContract: validateContract !== false,
+          autoAdvance: autoAdvance || false,
+        }
+      );
+
+      return data;
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  /**
+   * Smart guidance on what to do next
+   */
+  async orchestraGuide(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId } = args;
+
+    try {
+      // Get session status first
+      const status = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'status',
+          sessionId: sessionId || undefined,
+        }
+      );
+
+      if (!status || status.error) {
+        return {
+          nextTool: 'aether_start_orchestra',
+          parameters: {},
+          explanation: 'No active orchestra session found. Start a new session to begin autonomous development.',
+          example: `aether_start_orchestra({ maxIterations: 100, timeoutMinutes: 480 })`,
+        };
+      }
+
+      const session = status;
+      const sessionStatus = session.status;
+      const hasContract = !!session.contract || session.contractVersion > 0;
+      const hasPlan = session.totalTasks > 0;
+
+      // Determine next action based on state
+      switch (sessionStatus) {
+        case 'planning':
+          if (!hasPlan) {
+            return {
+              nextTool: 'aether_set_orchestra_plan',
+              parameters: {
+                sessionId: session.sessionId,
+                planContent: '<DEVELOPMENT_PLAN.md content>',
+                phases: '<Array of phases with tasks>',
+              },
+              explanation: 'Session created but no plan set. Define the development plan with phases and tasks.',
+              example: `aether_set_orchestra_plan({
+  sessionId: "${session.sessionId}",
+  planContent: "# Development Plan\\n...",
+  phases: [{
+    phaseNumber: 1,
+    title: "Phase 1: Foundation",
+    tasks: [{
+      title: "Create data models",
+      agentId: "architect",
+      contextPrompt: "Design the database schema...",
+      expectedOutput: "Database schema and Drizzle migrations"
+    }]
+  }]
+})`,
+            };
+          }
+          // Has plan but still planning - should set contract
+          return {
+            nextTool: 'aether_create_contract',
+            parameters: {
+              sessionId: session.sessionId,
+              requirements: '<Full project requirements>',
+            },
+            explanation: 'Plan is set. Now generate the Source of Truth contract to ensure consistency across all agents.',
+            example: `aether_create_contract({
+  sessionId: "${session.sessionId}",
+  requirements: "Build a task management app with user auth, projects, and real-time updates..."
+})`,
+            note: 'This step is RECOMMENDED but optional. You can skip to aether_orchestra_approve if needed.',
+          };
+
+        case 'awaiting_approval':
+          if (!hasContract) {
+            return {
+              nextTool: 'aether_create_contract',
+              parameters: {
+                sessionId: session.sessionId,
+                requirements: '<Full project requirements>',
+              },
+              explanation: 'Plan awaiting approval. RECOMMENDED: Generate contract first for type consistency.',
+              alternative: {
+                tool: 'aether_orchestra_approve',
+                note: 'Skip contract and approve directly (not recommended for complex projects)',
+              },
+            };
+          }
+          return {
+            nextTool: 'aether_orchestra_approve',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Plan and contract ready. Approve to begin autonomous execution.',
+            example: `aether_orchestra_approve({ sessionId: "${session.sessionId}" })`,
+            warning: 'After approval, tasks will execute. Review the plan carefully first.',
+          };
+
+        case 'running':
+          // Check if there are ready tasks
+          if (session.readyTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_next',
+              parameters: { sessionId: session.sessionId },
+              explanation: `${session.readyTasks} task(s) ready to execute. Get them and trigger generation.`,
+              example: `aether_orchestra_next({ sessionId: "${session.sessionId}", maxTasks: 3 })`,
+              followUp: 'After getting tasks, use aether_trigger_generation with the orchestraContext from each task.',
+            };
+          }
+          // Check for running tasks
+          if (session.runningTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_status',
+              parameters: { sessionId: session.sessionId, includeReports: true },
+              explanation: `${session.runningTasks} task(s) currently running. Check status and handle any reports.`,
+              example: `aether_orchestra_status({ sessionId: "${session.sessionId}", includeReports: true })`,
+            };
+          }
+          // Check for blocked tasks
+          if (session.blockedTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_status',
+              parameters: { sessionId: session.sessionId, includeReports: true },
+              explanation: `${session.blockedTasks} task(s) blocked. Review blockers and resolve or edit the plan.`,
+              alternative: {
+                tool: 'aether_edit_orchestra',
+                note: 'Use to modify blocked tasks or add workaround tasks',
+              },
+            };
+          }
+          // All tasks might be complete
+          return {
+            nextTool: 'aether_orchestra_status',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Check if all tasks are complete. May be ready to finalize.',
+            possibleActions: [
+              { tool: 'aether_complete_orchestra', when: 'All tasks done' },
+              { tool: 'aether_edit_orchestra', when: 'Need to add more tasks' },
+              { tool: 'aether_orchestra_checkpoint', when: 'Validate phase completion' },
+            ],
+          };
+
+        case 'paused':
+          return {
+            nextTool: 'aether_orchestra_resume',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Session is paused. Resume to continue execution.',
+            alternative: {
+              tool: 'aether_orchestra_status',
+              note: 'Review status before resuming',
+            },
+          };
+
+        case 'completed':
+          return {
+            nextTool: 'aether_start_orchestra',
+            parameters: {},
+            explanation: 'Session completed. Start a new session for more development work.',
+            summary: {
+              completedTasks: session.completedTasks,
+              completedAt: session.completedAt,
+            },
+          };
+
+        default:
+          return {
+            nextTool: 'aether_orchestra_status',
+            parameters: { sessionId: session.sessionId },
+            explanation: `Unknown session status: ${sessionStatus}. Check status for details.`,
+          };
+      }
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
   async run() {
     const rl = readline.createInterface({
       input: process.stdin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithr-ai/mcp-server",
-  "version": "1.1.7",
+  "version": "1.2.1",
   "description": "MCP server to connect Claude Code to Aether canvas - AI-powered team workspace for software development",
   "main": "index.js",
   "bin": {

package/skills/orchestra/SKILL.md

@@ -646,6 +646,7 @@ aether_complete_orchestra(
 |------|---------|
 | `aether_start_orchestra(maxIterations?, maxAgents?, timeoutMinutes?, completionCriteria?)` | Start session |
 | `aether_set_orchestra_plan(sessionId, planContent, phases, completionCriteria?)` | Set development plan |
+| `aether_create_contract(sessionId, requirements, existingCodeSummary?)` | Generate Source of Truth contract |
 | `aether_orchestra_approve(sessionId)` | Approve and start execution |
 | `aether_orchestra_status(sessionId?, includeReports?, includeLogs?)` | Get full status |
 | `aether_orchestra_next(sessionId, maxTasks?)` | Get ready tasks |
@@ -654,6 +655,14 @@ aether_complete_orchestra(
 | `aether_orchestra_pause(sessionId)` | Pause execution |
 | `aether_orchestra_resume(sessionId)` | Resume execution |
 | `aether_complete_orchestra(sessionId, completionReason, summary?)` | Complete session |
+| `aether_edit_orchestra(sessionId, action, ...)` | Edit plan without restarting |
+
+### Workflow Enforcement Tools (v7)
+| Tool | Purpose |
+|------|---------|
+| `aether_orchestra_guide(sessionId?)` | Get intelligent guidance on next action |
+| `aether_orchestra_validate(sessionId?, intendedAction?)` | Pre-flight check before major actions |
+| `aether_orchestra_checkpoint(sessionId, phaseNumber?, validateContract?, autoAdvance?)` | Quality gate between phases |
 
 ---
 
@@ -2018,6 +2027,280 @@ The session automatically pauses when:
 
 ---
 
+## Workflow Enforcement (Orchestra v7)
+
+Orchestra v7 introduces workflow enforcement tools to prevent skipped steps and ensure proper execution order.
+
+### The Problem
+
+Without enforcement, Claude Code might:
+- Skip contract generation (causing type inconsistencies)
+- Try to execute tasks before plan approval
+- Miss phase checkpoints
+- Not know what step comes next
+
+### Workflow Enforcement Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `aether_orchestra_guide` | Get intelligent guidance on next action | When unsure what to do next |
+| `aether_orchestra_validate` | Pre-flight check before actions | Before approving, executing, or completing |
+| `aether_orchestra_checkpoint` | Quality gate between phases | After completing a phase |
+
+### The Correct Workflow
+
+```
+📋 ORCHESTRA WORKFLOW (MANDATORY ORDER):
+
+1. aether_start_orchestra        → Creates session (status: planning)
+2. aether_set_orchestra_plan     → Defines phases/tasks (status: awaiting_approval)
+3. aether_create_contract        → Generates type contracts [RECOMMENDED]
+4. aether_orchestra_approve      → Begins execution (status: running)
+5. aether_orchestra_next         → Get ready tasks
+6. aether_trigger_generation     → Execute task with orchestraContext
+7. aether_report_to_orchestrator → Report completion/blockers
+8. Repeat 5-7 until phase complete
+9. aether_orchestra_checkpoint   → Validate phase before advancing
+10. Repeat 5-9 until all phases done
+11. aether_complete_orchestra    → Finalize session
+```
+
+### Using aether_orchestra_guide
+
+**RECOMMENDED**: Call this when starting or when unsure what to do:
+
+```javascript
+// Get intelligent guidance
+aether_orchestra_guide({})
+
+// Returns (example when no session exists):
+{
+  nextTool: "aether_start_orchestra",
+  parameters: {},
+  explanation: "No active orchestra session found. Start a new session to begin.",
+  example: "aether_start_orchestra({ maxIterations: 100, timeoutMinutes: 480 })"
+}
+
+// Returns (example when plan set but no contract):
+{
+  nextTool: "aether_create_contract",
+  parameters: { sessionId: "abc-123", requirements: "<Full project requirements>" },
+  explanation: "Plan is set. Now generate the Source of Truth contract.",
+  note: "This step is RECOMMENDED but optional. You can skip to aether_orchestra_approve."
+}
+
+// Returns (example when tasks ready):
+{
+  nextTool: "aether_orchestra_next",
+  parameters: { sessionId: "abc-123" },
+  explanation: "3 task(s) ready to execute. Get them and trigger generation.",
+  followUp: "After getting tasks, use aether_trigger_generation with orchestraContext."
+}
+```
+
+### Using aether_orchestra_validate
+
+**Pre-flight check** before taking any major action:
+
+```javascript
+// Validate before approving
+aether_orchestra_validate({
+  sessionId: "abc-123",
+  intendedAction: "approve"
+})
+
+// Returns (if prerequisites missing):
+{
+  valid: false,
+  status: "planning",
+  hasPlan: true,
+  hasContract: false,
+  warnings: ["Contract not generated (RECOMMENDED)"],
+  actionValid: true,
+  nextStep: {
+    tool: "aether_create_contract",
+    reason: "Generate contract for consistent types/schemas across agents",
+    canSkip: true
+  },
+  workflow: "📋 ORCHESTRA WORKFLOW: ... Current position: Step 3 (awaiting contract)"
+}
+
+// Returns (if ready to proceed):
+{
+  valid: true,
+  status: "awaiting_approval",
+  hasPlan: true,
+  hasContract: true,
+  warnings: [],
+  actionValid: true,
+  nextStep: {
+    tool: "aether_orchestra_approve",
+    reason: "Approve the plan to begin execution"
+  }
+}
+```
+
+**Intended Actions:**
+- `execute_task` - Checks if session is running
+- `approve` - Checks if plan exists
+- `complete` - Checks if session isn't already complete
+- `any` - General validation
+
+### Using aether_orchestra_checkpoint
+
+**Quality gate** between phases:
+
+```javascript
+// Validate phase completion
+aether_orchestra_checkpoint({
+  sessionId: "abc-123",
+  phaseNumber: 1,           // Optional, uses current phase if not provided
+  validateContract: true,    // Check contract compliance
+  autoAdvance: true          // Automatically advance to next phase if passed
+})
+
+// Returns (if phase incomplete):
+{
+  success: false,
+  checkpointPassed: false,
+  phase: { number: 1, title: "Foundation", status: "in_progress" },
+  tasks: { total: 5, completed: 3, running: 1, pending: 1 },
+  blockers: [
+    "1 task(s) still running",
+    "1 task(s) still pending"
+  ],
+  message: "❌ Phase 1 checkpoint FAILED - 2 blocker(s)"
+}
+
+// Returns (if phase complete and auto-advancing):
+{
+  success: true,
+  checkpointPassed: true,
+  phase: { number: 1, title: "Foundation", status: "completed" },
+  tasks: { total: 5, completed: 5, running: 0, pending: 0 },
+  artifacts: { expected: 5, found: 5, missing: [] },
+  contract: { checked: true, hasContract: true, warnings: [] },
+  blockers: [],
+  autoAdvanced: true,
+  advancedToPhase: 2,
+  message: "✅ Phase 1 checkpoint PASSED - Advanced to Phase 2"
+}
+```
+
+### Best Practices for Workflow Enforcement
+
+#### 1. Start with Guide
+
+When beginning or resuming a session:
+
+```javascript
+// First call - get guidance
+const guidance = await aether_orchestra_guide({});
+console.log(`Next: ${guidance.nextTool}`);
+console.log(`Why: ${guidance.explanation}`);
+
+// Then follow the recommendation
+await callTool(guidance.nextTool, guidance.parameters);
+```
+
+#### 2. Validate Before Major Actions
+
+Before approving or completing:
+
+```javascript
+// Check if ready to approve
+const validation = await aether_orchestra_validate({
+  sessionId,
+  intendedAction: "approve"
+});
+
+if (!validation.valid) {
+  console.log(`Not ready: ${validation.warnings.join(', ')}`);
+  console.log(`Next step: ${validation.nextStep.tool}`);
+  return;
+}
+
+// Safe to proceed
+await aether_orchestra_approve({ sessionId });
+```
+
+#### 3. Checkpoint Between Phases
+
+After completing all tasks in a phase:
+
+```javascript
+// Validate phase before advancing
+const checkpoint = await aether_orchestra_checkpoint({
+  sessionId,
+  autoAdvance: true
+});
+
+if (!checkpoint.checkpointPassed) {
+  console.log(`Phase blocked: ${checkpoint.blockers.join('\n')}`);
+  // Handle blockers before continuing
+  return;
+}
+
+// Phase validated, proceeding to next
+console.log(`Advanced to Phase ${checkpoint.advancedToPhase}`);
+```
+
+#### 4. Never Skip the Contract Step
+
+The contract ensures type consistency:
+
+```javascript
+// Always check for contract before executing tasks
+const validation = await aether_orchestra_validate({ sessionId });
+
+if (!validation.hasContract) {
+  // Generate contract first
+  await aether_create_contract({
+    sessionId,
+    requirements: fullProjectRequirements
+  });
+}
+```
+
+### Workflow Enforcement Decision Tree
+
+```
+START
+  │
+  ▼
+aether_orchestra_guide({})
+  │
+  ├─ No session? ──────────────▶ aether_start_orchestra
+  │
+  ├─ No plan? ─────────────────▶ aether_set_orchestra_plan
+  │
+  ├─ No contract? ─────────────▶ aether_create_contract (recommended)
+  │                                      or
+  │                              aether_orchestra_approve (skip)
+  │
+  ├─ Awaiting approval? ───────▶ aether_orchestra_validate({ intendedAction: "approve" })
+  │                                      │
+  │                                      ├─ valid=true ──▶ aether_orchestra_approve
+  │                                      └─ valid=false ─▶ Fix warnings first
+  │
+  ├─ Running + tasks ready? ───▶ aether_orchestra_next
+  │                                      │
+  │                                      ▼
+  │                              aether_trigger_generation (with orchestraContext)
+  │                                      │
+  │                                      ▼
+  │                              aether_report_to_orchestrator
+  │
+  ├─ Phase complete? ──────────▶ aether_orchestra_checkpoint({ autoAdvance: true })
+  │                                      │
+  │                                      ├─ passed ──▶ Continue to next phase
+  │                                      └─ failed ──▶ Fix blockers
+  │
+  └─ All phases done? ─────────▶ aether_complete_orchestra
+```
+
+---
+
 ## Audit Trail
 
 Every action in Orchestra is logged for full auditability.
@@ -2320,6 +2603,52 @@ aether_complete_orchestra({
   completionReason: 'all_criteria_met' | 'all_phases_complete' | 'manual_stop' | 'timeout' | 'max_iterations',
   summary?: string
 })
+
+// Edit Orchestra (modify plan without restarting)
+aether_edit_orchestra({
+  sessionId: string,
+  action: 'add_task' | 'remove_task' | 'update_task' | 'split_task' | 'add_phase' | 'update_phase',
+  phaseId?: string,           // For add_task
+  taskId?: string,            // For remove_task, update_task, split_task
+  task?: object,              // Task definition for add_task/update_task
+  splitInto?: object[],       // Sub-tasks for split_task
+  phase?: object,             // Phase definition for add_phase
+  phaseUpdates?: object       // Updates for update_phase
+})
+
+// Create Contract (Source of Truth)
+aether_create_contract({
+  sessionId: string,
+  requirements: string,       // Full project requirements
+  existingCodeSummary?: string // For brownfield projects
+})
+// Returns: { success: boolean, contract: object, contractVersion: number }
+```
+
+### Workflow Enforcement (v7)
+
+```typescript
+// Get Intelligent Guidance
+aether_orchestra_guide({
+  sessionId?: string          // Uses latest if not provided
+})
+// Returns: { nextTool: string, parameters: object, explanation: string, example?: string }
+
+// Pre-flight Validation
+aether_orchestra_validate({
+  sessionId?: string,
+  intendedAction?: 'execute_task' | 'approve' | 'complete' | 'any'
+})
+// Returns: { valid: boolean, status: string, hasPlan: boolean, hasContract: boolean, warnings: string[], nextStep: object }
+
+// Phase Checkpoint
+aether_orchestra_checkpoint({
+  sessionId: string,
+  phaseNumber?: number,       // Uses current phase if not provided
+  validateContract?: boolean, // Default: true
+  autoAdvance?: boolean       // Default: false - advance to next phase if passed
+})
+// Returns: { checkpointPassed: boolean, blockers: string[], autoAdvanced: boolean, advancedToPhase?: number }
 ```
 
 ### Generation
@@ -2428,6 +2757,7 @@ aether_push_local({
 
 | Version | Date | Changes |
 |---------|------|---------|
+| v7.0 | 2025-01 | Workflow enforcement: validate, checkpoint, guide tools |
 | v6.0 | 2025-01 | File collision prevention, file lock manager |
 | v5.0 | 2025-01 | Contract-first development, validation protocol |
 | v4.0 | 2024-12 | Orchestrator Brain, dynamic decisions |
@@ -2441,17 +2771,22 @@ aether_push_local({
 
 ### Starting an Orchestra Session
 
+- [ ] `aether_orchestra_guide({})` - Get guidance on what to do
 - [ ] `/orchestra` - Create session and plan
 - [ ] Review generated DEVELOPMENT_PLAN.md
 - [ ] Verify local project path for validation
+- [ ] `aether_create_contract()` - Generate Source of Truth [RECOMMENDED]
+- [ ] `aether_orchestra_validate({ intendedAction: "approve" })` - Pre-flight check
 - [ ] `/orchestra approve` - Start execution
 
 ### During Execution
 
+- [ ] Use `aether_orchestra_guide` when unsure what to do next
 - [ ] Monitor `aether_orchestra_status` regularly
 - [ ] Check `safeguards` for approaching limits
 - [ ] Validate after each code-generating task
 - [ ] Full validation after each phase (typecheck + lint + test)
+- [ ] `aether_orchestra_checkpoint({ autoAdvance: true })` - Gate between phases
 - [ ] Handle blockers promptly
 
 ### On Completion
@@ -2465,12 +2800,30 @@ aether_push_local({
 ### If Issues Occur
 
 - [ ] Check `aether_orchestra_status` with logs
+- [ ] Use `aether_orchestra_guide` to get next step
 - [ ] Review `tasksBlockedByFiles` for v6 conflicts
 - [ ] Check `lastValidationErrors`
+- [ ] Use `aether_edit_orchestra` to modify plan mid-flight
 - [ ] Use `aether_orchestra_pause` if needed
 - [ ] Create fix tasks or manually resolve
 - [ ] `aether_orchestra_resume` to continue
 
+### Workflow Enforcement Quick Commands
+
+```javascript
+// When unsure what to do next:
+aether_orchestra_guide({})
+
+// Before approving a plan:
+aether_orchestra_validate({ intendedAction: "approve" })
+
+// After completing a phase:
+aether_orchestra_checkpoint({ sessionId, autoAdvance: true })
+
+// To modify plan without restarting:
+aether_edit_orchestra({ sessionId, action: "add_task", ... })
+```
+
 ---
 
-*Orchestra v6 - Autonomous AI Development Orchestration with Contract-First Development, Dynamic Agent Switching, and File Collision Prevention. The trust of millions of codebases depends on this system working reliably.*
+*Orchestra v7 - Autonomous AI Development Orchestration with Workflow Enforcement, Contract-First Development, Dynamic Agent Switching, and File Collision Prevention. The trust of millions of codebases depends on this system working reliably.*