@aithr-ai/mcp-server 1.2.0 → 1.2.2

package/index.js

@@ -3742,17 +3742,13 @@ class MCPServer {
     const { sessionId, intendedAction } = args;
 
     try {
-      // Get current session status
-      const data = await this.mcpApiCall(
-        `/mcp/projects/${projectId}/orchestra`,
-        'POST',
-        {
-          action: 'status',
-          sessionId: sessionId || undefined,
-        }
-      );
+      // Get current session status via GET
+      const url = sessionId
+        ? `/mcp/projects/${projectId}/orchestra?sessionId=${sessionId}`
+        : `/mcp/projects/${projectId}/orchestra`;
+      const data = await this.mcpApiCall(url, 'GET');
 
-      if (!data || data.error) {
+      if (!data || data.error || !data.session) {
         return {
           valid: false,
           error: data?.error || 'No orchestra session found',
@@ -3763,7 +3759,7 @@ class MCPServer {
         };
       }
 
-      const session = data;
+      const session = data.session;
       const status = session.status;
       const hasContract = !!session.contract || session.contractVersion > 0;
       const hasPlan = session.totalTasks > 0;
@@ -3842,7 +3838,7 @@ class MCPServer {
 
       return {
         valid: actionValid && currentState.missing.length === 0,
-        sessionId: session.sessionId,
+        sessionId: session.id,
         status,
         hasPlan,
         hasContract,
@@ -3935,17 +3931,13 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
     const { sessionId } = args;
 
     try {
-      // Get session status first
-      const status = await this.mcpApiCall(
-        `/mcp/projects/${projectId}/orchestra`,
-        'POST',
-        {
-          action: 'status',
-          sessionId: sessionId || undefined,
-        }
-      );
+      // Get session status via GET
+      const url = sessionId
+        ? `/mcp/projects/${projectId}/orchestra?sessionId=${sessionId}`
+        : `/mcp/projects/${projectId}/orchestra`;
+      const data = await this.mcpApiCall(url, 'GET');
 
-      if (!status || status.error) {
+      if (!data || data.error || !data.session) {
         return {
           nextTool: 'aether_start_orchestra',
           parameters: {},
@@ -3954,7 +3946,7 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
         };
       }
 
-      const session = status;
+      const session = data.session;
       const sessionStatus = session.status;
       const hasContract = !!session.contract || session.contractVersion > 0;
       const hasPlan = session.totalTasks > 0;
@@ -3966,13 +3958,13 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
             return {
               nextTool: 'aether_set_orchestra_plan',
               parameters: {
-                sessionId: session.sessionId,
+                sessionId: session.id,
                 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}",
+  sessionId: "${session.id}",
   planContent: "# Development Plan\\n...",
   phases: [{
     phaseNumber: 1,
@@ -3991,12 +3983,12 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
           return {
             nextTool: 'aether_create_contract',
             parameters: {
-              sessionId: session.sessionId,
+              sessionId: session.id,
               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}",
+  sessionId: "${session.id}",
   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.',
@@ -4007,7 +3999,7 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
             return {
               nextTool: 'aether_create_contract',
               parameters: {
-                sessionId: session.sessionId,
+                sessionId: session.id,
                 requirements: '<Full project requirements>',
               },
               explanation: 'Plan awaiting approval. RECOMMENDED: Generate contract first for type consistency.',
@@ -4019,9 +4011,9 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
           }
           return {
             nextTool: 'aether_orchestra_approve',
-            parameters: { sessionId: session.sessionId },
+            parameters: { sessionId: session.id },
             explanation: 'Plan and contract ready. Approve to begin autonomous execution.',
-            example: `aether_orchestra_approve({ sessionId: "${session.sessionId}" })`,
+            example: `aether_orchestra_approve({ sessionId: "${session.id}" })`,
             warning: 'After approval, tasks will execute. Review the plan carefully first.',
           };
 
@@ -4030,9 +4022,9 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
           if (session.readyTasks > 0) {
             return {
               nextTool: 'aether_orchestra_next',
-              parameters: { sessionId: session.sessionId },
+              parameters: { sessionId: session.id },
               explanation: `${session.readyTasks} task(s) ready to execute. Get them and trigger generation.`,
-              example: `aether_orchestra_next({ sessionId: "${session.sessionId}", maxTasks: 3 })`,
+              example: `aether_orchestra_next({ sessionId: "${session.id}", maxTasks: 3 })`,
               followUp: 'After getting tasks, use aether_trigger_generation with the orchestraContext from each task.',
             };
           }
@@ -4040,16 +4032,16 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
           if (session.runningTasks > 0) {
             return {
               nextTool: 'aether_orchestra_status',
-              parameters: { sessionId: session.sessionId, includeReports: true },
+              parameters: { sessionId: session.id, includeReports: true },
               explanation: `${session.runningTasks} task(s) currently running. Check status and handle any reports.`,
-              example: `aether_orchestra_status({ sessionId: "${session.sessionId}", includeReports: true })`,
+              example: `aether_orchestra_status({ sessionId: "${session.id}", includeReports: true })`,
             };
           }
           // Check for blocked tasks
           if (session.blockedTasks > 0) {
             return {
               nextTool: 'aether_orchestra_status',
-              parameters: { sessionId: session.sessionId, includeReports: true },
+              parameters: { sessionId: session.id, includeReports: true },
               explanation: `${session.blockedTasks} task(s) blocked. Review blockers and resolve or edit the plan.`,
               alternative: {
                 tool: 'aether_edit_orchestra',
@@ -4060,7 +4052,7 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
           // All tasks might be complete
           return {
             nextTool: 'aether_orchestra_status',
-            parameters: { sessionId: session.sessionId },
+            parameters: { sessionId: session.id },
             explanation: 'Check if all tasks are complete. May be ready to finalize.',
             possibleActions: [
               { tool: 'aether_complete_orchestra', when: 'All tasks done' },
@@ -4072,7 +4064,7 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
         case 'paused':
           return {
             nextTool: 'aether_orchestra_resume',
-            parameters: { sessionId: session.sessionId },
+            parameters: { sessionId: session.id },
             explanation: 'Session is paused. Resume to continue execution.',
             alternative: {
               tool: 'aether_orchestra_status',
@@ -4094,7 +4086,7 @@ Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
         default:
           return {
             nextTool: 'aether_orchestra_status',
-            parameters: { sessionId: session.sessionId },
+            parameters: { sessionId: session.id },
             explanation: `Unknown session status: ${sessionStatus}. Check status for details.`,
           };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithr-ai/mcp-server",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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.*