@orchestrator-claude/cli 3.0.2 → 3.1.0

package/README.md

@@ -1,5 +1,10 @@
 # @orchestrator-claude/cli
 
+> **DEPRECATED**: This package is deprecated since RFC-014. All orchestration
+> logic now runs through MCP tools backed by PostgreSQL/MinIO. The thin-client
+> CLI is no longer maintained. Use the orchestrator MCP server directly via
+> Claude Code hooks and skills instead.
+
 **Orchestrator CLI - True Thin Client**
 
 This is the thin client CLI for the Orchestrator system. It contains only HTTP client logic and bundled templates, with all business logic running in a Docker container.

package/dist/index.d.ts

@@ -11,5 +11,5 @@
 /**
  * CLI version
  */
-export declare const CLI_VERSION = "3.0.2";
+export declare const CLI_VERSION = "3.1.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -20,7 +20,7 @@ import { OutputFormatter } from './formatters/OutputFormatter.js';
 /**
  * CLI version
  */
-export const CLI_VERSION = '3.0.2';
+export const CLI_VERSION = '3.1.0';
 /**
  * Main CLI function
  */

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

@@ -153,12 +153,14 @@ RESEARCH (optional)
 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
+Each phase produces artifacts stored in MinIO (object storage) and tracked in PostgreSQL:
+- `research` - Research context documents
+- `specify` - Specifications (spec.md)
+- `plan` - Technical plans (plan.md)
+- `tasks` - Task backlogs (tasks.md)
+- `implement` - Implementation reports
+
+**CRITICAL**: Artifacts are accessed via MCP tools (`artifactStore`, `artifactRetrieve`), NOT via filesystem paths. The `.orchestrator/artifacts/` directory does NOT exist on the filesystem.
 
 ---
 
@@ -302,7 +304,6 @@ When user approves implementation with ANY of these phrases:
    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
    ```
@@ -312,7 +313,7 @@ When user approves implementation with ANY of these phrases:
 - Using Edit/Write tools directly for code implementation
 - Skipping Task tool invocation
 - Writing production code without implementer agent
-- Forgetting to update orchestrator-index.json
+- Editing `.orchestrator/orchestrator-index.json` directly (state is in PostgreSQL)
 
 ### Self-Verification Checklist
 
@@ -334,19 +335,24 @@ If ANY answer is NO -> STOP and correct before continuing.
 - **Clean Architecture**: Dependencies point inward
 - **TypeScript Strict**: `strict: true` required
 
-## Project Structure
+## State Management
 
 ```
-.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
+PostgreSQL (Single Source of Truth):
+├── workflows          # Workflow state, pending actions, phases
+├── artifacts          # Artifact metadata
+├── checkpoints        # Checkpoint metadata
+└── agent_invocations  # Agent invocation history
+
+MinIO (Object Storage):
+└── artifacts/         # Generated artifact content by phase
+
+.orchestrator/ (DEPRECATED - do NOT read or write directly):
+└── orchestrator-index.json  # DEPRECATED: state is in PostgreSQL
 ```
 
+**CRITICAL**: All workflow state is in PostgreSQL. All artifact content is in MinIO. Access everything through MCP tools. NEVER edit `.orchestrator/orchestrator-index.json` directly.
+
 ## Important Notes
 
 1. **Always start with workflow detection** - Don't skip this step

package/dist/templates/base/claude/agents/api-extractor.md

@@ -452,7 +452,7 @@ tags:
 4. MUST identify and document authentication requirements
 5. MUST group endpoints by tags/resources logically
 6. MUST include at least one example per endpoint (request or response)
-7. MUST update orchestrator-index.json after completion
+7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
 8. MUST create checkpoint after MAP phase complete
 
 ### MUST NOT (Forbidden)
@@ -518,29 +518,9 @@ After completing MAP phase (API portion):
 
 2. Validate OpenAPI 3.0 compliance (if swagger-cli available)
 
-3. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "map",
-       "status": "in_progress"
-     },
-     "artifacts": [
-       {
-         "id": "art-map-001",
-         "type": "api-spec",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/api-spec.yaml",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "map",
-         "format": "openapi-3.0",
-         "validated": true,
-         "endpointCount": 45,
-         "coveragePercent": 92
-       }
-     ]
-   }
-   ```
+3. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 4. MUST NOT create checkpoint yet (wait for schema-extractor to complete MAP phase)
 
@@ -652,7 +632,7 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] At least one example per endpoint
 - [ ] No sensitive data in examples
 - [ ] Artifact saved to correct path
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 
 **FORBIDDEN**: Claiming completion without generating valid OpenAPI 3.0 spec.
 

package/dist/templates/base/claude/agents/business-rule-miner.md

@@ -609,7 +609,7 @@ stateDiagram-v2
 4. MUST categorize rules by domain
 5. MUST generate business-rules.md using template
 6. MUST assign unique IDs to business rules (BR-DOMAIN-###)
-7. MUST update orchestrator-index.json after completion
+7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
 8. MUST create checkpoint after DOCUMENT phase complete
 
 ### MUST NOT (Forbidden)
@@ -665,37 +665,9 @@ After completing DOCUMENT phase:
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/business-rules.md`
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/glossary.md`
 
-2. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "document",
-       "status": "completed"
-     },
-     "artifacts": [
-       {
-         "id": "art-document-001",
-         "type": "business-rules",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/business-rules.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "document",
-         "rulesExtracted": 87,
-         "domains": 5,
-         "stateMachines": 4
-       },
-       {
-         "id": "art-document-002",
-         "type": "glossary",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/glossary.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "document",
-         "termsCount": 25
-       }
-     ]
-   }
-   ```
+2. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 3. Create checkpoint (MANDATORY after DOCUMENT phase):
    ```
@@ -720,7 +692,7 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] glossary.md generated (if applicable)
 - [ ] Unique IDs assigned (BR-DOMAIN-###)
 - [ ] Artifacts saved to correct paths
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 - [ ] Checkpoint created
 
 **FORBIDDEN**: Claiming completion without file:line locations.

package/dist/templates/base/claude/agents/code-archaeologist.md

@@ -496,7 +496,7 @@ Se ferramenta nao instalada: SKIP (nao e blocker)
 4. MUST sanitize ALL secrets in outputs (replace with `***REDACTED***`)
 5. MUST classify findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
 6. MUST generate all 3 artifacts (analysis-report, dead-code-report, tech-debt)
-7. MUST update orchestrator-index.json after completion
+7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
 8. MUST create checkpoint after analysis complete
 
 ### MUST NOT (Forbidden)
@@ -561,50 +561,9 @@ After completing ANALYZE phase:
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/dead-code-report.md`
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/tech-debt.md`
 
-2. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "analyze",
-       "status": "completed"
-     },
-     "artifacts": [
-       {
-         "id": "art-analyze-001",
-         "type": "analysis-report",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/analysis-report.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "analyze",
-         "findingsCount": {
-           "critical": 2,
-           "high": 8,
-           "medium": 15,
-           "low": 23
-         }
-       },
-       {
-         "id": "art-analyze-002",
-         "type": "dead-code-report",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/dead-code-report.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "analyze",
-         "deadCodeLOC": 12450,
-         "percentageOfCodebase": 23
-       },
-       {
-         "id": "art-analyze-003",
-         "type": "tech-debt",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/tech-debt.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "analyze",
-         "estimatedEffort": "320h"
-       }
-     ]
-   }
-   ```
+2. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 3. Create checkpoint (MANDATORY after ANALYZE):
    ```
@@ -701,7 +660,7 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] tech-debt.md generated using template
 - [ ] All findings classified by severity
 - [ ] All artifacts saved to correct paths
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 - [ ] Checkpoint created
 
 **FORBIDDEN**: Claiming completion without generating all 3 artifacts.

package/dist/templates/base/claude/agents/implementer.md

@@ -303,23 +303,9 @@ npm run build  # PASSOU
 
 **ATENCAO:** Alem de implementar codigo, voce DEVE manter a governanca do workflow.
 
-### 1. Atualizar orchestrator-index.json
-
-Apos **CADA TAREFA** completada, atualize o arquivo `.orchestrator/orchestrator-index.json`:
-
-```json
-{
-  "activeWorkflow": {
-    "currentPhase": "implement",
-    "status": "in_progress"
-  },
-  "implementation": {
-    "completedTasks": [/* IDs das tasks completas */],
-    "currentTask": "TASK-XXX",
-    "progress": "X/Y tasks"
-  }
-}
-```
+### 1. Return Structured Output for Task Progress
+
+After **EACH TASK** completed, return structured output to the CLI with task completion status. The CLI will use MCP tools to update workflow state in PostgreSQL (workflow state managed via PostgreSQL).
 
 ### 2. Criar Checkpoints
 
@@ -334,8 +320,7 @@ Parametros:
 
 ### 3. Gerar implementation-report.md
 
-Ao **FINALIZAR TODAS AS TAREFAS**, crie o artefato em:
-`.orchestrator/artifacts/implement/implementation-report.md`
+Ao **FINALIZAR TODAS AS TAREFAS**, crie o artefato e persista via MCP tool `artifactStore` (phase: implement).
 
 Formato obrigatorio:
 ```markdown
@@ -381,66 +366,28 @@ Validacao:
 - [ ] Build sem erros
 ```
 
-### 4. Registrar Artefato em orchestrator-index.json
-
-Adicione o artefato ao array `artifacts`:
-
-```json
-{
-  "artifacts": [
-    {
-      "id": "art-XXX",
-      "type": "implementation",
-      "path": ".orchestrator/artifacts/implement/implementation-report.md",
-      "status": "completed",
-      "createdAt": "{timestamp}",
-      "workflowId": "{workflowId}",
-      "phase": "implement"
-    }
-  ]
-}
-```
+### 4. Artifact Registration (automatic via MCP tools)
 
-### 5. Atualizar Gates
+**Note**: The artifact will be automatically registered in PostgreSQL by the domain layer when you use `artifactStore`. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
 
-Ao finalizar, atualize o gate da fase implement:
+### 5. Return Structured Output for Final State
 
-```json
-{
-  "gates": {
-    "implement": {
-      "passed": true,
-      "evaluatedAt": "{timestamp}"
-    }
-  }
-}
-```
-
-### 6. Atualizar Status Final
-
-Ao completar TODAS as tarefas:
-
-```json
-{
-  "activeWorkflow": {
-    "currentPhase": "completed",
-    "status": "completed",
-    "completedAt": "{timestamp}"
-  }
-}
-```
+Ao finalizar todas as tarefas, return structured output to the CLI indicating completion. The CLI will use MCP tools to update workflow state in PostgreSQL:
+- Phase gate: implement.passed = true
+- Workflow status: "completed"
+- Completion timestamp
 
 ### Checklist de Governanca (OBRIGATORIO)
 
 Antes de considerar a fase IMPLEMENT finalizada:
 
 - [ ] Todas as tarefas do tasks.md implementadas
-- [ ] orchestrator-index.json atualizado com progresso
+- [ ] Structured output returned to CLI for state update
 - [ ] Checkpoints criados a cada grupo de tarefas
-- [ ] implementation-report.md criado
-- [ ] Artefato registrado em artifacts[]
-- [ ] Gate implement.passed = true
-- [ ] Status do workflow = "completed"
+- [ ] implementation-report.md persistido via MCP tool `artifactStore`
+- [ ] Artefato automaticamente registrado em PostgreSQL pelo domain layer
+- [ ] Gate implement.passed = true (updated via CLI)
+- [ ] Status do workflow = "completed" (updated via CLI)
 - [ ] Testes passando (npm run test)
 - [ ] Coverage >= 80% (npm run test:coverage)
 - [ ] Build sem erros (npm run build)

package/dist/templates/base/claude/agents/legacy-discoverer.md

@@ -364,7 +364,7 @@ LOW:
 4. MUST generate inventory.json validated against schema
 5. MUST sanitize secrets in all outputs (replace with `***REDACTED***`)
 6. MUST catalog >= 95% of assets vs reality (if pattern set is good)
-7. MUST update orchestrator-index.json after completion
+7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
 8. MUST classify findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
 
 ### MUST NOT (Forbidden)
@@ -424,25 +424,9 @@ After completing DISCOVER phase:
 1. Save discovery-report.md to:
    `.orchestrator/artifacts/legacy-analysis/{workflowId}/discovery-report.md`
 
-2. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "discover",
-       "status": "completed"
-     },
-     "artifacts": [
-       {
-         "id": "art-discover-001",
-         "type": "discovery-report",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/discovery-report.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "discover"
-       }
-     ]
-   }
-   ```
+2. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 After completing INVENTORY phase:
 
@@ -452,27 +436,9 @@ After completing INVENTORY phase:
 2. Validate against schema:
    `.orchestrator/templates/legacy/inventory.json.schema`
 
-3. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "inventory",
-       "status": "completed"
-     },
-     "artifacts": [
-       {
-         "id": "art-inventory-001",
-         "type": "inventory",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/inventory.json",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "inventory",
-         "validated": true,
-         "schema": ".orchestrator/templates/legacy/inventory.json.schema"
-       }
-     ]
-   }
-   ```
+3. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 4. Create checkpoint (MANDATORY after INVENTORY):
    ```
@@ -554,7 +520,7 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] Red flags classified by severity
 - [ ] Secrets sanitized (if any found)
 - [ ] Artifact saved to correct path
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 
 ### INVENTORY Phase Checklist
 
@@ -564,7 +530,7 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] >= 95% asset coverage vs reality
 - [ ] JSON is valid and parseable
 - [ ] Artifact saved to correct path
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 - [ ] Checkpoint created
 
 **FORBIDDEN**: Claiming completion without evidence.

package/dist/templates/base/claude/agents/legacy-synthesizer.md

@@ -959,7 +959,7 @@ This analysis followed the **RFC-004 Legacy Analysis Workflow** with 6 phases:
 5. MUST identify quick wins (high impact, low effort)
 6. MUST document risks with probability, impact, and mitigations
 7. MUST generate all 3 final artifacts (migration-roadmap, architecture-proposal, final-report)
-8. MUST update orchestrator-index.json after completion
+8. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
 9. MUST create final checkpoint after RECOMMEND phase complete
 
 ### MUST NOT (Forbidden)
@@ -1003,48 +1003,9 @@ After completing RECOMMEND phase:
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/architecture-proposal.md`
    - `.orchestrator/artifacts/legacy-analysis/{workflowId}/final-report.md`
 
-2. Update orchestrator-index.json:
-   ```json
-   {
-     "activeWorkflow": {
-       "currentPhase": "recommend",
-       "status": "completed",
-       "completedAt": "{timestamp}"
-     },
-     "artifacts": [
-       {
-         "id": "art-recommend-001",
-         "type": "migration-roadmap",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/migration-roadmap.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "recommend",
-         "strategy": "strangler-fig",
-         "totalEffort": "1020-1530h",
-         "phases": 7
-       },
-       {
-         "id": "art-recommend-002",
-         "type": "architecture-proposal",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/architecture-proposal.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "recommend",
-         "targetArchitecture": "modular-monolith"
-       },
-       {
-         "id": "art-recommend-003",
-         "type": "final-report",
-         "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/final-report.md",
-         "status": "completed",
-         "createdAt": "{timestamp}",
-         "phase": "recommend",
-         "totalArtifacts": 12,
-         "totalIssues": 48
-       }
-     ]
-   }
-   ```
+2. Return structured output to CLI for state update:
+
+   Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
 
 3. Create final checkpoint (MANDATORY):
    ```
@@ -1054,15 +1015,7 @@ After completing RECOMMEND phase:
      - description: "Complete RECOMMEND phase - {strategy} strategy, {X} phases, {Y}h effort"
    ```
 
-4. Mark workflow as completed:
-   ```json
-   {
-     "activeWorkflow": {
-       "status": "completed",
-       "completedAt": "{timestamp}"
-     }
-   }
-   ```
+4. CLI will mark workflow as completed via MCP tools → PostgreSQL
 
 ## Verification Before Completion
 
@@ -1082,9 +1035,9 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] architecture-proposal.md generated
 - [ ] final-report.md generated using template
 - [ ] All 3 artifacts saved to correct paths
-- [ ] orchestrator-index.json updated
+- [ ] Structured output returned to CLI for state update
 - [ ] Final checkpoint created
-- [ ] Workflow marked as completed
+- [ ] Workflow marked as completed (via CLI)
 
 **FORBIDDEN**: Claiming completion without reading ALL artifacts or generating ALL 3 final artifacts.
 

package/dist/templates/base/claude/agents/orchestrator.md

@@ -83,12 +83,12 @@ The role: **Choose actions using MCP tools, delegate artifact creation to specia
 **CRITICAL: Violating these rules breaks checkpoints, metrics, and recovery.**
 
 You MUST NOT:
-- Use Edit/Write tools on `orchestrator-index.json` (MCP tools manage state)
+- Use Edit/Write tools on `.orchestrator/orchestrator-index.json` (workflow state managed via PostgreSQL)
 - Use Edit/Write tools to create artifacts (subagents create them)
 - Spawn subagents internally via Task tool (use executeAction instead)
 - Execute multiple phases in a single invocation
 - Skip MCP tools for "efficiency"
-- Update `agentInvocations` or `checkpoints` arrays manually
+- Attempt to manually update workflow state (MCP tools → REST API → PostgreSQL)
 
 **WHY:** The deterministic layer (MCP tools) triggers:
 - Auto-checkpoints after artifact approval
@@ -111,7 +111,7 @@ getContext() → executeAction("advance_to_specify") → RETURN
 getContext() → executeAction("advance_to_specify") → Task(specifier) ← WRONG!
 ```
 
-The CLI reads `pendingAction` from orchestrator-index.json and invokes the appropriate agent. Your job is to SET the pendingAction via executeAction(), not to execute it yourself.
+The CLI reads `pendingAction` via MCP tools (PostgreSQL) and invokes the appropriate agent. Your job is to SET the pendingAction via executeAction(), not to execute it yourself.
 
 ## Example Flow
 
@@ -124,7 +124,7 @@ User: "Create OAuth2 API"
 5. **RETURN** ← You stop here! CLI handles the rest.
 
 **What happens next (NOT your responsibility):**
-- CLI reads pendingAction from orchestrator-index.json
+- CLI reads pendingAction via MCP tools (PostgreSQL)
 - CLI invokes specifier agent
 - Specifier creates spec.md
 - CLI invokes orchestrator again for next phase