self-bootstrap Topic Execution Plan Template

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 generic template for submitting a topic directly to the orchestrator's self-bootstrap workflow for execution. Usage: copy this file, replace the placeholders, and pass the topic objective to orchestrator. The human role is limited to launching, monitoring, recording, and intervening when exceptions occur.

Recommended reference examples:

1. docs/showcases/resource-rs-refactor-execution.md (if this file is still present)
2. docs/showcases/self-bootstrap-builtin-self-test-workaround-execution.md

---

1. Task Objective

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

Topic name: <topic title>

Background: <Brief description of the current problem, tech debt, defect, or optimization opportunity>

Task objective for this round: <Describe the expected outcome from orchestrator>

Constraints:

1. Prioritize fixing the root cause; superficial workarounds are not acceptable.
2. Preserve existing core semantics, compatibility requirements, key events, or state behaviors: <behaviors to preserve>
3. The final goal is: <explicit completion state>

1.1 Expected Output

Produced and delivered autonomously by orchestrator:

1. An implementation plan (generated by the plan step).
2. Necessary QA documentation updates (generated/updated as determined by qa_doc_gen).
3. Code or configuration changes corresponding to the topic objective.
4. Bootstrap regression verification results.
5. If issues are found in this round, ticket_fix and subsequent steps attempt to close them out.

1.2 Non-Goals

This round does not involve humans pre-defining implementation details or specifying concrete code changes on behalf of orchestrator in the plan document. Implementation paths are decided autonomously by the workflow — humans only observe whether the process deviates from the objective.

---

2. Execution Method

This round follows the standard self-bootstrap pipeline without manual task decomposition:

plan -> qa_doc_gen -> implement -> self_test -> self_restart -> qa_testing -> ticket_fix -> align_tests -> doc_governance -> loop_guard

self_restart step: After self_test passes, self_restart rebuilds the release binary (cargo build --release -p orchestratord), verifies it (--help), snapshots .stable, sets the task to restart_pending, and signals a restart via RestartRequestedError. The daemon drains workers (30s timeout), then uses exec() to replace itself with the new binary in-place (preserving PID). The new process auto-resumes the restart_pending task and continues into Cycle 2. This step has repeatable: false, so it only runs in Cycle 1. Build failure is non-fatal (on_failure: continue) — the loop continues with the old binary.

The human role is limited to two types:

1. Launching and providing the topic objective.
2. Monitoring execution status, determining if the process is stuck, and recording results.

---

3. Startup Steps

3.1 Build and Start the Daemon

In C/S architecture, the CLI (orchestrator) connects to the daemon (orchestratord) via Unix Domain Socket.

cd "$ORCHESTRATOR_ROOT"   # your orchestrator project directory

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

# Start daemon (if not running)
# --foreground keeps log output in foreground; --workers specifies parallel worker count
nohup ./target/release/orchestratord --foreground --workers 2 > /tmp/orchestratord.log 2>&1 &

# Verify daemon is running
ps aux | grep orchestratord | grep -v grep
# Verify queue can be consumed by daemon workers
orchestrator task list -o json

Warning: CLI binary path: The C/S mode CLI is at target/release/orchestrator (crates/cli), not the legacy monolithic binary core/target/release/agent-orchestrator. Update any symlinks pointing to the old path.

3.2 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
# To use the Claude native API, comment out the above line (claude-* model configs will take effect)
orchestrator apply -f docs/workflow/execution-profiles.yaml --project self-bootstrap
# Warning: --project is required, otherwise real AI agents will register in the global space
orchestrator apply -f docs/workflow/self-bootstrap.yaml --project self-bootstrap

3.3 Verify Resources Are Loaded

Verify resources are loaded (add --project to limit scope to a project):

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

3.4 Create Task (Submit Objective to Orchestrator)

In C/S mode, task create enqueues directly to daemon workers. Task creation automatically starts execution — no separate task start is needed.

Before creating the task, determine the target file scope:

• Option A: Specify files (recommended) — process only files directly relevant to this topic; faster execution and higher focus.
• Option B: Full scan — omit -t; the system automatically scans all .md files under the folder configured in qa_targets (default docs/qa/). Suitable for full regression or documentation governance scenarios, but the item count may be large and execution time will increase accordingly.

Option A: Specify Target Files

orchestrator task create \
  -n "<task name>" \
  -w self -W self-bootstrap \
  --project self-bootstrap \
  -g "<Compress the task objective above into a single line and pass it directly as the goal>" \
  -t <target file 1> \
  -t <target file 2>

Option B: Full Scan

orchestrator task create \
  -n "<task name>" \
  -w self -W self-bootstrap \
  --project self-bootstrap \
  -g "<Compress the task objective above into a single line and pass it directly as the goal>"

Record the returned <task_id>. The task will be immediately claimed by a worker and begin executing. To wait for completion, use orchestrator task watch <task_id> or poll task info.

---

4. Monitoring Methods

This round involves no manual code changes — only continuous observation of whether orchestrator is progressing toward the objective.

4.1 Status Monitoring

orchestrator task list
orchestrator task info <task_id>
orchestrator task trace <task_id>    # execution timeline with anomaly detection
orchestrator task watch <task_id>    # real-time status panel refresh

Key observations:

1. Current cycle
2. Current step
3. Whether task status is progressing
4. Whether step order in task trace matches expectations
5. Whether failed, blocked, or prolonged inactivity appears

4.2 Log Monitoring

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

Key observations:

1. Whether plan correctly understands the topic objective
2. Whether implement is fixing the root cause rather than applying superficial workarounds
3. Whether self_test still serves as a bootstrap safety gate
4. Whether qa_testing / ticket_fix discovers and collects regression issues
5. Whether the output from each step can pinpoint where stalling or deviation occurred

4.3 Process / Daemon Monitoring

# daemon process
ps aux | grep orchestratord | grep -v grep

# queue/task status
orchestrator task list -o json

# agent subprocesses (claude -p)
ps aux | grep "claude -p" | grep -v grep

# code changes
git diff --stat

Key observations:

1. Whether agent processes are still progressing, not deadlocked
2. Whether git diff --stat shows reasonable ongoing changes
3. If there is prolonged zero output, zero diff, or stalled processes, record as suspected stuck

4.4 Additional Diagnostic Commands

When finer-grained observation is needed, the following commands can be used:

orchestrator task trace <task_id> --json
orchestrator task watch <task_id>
orchestrator event list --task <task_id> --limit 20

Applicable scenarios:

1. Need to confirm which steps were actually executed and which were skipped
2. Need to determine whether the issue is at the scheduler layer, agent layer, or event persistence layer
3. Need to quickly review recent events and confirm whether step_started, step_finished, and guard decisions match expectations

---

5. Key Checkpoints

During monitoring, humans judge whether to continue waiting or intervene based solely on the following checkpoints.

5.1 Plan Phase Checkpoint

Confirm orchestrator's understanding of the problem includes:

1. What the root cause is
2. What the completion state is
3. Which core semantics must be preserved

If the plan clearly deviates from the topic, or downgrades the topic to a superficial fix, it should be flagged as deviation.

5.2 Implement Phase Checkpoint

Confirm code changes satisfy at least one of the following:

1. Directly fixes the root cause
2. Adds missing regression protection
3. Removes temporary workarounds

If changes only occur in peripheral documentation or configuration without addressing the root cause, it should be flagged as not meeting the objective.

5.3 Self-Restart Phase Checkpoint

Confirm execution evidence shows:

1. self_restart executed after self_test in Cycle 1
2. Daemon hot-reloaded the new binary via exec() (PID unchanged)
3. New process successfully took over the restart_pending task and entered Cycle 2
4. If build failed, the task continued normally (on_failure: continue) without affecting subsequent steps

Monitor self_restart hot-reload:

orchestrator event list --task <task_id> --type self_restart --limit 10

5.4 Self-Test Phase Checkpoint

Confirm execution evidence shows:

1. self_test still executes
2. Compilation and test gates were not bypassed
3. This round's changes did not break basic bootstrap safety

5.5 Validation Phase Checkpoint

Key observations in Cycle 2:

1. Whether qa_testing produces regression tickets
2. Whether ticket_fix collects new issues
3. Whether align_tests adds missing unit tests
4. Whether doc_governance introduces no documentation drift

---

6. Success Criteria

The topic is considered complete when all of the following conditions are met:

1. orchestrator completed the full self-bootstrap pipeline, or exited normally at loop_guard.
2. The core fix addresses the root cause defined in the objective, not a superficial workaround.
3. Key completion state achieved: <fill in the explicit completion condition for the topic here>
4. self_test still functions normally as a builtin.
5. This round did not leave any new unresolved tickets; if tickets exist, they must have been collected by ticket_fix in the same round, or the reason for not closing them must be explicitly recorded.

---

7. Exception Handling

If any of the following occur, the human should stop "monitor-only" mode and record the exception:

1. plan clearly deviates from the topic
2. implement has prolonged zero output or zero code changes
3. self_test is ineffective or bypassed
4. qa_testing continuously produces tickets of the same type, entering a futile loop

7.2 C/S Architecture-Specific Exceptions

Exception	Detection Method	Resolution
Daemon not running	CLI reports failed to connect to daemon at .../orchestrator.sock	Start with orchestratord --foreground --workers 2
CLI points to legacy monolithic binary	which orchestrator points to core/target/release/	Update symlink to target/release/orchestrator
Daemon still uses old code after rebuild	Previously fixed bug reappears	Kill old daemon process and start a new one
Task starts immediately after task create	task list shows pending or quickly becomes running	In C/S mode, task lifecycle is queue-only; this is normal behavior

Recommended recording method:

orchestrator task info <task_id>
orchestrator task logs --tail 200 <task_id>
git diff --stat

Manual takeover for analysis should follow if necessary, rather than designing implementation solutions on behalf of orchestrator.

---

8. Human Role Boundaries

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

1. Providing the objective
2. Launching the workflow
3. Monitoring status
4. Interrupting and recording when exceptions occur

Humans do not write implementation plans for orchestrator in advance, do not preset code changes, and do not decompose tasks into manual sub-steps. The purpose of this template is to reuse a stable execution method to verify: whether the current orchestrator can autonomously complete a bootstrap topic around a clear objective.