seaworld008/hermes-graphify-gsd-nonintrusive-workflow

Hermes + graphify + GSD Non-Intrusive Workflow

Overview

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

1. 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

2. Depend on stable entrypoints Prefer these interfaces:

• hermes
• python -m graphify
• node <get-shit-done>/sdk/dist/cli.js

3. 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/

4. 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:

1. Check command -v hermes
2. If Hermes is missing, stop and instruct the user to install Hermes manually first
3. If Hermes exists, automatically install or upgrade graphify and GSD to latest stable upstream entrypoints
4. Configure graphify globally for Hermes
5. Configure GSD globally for the target runtime, defaulting to Codex unless the user specifies another runtime

Recommended commands:

# graphify — latest package, then global Hermes integration
# Baseline checked 2026-04-24: graphifyy 0.5.0.
# prefer a Python that actually has pip available; Hermes venv python is a valid fallback
PY_BIN="${PYTHON_BIN:-$HOME/.hermes/hermes-agent/venv/bin/python3}"
[ -x "$PY_BIN" ] || PY_BIN="$(command -v python3)"
if "$PY_BIN" -c 'import sys; print(int(sys.prefix != sys.base_prefix))' 2>/dev/null | grep -q '^1$'; then
  "$PY_BIN" -m pip install -U "graphifyy>=0.5.0"
else
  "$PY_BIN" -m pip install --user -U "graphifyy>=0.5.0"
fi
~/.local/bin/graphify install --platform hermes || graphify install --platform hermes

# GSD — latest global runtime + SDK
npx -y get-shit-done-cc@latest --codex --global --sdk

Notes:

• 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

Recommended repo-local files:

• scripts/hermes-auto-continue-config.sh
• scripts/hermes-auto-continue-status.sh
• scripts/hermes-auto-continue-trigger.sh
• scripts/hermes-auto-continue-checkpoint.sh (manual no-commit checkpoint trigger)
• scripts/hermes-auto-continue-summary.sh (generate the last-run summary artifact)
• scripts/hermes-auto-continue-task-board-init.sh
• scripts/hermes-auto-continue-task-board-status.sh
• scripts/hermes-auto-continue-task-board-update.sh
• scripts/hermes-auto-continue-task-board-complete-if-ready.sh
• scripts/hermes-auto-continue-task-board-sync-docs.sh
• scripts/hermes-auto-continue-resume-if-ready.sh
• scripts/hermes-auto-continue-notify.sh
• scripts/hermes-gsd-phase-engine-status.sh
• scripts/hermes-gsd-next-state.sh
• scripts/hermes-gsd-sync-runtime-mirror.sh
• scripts/hermes-graphify-strategy-hints.sh
• scripts/hermes-auto-continue-learnings.sh
• scripts/hermes-auto-continue-mark-complete.sh
• scripts/install-hermes-auto-continue-cron.sh
• .husky/post-commit
• optional .husky/post-merge

Recommended optional relay artifacts:

• .planning/auto-continue-last-summary.md
• .planning/task-board.json
• .planning/auto-gsd-next-state.json
• .planning/notifications/
• .planning/learnings/
• .planning/skill-candidates/
• optional explicit delivery env vars such as:
  • HERMES_AUTO_CONTINUE_NOTIFY_DELIVER
  • HERMES_AUTO_CONTINUE_NOTIFY_SCHEDULE
  • HERMES_AUTO_CONTINUE_NOTIFY_COMMAND
  • HERMES_AUTO_CONTINUE_NOTIFY_EVENTS
• recommended runtime tuning env vars such as:
  • HERMES_AUTO_CONTINUE_MAX_PASSES_PER_TRIGGER
  • HERMES_AUTO_CONTINUE_PASS_IDLE_SECONDS
  • HERMES_AUTO_CONTINUE_CRON_SCHEDULE

Reality-tested runtime contract

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:
  • ./scripts/ai-workflow.sh doctor
  • ./scripts/ai-workflow.sh gsd-doctor
  • ./scripts/ai-workflow.sh gsd-next-state
  • ./scripts/ai-workflow.sh gsd-skill-show <name>
  • ./scripts/ai-workflow.sh gsd-workflow-show <name>
  • ./scripts/ai-workflow.sh graphify-hints
  • ./scripts/ai-workflow.sh auto-learnings <event> [title] [detail]
  • ./scripts/ai-workflow.sh auto-status
  • ./scripts/ai-workflow.sh auto-progress
  • ./scripts/ai-workflow.sh auto-runner-show
  • ./scripts/ai-workflow.sh auto-execution-surface-show
  • ./scripts/ai-workflow.sh auto-workflow-state-show
  • ./scripts/ai-workflow.sh auto-handoff-show
  • ./scripts/ai-workflow.sh auto-resume-if-ready
• the bundled templates/ai-workflow.sh in this skill now exposes those subcommands and delegates to the repo-local auto-continue scripts
• use the operator commands as the primary fact source before assuming the runtime is healthy

Recommended execution-surface guard for any repo allowed to write:

• require at least:
  • package.json
  • pnpm-lock.yaml
  • src-tauri/ or the repo's real backend root
  • .planning/STATE.md
  • executable scripts/graphify-sync.sh
• doctor, trigger, and cron/timer install paths should all refuse to proceed on an incomplete execution surface
• if temporary experiments must bypass the guard, require an explicit override env var and treat it as an exception path, not the normal workflow

Recommended writer-surface contract:

• define a primary root for the project
• compute and expose:
  • writer_eligible
  • primary_root_match
  • writer_recommended
• only allow runtime-binding commands or cron installation on writer_recommended=yes

Core rule:

• Do not stop because one small task or one local checklist is done.
• Stop only when a project-level completion sentinel exists and still matches the current HEAD/worktree state.

Recommended machine-readable planning contract:

• keep human-readable docs (PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md)
• 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:
  1. GSD phase truth (gsd-next, discuss / plan / execute / verify workflow docs when available)
  2. in_progress task
  3. highest-priority executable todo
  4. 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.
• Typical immediate triggers are: post-commit, optional post-merge, explicit manual checkpoint scripts, and periodic cron/timer reconciliation.
• 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:

1. The normal runner keeps going by default.
2. When the agent believes the whole scoped project is finished, it runs a dedicated completion script.
3. That script executes the repo's full verification command.
4. 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
5. 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.

Minimum Verification Checklist

Run these before claiming success:

command -v hermes
hermes --version

command -v graphify
graphify --help

command -v gsd-sdk
gsd-sdk --version

./scripts/graphify-sync.sh status
./scripts/graphify-sync.sh smart

For first-time bootstrap, also verify:

• hermes existed before any automation began
• 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

1. ./scripts/graphify-sync.sh smart
2. Read graphify-out/GRAPH_REPORT.md
3. Read .planning/STATE.md and .planning/ROADMAP.md
4. Use GSD phase / plan / execute workflow
5. Implement changes
6. Re-run ./scripts/graphify-sync.sh smart
7. 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:

1. wrapper path detection
2. wrapper invocation contract
3. project-local script assumptions
4. only then consider upstream changes

Common Pitfalls

1. Treating one repo's path layout as universal

• make wrapper paths configurable with env vars where reasonable

2. 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

3. 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

4. Misreading graphify version warnings as Hermes-only failures

• graphify scans multiple installed platform skill directories when checking installed skill versions
• 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

5. 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

6. 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

7. 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

8. 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

9. 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

10. 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

Files to Reuse

Load these bundled files when implementing:

• templates/bootstrap-toolchain.sh
• templates/graphify-wrapper.sh
• templates/gsd-sdk-wrapper.sh
• templates/ai-workflow.sh
• templates/hermes-auto-continue-config.sh
• templates/hermes-auto-continue-status.sh
• templates/hermes-auto-continue-trigger.sh
• templates/hermes-auto-continue-checkpoint.sh
• templates/hermes-auto-continue-summary.sh
• templates/hermes-auto-continue-task-board-init.sh
• templates/hermes-auto-continue-task-board-status.sh
• templates/hermes-auto-continue-task-board-update.sh
• templates/hermes-auto-continue-task-board-complete-if-ready.sh
• templates/hermes-auto-continue-task-board-sync-docs.sh
• templates/hermes-auto-continue-resume-if-ready.sh
• templates/hermes-auto-continue-notify.sh
• templates/hermes-gsd-phase-engine-status.sh
• templates/hermes-gsd-next-state.sh
• templates/hermes-gsd-sync-runtime-mirror.sh
• templates/hermes-graphify-strategy-hints.sh
• templates/hermes-auto-continue-learnings.sh
• templates/hermes-auto-continue-mark-complete.sh
• templates/install-hermes-auto-continue-cron.sh
• templates/husky-post-commit-auto-continue.sh
• templates/husky-post-merge-auto-continue.sh
• references/first-install.md
• references/upgrade-contract.md
• references/auto-continue-best-practices.md
• references/ai-workflow-auto-continue-snippet.md

Execution Pattern

When using this skill:

1. Audit live tool availability first
2. If Hermes is missing, stop and instruct manual Hermes installation — do not auto-install it
3. If Hermes exists, automatically install or upgrade latest graphify and GSD globally
4. Add wrappers only if the native commands are missing or inconsistent after install
5. Add project-local scripts second
6. If the user wants autonomous continuation, add the repo-local auto-continue layer with hook + cron/timer + lock + completion gate
7. Verify the full loop with real commands
8. Document the contract so future upgrades stay safe
9. For auto-continue setups, explicitly verify that partial completion does not stop the loop and that only the completion sentinel can stop it
10. 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
11. Verify that Hermes runner failures become explicit blocked/operator state instead of being silently treated as ordinary incomplete runs