buildflow-dev 1.0.0

package/templates/commands/onboard.md

@@ -0,0 +1,78 @@
+---
+name: buildflow-onboard
+description: Analyze existing codebase and create knowledge maps
+allowed-tools: Read, Bash, Glob, Grep
+agent: cartographer
+---
+
+# /buildflow-onboard
+
+ONE-TIME analysis of your existing codebase. Creates knowledge maps for all other agents.
+
+## When to Run
+- First time using BuildFlow on existing project
+- After major refactor
+- After framework upgrade
+- Use --update flag to refresh incrementally
+
+## Step 1: Check Prior State
+If `.buildflow/codebase/MAP.md` exists, ask: "Re-onboard (full) or update (incremental)?"
+
+## Step 2: Structural Analysis
+- Read folder structure
+- Find entry points (package.json, main.py, Cargo.toml, go.mod)
+- Map src/ organization
+- Note configuration files
+
+## Step 3: Technology Detection
+Parse dependency files. Detect:
+- Language(s)
+- Framework(s)
+- Major libraries
+- Build tools
+- Test setup
+
+## Step 4: Pattern Recognition
+Read 5-10 representative source files. Document:
+- Component structure conventions
+- Naming patterns (PascalCase, camelCase, snake_case)
+- Import organization order
+- Comment style
+- Error handling approach
+- Test file conventions
+
+## Step 5: Complexity Assessment
+- Identify large files (>300 lines)
+- Find deeply nested code
+- Note files with many imports (high coupling)
+- Mark as HOTSPOTS for Surgeon agent
+
+## Step 6: Generate Knowledge Files
+
+Write these files:
+
+### `.buildflow/codebase/MAP.md`
+Architecture overview, folder structure, entry points, key patterns, top dependencies.
+
+### `.buildflow/codebase/PATTERNS.md`
+Code conventions: naming, component structure, imports, comments, error handling, testing.
+
+### `.buildflow/codebase/DEPENDENCIES.md`
+Top 10-15 dependencies with purpose, criticality, and security status.
+
+### `.buildflow/codebase/HOTSPOTS.md`
+Files to handle carefully: high complexity, frequently changed, low test coverage.
+
+## Step 7: Update Memory
+```yaml
+.buildflow/memory/light.md:
+  onboarded: true
+  onboarded_date: [today]
+  codebase_summary: [3-line summary]
+```
+
+## Step 8: Summary
+Show: framework, file count, test coverage estimate, complexity summary.
+Suggest: /buildflow-modify, /buildflow-refactor, or /buildflow-think.
+
+## Token Budget: 30-40K (one-time cost, pays back immediately)

package/templates/commands/plan.md

@@ -0,0 +1,60 @@
+---
+name: buildflow-plan
+description: Create a dependency-aware execution plan with the Architect agent
+allowed-tools: Read, Write
+agent: architect
+---
+
+# /buildflow-plan
+
+Create a detailed, phased execution plan. The Architect agent maps dependencies before sequencing work.
+
+## Usage
+- `/buildflow-plan` — plan the next phase
+- `/buildflow-plan phase-2` — plan a specific phase
+- `/buildflow-plan <feature>` — plan a specific feature
+
+## Step 1: Load Context
+Read `.buildflow/core/vision.md`, `.buildflow/memory/light.md`.
+If existing project: read `.buildflow/codebase/MAP.md` and `DEPENDENCIES.md`.
+
+## Step 2: Scope Confirmation
+Ask: "What are we building in this phase? What's the definition of done?"
+Confirm scope before planning.
+
+## Step 3: Dependency Mapping
+List all components/features needed. For each:
+- What does it depend on?
+- What depends on it?
+- Can it be built in parallel?
+
+## Step 4: Task Breakdown
+For each task:
+```
+Task: [name]
+Description: [what it does]
+Depends on: [prerequisite tasks]
+Parallelizable: yes/no
+Estimated complexity: low/medium/high
+Files affected: [list]
+```
+
+## Step 5: Wave Planning
+Group tasks into parallel waves:
+```
+Wave 1 (parallel): [tasks with no dependencies]
+Wave 2 (parallel): [tasks depending only on Wave 1]
+Wave 3: [tasks depending on Wave 2]
+```
+
+## Step 6: Risk Check
+Identify:
+- Tasks with high complexity
+- Tasks touching security-sensitive code
+- Tasks requiring external APIs or services
+
+## Step 7: Save Plan
+Write to `.buildflow/phases/[N]/PLAN.md`
+Update state.md with current phase number.
+
+## Token Budget: ~20K

package/templates/commands/refactor.md

@@ -0,0 +1,58 @@
+---
+name: buildflow-refactor
+description: Improve existing code quality without changing behavior
+allowed-tools: Read, Write, Grep, Glob, Bash
+agents: surgeon, reviewer
+---
+
+# /buildflow-refactor
+
+Improve code quality, readability, or performance — without changing observable behavior.
+
+## Usage
+- `/buildflow-refactor src/components/Dashboard.tsx`
+- `/buildflow-refactor "Extract auth logic into middleware"`
+- `/buildflow-refactor --scope=module src/api/`
+
+## Step 1: Load Context
+Read `.buildflow/codebase/MAP.md`, `PATTERNS.md`, `HOTSPOTS.md`.
+
+## Step 2: Define Refactor Goal
+Clarify what kind of improvement:
+- Readability (rename, extract function, reduce nesting)
+- Performance (memoization, lazy loading, caching)
+- Maintainability (extract module, reduce coupling)
+- Test coverage (add tests for existing logic)
+
+## Step 3: Behavior Contract
+Before refactoring:
+- Document current behavior (inputs → outputs)
+- Identify existing tests
+- Note any implicit side effects
+
+The refactor must NOT change this contract.
+
+## Step 4: Restore Point
+```bash
+git commit -m "pre-refactor restore point: [scope]"
+```
+
+## Step 5: Incremental Refactor
+Small, reviewable steps:
+1. Rename in isolation
+2. Extract without logic changes
+3. Move with no modifications
+4. Simplify one function at a time
+
+After each step: verify behavior unchanged.
+
+## Step 6: Quality Check (Reviewer agent)
+- Is the refactored code simpler?
+- Are existing tests still passing?
+- Does it match PATTERNS.md conventions?
+- Any new complexity introduced?
+
+## Step 7: Update Codebase Map
+If patterns changed significantly, update `.buildflow/codebase/PATTERNS.md`.
+
+## Token Budget: ~40K

package/templates/commands/ship.md

@@ -0,0 +1,97 @@
+---
+name: buildflow-ship
+description: Finalize phase with mandatory pre-ship security gate
+allowed-tools: Read, Write, Bash
+agents: strategist, security-auditor
+---
+
+# /buildflow-ship
+
+Finalize current phase. Security gate runs automatically before shipping.
+
+## MANDATORY Step 0: Pre-Ship Security Gate
+
+Spawn Security Auditor in `--pre-ship` mode:
+- Scan only changed files (git diff since last commit)
+- Check for secrets
+- Check critical injection patterns
+- Check auth bypass risks
+- Check critical dependency CVEs
+- Token cost: ~10K
+
+### Gate Outcomes
+
+**Critical found → BLOCK:**
+```
+🔴 SHIP BLOCKED — Critical Security Issues
+
+Fix these before shipping:
+[C1] [Issue] at [file:line]
+     Fix: [specific action]
+
+Run /buildflow-modify for surgical fixes.
+Override (not recommended): /buildflow-ship --force
+```
+
+**High found → WARN:**
+```
+⚠️  Security Warnings (non-blocking)
+[H1] [Issue]
+     Risk: [...]
+     Fix later: /buildflow-audit for details
+```
+
+**Clean → proceed:**
+```
+✅ Security gate passed. No critical issues.
+```
+
+## Step 1: Pre-Ship Checklist
+- [ ] All acceptance criteria met
+- [ ] /buildflow-check passed
+- [ ] Tests pass
+- [ ] Security gate passed (above)
+
+## Step 2: Retrospective
+Ask:
+1. What worked well this phase?
+2. What was harder than expected?
+3. What did you learn?
+4. Confidence in deliverables (1-5)?
+
+Save to `.buildflow/phases/[N]/retro.md`
+
+## Step 3: Update Docs
+- README if needed
+- vision.md if pivots occurred
+- state.md: Phase X → Shipped
+
+## Step 4: Update Codebase Map (existing projects)
+If patterns changed, new hotspots added, or dependencies updated:
+- Update PATTERNS.md
+- Update HOTSPOTS.md
+- Update DEPENDENCIES.md
+
+## Step 5: Tag Release
+```bash
+git add .
+git commit -m "buildflow: phase X shipped"
+git tag "buildflow-phase-X-complete"
+```
+
+## Step 6: Update Memory
+```yaml
+last_ship_date: [today]
+phase: X
+security_gate: passed|passed-with-warnings|overridden
+```
+
+## Step 7: Next Phase
+Suggest next phase based on roadmap.
+
+## --force Override
+If used, adds to `.buildflow/security/DEBT.md` and requires:
+- Typed confirmation: "I understand the risk"
+- Logged with timestamp
+
+## Token Budget: ~22K (including pre-ship audit)

package/templates/commands/start.md

@@ -0,0 +1,39 @@
+---
+name: buildflow-start
+description: Start a project with BuildFlow's Strategist agent
+allowed-tools: Read, Write, WebSearch
+agent: strategist
+---
+
+# /buildflow-start
+
+Begin your project. Works for both greenfield and existing codebases.
+
+## Step 1: Load Memory
+Read `.buildflow/memory/light.md` and `.buildflow/you/preferences.md`.
+
+## Step 2: Detect Mode
+
+**Greenfield (no src/ code):**
+Ask vision questions one at a time:
+1. What are you building?
+2. Who is it for?
+3. What problem does it solve?
+4. What's the simplest useful version?
+5. Timeline, team size, budget?
+6. Confidence in the idea (1-5)?
+
+**Existing codebase (src/ exists):**
+Check if `.buildflow/codebase/MAP.md` exists.
+- If NO: "Run /buildflow-onboard first to analyze your codebase."
+- If YES: Load MAP.md. Ask about goals for this work session.
+
+## Step 3: Save Vision
+Write to `.buildflow/core/vision.md` and update `.buildflow/core/state.md`.
+
+## Step 4: Recommend Next Step
+- High confidence (4-5) + greenfield: "Run /buildflow-think"
+- Low confidence: "Let's research first with /buildflow-think"
+- Existing project, onboarded: "Ready! Try /buildflow-modify or /buildflow-think"
+
+## Token Budget: ~8K

package/templates/commands/status.md

@@ -0,0 +1,50 @@
+---
+name: buildflow-status
+description: Show current project state and phase progress
+allowed-tools: Read
+agent: strategist
+---
+
+# /buildflow-status
+
+Quick orientation — where are you in the BuildFlow workflow?
+
+## Step 1: Load State
+Read `.buildflow/core/state.md` and `.buildflow/memory/light.md`.
+
+## Step 2: Display Summary
+
+```
+Project: [app name]
+Phase: [current phase]
+Status: [Initialized / In Progress / Shipped]
+Type: [greenfield / existing]
+Framework: [detected framework]
+Onboarded: [yes / no / n/a]
+Last session: [date]
+```
+
+## Step 3: Current Phase Progress
+If in a phase, read `.buildflow/phases/[N]/PLAN.md` and show:
+- Total tasks
+- Completed tasks
+- Remaining tasks
+- Estimated completion
+
+## Step 4: Security Status
+Read `.buildflow/security/DEBT.md`:
+- Clean: "No outstanding security debt"
+- Issues: List open items with severity
+
+## Step 5: Recommend Next Action
+
+Based on state:
+- Phase 0 (just initialized): "Run /buildflow-start"
+- Greenfield + no vision: "Run /buildflow-start"
+- Has vision, no plan: "Run /buildflow-think or /buildflow-plan"
+- Has plan, not built: "Run /buildflow-build"
+- Built, not checked: "Run /buildflow-check"
+- Checked: "Run /buildflow-ship"
+- Existing + not onboarded: "Run /buildflow-onboard first"
+
+## Token Budget: ~3K

package/templates/commands/think.md

@@ -0,0 +1,49 @@
+---
+name: buildflow-think
+description: Research and discuss with parallel Researcher agents
+allowed-tools: Read, Write, WebSearch
+agents: strategist, researcher, synthesizer
+---
+
+# /buildflow-think
+
+Deep research and discussion mode. Spawns parallel Researcher agents then synthesizes findings.
+
+## Usage
+- `/buildflow-think` — open-ended discussion
+- `/buildflow-think <topic>` — research a specific topic
+- `/buildflow-think tech-stack` — compare technology options
+- `/buildflow-think risks` — identify project risks
+
+## Step 1: Load Context
+Read `.buildflow/memory/light.md`, `.buildflow/core/vision.md`.
+
+## Step 2: Clarify Research Goal
+Ask: "What do you want to explore or decide?"
+If already specified in the command, confirm understanding.
+
+## Step 3: Parallel Research (if web research needed)
+Spawn up to 3 Researcher agents in parallel, each with:
+- A specific research question
+- Instructions to find 2-3 sources
+- Trust score (1-5) for each source
+- Key findings in bullet points
+
+## Step 4: Synthesize
+Synthesizer agent combines findings:
+- Points of agreement across sources
+- Conflicting information (flag explicitly)
+- Recommendation with confidence (1-5)
+- Open questions remaining
+
+## Step 5: Discussion
+Ask confidence check: "How confident are you in this direction? (1-5)"
+- 1-2: Explore alternatives
+- 3: Identify what would increase confidence
+- 4-5: Move forward, suggest next step
+
+## Step 6: Save Insights
+Write to `.buildflow/research/[topic]-[date].md`
+Update `.buildflow/memory/light.md` with key decisions.
+
+## Token Budget: ~30K (parallel research)