Agent Skills: Deepwork Guardrail Management

Deepwork Guardrail Management

Manually manage the state.json.guardrails[] array for the active deepwork session. Guardrails are rendered into every subsequent teammate spawn as {{HARD_GUARDRAILS}}.

Arguments

The args string passed to this skill is one of:

• add [--source <src>] "<rule text>" — append a guardrail. --source defaults to "user"; override with values like "scope-boundary", "orchestrator", "incident" when the rule isn't a direct user-authored constraint.
• remove <index> — remove the guardrail at the given 0-based index (0-based to match state.json array order).
• replace <index> [--source <src>] "<rule text>" — overwrite the rule (and optionally the source) at 0-based index. Preserves the existing timestamp unless --source is supplied AND the existing source was a computed/auto source (incident, flag) — in which case the timestamp is refreshed to now() to reflect the re-attribution.
• list — show the current guardrails.

Flow

1. Use Glob to find active instance state:

Glob: ${CLAUDE_PROJECT_DIR:-$(pwd -P)}/.claude/deepwork/*/state.json

2. If no active session, report "No active deepwork session. Run /deepwork <goal> first."

3. If multiple instances exist, use AskUserQuestion to pick which one (show goal + instance_id for each).

4. Parse the args string into the subcommand and its argument. Common shapes:

   • add "no kill signals" (defaults to source: "user")
   • add --source scope-boundary "plan-only scope: no target-repo edits" (explicit source)
   • add no signals to host process (unquoted; everything after add is the rule)
   • remove 2
   • replace 3 "new rule text" (preserves existing source)
   • replace 3 --source orchestrator "new rule text" (changes source)
   • list

   --source <value> is optional for add and replace. Valid source values (convention, not validated): user, incident, flag, scope-boundary, orchestrator, teammate. Any non-empty string is accepted.

5. Perform the action:

add [--source <src>] "<rule>"

Append a guardrail entry via the canonical writer:

STATE="${CLAUDE_PROJECT_DIR:-$(pwd -P)}/.claude/deepwork/<id>/state.json"
SOURCE="${SOURCE_OVERRIDE:-user}"  # parsed from --source, default "user"
bash "${CLAUDE_PLUGIN_ROOT}/scripts/state-transition.sh" \
  --state-file "$STATE" guardrail_add \
  --statement "<rule>" \
  --source "$SOURCE"

Report: "Added guardrail [source: <src>]: <rule>. Applies to all subsequent teammate spawns. Existing teammates don't see it until you re-spawn or DM them."

remove <index>

Remove the guardrail at 0-based index via the canonical writer:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/state-transition.sh" \
  --state-file "$STATE" guardrail_remove --index <index>

Report which rule was removed, or error if the index was out of range.

replace <index> [--source <src>] "<rule>"

Overwrite the rule at 0-based index via the canonical writer. Attribution is preserved by default — if --source is not supplied, the entry's existing source field is kept. If --source is supplied, the timestamp is refreshed to reflect re-attribution.

# SOURCE_OVERRIDE is empty if --source was not supplied
bash "${CLAUDE_PLUGIN_ROOT}/scripts/state-transition.sh" \
  --state-file "$STATE" guardrail_replace \
  --index <index> \
  --statement "<rule>" \
  $( [[ -n "${SOURCE_OVERRIDE:-}" ]] && echo "--source $SOURCE_OVERRIDE" )

Report: "Replaced guardrail [<index>] — source: <src>, new rule: <rule>."

list

Read state.json.guardrails[] and print:

Guardrails for instance <id>:

0. <rule>  [source: <source>, <timestamp>]
1. <rule>  [source: <source>, <timestamp>]
...

If empty: "No guardrails currently set."

Notes

• Auto-accumulated guardrails (from hooks/incident-detector.sh) have source: "incident" with an incident_ref field. User-added ones have source: "user".
• Removing an auto-accumulated guardrail is fine — the user may judge the incident doesn't actually warrant a persistent rule.
• Flag-seeded guardrails (from --guardrail at invocation) have source: "flag".