Automate DevOps Remediation Agent

Build a guarded Hermes workflow that investigates incidents and drafts repairs.

Introduction

30 Second Summary

A quick fix can create a second problem when nobody checks what changed. Teams need a way to respond quickly while keeping the final decision in human hands.

In this project, you will turn the detection flow from Build an AI DevOps Organization into a guarded recovery workflow with Hermes Agent. The workflow investigates a missing TaskFlow document in parallel before proposing a validated repair for human review.

What You'll Build

You'll watch a missing-document incident finish as a validated draft pull request in GitHub while the default branch stays untouched.

By the end of this project, you'll have:

  • A repeatable incident drill that detects a missing TaskFlow document before handing the problem to the existing SRE flow.
  • Three parallel investigators that gather root-cause, impact, and recovery evidence without editing the repository.
  • A review-ready repair in one draft PR while the default branch remains untouched. Its Kanban handoff preserves validation evidence and residual risk for review.
  • Secret Mission: Add a failed-validation rollback gate that blocks unsafe publication and recommends a human-reviewed recovery path.

Are there any prerequisites?

This project continues from Build an AI DevOps Organization with its working sre profile on Linux.

You need the existing gateway, TaskFlow health-check cron job, GitHub write access, GitHub CLI, GitHub MCP, and configured model provider.

Before We Start

Before the hands-on work begins, lock in the boundary that makes this recovery workflow safe. You are building a guarded system that prepares reviewable repairs while every final merge remains a human decision.

Verify the Recovery Toolchain

Your Part 5 workflow can already detect and triage failures. Safe remediation now depends on a toolchain that can investigate incidents without widening the SRE profile's permissions.

Hermes Agent 0.21.0 provides the delegation behavior this recovery workflow needs. Its SRE profile must expose the required toolsets to every child investigator.

An authenticated GitHub path lets the parent worker prepare a review-only pull request. A running gateway keeps the durable incident workflow available.

In this step, get ready to:
  • Pin the TaskFlow workspace variables.
  • Verify the SRE recovery runtime.
  • Prove the GitHub draft pull request path.
Pin the project variables

Environment variables give later commands one consistent repository target. They also reserve a separate location for the disposable clone.

  • Return to the terminal from your Part 5 environment.
  • Replace your-username/TaskFlow with your real repository owner and repository name.
  • Apply both project values by running the edited commands below:
export TASKFLOW_REPO="your-username/TaskFlow"
export TASKFLOW_DIR="$HOME/taskflow-self-healing"

What do these variables control?

  • TASKFLOW_REPO identifies the GitHub repository that the incident drill targets.
  • TASKFLOW_DIR points to the disposable clone used during remediation.
  • Keep this terminal open for the rest of the project.

Your shell prompt returns without an error. Good, your recovery workflow now has a consistent repository target.

The disposable workspace path is also ready in this terminal.

Did the export fail?

Check that both values use straight double quotes. Make sure you replaced only your-username/TaskFlow.

Help me fix my TaskFlow environment variables.

Verify Hermes Agent and the SRE tools

Each delegated investigator inherits the parent SRE profile's enabled toolsets. This check confirms the parent can provide read-only investigation tools before the workflow dispatches any child agents.

  • Check the installed Hermes Agent version by running:
hermes --version

What does this command confirm?

The command prints the installed Hermes Agent version. This project requires 0.21.0 for its delegation workflow.

✔️ I see the required version

You're set. Hermes Agent 0.21.0 is ready to coordinate the recovery workflow.

ⓧ I see an older version

The update takes a full pre-update backup before changing the managed installation. Your existing setup has a recovery point if the update needs attention.

  • Update Hermes Agent by running:
hermes update --backup --yes

What does this update do?

  • hermes update updates the managed installation.
  • --backup creates a full pre-update snapshot.
  • --yes accepts the interactive prompts.
  • Recheck the installed version by running:
hermes --version

What should this confirm?

The version output should now report Hermes Agent 0.21.0.

🙋‍♀️ Did the update fail?

Keep the terminal output available because it identifies the update stage that failed. Avoid deleting the backup while you diagnose the problem.

Help me diagnose this Hermes Agent update failure.

ⓧ Command not found

The official Linux installer restores the Hermes Agent command. The installer can open setup prompts during the process.

  • Reuse your existing model provider settings if setup prompts appear.
  • Install Hermes Agent by running:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

What does this installer do?

This downloads the official Hermes Agent installer for Linux. The installer configures the command-line installation and its required components.

  • Check the installed version after the installer finishes by running:
hermes --version

What should this confirm?

The version output should report Hermes Agent 0.21.0.

🙋‍♀️ Still missing the command?

Start a fresh shell after the installer finishes if your current shell cannot find the command. This reloads the command path configured by the installer.

Help me find Hermes Agent after installation.

  • Check the SRE diagnostics plus its enabled toolsets by running the commands below:
sre doctor
sre tools --summary
hermes gateway status

What do these checks prove?

  • sre doctor checks the SRE profile for configuration or dependency problems.
  • sre tools --summary prints the toolsets available to the parent worker.
  • hermes gateway status confirms whether the gateway service is running.

The SRE summary should include delegation, terminal, plus file. The gateway status should confirm that the service is running.

✔️ I see all three toolsets

That's the inheritance boundary confirmed. The SRE parent can give its investigators the required capabilities without broadening their access.

ⓧ A required toolset is missing

The SRE profile has an interactive tool configuration for enabling missing toolsets. Each enabled toolset becomes available to the profile's delegated investigators.

  • Open the SRE tool configuration by running:
sre tools

What does this command open?

This opens the interactive tool configuration for the SRE profile. Your choices update the capabilities available to that profile.

  • Enable delegation if it is missing.
  • Enable terminal if it is missing.
  • Enable file if it is missing.
  • Confirm the updated tool summary by running:
sre tools --summary

What should the updated summary show?

The updated SRE summary should include delegation, terminal, plus file.

🙋‍♀️ Still missing a toolset?

Confirm that you ran the tool configuration through the sre profile alias. A configuration opened through another profile does not update the SRE profile.

Help me enable the missing SRE toolset.

Gateway not running?

Return to the gateway setup from Part 5. Confirm that you are checking the same Hermes environment used by the SRE profile.

Help me diagnose the Hermes gateway status.

Verify the GitHub PR path

Authentication proves the SRE worker can reach the repository with your existing account. Draft pull request support preserves the human-review boundary after a repair is proposed.

Before you run these checks, do you expect both parts of the Part 5 GitHub setup to pass?

  • Verify the authenticated account plus draft pull request support by running:
gh auth status
gh pr create --help | grep -- '--draft'

What do these checks prove?

  • gh auth status displays the active GitHub account plus its authentication state.
  • gh pr create --help | grep -- '--draft' searches the pull request help output for the draft option.

You'll see an active authenticated GitHub account. You'll also see the --draft option in the filtered help output.

Did a GitHub check fail?

Reuse the GitHub authentication method from Part 5 if the account check is inactive. Confirm that the same GitHub CLI installation is available in this terminal if the draft option is absent.

Help me restore the GitHub PR path.

Your recovery toolchain is ready to delegate investigations through the SRE profile while keeping publication behind a draft pull request. Next, you'll trigger a real TaskFlow incident and watch the existing workflow stop at triage.

Trigger the Triage Gap

Your recovery toolchain is ready. The existing TaskFlow monitor can already detect a missing document.

This step exposes where the older workflow stops. A controlled GitHub incident lets you compare detection with the durable Hermes Agent handoff.

In this step, get ready to:
  • Reproduce the missing-document incident on the TaskFlow default branch.
  • Run the manual health check plus the scheduled detection path.
  • Inspect the newest incident to locate the triage boundary.
Set up a repeatable failure condition

The ARCHITECTURE.md file is the known health-check target from Part 5. Removing it gives both detection paths the same failure to observe.

Deleting a file from the default branch can feel uncomfortable. This conditional keeps the drill repeatable because it removes the document only when the file currently exists.

  • Remove ARCHITECTURE.md only when it exists by running this conditional in the terminal from the previous step:
if gh api "repos/$TASKFLOW_REPO/contents/ARCHITECTURE.md" --silent; then
  FILE_SHA=$(gh api "repos/$TASKFLOW_REPO/contents/ARCHITECTURE.md" --jq '.sha')
  gh api --method DELETE "repos/$TASKFLOW_REPO/contents/ARCHITECTURE.md" \
    -f message='test: remove architecture doc for self-healing drill' \
    -f sha="$FILE_SHA"
else
  echo "ARCHITECTURE.md is already missing; continuing with the existing incident."
fi

What does this conditional do?

  • The first gh api request checks whether ARCHITECTURE.md currently exists.
  • The FILE_SHA value identifies the exact file version that GitHub must delete.
  • The deletion request runs only when the file exists.
  • The other path preserves an incident that is already active.

You will see a deletion response when the document existed. An existing incident produces the explicit already-missing message instead.

GitHub rejected the request?

  • Confirm that TASKFLOW_REPO still contains your TaskFlow owner and repository.
  • Confirm that your authenticated GitHub account has write access to that repository.

Ask for help with the repository request:

Run both detection paths

The local Bash health check proves that detection works immediately. The cron job proves that the same incident reaches the existing SRE triage flow.

Before you run the health check, do you expect it to report a healthy repository or a missing document?

  • Test the incident with the local health-check script by running:
bash ~/.hermes/scripts/taskflow-healthcheck.sh

What should you see?

The script should report that ARCHITECTURE.md is missing. This proves the controlled incident is visible to the detector.

🙋‍♀️ Health check reports a healthy repository?

  • Confirm that the script is checking the repository stored in TASKFLOW_REPO.
  • Repeat the failure-condition command if the document was restored after the earlier check.

Ask for help tracing the health-check result:

  • Find the scheduled health-check job by running:
hermes cron list

What does this command show?

The command lists the cron jobs managed by Hermes. Find the entry named taskflow-healthcheck so you can target the correct scheduled workflow.

  • Record the ID beside taskflow-healthcheck here: taskflow-healthcheck job ID.

The job may wait briefly for the next scheduler tick. That short pause is expected.

  • Trigger the scheduled health-check workflow by running:
hermes cron run [[HEALTHCHECK_JOB_ID="taskflow-healthcheck job ID"]]

What does this run prove?

Hermes queues the existing health-check job for its next scheduler tick. The job passes the detected incident into the SRE triage workflow.

🙋‍♀️ Scheduled workflow did not start?

  • Confirm that you copied the ID from the taskflow-healthcheck entry.
  • Return to the gateway status check from the previous step if the scheduler does not respond.

Ask for help tracing the scheduled run:

Inspect the triage-only handoff

A Kanban incident keeps the SRE result available after the worker finishes. Its contents reveal how far the existing workflow progressed.

  • List the incidents assigned to the SRE profile by running:
hermes kanban list --assignee sre

What does this list show?

The list shows durable tasks assigned to the sre profile. The newest incident should correspond to the missing TaskFlow document.

  • Record the newest incident task ID here: newest incident task ID.

Before you open the incident, do you expect to find a diagnosis alone or a completed repository repair?

  • Inspect the newest incident card by running:
hermes kanban show [[INCIDENT_TASK_ID="newest incident task ID"]]

Where does the workflow stop?

The card should explain that ARCHITECTURE.md is missing. Its triage may also explain the likely cause or impact.

The card should contain no repair branch, committed repair, or draft pull request URL. You have reached the intended triage gap.

🙋‍♀️ Newest incident is not listed?

  • Allow the scheduled worker a short moment to create the incident.
  • Repeat the Kanban list command above to refresh the assigned tasks.

Ask for help locating the incident:

You found the exact limit in the existing workflow. Next, you will give the SRE a guarded remediation skill that can investigate the incident before proposing a reviewable repair.

Create the Remediation Skill

The triage run now identifies the missing TaskFlow document. It still has no repeatable way to investigate or prepare a reviewable repair.

This step gives the SRE profile a reusable Hermes Agent skill. Its protocol uses parallel read-only investigations before one parent worker prepares a validated draft pull request on GitHub.

In this step, get ready to:
  • Clone the broken TaskFlow repository into a disposable workspace.
  • Create the guarded incident-remediation skill.
  • Confirm the SRE profile discovers the new skill.
Clone the broken repository

A disposable Git clone gives the remediation worker an isolated place to investigate the incident. Your normal development checkout stays outside the automated repair path.

  • Create the disposable clone and print its branch status by running these commands:
gh repo clone "$TASKFLOW_REPO" "$TASKFLOW_DIR"
git -C "$TASKFLOW_DIR" status --short --branch

What do these commands do?

  • The gh command copies TaskFlow into the disposable path held by TASKFLOW_DIR.
  • The git command prints the current branch plus any working-tree changes.

You'll see the clone complete. The status output shows the default branch header with no changed-file lines beneath it.

Did the clone stop?

  • Set TASKFLOW_DIR to a new empty directory if the current destination already contains files.
  • Confirm your authenticated GitHub account can read the TaskFlow repository if the clone cannot access it.

Help me diagnose the failed TaskFlow clone.

Create the guarded skill file

The profile-local SKILL.md file turns safe remediation into a reusable protocol. Its frontmatter controls discovery while its procedure defines investigation ownership and publication limits.

A quoted heredoc delimiter preserves the skill text exactly as written. The terminal waits for each section until you enter the closing marker.

  • Start the skill file in its profile directory by running these commands:
mkdir -p ~/.hermes/profiles/sre/skills/incident-remediation
cat > ~/.hermes/profiles/sre/skills/incident-remediation/SKILL.md <<'EOF'

What does this setup do?

  • The first command creates the profile-local directory for incident-remediation.
  • The second command starts writing SKILL.md while preserving literal symbols inside the skill.
  • Paste the skill identity and guardrails into the waiting terminal:
---
name: incident-remediation
description: Investigate TaskFlow incidents and prepare safe draft PRs
version: 1.0.0
platforms: [linux]
metadata:
  hermes:
    tags: [devops, incident-response, github]
    category: devops
    requires_toolsets: [terminal, file, delegation]
---

# Incident Remediation

## When to Use

Use this skill for a confirmed TaskFlow repository incident that needs investigation and a reviewable repair.

## Guardrails

- Treat every delegated investigation as read-only.
- Never commit to or push the repository default branch.
- Exactly one agent, the parent worker, owns the remediation decision and file edits.
- Open a draft pull request only after every required validation passes.
- Never merge a pull request.

## Procedure

1. Read the assigned incident with `kanban_show()` and move into the supplied workspace.
2. Run `git status --porcelain`. If the workspace is not clean, call `kanban_block(reason="Workspace is not clean; refusing autonomous remediation.")` and stop.

How do the guardrails work?

  • Version 1.0.0 activates only on Linux with the required SRE toolsets.
  • The parent worker remains the sole owner of repository edits.
  • The publication boundary ends at a draft pull request.
  • Paste the investigation and validation procedure beneath the previous section:
3. Launch one parallel investigation batch:

```text
delegate_task(tasks=[
  {
    "goal": "Identify the root cause of the missing TaskFlow architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Inspect Git history and report the deletion commit, the last trustworthy version, and the exact recovery source. Do not edit files."
  },
  {
    "goal": "Assess the impact of the missing TaskFlow architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Find references to the file, explain what workflows or readers are affected, and report any related repository damage. Do not edit files."
  },
  {
    "goal": "Design a minimal validation plan for restoring the architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Identify a trustworthy historical source and define checks that prove a one-file restoration is non-empty, scoped, and free of whitespace or conflict-marker errors. Do not edit files."
  }
])
```

4. Compare the three summaries. If they do not support one trustworthy historical version or reveal broader damage, call `kanban_block(reason="Investigation did not produce one safe recovery source; human review required.")` and stop.
5. Create the repair branch with `git switch -c incident/restore-architecture`. Recover only `ARCHITECTURE.md` from the agreed historical source. Do not modify unrelated files.
6. Stage and validate the repair:

```bash
test -s ARCHITECTURE.md
git add ARCHITECTURE.md
git diff --cached --check
git diff --cached -- ARCHITECTURE.md
```

How does parallel investigation stay safe?

  • The three delegate_task entries investigate root cause, impact, and recovery evidence in parallel.
  • Each child receives the incident context plus the read-only rule.
  • The parent compares all three findings before selecting one historical recovery source.
  • The staged file must be non-empty and free of whitespace or conflict-marker errors.
  • Paste the draft publication and durable handoff procedure next:
7. If any validation fails, call `kanban_block(reason="Validation failed; no commit, push, or pull request was created.")` and stop.
8. Commit, push, and open a draft pull request:

```bash
git commit -m "fix: restore architecture documentation"
git push -u origin incident/restore-architecture
gh pr create --draft \
  --title "Restore TaskFlow architecture documentation" \
  --body "Restores ARCHITECTURE.md from trustworthy repository history after the SRE health check detected its removal. Validation: the file is non-empty and git diff --cached --check passes. Human review is required before merge."
```

9. Capture the printed pull request URL and call `kanban_complete` with a concise summary and metadata containing:

```text
{
  "changed_files": ["ARCHITECTURE.md"],
  "verification": ["test -s ARCHITECTURE.md", "git diff --cached --check"],
  "pull_request": "the URL printed by gh pr create",
  "residual_risk": ["The default branch remains unhealthy until a human reviews and merges the draft PR"]
}
```

How does publication stay guarded?

  • A failed validation blocks every remote change.
  • A successful repair publishes only to the dedicated incident branch.
  • The pull request remains a draft for human review.
  • The Kanban handoff records the changed file, verification evidence, pull request URL, and residual risk.
  • Paste the final pitfalls and verification sections:
## Pitfalls

- Subagents start with fresh context. Every delegated task must repeat the repository incident and read-only rule.
- Parallel agents must investigate, not edit. Only the parent worker changes the repository.
- A clean validation result does not authorize a merge.
- If the branch already exists, block for human review instead of resetting or force-pushing it.

## Verification

The Kanban task is complete only when its handoff includes the restored file, validation evidence, and a draft PR URL. The default branch must remain unchanged until a human merges the PR.

What does the final section enforce?

  • The pitfalls block prevents competing edits, unsafe branch reuse, and autonomous merges.
  • The verification block defines the evidence required for a completed incident handoff.
  • Finish the heredoc by entering this marker on its own line:
EOF

What does this marker do?

The closing marker ends the heredoc. Bash saves every preceding line to the profile-local skill file.

The skill file now contains the guarded remediation protocol. Its draft-only publication rule keeps the default branch behind human review.

Did the heredoc close early?

  • Compare the opening delimiter with the quoted EOF marker shown above.
  • Confirm the closing EOF appears alone on its line.
  • Repeat the file-writing sequence if the terminal returned before you pasted every section.

Help me repair my incomplete SKILL.md heredoc safely.

✔️ Awesome, I've got everything!

Your skill file is ready for the discovery check.

ⓧ I'd like to double check the full code

---
name: incident-remediation
description: Investigate TaskFlow incidents and prepare safe draft PRs
version: 1.0.0
platforms: [linux]
metadata:
  hermes:
    tags: [devops, incident-response, github]
    category: devops
    requires_toolsets: [terminal, file, delegation]
---

# Incident Remediation

## When to Use

Use this skill for a confirmed TaskFlow repository incident that needs investigation and a reviewable repair.

## Guardrails

- Treat every delegated investigation as read-only.
- Never commit to or push the repository default branch.
- Exactly one agent, the parent worker, owns the remediation decision and file edits.
- Open a draft pull request only after every required validation passes.
- Never merge a pull request.

## Procedure

1. Read the assigned incident with `kanban_show()` and move into the supplied workspace.
2. Run `git status --porcelain`. If the workspace is not clean, call `kanban_block(reason="Workspace is not clean; refusing autonomous remediation.")` and stop.
3. Launch one parallel investigation batch:

```text
delegate_task(tasks=[
  {
    "goal": "Identify the root cause of the missing TaskFlow architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Inspect Git history and report the deletion commit, the last trustworthy version, and the exact recovery source. Do not edit files."
  },
  {
    "goal": "Assess the impact of the missing TaskFlow architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Find references to the file, explain what workflows or readers are affected, and report any related repository damage. Do not edit files."
  },
  {
    "goal": "Design a minimal validation plan for restoring the architecture document",
    "context": "ARCHITECTURE.md is missing from the current TaskFlow repository. Work read-only. Identify a trustworthy historical source and define checks that prove a one-file restoration is non-empty, scoped, and free of whitespace or conflict-marker errors. Do not edit files."
  }
])
```

4. Compare the three summaries. If they do not support one trustworthy historical version or reveal broader damage, call `kanban_block(reason="Investigation did not produce one safe recovery source; human review required.")` and stop.
5. Create the repair branch with `git switch -c incident/restore-architecture`. Recover only `ARCHITECTURE.md` from the agreed historical source. Do not modify unrelated files.
6. Stage and validate the repair:

```bash
test -s ARCHITECTURE.md
git add ARCHITECTURE.md
git diff --cached --check
git diff --cached -- ARCHITECTURE.md
```

7. If any validation fails, call `kanban_block(reason="Validation failed; no commit, push, or pull request was created.")` and stop.
8. Commit, push, and open a draft pull request:

```bash
git commit -m "fix: restore architecture documentation"
git push -u origin incident/restore-architecture
gh pr create --draft \
  --title "Restore TaskFlow architecture documentation" \
  --body "Restores ARCHITECTURE.md from trustworthy repository history after the SRE health check detected its removal. Validation: the file is non-empty and git diff --cached --check passes. Human review is required before merge."
```

9. Capture the printed pull request URL and call `kanban_complete` with a concise summary and metadata containing:

```text
{
  "changed_files": ["ARCHITECTURE.md"],
  "verification": ["test -s ARCHITECTURE.md", "git diff --cached --check"],
  "pull_request": "the URL printed by gh pr create",
  "residual_risk": ["The default branch remains unhealthy until a human reviews and merges the draft PR"]
}
```

## Pitfalls

- Subagents start with fresh context. Every delegated task must repeat the repository incident and read-only rule.
- Parallel agents must investigate, not edit. Only the parent worker changes the repository.
- A clean validation result does not authorize a merge.
- If the branch already exists, block for human review instead of resetting or force-pushing it.

## Verification

The Kanban task is complete only when its handoff includes the restored file, validation evidence, and a draft PR URL. The default branch must remain unchanged until a human merges the PR.

How does the complete skill fit together?

The frontmatter makes the skill discoverable by the SRE profile. The procedure turns a durable incident into a guarded investigation and repair plan.

Every successful path ends with evidence in a draft pull request. Every unsafe path ends with a blocked task for human review.

Confirm Hermes discovers the skill

Skill discovery proves that the file path and frontmatter are valid. The SRE profile can only load the remediation protocol after this check succeeds.

Before you run the check, do you expect the SRE profile to list the skill by its frontmatter name?

  • Check the SRE profile's installed skills by running this command:
sre skills list

What should I see?

You should find incident-remediation in the SRE skill list. That result proves the profile can discover version 1.0.0 from the expected directory.

🙋‍♀️ Is the skill missing?

  • Confirm the file exists at ~/.hermes/profiles/sre/skills/incident-remediation/SKILL.md.
  • Compare the YAML frontmatter with the complete file above.
  • Check that the opening and closing frontmatter markers each contain exactly three hyphens.

Help me find why the SRE profile cannot discover this skill.

Your SRE profile now has a discoverable remediation protocol with parallel investigation and a human-review boundary. Next up, you'll dispatch the durable incident task and watch the guarded recovery run.

Dispatch the Self-Healing Run

Your SRE profile now has a guarded remediation skill. The missing ARCHITECTURE.md still needs a durable path from diagnosis to review.

A Hermes Agent Kanban task keeps the incident work outside an interactive chat. The parent worker uses three short-lived subagents for parallel evidence gathering. It remains the only editor.

In this step, get ready to:
  • Create a durable remediation task in the disposable TaskFlow clone.
  • Watch three read-only investigations feed one parent worker.
  • Inspect the completed handoff containing validation evidence plus a draft GitHub pull request URL.

Why Kanban With Delegation?

Kanban keeps the incident resumable outside an interactive chat. Delegation lets the worker gather three bounded reports in parallel.

Three independent investigator cards would add routing overhead. One parent task keeps the evidence together under a single decision owner.

Set the task boundaries

The task binds the existing clone to the SRE worker. It also loads the remediation skill with a bounded runtime.

  • Return to the terminal from earlier.
  • Submit the durable remediation job by running this command:
hermes kanban create "Restore TaskFlow architecture document" \
  --body "Restore ARCHITECTURE.md in $TASKFLOW_REPO from trustworthy repository history. Use branch incident/restore-architecture. Investigate first, validate the staged change, open a draft PR, never merge, and record the PR URL plus evidence in the task handoff." \
  --assignee sre \
  --workspace "dir:$TASKFLOW_DIR" \
  --skill incident-remediation \
  --max-runtime 30m \
  --max-retries 1

What Does This Command Set Up?

  • The --assignee sre option gives one parent worker ownership of the task.
  • The --workspace "dir:$TASKFLOW_DIR" option scopes repository work to the disposable clone.
  • The --skill incident-remediation option loads the investigation protocol plus its publication guardrails.
  • The --max-runtime 30m option bounds one attempt.
  • The --max-retries 1 option limits automatic retries.

The command prints a new task ID. That ID becomes the handle for the durable run.

  • Record the new task ID here: your new remediation task ID.
  • Use the recorded value in place of INCIDENT_TASK_ID in every command below.

Task Not Created?

  • Retry the command in the terminal from Step 1.
  • Confirm that TASKFLOW_DIR still names the clean disposable clone.
  • Return to the earlier gateway checks if Hermes cannot submit the task.

Help me diagnose the task creation problem.

Watch the parallel investigation

The live tail lets you watch the parent gather three reports before making one recovery decision. Expect the run to take several minutes while the model calls and repository checks complete.

  • Replace INCIDENT_TASK_ID with the task ID you recorded.
  • Follow the worker transcript by running this command:
hermes kanban tail INCIDENT_TASK_ID

What Should the Transcript Prove?

  • The worker loads the remediation task plus its installed skill.
  • One delegate_task batch launches the read-only root-cause investigation.
  • The same batch launches the read-only impact investigation.
  • The same batch launches the read-only validation-plan investigation.
  • The parent worker compares all three reports before choosing a recovery source.
  • The parent worker restores ARCHITECTURE.md on incident/restore-architecture.
  • The parent validates the staged one-file change.
  • The parent opens a draft pull request after the checks pass.
  • Press Ctrl+C after the task reaches a terminal state.

The durable task keeps its transcript after the live stream closes. You can return to that record when you need to audit a completed action.

  • Use the same recorded value in place of INCIDENT_TASK_ID.
  • Recover the finished worker transcript by running this command if the live tail has already closed:
hermes kanban log INCIDENT_TASK_ID

What Does the Saved Log Show?

The saved transcript preserves the worker's investigations plus its repository actions. It gives you an audit trail after the live stream closes.

🙋‍♀️ Worker Stopped Early?

  • Inspect the saved transcript for the last completed action.
  • Preserve the disposable workspace if the worker records a block.
  • Review the block reason before deciding whether the evidence supports another attempt.

Help me understand why the remediation worker stopped.

Inspect the durable handoff

The durable handoff is where the worker leaves its auditable record. This record connects the investigation to the proposed repair.

Before you inspect the handoff, do you expect to see three editing agents or one editor supported by three investigators?

  • Replace INCIDENT_TASK_ID with the task ID you recorded.
  • Inspect the completed Kanban handoff by running this command:
hermes kanban show INCIDENT_TASK_ID

What Should You See?

  • The task status is done.
  • The summary includes one finding from each of the three investigations.
  • The changed_files metadata names ARCHITECTURE.md.
  • The verification metadata records the non-empty-file check.
  • The same field records the staged-diff check.
  • The pull_request metadata contains the draft pull request URL.
  • The residual_risk metadata says the default branch remains unhealthy until human review and merge.

You have a complete recovery loop now. Your SRE worker produced a validated draft repair while the merge decision remains with a human.

Task Not Done?

A blocked task is a valid safety outcome when the evidence does not support a trustworthy repair. The guardrail protects the repository from uncertain publication.

  • Return to the live tail if the task is still running.
  • Preserve the workspace if the task is blocked.
  • Review the recorded reason before deciding on another run.

Help me diagnose the incomplete remediation task.

Your durable handoff now records the repair plus its remaining risk. Next, you'll verify that GitHub kept the fix on the draft pull request branch while the default branch stayed unchanged.

Verify the Safety Boundary

Your remediation worker restored ARCHITECTURE.md on incident/restore-architecture. It also opened a draft pull request through GitHub.

The repair must remain reviewable. The default branch must stay untouched until a human merges the draft pull request.

In this step, get ready to:
  • Confirm the pull request is open in draft state.
  • Compare the pull request with the durable Kanban handoff.
  • Prove the repair exists only on the remediation branch.
Confirm the pull request is a draft

A draft pull request creates a review gate around the proposed repair. The pull request state shows whether that gate is still active.

  • Return to the terminal from earlier.
  • Check the remediation pull request from the disposable clone by running these commands:
cd "$TASKFLOW_DIR"
gh pr list --head "incident/restore-architecture" \
  --json number,title,isDraft,state,url

What Does This Check Prove?

  • The TASKFLOW_DIR variable sends the check to your disposable clone.
  • The --head filter limits the result to the remediation branch.
  • The --json fields expose the review state plus the pull request URL.

You should see one entry with isDraft set to true. Its state should be OPEN.

The output should also include the pull request number plus its URL.

That is your first safety check complete. The repair is visibly parked behind GitHub's review gate.

Can't Find the Draft Pull Request?

  • Confirm TASKFLOW_DIR still points to $HOME/taskflow-self-healing.
  • Confirm the remote branch is named incident/restore-architecture.

Ask for help if the branch exists but the pull request is missing: Help me diagnose the missing draft pull request.

Inspect the human-review evidence

Reviewability depends on evidence that another person can inspect. The pull request description and durable task handoff should tell the same recovery story.

  • Replace INCIDENT_TASK_ID in the second command with the remediation task ID from the previous step.
  • Compare the pull request with its Kanban handoff by running these commands:
gh pr view incident/restore-architecture
hermes kanban show INCIDENT_TASK_ID

What Should the Records Contain?

  • The first command displays the pull request associated with the remediation branch.
  • The second command displays the durable incident summary plus its handoff metadata.
  • Together, the records provide the evidence a human needs before deciding whether to merge.

You should see ARCHITECTURE.md named in the recovery records. You should also see matching validation evidence.

Both records should preserve the requirement for human review. You now have an auditable explanation of the proposed repair.

Does the Evidence Look Incomplete?

  • Confirm you substituted the remediation task ID for INCIDENT_TASK_ID.
  • Confirm the Kanban task status is done.
  • Compare the changed file against the pull request description.

Ask for help if the records disagree: Help me compare the pull request with the Kanban handoff.

Prove the branch boundary

The GitHub Contents API can check the same file on two different branch references. This gives you direct evidence that the worker proposed a repair without changing the default branch.

  • Predict which branch contains the repair.
  • Prove the branch boundary by running these checks:
gh api "repos/$TASKFLOW_REPO/contents/ARCHITECTURE.md?ref=incident/restore-architecture" --silent \
  && echo "Repair exists on the PR branch."

if gh api "repos/$TASKFLOW_REPO/contents/ARCHITECTURE.md" --silent; then
  echo "The default branch already contains the file."
else
  echo "The default branch is unchanged; the repair is still waiting in the draft PR."
fi

How Does This Prove the Boundary?

  • The first API request selects incident/restore-architecture as its branch reference.
  • A successful first request proves that ARCHITECTURE.md exists on the pull request branch.
  • The second API request omits a branch reference. GitHub therefore checks the repository's default branch.

The first check should confirm the repair exists on the pull request branch. The second check should report that the default branch is unchanged.

That is the safety boundary proven. The agent prepared a reviewable recovery without bypassing human approval.

Did the Branch Check Surprise You?

  • Confirm TASKFLOW_REPO contains your TaskFlow owner and repository value.
  • Confirm the remediation branch still exists on GitHub.
  • Check whether someone already merged the draft pull request.

Ask for help if the branch results do not match the pull request state: Help me diagnose the branch boundary results.

Secret mission

Add a Failed-Validation Rollback Gate

Upgrade the remediation skill so a failed validation preserves its evidence and blocks every publication action. The handoff will recommend a human-reviewed recovery path without changing or deleting the failed workspace.

Clean Up Your Resources

🗑 Before you go

The TaskFlow cron job can continue to trigger your existing SRE workflow while the Hermes Agent gateway runs. Those runs may consume paid model tokens under your provider configuration.

Nice Work!

Nice Work!

Mission complete. You built an auditable recovery workflow with Hermes Agent. Your workflow now turns a missing TaskFlow document into a validated draft repair.

What you learned:

  • Built a reusable incident-remediation skill that coordinates three read-only investigations in one parallel batch. Kept the parent worker as the single owner of every repository edit.
  • Restored ARCHITECTURE.md on incident/restore-architecture. Validated the staged change. Opened a draft pull request on GitHub.
  • Recorded a structured Kanban handoff for human review. Proved the default branch remained behind the human-review boundary.
  • Secret Mission: Added a failed-validation protocol that preserves the failed workspace for human review. It blocks publication while returning a non-destructive rollback recommendation.

Ready to quiz yourself?