Claude Skill

next

Use when user asks "what's next" or "next step". Prints next slash command from current state via a sonnet subagent. Flags: `--clear`, `--list`.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download grimoire-rs-grimoire-.claude_skills_next-dddf811.zip · 4 KB

Install

skills CLI npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.claude/skills/next
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
Git git clone https://github.com/grimoire-rs/grimoire.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/next — Suggest the Next Slash Command

Look at current state (branch, working tree, plans, recent commits, open PR). Print exactly one slash command user copy-paste to continue. State inspection delegated to sonnet subagent so output stay compact, main session context not flooded with git log / gh pr view / plan-file output.

Primarily read-only. Becomes a one-shot state-fixer when no ## Status block found and no .claude/state/current_plan.md pointer — prompts user to confirm inferred state, then writes current_plan.md + injects Status block into plan so future invocations land in the fast path. Never edits code, never commits, never pushes.

Flags

  • --clear — tell subagent make suggested command fully self-contained (absolute paths, no "the work we just did" refs), prepend /clear so future session with no memory run cleanly.
  • --list — subagent return top 3 candidates with one-line rationale each.
  • (no flag) — one self-contained command + one-line "why" + one-line "what was checked".

Workflow

1. Parse flags

Strip --clear and --list from argument string. Leftover = free-text intent (rare; e.g. /next --clear after fixing the bug).

2. Delegate to sonnet subagent

Spawn one subagent (Agent tool, subagent_type: general-purpose, model: sonnet) with prompt below. Do NOT run inspection commands yourself — point of delegation = keep main context clean.

Subagent prompt template (fill {flags} and {intent} placeholders):

You are inspecting Grimoire project state to suggest exactly ONE next slash command for the user to type. You are read-only — never edit, commit, or push.

Flags from the user: {flags}     # e.g. "--clear", "--list", or "" (none)
Free-text intent (optional): {intent}

## Step 1 — Snapshot state (parallel batch, single message, multiple Bash calls)

- `git rev-parse --abbrev-ref HEAD`               # current branch
- `git status --porcelain=v1`                     # never -uall
- `git log -10 --oneline`                         # commit window
- `git rev-list --count main..HEAD 2>/dev/null`   # commits ahead of main
- `git diff --stat main...HEAD 2>/dev/null`       # changed-files summary
- `gh pr view --json number,state,baseRefName,headRefName 2>/dev/null` # open PR for branch
- `cat .claude/state/current_plan.md 2>/dev/null`                           # pointer to active plan (primary signal)
- `ls -t .agents/plans/*.md 2>/dev/null | head -10`              # recent plans (mtime)
- `ls -t .agents/plans/meta-plan_*.md 2>/dev/null | head -5`     # recent meta-plans

## Step 2 — Resolve active plan (Status block is primary signal)

Resolution order — first match wins. **Steps 1+2 are read-only fast paths. Step 3 is the state-fixer fallback that prompts the user and persists their answer to `.claude/state/current_plan.md` so future invocations land in step 1.**

### Step 2a — `.claude/state/current_plan.md` pointer (preferred)

If `current_plan.md` exists, parse it for the `**Plan:**` line. If the referenced plan file exists and has a `## Status` block (grep `^## Status$` to next `^## ` heading), use the block's `Active phase` + `Step` fields verbatim. Done — go to Step 3.

### Step 2b — Status block on most-recent plan

If `current_plan.md` absent, glob `.agents/plans/plan_*.md` (mtime desc). For each, grep for `## Status` block. First match wins — use its fields. Don't read the whole plan, just the first 30 lines.

### Step 2c — Inferred-state fallback (state-fixer)

If steps 2a+2b both fail (legacy plan with no Status block, or stale state, or no plan file matches), fall back to **commit-subject heuristic**:

1. Identify newest plan via mtime: `ls -t .agents/plans/plan_*.md`
2. Grep `^## Phase` headers in that plan to enumerate phases
3. Grep commit subjects in `main..HEAD` (`git log --format=%s main..HEAD`)
4. Cross-reference: a phase is **done** if its title (or commit-subject keywords from it, e.g. "load_exclusive", "grimoire lock") appears in any commit subject. The first phase with no commit-subject match is **active**.
5. **Prompt the user via `AskUserQuestion`** with the inferred state:

       Inferred from commits + plan headers: plan=<X>, phase=<N> "<title>" active.
       Confirm and persist to .claude/state/current_plan.md?

   Options:
   - **Confirm + persist** (default) — write `current_plan.md`, inject `## Status` block at top of plan file (after H1, before next heading). Future `/next` invocations land in Step 2a.
   - **Different phase** — user names phase number; same persistence.
   - **No active plan** — write nothing, treat as Step 2d.

If `--list` flag set, do not prompt — present the inferred phase as candidate #1 and let user pick.

### Step 2d — No active plan (valid empty state)

If user picks "No active plan" in Step 2c, or no plan files exist at all:

- `commits-ahead-of-main = 0` AND clean tree → say so explicitly, suggest browsing open issues/PRs (`gh issue list --state open --limit 5` or `/hex-plan "<task>"` for new work)
- `commits-ahead > 0` AND no plan → suggest `/hex-plan` to capture the in-flight work as a tracked plan, OR `/commit` if there's a Checkpoint
- Right after `/finalize` clears `current_plan.md` → "feature just landed, pick next PR/issue"

Empty state is a **valid outcome**, not an error.

## Step 3 — Classify the phase

Apply the first matching row. **Status-block fields beat heuristic table** when both apply.

| Observed state                                                          | Suggest                                       |
|---|---|
| Status `Step: /hex-execute → ...` OR plan-approved OR phase done with next phase | `/hex-execute <tier> <plan-path>` |
| Status `Step: /hex-review → round N`                                  | `/hex-review` (continue same round)         |
| Status all phases done, dirty tree                                      | `/commit`                                     |
| Status all phases done, clean tree, no PR                               | `/hex-review` then `/finalize`              |
| On `main`                                                               | `/hex-plan "<task>"` — never work on main   |
| Branch exists, no plan, no commits ahead                                | `/hex-plan "<task>"` (ask if no task named) |
| Meta-plan exists, no `plan_*.md` yet                                    | Awaiting plan approval — print `/hex-plan`  |
| Plan exists, 0 commits ahead, clean tree                                | `/hex-execute <plan-path>`                  |
| Plan exists, commits ahead, dirty tree                                  | `/commit`                                     |
| PR exists (state OPEN)                                                  | `/hex-review #<N>`                          |
| Worktree branch (goat/evelynn/sion/soraka), multiple Checkpoints, clean | `/finalize` (only if Status confirms phases done) |
| HEAD subject == `Checkpoint`, clean tree                                | `/commit` (will draft + amend)                |

When two rows tie, pick the earlier (correctness > convenience). **Never suggest `/finalize` without confirming via Status block that no phases are still active** — that was the regression this skill is fixing.

## Step 4 — Synthesize the command

Rules — strictly enforced when `--clear` is set; recommended otherwise:

- Use absolute paths to plan artifacts (`.agents/plans/plan_X.md`).
- Inline tier and overlay flags from the plan's handoff block when known (`/hex-execute max .agents/plans/plan_X.md`).
- For `/hex-review`, prefer a PR number (`#61`) when an open PR exists; otherwise the branch name.
- For `/commit` and `/finalize`, no arguments — they snapshot state themselves.
- For `/hex-plan`, include a 1-line task description in quotes.
- NEVER reference "the previous work" / "what we just discussed" / "the bug from earlier".
- NEVER suggest a slash command that is not present in `.claude/rules.md` "Skills by task topic" — read that table if uncertain.

## Step 5 — Reply

Output exactly one of these three formats. No preamble, no signature.

DEFAULT (no flag):
~~~
Next:
    <slash-command>

Why:    <one-line reason>
Looked at: <one-line list of state checks>
~~~

--clear:
~~~
Next (handover — context will be cleared):
    /clear
    <self-contained slash-command>

Why:    <one-line reason>
Looked at: <one-line list of state checks>
Note: command is self-contained — safe to run after /clear.
~~~

--list:
~~~
Candidates:
  1. <slash-command>
       <one-line rationale, why this is #1>
  2. <slash-command>
       <one-line rationale>
  3. <slash-command>
       <one-line rationale>
~~~

## Edge cases

- No git repo → reply: "not in a git repo — nothing to suggest". Exit.
- Detached HEAD → suggest `git checkout <branch>` first; do not propose a hex command.
- `gh` unavailable / unauthenticated → skip PR detection, fall through to branch baseline.
- Multiple plans with mtime within 1h → list them, ask the user to pick (still one Candidates block).
- Skill list expanded recently → re-read `.claude/rules.md` "Skills by task topic" before mapping. Never invent a skill. The `/hex-*` commands listed there are user-level and will not appear under `.claude/skills/` — that is expected.

Keep your reply under 12 lines. The user will copy-paste from your output directly.

3. Print subagent's output verbatim

Subagent already formatted output. Do not rewrap, summarise, comment. Print exactly what returned. If --clear set, subagent output already include /clear line — do not add another.

If subagent report hard error (no git repo, detached HEAD, etc.), print message and stop.

Constraints

  • NEVER edit code, commit, push.
  • May write .claude/state/current_plan.md and inject ## Status block into a plan only via user-confirmed Step 2c state-fixer path. Never silently mutate state. The user's AskUserQuestion answer is consent.
  • NEVER run inspection commands in main session — subagent's job. Skip delegation = defeat context-isolation.
  • NEVER suggest a slash command that is neither in .claude/skills/ nor a hex command (/hex-init, /hex-plan, /hex-execute, /hex-review, /hex-architect) — hex ships at user level, so its absence from .claude/skills/ is expected, not an invented skill. Subagent cross-checks .claude/rules.md; main session no second-guess.
  • ALWAYS spawn exactly one subagent. No parallelism — only one question asked.
  • NEVER suggest /finalize without confirming via Status block that all phases are marked done. (See Step 3 table — premature finalize was the regression that motivated this skill's redesign.)

References

  • .claude/rules.md — "Skills by task topic" (authoritative skill list — subagent reads it)
  • .claude/rules/workflow-intent.md — work-type router
  • .claude/rules/workflow-git.md — branching, two-phase commit/finalize
  • .claude/rules/meta-ai-config.md "Plan Status Protocol" — schema + per-skill mutation table; .claude/state/ tree is gitignored (per-worktree)
  • /hex-execute's closing handoff — the pattern this skill emulates
Files (grimoire)
  • SKILL.md 11.3 KB
    ---
    name: next
    description: 'Use when user asks "what''s next" or "next step". Prints next slash command from current state via a sonnet subagent. Flags: `--clear`, `--list`.'
    user-invocable: true
    disable-model-invocation: true
    argument-hint: "[--clear | --list]"
    triggers:
      - "what's next"
      - "what is next"
      - "next step"
      - "next command"
      - "what now"
    ---
    
    # /next — Suggest the Next Slash Command
    
    Look at current state (branch, working tree, plans, recent commits, open PR). Print exactly **one** slash command user copy-paste to continue. State inspection delegated to **sonnet subagent** so output stay compact, main session context not flooded with `git log` / `gh pr view` / plan-file output.
    
    **Primarily read-only.** Becomes a one-shot **state-fixer** when no `## Status` block found and no `.claude/state/current_plan.md` pointer — prompts user to confirm inferred state, then writes `current_plan.md` + injects Status block into plan so future invocations land in the fast path. Never edits code, never commits, never pushes.
    
    ## Flags
    
    - `--clear` — tell subagent make suggested command **fully self-contained** (absolute paths, no "the work we just did" refs), prepend `/clear` so future session with no memory run cleanly.
    - `--list` — subagent return top 3 candidates with one-line rationale each.
    - (no flag) — one self-contained command + one-line "why" + one-line "what was checked".
    
    ## Workflow
    
    ### 1. Parse flags
    
    Strip `--clear` and `--list` from argument string. Leftover = free-text intent (rare; e.g. `/next --clear after fixing the bug`).
    
    ### 2. Delegate to sonnet subagent
    
    Spawn **one** subagent (`Agent` tool, `subagent_type: general-purpose`, `model: sonnet`) with prompt below. Do NOT run inspection commands yourself — point of delegation = keep main context clean.
    
    **Subagent prompt template** (fill `{flags}` and `{intent}` placeholders):
    
    ```
    You are inspecting Grimoire project state to suggest exactly ONE next slash command for the user to type. You are read-only — never edit, commit, or push.
    
    Flags from the user: {flags}     # e.g. "--clear", "--list", or "" (none)
    Free-text intent (optional): {intent}
    
    ## Step 1 — Snapshot state (parallel batch, single message, multiple Bash calls)
    
    - `git rev-parse --abbrev-ref HEAD`               # current branch
    - `git status --porcelain=v1`                     # never -uall
    - `git log -10 --oneline`                         # commit window
    - `git rev-list --count main..HEAD 2>/dev/null`   # commits ahead of main
    - `git diff --stat main...HEAD 2>/dev/null`       # changed-files summary
    - `gh pr view --json number,state,baseRefName,headRefName 2>/dev/null` # open PR for branch
    - `cat .claude/state/current_plan.md 2>/dev/null`                           # pointer to active plan (primary signal)
    - `ls -t .agents/plans/*.md 2>/dev/null | head -10`              # recent plans (mtime)
    - `ls -t .agents/plans/meta-plan_*.md 2>/dev/null | head -5`     # recent meta-plans
    
    ## Step 2 — Resolve active plan (Status block is primary signal)
    
    Resolution order — first match wins. **Steps 1+2 are read-only fast paths. Step 3 is the state-fixer fallback that prompts the user and persists their answer to `.claude/state/current_plan.md` so future invocations land in step 1.**
    
    ### Step 2a — `.claude/state/current_plan.md` pointer (preferred)
    
    If `current_plan.md` exists, parse it for the `**Plan:**` line. If the referenced plan file exists and has a `## Status` block (grep `^## Status$` to next `^## ` heading), use the block's `Active phase` + `Step` fields verbatim. Done — go to Step 3.
    
    ### Step 2b — Status block on most-recent plan
    
    If `current_plan.md` absent, glob `.agents/plans/plan_*.md` (mtime desc). For each, grep for `## Status` block. First match wins — use its fields. Don't read the whole plan, just the first 30 lines.
    
    ### Step 2c — Inferred-state fallback (state-fixer)
    
    If steps 2a+2b both fail (legacy plan with no Status block, or stale state, or no plan file matches), fall back to **commit-subject heuristic**:
    
    1. Identify newest plan via mtime: `ls -t .agents/plans/plan_*.md`
    2. Grep `^## Phase` headers in that plan to enumerate phases
    3. Grep commit subjects in `main..HEAD` (`git log --format=%s main..HEAD`)
    4. Cross-reference: a phase is **done** if its title (or commit-subject keywords from it, e.g. "load_exclusive", "grimoire lock") appears in any commit subject. The first phase with no commit-subject match is **active**.
    5. **Prompt the user via `AskUserQuestion`** with the inferred state:
    
           Inferred from commits + plan headers: plan=<X>, phase=<N> "<title>" active.
           Confirm and persist to .claude/state/current_plan.md?
    
       Options:
       - **Confirm + persist** (default) — write `current_plan.md`, inject `## Status` block at top of plan file (after H1, before next heading). Future `/next` invocations land in Step 2a.
       - **Different phase** — user names phase number; same persistence.
       - **No active plan** — write nothing, treat as Step 2d.
    
    If `--list` flag set, do not prompt — present the inferred phase as candidate #1 and let user pick.
    
    ### Step 2d — No active plan (valid empty state)
    
    If user picks "No active plan" in Step 2c, or no plan files exist at all:
    
    - `commits-ahead-of-main = 0` AND clean tree → say so explicitly, suggest browsing open issues/PRs (`gh issue list --state open --limit 5` or `/hex-plan "<task>"` for new work)
    - `commits-ahead > 0` AND no plan → suggest `/hex-plan` to capture the in-flight work as a tracked plan, OR `/commit` if there's a Checkpoint
    - Right after `/finalize` clears `current_plan.md` → "feature just landed, pick next PR/issue"
    
    Empty state is a **valid outcome**, not an error.
    
    ## Step 3 — Classify the phase
    
    Apply the first matching row. **Status-block fields beat heuristic table** when both apply.
    
    | Observed state                                                          | Suggest                                       |
    |---|---|
    | Status `Step: /hex-execute → ...` OR plan-approved OR phase done with next phase | `/hex-execute <tier> <plan-path>` |
    | Status `Step: /hex-review → round N`                                  | `/hex-review` (continue same round)         |
    | Status all phases done, dirty tree                                      | `/commit`                                     |
    | Status all phases done, clean tree, no PR                               | `/hex-review` then `/finalize`              |
    | On `main`                                                               | `/hex-plan "<task>"` — never work on main   |
    | Branch exists, no plan, no commits ahead                                | `/hex-plan "<task>"` (ask if no task named) |
    | Meta-plan exists, no `plan_*.md` yet                                    | Awaiting plan approval — print `/hex-plan`  |
    | Plan exists, 0 commits ahead, clean tree                                | `/hex-execute <plan-path>`                  |
    | Plan exists, commits ahead, dirty tree                                  | `/commit`                                     |
    | PR exists (state OPEN)                                                  | `/hex-review #<N>`                          |
    | Worktree branch (goat/evelynn/sion/soraka), multiple Checkpoints, clean | `/finalize` (only if Status confirms phases done) |
    | HEAD subject == `Checkpoint`, clean tree                                | `/commit` (will draft + amend)                |
    
    When two rows tie, pick the earlier (correctness > convenience). **Never suggest `/finalize` without confirming via Status block that no phases are still active** — that was the regression this skill is fixing.
    
    ## Step 4 — Synthesize the command
    
    Rules — strictly enforced when `--clear` is set; recommended otherwise:
    
    - Use absolute paths to plan artifacts (`.agents/plans/plan_X.md`).
    - Inline tier and overlay flags from the plan's handoff block when known (`/hex-execute max .agents/plans/plan_X.md`).
    - For `/hex-review`, prefer a PR number (`#61`) when an open PR exists; otherwise the branch name.
    - For `/commit` and `/finalize`, no arguments — they snapshot state themselves.
    - For `/hex-plan`, include a 1-line task description in quotes.
    - NEVER reference "the previous work" / "what we just discussed" / "the bug from earlier".
    - NEVER suggest a slash command that is not present in `.claude/rules.md` "Skills by task topic" — read that table if uncertain.
    
    ## Step 5 — Reply
    
    Output exactly one of these three formats. No preamble, no signature.
    
    DEFAULT (no flag):
    ~~~
    Next:
        <slash-command>
    
    Why:    <one-line reason>
    Looked at: <one-line list of state checks>
    ~~~
    
    --clear:
    ~~~
    Next (handover — context will be cleared):
        /clear
        <self-contained slash-command>
    
    Why:    <one-line reason>
    Looked at: <one-line list of state checks>
    Note: command is self-contained — safe to run after /clear.
    ~~~
    
    --list:
    ~~~
    Candidates:
      1. <slash-command>
           <one-line rationale, why this is #1>
      2. <slash-command>
           <one-line rationale>
      3. <slash-command>
           <one-line rationale>
    ~~~
    
    ## Edge cases
    
    - No git repo → reply: "not in a git repo — nothing to suggest". Exit.
    - Detached HEAD → suggest `git checkout <branch>` first; do not propose a hex command.
    - `gh` unavailable / unauthenticated → skip PR detection, fall through to branch baseline.
    - Multiple plans with mtime within 1h → list them, ask the user to pick (still one Candidates block).
    - Skill list expanded recently → re-read `.claude/rules.md` "Skills by task topic" before mapping. Never invent a skill. The `/hex-*` commands listed there are user-level and will not appear under `.claude/skills/` — that is expected.
    
    Keep your reply under 12 lines. The user will copy-paste from your output directly.
    ```
    
    ### 3. Print subagent's output verbatim
    
    Subagent already formatted output. Do not rewrap, summarise, comment. Print exactly what returned. If `--clear` set, subagent output already include `/clear` line — do not add another.
    
    If subagent report hard error (no git repo, detached HEAD, etc.), print message and stop.
    
    ## Constraints
    
    - NEVER edit code, commit, push.
    - May write `.claude/state/current_plan.md` and inject `## Status` block into a plan **only via user-confirmed Step 2c state-fixer path**. Never silently mutate state. The user's `AskUserQuestion` answer is consent.
    - NEVER run inspection commands in main session — subagent's job. Skip delegation = defeat context-isolation.
    - NEVER suggest a slash command that is neither in `.claude/skills/` nor a hex command (`/hex-init`, `/hex-plan`, `/hex-execute`, `/hex-review`, `/hex-architect`) — hex ships at user level, so its absence from `.claude/skills/` is expected, not an invented skill. Subagent cross-checks `.claude/rules.md`; main session no second-guess.
    - ALWAYS spawn exactly one subagent. No parallelism — only one question asked.
    - NEVER suggest `/finalize` without confirming via Status block that all phases are marked done. (See Step 3 table — premature finalize was the regression that motivated this skill's redesign.)
    
    ## References
    
    - `.claude/rules.md` — "Skills by task topic" (authoritative skill list — subagent reads it)
    - `.claude/rules/workflow-intent.md` — work-type router
    - `.claude/rules/workflow-git.md` — branching, two-phase commit/finalize
    - `.claude/rules/meta-ai-config.md` "Plan Status Protocol" — schema + per-skill mutation table; `.claude/state/` tree is gitignored (per-worktree)
    - `/hex-execute`'s closing handoff — the pattern this skill emulates

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.