buildflow-dev 1.0.1 → 1.0.3

package/src/commands/init.js

@@ -86,36 +86,409 @@ function scaffoldBuildflow(appName, projectInfo) {
   for (const d of dirs) mkdirSync(join(base, d), { recursive: true })
 
   const today = new Date().toISOString().split('T')[0]
+  const isExisting = projectInfo.projectType === 'existing'
 
-  writeFileSync(join(base, 'core', 'vision.md'),
-    projectInfo.projectType === 'existing'
-      ? `# Project Vision: ${appName}\n\n## Type\nExisting ${projectInfo.framework} project\n\n## Goals\n[Fill during /buildflow-start]\n\n---\nInitialized: ${today}\n`
-      : `# Project Vision: ${appName}\n\n## What I'm Building\n[Fill during /buildflow-start]\n\n---\nInitialized: ${today}\n`
-  )
+  // ── core/vision.md ──────────────────────────────────────────────────────────
+  writeFileSync(join(base, 'core', 'vision.md'), isExisting
+    ? `# Vision — ${appName}
 
+> **Purpose:** This file is the source of truth for what you're building.
+> Every agent reads it at session start to stay aligned with your goals.
+> Fill it in during your first \`/buildflow-start\` session.
+
+---
+
+## Project Type
+
+**Existing ${projectInfo.framework} project** — language: ${projectInfo.language}
+
+---
+
+## Goals for This Project
+
+> What do you want to achieve by using BuildFlow on this codebase?
+> Examples: "Add auth system", "Migrate to TypeScript", "Improve performance"
+
+- [ ] Goal 1 — *(fill in)*
+- [ ] Goal 2 — *(fill in)*
+
+---
+
+## What NOT to Change
+
+> Any areas of the codebase that are off-limits or need special care?
+
+*(fill in or delete this section)*
+
+---
+
+## Success Criteria
+
+> How will you know the work is done and done well?
+
+- [ ] *(fill in)*
+
+---
+
+*Initialized: ${today} · BuildFlow v3.0*
+`
+    : `# Vision — ${appName}
+
+> **Purpose:** This file is the source of truth for what you're building.
+> Every agent reads it at session start to stay aligned with your goals.
+> Fill it in during your first \`/buildflow-start\` session.
+
+---
+
+## What I'm Building
+
+> One paragraph: what is this product, tool, or service?
+
+*(fill in during /buildflow-start)*
+
+---
+
+## Who It's For
+
+> Describe the target user. Be specific — "developers using Node.js" beats "developers".
+
+*(fill in)*
+
+---
+
+## Problem It Solves
+
+> What exists today that's painful, broken, or missing?
+
+*(fill in)*
+
+---
+
+## Success Criteria
+
+> How will you know it's working? Measurable outcomes are better than vague goals.
+
+- [ ] *(fill in)*
+
+---
+
+## Simplest Useful Version (MVP)
+
+> What's the smallest thing you can ship that delivers real value?
+
+*(fill in)*
+
+---
+
+## Constraints
+
+| Constraint    | Value         |
+|---------------|---------------|
+| Target date   | —             |
+| Team size     | —             |
+| Stack         | ${projectInfo.language !== 'unknown' ? projectInfo.language : '—'} |
+
+---
+
+*Initialized: ${today} · BuildFlow v3.0*
+`)
+
+  // ── core/state.md ───────────────────────────────────────────────────────────
   writeFileSync(join(base, 'core', 'state.md'),
-    `# State\n\nProject: ${appName}\nType: ${projectInfo.projectType}\nFramework: ${projectInfo.framework}\nPhase: 0\nStatus: Initialized\nBuildFlow: 3.0\nDate: ${today}\n`
-  )
+    `# Project State
+
+> **Purpose:** Tracks where you are in the BuildFlow workflow.
+> Updated automatically by \`/buildflow-plan\`, \`/buildflow-ship\`, and \`/buildflow-back\`.
+> Also read by \`buildflow status\` in the terminal.
+
+---
+
+## Current State
+
+| Field         | Value                  |
+|---------------|------------------------|
+| **Project**   | ${appName}             |
+| **Type**      | ${projectInfo.projectType} |
+| **Framework** | ${projectInfo.framework} |
+| **Phase**     | 0                      |
+| **Status**    | Initialized            |
+| **BuildFlow** | 3.0                    |
+| **Updated**   | ${today}               |
 
+---
+
+## Phase History
+
+| Phase | Description | Status     | Date |
+|-------|-------------|------------|------|
+| 0     | Setup       | ✅ Complete | ${today} |
+
+---
+
+## Status Reference
+
+| Status        | Meaning                                      |
+|---------------|----------------------------------------------|
+| Initialized   | BuildFlow set up, ready to start             |
+| In Progress   | Actively building a phase                    |
+| Shipped       | Phase complete and committed to git          |
+| Blocked       | Waiting on a decision or external dependency |
+`)
+
+  // ── you/preferences.md ──────────────────────────────────────────────────────
   writeFileSync(join(base, 'you', 'preferences.md'),
-    `# Preferences\n\nexperience: junior\nproject_type: ${projectInfo.projectType}\nframework: ${projectInfo.framework}\n\nlearning:\n  show_explanations: true\n  confidence_calibration: true\n  source_citations: true\n\nsafety:\n  enable_undo: true\n  restore_points: true\n\nmemory:\n  type: light\n  retention_days: 30\n\nparallel:\n  enabled: true\n  max_researchers: 3\n\nsecurity:\n  pre_ship_gate: true\n  auto_suggest_on_sensitive: true\n`
-  )
+    `# Your Preferences
+
+> **Purpose:** BuildFlow reads this at session start to adapt its behavior to you.
+> Edit any value — changes take effect in the next AI session.
+
+---
+
+## Experience Level
+
+\`\`\`yaml
+experience: junior   # junior | mid | senior
+\`\`\`
+
+| Value    | What it changes                                                  |
+|----------|------------------------------------------------------------------|
+| \`junior\` | More explanations, analogies, LEARN: comments in generated code  |
+| \`mid\`    | Balanced — assumes framework knowledge, skips basics             |
+| \`senior\` | Concise — assumes full-stack knowledge, no hand-holding          |
+
+---
+
+## Project Context
+
+\`\`\`yaml
+project_type: ${projectInfo.projectType}   # greenfield | existing
+framework:    ${projectInfo.framework}
+\`\`\`
+
+---
 
+## Learning Aids
+
+\`\`\`yaml
+learning:
+  show_explanations:      true   # Explain WHY, not just WHAT
+  confidence_calibration: true   # Ask confidence (1-5) before big decisions
+  source_citations:       true   # Cite research sources with trust scores (1-5)
+\`\`\`
+
+---
+
+## Safety
+
+\`\`\`yaml
+safety:
+  enable_undo:     true   # /buildflow-back restores to git checkpoints
+  restore_points:  true   # Auto-commit before destructive operations
+\`\`\`
+
+---
+
+## Memory
+
+\`\`\`yaml
+memory:
+  type:            light   # light (≤5K tokens) | full (more context, more cost)
+  retention_days:  30      # Discard session data older than this
+\`\`\`
+
+---
+
+## Parallelization
+
+\`\`\`yaml
+parallel:
+  enabled:         true   # Run multiple agents simultaneously
+  max_researchers: 3      # Max parallel Researcher agents in /buildflow-think
+\`\`\`
+
+---
+
+## Security
+
+\`\`\`yaml
+security:
+  pre_ship_gate:           true   # Run security audit before every /buildflow-ship
+  auto_suggest_on_sensitive: true # Flag sensitive files (auth, payments) automatically
+\`\`\`
+`)
+
+  // ── memory/light.md ─────────────────────────────────────────────────────────
   writeFileSync(join(base, 'memory', 'light.md'),
-    `# Light Memory\n\napp: ${appName}\ntype: ${projectInfo.projectType}\nframework: ${projectInfo.framework}\nphase: 0\nlast_session: ${today}\nbuildflow: 3.0\nonboarded: ${projectInfo.projectType === 'greenfield' ? 'n/a' : 'false'}\n\n## Style Fingerprint\n[Auto-populated after first build]\n\n## Recent Decisions\n[Auto-populated]\n`
-  )
+    `# Light Memory
+
+> **Purpose:** Persists essential project context across AI sessions.
+> Loaded at the start of every BuildFlow session to avoid re-detecting things.
+> **Keep this file under 5,000 tokens.** Distill insights — don't log events.
+> The AI updates this automatically. You can edit it too.
+
+---
 
+## Session Data
+
+\`\`\`yaml
+app:          ${appName}
+type:         ${projectInfo.projectType}
+framework:    ${projectInfo.framework}
+phase:        0
+last_session: ${today}
+buildflow:    3.0
+onboarded:    ${projectInfo.projectType === 'greenfield' ? 'n/a  # greenfield project — no onboarding needed' : 'false  # run /buildflow-onboard to analyze your codebase'}
+\`\`\`
+
+---
+
+## Style Fingerprint
+
+> Auto-populated by \`/buildflow-build\` after the first coding session.
+> Captures naming conventions, import style, error handling patterns.
+
+*(not yet populated)*
+
+---
+
+## Key Decisions
+
+> Major architectural or technology decisions. Summarized here so agents
+> don't relitigate them. Full details are in \`learnings/decisions.md\`.
+
+*(not yet populated)*
+
+---
+
+## Current Focus
+
+> What you're working on right now. Updated by \`/buildflow-plan\` and \`/buildflow-ship\`.
+
+Phase 0 — Initial setup complete. Run \`/buildflow-start\` to begin.
+`)
+
+  // ── learnings/glossary.md ───────────────────────────────────────────────────
   writeFileSync(join(base, 'learnings', 'glossary.md'),
-    `# Glossary\n\n## context-rot\nAI quality degrades as conversation grows. Avoided by fresh agents.\n\n## confidence-calibration\nAsking 1-5 before locking decisions. Triggers explanations when low.\n\n## cartographer\nAgent that maps existing codebases for other agents to use.\n\n## surgeon\nAgent that makes precise modifications to existing code.\n\n## security-auditor\nAgent that runs OWASP Top 10 checks before shipping.\n`
-  )
+    `# Glossary
+
+> **Purpose:** Defines terms used across BuildFlow sessions.
+> Agents reference this to stay consistent with terminology.
+> Grows automatically when you use \`/buildflow-explain\`.
+> Add your own project-specific terms below the BuildFlow section.
+
+---
 
+## BuildFlow Terms
+
+| Term | Definition |
+|------|------------|
+| **context-rot** | AI quality degrades as conversation grows long. BuildFlow avoids this by using fresh agent sessions per task. |
+| **confidence-calibration** | Asking for a 1–5 confidence score before locking major decisions. Score below 3 triggers alternatives or research. |
+| **light memory** | The \`memory/light.md\` file — essential project context kept under 5K tokens, loaded at every session start. |
+| **wave** | A group of tasks that can run in parallel because they have no dependencies on each other. |
+| **restore point** | A git commit created before a destructive operation so \`/buildflow-back\` can undo it. |
+| **blast radius** | The set of files affected by a code change — mapped before modifying anything in Surgeon mode. |
+
+---
+
+## Agent Roles
+
+| Agent | Role |
+|-------|------|
+| **Strategist** | Vision, decisions, project orientation |
+| **Researcher** | Web research with source trust scores (1–5) |
+| **Synthesizer** | Combines parallel research into a recommendation |
+| **Architect** | Maps task dependencies, creates wave-based plans |
+| **Builder** | Writes code matched to your existing style |
+| **Reviewer** | Quality, correctness, and security checks |
+| **Cartographer** | One-time existing codebase analysis |
+| **Surgeon** | Precise, minimal-footprint code modifications |
+| **Security Auditor** | OWASP Top 10 scanning, pre-ship gate |
+
+---
+
+## Project Terms
+
+> Add your project-specific jargon here so all agents use consistent language.
+
+*(add terms as your project evolves)*
+`)
+
+  // ── learnings/decisions.md ──────────────────────────────────────────────────
   writeFileSync(join(base, 'learnings', 'decisions.md'),
-    `# Decision Log\n\n## ${today} — Initial Setup\nDecision: Use BuildFlow v3.0\nType: ${projectInfo.projectType} (${projectInfo.framework})\nConfidence: 5/5\n`
-  )
+    `# Decision Log
+
+> **Purpose:** Records major architectural and technology decisions.
+> Prevents relitigating the same choices in future sessions.
+> Each decision includes what was decided, why, and how confident you were.
+> Updated by agents during \`/buildflow-think\` and \`/buildflow-plan\`.
+
+---
+
+## How to Read This Log
+
+| Field | Meaning |
+|-------|---------|
+| **Decision** | What was chosen |
+| **Alternatives** | What else was considered |
+| **Rationale** | Why this option won |
+| **Confidence** | 1–5 at time of decision (5 = very sure) |
+| **Revisit if** | Conditions that would make this worth reconsidering |
+
+---
+
+## Log
+
+### ${today} — Initial Setup
 
+| Field | Value |
+|-------|-------|
+| **Decision** | Use BuildFlow v3.0 for development orchestration |
+| **Type** | ${projectInfo.projectType} · ${projectInfo.framework} |
+| **Confidence** | 5/5 |
+| **Revisit if** | — |
+
+---
+
+*New decisions are appended below by \`/buildflow-think\` and \`/buildflow-plan\`.*
+`)
+
+  // ── security/DEBT.md ────────────────────────────────────────────────────────
   writeFileSync(join(base, 'security', 'DEBT.md'),
-    `# Security Debt\n\nTrack deferred security issues.\n\n## Active\n[None]\n`
-  )
+    `# Security Debt
+
+> **Purpose:** Tracks security issues that were found but not immediately fixed.
+> Populated by \`buildflow fix\` (log to debt option) and \`/buildflow-ship\`
+> when high-severity issues are found but you choose to ship anyway.
+> Review this before every major release.
+
+---
+
+## Severity Reference
+
+| Level | Icon | Action Required |
+|-------|------|-----------------|
+| Critical | 🔴 | Fix before next commit. Blocks \`/buildflow-ship\`. |
+| High | 🟡 | Fix this sprint. Logged here when shipping despite warning. |
+| Medium | 🟠 | Fix when in the area. Won't block shipping. |
+| Low | 🔵 | Fix opportunistically. |
+
+---
+
+## Active Issues
+
+> Issues that need to be addressed.
+
+*None — clean slate.*
+
+---
+
+## Resolved Issues
+
+> Move items here (with resolution date and fix description) when addressed.
+
+*None yet.*
+`)
 
   return base
 }