Use when integrating Hermes Agent, graphify, and GSD into a local development workflow without modifying upstream repositories, especially when the user wants upgrade-safe wrappers, project-level workflow scripts, graph-aware planning, and a reusable setup that survives future upstream updates.
Use when integrating Hermes Agent, graphify, and GSD into a local development workflow without modifying upstream repositories, especially when the user wants upgrade-safe wrappers, project-level workflow scripts, graph-aware planning, and a reusable setup that survives future upstream updates.
Use this skill to build an upgrade-safe local AI development workflow that combines:
Hermes Agent for orchestration, memory, and execution
graphify for codebase graph recall and low-cost refresh
GSD for planning, phase management, and execution cadence
If the repo already has this workflow and the task is now about runtime diagnosis, writer ownership, stale cron/state/lease cleanup, or handoff/operator recovery, switch to hermes-graphify-gsd-runtime-operator.
Core rule: do not modify upstream Hermes, graphify, or GSD repository code unless the user explicitly wants to contribute upstream. Prefer thin wrappers, project-local scripts, and repo documentation.
Important prerequisite:
This skill assumes Hermes is already installed in an online-capable environment.
If hermes is missing, stop and ask the user to install Hermes first.
Do not auto-install Hermes from this skill.
However, on first-time bootstrap, this skill should automatically install or upgrade the latest graphify and GSD, then configure them globally.
When to Use
Use this skill when the user asks for any of these:
"把 Hermes + graphify + GSD 接起来"
non-intrusive integration
upgrade-safe local AI coding workflow
reusable project bootstrap for graph-aware planning
wrappers around Hermes / graphify / GSD instead of patching upstream
project-level workflow entrypoints like ai-workflow.sh
Do not use this skill when the user wants to directly change Hermes, graphify, or GSD upstream source behavior. In that case, work in the relevant upstream repo instead.
Design Principles
Non-intrusive first
Do not patch Hermes upstream repo for local workflow glue
Do not patch installed graphify package for convenience
Do not patch GSD installer/source just to fit one project
Depend on stable entrypoints
Prefer these interfaces:
hermes
python -m graphify
node <get-shit-done>/sdk/dist/cli.js
Keep adaptation thin
Allowed adaptation layers:
shell wrappers in ~/.local/bin/
repo-local scripts under scripts/
docs in README.md, AGENTS.md, docs/
local gitignored workflow state like .planning/ and graphify-out/
Make upgrade cost local
If upstream changes, update wrappers/templates first. Avoid spreading compatibility logic across many repos.
Recommended Architecture
Layer 1 — upstream tools
Hermes installation and config
graphify Python package / CLI entrypoint
GSD runtime and SDK installation
First-time bootstrap policy
When this skill is used on a fresh machine:
Check command -v hermes
If Hermes is missing, stop and instruct the user to install Hermes manually first
If Hermes exists, automatically install or upgrade graphify and GSD to latest stable upstream entrypoints
Configure graphify globally for Hermes
Configure GSD globally for the target runtime, defaulting to Codex unless the user specifies another runtime
graphify's current PyPI package name is graphifyy, while the CLI remains graphify
graphify 0.5+ adds video/audio handling through transcription (graphifyy[video] when needed) and Codex-specific chunk files; wrappers must not delete .graphify_chunk_*.json until semantic extraction has collected them
graphify 0.5+ still treats graphify-out/graph.json and graphify-out/GRAPH_REPORT.md as required outputs; manifest files are useful diagnostics, not a hard contract
graphify version warnings are global across installed platforms, not Hermes-only; if graphify --help still warns after updating Hermes, also check other installed platform copies such as ~/.claude/skills/graphify/.graphify_version and rerun graphify install --platform <platform> there
for GSD, --codex --global --sdk is the default global baseline for this workflow; choose another runtime only when the user explicitly wants it
if a repo also needs local .codex/ files, do a second repo-local install later during project integration
Layer 2 — local wrappers
Create thin wrappers when needed:
~/.local/bin/graphify
~/.local/bin/gsd-sdk
Purpose:
normalize invocation
discover interpreters/paths
avoid upstream edits
Layer 3 — project integration
Per repo, add:
scripts/graphify-sync.sh
optional scripts/ai-workflow.sh
AGENTS.md guidance
README.md workflow section
.gitignore entries for .planning/ and graphify-out/
Optional Layer 4 — autonomous continuation loop
When the user wants the repo to keep advancing with minimal manual prompting, add a repo-local auto-continue layer:
lightweight Git hooks for event triggers (post-commit, optionally post-merge)
a periodic reconciler (cron or systemd timer) that re-checks progress every N minutes
a single-runner lock to prevent concurrent agent executions
a project-level completion sentinel written only after full verification succeeds
evidence docs that record the final verification command and output
Recommended responsibilities:
hook: only enqueue or trigger; keep it lightweight
cron/timer: watchdog + periodic reconciliation; restart the runner if needed
runner: read planning/graph context, continue work, update docs, run focused verification, and only attempt final completion when the project is actually done
per-trigger loop: let one trigger run multiple internal passes before giving up, so the workflow does not stop after one small task when more scoped work remains
completion gate: a dedicated script that runs the full verification command and writes the sentinel/evidence only on success
When this workflow grows into an autonomous repo-local runtime, prefer these additional constraints by default:
main project repo = primary writer execution surface
do not assume a separate sandbox/worktree should be the canonical writer
treat extra worktrees as read-only analysis or temporary experiments unless they are rebuilt into a complete project environment and explicitly promoted
Recommended operator contract:
maintain a project-level writer lease, state file, handoff file, and planning mirror under a shared state dir
expose a repo-local doctor/operator surface such as:
also keep a machine-readable task board at .planning/task-board.json
also keep a machine-readable GSD lifecycle mirror at .planning/auto-gsd-next-state.json
sync that GSD lifecycle mirror into the broader runtime mirror so operator views and notifications share one coherent state model
if local GSD is installed under .codex/get-shit-done/, treat GSD workflow files as the lifecycle source of truth and use the task board as execution cache
the autonomous runner should prefer:
GSD phase truth (gsd-next, discuss / plan / execute / verify workflow docs when available)
in_progress task
highest-priority executable todo
documented fallback to REQUIREMENTS.md / ROADMAP.md only when the board is missing or stale
expose task-board operator commands for:
initialization
current/next task inspection
claiming the next task
status transitions (todo, in_progress, blocked, done, dropped)
appending notes and acceptance evidence
complete-if-ready evaluation before marking a task done
syncing the machine task board back into managed sections of STATE.md and ROADMAP.md
every task should ideally include:
id
title
status
priority
depends_on
acceptance
artifacts
blocked_by
last_updated
a strong default is: tasks should become done only through a lightweight completion gate that checks dependencies, acceptance evidence, and artifact existence
Trigger semantics note:
The default repo-local auto-continue loop described here is code-event driven + periodic reconciliation, not chat-turn driven.
A strong default is: one trigger may run multiple internal passes until completion is reached, a structured handoff becomes active, or the pass budget is exhausted.
A normal assistant reply ending does not automatically create a new trigger event unless your wrapper explicitly does so.
If the user expects "回复一停就继续跑", add a lightweight non-commit checkpoint trigger (for example scripts/hermes-auto-continue-checkpoint.sh) at agreed milestone boundaries rather than assuming message completion will fire hooks.
If the user also expects autonomous run summaries to return to chat, do not assume the local shell knows the current conversation origin. Repo-local scripts run without current-chat delivery context, so reliable auto-delivery requires an explicit target (for example discord:chat_id, telegram:chat_id:thread_id, or another concrete deliver string).
A practical pattern is: write .planning/auto-continue-last-summary.md after each run, then create a one-shot Hermes cron notification job only when an explicit deliver target is configured.
A robust default is: always write notifications to a local outbox under .planning/notifications/, then optionally invoke an external delivery command when HERMES_AUTO_CONTINUE_NOTIFY_COMMAND is configured.
Hermes cron runs in fresh sessions, so the trigger prompt itself should be self-contained and explicitly tell the runner which local files to read first (GRAPH_REPORT.md, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, and runtime summary/mirror files when present).
If a machine-readable task board exists, the trigger prompt should explicitly tell the runner to use that board as the canonical next-task selector and to update it after each meaningful step.
If local GSD skills/workflows are installed, the trigger prompt should read gsd-next first and let GSD decide whether the system currently needs discuss, plan, execute, or verify.
If graphify is installed, prefer query, path, and explain before guessing at cross-module structure.
A useful next step is to auto-surface graphify hints from recent file changes so the agent can tell when path, query, explain, or wiki are especially valuable.
If handoff is meant to auto-resume later, prefer machine-readable resume_condition probes such as:
file_exists:<path>
file_missing:<path>
task_done:<task_id>
task_status:<task_id>:<status>
ready_to_complete:<task_id>
writer_recommended
board_has_next_task
repo_lock_free
project_lock_free
Project-Level Completion Gate
For autonomous continuation loops, use a completion sentinel instead of guessing from partial task lists.
Recommended design:
The normal runner keeps going by default.
When the agent believes the whole scoped project is finished, it runs a dedicated completion script.
That script executes the repo's full verification command.
Only if verification succeeds and the worktree is clean does it write:
a sentinel file such as .planning/auto-continue-complete.json
an evidence doc such as docs/auto-continue-completion-evidence.md
Status checks should return COMPLETE only when:
sentinel exists
sentinel says complete
sentinel HEAD matches current HEAD
worktree is clean
This avoids the common failure mode where automation stops after a subtask, a phase checklist, or a focused test subset passes.
graphify was installed or upgraded via the selected Python + pip flow
graphify global Hermes integration was applied with graphify install --platform hermes
if graphify still warns about an older skill version, inspect other installed platform targets (for example ~/.claude/skills/graphify/.graphify_version) and update those too
GSD global install was applied with npx -y get-shit-done-cc@latest --codex --global --sdk
Also verify:
.planning/ exists when planning context is expected
.codex/ exists if local GSD runtime is used
graphify-out/graph.json and graphify-out/GRAPH_REPORT.md exist after graph build
git hooks exist if graphify hook automation is expected
if the repo uses an autonomous writer runtime, doctor / auto-progress / auto-runner-show all report the same primary writer facts
if the repo uses a primary-root contract, auto-execution-surface-show reports writer_recommended=yes only for the intended main repo
Standard Project Operating Loop
./scripts/graphify-sync.sh smart
Read graphify-out/GRAPH_REPORT.md
Read .planning/STATE.md and .planning/ROADMAP.md
Use GSD phase / plan / execute workflow
Implement changes
Re-run ./scripts/graphify-sync.sh smart
Update planning context if the phase meaning changed
Best division of labor:
Hermes = orchestration and persistence
graphify = architecture recall and code graph refresh
GSD = planning cadence and execution structure
Upgrade Contract
Always preserve these constraints:
wrappers may change
repo-local scripts may change
project docs may change
user-level installed platform copies of a skill may need resync across multiple runtimes
upstream repos should remain untouched unless upstream contribution is the actual task
If something breaks after upstream updates, fix in this order:
wrapper path detection
wrapper invocation contract
project-local script assumptions
only then consider upstream changes
Common Pitfalls
Treating one repo's path layout as universal
make wrapper paths configurable with env vars where reasonable
Depending on one pip install mode everywhere
virtualenv Python may reject --user
system Python may need --user
detect whether the chosen interpreter is in a venv, then choose pip install -U ... or pip install --user -U ... accordingly
Depending on graphify outputs that are no longer stable across versions
current graphify versions reliably produce graphify-out/graph.json and graphify-out/GRAPH_REPORT.md
do not require manifest.json unless you have verified that a specific version still emits it
wrappers and sync scripts should treat manifest as optional
Misreading graphify version warnings as Hermes-only failures
an outdated ~/.claude/skills/graphify/.graphify_version can trigger a warning even when ~/.hermes/skills/graphify/ is current
if warning persists, update every installed graphify platform target you actually use
Mixing project-specific guidance into the generic skill body
put reusable logic in this skill
put project-specific facts in repo docs or AGENTS.md
Stopping on partial completion
do not treat a single phase checklist, one small task, or a focused test subset as project completion
require a project-level completion sentinel written by a dedicated verification script
prefer default continue, not default stop
Letting hooks do long-running work
hooks should stay lightweight and should not run long autonomous sessions inline
use hooks to enqueue/trigger and let a runner or cron/timer do the heavy work
Missing concurrency control in auto-continue loops
use a single-runner lock (flock or equivalent)
if you want queue semantics, prefer one running + one pending over unbounded backlog
periodic reconciliation should recover from stale locks or crashed runners
Letting stale cron/state/lease metadata redefine the writer by accident
hermes cron list --all being empty does not prove there is no system cron entry
check system crontab -l when the observed writer and the intended writer disagree
if a stale sandbox/worktree cron is still running, remove the cron entry first, then clear or correct state/lease metadata so operator output returns to the main repo
if state says running but kernel locks are already free, treat it as stale metadata and reconcile it explicitly instead of trusting the stale file forever
Using one generic cron tag for every repo
cron install/uninstall should be keyed by project, not by one shared tag string
otherwise one repo's install step can silently overwrite another repo's autonomous loop
If Hermes is missing, stop and instruct manual Hermes installation — do not auto-install it
If Hermes exists, automatically install or upgrade latest graphify and GSD globally
Add wrappers only if the native commands are missing or inconsistent after install
Add project-local scripts second
If the user wants autonomous continuation, add the repo-local auto-continue layer with hook + cron/timer + lock + completion gate
Verify the full loop with real commands
Document the contract so future upgrades stay safe
For auto-continue setups, explicitly verify that partial completion does not stop the loop and that only the completion sentinel can stop it
Verify that the bundled ai-workflow.sh surface, auto-continue scripts, and operator docs all expose the same command names before packaging the workflow for teammates
Verify that Hermes runner failures become explicit blocked/operator state instead of being silently treated as ordinary incomplete runs
