Immutable. This exact content is served forever at /api/v1/blob/75dcc40e014e7a0c.
---
name: g-help
description: Context-aware help. With no argument, reads current project state and tells you where you are and what to do next, plus a map of every archive. With a topic or question argument (`/g-forge help <topic>`), answers it and points you at the right command or archive.
---
**Announce:** "Using g-help to assess project state and point at what's next."
You are running the g-help skill. Follow every step below precisely.
## Step 0 — Topic mode (if `$ARGUMENTS` is non-empty)
If the developer passed a topic or question in `$ARGUMENTS` (e.g. `/g-forge help how do I review`, `/g-forge help where are the ADRs`, `/g-forge help what happened last session`, `/g-forge help blast radius`), **answer that instead of dumping the full status**:
1. Announce: `> Using g-help to answer: "[the topic]".`
2. Resolve it to the right lens — a **command**, an **archive path**, or a **rule/doc** — and answer concisely:
- "how / what command for X" → name the command and one line on what it does (use the grouped list in Step 5). E.g. review → `/g-forge review`; capture a decision → `/g-forge adr`.
- "where is / show me X" → point at the archive path from the **Archives & lenses** map below, and if a concrete file is being asked for, Glob/Read the most relevant one and summarise it. E.g. decisions → `g-docs/decisions/`; last session → newest `g-docs/retros/*.md` + `.claude/journal/`; agent findings → `g-docs/agent-output/`; what's next → `g-docs/ROADMAP.md` `## Active Session`.
- "what is / how does X work" (a concept like the commit gate, tiers, the wave model, the context gate) → answer from `G-RULES.md` / `.claude/rules/` and the docs, then point at the file.
- "should I /g-plan this / is this too small for the full pipeline" (a trivial edit — one file, known location, no design decision) → `/g-plan` is the wrong tool: switch to the `light` tier (`/g-tier light`) or edit inline, and return to `full` afterwards; the full pipeline on a trivial task costs an order of magnitude more than the edit itself.
- **Unknown or retired token** — the topic names a command/skill token that doesn't resolve against the grouped list in Step 5 (this includes any bare `/g-<name>` form the developer tried to type directly, e.g. `/g-plan` or `/g-review` — those standalone command shims are retired per ADR-007). Never fail silently: name the closest matching token from the grouped list if one exists, and explain the two surviving invocation forms — `/g-forge <token>` (e.g. `/g-forge plan`) or the skill's direct registration `/g-forge:g-<name>` (e.g. `/g-forge:g-plan`).
3. End with the single most useful next command. Keep it tight — topic mode is an answer, not the full dashboard. Skip Steps 2–5 unless the answer genuinely needs the full state.
If `$ARGUMENTS` is empty, ignore this step and run the full assessment (Steps 1–5).
## Step 1 — Announce
Output exactly:
> Using g-help to assess project state.
## Step 2 — Read project files
Attempt to read each of the following files from the current working directory. If a file is missing, note it as "not found" and continue — never error out.
1. `g-docs/todo.md` — current tasks · `g-docs/ROADMAP.md` `## Active Session` — the handoff
2. `g-docs/plans/` — use Glob to find the most recent plan file (e.g. `g-docs/plans/*.md`); if multiple exist, use the one with the latest modification time or highest sort order
3. `g-docs/ROADMAP.md` — current milestone and status
4. `.claude/g-forge-approved` — presence indicates the commit gate is open
5. `.claude/hooks/workflow-checkpoint.sh` — presence indicates workflow hooks are installed
6. `g-docs/project_brief.md` — presence indicates the project has been onboarded or kicked off
7. Current git branch — run `git branch --show-current` via Bash (skip gracefully if git is unavailable)
8. `.claude/integration-tier` — active integration tier (default: `full`)
9. `.claude/voice-profile` — active voice profile (default: `dev`)
10. `.claude/telemetry-profile` — derived health profile from `/g-telemetry` (default: `stable`)
11. `g-docs/telemetry/` — Glob for most recent snapshot file (informational — shows date of last `/g-telemetry` run)
12. `g-docs/forecasts/` — Glob for most recent forecast file (informational — shows most recently forecast plan)
13. `g-docs/identity.md` — Read if present (informational — shows the project's last synthesised personality snapshot)
## Step 3 — Determine project name
Use the `name` field from `CLAUDE.md` if present, otherwise use the current directory name.
## Step 4 — Determine phase
Apply the following rules in order (first match wins):
| Condition | Phase |
|---|---|
| `CLAUDE.md` is missing OR has no G-Forge Rules block, AND `g-docs/project_brief.md` is missing | Not initialized |
| `g-docs/project_brief.md` is missing | Not initialized |
| `CLAUDE.md` exists but has no G-Forge Rules block | Not initialized |
| G-Forge Rules block exists, no plan file found in `g-docs/plans/` | Initialized |
| Plan file exists AND `.claude/g-forge-approved` is absent AND `g-docs/todo.md` shows tasks remaining | Execution in progress |
| Plan file exists AND `.claude/g-forge-approved` is absent AND `g-docs/todo.md` shows all tasks done | Review pending |
| Plan file exists AND `.claude/g-forge-approved` is absent | Active plan |
| `.claude/g-forge-approved` exists | Ready to merge |
Default to "Initialized" if none of the above conditions clearly match and the project appears set up.
**Next step mapping:**
- Not initialized (no g-docs/project_brief.md) → suggest `/g-forge kickoff` (new project) or `/g-forge onboard` (existing repo)
- Not initialized (g-docs/project_brief.md exists, no G-Forge Rules block) → suggest `/g-forge init`
- Initialized (no plan file) → suggest `/g-forge plan`
- Active plan → suggest `/g-forge execute` to dispatch waves
- Execution in progress → summarize remaining tasks from `g-docs/todo.md` and suggest continuing or running `/g-forge review` if all tasks are done
- Review pending → suggest `/g-forge review`
- Ready to merge → suggest merging the branch or running `/g-forge review` if not yet reviewed
## Step 5 — Output structured status
Print the following block, filling in values from what you read. Omit the "Branch" line if git is unavailable.
```
## G-Forge Status
Project: [name]
Branch: [current git branch]
Phase: [phase]
What's active:
- [milestone from g-docs/ROADMAP.md, e.g. "M2: Workflow Engine — in progress"]
- [plan file name if found, e.g. "g-docs/plans/wave-plan-2025-05-01.md"]
- [wave info if detectable from plan file, e.g. "Wave 3 of 4"]
- [count of remaining tasks from g-docs/todo.md, e.g. "3 tasks remaining in g-docs/todo.md"]
- [workflow hooks: installed / not installed]
- [commit gate: open / not set]
- [g-docs/project_brief.md: present / missing]
Configuration:
- Tier: [full / balanced / light] ([file present / using default])
- Voice: [dev / mid / eli5] ([file present / using default])
- Health profile: [stable / cautious / defensive / recovery] ([from /g-telemetry])
Recent intelligence:
- Last telemetry: [date of most recent g-docs/telemetry/*.md, or "never run — try /g-telemetry"]
- Last forecast: [most recent g-docs/forecasts/*.md slug, or "none — /g-forecast is auto-invoked by /g-plan"]
- Identity: [present (date of g-docs/identity.md) / not yet synthesised — try /g-identity]
Next step:
[one clear action the developer should take right now, including the exact command to run]
Archives & lenses (where to read what's going on — only list paths that exist):
State: g-docs/ROADMAP.md ## Active Session — the handoff (where you are / what's next)
g-docs/ROADMAP.md — milestone plan · g-docs/project_brief.md — goals & constraints
g-docs/todo.md / g-docs/todo-done.md — active task ledger / archive
Decisions: g-docs/decisions/ — ADRs (decisions + rationale) · CHANGELOG.md — version history
g-docs/env-vars.md — env var reference
Work: g-docs/plans/ — approved wave plans
g-docs/agent-output/ — full agent findings (wave + review), per task
g-docs/retros/ — session retrospectives · .claude/journal/ — raw observer log
Intel: g-docs/forecasts/ — premortems · g-docs/blast-radius/ — dependency impact
g-docs/telemetry/ — reliability snapshots · g-docs/identity.md — project personality
g-docs/patterns/ — mined pattern reports (latest.md = open report, date-named = resolved archive)
Tip: `/g-forge help <topic>` answers a specific question and points at the right lens.
(g-docs/inbox/adversarial/ is deliberately not listed above — it's an ingress for external counter-reports, not an archive.)
All commands (grouped by purpose):
Setup:
/g-forge init — the single front door: detect → onboard|kickoff → scaffold → specialize → ready
/g-forge kickoff — (sub-step of /g-init) new project: interview → g-docs/project_brief.md
/g-forge onboard — (sub-step of /g-init) existing repo: deep-read → g-docs/project_brief.md
/g-forge specialize — (sub-step of /g-init) install stack architect agent + architecture rules
Planning:
/g-forge roadmap — feature dump → cluster → sequence → g-docs/ROADMAP.md
/g-forge intake — triage a dropped feature vs the brief → propose → ask
/g-forge align — brief-deviation check: ALIGNED / DRIFTING (advisory)
Per-task loop (auto-triggered on `full` tier):
/g-forge plan — decompose task → wave schedule → approval
/g-forge execute — dispatch waves
/g-forge review — full review pipeline → MERGE READY or HOLD
/g-forge doc-review — standalone documentation-review gate → DOCS READY or DOCS HOLD
Intelligence:
/g-forge patterns — mine retros + todo-done for recurring patterns (saves abstracted report); resolve pending ones in a fresh session
/g-forge forecast — premortem + scope realism + token-cost band (auto in /g-plan)
/g-forge telemetry — 8 reliability metrics → health profile → adaptive orchestration
/g-forge blast-radius — forward + reverse deps + per-file volatility for a change
/g-forge identity — narrative synthesis of the project's operational personality
Configuration:
/g-forge tier — integration tier: full / balanced / light
/g-forge voice — voice profile: dev / mid / eli5
Hygiene:
/g-forge brief — refresh g-docs/project_brief.md as project evolves
/g-forge status — quick one-line state snapshot
/g-forge resume — re-hydrate a fresh session with the right slice of the durable record
/g-forge doctor — health check: hooks, settings, rules block, duplicate/legacy installs
/g-forge update — realign all g-forge files to current plugin version
/g-forge retro — synthesize session retro from the observer journal (no interview)
/g-forge adr — capture an architectural decision record
/g-forge trim — weekly read-only audit of CLAUDE.md + agent memory for bloat
/g-forge help — context-aware help (this skill); `/g-forge help <topic>` answers a question
/g-forge listen — Tier 3 listen mode for smoke testing
/g-forge train — training mode: PM mentors you through the workflow
/g-forge afk — autonomous milestone executor (requires approved plan)
Audit / docs:
/g-forge audit — code quality audit (SOLID, smells, dead code, coverage)
/g-forge optimize — performance audit (complexity, N+1, re-render waste)
/g-forge refactor — guided refactor with spec + review gate
/g-forge docs — documentation audit and generation (code-level doc hygiene)
/g-forge wiki — build/maintain the human-facing project wiki in g-wiki/
Skill development:
/g-forge skill-design — design a new G-Forge skill from scratch
/g-forge skill-validate — validate a skill or agent against structural rules
```
## Rules
- Never error out. If any file is missing, treat it as "not set up yet" and note it gracefully in "What's active".
- Be concise. "What's active" bullets should be short facts, not prose.
- The "Next step" must be a single, actionable sentence ending with the exact command to run (e.g. "Run `/g-forge plan` to decompose your task into a wave schedule.").
- Do not invent state. Only report what you actually found in the files.
- Do not include `argument-hint` in any output or metadata.
- On an unknown or retired token (Step 0), never fail silently — always name the surviving invocation form(s).