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`

```markdown
# <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/<SLUG>/
git commit -m "spec: add <feature-slug> 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`

```markdown
# <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`

```markdown
# <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`

```markdown
# <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