Self-Bootstrap Test Fixture: Echo CLI Subcommand

Harness Engineering execution plan: this is an agent-executable scenario that shows how the control plane coordinates environment, workflow, guardrails, and feedback loops rather than a one-off agent call.

Agent Collaboration: This document is an agent-executable plan. Open this project in an AI coding agent (Claude Code, OpenCode, Codex, etc.) — the agent reads this plan and orchestrates other agents via the orchestrator CLI to collaboratively complete the task, from resource deployment and execution to result verification, fully autonomously.

This document is a permanent test fixture for validating the orchestrator's self-bootstrap capability. The fixture itself is implementable but should never be merged — simply revert the code after each test to reuse it.

---

1. Task Objective

Pass the following objective verbatim to the orchestrator as the topic for this round of self-bootstrap:

Topic name: Echo CLI Subcommand

Background: The current orchestrator CLI does not have an echo subcommand. To validate the end-to-end RPC pathway (proto definition → daemon handler → CLI command), a new orchestrator echo --message "hello" subcommand is needed. It calls the daemon's Echo RPC via gRPC, the daemon echoes the message back as-is, and the CLI prints the result.

Objectives for this round:

1. Add an Echo RPC, EchoRequest (with a message field), and EchoResponse (with a reply field) in proto/orchestrator.proto.
2. Implement the Echo handler in crates/daemon/src/server/system.rs that returns request.message as-is.
3. Add an echo.rs subcommand in crates/cli/src/commands/ that calls the daemon's Echo RPC and prints the result.
4. Register the echo subcommand in the CLI's mod.rs or main command registration point.
5. Add unit tests.

Constraints:

1. Do not modify the behavior of any existing RPC or command.
2. The Echo handler must go through control-plane authorization (authorize(server, &request, "Echo")), with the ReadOnly role.
3. Maintain consistency with the existing code style (clap derive, tonic handler patterns).
4. Do not introduce new dependencies.

1.1 Expected Outputs

Produced and landed autonomously by the orchestrator:

1. An implementation plan (generated by the plan step).
2. Necessary QA documentation updates (if deemed needed by qa_doc_gen).
3. Code changes (expected to involve proto/orchestrator.proto, crates/daemon/src/server/system.rs, crates/cli/src/commands/).
4. New unit tests.
5. Self-bootstrap regression verification results.

1.2 Non-Goals

• Do not change the signature or behavior of any existing RPC.
• Do not introduce a new proto service (add to the existing OrchestratorService).
• No gRPC streaming needed — a simple unary RPC is sufficient.

1.3 Design Rationale as a Test Fixture

1. Cross-crate completeness: The change spans three layers — proto → daemon → CLI — validating the orchestrator's understanding of module boundaries.
2. Compilation gate effectiveness: Proto changes trigger code generation; signature mismatches will be caught by self_test.
3. self_restart verification: Adding a new RPC requires rebuilding the daemon binary; self_restart must succeed.
4. Clear completion criteria: orchestrator echo --message "test" returning test means success.
5. Should never be merged: The echo command has no production value.
6. Idempotent and repeatable: All changes are new files/fields; git checkout cleanly reverts everything, ready to run again from a clean tree.
7. Fixture does not become stale as code evolves: It does not depend on specific function names or internal structures — it remains valid as long as the proto + daemon + CLI architecture is unchanged.

---

2. Execution Method

This round follows the standard self-bootstrap pipeline:

Cycle 1: plan -> qa_doc_gen -> implement -> self_test -> self_restart
Cycle 2: plan -> qa_doc_gen -> implement -> self_test -> [self_restart skipped] -> qa_testing -> ticket_fix -> align_tests -> doc_governance -> loop_guard

Human responsibilities are limited to two categories:

1. Launching and providing the task objective.
2. Monitoring execution status, observing behavioral changes, determining if execution is stuck, and recording results.

---

3. Launch Steps

3.1 Build and Start the Daemon

cd "$ORCHESTRATOR_ROOT"   # your orchestrator project directory

cargo build --release -p orchestratord -p orchestrator-cli

# Start the daemon
nohup ./target/release/orchestratord --foreground --workers 2 > /tmp/orchestratord.log 2>&1 &

# Verify the daemon is running
ps aux | grep orchestratord | grep -v grep

3.2 Baseline Collection

# Confirm Echo RPC does not exist
grep -n "Echo" proto/orchestrator.proto
# Expected: no matches

# Confirm echo subcommand does not exist
ls crates/cli/src/commands/echo.rs 2>/dev/null
# Expected: file does not exist

# Confirm system.rs has no echo handler
grep -n "echo" crates/daemon/src/server/system.rs
# Expected: no matches

3.3 Initialize Database and Load Resources

orchestrator delete project/self-bootstrap --force
orchestrator init
orchestrator apply -f your-secrets.yaml           --project self-bootstrap
# apply additional secret manifests as needed      --project self-bootstrap
orchestrator apply -f docs/workflow/execution-profiles.yaml --project self-bootstrap
orchestrator apply -f docs/workflow/self-bootstrap.yaml --project self-bootstrap

3.4 Verify Resources Are Loaded

orchestrator get workspaces --project self-bootstrap -o json
orchestrator get agents --project self-bootstrap -o json

3.5 Create the Task

orchestrator task create \
  -n "echo-command-test" \
  -w self -W self-bootstrap \
  --project self-bootstrap \
  -g "Topic: Echo CLI Subcommand. Add an Echo RPC in proto/orchestrator.proto (EchoRequest with a message field, EchoResponse with a reply field). Implement the Echo handler in crates/daemon/src/server/system.rs that returns request.message as-is, with authorize check (ReadOnly role). Add an echo.rs subcommand in crates/cli/src/commands/ that calls the daemon Echo RPC and prints the result. Register the echo subcommand at the CLI main command registration point. Add unit tests. Do not modify the behavior of any existing RPC or command, and do not introduce new dependencies."

Record the returned <task_id>.

---

4. Monitoring Methods

4.1 Status Monitoring

orchestrator task list
orchestrator task info <task_id>
orchestrator task trace <task_id>
orchestrator task watch <task_id>

Key observations:

1. Current cycle (expected to start at 1, eventually reaching 2)
2. Current step name and order
3. Whether the task status is progressing
4. Whether step order in task trace matches the pipeline definition in section 2

4.2 Log Monitoring

orchestrator task logs --tail 100 <task_id>
orchestrator task logs --tail 200 <task_id>

Key observations:

1. Whether plan identifies the need for changes spanning proto/daemon/CLI layers
2. Whether implement correctly generates proto definitions, handler, and CLI command
3. Whether self_test compilation passes (proto codegen + handler signatures)
4. Whether self_restart successfully rebuilds the daemon binary with the new RPC

4.3 Process / Daemon Monitoring

ps aux | grep orchestratord | grep -v grep
ps aux | grep "claude -p" | grep -v grep
git diff --stat

---

5. Behavioral Change Observations

5.1 Expected Code Changes

File	Expected Change
proto/orchestrator.proto	Add rpc Echo, message EchoRequest, message EchoResponse
crates/daemon/src/server/system.rs	Add echo handler that calls authorize and returns EchoResponse { reply: req.message }
crates/daemon/src/server/mod.rs	Route registration (if manual registration is required)
crates/cli/src/commands/echo.rs	Add echo subcommand with clap derive, calling gRPC Echo
crates/cli/src/commands/mod.rs	Register echo module and subcommand

5.2 self_restart Behavior Verification

Cycle 1's self_restart rebuilds the daemon binary with the new RPC code. Verify:

1. cargo build --release -p orchestratord succeeds (proto codegen + new handler compiles)
2. New binary passes --help verification
3. exec() hot-reload keeps the daemon PID unchanged
4. Cycle 2 continues running on the new binary

---

6. Key Checkpoints

6.1 Plan Phase Checkpoint

Confirm the orchestrator understands the need to:

1. Modify the proto file to add the RPC definition
2. Implement the daemon-side handler
3. Implement the CLI-side subcommand
4. Wire all three layers together while preserving existing behavior

If the plan only proposes modifying one layer while ignoring the others, it should be deemed incomplete.

6.2 Implement Phase Checkpoint

Confirm code changes satisfy:

1. Proto contains the Echo RPC definition
2. Handler includes the authorize call
3. CLI has clap registration and gRPC call
4. No existing RPCs are modified

6.3 Self-Test Phase Checkpoint

1. cargo check passes (proto codegen succeeds)
2. cargo test passes (no regressions)
3. Gates are not bypassed

---

7. Success Criteria

The test is considered passed when all of the following conditions are met:

1. The orchestrator completes 2 full cycles of the self-bootstrap pipeline and terminates normally at loop_guard.
2. proto/orchestrator.proto contains the Echo RPC definition.
3. crates/daemon/src/server/system.rs contains the echo handler with an authorize call.
4. crates/cli/src/commands/ contains the echo subcommand.
5. cargo test --workspace --lib passes.
6. No new unresolved tickets remain from this round.

---

8. Post-Test Revert

This fixture should not be merged. After testing, regardless of success or failure, revert the code:

# Revert all changes
git checkout HEAD -- proto/ crates/ core/

# Delete new files that the agent may have created
git clean -fd proto/ crates/ core/ docs/qa/ docs/design_doc/

# Confirm working tree is clean
git status --short

# Verify compilation
cargo check

The next test can be started from a clean tree.

---

9. Human Role Boundaries

In this plan, the human role is strictly limited to:

1. Providing the objective
2. Starting the workflow
3. Performing baseline collection (section 3.2)
4. Monitoring status and behavioral changes
5. Interrupting and recording on anomalies
6. Reverting code after the test completes

Humans do not prescribe specific implementation approaches and do not manually modify code.