Use when operating or debugging a repo-local Hermes + graphify + GSD autonomous runtime, especially when checking writer ownership, execution-surface eligibility, handoff/blocked state, stale cron or lease metadata, and whether the main project repo is still the only recommended writer surface.
Use when operating or debugging a repo-local Hermes + graphify + GSD autonomous runtime, especially when checking writer ownership, execution-surface eligibility, handoff/blocked state, stale cron or lease metadata, and whether the main project repo is still the only recommended writer surface.
Do not use this skill to bootstrap the workflow from scratch. Use the companion integration skills first.
Core Operating Model
Preferred steady state:
main project repo = primary writer execution surface
extra worktrees are read-only analysis areas or temporary experiments unless explicitly promoted
operator commands are the fact source, not intuition
First Checks
Always start with the repo-local operator surface:
./scripts/ai-workflow.sh doctor
./scripts/ai-workflow.sh auto-execution-surface-show
./scripts/ai-workflow.sh auto-runner-show
./scripts/ai-workflow.sh auto-progress
./scripts/ai-workflow.sh auto-workflow-state-show
Also check the graphify runtime baseline when diagnosing graph or planning drift:
graphify --help | sed -n '1,40p'
python3 -m pip show graphifyy 2>/dev/null | sed -n '1,20p'
Expected baseline as of 2026-04-24:
graphifyy should be 0.5.0 or newer
required graph outputs are still graphify-out/graph.json and graphify-out/GRAPH_REPORT.md
missing manifest.json is not a runtime failure
transient .graphify_chunk_*.json files can indicate an interrupted Codex semantic extraction and should be treated as evidence, not immediately deleted
Interpretation:
means the repo looks complete enough to participate
execution_surface: ready
writer_eligible=yes means the repo passes the execution-surface check
primary_root_match=yes means the repo matches the configured primary root
writer_recommended=yes means the repo is the intended writer surface
If writer_recommended=no, do not install cron or bind runtime metadata here.
Runtime Triage Order
1. Check the current writer contract
Read:
execution-surface status
global runner state
planning mirror
effective state
current lease
Use auto-runner-show and auto-progress before any mutation.
2. Distinguish live lock from stale metadata
A common trap is stale files saying running after the process is already gone.
Check both:
operator views (auto-runner-show, auto-progress)
actual lock/process reality
If needed, verify directly with shell tools such as:
blocked = could not proceed right now (busy, refusal, conflict)
handoff = intentionally waiting for human or external input
When handoff is active, prefer preserving the structured payload:
reason
detail
requested_input
resume_condition
next_action
Do not clear handoff casually if the required input has not actually arrived.
Prefer machine-readable resume_condition probes when the runtime should recover automatically on the next cron/timer cycle.
Planning Mirror
Use:
./scripts/ai-workflow.sh auto-workflow-state-show
Purpose:
gives .planning / GSD a machine-readable mirror of runtime state
should align with global state and effective state
If planning mirror says one thing and global runtime says another, note the divergence explicitly and reconcile only after checking the live process/lock situation.
Common Failure Patterns
Pattern 1: Empty Hermes cron, but writer still active
Cause:
system crontab still contains an old runtime entry
Action:
inspect crontab -l
remove the stale cron tag
stop the stale trigger process
reconcile state/lease
Pattern 2: State says running, but no visible process
Cause:
stale metadata
Action:
verify kernel/user-space lock reality
if lock is actually free, rewrite state/lease to inactive with an operator reason
Pattern 3: Sandbox still appears as writer after policy changed
Cause:
historical cron or stale lease
Action:
prove whether sandbox is still truly running
if not, clear the stale metadata
if yes, remove the cron/process first
Pattern 4: Current repo passes execution-surface check but still should not write
Cause:
it is not the configured primary root
Action:
check primary_root_match
only allow runtime binding / cron install on writer_recommended=yes
Verification Checklist
Before claiming runtime/operator work is done, verify:
./scripts/ai-workflow.sh doctor
./scripts/ai-workflow.sh auto-execution-surface-show
./scripts/ai-workflow.sh auto-runner-show
./scripts/ai-workflow.sh auto-progress
hermes cron list --all
crontab -l
And make sure all of these are coherent:
current repo shows writer_recommended=yes if it is meant to write
writer state reflects reality
global state file and effective state agree, or divergence is explicitly explained
planning mirror is not silently stale
no old sandbox/worktree cron remains active
Common Mistakes
Treating operator JSON as more trustworthy than live process reality
stale metadata is common; verify real processes and locks
Checking Hermes cron only
system cron may still be active
Clearing lease/state before removing the stale scheduler source
the next cron tick will recreate the bad state
Assuming a sandbox should stay canonical forever
if the main project repo is now the writer surface, remove the stale sandbox runtime instead of working around it
Forgetting to re-check operator views after cleanup
always rerun auto-runner-show and auto-progress
Minimal Success Definition
A good operator outcome means:
the intended main repo reports writer_recommended=yes
stale sandbox/worktree writers are gone
current writer state is accurate
state/lease/planning mirror are coherent enough for the next development step
