claudetools/.claude/commands/feature-request.md

GuruRMM Feature Request — Comprehensive Analysis & Specification

When Howard (or Mike) submits a feature request, conduct full research and produce a detailed specification with implementation recommendations.

---

## Phase 1 — Context Loading

1. **Read identity and machine info:**
   - `.claude/identity.json` — hostname, user, Ollama endpoint

2. **Read project documentation:**
   - `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` — existing features, structure, priorities
   - `projects/msp-tools/guru-rmm/docs/UI_GAPS.md` — current UI implementation status
   - `.claude/CODING_GUIDELINES.md` — code standards, patterns, architecture rules
   - `projects/msp-tools/guru-rmm/CONTEXT.md` — current project state, tech stack, architecture

3. **Determine Ollama endpoint:**
   - `DESKTOP-0O8A1RL`: `http://localhost:11434`
   - All other machines: `http://100.92.127.64:11434`

---

## Phase 2 — Initial Classification (Ollama)

Call Ollama with model `qwen3.6:latest` (strict JSON) to perform initial classification:

**Prompt:**
```
You are analyzing a feature request for GuruRMM, a Rust/Axum/TypeScript RMM tool for MSPs.

Roadmap sections: Core Agent Features, Server/API Features, Dashboard & UI, Platform & Infrastructure, Integrations, Security Features, Future Considerations.

Feature request: $ARGUMENTS

Respond with JSON only:
{
  "section": "...",
  "subsection": "...",
  "priority": "P1|P2|P3",
  "brief_summary": "1-2 sentence plain English summary",
  "similar_features": ["list of similar/related features that might already exist"],
  "research_needed": ["list of areas requiring investigation before implementation"]
}
```

If Ollama unreachable, perform classification yourself.

---

## Phase 3 — Research & Investigation

Based on the classification and research_needed list:

### 3.1 — Codebase Search
Search for similar/related implementations:
- Use Grep to search for related functionality in `projects/msp-tools/guru-rmm/`
- Check `server/src/` for API patterns
- Check `agent/src/` for agent-side functionality
- Check `dashboard/src/` for UI patterns
- Identify existing code that could be extended vs. new code needed

### 3.2 — External Research (if needed)
If the feature involves:
- Industry standards (e.g., SNMP, Syslog, API protocols): WebSearch for best practices
- Security implications: Research common vulnerabilities and mitigations
- Third-party integrations: Check if APIs/SDKs exist
- Platform-specific behavior: Research OS-level APIs (Windows/Linux/macOS)

### 3.3 — Architecture Analysis
Consider:
- Where does this feature fit in the architecture? (agent, server, dashboard, all three?)
- What database schema changes are needed?
- What API endpoints are needed?
- Are there performance/scalability implications?
- Security considerations?

---

## Phase 4 — Consult Coding Guidelines

Read `.claude/CODING_GUIDELINES.md` and identify relevant patterns:
- Error handling requirements
- API design patterns
- Database conventions
- Frontend patterns
- Security requirements
- Testing requirements

---

## Phase 5 — Specification Generation (Ollama)

Use Ollama with model `qwen3:14b` (prose) to generate comprehensive specification:

**Prompt:**
```
You are writing a detailed implementation specification for a GuruRMM feature.

FEATURE REQUEST: $ARGUMENTS

RESEARCH FINDINGS:
- Classification: <section/subsection/priority>
- Similar existing features: <list>
- Codebase search results: <relevant files/patterns found>
- External research: <standards, best practices, security considerations>
- Architecture fit: <where it belongs in the system>

CODING GUIDELINES REQUIREMENTS:
<relevant excerpts from CODING_GUIDELINES.md>

Write a comprehensive specification with these sections:

1. OVERVIEW
   - What the feature does (2-3 sentences)
   - User-facing benefit
   - Primary use cases

2. SCOPE
   - What's included in v1
   - What's explicitly out of scope (for future)
   - Success criteria

3. ARCHITECTURE
   - Components involved (agent/server/dashboard)
   - Data flow
   - Database schema changes
   - API endpoints needed

4. IMPLEMENTATION DETAILS
   Agent (if applicable):
   - Files to modify/create
   - Rust structs/enums needed
   - IPC commands (if any)

   Server (if applicable):
   - API routes
   - Database migrations
   - Business logic modules

   Dashboard (if applicable):
   - New pages/components
   - State management
   - API integration

5. SECURITY CONSIDERATIONS
   - Authentication/authorization requirements
   - Input validation
   - Audit logging
   - Potential vulnerabilities and mitigations

6. TESTING STRATEGY
   - Unit tests needed
   - Integration tests
   - Manual test scenarios

7. ROLLOUT PLAN
   - Feature flag approach
   - Backward compatibility
   - Migration path
   - Documentation needs

8. EFFORT ESTIMATE
   - Small (1-2 days), Medium (3-5 days), Large (1-2 weeks), X-Large (2+ weeks)
   - Breakdown by component

Be specific and actionable. Reference actual file paths, struct names, and patterns from the codebase.
```

If Ollama unreachable, write the specification yourself using the research findings.

---

## Phase 6 — Roadmap Placement Analysis

Analyze the FEATURE_ROADMAP.md structure to determine:

1. **Exact placement:** Which existing subsection does this belong in? Or does it need a new subsection?

2. **Build sequencing:** Based on the roadmap structure and existing priorities:
   - What features must be built before this one? (dependencies)
   - What features does this unblock? (enables)
   - Which sprint/milestone does this fit into?

3. **Priority justification:**
   - P1: Blocks other critical features, security-critical, or MVP requirement
   - P2: Important for competitive parity, customer requests, or usability
   - P3: Nice-to-have, future enhancement, or edge case

---

## Phase 7 — Write Specification Document

Create a new file: `projects/msp-tools/guru-rmm/docs/specs/SPEC-XXX-<feature-name>.md`

Where XXX is the next available number (check existing specs directory).

**File format:**
```markdown
# SPEC-XXX: <Feature Name>

**Status:** Proposed
**Priority:** P1/P2/P3
**Requested By:** <Howard|Mike> (<date>)
**Estimated Effort:** <Small|Medium|Large|X-Large>

---

## Overview
<2-3 sentence summary>

**Use Cases:**
- <primary use case>
- <secondary use case>

**Success Criteria:**
- <measurable criteria>

---

## Scope

### Included in v1
- <feature 1>
- <feature 2>

### Explicitly Out of Scope
- <future enhancement>

---

## Architecture

### Components
- **Agent:** <what agent does>
- **Server:** <what server does>
- **Dashboard:** <what dashboard does>

### Data Flow
<step-by-step description or diagram>

### Database Schema
```sql
-- New tables or columns
```

### API Endpoints
- `POST /api/...` — <description>
- `GET /api/...` — <description>

---

## Implementation Details

### Agent (`agent/src/`)
**Files to modify:**
- `agent/src/xyz.rs` — <what changes>

**New structs/enums:**
```rust
// Example code
```

### Server (`server/src/`)
**Files to modify:**
- `server/src/routes/xyz.rs` — <what changes>

**Database migrations:**
- `migrations/YYYYMMDD_feature_name.sql`

### Dashboard (`dashboard/src/`)
**New components:**
- `dashboard/src/components/XyzFeature.tsx` — <description>

**API integration:**
- Use `useQuery` for GET, `useMutation` for POST/PUT

---

## Security Considerations

- **Authentication:** <requirements>
- **Authorization:** <who can access>
- **Input Validation:** <validation rules>
- **Audit Logging:** <what to log>
- **Threat Model:** <potential attacks and mitigations>

---

## Testing Strategy

### Unit Tests
- `agent/tests/xyz_test.rs` — <test scenarios>
- `server/tests/api/xyz_test.rs` — <test scenarios>

### Integration Tests
- <end-to-end test scenarios>

### Manual Testing
1. <test step 1>
2. <test step 2>

---

## Rollout Plan

1. **Feature flag:** `feature.xyz.enabled` (default: false)
2. **Database migration:** Apply schema changes
3. **Agent update:** Deploy agent with feature flag check
4. **Dashboard deploy:** UI available when feature enabled
5. **Documentation:** Update user guide

### Backward Compatibility
<how older agents/servers handle this>

---

## Dependencies

**Must be completed first:**
- <existing feature or infrastructure>

**Enables future features:**
- <what this unblocks>

---

## Open Questions
- <question 1>
- <question 2>

---

## References
- Related roadmap section: <link>
- Similar implementations: <links to code>
- External documentation: <links>

---

**Next Steps:**
1. Review specification with team
2. Refine based on feedback
3. Move to sprint backlog
4. Assign to developer
```

---

## Phase 8 — Update Roadmap

Add or update the feature in `FEATURE_ROADMAP.md`:

- If it fits an existing subsection, add it there
- If it needs a new subsection, create one
- Link to the spec document: `[Feature Name](docs/specs/SPEC-XXX-feature-name.md) - P2`
- Add checkboxes for sub-tasks if applicable

---

## Phase 9 — Commit Changes

```bash
cd projects/msp-tools/guru-rmm
git add docs/specs/SPEC-XXX-feature-name.md docs/FEATURE_ROADMAP.md
git commit -m "spec: add SPEC-XXX <feature name>

Comprehensive specification for <brief description>.
Requested by <Howard|Mike>.

- Full architecture analysis
- Implementation details across agent/server/dashboard
- Security considerations
- Effort estimate: <Small|Medium|Large|X-Large>
- Priority: P1/P2/P3
- Added to roadmap under <section>/<subsection>"

git push origin main
```

Then update submodule pointer in parent repo:
```bash
cd /Users/azcomputerguru/ClaudeTools
git add projects/msp-tools/guru-rmm
git commit -m "chore: update guru-rmm submodule (SPEC-XXX <feature name>)"
git push origin main
```

---

## Phase 10 — Send Coord Message (if requested by Howard)

If Howard submitted this (not Mike), send a coord message:

```bash
curl -s -X POST http://172.16.3.30:8001/api/coord/messages \
  -H "Content-Type: application/json" \
  -d '{
    "from_session": "<HOSTNAME>/claude-main",
    "to_session": "ALL_SESSIONS",
    "project_key": "gururmm",
    "subject": "Feature Spec Complete: <feature name>",
    "body": "Howard submitted a feature request. Full specification created.\n\nSPEC: docs/specs/SPEC-XXX-<feature-name>.md\n\nPriority: <P1/P2/P3>\nEffort: <Small|Medium|Large|X-Large>\nPlacement: <section>/<subsection>\n\nSummary:\n<2-3 sentence summary>\n\nReady for review and sprint planning."
  }'
```

---

## Phase 11 — Response to User

Provide a comprehensive summary:

```
[SUCCESS] Feature specification created

SPEC-XXX: <Feature Name>
Priority: P1/P2/P3
Effort: <Small|Medium|Large|X-Large>
Placement: <section>/<subsection>

OVERVIEW
<2-3 sentence summary>

KEY COMPONENTS
- Agent: <brief>
- Server: <brief>
- Dashboard: <brief>

SECURITY CONSIDERATIONS
- <key security points>

DEPENDENCIES
- Requires: <list>
- Enables: <list>

FILES CREATED
- docs/specs/SPEC-XXX-<feature-name>.md (full specification)
- Updated FEATURE_ROADMAP.md

The specification includes:
✓ Complete architecture analysis
✓ Implementation details for all components
✓ Security threat model and mitigations
✓ Testing strategy
✓ Rollout plan with feature flags
✓ Effort breakdown

<If Howard submitted:>
Coord message sent to Mike for review and sprint planning.

<Next steps based on priority:>
P1: Schedule for immediate sprint
P2: Add to near-term backlog
P3: Track for future consideration
```

---

## Error Handling

- If Ollama unreachable: Perform all analysis yourself (no degradation)
- If coord API fails: Warn user but continue (they can manually notify Mike)
- If spec number conflicts: Check existing specs and use next available
- If roadmap section unclear: Create new subsection rather than force-fit

---

## Notes

- This command can take 2-5 minutes due to research and specification generation
- The specification is a living document — can be refined during sprint planning
- Feature flags ensure safe rollout even for partially complete features
- Effort estimates are initial and may be revised during implementation