specweave 0.23.2 → 0.23.5

package/dist/src/utils/fs-native.js

@@ -0,0 +1,224 @@
+/**
+ * Native Node.js fs API Helpers
+ *
+ * Drop-in replacements for fs-extra methods using only Node.js stdlib.
+ * All methods use native Node.js 20+ APIs with no external dependencies.
+ *
+ * Migration from fs-extra:
+ * - import fs from 'fs-extra' → import * as fs from './utils/fs-native.js'
+ * - All fs-extra methods work as drop-in replacements
+ *
+ * Benefits:
+ * - Zero bundle overhead (no npm packages)
+ * - Works in marketplace (no node_modules needed)
+ * - Faster startup (native APIs)
+ * - Better debugging (native stack traces)
+ */
+import { promises as fsPromises, existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync, rmSync, unlinkSync, copyFileSync } from 'fs';
+import path from 'path';
+/**
+ * Ensures that a directory exists. If the directory does not exist, it is created.
+ * @param dirPath - The directory path to ensure
+ */
+export async function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        await fsPromises.mkdir(dirPath, { recursive: true });
+    }
+}
+/**
+ * Synchronous version of ensureDir
+ */
+export function ensureDirSync(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Alias for ensureDirSync (fs-extra compatibility)
+ */
+export function mkdirpSync(dirPath) {
+    ensureDirSync(dirPath);
+}
+/**
+ * Check if a path exists
+ * @param filePath - The path to check
+ */
+export async function pathExists(filePath) {
+    return existsSync(filePath);
+}
+/**
+ * Synchronous version of pathExists
+ */
+export { existsSync };
+/**
+ * Read a JSON file and parse it
+ * @param filePath - The JSON file path
+ */
+export async function readJson(filePath) {
+    const content = await fsPromises.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Synchronous version of readJson
+ */
+export function readJsonSync(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Write a JSON file with formatting
+ * @param filePath - The JSON file path
+ * @param data - The data to write
+ * @param options - Options (spaces for indentation)
+ */
+export async function writeJson(filePath, data, options) {
+    const spaces = options?.spaces ?? 2;
+    const content = JSON.stringify(data, null, spaces);
+    await fsPromises.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Synchronous version of writeJson
+ */
+export function writeJsonSync(filePath, data, options) {
+    const spaces = options?.spaces ?? 2;
+    const content = JSON.stringify(data, null, spaces);
+    writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Remove a file or directory (recursively)
+ * @param targetPath - The path to remove
+ */
+export async function remove(targetPath) {
+    if (existsSync(targetPath)) {
+        await fsPromises.rm(targetPath, { recursive: true, force: true });
+    }
+}
+/**
+ * Synchronous version of remove
+ */
+export function removeSync(targetPath) {
+    if (existsSync(targetPath)) {
+        rmSync(targetPath, { recursive: true, force: true });
+    }
+}
+/**
+ * Copy a file or directory
+ * @param src - Source path
+ * @param dest - Destination path
+ * @param options - Copy options
+ */
+export async function copy(src, dest, options) {
+    const srcStat = await fsPromises.stat(src);
+    if (srcStat.isFile()) {
+        // Copy single file
+        await fsPromises.mkdir(path.dirname(dest), { recursive: true });
+        await fsPromises.copyFile(src, dest);
+    }
+    else if (srcStat.isDirectory()) {
+        // Copy directory recursively
+        await fsPromises.mkdir(dest, { recursive: true });
+        const entries = await fsPromises.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            // Apply filter if provided
+            if (options?.filter && !options.filter(srcPath)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await copy(srcPath, destPath, options);
+            }
+            else {
+                await fsPromises.copyFile(srcPath, destPath);
+            }
+        }
+    }
+}
+/**
+ * Synchronous version of copy
+ */
+export function copySync(src, dest, options) {
+    const srcStat = statSync(src);
+    if (srcStat.isFile()) {
+        // Copy single file
+        mkdirSync(path.dirname(dest), { recursive: true });
+        copyFileSync(src, dest);
+    }
+    else if (srcStat.isDirectory()) {
+        // Copy directory recursively
+        mkdirSync(dest, { recursive: true });
+        const entries = readdirSync(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            // Apply filter if provided
+            if (options?.filter && !options.filter(srcPath)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                copySync(srcPath, destPath, options);
+            }
+            else {
+                copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+}
+/**
+ * Ensure a file exists (create if it doesn't)
+ * @param filePath - The file path
+ */
+export async function ensureFile(filePath) {
+    if (!existsSync(filePath)) {
+        await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+        await fsPromises.writeFile(filePath, '', 'utf-8');
+    }
+}
+/**
+ * Synchronous version of ensureFile
+ */
+export function ensureFileSync(filePath) {
+    if (!existsSync(filePath)) {
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        writeFileSync(filePath, '', 'utf-8');
+    }
+}
+// Re-export common fs/promises methods for convenience
+export const { readFile, writeFile, appendFile, stat, readdir, access, unlink, rmdir, rename, chmod, } = fsPromises;
+// Re-export common synchronous methods
+export { readFileSync, writeFileSync, statSync, readdirSync, unlinkSync, mkdirSync, rmSync, };
+// Default export for convenience
+export default {
+    // Async methods
+    ensureDir,
+    pathExists,
+    readJson,
+    writeJson,
+    remove,
+    copy,
+    ensureFile,
+    readFile,
+    writeFile,
+    appendFile,
+    stat,
+    readdir,
+    access,
+    unlink,
+    // Sync methods
+    ensureDirSync,
+    mkdirpSync,
+    existsSync,
+    readJsonSync,
+    writeJsonSync,
+    removeSync,
+    copySync,
+    ensureFileSync,
+    readFileSync,
+    writeFileSync,
+    statSync,
+    readdirSync,
+    unlinkSync,
+    mkdirSync,
+    rmSync,
+};
+//# sourceMappingURL=fs-native.js.map

package/dist/src/utils/fs-native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-native.js","sourceRoot":"","sources":["../../../src/utils/fs-native.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.23.2",
+  "version": "0.23.5",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -20,6 +20,18 @@
     "living-docs"
   ],
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-task-completion.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "TodoWrite",

package/plugins/specweave/agents/AGENTS-INDEX.md

@@ -0,0 +1,216 @@
+# SpecWeave Agents Index
+
+## Quick Reference: How to Invoke Agents
+
+All SpecWeave agents follow the naming pattern: `{plugin}:{directory}:{name-from-yaml}`
+
+### Core Planning & Design Agents
+
+#### Product Manager (PM)
+```typescript
+Task({
+  subagent_type: "specweave:pm:pm",
+  prompt: "Create product requirements for user dashboard feature"
+});
+```
+**Use for**: Product strategy, requirements gathering, user story creation, feature prioritization
+
+#### Architect
+```typescript
+Task({
+  subagent_type: "specweave:architect:architect",
+  prompt: "Design system architecture for user authentication"
+});
+```
+**Use for**: System architecture, technical specifications, ADRs, component designs, API contracts
+
+#### Tech Lead
+```typescript
+Task({
+  subagent_type: "specweave:tech-lead:tech-lead",
+  prompt: "Review code and suggest improvements"
+});
+```
+**Use for**: Code review, best practices, technical mentorship, implementation planning
+
+---
+
+### Quality & Testing Agents
+
+#### QA Lead
+```typescript
+Task({
+  subagent_type: "specweave:qa-lead:qa-lead",
+  prompt: "Create test strategy for permission gates feature"
+});
+```
+**Use for**: Test plans, test cases, E2E testing with Playwright, test automation, coverage analysis
+
+#### Test-Aware Planner
+```typescript
+Task({
+  subagent_type: "specweave:test-aware-planner:test-aware-planner",
+  prompt: "Generate tasks with embedded test plans"
+});
+```
+**Use for**: Task generation with BDD test plans, coverage targets, AC-test mapping
+
+#### TDD Orchestrator
+```typescript
+Task({
+  subagent_type: "specweave:tdd-orchestrator:tdd-orchestrator",
+  prompt: "Coordinate TDD workflow for feature implementation"
+});
+```
+**Use for**: Red-green-refactor discipline, multi-agent TDD coordination
+
+---
+
+### Code Quality & Standards Agents
+
+#### Code Reviewer
+```typescript
+Task({
+  subagent_type: "specweave:code-reviewer",
+  prompt: "Review recent changes for security and performance issues"
+});
+```
+**Use for**: Modern AI-powered code analysis, security scanning, performance optimization
+
+#### Code Standards Detective
+```typescript
+Task({
+  subagent_type: "specweave:code-standards-detective:code-standards-detective",
+  prompt: "Analyze codebase and generate coding standards documentation"
+});
+```
+**Use for**: Discovering naming conventions, import patterns, detecting anti-patterns
+
+#### Security
+```typescript
+Task({
+  subagent_type: "specweave:security:security",
+  prompt: "Perform security review of authentication implementation"
+});
+```
+**Use for**: Threat modeling, security architecture, OWASP Top 10, vulnerability assessment
+
+---
+
+### Documentation & Communication Agents
+
+#### Docs Writer
+```typescript
+Task({
+  subagent_type: "specweave:docs-writer:docs-writer",
+  prompt: "Create API documentation for REST endpoints"
+});
+```
+**Use for**: API docs, user guides, developer guides, README files, architecture documentation
+
+#### Translator
+```typescript
+Task({
+  subagent_type: "specweave:translator:AGENT",
+  prompt: "Translate documentation to Spanish"
+});
+```
+**Use for**: Batch translation projects, multi-file translation coordination
+
+---
+
+### Infrastructure & Performance Agents
+
+#### Infrastructure
+```typescript
+Task({
+  subagent_type: "specweave:infrastructure:infrastructure",
+  prompt: "Generate Terraform configurations for serverless deployment"
+});
+```
+**Use for**: Infrastructure-as-Code, AWS Lambda, Azure Functions, GCP Cloud Functions, Supabase
+
+#### Performance
+```typescript
+Task({
+  subagent_type: "specweave:performance:performance",
+  prompt: "Analyze and optimize database query performance"
+});
+```
+**Use for**: Performance optimization, profiling, benchmarking, scalability analysis
+
+---
+
+### Quality Assurance Agents
+
+#### Increment Quality Judge v2
+```typescript
+Task({
+  subagent_type: "specweave:increment-quality-judge-v2:increment-quality-judge-v2",
+  prompt: "Assess quality of increment specification and implementation"
+});
+```
+**Use for**: AI-powered quality assessment, risk scoring (BMAD), quality gate decisions
+
+#### Reflective Reviewer
+```typescript
+Task({
+  subagent_type: "specweave:reflective-reviewer:reflective-reviewer",
+  prompt: "Perform reflective review of implementation quality"
+});
+```
+**Use for**: Post-implementation review, learning from mistakes, improvement suggestions
+
+---
+
+## Naming Pattern Explanation
+
+**Directory-based agents** (most common):
+```
+Pattern: {plugin}:{directory}:{name-from-yaml}
+Example: specweave:qa-lead:qa-lead
+
+Structure:
+plugins/specweave/agents/qa-lead/
+  └── AGENT.md (contains: name: qa-lead)
+```
+
+**File-based agents** (legacy):
+```
+Pattern: {plugin}:{filename}
+Example: specweave:code-reviewer
+
+Structure:
+plugins/specweave/agents/
+  └── code-reviewer.md
+```
+
+## Finding Agent Types
+
+```bash
+# List all available agents
+ls -la plugins/specweave/agents/
+
+# Check agent's YAML name field
+head -5 plugins/specweave/agents/qa-lead/AGENT.md
+# Output: name: qa-lead
+
+# Construct full type: specweave:qa-lead:qa-lead
+```
+
+## Common Mistakes
+
+```typescript
+// ❌ WRONG: Missing directory/name part
+Task({ subagent_type: "specweave:qa-lead", ... });
+// Error: Agent type 'specweave:qa-lead' not found
+
+// ✅ CORRECT: Full pattern with directory and name
+Task({ subagent_type: "specweave:qa-lead:qa-lead", ... });
+```
+
+## See Also
+
+- **Agent Details**: Each agent's `AGENT.md` file contains full documentation
+- **CLAUDE.md**: Section 15 - Skills vs Agents: Understanding the Distinction
+- **Plugin Validation**: `scripts/validate-plugin-directories.sh`

package/plugins/specweave/agents/architect/AGENT.md

@@ -8,6 +8,23 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+# Architect Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:architect:architect",
+  prompt: "Design system architecture for user authentication"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: architect (folder name)
+// - name: architect (from YAML frontmatter above)
+```
+
 # Architect Agent - System Architecture & Technical Design Expert
 
 You are an expert System Architect with 15+ years of experience designing scalable, maintainable systems across multiple domains (SaaS, e-commerce, fintech, healthcare).

package/plugins/specweave/agents/code-standards-detective/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: research
 fallback_behavior: strict
 ---
 
+# code-standards-detective Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:code-standards-detective:code-standards-detective",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: code-standards-detective (folder name)
+// - name: code-standards-detective (from YAML frontmatter above)
+```
 # Code Standards Detective Agent
 
 **Purpose**: Autonomously discover and document coding standards from existing codebases using statistical analysis and pattern detection.

package/plugins/specweave/agents/docs-writer/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: hybrid
 fallback_behavior: auto
 ---
 
+# docs-writer Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:docs-writer:docs-writer",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: docs-writer (folder name)
+// - name: docs-writer (from YAML frontmatter above)
+```
 # Docs Writer Agent - Technical Documentation Expert
 
 You are an expert technical writer with 8+ years of experience creating clear, comprehensive documentation for developers and end-users.