@raftlabs/raftstack 1.9.2 → 1.9.3

package/.claude/commands/raftstack/_planning-protocol.md

@@ -0,0 +1,216 @@
+# RaftStack Planning Protocol
+
+**INTERNAL REFERENCE - NOT A USER-FACING COMMAND**
+
+All RaftStack commands MUST follow this protocol to enforce plan-first workflows.
+
+---
+
+## Core Principle
+
+**NEVER implement before planning and getting explicit user approval.**
+
+This protocol ensures:
+- Users understand what will happen before it happens
+- No accidental file modifications
+- Changes align with user expectations
+- Clear decision points with explicit approval gates
+
+---
+
+## Phase: Planning Gate (Required Before Implementation)
+
+Before ANY file creation or modification:
+
+### 1. Present Plan Summary
+
+```markdown
+## 📋 Implementation Plan
+
+### What Will Be Done
+- [Bullet list of changes]
+- [Standards that will be applied]
+- [Files that will be created/modified]
+
+### Files to Create/Modify
+| File | Action | Purpose |
+|------|--------|---------|
+| [path] | [create/modify] | [why] |
+
+### Standards Applied
+- [List relevant RaftLabs standards]
+- [Conventions being enforced]
+
+### Estimated Scope
+- [N] files affected
+- [Complexity: Simple/Medium/Complex]
+```
+
+### 2. Request Approval via AskUserQuestion
+
+**REQUIRED:** Use the `AskUserQuestion` tool with these options:
+
+```json
+{
+  "questions": [{
+    "question": "Ready to proceed with this implementation?",
+    "header": "Approval",
+    "multiSelect": false,
+    "options": [
+      {
+        "label": "Proceed with implementation",
+        "description": "Start implementing the plan as presented"
+      },
+      {
+        "label": "Modify the plan",
+        "description": "Revise the approach before implementing"
+      },
+      {
+        "label": "Show more details",
+        "description": "Provide additional context about the plan"
+      },
+      {
+        "label": "Cancel",
+        "description": "Stop and do not implement"
+      }
+    ]
+  }]
+}
+```
+
+### 3. Implementation Rules
+
+#### ✅ ALWAYS:
+- Wait for explicit "Proceed with implementation" selection
+- Present complete plan before asking for approval
+- If user selects "Modify the plan", revise and re-present with new approval gate
+- If user selects "Show more details", expand explanation then re-ask for approval
+- If user selects "Cancel", stop all implementation activities
+
+#### ❌ NEVER:
+- Skip the approval step
+- Implement before presenting the plan
+- Assume approval from partial agreement
+- Proceed without explicit "Proceed" selection
+- Create or modify files during the planning phase
+
+---
+
+## Standard Planning Gate Template
+
+Use this template in command files:
+
+```markdown
+## ⚠️ PLANNING GATE
+
+**DO NOT [ACTION] WITHOUT USER APPROVAL**
+
+Before [specific action]:
+
+1. **Present the Plan:**
+   - What will be done
+   - Files affected
+   - Standards applied
+   - Expected outcomes
+
+2. **Request Approval:**
+   Use `AskUserQuestion` with these options:
+   - [A] Proceed with implementation (Recommended)
+   - [B] Modify the plan
+   - [C] Show more details
+   - [D] Cancel
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit "Proceed" approval
+   - ✅ If "Modify" selected, revise plan and re-present
+   - ✅ If "Show details" selected, expand then re-ask
+   - ❌ Never skip approval gate
+   - ❌ Never implement without [A] selection
+   - ❌ Never create/modify files during planning
+```
+
+---
+
+## When to Use Planning Gates
+
+### Required Gates (Every Command):
+1. **Before any file creation**
+2. **Before any file modification**
+3. **Before running code generators**
+4. **Before applying bulk changes**
+
+### Optional Gates (Use judgment):
+- After complex analysis when user might want to adjust scope
+- When presenting multiple implementation options
+- When significant decisions affect downstream work
+
+---
+
+## Command-Specific Guidelines
+
+### `/raftstack/shape`
+- Gate after complexity assessment (Quick/Light/Full)
+- Gate before implementation phase
+- All three complexity levels require approval
+
+### `/raftstack/discover`
+- Gate after pattern analysis
+- Gate before creating standard files
+- Gate before applying discovered standards
+
+### `/raftstack/inject`
+- No file modifications - guidance only
+- Recommend `/raftstack/shape` for actual implementation
+- Remind user that injected context is for planning
+
+### `/raftstack/init-context`
+- Gate after presenting constitution preview
+- Gate before writing constitution file
+
+### `/raftstack/index`
+- Gate before creating/updating registry file
+- Gate before resolving drift (file modifications)
+
+---
+
+## Example Flow
+
+**Good:**
+```
+1. User: "/raftstack/shape Add login button"
+2. Claude: [Analyzes, creates plan]
+3. Claude: [Presents plan summary]
+4. Claude: [Uses AskUserQuestion for approval]
+5. User: [Selects "Proceed"]
+6. Claude: [Implements plan]
+```
+
+**Bad:**
+```
+1. User: "/raftstack/shape Add login button"
+2. Claude: [Analyzes]
+3. Claude: [Immediately starts creating files] ❌
+```
+
+---
+
+## Enforcement Strategy
+
+This protocol relies on **instruction-based enforcement** because:
+- Plan mode cannot be programmatically triggered
+- Hooks execute after tool calls, can't prevent them
+- No settings exist to enforce plan-first workflows
+
+**Strong imperative language** ("DO NOT", "MUST", "NEVER") in command prompts is the most reliable enforcement mechanism.
+
+---
+
+## Verification Checklist
+
+Before considering a command complete:
+
+- [ ] Planning gate added before all file operations
+- [ ] `AskUserQuestion` tool configured with standard options
+- [ ] Clear instructions about when to implement
+- [ ] "DO NOT IMPLEMENT WITHOUT APPROVAL" warning present
+- [ ] Command references this protocol file

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

@@ -2,6 +2,15 @@
 
 Analyze a specific area of the codebase and extract patterns into reusable standards.
 
+## 🔒 Planning Protocol
+
+This command follows the RaftStack Planning Protocol:
+- All changes are planned before implementation
+- User approval is required before creating standard files
+- Use `AskUserQuestion` for all approval gates
+
+**Reference:** See `_planning-protocol.md` for full protocol details.
+
 ## Arguments
 
 - `$ARGUMENTS` - (Optional) Focus area to analyze (e.g., "API", "components", "database", "error handling")
@@ -11,6 +20,7 @@ Analyze a specific area of the codebase and extract patterns into reusable stand
 **IMPORTANT:** Always use the `AskUserQuestion` tool for:
 - Focus area selection
 - Standard creation decisions
+- **Standard file creation approval** (required before writing files)
 - Location negotiation
 - Option selection
 
@@ -35,6 +45,12 @@ If no focus area provided, use `AskUserQuestion` with these options:
 
 ## Phase 2: Deep Pattern Analysis
 
+**IMPORTANT:** When researching patterns or understanding existing code:
+- Use `context7` plugin to get latest documentation for any libraries detected
+- Example: If analyzing React patterns, use context7 to get React 19 docs
+- Example: If analyzing Drizzle ORM, use context7 to get current Drizzle docs
+- This ensures standards are based on current best practices
+
 For the selected area, analyze:
 
 1. **Find representative files:**
@@ -89,14 +105,35 @@ After analyzing patterns, present:
 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.
+#### ⚠️ PLANNING GATE (Before Standard Creation)
+
+**DO NOT CREATE STANDARD FILES WITHOUT USER APPROVAL**
+
+Before creating any standard files:
+
+1. **Present the Pattern Analysis Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Create all standards (Recommended)
+   - [B] Select specific standards
+   - [C] Analyze another area first
+   - [D] Skip standardization
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] or [B] selection before creating files
+   - ✅ If [A] selected, create all recommended standards
+   - ✅ If [B] selected, ask which standards to create, then proceed
+   - ✅ If [C] selected, return to Phase 1 for new area
+   - ✅ If [D] selected, skip standard creation
+   - ❌ Never skip approval
+   - ❌ Never create standard files without [A] or [B] selection
 
 ## Phase 4: Standard Creation
 
+**ONLY proceed to this phase after receiving approval in Phase 3 Planning Gate.**
+
 For each selected pattern, create a standard document:
 
 ```markdown
@@ -130,13 +167,20 @@ For each selected pattern, create a standard document:
 - [Link to related skill if applicable]
 ```
 
-## Phase 5: Location Negotiation
+## Phase 5: Standard File Location
 
-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)
+Standards are always saved at: `.claude/standards/[area]/[standard-name].md`
+
+**Directory Structure:**
+```
+.claude/standards/
+├── api/
+├── react/
+├── database/
+└── REGISTRY.md
+```
+
+**Note:** For business documentation (user flows, edge cases, PRDs), use `docs/` instead.
 
 ## Phase 6: Completion Summary
 

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

@@ -15,29 +15,60 @@ Never use plain text questions - always use the structured `AskUserQuestion` too
 
 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
+### Technical Documentation (`.claude/`)
+- `.claude/context/constitution.md` → Project constitution
+- `.claude/standards/**/*.md` → Coding standards
+- `.claude/standards/REGISTRY.md` → Standards registry
+- `.claude/specs/**/*` → Feature specifications
+- `.claude/skills/*/SKILL.md` → RaftStack skills
+
+### Required Marketplaces
+Check if required Claude Code marketplaces are installed:
+
+1. **Check for marketplace directories:**
+   - `~/.claude/plugins/marketplaces/claude-plugins-official/` → Official plugins
+   - `~/.claude/plugins/marketplaces/anthropic-agent-skills/` → Document skills
+
+2. **If missing, note in Health Assessment for installation guidance**
+
+### Business Documentation (`docs/`)
+All business logic and product-specific files are stored in the `docs/` folder.
+
+## Planning Protocol
+
+**All RaftStack commands follow a plan-first workflow:**
+- Commands always plan before implementing
+- User approval is required before any file modifications
+- Use `AskUserQuestion` for all approval gates
+
+For details, see `.claude/commands/raftstack/_planning-protocol.md`
+
+## RaftStack Folder Convention
+
+### `.claude/` - Technical (AI Context)
+```
+.claude/
+├── context/
+│   └── constitution.md          # Project patterns & structure
+├── standards/
+│   ├── REGISTRY.md              # Index of all standards
+│   ├── api/                     # Domain-specific standards
+│   ├── react/
+│   └── database/
+├── specs/
+│   └── {timestamp}-{slug}/      # Feature specifications
+├── skills/                      # RaftStack skills
+├── commands/
+│   └── raftstack/
+│       ├── _planning-protocol.md  # Internal: Planning enforcement protocol
+│       ├── shape.md            # /raftstack/shape command
+│       ├── discover.md         # /raftstack/discover command
+│       └── ...                 # Other commands
+└── subagents/                   # Subagent definitions
+```
+
+### `docs/` - Business (Human-Facing)
+Contains all business logic and product-specific documentation.
 
 ## Phase 2: Assess Project State
 
@@ -78,6 +109,15 @@ Show the user their current state:
 | Registry | [✅ Found / ❌ Missing] | [path or -] |
 | Specs | [[N] found / ❌ None] | [path or -] |
 | Skills | [✅ Installed / ❌ Missing] | [path or -] |
+| Plugins | [✅ Ready / ⚠️ Marketplaces missing] | `.claude/settings.json` |
+
+### 🔌 Marketplace Status (if any missing)
+| Marketplace | Status | Install Command |
+|-------------|--------|-----------------|
+| claude-plugins-official | [✅ Installed / ❌ Missing] | `claude plugins add claude-plugins-official` |
+| anthropic-agent-skills | [✅ Installed / ❌ Missing] | `claude plugins add https://github.com/anthropics/skills` |
+
+**Note:** If marketplaces are missing, run the install commands above, then restart Claude Code.
 
 ### Health Assessment
 - **Overall:** [New / Partially Set Up / Ready / Needs Maintenance]

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

@@ -2,6 +2,16 @@
 
 Scan for standards files and maintain a registry. Works with any directory structure.
 
+## 🔒 Planning Protocol
+
+This command follows the RaftStack Planning Protocol:
+- All changes are planned before implementation
+- User approval is required before creating/updating registry file
+- User approval is required before resolving drift (file modifications)
+- Use `AskUserQuestion` for all approval gates
+
+**Reference:** See `_planning-protocol.md` for full protocol details.
+
 ## Purpose
 
 Keep track of all standards and context files in the project, regardless of where they're stored.
@@ -9,6 +19,8 @@ Keep track of all standards and context files in the project, regardless of wher
 ## Tool Usage
 
 **IMPORTANT:** Always use the `AskUserQuestion` tool for:
+- **Registry file creation/update approval** (required before writing files)
+- **Drift resolution approval** (required before modifying files)
 - Location negotiation
 - Drift resolution decisions
 - Follow-up options
@@ -17,23 +29,21 @@ Never use plain text questions - always use the structured `AskUserQuestion` too
 
 ## Phase 1: Scan for Standards
 
-Search common locations for standards files:
+Search for standards and context files:
 
-1. **Standard locations:**
-   - `.claude/standards/**/*.md`
-   - `.claude/context/**/*.md`
-   - `docs/standards/**/*.md`
-   - `standards/**/*.md`
-   - `*.standard.md` (root level)
+1. **Canonical locations:**
+   - `.claude/standards/**/*.md` → Project standards
+   - `.claude/context/**/*.md` → Project context
 
-2. **Context files:**
-   - `CONSTITUTION.md`
-   - `.claude/context/constitution.md`
-   - `docs/constitution.md`
-
-3. **Skills (RaftStack-provided):**
+2. **Skills:**
    - `.claude/skills/*/SKILL.md`
 
+3. **Legacy locations (migration detection):**
+   - `docs/standards/**/*.md`, `standards/**/*.md`, `*.standard.md`
+   - `CONSTITUTION.md`, `docs/constitution.md`
+
+   If found at legacy locations, suggest migration to `.claude/`.
+
 ## Phase 2: Analyze Each File
 
 For each discovered file, extract:
@@ -99,15 +109,11 @@ Reference standards in conversation:
 - `/raftstack/inject [domain]` - Get relevant standards for a task
 ```
 
-## Phase 4: Location Negotiation
+## Phase 4: Registry Location
 
-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)
+The registry is always saved at: `.claude/standards/REGISTRY.md`
 
-If a registry already exists, update it in place.
+If a registry exists at a legacy location (`.claude/REGISTRY.md` or `docs/REGISTRY.md`), inform the user and migrate it.
 
 ## Phase 5: Drift Detection
 
@@ -175,13 +181,34 @@ After scanning and creating the registry, present:
 - **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.
+#### ⚠️ PLANNING GATE (Before Creating/Updating Registry)
+
+**DO NOT CREATE OR UPDATE REGISTRY FILE WITHOUT USER APPROVAL**
+
+Before writing the registry file:
+
+1. **Present the Indexing Summary Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Create/update registry file (Recommended)
+   - [B] Fix orphaned standards first
+   - [C] Document undocumented areas first
+   - [D] Review violations first
+   - [E] Cancel (don't create registry)
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] selection before creating/updating registry
+   - ✅ If [B/C/D] selected, proceed to drift resolution (which has its own gates)
+   - ✅ If [E] selected, stop without creating registry
+   - ❌ Never skip approval
+   - ❌ Never create/update registry file without [A] selection
 
 ## Phase 7: Drift Resolution
 
+**IMPORTANT:** Each drift resolution action requires its own approval gate.
+
 If user chooses to address drift:
 
 ### Orphaned Standards

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

@@ -2,10 +2,20 @@
 
 Analyze this codebase and generate a constitution document that captures how this project works.
 
+## 🔒 Planning Protocol
+
+This command follows the RaftStack Planning Protocol:
+- All changes are planned before implementation
+- User approval is required before creating constitution file
+- Use `AskUserQuestion` for all approval gates
+
+**Reference:** See `_planning-protocol.md` for full protocol details.
+
 ## Tool Usage
 
 **IMPORTANT:** Always use the `AskUserQuestion` tool for:
 - Location negotiation (where to save files)
+- **Constitution file creation approval** (required before writing file)
 - Confirmation requests
 - Clarification questions
 
@@ -124,7 +134,7 @@ Use `AskUserQuestion` to present options A/B/C/D.
 
 ## Phase 3: Generate Constitution
 
-Create a constitution document with these sections:
+**IMPORTANT:** Prepare the constitution content but DO NOT write the file yet. Present it for approval first.
 
 ```markdown
 # [Project Name] Constitution
@@ -166,17 +176,52 @@ Create a constitution document with these sections:
 [User provides this - project goals, planned features]
 ```
 
-## Phase 4: Location Negotiation
+## Phase 4: Constitution Preview & Approval Gate
+
+Present the generated constitution content to the user for review:
+
+```markdown
+## 📋 Constitution Preview
+
+[Show first 30-40 lines of generated constitution content]
+
+...
+
+[Full constitution will be saved to `.claude/context/constitution.md`]
+```
+
+#### ⚠️ PLANNING GATE (Before Creating Constitution File)
+
+**DO NOT CREATE CONSTITUTION FILE WITHOUT USER APPROVAL**
+
+Before writing the constitution file:
+
+1. **Present the Constitution Preview Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Create constitution file (Recommended)
+   - [B] Modify the constitution content
+   - [C] Show full preview
+   - [D] Cancel
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] selection before creating file
+   - ✅ If [B] selected, revise content and re-present
+   - ✅ If [C] selected, show full content and re-ask for approval
+   - ❌ Never skip approval
+   - ❌ Never create file without [A] selection
+
+## Phase 5: Constitution Location
+
+**ONLY proceed to this phase after receiving approval in Phase 4 Planning Gate.**
+
+The constitution is always saved at: `.claude/context/constitution.md`
 
-After generating the constitution, use `AskUserQuestion` to ask where to save it:
+**Migration:** If a constitution exists at a legacy location (`CONSTITUTION.md` or `docs/constitution.md`), inform the user and offer to migrate 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)
+**Note:** For business-facing documentation (PRD, stakeholder docs), use `docs/` instead.
 
-## Phase 5: Final Summary
+## Phase 6: Final Summary
 
 After saving the constitution, present: