@raftlabs/raftstack 1.9.1 → 1.9.3

package/.claude/commands/raftstack/inject.md

@@ -2,6 +2,15 @@
 
 Surface relevant standards and skills for the current work context.
 
+## 🔒 Planning Protocol
+
+This command follows the RaftStack Planning Protocol:
+- **No file modifications** - This command is read-only (context injection for planning)
+- If user wants to implement after injecting context, recommend `/raftstack/shape [task]`
+- That command will handle planning and approval gates
+
+**Reference:** See `_planning-protocol.md` for full protocol details.
+
 ## Arguments
 
 - `$ARGUMENTS` - (Optional) Specific domain or task context (e.g., "React component", "API endpoint", "database migration")
@@ -15,6 +24,15 @@ Surface relevant standards and skills for the current work context.
 
 Never use plain text questions - always use the structured `AskUserQuestion` tool.
 
+## Important Note About Implementation
+
+**This command does NOT implement code.** It only surfaces relevant context for planning.
+
+After injecting context, if the user wants to proceed with implementation:
+1. Recommend running `/raftstack/shape [task description]`
+2. The shape command will plan the work and require approval before implementation
+3. Never proceed directly to implementation from this command
+
 ## Phase 1: Context Detection
 
 If no specific context provided, infer from:
@@ -39,24 +57,23 @@ If context is unclear, use `AskUserQuestion`:
 
 ## Phase 2: Standards Discovery
 
-Scan for standards files in likely locations:
+Scan for standards files:
 
-1. **Check common standard locations:**
+1. **Canonical locations:**
    - `.claude/standards/` and subdirectories
-   - `docs/standards/`
-   - `standards/`
-   - Files matching `*.standard.md`
+   - `.claude/context/constitution.md`
+
+2. **Legacy fallback (suggest migration):**
+   - `docs/standards/`, `standards/`, `*.standard.md`
+   - `CONSTITUTION.md`, `docs/constitution.md`
+
+   If found at legacy locations, suggest migration to `.claude/`.
 
-2. **Match by domain:**
+3. **Match by domain:**
    - React work → look for component, state, hooks standards
    - API work → look for route, validation, error standards
    - Database work → look for schema, query, migration standards
 
-3. **Check for constitution/context:**
-   - `.claude/context/constitution.md`
-   - `CONSTITUTION.md`
-   - `docs/constitution.md`
-
 ## Phase 3: Skills Matching
 
 Based on the detected domain, identify relevant RaftStack skills:
@@ -70,6 +87,28 @@ Based on the detected domain, identify relevant RaftStack skills:
 | General | Code Quality | `.claude/skills/code-quality/SKILL.md` |
 | Asana Integration | Asana Workflow | `.claude/skills/asana/SKILL.md` |
 
+## Phase 3.5: Plugin Recommendations
+
+Based on the detected domain, identify required Claude Code plugins:
+
+### Plugin Enforcement Matrix
+
+| Domain | Plugin | Skill/Tool | When to Trigger |
+|--------|--------|------------|-----------------|
+| React/Frontend/JSX | `frontend-design` | `/frontend-design` skill | Any UI component, JSX, CSS work |
+| React/Frontend/JSX | `figma` | `/implement-design` | Figma files to code |
+| Testing | `playwright` | Browser tools | E2E tests, browser automation |
+| Testing | `superpowers` | `/tdd` skill | Test-driven development |
+| Research/Documentation | `context7` | Documentation lookup | Getting library docs, API references |
+| Code Review | `code-review` | `/code-review` | Before commits, PR creation |
+| Code Review | `pr-review-toolkit` | `/review-pr` | Specialized review agents |
+| Git/Commits | `commit-commands` | `/commit`, `/commit-push-pr` | Any git operations |
+| Git/Commits | `github` | GitHub tools | Issue/PR management |
+| Backend/API | `security-guidance` | Security warnings | API routes, handlers, auth |
+| Deployment | `vercel` | Vercel tools | Deployment-related tasks |
+| Project Management | `linear` | Linear tools | Task tracking with Linear |
+| Project Management | `asana` | Asana tools | Task tracking with Asana |
+
 ## Phase 4: Context-Aware Summary
 
 Present the injected context as a structured summary:
@@ -89,6 +128,13 @@ Present the injected context as a structured summary:
 | [Name] | `[Path]` | [Trigger condition] |
 | [Name] | `[Path]` | [Trigger condition] |
 
+### 🔌 Recommended Plugins
+| Plugin | Purpose | Skill to Use |
+|--------|---------|--------------|
+| [plugin] | [why needed for this domain] | `/[skill-name]` or [tool description] |
+
+**Important:** Always use `context7` when researching libraries or getting documentation.
+
 ### Quick Reference (Most Important Rules)
 1. **[Rule]** - [Brief explanation]
 2. **[Rule]** - [Brief explanation]

package/.claude/commands/raftstack/shape.md

@@ -2,6 +2,15 @@
 
 Plan a feature or task with scale-adaptive depth. Simple tasks get quick flow, complex tasks get full specs.
 
+## 🔒 Planning Protocol
+
+This command follows the RaftStack Planning Protocol:
+- All changes are planned before implementation
+- User approval is required before any file modifications
+- Use `AskUserQuestion` for all approval gates
+
+**Reference:** See `_planning-protocol.md` for full protocol details.
+
 ## Arguments
 
 - `$ARGUMENTS` - Description of the feature or task to plan
@@ -13,6 +22,7 @@ Plan a feature or task with scale-adaptive depth. Simple tasks get quick flow, c
 - Location negotiation
 - Option selection
 - Clarification questions
+- **Implementation approval** (required before any file operations)
 
 Never use plain text questions - always use the structured `AskUserQuestion` tool.
 
@@ -63,12 +73,14 @@ After assessment, use `AskUserQuestion` to confirm the complexity level:
 
 ## Phase 2: Execute Based on Scale
 
+**IMPORTANT:** Each flow level (Quick/Light/Full) MUST include an approval gate before implementation.
+
 ### Quick Flow (Simple Tasks)
 
 1. Clarify scope in 2-3 sentences
 2. Identify the file(s) to change
 3. Describe the change briefly
-4. Proceed directly to implementation
+4. **WAIT FOR APPROVAL** - Do NOT implement yet
 
 Output format:
 ```markdown
@@ -81,12 +93,31 @@ Output format:
 **Files:** [1-2 files]
 **Approach:** [Brief description]
 
-Ready to implement.
-
-**Your options:** [A] Proceed to implement [B] Add more detail [C] Change approach [D] Cancel
+### 🔌 Use These Plugins
+- [Plugin based on domain detected]
 ```
 
-Use `AskUserQuestion` for options.
+#### ⚠️ PLANNING GATE (Quick Flow)
+
+**DO NOT IMPLEMENT WITHOUT USER APPROVAL**
+
+Before implementing:
+
+1. **Present the Plan Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Proceed to implement (Recommended)
+   - [B] Add more detail
+   - [C] Change approach
+   - [D] Cancel
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] selection
+   - ✅ If [B] selected, provide more detail and re-present
+   - ✅ If [C] selected, revise approach and re-present
+   - ❌ Never skip approval
+   - ❌ Never implement without [A] selection
+   - ❌ Never create/modify files before approval
 
 ### Light Spec (Medium Tasks)
 
@@ -94,6 +125,7 @@ Use `AskUserQuestion` for options.
 2. Identify related code patterns to follow
 3. List files to create/modify
 4. Note any standards to apply
+5. **WAIT FOR APPROVAL** - Do NOT implement yet
 
 Output format:
 ```markdown
@@ -113,14 +145,40 @@ Output format:
 2. [Step with file path]
 3. [Step with file path]
 
+### 🔌 Plugins to Use
+| Plugin | Purpose | When |
+|--------|---------|------|
+| [Plugin] | [Why needed] | [Trigger condition] |
+
+**Important:** Always use `context7` when researching libraries or getting documentation.
+
 ### Standards to Apply
 - [Reference any discovered standards: @.claude/standards/...]
 - [Reference any skills: @.claude/skills/...]
-
-**Your options:** [A] Proceed to implement [B] Save spec to file [C] Modify plan [D] Upgrade to full spec
 ```
 
-Use `AskUserQuestion` for options.
+#### ⚠️ PLANNING GATE (Light Spec)
+
+**DO NOT IMPLEMENT WITHOUT USER APPROVAL**
+
+Before implementing:
+
+1. **Present the Plan Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Proceed to implement (Recommended)
+   - [B] Save spec to file
+   - [C] Modify plan
+   - [D] Upgrade to full spec
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] selection
+   - ✅ If [B] selected, save spec and await further instructions
+   - ✅ If [C] selected, revise plan and re-present
+   - ✅ If [D] selected, transition to Full Spec workflow
+   - ❌ Never skip approval
+   - ❌ Never implement without [A] selection
+   - ❌ Never create/modify files before approval
 
 ### Full Spec (Complex Tasks)
 
@@ -146,13 +204,11 @@ Use `AskUserQuestion` for options.
    - Phase 2: Edge cases/polish
    - Phase 3: Testing/docs
 
-5. **Location negotiation for spec folder:**
+5. **Spec folder location:**
 
-Use `AskUserQuestion` with these options:
-- Option A: `.claude/specs/[feature-slug]/` - Claude-specific planning (Recommended)
-- Option B: `docs/specs/[feature-slug]/` - With documentation
-- Option C: `specs/[feature-slug]/` - At project root
-- Option D: Other (let user specify)
+Specs are always saved at: `.claude/specs/{YYYY-MM-DD-HHMM}-{feature-slug}/`
+
+**Note:** For business requirements (PRD, user stories), use `docs/prd/` instead.
 
 ## Full Spec Folder Structure
 
@@ -204,6 +260,13 @@ After creating the spec folder, present:
 - **references.md:** [N] similar patterns found
 - **architecture.md:** Technical design
 
+### 🔌 Plugins & Skills
+| Plugin | Purpose | When |
+|--------|---------|------|
+| [Plugin] | [Why needed] | [Trigger condition] |
+
+**Important:** Always use `context7` when researching libraries or getting documentation.
+
 ### 🔍 Implementation Phases
 1. **Phase 1:** [Core functionality] - [N files]
 2. **Phase 2:** [Edge cases] - [N files]
@@ -213,22 +276,40 @@ After creating the spec folder, present:
 - [Risk or complexity] - **Mitigation:** [How to handle]
 - [Dependency or blocker] - **Status:** [Current state]
 
-### 🔄 Ready for Implementation
+### 📁 Spec Location
 Spec folder created at: `{path}`
-
-**Your options:** [A] Start implementation [B] Review spec files [C] Modify architecture [D] Add more detail
 ```
 
-Use `AskUserQuestion` for options.
+#### ⚠️ PLANNING GATE (Full Spec)
+
+**DO NOT IMPLEMENT WITHOUT USER APPROVAL**
+
+Before implementing:
+
+1. **Present the Plan Above** (already done)
+
+2. **Request Approval** using `AskUserQuestion` with these options:
+   - [A] Start implementation (Recommended)
+   - [B] Review spec files in detail
+   - [C] Modify architecture
+   - [D] Add more detail
+
+3. **Implementation Rules:**
+   - ✅ Wait for explicit [A] selection
+   - ✅ If [B] selected, review spec files and re-present
+   - ✅ If [C] selected, revise architecture and re-present
+   - ✅ If [D] selected, expand spec and re-present
+   - ❌ Never skip approval
+   - ❌ Never implement without [A] selection
+   - ❌ Never create/modify code files before approval
+   - ✅ Spec folder creation is allowed (it's planning, not implementation)
 
 ## Phase 3: Standards Injection
 
 Before finalizing the plan, check for relevant standards and skills:
 
-1. Scan for standards files in likely locations:
+1. Scan for standards at canonical location:
    - `.claude/standards/`
-   - `docs/standards/`
-   - Project root (`*.standard.md`)
 
 2. Identify relevant skills based on the task domain:
    - React work → `@.claude/skills/react/SKILL.md`

package/.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "model": "opusplan",
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "github@claude-plugins-official": true,
+    "feature-dev@claude-plugins-official": true,
+    "typescript-lsp@claude-plugins-official": true,
+    "code-simplifier@claude-plugins-official": true,
+    "ralph-loop@claude-plugins-official": true,
+    "commit-commands@claude-plugins-official": true,
+    "playwright@claude-plugins-official": true,
+    "security-guidance@claude-plugins-official": true,
+    "pr-review-toolkit@claude-plugins-official": true,
+    "figma@claude-plugins-official": true,
+    "superpowers@claude-plugins-official": true,
+    "explanatory-output-style@claude-plugins-official": true,
+    "linear@claude-plugins-official": true,
+    "learning-output-style@claude-plugins-official": true,
+    "vercel@claude-plugins-official": true,
+    "asana@claude-plugins-official": true,
+    "claude-md-management@claude-plugins-official": true,
+    "claude-code-setup@claude-plugins-official": true,
+    "document-skills@anthropic-agent-skills": true
+  }
+}

package/.claude/subagents/quick-fix.md

@@ -0,0 +1,21 @@
+---
+name: quick-fix
+description: Handle simple bug fixes, typos, small refactors, and one-liner changes
+model: haiku
+tools: Read, Edit, Glob, Grep, Bash
+---
+
+# Quick Fix Agent
+
+Use this agent for:
+- Typo fixes
+- Simple bug fixes (1-5 lines)
+- Small refactors
+- Config changes
+- Import fixes
+
+Do NOT use for:
+- Multi-file changes
+- Architecture decisions
+- Complex debugging
+- New features

package/dist/cli.js

@@ -1701,14 +1701,79 @@ async function generateClaudeCommands(targetDir) {
   return result;
 }
 
-// src/generators/eslint.ts
+// src/generators/claude-config.ts
 import { existsSync as existsSync7 } from "fs";
+import { readdir as readdir3, copyFile as copyFile4 } from "fs/promises";
+import { join as join17, dirname as dirname4 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function getPackageConfigDir() {
+  const currentFilePath = fileURLToPath3(import.meta.url);
+  const packageRoot = join17(dirname4(currentFilePath), "..");
+  return join17(packageRoot, ".claude");
+}
+async function copyDirectory3(srcDir, destDir, result, baseDir) {
+  await ensureDir(destDir);
+  const entries = await readdir3(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join17(srcDir, entry.name);
+    const destPath = join17(destDir, entry.name);
+    const relativePath = destPath.replace(baseDir + "/", "");
+    if (entry.isDirectory()) {
+      await copyDirectory3(srcPath, destPath, result, baseDir);
+    } else {
+      if (existsSync7(destPath)) {
+        const backupPath = await backupFile(destPath);
+        if (backupPath) {
+          result.backedUp.push(relativePath);
+        }
+      }
+      await copyFile4(srcPath, destPath);
+      result.created.push(relativePath);
+    }
+  }
+}
+async function generateClaudeConfig(targetDir) {
+  const result = {
+    created: [],
+    modified: [],
+    skipped: [],
+    backedUp: []
+  };
+  const packageConfigDir = getPackageConfigDir();
+  const targetClaudeDir = join17(targetDir, ".claude");
+  await ensureDir(targetClaudeDir);
+  const settingsContent = JSON.stringify({ model: "opusplan" }, null, 2) + "\n";
+  const settingsResult = await writeFileSafe(
+    join17(targetClaudeDir, "settings.json"),
+    settingsContent,
+    { backup: true }
+  );
+  if (settingsResult.created) {
+    result.created.push(".claude/settings.json");
+    if (settingsResult.backedUp) {
+      result.backedUp.push(settingsResult.backedUp);
+    }
+  }
+  const packageSubagentsDir = join17(packageConfigDir, "subagents");
+  const targetSubagentsDir = join17(targetClaudeDir, "subagents");
+  if (existsSync7(packageSubagentsDir)) {
+    await copyDirectory3(packageSubagentsDir, targetSubagentsDir, result, targetDir);
+  } else {
+    console.warn(
+      "Warning: Subagents directory not found in package. Skipping subagents generation."
+    );
+  }
+  return result;
+}
+
+// src/generators/eslint.ts
+import { existsSync as existsSync8 } from "fs";
 import { readFile as readFile4 } from "fs/promises";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 async function hasReact(targetDir) {
   try {
-    const pkgPath = join17(targetDir, "package.json");
-    if (existsSync7(pkgPath)) {
+    const pkgPath = join18(targetDir, "package.json");
+    if (existsSync8(pkgPath)) {
       const content = await readFile4(pkgPath, "utf-8");
       const pkg = JSON.parse(content);
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
@@ -1720,8 +1785,8 @@ async function hasReact(targetDir) {
 }
 async function hasNextJs(targetDir) {
   try {
-    const pkgPath = join17(targetDir, "package.json");
-    if (existsSync7(pkgPath)) {
+    const pkgPath = join18(targetDir, "package.json");
+    if (existsSync8(pkgPath)) {
       const content = await readFile4(pkgPath, "utf-8");
       const pkg = JSON.parse(content);
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
@@ -2000,7 +2065,7 @@ async function generateEslint(targetDir, usesTypeScript, force = false) {
   } else {
     config = generateJsConfig();
   }
-  const configPath = join17(targetDir, "eslint.config.mjs");
+  const configPath = join18(targetDir, "eslint.config.mjs");
   const writeResult = await writeFileSafe(configPath, config);
   if (writeResult.backedUp) {
     result.backedUp.push("eslint.config.mjs");
@@ -2010,7 +2075,7 @@ async function generateEslint(targetDir, usesTypeScript, force = false) {
 }
 
 // src/generators/quick-reference.ts
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 async function generateQuickReference(targetDir, pm) {
   const result = {
     created: [],
@@ -2018,7 +2083,7 @@ async function generateQuickReference(targetDir, pm) {
     skipped: [],
     backedUp: []
   };
-  const quickRefPath = join18(targetDir, ".github", "QUICK_REFERENCE.md");
+  const quickRefPath = join19(targetDir, ".github", "QUICK_REFERENCE.md");
   const content = `# RaftStack Quick Reference
 
 > One-page guide for the RaftStack Git workflow
@@ -2152,7 +2217,7 @@ ${pm.run} test
 }
 
 // src/generators/shared-configs.ts
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 function getEslintConfigPackageJson() {
   return JSON.stringify(
     {
@@ -2418,15 +2483,15 @@ async function generateSharedConfigs(targetDir, projectType) {
   if (!isMonorepo(projectType)) {
     return result;
   }
-  const packagesDir = join19(targetDir, "packages");
-  const eslintConfigDir = join19(packagesDir, "eslint-config");
+  const packagesDir = join20(targetDir, "packages");
+  const eslintConfigDir = join20(packagesDir, "eslint-config");
   await ensureDir(eslintConfigDir);
   const eslintFiles = [
-    { path: join19(eslintConfigDir, "package.json"), content: getEslintConfigPackageJson(), name: "packages/eslint-config/package.json" },
-    { path: join19(eslintConfigDir, "base.js"), content: getBaseEslintConfig(), name: "packages/eslint-config/base.js" },
-    { path: join19(eslintConfigDir, "next.js"), content: getNextJsEslintConfig(), name: "packages/eslint-config/next.js" },
-    { path: join19(eslintConfigDir, "react-internal.js"), content: getReactInternalEslintConfig(), name: "packages/eslint-config/react-internal.js" },
-    { path: join19(eslintConfigDir, "vite.js"), content: getViteEslintConfig(), name: "packages/eslint-config/vite.js" }
+    { path: join20(eslintConfigDir, "package.json"), content: getEslintConfigPackageJson(), name: "packages/eslint-config/package.json" },
+    { path: join20(eslintConfigDir, "base.js"), content: getBaseEslintConfig(), name: "packages/eslint-config/base.js" },
+    { path: join20(eslintConfigDir, "next.js"), content: getNextJsEslintConfig(), name: "packages/eslint-config/next.js" },
+    { path: join20(eslintConfigDir, "react-internal.js"), content: getReactInternalEslintConfig(), name: "packages/eslint-config/react-internal.js" },
+    { path: join20(eslintConfigDir, "vite.js"), content: getViteEslintConfig(), name: "packages/eslint-config/vite.js" }
   ];
   for (const file of eslintFiles) {
     const writeResult = await writeFileSafe(file.path, file.content, { backup: true });
@@ -2437,14 +2502,14 @@ async function generateSharedConfigs(targetDir, projectType) {
       }
     }
   }
-  const tsConfigDir = join19(packagesDir, "typescript-config");
+  const tsConfigDir = join20(packagesDir, "typescript-config");
   await ensureDir(tsConfigDir);
   const tsFiles = [
-    { path: join19(tsConfigDir, "package.json"), content: getTsConfigPackageJson(), name: "packages/typescript-config/package.json" },
-    { path: join19(tsConfigDir, "base.json"), content: getBaseTsConfig(), name: "packages/typescript-config/base.json" },
-    { path: join19(tsConfigDir, "nextjs.json"), content: getNextJsTsConfig(), name: "packages/typescript-config/nextjs.json" },
-    { path: join19(tsConfigDir, "react-library.json"), content: getReactLibraryTsConfig(), name: "packages/typescript-config/react-library.json" },
-    { path: join19(tsConfigDir, "node-library.json"), content: getNodeLibraryTsConfig(), name: "packages/typescript-config/node-library.json" }
+    { path: join20(tsConfigDir, "package.json"), content: getTsConfigPackageJson(), name: "packages/typescript-config/package.json" },
+    { path: join20(tsConfigDir, "base.json"), content: getBaseTsConfig(), name: "packages/typescript-config/base.json" },
+    { path: join20(tsConfigDir, "nextjs.json"), content: getNextJsTsConfig(), name: "packages/typescript-config/nextjs.json" },
+    { path: join20(tsConfigDir, "react-library.json"), content: getReactLibraryTsConfig(), name: "packages/typescript-config/react-library.json" },
+    { path: join20(tsConfigDir, "node-library.json"), content: getNodeLibraryTsConfig(), name: "packages/typescript-config/node-library.json" }
   ];
   for (const file of tsFiles) {
     const writeResult = await writeFileSafe(file.path, file.content, { backup: true });
@@ -2460,10 +2525,10 @@ async function generateSharedConfigs(targetDir, projectType) {
 
 // src/utils/git.ts
 import { execa } from "execa";
-import { existsSync as existsSync8 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { join as join21 } from "path";
 async function isGitRepo(targetDir = process.cwd()) {
-  if (existsSync8(join20(targetDir, ".git"))) {
+  if (existsSync9(join21(targetDir, ".git"))) {
     return true;
   }
   try {
@@ -2636,6 +2701,7 @@ async function runInit(targetDir = process.cwd()) {
       includeAsana: !!config.asanaBaseUrl
     }));
     results.push(await generateClaudeCommands(targetDir));
+    results.push(await generateClaudeConfig(targetDir));
     results.push(await updateProjectPackageJson(targetDir, config));
     spinner5.stop("Configuration files generated!");
   } catch (error) {
@@ -3633,7 +3699,7 @@ async function runInstallCommands(targetDir = process.cwd()) {
 // package.json
 var package_default = {
   name: "@raftlabs/raftstack",
-  version: "1.9.1",
+  version: "1.9.3",
   description: "CLI tool for setting up Git hooks, commit conventions, and GitHub integration",
   type: "module",
   main: "./dist/index.js",
@@ -3651,7 +3717,9 @@ var package_default = {
     "dist",
     "templates",
     ".claude/skills",
-    ".claude/commands"
+    ".claude/commands",
+    ".claude/subagents",
+    ".claude/settings.json"
   ],
   scripts: {
     build: "tsup",