devflow-kit 0.9.0 → 1.0.0

package/dist/utils/safe-delete.js

@@ -0,0 +1,83 @@
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import * as path from 'path';
+export function detectPlatform() {
+    switch (process.platform) {
+        case 'darwin': return 'macos';
+        case 'win32': return 'windows';
+        default: return 'linux';
+    }
+}
+export function detectShell() {
+    // PowerShell detection via PSModulePath (set in all PowerShell sessions)
+    if (process.env.PSModulePath) {
+        return 'powershell';
+    }
+    const shellPath = process.env.SHELL;
+    if (!shellPath)
+        return 'unknown';
+    const shellName = path.basename(shellPath);
+    switch (shellName) {
+        case 'zsh': return 'zsh';
+        case 'bash': return 'bash';
+        case 'fish': return 'fish';
+        default: return 'unknown';
+    }
+}
+export function getProfilePath(shell) {
+    const home = process.env.HOME || homedir();
+    switch (shell) {
+        case 'zsh':
+            return path.join(home, '.zshrc');
+        case 'bash':
+            return path.join(home, '.bashrc');
+        case 'fish':
+            return path.join(home, '.config', 'fish', 'functions', 'rm.fish');
+        case 'powershell': {
+            // PowerShell profile path varies by platform
+            if (process.platform === 'win32') {
+                const docs = process.env.USERPROFILE
+                    ? path.join(process.env.USERPROFILE, 'Documents')
+                    : path.join(home, 'Documents');
+                return path.join(docs, 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+            }
+            return path.join(home, '.config', 'powershell', 'Microsoft.PowerShell_profile.ps1');
+        }
+        case 'unknown':
+            return null;
+    }
+}
+export function getSafeDeleteInfo(platform) {
+    switch (platform) {
+        case 'macos':
+            return {
+                command: 'trash',
+                installHint: 'brew install trash-cli',
+            };
+        case 'linux':
+            return {
+                command: 'trash-put',
+                installHint: 'sudo apt install trash-cli  # or: npm install -g trash-cli',
+            };
+        case 'windows':
+            return {
+                command: null,
+                installHint: null,
+            };
+    }
+}
+export function hasSafeDelete(platform) {
+    if (platform === 'windows')
+        return true; // Windows has recycle bin via .NET
+    const info = getSafeDeleteInfo(platform);
+    if (!info.command)
+        return false;
+    try {
+        execSync(`which ${info.command}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=safe-delete.js.map

package/package.json

@@ -1,25 +1,31 @@
 {
   "name": "devflow-kit",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
-  "main": "dist/index.js",
   "type": "module",
   "bin": {
     "devflow": "dist/cli.js"
   },
   "files": [
     "dist/",
-    "src/claude/",
+    "!dist/**/*.map",
+    "plugins/",
+    "shared/",
+    "scripts/hooks/",
+    "src/templates/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:cli && npm run build:plugins",
+    "build:cli": "tsc",
+    "build:plugins": "npx tsx scripts/build-plugins.ts",
     "dev": "tsc --watch",
     "cli": "node dist/cli.js",
     "prepublishOnly": "npm run build",
-    "test": "echo \"No tests yet\" && exit 0"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "claude",
@@ -40,15 +46,19 @@
   "bugs": {
     "url": "https://github.com/dean0x/devflow/issues"
   },
-  "homepage": "https://github.com/dean0x/devflow#readme",
+  "homepage": "https://dean0x.github.io/x/devflow/",
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "commander": "^12.0.0"
+    "@clack/prompts": "^0.9.1",
+    "commander": "^12.0.0",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
-    "typescript": "^5.3.3"
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
   }
 }

package/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "devflow-audit-claude",
+  "description": "Audit CLAUDE.md files against Anthropic best practices",
+  "version": "1.0.0",
+  "agents": [],
+  "skills": []
+}

package/plugins/devflow-audit-claude/README.md

@@ -0,0 +1,46 @@
+# devflow-audit-claude
+
+Audit CLAUDE.md files against Anthropic's best practices for size, structure, and content quality.
+
+## Command
+
+### `/audit-claude`
+
+Analyzes CLAUDE.md files and reports issues with severity levels and fix suggestions.
+
+```bash
+/audit-claude              # Audit all CLAUDE.md files in project + global
+/audit-claude ./CLAUDE.md  # Audit a specific file
+```
+
+## What It Checks
+
+| Category | What It Finds |
+|----------|--------------|
+| **SIZE** | Files exceeding line/token limits |
+| **MISSING** | Required sections (tech stack, structure, commands) |
+| **ANTI-PATTERN** | Content that belongs elsewhere (runbooks, catalogs, style rules) |
+| **STRUCTURE** | Deep heading nesting, non-scannable layout |
+| **CONTENT** | Generic advice, removable lines, vague instructions |
+| **HIERARCHY** | Duplicated content across root/subdir/global |
+| **INTEGRATION** | Content that should be skills, hooks, or linter config |
+| **CLAUDE-SPECIFIC** | Re-documented skills, agent internals, build details |
+
+## Severity Levels
+
+- **Critical**: File exceeds size limits, missing essential sections
+- **High**: Anti-pattern content (runbooks, catalogs), skill re-documentation
+- **Medium**: Section bloat, generic advice, integration opportunities
+- **Low**: Style issues, minor nesting problems
+
+## Guidelines
+
+Based on Anthropic's official CLAUDE.md guidance:
+- Target < 300 lines for root CLAUDE.md
+- "For each line, ask whether removing it would cause Claude to make mistakes; if not, cut it"
+- Use progressive disclosure: brief summary with pointers to detailed docs
+- CLAUDE.md loads every session — only include universally-applicable guidance
+
+## Agent
+
+- `claude-md-auditor` — Plugin-specific agent that runs the 8-category audit rubric

package/plugins/devflow-audit-claude/agents/claude-md-auditor.md

@@ -0,0 +1,134 @@
+---
+name: claude-md-auditor
+description: Audits CLAUDE.md files against Anthropic best practices for size, structure, and content quality
+model: sonnet
+allowed-tools: Read, Grep, Glob
+---
+
+# CLAUDE.md Auditor
+
+You are a strict auditor that evaluates CLAUDE.md files against Anthropic's official guidance. You find issues that waste tokens, confuse Claude, or belong in other locations. You never soften findings.
+
+## Input Context
+
+- `file_path`: Absolute path to the CLAUDE.md file
+- `location_context`: root | subdirectory | global
+- `tech_stack`: Detected project technologies (optional)
+
+## Audit Rubric
+
+Run all 8 checks against the file. Every finding needs: severity, category tag, line reference, explanation, and fix suggestion.
+
+### 1. Size Limits [SIZE]
+
+| Context | Line Limit | Token Estimate |
+|---------|-----------|----------------|
+| Root CLAUDE.md | < 300 | ~5KB |
+| Subdirectory CLAUDE.md | < 150 | ~2.5KB |
+| Global ~/.claude/CLAUDE.md | < 200 | ~3.5KB |
+
+- Count total lines (excluding blank lines at end)
+- Estimate tokens: word_count * 1.3
+- Flag sections exceeding 50 lines
+- **Critical** if file exceeds limit. **Medium** if any section exceeds 50 lines.
+
+### 2. Required Sections [MISSING]
+
+For root CLAUDE.md, check for presence of:
+- Project overview / purpose (what this project does)
+- Tech stack (languages, frameworks, key dependencies)
+- Project structure (directory layout or key files)
+- Development commands (build, test, run)
+- Key conventions (naming, patterns, gotchas)
+
+**High** if tech stack or project overview is missing. **Medium** for others.
+
+### 3. Anti-Pattern Detection [ANTI-PATTERN]
+
+Flag these content types — they belong elsewhere:
+- **Code style rules** (indentation, semicolons, quotes) — belongs in `.editorconfig` / ESLint / Prettier
+- **Procedural runbooks** (step-by-step release processes, deploy scripts) — belongs in `docs/` or scripts
+- **Reference catalogs** (full API lists, complete type inventories, exhaustive pattern tables) — belongs in `docs/reference/`
+- **Aspirational / motivational content** ("Remember: quality matters!") — provides no operational value
+- **Generic advice** ("test thoroughly", "write clean code") — Claude already knows this
+- **Duplicated content** — information already in skills, agents, or other config files
+
+**High** for procedural runbooks and reference catalogs. **Medium** for others.
+
+### 4. Structure Quality [STRUCTURE]
+
+- Headers should be scannable (clear hierarchy, descriptive names)
+- Maximum 3 heading levels (`#`, `##`, `###`) — deeper nesting hurts readability
+- Sections should use progressive disclosure: brief summary with pointer to detailed doc
+- Code blocks should be minimal — only include code that prevents mistakes
+
+**Medium** for nesting violations. **Low** for style issues.
+
+### 5. Content Quality [CONTENT]
+
+For each line, apply the test: "Would removing this cause Claude to make mistakes?"
+- If no: flag for removal
+- Flag vague instructions ("be careful", "use best practices")
+- Flag obvious statements that any model already follows
+- Prefer specific, actionable instructions over general guidance
+
+**Medium** for removable content. **Low** for vagueness.
+
+### 6. Hierarchical Usage [HIERARCHY]
+
+- Root CLAUDE.md: project-wide guidance only
+- Subdirectory CLAUDE.md: module-specific overrides only
+- Global CLAUDE.md: cross-project preferences only
+- No duplicated content across hierarchy levels
+
+**High** if global file contains project-specific content. **Medium** for duplication.
+
+### 7. Integration Opportunities [INTEGRATION]
+
+Flag content that should be:
+- A **skill** (auto-activating pattern enforcement)
+- A **hook** (pre-commit, post-save automation)
+- A **linter config** (.editorconfig, ESLint, Prettier)
+- A **CI check** (automated enforcement)
+- A **script** (repeatable procedures)
+
+**Medium** for clear integration opportunities.
+
+### 8. Claude Code Specifics [CLAUDE-SPECIFIC]
+
+Flag if file contains:
+- Re-documentation of skill contents (skills auto-load)
+- Plugin manifest details (Claude reads plugin.json directly)
+- Build process internals (belongs in docs/reference/)
+- Agent implementation details (belongs in agent definitions)
+
+**High** for skill/agent re-documentation. **Medium** for build/manifest details.
+
+## Output Format
+
+Return findings as structured markdown:
+
+```markdown
+### File: {file_path} ({line_count} lines, ~{token_estimate} tokens)
+
+#### CRITICAL
+- [{CATEGORY}] {description}. **Fix**: {suggestion}.
+
+#### HIGH
+- [{CATEGORY}] Lines {start}-{end}: {description}. **Fix**: {suggestion}.
+
+#### MEDIUM
+- [{CATEGORY}] {description}. **Fix**: {suggestion}.
+
+#### LOW
+- [{CATEGORY}] {description}. **Fix**: {suggestion}.
+```
+
+Omit severity sections that have no findings. Always include the file summary line with line count and token estimate.
+
+## Boundaries
+
+- **Read-only**: Never modify CLAUDE.md files
+- **No false positives**: Only flag issues you're confident about
+- **Severity accuracy**: Don't inflate severity to seem thorough
+- **Escalate**: If file structure is so unusual you can't assess it, say so

package/plugins/devflow-audit-claude/commands/audit-claude.md

@@ -0,0 +1,85 @@
+# Command: /audit-claude
+
+## Description
+
+Audit CLAUDE.md files against Anthropic's best practices. Finds oversized files, anti-patterns, missing sections, and content that belongs elsewhere. Reports issues with severity levels and fix suggestions.
+
+## Usage
+
+`/audit-claude [path]`
+
+- No argument: audits all CLAUDE.md files in project + `~/.claude/CLAUDE.md`
+- With path: audits the specific file
+
+## Implementation
+
+### Phase 1: Discovery
+
+Find all CLAUDE.md files to audit:
+
+```bash
+# Project CLAUDE.md files
+CLAUDE_FILES=$(find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null)
+
+# Global CLAUDE.md
+GLOBAL_CLAUDE="$HOME/.claude/CLAUDE.md"
+if [ -f "$GLOBAL_CLAUDE" ]; then
+  CLAUDE_FILES="$CLAUDE_FILES $GLOBAL_CLAUDE"
+fi
+```
+
+If a specific path argument was provided, use only that file.
+
+### Phase 2: Analysis
+
+For each discovered file, spawn a `claude-md-auditor` agent:
+
+```
+Task(
+  subagent_type: "claude-md-auditor",
+  prompt: "Audit this CLAUDE.md file: {file_path}
+    File location context: {root|subdirectory|global}
+    Project tech stack: {detected from package.json, go.mod, etc.}
+
+    Return your findings as structured markdown."
+)
+```
+
+Run agents in parallel when multiple files are found.
+
+### Phase 3: Report
+
+Combine all agent outputs into a single report:
+
+```markdown
+## CLAUDE.md Audit Report
+
+### File: ./CLAUDE.md ({line_count} lines, ~{token_estimate} tokens)
+
+#### CRITICAL
+- [{CATEGORY}] {description}. {fix suggestion}.
+
+#### HIGH
+- [{CATEGORY}] Lines {start}-{end}: {description}. {fix suggestion}.
+
+#### MEDIUM
+- [{CATEGORY}] {description}. {fix suggestion}.
+
+#### LOW
+- [{CATEGORY}] {description}. {fix suggestion}.
+
+### Summary
+- {N} Critical, {N} High, {N} Medium, {N} Low
+- Estimated reducible lines: ~{N} (move to docs/reference/)
+- Estimated token cost per session: ~{N} tokens
+```
+
+Present the report directly to the user. Do NOT write to `.docs/` — this is a diagnostic command.
+
+## Output Format
+
+Findings grouped by severity (Critical > High > Medium > Low), each with:
+- **Category tag** in brackets: SIZE, MISSING, ANTI-PATTERN, STRUCTURE, CONTENT, HIERARCHY, INTEGRATION, CLAUDE-SPECIFIC
+- **Line reference** when applicable
+- **Explanation** of why it's an issue
+- **Fix suggestion** with concrete action

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "devflow-code-review",
+  "description": "Comprehensive code review with parallel specialized agents covering security, architecture, performance, and more",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.0.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["review", "code-quality", "security", "architecture", "pr-review"],
+  "agents": ["git", "reviewer", "synthesizer"],
+  "skills": [
+    "accessibility",
+    "agent-teams",
+    "architecture-patterns",
+    "complexity-patterns",
+    "consistency-patterns",
+    "database-patterns",
+    "dependencies-patterns",
+    "documentation-patterns",
+    "frontend-design",
+    "performance-patterns",
+    "react",
+    "regression-patterns",
+    "review-methodology",
+    "security-patterns",
+    "test-patterns"
+  ]
+}

package/plugins/devflow-code-review/README.md

@@ -0,0 +1,73 @@
+# devflow-code-review
+
+Comprehensive code review plugin for Claude Code. Runs parallel specialized review agents covering security, architecture, performance, and more.
+
+## Installation
+
+```bash
+# Via DevFlow CLI
+npx devflow-kit init --plugin=code-review
+
+# Via Claude Code (when available)
+/plugin install dean0x/devflow-code-review
+```
+
+## Usage
+
+```
+/code-review                    # Review current branch
+/code-review <branch-name>      # Review specific branch
+/code-review #123               # Review PR by number
+```
+
+## Review Focus Areas
+
+The plugin spawns 7-11 parallel Reviewer agents, each with a specific focus:
+
+| Focus | What It Checks |
+|-------|----------------|
+| security | Injection, auth, crypto, OWASP vulnerabilities |
+| architecture | SOLID violations, coupling, layering |
+| performance | Algorithms, N+1 queries, memory, I/O |
+| complexity | Cyclomatic complexity, readability |
+| consistency | Pattern violations, style drift |
+| regression | Lost functionality, broken behavior |
+| tests | Coverage gaps, brittle tests |
+| database | Schema issues, slow queries |
+| dependencies | CVEs, outdated packages |
+| documentation | Doc drift, stale comments |
+
+## Components
+
+### Command
+- `/code-review` - Comprehensive branch review
+
+### Agents
+- `git` - GitHub operations (PR comments)
+- `reviewer` - Universal parameterized reviewer
+- `synthesizer` - Combines review outputs
+
+### Skills (11)
+- `review-methodology` - 6-step review process
+- `security-patterns` - Security vulnerabilities
+- `architecture-patterns` - Design patterns
+- `performance-patterns` - Performance issues
+- `complexity-patterns` - Complexity metrics
+- `consistency-patterns` - Pattern violations
+- `regression-patterns` - Regression detection
+- `test-patterns` - Test quality
+- `database-patterns` - Database issues
+- `dependencies-patterns` - Dependency management
+- `documentation-patterns` - Documentation quality
+
+## Output
+
+- Review summary in `.docs/reviews/{branch-slug}/`
+- Individual reports per focus area
+- Issues categorized as P0/P1/P2 with file:line references
+- Actionable fixes for each issue
+
+## Related Plugins
+
+- [devflow-implement](../devflow-implement) - Implement features
+- [devflow-resolve](../devflow-resolve) - Fix code review issues