@orchestrator-claude/cli 1.4.0

package/dist/templates/projects/minimal/template.config.json

@@ -0,0 +1,185 @@
+{
+  "name": "minimal",
+  "description": "Minimal project template with basic Orchestrator setup",
+  "version": "1.0.0",
+  "directories": [
+    ".orchestrator",
+    ".orchestrator/artifacts",
+    ".orchestrator/artifacts/research",
+    ".orchestrator/artifacts/specify",
+    ".orchestrator/artifacts/plan",
+    ".orchestrator/artifacts/tasks",
+    ".orchestrator/artifacts/implement",
+    ".orchestrator/workflows",
+    ".orchestrator/memory",
+    ".orchestrator/memory/knowledge-base",
+    ".orchestrator/memory/knowledge-base/core",
+    ".orchestrator/memory/knowledge-base/contextual",
+    ".orchestrator/memory/knowledge-base/research",
+    ".orchestrator/checkpoints",
+    ".orchestrator/.state",
+    ".claude",
+    ".claude/agents",
+    ".claude/skills",
+    ".claude/skills/artifact-validator",
+    ".claude/skills/kb-lookup",
+    ".claude/skills/phase-gate-evaluator",
+    ".claude/skills/workflow-status",
+    ".claude/skills/docs-guardian",
+    ".claude/hooks",
+    "src",
+    "tests"
+  ],
+  "files": [
+    {
+      "source": "projects/minimal/files/gitignore.hbs",
+      "destination": ".gitignore",
+      "template": true
+    },
+    {
+      "source": "projects/minimal/files/env.example.hbs",
+      "destination": ".env.example",
+      "template": true
+    },
+    {
+      "source": "projects/minimal/files/tsconfig.json.hbs",
+      "destination": "tsconfig.json",
+      "template": true
+    },
+    {
+      "source": "projects/minimal/files/index.ts.hbs",
+      "destination": "src/index.ts",
+      "template": true
+    },
+    {
+      "source": "base/CLAUDE.md.hbs",
+      "destination": "CLAUDE.md",
+      "template": true
+    },
+    {
+      "source": "base/mcp.json.hbs",
+      "destination": ".mcp.json",
+      "template": true
+    },
+    {
+      "source": "base/package.json.hbs",
+      "destination": "package.json",
+      "template": true
+    },
+    {
+      "source": "base/orchestrator-index.json.hbs",
+      "destination": ".orchestrator/orchestrator-index.json",
+      "template": true
+    },
+    {
+      "source": "base/claude/settings.json",
+      "destination": ".claude/settings.json",
+      "template": false
+    },
+    {
+      "source": "base/claude/orchestrator-config.json",
+      "destination": ".claude/orchestrator-config.json",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/orchestrator.md",
+      "destination": ".claude/agents/orchestrator.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/specifier.md",
+      "destination": ".claude/agents/specifier.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/planner.md",
+      "destination": ".claude/agents/planner.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/task-generator.md",
+      "destination": ".claude/agents/task-generator.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/implementer.md",
+      "destination": ".claude/agents/implementer.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/reviewer.md",
+      "destination": ".claude/agents/reviewer.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/agents/researcher.md",
+      "destination": ".claude/agents/researcher.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/skills/artifact-validator/SKILL.md",
+      "destination": ".claude/skills/artifact-validator/SKILL.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/skills/kb-lookup/SKILL.md",
+      "destination": ".claude/skills/kb-lookup/SKILL.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/skills/phase-gate-evaluator/SKILL.md",
+      "destination": ".claude/skills/phase-gate-evaluator/SKILL.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/skills/workflow-status/SKILL.md",
+      "destination": ".claude/skills/workflow-status/SKILL.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/skills/docs-guardian/SKILL.md",
+      "destination": ".claude/skills/docs-guardian/SKILL.md",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/pre-agent-invoke.sh",
+      "destination": ".claude/hooks/pre-agent-invoke.sh",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/pre-phase-advance.sh",
+      "destination": ".claude/hooks/pre-phase-advance.sh",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/post-artifact-generate.sh",
+      "destination": ".claude/hooks/post-artifact-generate.sh",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/post-implement-validate.sh",
+      "destination": ".claude/hooks/post-implement-validate.sh",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/track-agent-invocation.sh",
+      "destination": ".claude/hooks/track-agent-invocation.sh",
+      "template": false
+    },
+    {
+      "source": "base/claude/hooks/post-phase-checkpoint.sh",
+      "destination": ".claude/hooks/post-phase-checkpoint.sh",
+      "template": false
+    },
+    {
+      "source": "base/orchestrator/.state/.gitkeep",
+      "destination": ".orchestrator/.state/.gitkeep",
+      "template": false
+    }
+  ],
+  "dependencies": {},
+  "devDependencies": {},
+  "scripts": {},
+  "constitutionExtensions": [],
+  "knowledgeBaseSeeds": ["docs-constitution"]
+}

package/dist/templates/projects/minimal/template.config.ts

@@ -0,0 +1,88 @@
+/**
+ * Minimal Project Template Configuration
+ */
+import { ProjectTemplate } from '../../../../domain/entities/ProjectTemplate.js';
+
+const config = ProjectTemplate.create({
+  name: 'minimal',
+  description: 'Minimal project template with basic Orchestrator setup',
+  version: '1.0.0',
+
+  directories: [
+    '.orchestrator',
+    '.orchestrator/artifacts',
+    '.orchestrator/artifacts/research',
+    '.orchestrator/artifacts/specify',
+    '.orchestrator/artifacts/plan',
+    '.orchestrator/artifacts/tasks',
+    '.orchestrator/artifacts/implement',
+    '.orchestrator/memory',
+    '.orchestrator/memory/knowledge-base',
+    '.orchestrator/memory/knowledge-base/core',
+    '.orchestrator/memory/knowledge-base/contextual',
+    '.orchestrator/memory/knowledge-base/research',
+    '.orchestrator/checkpoints',
+    '.orchestrator/.state',
+    'src',
+    'tests',
+  ],
+
+  files: [
+    {
+      source: 'projects/minimal/files/gitignore.hbs',
+      destination: '.gitignore',
+      template: true,
+    },
+    {
+      source: 'projects/minimal/files/env.example.hbs',
+      destination: '.env.example',
+      template: true,
+    },
+    {
+      source: 'projects/minimal/files/claude-settings.json.hbs',
+      destination: '.claude/claude-settings.json',
+      template: true,
+    },
+    {
+      source: 'base/CLAUDE.md.hbs',
+      destination: 'CLAUDE.md',
+      template: true,
+    },
+    {
+      source: 'base/mcp.json.hbs',
+      destination: '.mcp.json',
+      template: true,
+    },
+    {
+      source: 'base/package.json.hbs',
+      destination: 'package.json',
+      template: true,
+    },
+    {
+      source: 'base/orchestrator-index.json.hbs',
+      destination: '.orchestrator/orchestrator-index.json',
+      template: true,
+    },
+    {
+      source: 'base/orchestrator/.state/.gitkeep',
+      destination: '.orchestrator/.state/.gitkeep',
+      template: false,
+    },
+  ],
+
+  dependencies: {},
+
+  devDependencies: {},
+
+  scripts: {},
+
+  constitutionExtensions: [],
+
+  knowledgeBaseSeeds: [],
+});
+
+if (config.isErr()) {
+  throw new Error(`Failed to create minimal template config: ${config.error}`);
+}
+
+export default config.value;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@orchestrator-claude/cli",
+  "version": "1.4.0",
+  "description": "Orchestrator CLI - Thin Client",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "orchestrator": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc && npm run copy-templates && npm run postbuild",
+    "copy-templates": "cp -r templates dist/",
+    "postbuild": "chmod +x dist/index.js",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "commander": "^13.0.0",
+    "chalk": "^5.4.0",
+    "handlebars": "^4.7.8",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@vitest/coverage-v8": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/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}}*