@aithr-ai/mcp-server 1.2.0 → 1.2.1

package/package.json

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