Orchestrata Ultimate / Specs / 000-orchestrata-cli

000-orchestrata-cli: Orchestrata CLI

The Orchestrata CLI is the human's entry point into the orchestration system. It provides a unified command interface to initialize projects, boot the runtime, submit intents, monitor agents, review outputs, query governance, and manage sessions.

At a glance

Item	Value
Spec directory	`specs/000-orchestrata-cli/`
Status line in the spec	Design Phase
Requirement IDs defined	112
With a `@traces` citation in `src/`	89 (79.5%)
With a `@traces` citation in `tests/`	5 (4.5%)
Tracked files	12
RTM page	000-orchestrata-cli

Reading this spec

The Orchestrata CLI is the human's entry point into the orchestration system. It replaces five or more separate command-line tools with one unified command interface, so that a person keeps control over a multi-agent run through consistent commands. The spec covers initializing projects, booting the runtime, submitting intents, monitoring agents, reviewing and approving output, querying governance, running verification, querying the knowledge graph and managing sessions.

The scope is nine user stories: project initialization, runtime lifecycle, intent submission, review and approval, and session management are priority 1; agent monitoring, governance query, verification and knowledge graph query are priority 2. Five functional requirement groups sit beside them: command structure, configuration management, service integration, human-in-the-loop control and output formatting. All requirement IDs use the REQ-000- prefix.

The key design decisions are stated in the overview. The CLI is a thin layer that delegates to existing packages rather than reimplementing them. It is built on the Click framework and exposed through a root entry point in the project scripts so that it works with uv. Prolog gates guard every destructive or approval action, which is how human-in-the-loop control is enforced. The CLI integrates with the components specified in specs 001 to 008.

In the code, most of the work lives in orchestrata_ultimate/kernel/cli_main, with supporting pipeline code in orchestrata_ultimate/kernel/pipeline, orchestrata_ultimate/session/cli/pipeline, orchestrata_ultimate/orchestrator/pipeline_escalation and the gate in orchestrata_ultimate/governance/prolog_gate. The per-requirement view is on the RTM page.

The spec's own status line reads Design Phase, while the code already traces most of its requirements. It tracks 12 files and defines 112 requirement IDs. The full text follows below.

Measured coverage is 89 of 112 requirements cited by at least one @traces in src/ (79.5%), spread over 15 modules; the module citing the most of them is orchestrata_ultimate/kernel/cli_main (80 requirements). In tests/, 5 requirements are cited by a test-side @traces.

Coverage gaps: 23 requirements have no citing symbol. The largest untraced groups are REQ-000-* (23). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (5 against 89).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

ID	Done	Requirement	Traced by
`REQ-000-001`	no	`orchestrata init <project>` creates project directory	1
`REQ-000-002`	no	`orchestrata init` initializes context.json	2
`REQ-000-003`	no	`orchestrata init` creates orchestrata.yaml config	1
`REQ-000-004`	no	`orchestrata init` loads Prolog governance rules	none
`REQ-000-005`	no	`orchestrata init` registers project in Memgraph	1
`REQ-000-006`	no	`orchestrata init` opens first session automatically	1
`REQ-000-007`	no	`orchestrata init --template <type>` applies project template	1
`REQ-000-008`	no	`orchestrata init` validates project name	1
`REQ-000-009`	no	`orchestrata start` boots Kernel (Spec 001)	5
`REQ-000-010`	no	`orchestrata start` starts Postman routing (Spec 002)	3
`REQ-000-011`	no	`orchestrata start` loads Prolog rules (Spec 007)	3
`REQ-000-012`	no	`orchestrata start` connects Redis	1
`REQ-000-013`	no	`orchestrata start` connects Neo4j	1
`REQ-000-014`	no	`orchestrata start` opens session (Spec 006)	none
`REQ-000-015`	no	`orchestrata start` starts health endpoint	6
`REQ-000-016`	no	`orchestrata start --config <path>` loads custom config	2
`REQ-000-017`	no	`orchestrata stop` archives current session	1
`REQ-000-018`	no	`orchestrata stop` drains message queues	1
`REQ-000-019`	no	`orchestrata stop` disconnects Redis and Neo4j	1
`REQ-000-020`	no	`orchestrata stop` shuts down Kernel and Postman	2
`REQ-000-021`	no	`orchestrata status` shows runtime state	1
`REQ-000-022`	no	`orchestrata status` shows connected services	1
`REQ-000-023`	no	`orchestrata status` shows active volks with work_status	4
`REQ-000-024`	no	`orchestrata status` shows session info	1
`REQ-000-025`	no	`orchestrata status` shows health endpoint URL	1
`REQ-000-026`	no	Graceful shutdown on SIGINT/SIGTERM	3
`REQ-000-027`	no	`orchestrata config team --add <volks>` activates volks	1
`REQ-000-028`	no	`orchestrata config team --remove <volks>` deactivates volks	1
`REQ-000-029`	no	Team changes update Prolog facts (active_volk/1)	2
`REQ-000-030`	no	Valid volk aliases enforced (U:Ox, U:PS, U:Vz, U:Ux, U:PM, U:Ar, U:Qa, U:Cx)	2
`REQ-000-031`	no	Invalid volk alias rejected with error message	2
`REQ-000-032`	no	Team configuration persisted in orchestrata.yaml	2
`REQ-000-033`	no	`orchestrata intent "<text>"` submits to Intent Broker (Spec 003)	4
`REQ-000-034`	no	Intent Broker parses natural language into structured intent	1
`REQ-000-035`	no	Prolog validates intent (may_execute, constitutional_check)	1
`REQ-000-036`	no	Validated intent routed to appropriate Volk via CXP packet	1
`REQ-000-037`	no	CLI returns thread_id for tracking	2
`REQ-000-038`	no	CLI displays which volk received the intent	1
`REQ-000-039`	no	`orchestrata respond --thread <id> "<text>"` sends response to volk	6
`REQ-000-040`	no	Response travels as CXP packet through Postman	4
`REQ-000-041`	no	Blocked intents show governance reason	4
`REQ-000-042`	no	`orchestrata agents list` shows all registered volks	1
`REQ-000-043`	no	Agent list shows alias, role, status per volk	1
`REQ-000-044`	no	`orchestrata agents health` shows health per volk	1
`REQ-000-045`	no	Health shows responding/idle/error state	1
`REQ-000-046`	no	`orchestrata packets --thread <id>` shows CXP flow	1
`REQ-000-047`	no	Packet display shows delivery_status per message	1
`REQ-000-048`	no	Packet display shows work_status per message	1
`REQ-000-049`	no	Packet display shows from_agent, to_agent, subject	1
`REQ-000-050`	no	`orchestrata status` combines agents + packets + session view	none
`REQ-000-051`	no	`orchestrata review <volk>` shows volk output/artifacts	3
`REQ-000-052`	no	Review displays on active thread	2
`REQ-000-053`	no	`orchestrata approve --thread <id>` sends work_status=resolved	8
`REQ-000-054`	no	Approve unblocks downstream volks	5
`REQ-000-055`	no	`orchestrata reject --thread <id> "<reason>"` sends feedback	3
`REQ-000-056`	no	Reject keeps volk working with feedback	4
`REQ-000-057`	no	Approve/reject travel as CXP packets through Postman	7
`REQ-000-058`	no	Human must explicitly approve — no auto-approval	10
`REQ-000-059`	no	`orchestrata governance check "<action>"` queries Prolog	1
`REQ-000-060`	no	Check evaluates may_execute, constitutional_check, ethical_check	1
`REQ-000-061`	no	Check returns allowed/denied with reason	3
`REQ-000-062`	no	`orchestrata governance log` shows decision history	1
`REQ-000-063`	no	Log shows which Prolog rule fired per decision	1
`REQ-000-064`	no	`orchestrata governance policies` lists active policies	1
`REQ-000-065`	no	Policies show constitutional constraints	1
`REQ-000-066`	no	All governance queries go through Prolog engine (Spec 007)	4
`REQ-000-067`	no	`orchestrata verify` runs full verification across all specs	1
`REQ-000-068`	no	`orchestrata verify --spec <id>` verifies specific spec	1
`REQ-000-069`	no	Verification reports verified/partial/missing per requirement	1
`REQ-000-070`	no	Verification uses knowledge graph for traceability (Spec 008)	1
`REQ-000-071`	no	Verification results stored in Memgraph	none
`REQ-000-072`	no	RTM generated from verification results	none
`REQ-000-073`	no	`orchestrata knowledge query "<query>"` queries Neo4j	1
`REQ-000-074`	no	Query returns decisions, facts, artifacts from sessions	1
`REQ-000-075`	no	Query supports temporal queries (what happened in session N)	1
`REQ-000-076`	no	Query results formatted for terminal display	1
`REQ-000-077`	no	`orchestrata session status` shows current session state	none
`REQ-000-078`	no	`orchestrata session list` shows all sessions	none
`REQ-000-079`	no	`orchestrata session end` closes current session	none
`REQ-000-080`	no	`orchestrata session end --archive` archives to Neo4j	none
`REQ-000-081`	no	Session end updates context.md	none
`REQ-000-082`	no	Session end creates git checkpoint	none
`REQ-000-083`	no	`orchestrata session resume` loads previous session	none
`REQ-000-084`	no	Resume restores agent state	none
`REQ-000-085`	no	`orchestrata session facts` shows session facts	none
`REQ-000-086`	no	Session commands wrap orchestrata-session (Spec 006)	1
`REQ-000-087`	no	No volk work_status transitions to resolved without may_complete/2	1
`REQ-000-088`	no	may_complete/2 checks all_acceptance_criteria_met	1
`REQ-000-089`	no	may_complete/2 checks all_outputs_verified	2
`REQ-000-090`	no	may_complete/2 checks no_open_questions	3
`REQ-000-091`	no	may_complete/2 checks downstream_volk_not_blocked	none
`REQ-000-092`	no	Failed gate returns reason to volk	1
`REQ-000-093`	no	Volk continues working until all gates pass	none
`REQ-000-094`	no	Click framework for all commands	1
`REQ-000-095`	no	`orchestrata version` shows version	1
`REQ-000-096`	no	--json flag for machine-readable output	2
`REQ-000-097`	no	Clear error messages (no raw tracebacks)	5
`REQ-000-098`	no	Help text for every command and subcommand	none
`REQ-000-109`	no	`uv sync` installs `orchestrata` script to venv bin directory	none
`REQ-000-110`	no	`uv run orchestrata` works from any directory within the workspace	none
`REQ-000-111`	no	Root pyproject.toml defines [project.scripts] entry point	none
`REQ-000-112`	no	Entry point resolves to orchestrata.kernel.cli_main:main	1
`REQ-000-099`	no	Single `orchestrata` entry point replaces 5 existing CLIs	1
`REQ-000-100`	no	orchestrata-kernel start subsumed by `orchestrata start`	1
`REQ-000-101`	no	orchestrata-postman start subsumed by `orchestrata start`	1
`REQ-000-102`	no	orchestrata-session commands wrapped by `orchestrata session`	1
`REQ-000-103`	no	orchestrata-console replaced by full command tree	1
`REQ-000-104`	no	U:Cx (Concierge) intake workflow: clarify, gather facts, escalate	none
`REQ-000-105`	no	U:Ar (Architect) 5-step pipeline: research, questions, design, tasks, review loop	1
`REQ-000-106`	no	U:Vz (VizInt) reviews architecture for gaps before implementation	none
`REQ-000-107`	no	Each volk has a world-class expert system prompt	1
`REQ-000-108`	no	Every volk action traced to a numbered spec	none

Code that traces this spec

Module	Symbols	Requirements
`orchestrata_ultimate/agents/volks/architect/volk`	1	1
`orchestrata_ultimate/agents/volks/persona`	1	1
`orchestrata_ultimate/governance/prolog_client`	1	1
`orchestrata_ultimate/governance/prolog_gate`	6	6
`orchestrata_ultimate/kernel/cli_client`	2	1
`orchestrata_ultimate/kernel/cli_main`	41	80
`orchestrata_ultimate/kernel/cli_watch`	3	1
`orchestrata_ultimate/kernel/pipeline`	7	11
`orchestrata_ultimate/kernel/pipeline_checkpoint`	1	1
`orchestrata_ultimate/kernel/pipeline_escalation`	3	4
`orchestrata_ultimate/orchestrator/engine`	1	1
`orchestrata_ultimate/orchestrator/orchestrator`	2	2
`orchestrata_ultimate/orchestrator/pipeline_escalation`	9	9
`orchestrata_ultimate/orchestrator/pipeline_runner`	2	1
`orchestrata_ultimate/session/cli/pipeline`	5	10

Checklists

`checklists/README.md`

SPEC-000: Orchestrata CLI — Checklist Overview

Purpose

Checklists for the unified Orchestrata CLI — the human's control plane over the multi-agent orchestration system. The CLI is a thin interface layer over Specs 001-008.

Checklist Files

File	Contents	Items
constitutional.md	11 constitutional articles compliance	110
requirements.md	10 user stories + cross-cutting requirements	108
testing.md	Unit, integration, and performance tests	143
Total		361

Command Coverage

Spec ID	Command Group	Requirements	Tests
SPEC-000-001	`orchestrata init`	8 reqs	7 tests
SPEC-000-002	`orchestrata start/stop/status`	18 reqs	18 tests
SPEC-000-003	`orchestrata config team`	6 reqs	6 tests
SPEC-000-004	`orchestrata intent/respond`	9 reqs	8 tests
SPEC-000-005	`orchestrata agents/packets`	9 reqs	8 tests
SPEC-000-006	`orchestrata review/approve/reject`	8 reqs	8 tests
SPEC-000-007	`orchestrata governance`	8 reqs	7 tests
SPEC-000-008	`orchestrata verify`	6 reqs	6 tests
SPEC-000-009	`orchestrata knowledge`	4 reqs	5 tests
SPEC-000-010	`orchestrata session`	10 reqs	10 tests
Cross-cutting	Prolog gates, CLI design, unified CLI, volks	22 reqs	19 tests

Dependencies on Other Specs

This CLI Command	Depends On
`orchestrata start`	Spec 001 (Kernel), 002 (Postman), 006 (Session), 007 (Governance)
`orchestrata intent`	Spec 003 (Intent), 004 (CXP), 007 (Governance)
`orchestrata agents`	Spec 001 (Kernel), 002 (Postman)
`orchestrata review/approve`	Spec 004 (CXP), 002 (Postman)
`orchestrata governance`	Spec 007 (Prolog Governance)
`orchestrata verify`	Spec 007b (Verification), 008 (Knowledge Graph)
`orchestrata knowledge`	Spec 008 (Knowledge Graph)
`orchestrata session`	Spec 006 (Session Management)

Completion Tracking

All checkboxes start unchecked [ ]. A checkbox is marked [x] ONLY when:

The implementation exists in code
A test verifies the implementation
The test passes
Prolog logic gates confirm completion (may_complete/2)

No self-declaration. No assumption. Verified only.

`checklists/constitutional.md`

SPEC-000: Constitutional Compliance Checklist — Orchestrata CLI

Article I: Human Authority

[ ] Every CLI command requires explicit human invocation
[ ] orchestrata approve required before volk work is accepted
[ ] orchestrata reject sends feedback and continues volk work
[ ] Human notified on all volk state transitions
[ ] Human can stop runtime at any time via orchestrata stop
[ ] Human can override governance via orchestrata governance check
[ ] Human reviews volk output before downstream work proceeds
[ ] No autonomous state changes without human awareness
[ ] Intent submission requires explicit human command
[ ] Session end requires explicit human command

Article II: Prolog as Single Source of Truth

[ ] No volk can self-declare task completion
[ ] Prolog evaluates may_complete/2 before any work_status=resolved
[ ] orchestrata governance check queries Prolog directly
[ ] orchestrata governance log shows which Prolog rule fired
[ ] orchestrata governance policies lists Prolog-backed policies
[ ] Active volk registration stored as Prolog facts (active_volk/1)
[ ] Intent validation runs through Prolog (may_execute, constitutional_check)
[ ] All routing decisions validated through Prolog predicates
[ ] Completion logic gates encoded as Prolog rules
[ ] Constitutional compliance queryable via CLI

Article III: Session Isolation

[ ] orchestrata init creates isolated project context
[ ] Session facts scoped to current project
[ ] orchestrata session commands operate on active session only
[ ] No cross-project state leakage via CLI
[ ] Redis topics namespaced per session
[ ] Neo4j knowledge scoped per project
[ ] CXP packets tagged with session_id
[ ] orchestrata session resume restores correct project context
[ ] orchestrata session list shows only current project sessions
[ ] Agent state isolated per session

Article IV: Hooks for Extensibility

[ ] CLI uses Click framework with extensible command groups
[ ] New subcommands addable without modifying core CLI
[ ] orchestrata config team dynamically manages volk roster
[ ] Governance policies loadable at runtime
[ ] Session hooks fire on start/end/archive
[ ] Intent routing extensible via Prolog rules
[ ] CXP packet handlers registrable per volk
[ ] Knowledge graph queries extensible
[ ] Verification checks extensible per spec
[ ] Health checks extensible per service

Article V: Minimal Core, Maximal Extension

[ ] CLI is a thin layer — no business logic
[ ] orchestrata start delegates to Kernel (Spec 001)
[ ] orchestrata intent delegates to Intent Broker (Spec 003)
[ ] orchestrata session delegates to Session Manager (Spec 006)
[ ] orchestrata governance delegates to Prolog Engine (Spec 007)
[ ] orchestrata verify delegates to Verification Agent (Spec 007b)
[ ] orchestrata knowledge delegates to Knowledge Graph (Spec 008)
[ ] orchestrata packets delegates to Postman (Spec 002)
[ ] orchestrata agents delegates to Kernel Registry (Spec 001)
[ ] CLI adds only presentation and argument parsing

Article VI: Python 3.11+ Implementation

[ ] CLI implemented in Python 3.11+
[ ] Type hints on all CLI handler functions
[ ] async/await for commands that call async services
[ ] Click framework for argument parsing
[ ] Absolute imports only
[ ] uv for package management
[ ] Pydantic for config validation
[ ] pathlib.Path for all file paths
[ ] f-strings for output formatting
[ ] Structured error messages (no raw tracebacks to user)

Article VII: Testing Without Mocks

[ ] CLI tests invoke real Click test runner
[ ] Integration tests boot real Kernel and Postman
[ ] Governance tests query real Prolog engine
[ ] Session tests create real sessions in Redis
[ ] Knowledge tests query real Neo4j
[ ] CXP tests send real packets through Postman
[ ] No unittest.mock, MagicMock, patch, or @mock
[ ] Test fixtures create real project directories
[ ] Intent tests parse real natural language input
[ ] Verification tests run real constraint checks

Article VIII: Metrics and Observability

[ ] orchestrata status shows all service health
[ ] orchestrata agents health shows per-volk metrics
[ ] orchestrata governance log shows decision audit trail
[ ] orchestrata packets shows message delivery metrics
[ ] CLI commands log execution time
[ ] Failed commands log error context
[ ] Session facts queryable via orchestrata session facts
[ ] Verification results queryable via orchestrata verify
[ ] All CLI output structured for human readability
[ ] JSON output mode available (--json flag)

Article IX: Graceful Degradation

[ ] CLI starts even if Neo4j is unavailable (knowledge commands disabled)
[ ] CLI starts even if Redis is unavailable (messaging commands disabled)
[ ] CLI starts even if Prolog is unavailable (governance commands warn)
[ ] orchestrata status shows which services are down
[ ] Commands that depend on unavailable services return clear error
[ ] Session management works with file-only fallback (no Redis)
[ ] orchestrata verify works offline against local code
[ ] orchestrata agents list works from cached registry
[ ] Partial service availability clearly communicated
[ ] No silent failures — every degradation is visible

Article X: Version Compatibility

[ ] CLI version shown via orchestrata version
[ ] CLI version compatible with kernel/postman/session package versions
[ ] CXP protocol version tracked in all packets
[ ] orchestrata.yaml schema versioned
[ ] Backward-compatible config loading
[ ] Deprecation warnings for removed commands
[ ] Semantic versioning on CLI package
[ ] API compatibility with all Spec 001-008 packages
[ ] Migration guidance for breaking changes
[ ] Version mismatch detection at startup

Article XI: Documentation First

[ ] Architecture document written before code (this document)
[ ] CLI command tree documented with all flags and arguments
[ ] Each command spec references dependent Specs (001-008)
[ ] Interaction diagrams for all major flows
[ ] Existing CLI mapping documented (what replaces what)
[ ] Open items tracked and resolved before implementation
[ ] Design decisions documented with rationale
[ ] Usage scenarios written (specs/000-orchestrata-cli/usage-scenarios/)
[ ] All specs traceable to Neo4j knowledge graph
[ ] RTM generated from graph (never hand-written)

`checklists/requirements.md`

The requirement list above comes from this file; 0 of 112 checkbox items are ticked.

`checklists/testing.md`

SPEC-000: Testing Checklist — Orchestrata CLI

Unit Tests: Project Initialization (SPEC-000-001)

[ ] orchestrata init creates project directory
[ ] orchestrata init creates context.json
[ ] orchestrata init creates orchestrata.yaml
[ ] orchestrata init rejects invalid project names
[ ] orchestrata init --template applies template
[ ] orchestrata init fails gracefully if Prolog unavailable
[ ] orchestrata init fails gracefully if Neo4j unavailable

Unit Tests: Runtime Lifecycle (SPEC-000-002)

[ ] orchestrata start boots Kernel
[ ] orchestrata start starts Postman
[ ] orchestrata start loads Prolog rules
[ ] orchestrata start connects Redis
[ ] orchestrata start connects Neo4j
[ ] orchestrata start opens session
[ ] orchestrata start --config loads custom config
[ ] orchestrata start reports missing services clearly
[ ] orchestrata stop archives session
[ ] orchestrata stop drains message queues
[ ] orchestrata stop disconnects services
[ ] orchestrata stop handles already-stopped state
[ ] orchestrata status shows running state
[ ] orchestrata status shows stopped state
[ ] orchestrata status shows connected services
[ ] orchestrata status shows active volks
[ ] orchestrata status shows session info
[ ] Signal handler triggers graceful shutdown

Unit Tests: Team Configuration (SPEC-000-003)

[ ] orchestrata config team --add U:Cx activates Concierge
[ ] orchestrata config team --add accepts multiple volks
[ ] orchestrata config team --remove U:Cx deactivates Concierge
[ ] Invalid volk alias rejected with error
[ ] Team changes persist in orchestrata.yaml
[ ] Team changes update Prolog facts

Unit Tests: Intent Submission (SPEC-000-004)

[ ] orchestrata intent submits to Intent Broker
[ ] Intent returns thread_id
[ ] Intent displays target volk
[ ] Blocked intent shows governance reason
[ ] orchestrata respond sends CXP packet to correct thread
[ ] Response delivered through Postman
[ ] Empty intent rejected
[ ] Invalid thread_id handled

Unit Tests: Agent Monitoring (SPEC-000-005)

[ ] orchestrata agents list shows registered volks
[ ] Agent list shows alias, role, status
[ ] orchestrata agents health shows per-volk health
[ ] Health shows responding/idle/error
[ ] orchestrata packets shows CXP flow for thread
[ ] Packets show delivery_status
[ ] Packets show work_status
[ ] Invalid thread_id handled

Unit Tests: Review and Approval (SPEC-000-006)

[ ] orchestrata review shows volk output
[ ] orchestrata approve sends work_status=resolved
[ ] Approve unblocks downstream volks
[ ] orchestrata reject sends feedback to volk
[ ] Reject keeps volk working
[ ] Approve/reject travel as CXP packets
[ ] Invalid thread_id handled
[ ] Review with no output shows appropriate message

Unit Tests: Governance (SPEC-000-007)

[ ] orchestrata governance check queries Prolog
[ ] Check returns allowed with empty violations
[ ] Check returns denied with reason
[ ] orchestrata governance log shows decisions
[ ] Log shows Prolog rule that fired
[ ] orchestrata governance policies lists policies
[ ] Governance commands fail gracefully without Prolog

Unit Tests: Verification (SPEC-000-008)

[ ] orchestrata verify runs full verification
[ ] orchestrata verify --spec 001 verifies specific spec
[ ] Verification reports verified/partial/missing
[ ] Results stored in Neo4j
[ ] Verify works without Neo4j (local code only)
[ ] Invalid spec ID handled

Unit Tests: Knowledge Graph (SPEC-000-009)

[ ] orchestrata knowledge query queries Neo4j
[ ] Query returns formatted results
[ ] Query handles empty results
[ ] Query fails gracefully without Neo4j
[ ] Temporal queries return session-scoped results

Unit Tests: Session Management (SPEC-000-010)

[ ] orchestrata session status shows current session
[ ] orchestrata session list shows all sessions
[ ] orchestrata session end closes session
[ ] orchestrata session end --archive archives to Neo4j
[ ] Session end updates context.md
[ ] Session end creates git checkpoint
[ ] orchestrata session resume loads previous session
[ ] Resume restores agent state
[ ] orchestrata session facts shows facts
[ ] Session commands delegate to Spec 006

Unit Tests: Prolog Completion Gates

[ ] may_complete/2 returns true when all gates pass
[ ] may_complete/2 returns false when acceptance criteria missing
[ ] may_complete/2 returns false when outputs unverified
[ ] may_complete/2 returns false when open questions remain
[ ] may_complete/2 returns false when downstream volk blocked
[ ] Failed gate returns specific reason
[ ] Volk cannot transition to resolved without may_complete/2

Unit Tests: CLI Framework

[ ] orchestrata version shows version
[ ] orchestrata --help shows all commands
[ ] Every subcommand has help text
[ ] --json flag produces JSON output
[ ] Invalid commands show helpful error
[ ] Clear error messages (no raw tracebacks)

Integration Tests

[ ] Full flow: init -> start -> intent -> respond -> review -> approve -> session end
[ ] Intent submission through Kernel -> Intent Broker -> Prolog -> Postman -> Volk
[ ] Volk completion: work done -> may_complete/2 -> resolved -> human notified
[ ] Volk rejection: review -> reject -> volk continues -> re-review -> approve
[ ] Governance block: intent blocked by Prolog -> human notified with reason
[ ] Session lifecycle: start -> work -> end --archive -> resume -> previous state restored
[ ] Multi-volk handoff: U:Cx completes -> U:Ar receives -> U:Vz receives
[ ] CXP packet round-trip: human -> Postman -> Redis -> Volk -> Postman -> human
[ ] Knowledge graph: session facts persisted -> query returns them
[ ] Graceful degradation: start without Neo4j, knowledge commands disabled
[ ] Graceful degradation: start without Redis, messaging commands disabled
[ ] Graceful degradation: start without Prolog, governance commands warn

Performance Tests

[ ] orchestrata start boots in < 5 seconds
[ ] orchestrata status responds in < 500ms
[ ] orchestrata intent submission to volk delivery < 1 second
[ ] orchestrata agents list responds in < 200ms
[ ] orchestrata governance check responds in < 100ms
[ ] orchestrata session end --archive completes in < 3 seconds
[ ] orchestrata knowledge query responds in < 1 second
[ ] CXP packet round-trip through Redis < 50ms
[ ] may_complete/2 evaluation < 10ms
[ ] CLI help renders in < 100ms

Other tracked files

specs/000-orchestrata-cli/architecture.md
specs/000-orchestrata-cli/compliance-audit.md
specs/000-orchestrata-cli/diagrams/cli-dependencies.drawio
specs/000-orchestrata-cli/diagrams/completion-gate.drawio
specs/000-orchestrata-cli/diagrams/intent-flow.drawio
specs/000-orchestrata-cli/spec-001-updated.md
specs/000-orchestrata-cli/usage-scenarios/scenario-000-new-project.md

Full spec text

Verbatim from specs/000-orchestrata-cli/spec.md; headings are pushed down two levels.

SPEC-000: Orchestrata CLI

Metadata

Spec ID: 000-orchestrata-cli
Title: Orchestrata Command Line Interface
Author: Mohamed
Status: Design Phase
Created: 2026-01-15
Last Updated: 2026-01-15
Priority: P1
Components: CLI module, orchestrata-kernel, orchestrata-postman

Overview

What

Why

Single unified interface replaces 5+ separate CLIs
Human-in-the-loop control over multi-agent orchestration
Consistent command structure across all operations
Integration with all Orchestrata components (Specs 001-008)

How

Thin layer that delegates to existing packages
Click framework for CLI implementation
Root entry point in [project.scripts] for uv compatibility
Prolog gates for all destructive/approval actions

User Scenarios & Stories

US-001: Project Initialization (P1)

As a developer I want to initialize a new Orchestrata project So that I can start orchestrating agents quickly

Acceptance Criteria:

Creates project directory structure
Initializes context.json (session source of truth)
Creates orchestrata.yaml (project config)
Loads Prolog governance rules (11 constitutional articles)
Registers project in Neo4j knowledge graph
Opens first session automatically

Command:

orchestrata init <project> [--template <type>]

US-002: Runtime Lifecycle (P1)

As a system operator I want to control the Orchestrata runtime So that I can start, stop, and monitor the system

Acceptance Criteria:

start: Boots Kernel, Postman, loads Prolog rules, connects Redis/Neo4j, opens session
stop: Archives session, drains queues, disconnects services, shuts down components
status: Shows runtime state, connected services, active volks, session info

Commands:

orchestrata start [--config <path>]
orchestrata stop
orchestrata status

US-003: Intent Submission (P1)

As a user I want to submit natural language intents to the system So that agents can execute my requests

Acceptance Criteria:

Submits intent to Intent Broker (Spec 003)
Intent Broker parses and Prolog validates
Routes to appropriate Volk
Returns thread_id for tracking
Supports response back to Volk

Commands:

orchestrata intent "<text>"
orchestrata respond --thread <id> "<text>"

US-004: Agent Monitoring (P2)

As a system administrator I want to monitor agents and message flow So that I can observe system health

Acceptance Criteria:

List all registered volks with alias, role, status
Show health per volk (responding/idle/error)
Display CXP packet flow on threads
Combined view of agents + packets + session

Commands:

orchestrata agents list
orchestrata agents health
orchestrata packets --thread <id>

US-005: Review and Approval (P1)

As a human supervisor I want to review and approve agent outputs So that Article I (Human Authority) is enforced

Acceptance Criteria:

Review output from specific volk on active thread
Approve work (sends work_status=resolved)
Reject with feedback (sends CXP with feedback)

Commands:

orchestrata review <volk>
orchestrata approve --thread <id>
orchestrata reject --thread <id> "<reason>"

US-006: Governance Query (P2)

As a governance officer I want to query and inspect governance policies So that I can understand system constraints

Acceptance Criteria:

Check if action is allowed via Prolog
Show governance decisions with rule that fired
List active policies and constitutional constraints

Commands:

orchestrata governance check "<action>"
orchestrata governance log
orchestrata governance policies

US-007: Verification (P2)

As a quality engineer I want to run verification against specifications So that I can validate requirements compliance

Acceptance Criteria:

Run constraint satisfaction against spec requirements
Report verified/partial/missing per requirement
Use knowledge graph for traceability
Store results in Neo4j for RTM generation

Command:

orchestrata verify [--spec <id>]

US-008: Knowledge Graph Query (P2)

As a analyst I want to query the knowledge graph So that I can retrieve project context and history

Acceptance Criteria:

Query Neo4j temporal knowledge graph
Return decisions, facts, artifacts from sessions
Support natural language to Cypher translation

Command:

orchestrata knowledge query "<query>"

US-009: Session Management (P1)

As a developer I want to manage work sessions So that I can track work and resume contexts

Acceptance Criteria:

Show current session state
List all sessions with timestamps and fact counts
Archive session to Neo4j, update context.md
Resume previous session context
Show accumulated session facts

Commands:

orchestrata session status
orchestrata session list
orchestrata session end [--archive]
orchestrata session resume
orchestrata session facts

Functional Requirements

FR-001: Command Structure

System SHALL provide unified orchestrata command tree
System SHALL support nested subcommands (e.g., orchestrata session status)
System SHALL provide help text for all commands
System SHALL validate command arguments

FR-002: Configuration Management

System SHALL load configuration from orchestrata.yaml
System SHALL support environment variable overrides
System SHALL validate configuration on load
System SHALL provide default values for all settings

FR-003: Service Integration

System SHALL integrate with Kernel (Spec 001)
System SHALL integrate with Postman (Spec 002)
System SHALL integrate with Intent Broker (Spec 003)
System SHALL integrate with CXP Protocol (Spec 004)
System SHALL integrate with Agents (Spec 005)
System SHALL integrate with Session Management (Spec 006)
System SHALL integrate with Governance (Spec 007)
System SHALL integrate with Knowledge Graph (Spec 008)

FR-004: Human-in-the-Loop

System SHALL require explicit human command for destructive actions
System SHALL require explicit approval for work completion (Article I)
System SHALL route human responses as CXP packets through Postman

FR-005: Output Formatting

System SHALL support human-readable output (default)
System SHALL support JSON output (--json flag)
System SHALL support quiet mode (--quiet flag)
System SHALL provide colored output for terminals

Technical Design

Architecture

┌─────────────────────────────────────────────────────────┐
│                    orchestrata CLI                       │
├─────────────────────────────────────────────────────────┤
│  init  │  start/stop/status  │  intent/respond         │
│  agents │  review/approve/reject  │  governance         │
│  verify  │  knowledge  │  session                     │
├─────────────────────────────────────────────────────────┤
│              CLI Entry Point (Click)                    │
├─────────────────────────────────────────────────────────┤
│  orchestrata-kernel  │  orchestrata-postman            │
│  orchestrata-session │  orchestrata-governance         │
│  orchestrata-knowledge                                │
└─────────────────────────────────────────────────────────┘

Entry Point

Entry point defined in root pyproject.toml [project.scripts]
orchestrata = "orchestrata.kernel.cli_main:main"
Required for uv workspace mode compatibility

Existing CLI Mapping

Existing CLI	Spec 000 Equivalent
`orchestrata`	`orchestrata start` (expanded)
`orchestrata-kernel`	Subsumed by `orchestrata start`
`orchestrata-postman`	Subsumed by `orchestrata start`
`orchestrata-session`	`orchestrata session *` (wrapped)
—	`orchestrata init` (NEW)
—	`orchestrata intent` (NEW)
—	`orchestrata governance` (NEW)

Success Criteria

All commands listed in Command Tree are functional
Integration with all 8 component specs verified
Human-in-the-loop workflows tested
Configuration management working
Help text complete for all commands

Dependencies

orchestrata-kernel (Spec 001)
orchestrata-postman (Spec 002)
orchestrata-orchestrator (Spec 003)
orchestrata-cxp (Spec 004)
orchestrata-agents (Spec 005)
orchestrata-session (Spec 006)
orchestrata-governance (Spec 007)
orchestrata-knowledge (Spec 008)

Open Items

#	Item	Owner
1	Define orchestrata.yaml project config schema	U:Ar
2	Define how `intent` translates natural language to structured intent	Spec 003
3	Define how `review` renders volk output (terminal format)	U:Ar
4	Define how `knowledge query` translates natural language to Cypher	Spec 008
5	Determine if standalone kernel/postman CLIs are kept for microservice deployment	U:Ar

Revision History

Date	Version	Author	Changes
2026-03-07	1.0	Mohamed	Initial specification

000-orchestrata-cli: Orchestrata CLI

At a glance

Reading this spec

Requirements

Code that traces this spec

Checklists

checklists/README.md

SPEC-000: Orchestrata CLI — Checklist Overview

Purpose

Checklist Files

Command Coverage

Dependencies on Other Specs

Completion Tracking

checklists/constitutional.md

SPEC-000: Constitutional Compliance Checklist — Orchestrata CLI

Article I: Human Authority

Article II: Prolog as Single Source of Truth

Article III: Session Isolation

Article IV: Hooks for Extensibility

Article V: Minimal Core, Maximal Extension

Article VI: Python 3.11+ Implementation

Article VII: Testing Without Mocks

Article VIII: Metrics and Observability

Article IX: Graceful Degradation

Article X: Version Compatibility

Article XI: Documentation First

checklists/requirements.md

checklists/testing.md

SPEC-000: Testing Checklist — Orchestrata CLI

Unit Tests: Project Initialization (SPEC-000-001)

Unit Tests: Runtime Lifecycle (SPEC-000-002)

Unit Tests: Team Configuration (SPEC-000-003)

Unit Tests: Intent Submission (SPEC-000-004)

Unit Tests: Agent Monitoring (SPEC-000-005)

Unit Tests: Review and Approval (SPEC-000-006)

Unit Tests: Governance (SPEC-000-007)

Unit Tests: Verification (SPEC-000-008)

Unit Tests: Knowledge Graph (SPEC-000-009)

Unit Tests: Session Management (SPEC-000-010)

Unit Tests: Prolog Completion Gates

Unit Tests: CLI Framework

Integration Tests

Performance Tests

Other tracked files

Full spec text

SPEC-000: Orchestrata CLI

Metadata

Overview

What

Why

How

User Scenarios & Stories

US-001: Project Initialization (P1)

US-002: Runtime Lifecycle (P1)

US-003: Intent Submission (P1)

US-004: Agent Monitoring (P2)

US-005: Review and Approval (P1)

US-006: Governance Query (P2)

US-007: Verification (P2)

US-008: Knowledge Graph Query (P2)

US-009: Session Management (P1)

Functional Requirements

FR-001: Command Structure

FR-002: Configuration Management

FR-003: Service Integration

FR-004: Human-in-the-Loop

FR-005: Output Formatting

Technical Design

Architecture

Entry Point

Existing CLI Mapping

Success Criteria

Dependencies

Open Items

Revision History

Related

`checklists/README.md`

`checklists/constitutional.md`

`checklists/requirements.md`

`checklists/testing.md`