@raftlabs/raftstack 1.8.0 → 1.9.1

package/.claude/commands/raftstack/index.md

@@ -0,0 +1,259 @@
+# RaftStack: Index Standards Registry
+
+Scan for standards files and maintain a registry. Works with any directory structure.
+
+## Purpose
+
+Keep track of all standards and context files in the project, regardless of where they're stored.
+
+## Tool Usage
+
+**IMPORTANT:** Always use the `AskUserQuestion` tool for:
+- Location negotiation
+- Drift resolution decisions
+- Follow-up options
+
+Never use plain text questions - always use the structured `AskUserQuestion` tool.
+
+## Phase 1: Scan for Standards
+
+Search common locations for standards files:
+
+1. **Standard locations:**
+   - `.claude/standards/**/*.md`
+   - `.claude/context/**/*.md`
+   - `docs/standards/**/*.md`
+   - `standards/**/*.md`
+   - `*.standard.md` (root level)
+
+2. **Context files:**
+   - `CONSTITUTION.md`
+   - `.claude/context/constitution.md`
+   - `docs/constitution.md`
+
+3. **Skills (RaftStack-provided):**
+   - `.claude/skills/*/SKILL.md`
+
+## Phase 2: Analyze Each File
+
+For each discovered file, extract:
+
+- **Path:** Full path from project root
+- **Title:** First H1 heading
+- **Domain:** Inferred from path or content (API, React, Database, etc.)
+- **Last Modified:** File modification date
+- **Summary:** First paragraph or purpose section
+
+## Phase 3: Generate Registry
+
+Create or update a registry file:
+
+```markdown
+# Standards Registry
+
+> Auto-generated by `/raftstack/index`
+> Last updated: [timestamp]
+
+## Project Context
+
+| File | Description | Last Modified |
+|------|-------------|---------------|
+| [path] | [title/summary] | [date] |
+
+## Standards by Domain
+
+### API/Backend
+| Standard | Path | Last Modified |
+|----------|------|---------------|
+| [name] | [path] | [date] |
+
+### React/Frontend
+| Standard | Path | Last Modified |
+|----------|------|---------------|
+| [name] | [path] | [date] |
+
+### Database
+| Standard | Path | Last Modified |
+|----------|------|---------------|
+| [name] | [path] | [date] |
+
+### Other
+| Standard | Path | Last Modified |
+|----------|------|---------------|
+| [name] | [path] | [date] |
+
+## RaftStack Skills
+
+| Skill | Path | Description |
+|-------|------|-------------|
+| React | `.claude/skills/react/SKILL.md` | React 19+ patterns |
+| Backend | `.claude/skills/backend/SKILL.md` | Clean architecture |
+| Database | `.claude/skills/database/SKILL.md` | PostgreSQL/Drizzle |
+| SEO | `.claude/skills/seo/SKILL.md` | Technical SEO |
+| Code Quality | `.claude/skills/code-quality/SKILL.md` | General patterns |
+
+## Usage
+
+Reference standards in conversation:
+- `@path/to/standard.md` - Load full standard
+- `/raftstack/inject [domain]` - Get relevant standards for a task
+```
+
+## Phase 4: Location Negotiation
+
+Use `AskUserQuestion` with these options:
+- Option A: `.claude/standards/REGISTRY.md` - With standards (Recommended)
+- Option B: `.claude/REGISTRY.md` - In Claude folder
+- Option C: `docs/REGISTRY.md` - With documentation
+- Option D: Other (let user specify)
+
+If a registry already exists, update it in place.
+
+## Phase 5: Drift Detection
+
+Compare current codebase against documented standards:
+
+1. **Check for orphaned standards:**
+   - Standards that reference files/patterns no longer in codebase
+   - Flag for review
+
+2. **Check for undocumented patterns:**
+   - Significant code areas without corresponding standards
+   - Suggest running `/raftstack/discover` for those areas
+
+3. **Check for inconsistencies:**
+   - Code that violates documented standards
+   - Flag specific files for review
+
+## Phase 6: Indexing Summary
+
+After scanning and creating the registry, present:
+
+```markdown
+## ✅ Standards Indexing Completed
+
+### 🎯 Registry Overview
+- **Total Standards:** [N] documents
+- **Domains Covered:** [list domains]
+- **Skills Available:** [N] RaftStack skills
+- **Registry Location:** `[path]`
+
+### 📋 What Was Found
+| Domain | Standards | Last Updated |
+|--------|-----------|--------------|
+| API/Backend | [N] | [most recent date] |
+| React/Frontend | [N] | [most recent date] |
+| Database | [N] | [most recent date] |
+| Other | [N] | [most recent date] |
+
+### 🔍 Drift Report
+
+#### Orphaned Standards
+| Standard | Issue | Recommendation |
+|----------|-------|----------------|
+| [path] | [References deleted file] | [Remove or update] |
+
+#### Undocumented Areas
+| Area | Files | Recommendation |
+|------|-------|----------------|
+| `src/auth/` | [N files] | Run `/raftstack/discover auth` |
+| `src/utils/` | [N files] | Run `/raftstack/discover utils` |
+
+#### Potential Violations
+| File | Standard | Issue |
+|------|----------|-------|
+| `src/api/users.ts:45` | Error Handling | [Description] |
+
+### ⚠️ Action Items
+1. **[High Priority]** [Action needed] - [Why]
+2. **[Medium Priority]** [Action needed] - [Why]
+3. **[Low Priority]** [Action needed] - [Why]
+
+### 🔄 What's Next
+- **Option A:** Fix orphaned standards - Update or remove stale references
+- **Option B:** Document undocumented areas - Run discover for flagged areas
+- **Option C:** Review violations - Check flagged files for compliance
+- **Option D:** Done for now
+
+**Your options:** [A] Fix orphaned [B] Document areas [C] Review violations [D] Done
+```
+
+Use `AskUserQuestion` for options.
+
+## Phase 7: Drift Resolution
+
+If user chooses to address drift:
+
+### Orphaned Standards
+```markdown
+## Resolving Orphaned Standard: [Standard Name]
+
+**Issue:** References `[old-path]` which no longer exists.
+
+**Options:**
+- [A] Update standard to reference new location (if moved)
+- [B] Remove the outdated reference
+- [C] Delete the standard entirely
+- [D] Skip for now
+```
+
+Use `AskUserQuestion` for each orphaned standard.
+
+### Undocumented Areas
+For each undocumented area, suggest:
+- Run `/raftstack/discover [area]` to document patterns
+
+### Violations
+For each violation, present:
+- The standard that's being violated
+- The specific code that violates it
+- Options to fix or mark as acceptable deviation
+
+## Automation Suggestions
+
+After indexing, suggest based on findings:
+
+1. **If many undocumented areas:** "Run `/raftstack/discover` for key areas"
+
+2. **If standards are old:** "Some standards haven't been updated in 90+ days. Review for accuracy."
+
+3. **If violations found:** "Review flagged files for standard compliance"
+
+## Example Output
+
+```markdown
+## ✅ Standards Indexing Completed
+
+### 🎯 Registry Overview
+- **Total Standards:** 5 documents
+- **Domains Covered:** API, React, Database
+- **Skills Available:** 5 RaftStack skills
+- **Registry Location:** `.claude/standards/REGISTRY.md`
+
+### 📋 What Was Found
+| Domain | Standards | Last Updated |
+|--------|-----------|--------------|
+| API/Backend | 2 | 2024-01-20 |
+| React/Frontend | 1 | 2024-01-18 |
+| Database | 1 | 2024-01-15 |
+| Other | 1 | 2024-01-10 |
+
+### 🔍 Drift Report
+
+#### Undocumented Areas
+| Area | Files | Recommendation |
+|------|-------|----------------|
+| `src/auth/` | 8 files | Run `/raftstack/discover auth` |
+| `src/middleware/` | 3 files | Run `/raftstack/discover middleware` |
+
+#### Potential Violations
+| File | Standard | Issue |
+|------|----------|-------|
+| `src/api/users.ts:45` | Error Handling | Missing correlation ID |
+
+### ⚠️ Action Items
+1. **[Medium Priority]** Document auth patterns - 8 files without standards
+2. **[Low Priority]** Review error handling - 1 potential violation
+
+**Your options:** [A] Document auth area [B] Review violations [C] Update old standards [D] Done
+```

package/.claude/commands/raftstack/init-context.md

@@ -0,0 +1,221 @@
+# RaftStack: Initialize Project Context
+
+Analyze this codebase and generate a constitution document that captures how this project works.
+
+## Tool Usage
+
+**IMPORTANT:** Always use the `AskUserQuestion` tool for:
+- Location negotiation (where to save files)
+- Confirmation requests
+- Clarification questions
+
+Never use plain text questions - always use the structured `AskUserQuestion` tool.
+
+## Phase 1: Structure Discovery
+
+First, analyze the project structure:
+
+1. **Detect project type:**
+   - Check for `nx.json` → NX Monorepo
+   - Check for `turbo.json` → Turborepo
+   - Check for `pnpm-workspace.yaml` → pnpm Workspace
+   - Check for `apps/` or `packages/` directories → Monorepo pattern
+   - Otherwise → Single package
+
+2. **Scan key configuration files:**
+   - `package.json` - dependencies, scripts, name
+   - `tsconfig.json` - TypeScript settings
+   - Framework configs (next.config.*, vite.config.*, etc.)
+   - `.env.example` or `.env.local` - environment patterns
+   - Database configs (drizzle.config.ts, prisma/schema.prisma)
+
+3. **Map directory structure:**
+   - Source locations (`src/`, `app/`, `pages/`, `lib/`)
+   - Test locations (`__tests__/`, `*.test.ts`, `*.spec.ts`)
+   - Config locations (`.github/`, `.husky/`, etc.)
+
+### Phase 1 Summary
+
+After completing structure discovery, present:
+
+```markdown
+## ✅ Structure Discovery Completed
+
+### 🎯 Key Discoveries (Top 3)
+1. [Discovery] - **Significance:** [Why this matters]
+2. [Discovery] - **Significance:** [Why this matters]
+3. [Discovery] - **Significance:** [Why this matters]
+
+### 📋 What Was Found
+- **Project Type:** [Detected type]
+- **Framework:** [Detected framework]
+- **Key Directories:** [List main directories]
+
+### 🔍 Important Configuration Files
+1. [File and what it configures]
+2. [File and what it configures]
+3. [File and what it configures]
+
+### ⚠️ Watch Out For
+- [Potential issue or unusual pattern] - **Note:** [Guidance]
+- [Missing expected config] - **Note:** [Guidance]
+
+### 🔄 Ready for Next Phase
+Pattern extraction will analyze code style and architecture.
+
+**Your options:** [A] Proceed to Pattern Extraction [B] Re-analyze structure [C] Explain findings [D] Skip to constitution
+```
+
+Use `AskUserQuestion` to present options A/B/C/D.
+
+## Phase 2: Pattern Extraction
+
+Analyze the code to discover existing patterns:
+
+1. **Component/Module patterns:**
+   - How are React components structured? (file naming, export style)
+   - How are API routes organized?
+   - What's the state management approach?
+
+2. **Code style patterns:**
+   - Import ordering conventions
+   - Error handling approach
+   - Logging patterns
+   - Naming conventions (camelCase, kebab-case for files, etc.)
+
+3. **Architecture patterns:**
+   - Data flow (client → API → database)
+   - Authentication approach
+   - Shared utilities location
+
+### Phase 2 Summary
+
+After completing pattern extraction, present:
+
+```markdown
+## ✅ Pattern Extraction Completed
+
+### 🎯 Key Patterns Found (Top 3)
+1. [Pattern] - **Significance:** [How it shapes development]
+2. [Pattern] - **Significance:** [How it shapes development]
+3. [Pattern] - **Significance:** [How it shapes development]
+
+### 📋 What Was Analyzed
+- **Components:** [Summary of component patterns]
+- **API/Backend:** [Summary of backend patterns]
+- **Code Style:** [Summary of style conventions]
+
+### 🔍 Conventions Detected
+1. [Naming convention with example]
+2. [Import convention with example]
+3. [Error handling approach]
+
+### ⚠️ Inconsistencies Noted
+- [Inconsistency] - **Impact:** [Why it matters]
+- [Inconsistency] - **Impact:** [Why it matters]
+
+### 🔄 Ready for Constitution Generation
+The constitution will capture all discovered patterns and structure.
+
+**Your options:** [A] Generate constitution [B] Analyze more patterns [C] Explain a pattern [D] Start over
+```
+
+Use `AskUserQuestion` to present options A/B/C/D.
+
+## Phase 3: Generate Constitution
+
+Create a constitution document with these sections:
+
+```markdown
+# [Project Name] Constitution
+
+## Overview
+[One paragraph describing what this project does]
+
+## Project Structure
+[Detected structure - monorepo type, key directories]
+
+## Tech Stack
+| Layer | Technology | Config File |
+|-------|------------|-------------|
+| Framework | [detected] | [config path] |
+| Database | [detected] | [config path] |
+| Styling | [detected] | [config path] |
+| Testing | [detected] | [config path] |
+
+## Patterns
+### Component Structure
+[Detected patterns]
+
+### API/Backend Structure
+[Detected patterns]
+
+### Error Handling
+[Detected patterns]
+
+## Conventions
+### Naming
+- Files: [detected]
+- Functions: [detected]
+- Components: [detected]
+
+### Imports
+[Detected ordering/aliasing patterns]
+
+## Future Direction
+[User provides this - project goals, planned features]
+```
+
+## Phase 4: Location Negotiation
+
+After generating the constitution, use `AskUserQuestion` to ask where to save it:
+
+**Use AskUserQuestion with these options:**
+- Option A: `.claude/context/constitution.md` - Claude-specific context folder (Recommended)
+- Option B: `docs/constitution.md` - With project documentation
+- Option C: `CONSTITUTION.md` - At project root
+- Option D: Other (let user specify)
+
+## Phase 5: Final Summary
+
+After saving the constitution, present:
+
+```markdown
+## ✅ Context Initialization Completed
+
+### 🎯 What Was Created
+1. **Constitution Document** - **Location:** [path]
+   - Captures project structure and patterns
+2. **[N] Patterns Documented** - **Coverage:** [areas covered]
+3. **Tech Stack Mapped** - **Frameworks:** [list]
+
+### 📋 Constitution Highlights
+- [Key insight about the project]
+- [Key insight about the project]
+- [Key insight about the project]
+
+### 🔍 Important Items to Review
+1. [Section that may need user refinement]
+2. [Area with incomplete detection]
+3. [Future Direction section - needs user input]
+
+### ⚠️ Follow-up Recommendations
+- **Run `/raftstack/discover`** - Extract specific patterns as reusable standards
+- **Review Future Direction** - Add your project goals and planned features
+
+### 🔄 What This Enables
+- **Option A:** Run `/raftstack/discover [area]` - Document specific patterns as standards
+- **Option B:** Run `/raftstack/shape [feature]` - Plan a feature using this context
+- **Option C:** Edit constitution manually - Refine detected patterns
+
+**Your options:** [A] Discover patterns [B] Shape a feature [C] Edit constitution [D] Done for now
+```
+
+Use `AskUserQuestion` to present final options.
+
+## Output
+
+Once location is confirmed:
+1. Create the constitution file at the chosen location
+2. Present the final summary with discoveries
+3. Offer next step options via `AskUserQuestion`