ucsandman/claude-skills / dashclaw-governance
dashclaw-governance
VerifiedApply DashClaw governance: guard decisions, approvals, action recording, and agent session lifecycle.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| references/governance-patterns.md | markdown | 6.9 KB |
references/governance-patterns.md
View on GitHub# DashClaw Governance Patterns
Concrete tool call sequences for common governance scenarios. Load this reference when
you need implementation examples.
## Guard-Before-Invoke Pattern
The standard pattern for governed capability invocations:
```
Step 1: Guard the action
dashclaw_guard(action_type="api_call", declared_goal="Send Slack notification",
risk_score=45, systems_touched=["slack"])
Step 2: Check the decision
If "allow" or "warn" → proceed to step 3
If "block" → stop, inform user
If "require_approval" → go to Approval Wait Pattern
Step 3: Invoke the capability
dashclaw_invoke(capability_id="cap_slack_notify",
declared_goal="Send deployment notification to #ops",
payload={"channel": "#ops", "message": "Deployed v2.3.1"})
Step 4: dashclaw_invoke records automatically. Do NOT call dashclaw_record again
for the same operation — that would create a second audit row for one action.
Only emit a separate dashclaw_record when summarizing a multi-call workflow as
one parent action.
```
## Approval Wait Pattern
When a guard decision requires human approval:
```
Step 1: Guard returns require_approval
result = dashclaw_guard(action_type="deploy", declared_goal="Deploy to production",
risk_score=85, systems_touched=["production"])
result.decision == "require_approval"
Step 2: Record the pending action
dashclaw_record(action_type="deploy", declared_goal="Deploy v2.3.1 to production",
status="pending_approval", risk_score=85,
reasoning="All tests passed, staging verified")
Step 3: Inform the user
"This deployment requires human approval. An operator can approve or deny
this action in DashClaw Mission Control."
Step 4: Wait for the decision
dashclaw_wait_for_approval(action_id="act_xxx")
Step 5: Handle the result. The response shape is { approved, action, timed_out }.
- approved == true → proceed with the deploy, then PATCH the outcome
(status="completed", optional tokens_in/tokens_out/model)
- timed_out == true → operator never responded inside the configured timeout
(default 300s; override with timeout_seconds). Either
re-request, fall back, or stop with an explicit log.
- approved == false (timed_out == false) → operator denied OR action moved to
a non-completed terminal state.
Read action.error_message for the
operator's reason, then stop.
## Token + Cost Reporting Pattern
For any action driven by an LLM call, attach token usage so the dashboard can
compute spend. Cost is derived server-side from the configured pricing table —
omit cost_estimate unless you have an authoritative number from the provider.
```
Step 1: Run the LLM call
response = anthropic.messages.create(model="claude-opus-4-6", ...)
Step 2: Record (or PATCH) with token usage
dashclaw_record(
action_type="research",
declared_goal="Summarize Q3 incident report",
status="completed",
output_summary=response.content[0].text[:500],
tokens_in=response.usage.input_tokens,
tokens_out=response.usage.output_tokens,
model="claude-opus-4-6",
# cost_estimate intentionally omitted — server derives from billing.js
)
# If you only learn token counts after the action was already recorded
# (e.g. a Stop hook, or streaming response), PATCH instead:
PATCH /api/actions/<action_id>
{ "tokens_in": ..., "tokens_out": ..., "model": "..." }
```
## Session Lifecycle Pattern
Clean session boundaries for long-running tasks:
```
Step 1: Start session
dashclaw_session_start(agent_id="research-agent", workspace="market-analysis")
→ session_id = "sess_xxx"
Step 2: Execute governed work
... (guard, act, record for each action) ...
Step 3: End session
dashclaw_session_end(session_id="sess_xxx", status="completed",
summary="Analyzed 5 market segments, produced comparison report")
```
## Multi-Step Task Pattern
Governing a sequence of dependent actions:
```
Step 1: Start session
dashclaw_session_start(agent_id="deploy-agent", workspace="release-v2.3.1")
Step 2: Guard the overall plan (low risk — just planning)
dashclaw_guard(action_type="planning", declared_goal="Plan v2.3.1 release",
risk_score=10)
Step 3: Run tests (moderate risk)
dashclaw_guard(action_type="test_execution", declared_goal="Run full test suite",
risk_score=35, systems_touched=["ci"])
... run tests ...
dashclaw_record(action_type="test_execution", status="completed",
output_summary="847/847 tests passed")
Step 4: Deploy to staging (high risk)
dashclaw_guard(action_type="deploy", declared_goal="Deploy to staging",
risk_score=70, systems_touched=["staging"])
dashclaw_invoke(capability_id="cap_deploy", payload={"env": "staging"})
Step 5: Deploy to production (very high risk — expect approval)
dashclaw_guard(action_type="deploy", declared_goal="Deploy to production",
risk_score=90, systems_touched=["production"])
→ require_approval → wait → approved
dashclaw_invoke(capability_id="cap_deploy", payload={"env": "production"})
Step 6: End session
dashclaw_session_end(session_id="sess_xxx", status="completed",
summary="Released v2.3.1: tests passed, staged, deployed to production")
```
## Error/Failure Recording Pattern
Always record failures — silent failures are governance gaps:
```
Step 1: Attempt the action
result = dashclaw_invoke(capability_id="cap_api", payload={...})
Step 2: Check for failure
If result.success == false:
dashclaw_record(action_type="api_call", declared_goal="Fetch user data",
status="failed", risk_score=40,
output_summary="HTTP 503: Service temporarily unavailable")
Step 3: Do NOT silently retry
If you want to retry, record the retry as a new action:
dashclaw_guard(action_type="api_call", declared_goal="Retry: Fetch user data",
risk_score=40)
dashclaw_invoke(capability_id="cap_api", payload={...})
```
## Discovery Pattern
Finding and using capabilities you haven't used before:
```
Step 1: List available capabilities
dashclaw_capabilities_list(search="slack")
→ [{id: "cap_slack_notify", name: "Slack Notifications", health: "healthy", risk: "medium"}]
Step 2: Check the capability's health
If health == "degraded" or "failing" → inform user, consider alternatives
Step 3: Guard the invocation
dashclaw_guard(action_type="api_call", declared_goal="Send Slack message",
risk_score=45)
Step 4: Invoke
dashclaw_invoke(capability_id="cap_slack_notify",
declared_goal="Notify team of completed analysis",
payload={"channel": "#team", "message": "Analysis complete"})
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |