jumpstart-mode 1.0.6 → 1.0.8

package/README.md

@@ -28,23 +28,30 @@ Every artifact lives in your repository, version-controlled, diffable, and trans
 
 Jump Start runs five phases in a strict sequence. Each phase is owned by a specialized AI agent and produces Markdown artifacts that serve as the input for the next phase. A human gate sits between every transition to ensure quality.
 
+For **brownfield** projects (existing codebases), an optional pre-phase Scout agent analyzes the codebase first. For **greenfield** projects (new codebases), the Architect and Developer agents create per-directory `AGENTS.md` files to document the emerging codebase.
+
 ```mermaid
 flowchart TB
+    S[Pre-Phase: Scout] -.->|brownfield only| P0
     P0[Phase 0: Challenge] -->|Brief| P1[Phase 1: Analyze]
     P1 -->|Product Brief| P2[Phase 2: Plan]
     P2 -->|PRD| P3[Phase 3: Architect]
     P3 -->|Specs| P4[Phase 4: Build]
     
+    SC(Scout) -.-> S
     C(Challenger) -.-> P0
     A(Analyst) -.-> P1
     PM(Product Manager) -.-> P2
     Arch(Architect) -.-> P3
     Dev(Developer) -.-> P4
 
+    style S fill:#ff9800,stroke:#333,stroke-width:2px,color:#fff
     style P0 fill:#1976d2,stroke:#333,stroke-width:2px,color:#fff
     style P4 fill:#43a047,stroke:#333,stroke-width:2px,color:#fff
 ```
 
+**Pre-Phase -- Codebase Reconnaissance (Brownfield Only).** The Scout agent scans the existing codebase, maps the technology stack, generates C4 architecture diagrams, identifies code patterns and technical debt, and produces a codebase context document that informs all subsequent phases.
+
 **Phase 0 -- Problem Discovery.** The Challenger agent interrogates your idea, surfaces hidden assumptions, drills to root causes, and produces a validated problem statement.
 
 **Phase 1 -- Analysis.** The Analyst agent creates user personas, maps current and future-state journeys, and recommends an MVP scope.
@@ -70,6 +77,7 @@ npx jumpstart-mode
 Follow the prompts to set up the framework. You'll be asked for:
 - Target directory (default: current directory)
 - Project name (optional)
+- Project type (greenfield or brownfield — auto-detected based on existing files)
 - Whether to include GitHub Copilot integration
 
 **Command-line Mode:**
@@ -84,6 +92,9 @@ npx jumpstart-mode ./my-project
 # Install with all options
 npx jumpstart-mode ./my-project --name "My Project" --copilot
 
+# Install for an existing codebase (brownfield)
+npx jumpstart-mode ./existing-app --type brownfield --copilot
+
 # Preview what will be installed
 npx jumpstart-mode --dry-run .
 
@@ -102,6 +113,7 @@ jumpstart-mode ./my-project --name "My Project"
 
 - `<directory>` — Target directory (default: current)
 - `--name <name>` — Set project name in config
+- `--type <type>` — Set project type: `greenfield` or `brownfield` (auto-detected if omitted)
 - `--copilot` — Include GitHub Copilot integration files
 - `--force` — Overwrite existing files without prompting
 - `--dry-run` — Show what would be installed without copying
@@ -119,7 +131,7 @@ This creates the full directory structure, all agent definitions, templates, and
 
 ### 2. Configure
 
-Edit `.jumpstart/config.yaml` to customise agent behaviour, story format, prioritisation method, and other settings. The file is self-documenting with inline comments.
+Edit `.jumpstart/config.yaml` to customise agent behavior, story format, prioritization method, and other settings. The file is self-documenting with inline comments.
 
 ### 3. Run
 
@@ -127,13 +139,18 @@ Edit `.jumpstart/config.yaml` to customise agent behaviour, story format, priori
 
 1. Open the project in VS Code
 2. Open Copilot Chat
-3. Click the agent dropdown and select **"Jump Start: Challenger"**
-4. Describe your idea or problem when prompted
-5. After Phase 0 is approved, select **"Jump Start: Analyst"** and continue through each phase
+3. **Brownfield projects:** Select **"Jump Start: Scout"** agent first to analyze the existing codebase. After approval, proceed to Phase 0.
+4. **All projects:** Click the agent dropdown and select **"Jump Start: Challenger"**
+5. Describe your idea or problem when prompted
+6. After Phase 0 is approved, select **"Jump Start: Analyst"** and continue through each phase
 
 **With Claude Code:**
 
 ```
+# Brownfield projects: run Scout first
+/jumpstart.scout
+
+# Then start Phase 0
 /jumpstart.challenge I want to build a tool that helps remote teams track meeting action items
 ```
 
@@ -147,6 +164,7 @@ Then continue with `/jumpstart.analyze`, `/jumpstart.plan`, `/jumpstart.architec
 
 | Command | Phase | What It Does |
 |---------|-------|-------------|
+| `/jumpstart.scout` | Pre-0 | Analyze existing codebase (brownfield only) |
 | `/jumpstart.challenge` | 0 | Begin problem discovery |
 | `/jumpstart.analyze` | 1 | Generate Product Brief |
 | `/jumpstart.plan` | 2 | Generate PRD |
@@ -168,12 +186,15 @@ your-project/
 |-- .jumpstart/                      # Framework core (do not rename)
 |   |-- config.yaml                  # Project and agent settings
 |   |-- agents/                      # Detailed agent persona definitions
+|   |   |-- scout.md                 #   Pre-Phase: Codebase Reconnaissance (brownfield)
 |   |   |-- challenger.md            #   Phase 0: Problem Discovery
 |   |   |-- analyst.md               #   Phase 1: Analysis
 |   |   |-- pm.md                    #   Phase 2: Planning
 |   |   |-- architect.md             #   Phase 3: Solutioning
 |   |   |-- developer.md             #   Phase 4: Implementing
 |   |-- templates/                   # Artifact templates
+|   |   |-- codebase-context.md      #   Scout output template (brownfield)
+|   |   |-- agents-md.md             #   Per-directory AGENTS.md template (greenfield)
 |   |   |-- challenger-brief.md
 |   |   |-- product-brief.md
 |   |   |-- prd.md
@@ -186,6 +207,7 @@ your-project/
 |-- .github/                         # GitHub Copilot integration
 |   |-- copilot-instructions.md      # Always-on repo instructions
 |   |-- agents/                      # Custom agents (appear in Copilot dropdown)
+|   |   |-- jumpstart-scout.agent.md #   Pre-Phase: Scout (brownfield)
 |   |   |-- jumpstart-challenger.agent.md
 |   |   |-- jumpstart-analyst.agent.md
 |   |   |-- jumpstart-pm.agent.md
@@ -202,6 +224,7 @@ your-project/
 |-- .cursorrules                     # Cursor IDE integration
 |
 |-- specs/                           # Generated artifacts (version-controlled)
+|   |-- codebase-context.md          # Pre-Phase output (brownfield only)
 |   |-- challenger-brief.md          # Phase 0 output
 |   |-- product-brief.md             # Phase 1 output
 |   |-- prd.md                       # Phase 2 output
@@ -212,6 +235,7 @@ your-project/
 |   |-- research/                    # Optional research artifacts
 |
 |-- src/                             # Application code (Phase 4 output)
+|   |-- AGENTS.md                    # Per-directory AI context (greenfield, Phase 4)
 |-- tests/                           # Test code (Phase 4 output)
 |-- README.md                        # Updated by Developer agent
 ```
@@ -249,9 +273,10 @@ Insights live in `specs/insights/` with a 1:1 relationship to primary artifacts:
 
 ```
 specs/insights/
+├── codebase-context-insights.md      # Pre-Phase: Scout reasoning (brownfield only)
 ├── challenger-brief-insights.md      # Phase 0: Problem discovery reasoning
 ├── product-brief-insights.md         # Phase 1: Analysis explorations and trade-offs
-├── prd-insights-md                  # Phase 2: Planning decisions and story prioritisation
+├── prd-insights.md                  # Phase 2: Planning decisions and story prioritization
 ├── architecture-insights.md          # Phase 3: Technical choices and design trade-offs
 └── implementation-plan-insights.md   # Phase 4: Implementation learnings and gotchas
 ```
@@ -346,14 +371,14 @@ This creates a **two-way knowledge graph** between formal specs and informal rea
 
 ## Configuration
 
-The `.jumpstart/config.yaml` file controls framework behaviour. Key settings:
+The `.jumpstart/config.yaml` file controls framework behavior. Key settings:
 
 **Workflow:**
 - `require_gate_approval`: Enforce human approval between phases (default: true)
 - `allow_phase_skip`: Allow jumping to later phases (default: false)
 
 **Agents:**
-- Each agent has configurable settings (elicitation depth, story format, prioritisation method, diagram format, test framework, etc.)
+- Each agent has configurable settings (elicitation depth, story format, prioritization method, diagram format, test framework, etc.)
 
 **Integrations:**
 - `ai_assistant`: Which AI tool you're using (copilot, claude-code, cursor, gemini, windsurf)
@@ -362,6 +387,40 @@ See the config file itself for full documentation of all options.
 
 ---
 
+## Greenfield vs. Brownfield
+
+Jump Start adapts its workflow based on whether you're starting from scratch or working with an existing codebase.
+
+### Brownfield Projects (Existing Codebase)
+
+When `project.type` is `brownfield`, the framework activates a **Scout** agent that runs before Phase 0. The Scout:
+
+1. **Scans the repository** — maps directory structure, identifies languages, and catalogs key files
+2. **Analyzes dependencies** — reads package manifests, lock files, and import graphs
+3. **Extracts architecture** — identifies patterns, layers, and component boundaries
+4. **Generates C4 diagrams** — System Context, Container, Component, and (optionally) Code-level diagrams in Mermaid
+5. **Assesses technical debt** — flags deprecated dependencies, code smells, and missing test coverage
+6. **Produces `specs/codebase-context.md`** — a comprehensive reference document that all downstream agents read
+
+This ensures that the Challenger, Analyst, PM, Architect, and Developer agents all understand the existing system before proposing changes. The Architect uses brownfield-specific task types (`[R]` for refactoring, `[M]` for migration) in the implementation plan.
+
+### Greenfield Projects (New Codebase)
+
+When `project.type` is `greenfield`, the framework adds **per-directory AGENTS.md files** to document the emerging codebase as it's built:
+
+1. The **Architect** plans which directories should receive `AGENTS.md` files in the architecture document
+2. The **Developer** creates these files during scaffolding and updates them as code evolves
+3. Files follow the template in `.jumpstart/templates/agents-md.md`
+4. Depth is configurable via `agents.developer.agents_md_depth` in config: `top-level`, `module`, or `deep`
+
+These files provide AI-friendly context for each module, making the codebase easier for both humans and AI agents to navigate.
+
+### Detection
+
+The CLI auto-detects project type during installation by checking for existing source files, package manifests, `.git` history, and other signals. You can override this with `--type greenfield` or `--type brownfield`. The Challenger agent also confirms the project type at the start of Phase 0.
+
+---
+
 ## Using with AI Assistants
 
 Jump Start provides first-class integration files for three AI assistants. The installer creates all of them automatically.
@@ -492,7 +551,7 @@ vscode_tools:
 ### Adding Custom Agents
 
 Create a new agent file in `.jumpstart/agents/` following the pattern of the existing agents:
-- Define the agent's identity, mandate, and behavioural guidelines
+- Define the agent's identity, mandate, and behavioral guidelines
 - Specify its input context (which artifacts it reads)
 - Define its protocol (step-by-step instructions)
 - Specify its output (which artifacts it produces)

package/bin/cli.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const prompts = require('prompts');
+const { setupContext7 } = require('./context7-setup');
 
 // Get the package root directory (where .jumpstart/ lives)
 const PACKAGE_ROOT = path.join(__dirname, '..');
@@ -25,7 +26,8 @@ function parseArgs() {
     force: false,
     dryRun: false,
     help: false,
-    interactive: true
+    interactive: true,
+    projectType: null  // greenfield | brownfield | null (auto-detect)
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -46,6 +48,15 @@ function parseArgs() {
     } else if (arg === '--dry-run') {
       config.dryRun = true;
       config.interactive = false;
+    } else if (arg === '--type') {
+      const typeVal = args[++i];
+      if (typeVal === 'greenfield' || typeVal === 'brownfield') {
+        config.projectType = typeVal;
+      } else {
+        console.error(chalk.red(`Invalid --type value: ${typeVal}. Must be 'greenfield' or 'brownfield'.`));
+        process.exit(1);
+      }
+      config.interactive = false;
     } else if (!arg.startsWith('--') && !config.targetDir) {
       config.targetDir = arg;
     }
@@ -67,6 +78,7 @@ function showHelp() {
   console.log(chalk.bold('OPTIONS:'));
   console.log('  <directory>        Target directory (default: current directory)');
   console.log('  --name <name>      Set project name in config');
+  console.log('  --type <type>      Set project type: greenfield | brownfield');
   console.log('  --copilot          Include GitHub Copilot integration');
   console.log('  --force            Overwrite existing files without prompting');
   console.log('  --dry-run          Show what would be installed without copying');
@@ -75,9 +87,67 @@ function showHelp() {
   console.log('  npx jumpstart-mode');
   console.log('  npx jumpstart-mode ./my-project');
   console.log('  npx jumpstart-mode . --name "My Project" --copilot');
+  console.log('  npx jumpstart-mode ./existing-app --type brownfield --copilot');
   console.log('  npx jumpstart-mode --dry-run .\n');
 }
 
+// Detect whether a target directory is a greenfield or brownfield project
+function detectProjectType(targetDir) {
+  const absDir = path.resolve(targetDir);
+
+  // Indicators of an existing project (brownfield)
+  const brownfieldIndicators = [
+    'package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+    'requirements.txt', 'Pipfile', 'pyproject.toml', 'setup.py',
+    'Gemfile', 'go.mod', 'Cargo.toml', 'pom.xml', 'build.gradle',
+    'Makefile', 'CMakeLists.txt', 'composer.json',
+    '.gitignore', 'tsconfig.json', 'webpack.config.js', 'vite.config.ts',
+    'Dockerfile', 'docker-compose.yml'
+  ];
+
+  const brownfieldDirs = ['src', 'lib', 'app', 'components', 'pages', 'api', 'server', 'client'];
+
+  let score = 0;
+  const signals = [];
+
+  // Check for .git directory (strong signal)
+  if (fs.existsSync(path.join(absDir, '.git'))) {
+    const gitLog = path.join(absDir, '.git', 'refs', 'heads');
+    if (fs.existsSync(gitLog)) {
+      score += 2;
+      signals.push('.git history');
+    }
+  }
+
+  // Check for config/manifest files
+  for (const file of brownfieldIndicators) {
+    if (fs.existsSync(path.join(absDir, file))) {
+      score += 1;
+      signals.push(file);
+      if (signals.length >= 5) break; // Enough evidence
+    }
+  }
+
+  // Check for source directories with actual files
+  for (const dir of brownfieldDirs) {
+    const dirPath = path.join(absDir, dir);
+    if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
+      const entries = fs.readdirSync(dirPath);
+      if (entries.some(e => !e.startsWith('.') && e !== '.gitkeep')) {
+        score += 1;
+        signals.push(`${dir}/`);
+        if (signals.length >= 5) break;
+      }
+    }
+  }
+
+  if (score >= 2) {
+    return { type: 'brownfield', confidence: Math.min(score / 5, 1), signals };
+  }
+
+  return { type: 'greenfield', confidence: 1 - (score / 5), signals };
+}
+
 // Recursively copy directory
 function copyDirectoryRecursive(src, dest, options = {}) {
   const { dryRun = false, force = false, stats = { copied: [], skipped: [] } } = options;
@@ -183,6 +253,25 @@ function replaceProjectName(configPath, projectName, options = {}) {
   fs.writeFileSync(configPath, content, 'utf8');
 }
 
+// Set project type in config.yaml
+function setProjectType(configPath, projectType, options = {}) {
+  const { dryRun = false } = options;
+
+  if (!fs.existsSync(configPath) || !projectType || dryRun) {
+    return;
+  }
+
+  let content = fs.readFileSync(configPath, 'utf8');
+
+  // Replace type: null or type: "" under the project: section
+  content = content.replace(
+    /(project:\s*\n(?:.*\n)*?\s*)type:\s*(?:null|""|'')?/m,
+    `$1type: "${projectType}"`
+  );
+
+  fs.writeFileSync(configPath, content, 'utf8');
+}
+
 // Detect conflicts
 function detectConflicts(targetDir, config) {
   const conflicts = [];
@@ -245,9 +334,53 @@ async function runInteractive() {
     process.exit(0);
   }
 
+  // Detect and confirm project type
+  const targetPath = path.resolve(answers.targetDir);
+  const detection = detectProjectType(targetPath);
+
+  let projectType = detection.type;
+
+  if (detection.signals.length > 0 && detection.type === 'brownfield') {
+    console.log(chalk.cyan(`\n🔍 Detected existing project signals: ${detection.signals.slice(0, 3).join(', ')}`));
+    const { confirmedType } = await prompts({
+      type: 'select',
+      name: 'confirmedType',
+      message: 'This looks like an existing codebase. Project type:',
+      choices: [
+        { title: 'Brownfield (existing codebase)', value: 'brownfield' },
+        { title: 'Greenfield (new project)', value: 'greenfield' }
+      ],
+      initial: 0
+    });
+
+    if (!confirmedType) {
+      console.log(chalk.yellow('\n❌ Setup cancelled\n'));
+      process.exit(0);
+    }
+    projectType = confirmedType;
+  } else {
+    const { confirmedType } = await prompts({
+      type: 'select',
+      name: 'confirmedType',
+      message: 'Project type:',
+      choices: [
+        { title: 'Greenfield (new project)', value: 'greenfield' },
+        { title: 'Brownfield (existing codebase)', value: 'brownfield' }
+      ],
+      initial: 0
+    });
+
+    if (!confirmedType) {
+      console.log(chalk.yellow('\n❌ Setup cancelled\n'));
+      process.exit(0);
+    }
+    projectType = confirmedType;
+  }
+
   const config = {
     targetDir: answers.targetDir,
     projectName: answers.projectName || null,
+    projectType,
     copilot: answers.copilot,
     force: false,
     dryRun: false,
@@ -255,7 +388,6 @@ async function runInteractive() {
   };
 
   // Check for conflicts
-  const targetPath = path.resolve(config.targetDir);
   const conflicts = detectConflicts(targetPath, config);
 
   if (conflicts.length > 0 && !config.force) {
@@ -289,6 +421,9 @@ async function install(config) {
   if (config.projectName) {
     console.log(chalk.gray(`Project: ${config.projectName}`));
   }
+  if (config.projectType) {
+    console.log(chalk.gray(`Type: ${config.projectType}`));
+  }
   if (config.copilot) {
     console.log(chalk.gray('Including: GitHub Copilot integration'));
   }
@@ -342,6 +477,31 @@ async function install(config) {
     replaceProjectName(configPath, config.projectName, { dryRun: config.dryRun });
   }
 
+  // 6. Set project type in config
+  if (config.projectType) {
+    console.log(chalk.cyan('🏷️  Setting project type...'));
+    const configPath = path.join(targetPath, JUMPSTART_DIR, 'config.yaml');
+    setProjectType(configPath, config.projectType, { dryRun: config.dryRun });
+  }
+
+  // 7. Context7 MCP setup (interactive only)
+  if (config.interactive) {
+    try {
+      const context7Result = await setupContext7({
+        targetDir: targetPath,
+        dryRun: config.dryRun
+      });
+      if (context7Result.installed) {
+        // Record in config.yaml that context7 is enabled
+        const configPath = path.join(targetPath, JUMPSTART_DIR, 'config.yaml');
+        appendContext7Config(configPath, config.dryRun);
+      }
+    } catch (err) {
+      console.log(chalk.yellow('\n⚠️  Context7 MCP setup skipped due to an error.'));
+      console.log(chalk.gray(`   ${err.message}`));
+    }
+  }
+
   // Display summary
   console.log(chalk.bold.green('\n✅ Installation complete!\n'));
   
@@ -364,10 +524,42 @@ async function install(config) {
     console.log(chalk.gray(`   cd ${config.targetDir}`));
   }
   console.log(chalk.gray('   Open your project in VS Code with GitHub Copilot'));
-  console.log(chalk.gray('   Select "Jump Start: Challenger" agent to begin Phase 0'));
+  if (config.projectType === 'brownfield') {
+    console.log(chalk.gray('   Select "Jump Start: Scout" agent to analyze your codebase'));
+    console.log(chalk.gray('   Then proceed to "Jump Start: Challenger" for Phase 0'));
+  } else {
+    console.log(chalk.gray('   Select "Jump Start: Challenger" agent to begin Phase 0'));
+  }
   console.log(chalk.gray('   Or run: @workspace /jumpstart-status\n'));
 }
 
+// Append context7 integration entry to config.yaml
+function appendContext7Config(configPath, dryRun) {
+  if (dryRun || !fs.existsSync(configPath)) return;
+
+  let content = fs.readFileSync(configPath, 'utf8');
+
+  // Only add if not already present
+  if (content.includes('context7:')) return;
+
+  const context7Block = [
+    '',
+    '# ---------------------------------------------------------------------------',
+    '# Context7 MCP (Model Context Protocol)',
+    '# ---------------------------------------------------------------------------',
+    '# Context7 provides up-to-date library documentation to AI coding assistants.',
+    '# Configured during setup. Manage keys at: https://context7.com',
+    'context7:',
+    '  enabled: true',
+    '  # API key is stored in your client config files (e.g. .vscode/mcp.json),',
+    '  # NOT in this file. Keep those files in .gitignore.',
+    ''
+  ].join('\n');
+
+  content += context7Block;
+  fs.writeFileSync(configPath, content, 'utf8');
+}
+
 // Main entry point
 async function main() {
   try {
@@ -381,6 +573,10 @@ async function main() {
     // Run interactive mode if no flags provided
     if (config.interactive) {
       config = await runInteractive();
+    } else if (!config.projectType) {
+      // Auto-detect project type when not specified via --type
+      const detection = detectProjectType(config.targetDir);
+      config.projectType = detection.type;
     }
 
     await install(config);