buildflow-dev 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikas Gurrapu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# BuildFlow
+
+> Adaptive AI-powered development orchestration
+
+[![npm version](https://badge.fury.io/js/buildflow-dev.svg)](https://www.npmjs.com/package/buildflow-dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+# Interactive setup (recommended)
+npx buildflow-dev init
+```
+
+```bash
+# Or install globally
+npm install -g buildflow-dev
+buildflow init
+```
+
+---
+
+## What It Does
+
+`buildflow init` will:
+
+1. **Detect your project** — existing codebase or greenfield, your framework, language, test setup
+2. **Set up `.buildflow/`** — agents, memory, security rules, codebase knowledge
+3. **Detect installed AI tools** — Claude Code, Gemini CLI, Codex CLI, Cursor, Cline, Continue
+4. **Install `/buildflow-*` slash commands** into each detected tool
+5. **You type `/` in your AI tool** to see and use the commands
+
+---
+
+## Supported AI Tools
+
+| Tool | Detection | Global Install | Local Install | Slash Commands |
+|------|-----------|----------------|---------------|----------------|
+| **Claude Code** | ✓ Auto-detect | `~/.claude/commands/` | `.claude/commands/` | `/buildflow-*` |
+| **Gemini CLI** | ✓ Auto-detect | `~/.gemini/commands/` | `.gemini/commands/` | `/buildflow-*` |
+| **Codex CLI** | ✓ Auto-detect | `~/.codex/instructions/` | `.codex/instructions/` | `/buildflow-*` |
+| **Cursor** | ✓ Auto-detect | (local only) | `.cursor/rules/` | `@buildflow-*` |
+| **Cline** | ✓ Auto-detect | (local only) | `.clinerules` | `/buildflow-*` |
+| **Continue** | ✓ Auto-detect | `~/.continue/` | `.continue/` | `/buildflow-*` |
+
+---
+
+## Commands (type `/` in your AI tool)
+
+### Workflow
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `/buildflow-start` | Begin project (smart mode detection) | ~8K |
+| `/buildflow-think` | Discuss & research (parallel agents) | ~30K |
+| `/buildflow-plan` | Create execution plan | ~20K |
+| `/buildflow-build` | Execute plan (parallel waves) | ~50K/task |
+| `/buildflow-check` | Verify quality | ~20K |
+| `/buildflow-ship` | Finalize + **security gate** | ~22K |
+
+### Existing Codebase
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `/buildflow-onboard` | Map codebase (run once) | ~35K |
+| `/buildflow-modify` | Change existing code safely | ~30K |
+| `/buildflow-refactor` | Improve existing code | ~40K |
+
+### Security
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `/buildflow-audit` | Full OWASP Top 10 scan | ~35K |
+| `/buildflow-audit --quick` | Recent changes only | ~15K |
+
+### Utility
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `/buildflow-status` | Where am I? | ~3K |
+| `/buildflow-explain <term>` | Define jargon or describe file | ~2K |
+| `/buildflow-back` | Undo to safe restore point | ~3K |
+| `/buildflow-help` | Diagnostic recovery | ~15K |
+
+---
+
+## CLI Commands (terminal, outside AI tool)
+
+```bash
+buildflow init          # Set up BuildFlow + install slash commands
+buildflow install       # (Re)install into AI tools
+buildflow install --tool claude  # Install into specific tool
+buildflow install --tool all     # Install into all detected tools
+buildflow audit         # Terminal-level security scan (pattern-based)
+buildflow audit --quick # Scan recent changes only
+buildflow status        # Show project state
+buildflow update        # Update commands to latest version
+```
+
+---
+
+## How It Works
+
+### 9 Specialized Agents
+
+Each agent gets a **fresh 200K context window** — no context rot.
+
+| Agent | Role | Used In |
+|-------|------|---------|
+| 🎯 Strategist | Vision & decisions | `/buildflow-start`, `/buildflow-think` |
+| 🔍 Researcher | Parallel web research with source confidence | `/buildflow-think` |
+| 🔄 Synthesizer | Combines parallel research findings | `/buildflow-think` |
+| 🏗️ Architect | Dependency-aware planning | `/buildflow-plan` |
+| ⚒️ Builder | Code matching your style (parallel) | `/buildflow-build` |
+| 🔬 Reviewer | Quality checks (parallel) | `/buildflow-check` |
+| 🗺️ Cartographer | Maps existing codebases | `/buildflow-onboard` |
+| 🩺 Surgeon | Precise code modification | `/buildflow-modify` |
+| 🔒 Security Auditor | OWASP Top 10 scanning | `/buildflow-audit`, `/buildflow-ship` |
+
+### Parallelization
+
+Research and building run agents in parallel:
+
+```
+Sequential: 3 research topics × 60s = 180s
+Parallel:   3 researchers simultaneously = 60s (67% faster)
+```
+
+### Light Memory
+
+`.buildflow/memory/light.md` persists essentials across sessions (under 5K tokens). Saves more than it costs.
+
+### Security Gate
+
+Every `/buildflow-ship` runs a pre-ship security check:
+- 🔴 Critical → **BLOCKED** (must fix)
+- 🟡 High → WARNING (can ship, log to DEBT.md)
+- ✅ Clean → Ship freely
+
+---
+
+## Project Structure
+
+```
+your-project/
+├── .buildflow/
+│   ├── core/
+│   │   ├── vision.md          ← What you're building
+│   │   └── state.md           ← Current position
+│   ├── you/
+│   │   ├── preferences.md     ← Your settings
+│   │   └── style-guide.md     ← Auto-detected code style
+│   ├── memory/
+│   │   └── light.md           ← Persistent context (≤5K)
+│   ├── codebase/              ← Existing project maps
+│   │   ├── MAP.md
+│   │   ├── PATTERNS.md
+│   │   ├── DEPENDENCIES.md
+│   │   └── HOTSPOTS.md
+│   ├── security/
+│   │   ├── DEBT.md
+│   │   └── reports/
+│   ├── phases/                ← Per-phase work
+│   └── learnings/             ← Glossary, decisions
+│
+├── commands/buildflow/        ← Slash command definitions
+│   ├── start.md
+│   ├── think.md
+│   └── ... (14 commands)
+│
+└── agents/                    ← Agent personalities
+    ├── strategist.md
+    └── ... (9 agents)
+```
+
+For AI tools with dedicated directories:
+
+```
+~/.claude/commands/buildflow-*.md   ← Global Claude Code
+.claude/commands/buildflow-*.md     ← Local Claude Code
+~/.gemini/commands/buildflow-*.md   ← Global Gemini CLI
+.cursor/rules/buildflow.mdc         ← Cursor
+.clinerules                          ← Cline
+```
+
+---
+
+## Examples
+
+### New project
+
+```bash
+mkdir my-app && cd my-app
+npx buildflow-dev init
+
+# → Detects: No existing code (greenfield)
+# → Detects: Claude Code ✓, Cursor ✓
+# → Installs commands into both
+# → Opens Claude Code...
+
+/buildflow-start
+/buildflow-think tech-stack
+/buildflow-plan phase-1
+/buildflow-build phase-1
+/buildflow-check
+/buildflow-ship    ← security gate runs automatically
+```
+
+### Existing project
+
+```bash
+cd my-existing-app
+npx buildflow-dev init
+
+# → Detects: Next.js project
+# → Detects: Claude Code ✓
+# → Installs commands
+# → Opens Claude Code...
+
+/buildflow-onboard          ← one-time codebase analysis
+/buildflow-modify "Add dark mode to settings page"
+/buildflow-refactor src/components/Dashboard.tsx
+/buildflow-audit --quick    ← security check on recent changes
+```
+
+---
+
+## Token Economics
+
+| Mode | Per Session | Notes |
+|------|-------------|-------|
+| Greenfield | 130-160K | Full workflow |
+| Existing (first time) | +35K | One-time onboarding |
+| Existing (after onboard) | 130-160K | Same as greenfield |
+| Security gate (pre-ship) | +10K | Always runs with ship |
+
+Light memory SAVES ~10K per session vs no memory (avoids re-detection).
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/new-agent`
+3. Make changes
+4. Run tests: `npm test`
+5. Submit a PR
+
+---
+
+## License
+
+MIT © 2026
+
+---
+
+## Roadmap
+
+- [ ] `buildflow install --tool windsurf` (Windsurf IDE)
+- [ ] `buildflow install --tool aider` (Aider CLI)
+- [ ] Web dashboard for project status
+- [ ] Team collaboration features
+- [ ] GitHub Actions integration
+- [ ] Custom agent creation wizard

package/bin/buildflow.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+import { program } from 'commander'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'))
+
+const loadInit    = () => import('../src/commands/init.js')
+const loadInstall = () => import('../src/commands/install.js')
+const loadAudit   = () => import('../src/commands/audit.js')
+const loadStatus  = () => import('../src/commands/status.js')
+const loadUpdate  = () => import('../src/commands/update.js')
+
+program
+  .name('buildflow')
+  .description('Adaptive AI-powered development orchestration')
+  .version(pkg.version)
+
+program
+  .command('init')
+  .description('Initialize BuildFlow in the current project')
+  .option('-y, --yes', 'Skip prompts, use defaults')
+  .option('--greenfield', 'Start a brand-new project')
+  .option('--existing', 'Add BuildFlow to existing codebase')
+  .action(async (opts) => {
+    const { run } = await loadInit()
+    await run(opts)
+  })
+
+program
+  .command('install')
+  .description('Install BuildFlow slash commands into an AI tool')
+  .option('--tool <name>', 'AI tool to install into (claude|gemini|codex|cursor|all)')
+  .option('--global', 'Install globally (available in all projects)')
+  .option('--local', 'Install locally (current project only)')
+  .action(async (opts) => {
+    const { run } = await loadInstall()
+    await run(opts)
+  })
+
+program
+  .command('audit')
+  .description('Run a security audit on the current project')
+  .option('-q, --quick', 'Quick audit (recent changes only)')
+  .option('-t, --target <path>', 'Audit specific file or directory')
+  .option('-c, --category <name>', 'Check specific OWASP category (A01-A10)')
+  .option('-r, --report', 'Show latest report')
+  .action(async (opts) => {
+    const { run } = await loadAudit()
+    await run(opts)
+  })
+
+program
+  .command('status')
+  .description('Show BuildFlow status for current project')
+  .option('-v, --verbose', 'Show detailed status')
+  .action(async (opts) => {
+    const { run } = await loadStatus()
+    await run(opts)
+  })
+
+program
+  .command('update')
+  .description('Update BuildFlow commands and agents in current project')
+  .option('--check', 'Check for updates without applying')
+  .action(async (opts) => {
+    const { run } = await loadUpdate()
+    await run(opts)
+  })
+
+if (process.argv.length <= 2) {
+  const { showWelcome } = await import('../src/utils/welcome.js')
+  await showWelcome()
+  process.exit(0)
+}
+
+program.parse()

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "buildflow-dev",
+  "version": "1.0.0",
+  "description": "Adaptive AI-powered development orchestration. Works with Claude Code, Gemini CLI, Codex CLI, Cursor, and more.",
+  "keywords": [
+    "ai",
+    "claude",
+    "gemini",
+    "codex",
+    "cursor",
+    "developer-tools",
+    "cli",
+    "workflow",
+    "scaffolding",
+    "security-audit",
+    "code-generation"
+  ],
+  "homepage": "https://github.com/Vikas-gurrapu/buildflow",
+  "bugs": {
+    "url": "https://github.com/Vikas-gurrapu/buildflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vikas-gurrapu/buildflow.git"
+  },
+  "license": "MIT",
+  "author": "Vikas Gurrapu <vikas.gurrapu@gmail.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "buildflow": "./bin/buildflow.js",
+    "bf": "./bin/buildflow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/buildflow.js",
+    "test": "node --test src/**/*.test.js",
+    "lint": "eslint src/ bin/",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "enquirer": "^2.4.1",
+    "ora": "^8.0.1",
+    "which": "^4.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/commands/audit.js

@@ -0,0 +1,230 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'fs'
+import { join, relative, resolve } from 'path'
+
+const SECRET_PATTERNS = [
+  { pattern: /(?<![a-zA-Z])(sk|pk|rk)[-_][a-zA-Z0-9]{20,}/g,             label: 'API Key (sk/pk/rk)' },
+  { pattern: /AKIA[0-9A-Z]{16}/g,                                           label: 'AWS Access Key' },
+  { pattern: /-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY/g,            label: 'Private Key' },
+  { pattern: /['"]\s*(password|passwd|pwd|secret|api.?key|auth.?token)\s*['"]?\s*[:=]\s*['"][^'"]{4,}/gi, label: 'Hardcoded credential' },
+  { pattern: /postgres:\/\/[^@]+:[^@]+@/g,                                  label: 'DB URL with credentials' },
+  { pattern: /mongodb(\+srv)?:\/\/[^@]+:[^@]+@/g,                           label: 'MongoDB URL with credentials' },
+]
+
+const VULN_PATTERNS = [
+  {
+    pattern: /\.query\s*\(\s*[`'"]\s*SELECT.*?\$\{|\.query\s*\(\s*["'`].*?\+\s*\w/gs,
+    label: 'Possible SQL Injection',
+    severity: 'CRITICAL',
+    owasp: 'A03',
+  },
+  {
+    pattern: /eval\s*\(/g,
+    label: 'eval() usage',
+    severity: 'HIGH',
+    owasp: 'A03',
+  },
+  {
+    pattern: /exec\s*\(\s*[`'"]\s*.*?\$\{|execSync\s*\(\s*[`'"]\s*.*?\$\{/g,
+    label: 'Command injection risk',
+    severity: 'CRITICAL',
+    owasp: 'A03',
+  },
+  {
+    pattern: /Math\.random\s*\(\)/g,
+    label: 'Math.random() used for tokens (not cryptographically secure)',
+    severity: 'HIGH',
+    owasp: 'A07',
+  },
+  {
+    pattern: /console\.log\s*\([^)]*(?:password|token|secret|key|user)[^)]*\)/gi,
+    label: 'Sensitive data may be logged',
+    severity: 'MEDIUM',
+    owasp: 'A09',
+  },
+]
+
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java'])
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '__pycache__', 'coverage'])
+
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      yield* walkFiles(full)
+    } else if (CODE_EXTENSIONS.has(entry.slice(entry.lastIndexOf('.')))) {
+      yield full
+    }
+  }
+}
+
+function scanFile(filePath) {
+  let content
+  try { content = readFileSync(filePath, 'utf8') } catch { return [] }
+
+  const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath) ||
+                     filePath.includes('__tests__') ||
+                     filePath.includes('fixtures')
+
+  const findings = []
+  const lines = content.split('\n')
+
+  if (!isTestFile) {
+    for (const { pattern, label } of SECRET_PATTERNS) {
+      for (let i = 0; i < lines.length; i++) {
+        pattern.lastIndex = 0
+        if (pattern.test(lines[i])) {
+          findings.push({
+            type: 'SECRET',
+            severity: 'CRITICAL',
+            label,
+            file: filePath,
+            line: i + 1,
+            snippet: lines[i].trim().slice(0, 80),
+          })
+        }
+      }
+    }
+  }
+
+  for (const { pattern, label, severity, owasp } of VULN_PATTERNS) {
+    for (let i = 0; i < lines.length; i++) {
+      pattern.lastIndex = 0
+      if (pattern.test(lines[i])) {
+        findings.push({
+          type: 'VULN',
+          severity,
+          label,
+          owasp,
+          file: filePath,
+          line: i + 1,
+          snippet: lines[i].trim().slice(0, 80),
+        })
+      }
+    }
+  }
+
+  return findings
+}
+
+export async function run(opts = {}) {
+  const cwd = process.cwd()
+  const base = join(cwd, '.buildflow')
+
+  if (!existsSync(base)) {
+    console.log(chalk.yellow('\n  BuildFlow not initialized. Run: npx buildflow-dev init\n'))
+    return
+  }
+
+  if (opts.report) {
+    const reportsDir = join(base, 'security', 'reports')
+    if (!existsSync(reportsDir)) {
+      console.log(chalk.dim('\n  No reports yet. Run: buildflow audit\n'))
+      return
+    }
+    const reports = readdirSync(reportsDir).filter(f => f.endsWith('.md')).sort().reverse()
+    if (reports.length === 0) {
+      console.log(chalk.dim('\n  No reports yet.\n'))
+      return
+    }
+    console.log('\n' + readFileSync(join(reportsDir, reports[0]), 'utf8'))
+    return
+  }
+
+  console.log('\n' + chalk.bold.white('  BuildFlow — Security Audit\n'))
+
+  const target = opts.target ? resolve(opts.target) : cwd
+  const spinner = ora('Scanning files...').start()
+
+  const allFindings = []
+  let fileCount = 0
+
+  for (const filePath of walkFiles(target)) {
+    fileCount++
+    allFindings.push(...scanFile(filePath))
+  }
+
+  spinner.stop()
+
+  const critical = allFindings.filter(f => f.severity === 'CRITICAL')
+  const high     = allFindings.filter(f => f.severity === 'HIGH')
+  const medium   = allFindings.filter(f => f.severity === 'MEDIUM')
+
+  console.log(chalk.dim(`  Scanned ${fileCount} files\n`))
+
+  const severityLine = [
+    critical.length > 0 ? chalk.red(`  🔴 ${critical.length} critical`)    : chalk.dim('  🟤 0 critical'),
+    high.length > 0     ? chalk.yellow(`  🟡 ${high.length} high`)          : chalk.dim('  ○ 0 high'),
+    medium.length > 0   ? chalk.yellow(`  🟠 ${medium.length} medium`)      : chalk.dim('  ○ 0 medium'),
+  ].join('   ')
+  console.log(severityLine + '\n')
+
+  if (allFindings.length === 0) {
+    console.log(chalk.green('  ✓ No issues found in quick scan.\n'))
+    console.log(chalk.dim('  Note: This is a pattern-based scan. For full OWASP analysis,'))
+    console.log(chalk.dim('  run /buildflow-audit inside your AI tool.\n'))
+    return
+  }
+
+  const printGroup = (findings, icon, color) => {
+    for (const f of findings) {
+      const rel = relative(cwd, f.file)
+      console.log(color(`  ${icon} [${f.severity}] ${f.label}`))
+      console.log(chalk.dim(`      File: ${rel}:${f.line}`))
+      console.log(chalk.dim(`      Code: ${f.snippet}`))
+      if (f.owasp) console.log(chalk.dim(`      OWASP: ${f.owasp}`))
+      console.log('')
+    }
+  }
+
+  if (critical.length > 0) {
+    console.log(chalk.bold.red('  ── Critical ──────────────────────────\n'))
+    printGroup(critical, '🔴', chalk.red)
+  }
+  if (high.length > 0) {
+    console.log(chalk.bold.yellow('  ── High ──────────────────────────────\n'))
+    printGroup(high, '🟡', chalk.yellow)
+  }
+  if (medium.length > 0) {
+    console.log(chalk.bold.yellow('  ── Medium ────────────────────────────\n'))
+    printGroup(medium, '🟠', chalk.yellow)
+  }
+
+  const reportsDir = join(base, 'security', 'reports')
+  mkdirSync(reportsDir, { recursive: true })
+  const reportDate = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -1)
+  const reportPath = join(reportsDir, `audit-${reportDate}.md`)
+
+  const reportContent = `# Security Audit Report
+Date: ${new Date().toISOString().split('T')[0]}
+Scanner: buildflow-dev CLI (pattern scan)
+Files scanned: ${fileCount}
+
+## Summary
+Critical: ${critical.length}
+High: ${high.length}
+Medium: ${medium.length}
+
+## Findings
+
+${allFindings.map(f =>
+    `### [${f.severity}] ${f.label}\n- File: ${relative(cwd, f.file)}:${f.line}\n- Code: \`${f.snippet}\`${f.owasp ? `\n- OWASP: ${f.owasp}` : ''}\n`
+  ).join('\n')}
+
+## Notes
+This is a pattern-based CLI scan. For deep OWASP analysis, run /buildflow-audit in your AI tool.
+`
+
+  writeFileSync(reportPath, reportContent)
+
+  console.log(chalk.bold('\n  Recommendations:\n'))
+  if (critical.length > 0) {
+    console.log(chalk.red('  Fix critical issues before committing or shipping.'))
+  }
+  console.log(chalk.dim(`\n  Report saved: ${relative(cwd, reportPath)}`))
+  console.log(chalk.dim('  For full AI-powered analysis: /buildflow-audit in your AI tool\n'))
+
+  if (critical.length > 0) process.exit(1)
+}