# Help Gnadd > GNADD workflow orientation: GitHub issues as backlog, describe-vs-track file rule, and which GNADD skill handles each workflow step. Use when the user asks about GNADD, agent-driven development workflow, project context files, tasks.md versus issues, startup guidance, how to set up work, or how to install, update, or refresh the GNADD skills themselves. Do not use for routine coding unless the question is workflow-shaped. - Skill: `alexhagemeister/help-gnadd` (Agent Skill) - Install (CLI): `npx skillmds@latest add alexhagemeister/help-gnadd` - Raw SKILL.md: https://api.skillmd.com/api/skills/alexhagemeister/help-gnadd/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: AlexHagemeister (https://skillmd.com/u/alexhagemeister) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/alexhagemeister/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 ` 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 `. - 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 ` (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:`): 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.