azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement agent-os standards system and feature planning tools

Browse Source 
- Split CODING_GUIDELINES.md into 19 indexed standards files under .claude/standards/
  - 9 from CODING_GUIDELINES (conventions, powershell, security, api, git, gururmm)
  - 10 from session log tribal knowledge (syncro, ssh, gitea, python, client, gururmm)
- Add .claude/standards/index.yml for cheap relevance-based lookup
- Add /inject-standards command: load targeted standards per task instead of full guidelines
- Add /shape-spec command: pre-implementation spec for GuruRMM features (plan.md,
  shape.md, references.md, standards.md) with mandatory out-of-scope gate
- Add docs/tech-stack.md and docs/mission.md for ClaudeTools API
- Add projects/msp-tools/guru-rmm/docs/tech-stack.md and mission.md for GuruRMM
- Update CLAUDE.md commands table with /inject-standards and /shape-spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-05-16 12:59:49 -07:00
parent 2fa8295ad0
commit dd0ef45645
26 changed files with 1757 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
.claude/commands/shape-spec.md Normal file
View File

@@ -0,0 +1,218 @@
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