@raftlabs/raftstack 1.8.0 → 1.9.1

package/.claude/commands/raftstack/discover.md

@@ -0,0 +1,205 @@
+# RaftStack: Discover and Extract Patterns
+
+Analyze a specific area of the codebase and extract patterns into reusable standards.
+
+## Arguments
+
+- `$ARGUMENTS` - (Optional) Focus area to analyze (e.g., "API", "components", "database", "error handling")
+
+## Tool Usage
+
+**IMPORTANT:** Always use the `AskUserQuestion` tool for:
+- Focus area selection
+- Standard creation decisions
+- Location negotiation
+- Option selection
+
+Never use plain text questions - always use the structured `AskUserQuestion` tool.
+
+## Phase 1: Focus Selection
+
+If no focus area provided, use `AskUserQuestion` with these options:
+- Option A: API/Backend - Route structure, error handling, validation
+- Option B: Components - File structure, prop patterns, styling
+- Option C: Database - Schema conventions, query patterns
+- Option D: Other (let user specify)
+
+**Common areas:**
+- **API/Backend** - Route structure, error handling, validation, response formats
+- **Components** - File structure, prop patterns, state management, styling
+- **Database** - Schema conventions, query patterns, migrations
+- **Error Handling** - Error types, logging, user-facing messages
+- **Testing** - Test structure, mocking patterns, coverage approach
+- **Authentication** - Auth flow, session management, permissions
+- **Utilities** - Helper function patterns, shared logic
+
+## Phase 2: Deep Pattern Analysis
+
+For the selected area, analyze:
+
+1. **Find representative files:**
+   - Locate 3-5 files that implement this pattern well
+   - Note file paths for reference
+
+2. **Extract structural patterns:**
+   - File naming convention
+   - Directory organization
+   - Export patterns
+
+3. **Extract code patterns:**
+   - Common function signatures
+   - Type definitions
+   - Error handling approach
+   - Import structure
+
+4. **Identify conventions:**
+   - Naming (variables, functions, types)
+   - Formatting preferences
+   - Comment style
+
+## Phase 3: Pattern Analysis Summary
+
+After analyzing patterns, present:
+
+```markdown
+## ✅ Pattern Discovery Completed
+
+### 🎯 Key Patterns Found (Top 3)
+1. **[Pattern Name]** - Location: `path/to/files/`
+   - [Brief description of pattern]
+2. **[Pattern Name]** - Location: `path/to/files/`
+   - [Brief description of pattern]
+3. **[Pattern Name]** - Location: `path/to/files/`
+   - [Brief description of pattern]
+
+### 📋 Files Analyzed
+- `path/to/file1.ts` - [what it demonstrates]
+- `path/to/file2.ts` - [what it demonstrates]
+- `path/to/file3.ts` - [what it demonstrates]
+
+### 🔍 Consistency Assessment
+- ✅ **Consistent:** [list consistent patterns]
+- ⚠️ **Inconsistent:** [list inconsistencies with file references]
+
+### ⚠️ Technical Debt Noted
+- [Debt item] - **Impact:** [why it matters] - **Files:** [affected files]
+- [Debt item] - **Impact:** [why it matters] - **Files:** [affected files]
+
+### 🔄 Recommended Standards to Create
+1. **[Standard Name]** - Captures: [what pattern]
+2. **[Standard Name]** - Captures: [what pattern]
+3. **[Standard Name]** - Captures: [what pattern]
+
+**Your options:** [A] Create all standards [B] Select specific standards [C] Analyze another area [D] Skip standardization
+```
+
+Use `AskUserQuestion` for options.
+
+## Phase 4: Standard Creation
+
+For each selected pattern, create a standard document:
+
+```markdown
+# [Pattern Name] Standard
+
+## Purpose
+[Why this pattern exists]
+
+## When to Use
+[Situations where this applies]
+
+## Pattern
+
+### Structure
+[File/directory structure]
+
+### Code Template
+```typescript
+// Template with placeholders
+[code template]
+```
+
+### Examples
+[Real examples from codebase with file paths]
+
+## Anti-patterns
+[What NOT to do]
+
+## References
+- [Link to related file in codebase]
+- [Link to related skill if applicable]
+```
+
+## Phase 5: Location Negotiation
+
+Use `AskUserQuestion` with these options:
+- Option A: `.claude/standards/[area]/` - Claude-specific standards folder (Recommended)
+- Option B: `docs/standards/[area]/` - With project documentation
+- Option C: `standards/[area]/` - At project root
+- Option D: Other (let user specify)
+
+## Phase 6: Completion Summary
+
+After creating standards, present:
+
+```markdown
+## ✅ Standards Created
+
+### 🎯 What Was Created
+1. **[Standard Name]** - **Location:** `path/to/standard.md`
+   - Captures: [what pattern]
+2. **[Standard Name]** - **Location:** `path/to/standard.md`
+   - Captures: [what pattern]
+
+### 📋 Standards Contents
+| Standard | Patterns Captured | Examples Included |
+|----------|-------------------|-------------------|
+| [Name] | [List] | [Count] |
+
+### 🔍 Coverage Assessment
+- **Fully Covered:** [list of patterns now documented]
+- **Partially Covered:** [patterns that could use more detail]
+- **Not Covered:** [patterns skipped for now]
+
+### ⚠️ Follow-up Recommendations
+- **Run `/raftstack/index`** - Update the standards registry
+- **Run `/raftstack/inject [area]`** - Use these standards when working on related code
+
+### 🔄 What This Enables
+- **Option A:** Run `/raftstack/index` - Update standards registry
+- **Option B:** Run `/raftstack/discover [other-area]` - Analyze another area
+- **Option C:** Run `/raftstack/inject [area]` - Test the new standards
+- **Option D:** Done for now
+
+**Your options:** [A] Index standards [B] Discover more [C] Test with inject [D] Done
+```
+
+Use `AskUserQuestion` for final options.
+
+## Example Session
+
+**User:** `/raftstack/discover API`
+
+**AI analyzes API routes, finds patterns:**
+- RESTful structure with `/api/[resource]/route.ts`
+- Zod validation on all inputs
+- Consistent error response format
+- Auth middleware pattern
+
+**AI presents Pattern Analysis Summary**
+
+**User selects:** [B] Select specific standards
+
+**AI uses AskUserQuestion:** Which patterns to document?
+- [A] Error handling
+- [B] Validation
+- [C] Auth middleware
+- [D] All of the above
+
+**User selects:** Error handling and Validation
+
+**AI creates:**
+- `.claude/standards/api/error-handling.md`
+- `.claude/standards/api/validation.md`
+
+**AI presents Completion Summary with next steps**

package/.claude/commands/raftstack/help.md

@@ -0,0 +1,309 @@
+# RaftStack: Help & Guidance
+
+Guide the user on what to do next based on their current project state.
+
+## Tool Usage
+
+**IMPORTANT:** Always use the `AskUserQuestion` tool for:
+- Presenting recommendations
+- Showing command options
+- Getting user preferences
+
+Never use plain text questions - always use the structured `AskUserQuestion` tool.
+
+## Phase 1: Detect Current State
+
+Check for existing RaftStack artifacts:
+
+### Constitution/Context
+- `.claude/context/constitution.md` → Has project context
+- `CONSTITUTION.md` → Has project context
+- `docs/constitution.md` → Has project context
+
+### Standards
+- `.claude/standards/**/*.md` → Has standards
+- `docs/standards/**/*.md` → Has standards
+- `standards/**/*.md` → Has standards
+- `*.standard.md` → Has standards
+
+### Specs
+- `.claude/specs/**/*` → Has feature specs
+- `docs/specs/**/*` → Has feature specs
+- `specs/**/*` → Has feature specs
+
+### Skills
+- `.claude/skills/*/SKILL.md` → Has RaftStack skills installed
+
+### Registry
+- `.claude/standards/REGISTRY.md` → Has standards registry
+- `.claude/REGISTRY.md` → Has standards registry
+- `docs/REGISTRY.md` → Has standards registry
+
+## Phase 2: Assess Project State
+
+Categorize the project state:
+
+### New to RaftStack (No artifacts found)
+- No constitution
+- No standards
+- No skills
+
+### Partially Set Up
+- Has constitution but no standards
+- Has standards but no registry
+- Has skills but no project-specific standards
+
+### Fully Set Up
+- Has constitution
+- Has standards
+- Has registry (recently updated)
+- Has skills
+
+### Needs Maintenance
+- Has artifacts but registry is outdated (>30 days)
+- Has standards that may have drifted
+
+## Phase 3: Present State Summary
+
+Show the user their current state:
+
+```markdown
+## 📊 RaftStack Project Status
+
+### Artifacts Found
+| Artifact | Status | Location |
+|----------|--------|----------|
+| Constitution | [✅ Found / ❌ Missing] | [path or -] |
+| Standards | [[N] found / ❌ None] | [path or -] |
+| Registry | [✅ Found / ❌ Missing] | [path or -] |
+| Specs | [[N] found / ❌ None] | [path or -] |
+| Skills | [✅ Installed / ❌ Missing] | [path or -] |
+
+### Health Assessment
+- **Overall:** [New / Partially Set Up / Ready / Needs Maintenance]
+- **Last Registry Update:** [date or Never]
+- **Standards Coverage:** [list of domains covered]
+```
+
+## Phase 4: Determine Recommendation
+
+Based on state, recommend next action:
+
+### If no constitution:
+**Recommended:** `/raftstack/init-context`
+> "Start by analyzing your codebase and generating a constitution. This captures your project's structure, patterns, and conventions."
+
+### If constitution but no standards:
+**Recommended:** `/raftstack/discover`
+> "You have project context. Consider extracting patterns from your code as reusable standards."
+
+### If standards but no registry:
+**Recommended:** `/raftstack/index`
+> "You have standards but no registry. Index them to enable easy discovery and drift detection."
+
+### If starting new work:
+**Recommended:** `/raftstack/shape`
+> "Use shape to plan your feature with the right level of detail - from quick fixes to full specs."
+
+### If working on code:
+**Recommended:** `/raftstack/inject`
+> "Surface relevant standards and skills for your current task to ensure consistency."
+
+### If registry is outdated (>30 days):
+**Recommended:** `/raftstack/index`
+> "Your standards registry hasn't been updated recently. Re-index to check for drift and updates."
+
+### If fully set up and current:
+**Recommended:** Based on what user wants to do
+> "Your RaftStack setup is complete and current. What would you like to work on?"
+
+## Phase 5: Present Options
+
+Use `AskUserQuestion` with context-appropriate options:
+
+### For New Projects
+```markdown
+**Recommended next step:** `/raftstack/init-context`
+Start by generating a constitution that captures how your project works.
+
+**Your options:**
+- [A] Initialize project context (Recommended) - Generate a constitution
+- [B] Skip to discover patterns - Extract standards from existing code
+- [C] Show all commands - See everything RaftStack can do
+- [D] Not now - Exit help
+```
+
+### For Partially Set Up Projects
+```markdown
+**Recommended next step:** [Based on what's missing]
+[Explanation of why this is recommended]
+
+**Your options:**
+- [A] [Recommended action] (Recommended)
+- [B] [Alternative action]
+- [C] Show all commands
+- [D] Not now
+```
+
+### For Ready Projects
+```markdown
+**Your RaftStack setup is complete!**
+
+**What would you like to do?**
+- [A] Shape a new feature - Plan work with /raftstack/shape
+- [B] Inject context - Surface standards for current work
+- [C] Check for drift - Re-index and detect changes
+- [D] Show all commands
+```
+
+## Phase 6: All Commands Reference
+
+If user requests to see all commands:
+
+```markdown
+## RaftStack Commands Reference
+
+### Setup & Context
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/raftstack/init-context` | Generate constitution | New project or first setup |
+| `/raftstack/index` | Update standards registry | Standards changed, check drift |
+
+### Planning & Discovery
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/raftstack/shape [task]` | Plan feature/task | Starting any new work |
+| `/raftstack/discover [area]` | Extract patterns | Document existing code patterns |
+
+### Working with Code
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/raftstack/inject [domain]` | Surface context | Before coding, need guidance |
+
+### Help
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/raftstack/help` | Get guidance | Unsure what to do next |
+
+---
+
+### Quick Start Guide
+
+1. **First time?** Run `/raftstack/init-context` to analyze your project
+2. **Have patterns?** Run `/raftstack/discover` to document them as standards
+3. **Starting work?** Run `/raftstack/shape [task]` to plan your approach
+4. **Need guidance?** Run `/raftstack/inject [domain]` to surface relevant standards
+
+**Your options:** [A] Run a command [B] Back to recommendations [C] Exit help
+```
+
+Use `AskUserQuestion` for navigation.
+
+## Example Sessions
+
+### Example 1: New Project
+
+**User:** `/raftstack/help`
+
+**AI detects:** No RaftStack artifacts found
+
+**AI responds:**
+```markdown
+## 📊 RaftStack Project Status
+
+### Artifacts Found
+| Artifact | Status | Location |
+|----------|--------|----------|
+| Constitution | ❌ Missing | - |
+| Standards | ❌ None | - |
+| Registry | ❌ Missing | - |
+| Specs | ❌ None | - |
+| Skills | ✅ Installed | `.claude/skills/` |
+
+### Health Assessment
+- **Overall:** New to RaftStack
+- **Last Registry Update:** Never
+- **Standards Coverage:** None
+
+---
+
+**Recommended next step:** `/raftstack/init-context`
+Start by generating a constitution that captures how your project works. This analyzes your codebase structure, patterns, and conventions.
+```
+
+**Uses AskUserQuestion:**
+- [A] Initialize project context (Recommended)
+- [B] Skip to discover patterns
+- [C] Show all commands
+- [D] Not now
+
+### Example 2: Ready Project
+
+**User:** `/raftstack/help`
+
+**AI detects:** Constitution, 5 standards, registry (3 days old), skills
+
+**AI responds:**
+```markdown
+## 📊 RaftStack Project Status
+
+### Artifacts Found
+| Artifact | Status | Location |
+|----------|--------|----------|
+| Constitution | ✅ Found | `.claude/context/constitution.md` |
+| Standards | 5 found | `.claude/standards/` |
+| Registry | ✅ Found | `.claude/standards/REGISTRY.md` |
+| Specs | 2 found | `.claude/specs/` |
+| Skills | ✅ Installed | `.claude/skills/` |
+
+### Health Assessment
+- **Overall:** Ready
+- **Last Registry Update:** 3 days ago
+- **Standards Coverage:** API, React, Database
+
+---
+
+**Your RaftStack setup is complete and current!**
+```
+
+**Uses AskUserQuestion:**
+- [A] Shape a new feature - Plan work with scale-adaptive depth
+- [B] Inject context - Surface standards for current task
+- [C] Check for drift - Re-index and detect changes
+- [D] Show all commands
+
+### Example 3: Needs Maintenance
+
+**User:** `/raftstack/help`
+
+**AI detects:** Constitution, standards, but registry is 45 days old
+
+**AI responds:**
+```markdown
+## 📊 RaftStack Project Status
+
+### Artifacts Found
+| Artifact | Status | Location |
+|----------|--------|----------|
+| Constitution | ✅ Found | `.claude/context/constitution.md` |
+| Standards | 3 found | `.claude/standards/` |
+| Registry | ⚠️ Outdated | `.claude/standards/REGISTRY.md` |
+| Specs | ❌ None | - |
+| Skills | ✅ Installed | `.claude/skills/` |
+
+### Health Assessment
+- **Overall:** Needs Maintenance
+- **Last Registry Update:** 45 days ago ⚠️
+- **Standards Coverage:** API, React
+
+---
+
+**Recommended next step:** `/raftstack/index`
+Your standards registry is over 30 days old. Re-index to check for drift and ensure standards are still accurate.
+```
+
+**Uses AskUserQuestion:**
+- [A] Re-index standards (Recommended) - Check for drift
+- [B] Shape a new feature - Plan work
+- [C] Show all commands
+- [D] Not now