@orchestrator-claude/cli 1.4.0

package/dist/templates/TemplateEngine.js

@@ -0,0 +1,149 @@
+/**
+ * Template Engine
+ *
+ * Renders templates using Handlebars and manages bundled templates.
+ * Used by offline commands (init, templates, migrate).
+ *
+ * @module templates
+ */
+import Handlebars from 'handlebars';
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Template Engine
+ *
+ * Manages bundled templates and renders them with Handlebars.
+ */
+export class TemplateEngine {
+    templatesPath;
+    templates;
+    /**
+     * Create template engine
+     *
+     * @param templatesPath - Path to templates directory (default: bundled templates)
+     */
+    constructor(templatesPath) {
+        this.templatesPath = templatesPath ?? this.resolveTemplatesPath();
+        this.templates = new Map();
+        this.loadTemplates();
+    }
+    /**
+     * List available templates
+     *
+     * @returns Array of template metadata
+     */
+    listTemplates() {
+        return Array.from(this.templates.values());
+    }
+    /**
+     * Get template metadata
+     *
+     * @param name - Template name
+     * @returns Template metadata or undefined
+     */
+    getTemplate(name) {
+        return this.templates.get(name);
+    }
+    /**
+     * Render template file
+     *
+     * @param templateName - Template name
+     * @param fileName - File name within template
+     * @param context - Rendering context
+     * @returns Rendered content
+     */
+    renderFile(templateName, fileName, context) {
+        const template = this.templates.get(templateName);
+        if (!template) {
+            throw new Error(`Template not found: ${templateName}`);
+        }
+        if (!template.files.includes(fileName)) {
+            throw new Error(`File not found in template ${templateName}: ${fileName}`);
+        }
+        const filePath = join(this.templatesPath, templateName, fileName);
+        const content = readFileSync(filePath, 'utf-8');
+        const compiledTemplate = Handlebars.compile(content);
+        return compiledTemplate(context);
+    }
+    /**
+     * Check if template exists
+     *
+     * @param name - Template name
+     * @returns True if template exists
+     */
+    hasTemplate(name) {
+        return this.templates.has(name);
+    }
+    /**
+     * Resolve templates path
+     *
+     * Finds templates directory relative to this module.
+     * In production (bundled), templates are in dist/templates.
+     * In development, templates are in packages/cli/templates.
+     */
+    resolveTemplatesPath() {
+        // Get __dirname equivalent in ES modules
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        // Try production path (dist/templates)
+        const prodPath = resolve(__dirname, '../../templates');
+        if (existsSync(prodPath)) {
+            return prodPath;
+        }
+        // Try development path
+        const devPath = resolve(__dirname, '../../../templates');
+        if (existsSync(devPath)) {
+            return devPath;
+        }
+        throw new Error('Templates directory not found');
+    }
+    /**
+     * Load all templates from templates directory
+     */
+    loadTemplates() {
+        if (!existsSync(this.templatesPath)) {
+            return; // No templates available
+        }
+        const entries = readdirSync(this.templatesPath);
+        for (const entry of entries) {
+            const entryPath = join(this.templatesPath, entry);
+            const stat = statSync(entryPath);
+            if (stat.isDirectory()) {
+                const metadata = this.loadTemplateMetadata(entry);
+                if (metadata) {
+                    this.templates.set(entry, metadata);
+                }
+            }
+        }
+    }
+    /**
+     * Load template metadata
+     */
+    loadTemplateMetadata(templateName) {
+        const templatePath = join(this.templatesPath, templateName);
+        const metadataPath = join(templatePath, 'template.json');
+        if (!existsSync(metadataPath)) {
+            return null;
+        }
+        try {
+            const content = readFileSync(metadataPath, 'utf-8');
+            const metadata = JSON.parse(content);
+            // Validate required fields
+            if (!metadata.name || !metadata.description || !metadata.version) {
+                return null;
+            }
+            return metadata;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Create default template engine
+ */
+export function createTemplateEngine() {
+    return new TemplateEngine();
+}
+//# sourceMappingURL=TemplateEngine.js.map

package/dist/templates/TemplateEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateEngine.js","sourceRoot":"","sources":["../../src/templates/TemplateEngine.ts"],"names":[],"mappings":"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"}

package/dist/templates/base/CLAUDE.md.hbs

@@ -0,0 +1,362 @@
+# {{projectName}}
+
+## Overview
+
+This project uses the **Orchestrator System** for autonomous workflow management. When handling feature requests, bug fixes, or refactoring tasks, you MUST use the orchestrator workflow instead of implementing directly.
+
+## Critical Rule
+
+**NEVER implement features directly.** Always use the orchestrator workflow:
+
+```
+User Request → Detect Workflow → Research (if needed) → SPECIFY → PLAN → TASKS → Implement
+```
+
+## How to Start a Workflow
+
+When a user requests a new feature, bug fix, or refactoring:
+
+### 1. Detect Workflow Type
+
+Use the MCP tool to detect the workflow type:
+
+```
+mcp__orchestrator-tools__detectWorkflow({ prompt: "user request here" })
+```
+
+Workflow types:
+- `feature_development` - New features, new functionality
+- `bug_fix` - Bug fixes, error corrections
+- `refactoring` - Code refactoring, improvements
+- `emergency_debug` - Urgent debugging
+
+### 2. Start Workflow and Get Next Step
+
+**MANDATORY:** After detecting workflow type, call `startWorkflow` to create the workflow:
+
+```
+mcp__orchestrator-tools__startWorkflow({ workflowType: "feature-development", prompt: "user request here" })
+```
+
+This returns a deterministic `nextStep` instruction:
+
+```json
+{
+  "success": true,
+  "workflowId": "wf-123",
+  "nextStep": {
+    "action": "invoke_agent",
+    "subagent_type": "orchestrator",
+    "prompt": "Start workflow feature-development (ID: wf-123) for user request: ..."
+  }
+}
+```
+
+### 3. Execute nextStep (Invoke Orchestrator Agent)
+
+**IMMEDIATELY** follow the `nextStep` instruction by invoking the orchestrator agent via Task tool:
+
+```
+Use the Task tool with subagent_type from nextStep.subagent_type
+Prompt: nextStep.prompt
+```
+
+The orchestrator agent will:
+1. Set pending actions for specialized agents
+2. Return control to CLI for Ping-Pong pattern
+3. CLI invokes agents via Task tool as directed by getNextAction()
+4. Process continues until workflow completes
+
+## Available MCP Tools
+
+### orchestrator-tools
+- `detectWorkflow` - Detect workflow type from user prompt
+- `startWorkflow` - **Create workflow and get deterministic nextStep instruction** (MANDATORY after detectWorkflow)
+- `advancePhase` - Advance to the next workflow phase
+- `evaluateGate` - Evaluate if a phase gate passes
+- `validateArtifact` - Validate artifact against schema
+- `createCheckpoint` - Create a git checkpoint
+- `getStatus` - Get current workflow status
+- `getWorkflows` - List workflows with phase configs (including `requiresApproval`)
+- `getNextAction` - Get the next pending action (Ping-Pong pattern)
+
+### knowledge-base
+- `search` - Search the knowledge base
+- `getDocument` - Get a specific document
+- `getConstitution` - Get the project constitution
+- `listByTier` - List documents by tier
+- `listByCategory` - List documents by category
+
+## Auto-Advance Behavior (requiresApproval)
+
+**CRITICAL**: Each workflow phase has a `requiresApproval` configuration.
+
+### How It Works
+
+1. **Load workflow config** at start using `getWorkflows`:
+   ```
+   mcp__orchestrator-tools__getWorkflows()
+   ```
+
+2. **Check each phase's `requiresApproval`**:
+   - `requiresApproval: false` → **AUTO-ADVANCE** after gate passes (no user interaction)
+   - `requiresApproval: true` → **PAUSE** and ask user for approval
+
+### Default Configuration (feature-development)
+
+```
+SPECIFY  → requiresApproval: false → auto-advance
+PLAN     → requiresApproval: false → auto-advance
+TASKS    → requiresApproval: false → auto-advance
+IMPLEMENT → requiresApproval: true  → PAUSE HERE
+```
+
+### Expected Behavior
+
+- **DO NOT ask user** between SPECIFY → PLAN → TASKS phases
+- **Run these phases sequentially** invoking each agent automatically
+- **ONLY pause** before IMPLEMENT phase (or phases with `requiresApproval: true`)
+- This reduces unnecessary interactions and speeds up the workflow
+
+### Example Flow
+
+```
+User: "Create a calculator function"
+
+Claude:
+1. detectWorkflow({ prompt: "Create a calculator function" }) → feature-development
+2. startWorkflow({ workflowType: "feature-development", prompt: "..." }) → { nextStep: {...} }
+3. Execute nextStep → Invoke orchestrator agent via Task tool
+4. getNextAction() → { agent: "specifier", status: "awaiting_agent" }
+5. Invoke specifier via Task tool → spec.md created
+6. getNextAction() → { agent: "planner", status: "awaiting_agent" }
+7. Invoke planner via Task tool → plan.md created
+8. getNextAction() → { agent: "task-generator", status: "awaiting_agent" }
+9. Invoke task-generator via Task tool → tasks.md created
+10. getNextAction() → { status: "awaiting_approval" }
+11. Ask user: "Artifacts ready. Approve implementation?"
+```
+
+## Workflow Phases
+
+```
+RESEARCH (optional)
+    ↓
+  SPECIFY
+    ↓
+   PLAN
+    ↓
+  TASKS
+    ↓
+  [HUMAN APPROVAL REQUIRED]
+    ↓
+IMPLEMENT
+```
+
+Each phase produces artifacts in `.orchestrator/artifacts/`:
+- `research/` - Research context documents
+- `specify/` - Specifications (spec.md)
+- `plan/` - Technical plans (plan.md)
+- `tasks/` - Task backlogs (tasks.md)
+- `implement/` - Implementation reports
+
+---
+
+## Workflow Execution Pattern (Ping-Pong Híbrido)
+
+### Critical Rule: Always Check for Pending Actions
+
+**MANDATORY:** After EVERY Task tool invocation that involves workflow orchestration, you MUST:
+
+1. **Call `mcp__orchestrator-tools__getNextAction()`**
+2. **Analyze the response and take appropriate action**
+
+### Status → Action Mapping
+
+| Status | Your Action |
+|--------|-------------|
+| `awaiting_agent` | **Immediately** invoke the specified agent via Task tool |
+| `awaiting_approval` | **Ask user** for approval, then call `approveAction()` |
+| `running` | Agent is currently executing, do nothing |
+| No pending action | Workflow is complete or paused |
+
+### Workflow Execution Loop
+
+```typescript
+// MANDATORY PATTERN for workflow execution
+
+// 1. Detect workflow type
+const detection = await detectWorkflow({ prompt: "Create authentication API" });
+
+// 2. Start workflow and get nextStep (DETERMINISTIC)
+const startResult = await startWorkflow({
+  workflowType: detection.workflowType,
+  prompt: "Create authentication API"
+});
+
+// 3. Execute nextStep - invoke orchestrator agent
+await invokeTool("Task", {
+  subagent_type: startResult.nextStep.subagent_type, // "orchestrator"
+  prompt: startResult.nextStep.prompt
+});
+
+// 4. Check for pending actions (Ping-Pong loop)
+const action = await getNextAction();
+
+// 5. Handle the action
+if (action.hasAction && action.pendingAction.status === "awaiting_agent") {
+  // Immediately invoke the specified agent
+  await invokeTool("Task", {
+    subagent_type: action.pendingAction.agent,
+    prompt: action.pendingAction.prompt
+  });
+
+  // 6. REPEAT: Check for next action after agent completes
+  const nextAction = await getNextAction();
+  // ... continue loop
+}
+
+if (action.hasAction && action.pendingAction.status === "awaiting_approval") {
+  // Inform user and wait for approval
+  console.log("⚠️ Workflow requires approval before continuing to IMPLEMENT phase.");
+  console.log("Review artifacts and type 'yes' to proceed.");
+
+  // After user approves:
+  await approveAction({ workflowId: action.workflowId });
+
+  // Then check for next action again
+  const nextAction = await getNextAction();
+  // ...
+}
+```
+
+### What NOT to Do
+
+- ❌ **NEVER** skip `startWorkflow` after `detectWorkflow` - it creates the workflow and returns deterministic `nextStep`
+- ❌ **NEVER** ignore `nextStep` from `startWorkflow` - it tells you exactly which agent to invoke
+- ❌ **NEVER** ignore `getNextAction()` after Task tool invocation
+- ❌ **NEVER** decide which agent to invoke without checking `pendingAction`
+- ❌ **NEVER** skip to IMPLEMENT phase without user approval
+- ❌ **NEVER** execute multiple phases in a single agent invocation
+- ❌ **NEVER** use Write/Edit tools to create artifacts during orchestration (let specialized agents do it)
+- ❌ **NEVER** invoke agents out of order defined by `pendingAction`
+
+### Why This Pattern?
+
+**Problem (LIM-001):** Context window bloat when orchestrator executes all phases internally in one invocation.
+
+**Solution (Ping-Pong Híbrido):** Orchestrator acts as **dispatcher**, creating `pendingActions` that guide the CLI to invoke specialized agents in separate, isolated invocations.
+
+**Benefits:**
+- Each agent invocation has isolated context (< 12k tokens)
+- Total token usage reduced by 40%+
+- No hallucination from massive context
+- Real agent metrics (not simulated)
+- Workflow resumable after crashes (pendingAction persists)
+
+---
+
+## MANDATORY: IMPLEMENT Phase Delegation
+
+> **WARNING**
+>
+> The IMPLEMENT phase REQUIRES delegation to the implementer subagent.
+> Direct implementation is FORBIDDEN and will break workflow governance.
+
+### Trigger Phrases
+
+When user approves implementation with ANY of these phrases:
+
+**English:**
+- "yes", "yes, implement", "proceed", "go ahead", "continue"
+- "start implementation", "implement it", "do it"
+
+**Portuguese:**
+- "sim", "prossiga", "continue", "pode implementar"
+- "manda ver", "vai la", "implementa"
+
+### Required Actions (IN ORDER)
+
+1. **ANNOUNCE DELEGATION:**
+   ```
+   I will now delegate to the implementer agent to execute the tasks.
+   ```
+
+2. **ADVANCE PHASE:**
+   ```
+   mcp__orchestrator-tools__advancePhase({ workflowId: "current-workflow-id" })
+   ```
+
+3. **INVOKE IMPLEMENTER (REQUIRED):**
+   ```
+   Use the Task tool with subagent_type="implementer"
+
+   Prompt:
+   Execute all tasks from .orchestrator/artifacts/tasks/tasks.md
+
+   Context:
+   - Specification: .orchestrator/artifacts/specify/spec.md
+   - Plan: .orchestrator/artifacts/plan/plan.md
+   - Tasks: .orchestrator/artifacts/tasks/tasks.md
+
+   Requirements:
+   - Follow TDD (write tests BEFORE implementation)
+   - Maintain 80% minimum coverage
+   - Update orchestrator-index.json after EACH task
+   - Create checkpoint after every 3-5 tasks
+   - Generate implementation-report.md at the end
+   ```
+
+### FORBIDDEN Actions
+
+- Using Edit/Write tools directly for code implementation
+- Skipping Task tool invocation
+- Writing production code without implementer agent
+- Forgetting to update orchestrator-index.json
+
+### Self-Verification Checklist
+
+Before proceeding, verify:
+- [ ] Did I announce delegation to the user?
+- [ ] Did I call advancePhase via MCP?
+- [ ] Did I use Task tool with subagent_type="implementer"?
+- [ ] Is the implementer prompt complete with all context?
+
+If ANY answer is NO -> STOP and correct before continuing.
+
+---
+
+## Quality Rules
+
+- **TDD**: Write tests BEFORE implementation
+- **Coverage**: Minimum 80% test coverage
+- **SOLID**: Follow SOLID principles
+- **Clean Architecture**: Dependencies point inward
+- **TypeScript Strict**: `strict: true` required
+
+## Project Structure
+
+```
+.orchestrator/
+├── artifacts/           # Generated artifacts by phase
+├── memory/
+│   └── knowledge-base/
+│       ├── core/        # CONSTITUTION.md (immutable rules)
+│       └── contextual/  # Project context
+├── checkpoints/         # Checkpoint metadata
+└── orchestrator-index.json  # Workflow state
+```
+
+## Important Notes
+
+1. **Always start with workflow detection** - Don't skip this step
+2. **Let agents do their work** - Don't bypass the workflow
+3. **Validate artifacts** - Use the artifact-validator skill
+4. **Check gates** - Use phase-gate-evaluator before advancing
+5. **Create checkpoints** - After each validated artifact
+6. **Consult CONSTITUTION** - For project rules and constraints
+
+---
+
+*This project was initialized with the Orchestrator CLI.*
+*Generated: {{currentDate}}*