claudetools/.claude/commands/shape-spec.md

Pre-implementation planning command for a GuruRMM feature. Produces a structured spec folder in specs/<slug>/ that persists across sessions, eliminating the need to re-explain context when resuming work.

---

Input

$ARGUMENTS = feature name slug (e.g., policy-wiring, asset-location-tracking, windows-update-check).

If $ARGUMENTS is empty, ask the user: "What should the feature slug be? Use kebab-case (e.g., windows-update-check)." Wait for the answer before continuing.

Set SLUG = the feature slug (lowercase, kebab-case). Set SPEC_DIR = specs/<SLUG>.

---

Phase 1 — Feature description

Ask the user in a single message (wait for response before continuing):

What does this feature do? Give me a user-facing description — what a user sees or what the system does.

What problem does it solve, or what prompted this? (ticket, gap report, field request, etc.)

Do NOT proceed to Phase 2 until the user responds.

---

Phase 2 — Scope boundaries

Ask the user in a single message (wait for response before continuing):

A few scoping questions:

1. What is explicitly OUT of scope for this implementation? What should we NOT build yet?
2. Are there any hard constraints? (e.g., must work offline, no new crates/dependencies, must not touch the agent binary)
3. Priority level: P1 (blocking other work), P2 (important, near-term), or P3 (nice-to-have)?

If the user does not provide out-of-scope items, ask specifically before writing any files:

"I need at least one explicit non-goal for shape.md — what should this implementation deliberately NOT do?"

Do NOT write any files until both Phase 1 and Phase 2 are complete and out-of-scope items exist.

---

Phase 3 — Codebase research (no user input needed)

Search the codebase for relevant context. Use Grep — do NOT open files just to scan them.

Search targets:

• Files or functions that will be touched or extended by this feature
• Similar existing implementations (e.g., if adding a new agent metric, find how other metrics are collected and reported)
• The feature roadmap: projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md — search for the slug keywords and adjacent section headers

Collect:

• File paths and a brief note on what each does and what will need to change
• Any existing pattern (with file:line) that this feature should follow
• The roadmap section/entry if one exists

---

Phase 4 — Standards matching (no user input needed)

Read .claude/standards/index.yml if it exists. If it does not exist, Glob .claude/standards/**/*.md to discover available standards files, and read the frontmatter of each.

Select the standards that apply to this feature. Minimum defaults:

Feature type	Standards to include
Rust agent feature	conventions/no-emojis, conventions/output-markers (for any shell scripts), plus any gururmm-specific standards found
Server/API feature	any api/ standards found
Dashboard/UI feature	conventions/output-markers, any frontend standards found
Git/build workflow	any git/ or gitea/ standards found
Any script output	conventions/output-markers

When in doubt, include the standard — it costs nothing to list it.

---

Phase 5 — Write spec files

Write all four files. Do not ask for confirmation before writing — the user approved the spec by completing Phases 1 and 2.

specs/<SLUG>/plan.md

# <Feature Name> — Implementation Plan

> Spec created: <date>
> Status: not started

## Task 0: Commit this spec

Commit the `specs/<SLUG>/` directory before writing any code:

git add specs// git commit -m "spec: add shape spec"

Do not start Task 1 until this commit exists.

## Task 1: [first concrete implementation step]

Files touched: `path/to/file.rs`, `path/to/other.rs`

[Description of what to do, specific enough that a future session can start without re-reading the full conversation]

## Task 2: [next step]

Files touched: ...

[Description]

[... continue for all tasks ...]

## Task N: Verification

How to confirm the feature works end-to-end:
- [specific check 1 — e.g., run agent on Windows, confirm metric appears in dashboard]
- [specific check 2]
- [expected log output or API response]

Rules for plan.md:

• Task 0 is always "commit this spec" — never omit it
• Each task names the specific files it touches
• Tasks must be specific enough that a future Claude session reading only specs/<SLUG>/ can continue without re-reading the conversation
• The final task is always verification with concrete, observable checks

specs/<SLUG>/shape.md

# <Feature Name> — Shape & Constraints

## What this is

[1-2 sentence description — what the user sees or what the system does]

## What this is NOT (out of scope)

- [explicit non-goal 1]
- [explicit non-goal 2]
[at least one item is required — do not write this file without it]

## Hard constraints

- [constraint 1 — or "None stated" if user provided none]

## Key decisions

- [decision + rationale — derived from Phase 1/2 answers and Phase 3 codebase research]

## Priority

P1 | P2 | P3  ← keep only the one that applies

## Roadmap reference

[Link to section in `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` if found in Phase 3, or "Not yet in roadmap"]

specs/<SLUG>/references.md

# <Feature Name> — Code References

## Files that will be touched

- `path/to/file.rs` — [what it does, what needs to change]

## Similar existing implementations

- `path/to/similar.rs:<line>` — [how this pattern is already done, what to follow]

[If no similar implementations were found, write: "No directly analogous implementation found in current codebase."]

## Database schema (if applicable)

[Relevant existing tables, or the migration pattern used by other features, or "No database changes required"]

specs/<SLUG>/standards.md

# <Feature Name> — Applicable Standards

The following standards from `.claude/standards/` apply to this feature:

## <standard name>

[The key rule from that standard most relevant to this feature]

Source: `.claude/standards/<relative-path>.md`

[Repeat for each applicable standard]

---

After writing files

Tell the user:

• The spec was written to specs/<SLUG>/ (list all four files)
• Task 0 in plan.md is to commit the spec before writing any code — do it now with /checkpoint or git add specs/<SLUG>/ && git commit -m "spec: add <SLUG> shape spec"
• To load this spec in a future session: read all four files in specs/<SLUG>/ — that is the full context needed to resume
• plan.md is the source of truth for implementation order; check tasks off by adding [DONE] markers as they complete

---

Quality rules

• Do NOT start writing files until Phase 1 AND Phase 2 are complete and at least one out-of-scope item exists
• Use Grep to find code references — never open files speculatively to scan for context
• Task 0 in plan.md is always "commit this spec" — non-negotiable
• shape.md must have at least one explicit out-of-scope item — ask before writing if the user didn't provide any
• Do not invent file paths for references.md — only include paths found via Grep in Phase 3
• Standards.md must name at least one standard — if index.yml does not exist, Glob the standards directory