Help Gnadd

GNADD Help

Provide lightweight orientation for Git-Native Agent-Driven Development (GNADD). Do not run git commands from this skill; route mechanics to the operational skills.

Core Model

• GitHub is the system of record: issues capture intent, branches hold work, PRs record what shipped, and git history is the audit trail.
• The operational skills drive the loop: init-gnadd (once per repo: rails and the conventions file), prime-gnadd, new-issue-gnadd, start-issue-gnadd, commit-gnadd, resolve-issue-gnadd, quickfix-gnadd (the no-issue fast path for trivial changes), and yolo-gnadd (autonomous full-loop on a decided unit; explicit invocation only). Their git mechanics run through a bundled deterministic script (gnadd.sh), not improvised commands. vision-gnadd sits before the loop: it interviews the user into VISION.md and touches no git.
• Enforcement is layered, lowest layer that can hold each invariant: GitHub server rules (gnadd init — squash-only merges, PR-required main), the script (ff-only syncs, divergence halts, gated cleanup), the skills (judgment and conversation), and the human (reading the diff before merge).
• Recovery from bad states has a sanctioned path: gnadd.sh doctor (bundled with prime-gnadd) diagnoses and offers lossless fixes, and a rescued branch has scripted exits (/quickfix-gnadd, start --from, drop). Never improvise reset/force recoveries.
• Two receipts are always available: gnadd.sh trace show prints every script call this repo has seen (command, exit status, branch, kept in .git/gnadd-trace.log), and gnadd.sh round list <N> prints an issue's round trail from any branch, not only its own.
• The user's load-bearing job is to describe desired behavior, answer scope questions, and read diffs before merge.

Describe vs Track

Files that describe stable truth are fine. Files that track mutable state should not exist.

• Keep: VISION.md (intent, marked by commitment level), README run instructions, project conventions, stable reference docs.
• Avoid: task lists, progress files, maintained plans, status checklists.
• Test: would the agent need to keep this file up to date? If yes, that state belongs in GitHub issues, PRs, branches, or commits instead.

Skill Router

• Adopt or realign a repo: use /audit-gnadd.
• Start a session or inspect state: use /prime-gnadd.
• Write or revise VISION.md in conversation: use /vision-gnadd.
• Capture new work: use /new-issue-gnadd.
• Begin or resume issue work: use /start-issue-gnadd <N>.
• Save progress on an issue branch: use /commit-gnadd.
• Verify, PR, merge, and clean up: use /resolve-issue-gnadd.
• Land one trivial fix (typo, doc line) without an issue: use /quickfix-gnadd.
• Run a decided issue or quickfix end-to-end without mid-loop gates: use /yolo-gnadd <N or description> (never auto-invoked).
• Diagnose or recover from a bad git state (diverged main, stashes, leftovers): run gnadd.sh doctor from the prime-gnadd skill's directory.
• Set up server-side rails on a new repo: gnadd.sh init (squash-only merges, branch ruleset on main; --ci adds a test workflow stub).
• If a git operation seems needed and no skill covers it, ask for a skill-shaped path before improvising raw git commands.
• Update, refresh, or reinstall the skills themselves: see Install & Update below.

Install & Update

The right refresh command depends on how the skills were installed — answer update questions with the path that matches, and never assume a scope.

• Installed from GitHub (npx skills add AlexHagemeister/gnadd ...): refresh in the same scope as the install — npx skills update -g -y for a global install, npx skills update -p -y for a project-local one. Updating the wrong scope leaves the active copies stale without any warning.
• Installed from a local checkout (npx skills add . --copy, e.g. the repo's scripts/sync.sh while developing): skills update cannot track local-path installs and skips them silently — re-run scripts/sync.sh from the checkout instead.
• Installed as a Claude Code plugin (claude plugin install gnadd@gnadd, skills invoked as /gnadd:<skill>): refresh the marketplace, then the plugin — claude plugin marketplace update gnadd followed by claude plugin update gnadd@gnadd (or the same two steps as /plugin ... inside a session). npx skills update does not see plugin installs.
• Caveats for any update: both channels install from the repo's default branch, so an update pulls the latest main, not the last tagged release. Pre-1.0, read the release notes (repo Releases page) before updating. gnadd version reports the release baseline — the installed copy may include changes merged after that release. Updated skill content applies from the next invocation; newly added or renamed skills may need an agent restart to appear.

Deep Reference

For startup guidance, file-hygiene questions, rationale, or edge cases not covered here, fetch the canonical guide from this pinned URL:

https://raw.githubusercontent.com/AlexHagemeister/gnadd/v0.5.0/GNADD.md

This URL is pinned to a commit, not main, so installed skills do not drift with unreleased guide changes. The pin is rewritten by scripts/release.sh at release time — do not hand-edit it out of band.

Closing Guidance

Do not nudge after every answer. Match nudge depth to user intent:

• Purely informational (describe-vs-track, "which skill does X?", rationale questions): no nudge — the answer stands alone.
• Routing toward action ("how do I start?", "where should this state live?"): light nudge — one skill pointer (e.g. /prime-gnadd, /new-issue-gnadd), no full loop recap.
• Session bootstrap ("I'm new here", end-to-end workflow orientation): full nudge toward /prime-gnadd to see live repo state.

When nudging, keep it to a sentence with an invitational option. Do not restate the skill router table.