Organizations can define base templates in .jumpstart/base/ that are merged with project-level templates. Project-level content wins on conflict. Enable via config:

`yaml
template_inheritance:
enabled: true
base_path: .jumpstart/base
merge_strategy: project-wins
`

---

Project Structure

After installation, your repository will look like this:

`
your-project/
│
├── .jumpstart/ # Framework core (do not rename)
│ ├── config.yaml # Project and agent settings
│ ├── roadmap.md # Non-negotiable principles (8 articles)
│ ├── glossary.md # Canonical term definitions
│ ├── invariants.md # Environment invariants
│ ├── correction-log.md # Self-correction log
│ ├── domain-complexity.csv # Domain-adaptive planning data
│ ├── usage-log.json # Token usage and cost tracking
│ ├── manifest.json # Artifact manifest
│ ├── spec-graph.json # Spec dependency graph
│ │
│ ├── agents/ # Agent persona definitions (22 agents)
│ │ ├── scout.md # Pre-Phase: Codebase Reconnaissance
│ │ ├── 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
│ │ └── (16 advisory agents) # Security, DevOps, QA, UX, etc.
│ │
│ ├── templates/ # 70+ artifact templates
│ ├── schemas/ # JSON Schema validation (6 schemas)
│ ├── commands/ # Slash command definitions (35 commands)
│ ├── handoffs/ # Phase-to-phase contract schemas
│ ├── skills/ # Skill-based knowledge injection
│ ├── modules/ # Pluggable add-on modules
│ ├── base/ # Organization-wide base templates
│ ├── compat/ # Cross-assistant portability mapping
│ ├── state/ # Workflow state persistence
│ └── archive/ # Timestamped artifact archives
│
├── .github/ # GitHub Copilot integration
│ ├── copilot-instructions.md # Always-on repo instructions
│ ├── agents/ # Custom agents (Copilot dropdown)
│ ├── prompts/ # Utility prompts (status, review)
│ └── instructions/ # File-specific instructions
│
├── AGENTS.md # Tool-agnostic agent instructions
├── CLAUDE.md # Claude Code integration
├── .cursorrules # Cursor IDE integration
│
├── specs/ # Generated artifacts (source of truth)
│ ├── challenger-brief.md # Phase 0 output
│ ├── product-brief.md # Phase 1 output
│ ├── prd.md # Phase 2 output
│ ├── architecture.md # Phase 3 output
│ ├── implementation-plan.md # Phase 3/4 working document
│ ├── codebase-context.md # Scout output (brownfield only)
│ ├── qa-log.md # Q&A decision audit trail
│ ├── decisions/ # Architecture Decision Records
│ ├── insights/ # Living insights (reasoning traces)
│ └── research/ # Optional research artifacts
│
├── bin/ # CLI and tooling (40 lib modules)
├── src/ # Application code (Phase 4 output)
├── tests/ # Test code (104 tests, 4 suites)
└── README.md
`

---

Living Insights

Living Insights capture the reasoning process of agents as they work through each phase. Unlike formal artifacts (like PRDs or Architecture Documents), insights are conversational, exploratory, and designed to preserve the why behind decisions.

$3

Insights are Markdown files that record:
- Questions agents considered during their analysis
- Trade-offs evaluated and why certain paths were chosen
- Hypotheses explored and rejected
- Uncertainties flagged for human review
- Connections between requirements and architectural decisions

They are living because they grow incrementally as agents work through their protocols—not just written at the end of a phase. They are optimized for agent thinking patterns and serve as a shared memory across phases.

$3

Traceability: Understand how a technical decision in Phase 3 connects back to a user need discovered in Phase 1.

Onboarding: New team members (human or AI) can review insights to understand not just what was built, but why it was built that way.

Debugging Specs: When a requirement seems unclear or contradictory, insights reveal the original context and assumptions.

Continuity: If you pause work and return weeks later, insights help you pick up where you left off without losing context.

$3

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 prioritization
├── architecture-insights.md # Phase 3: Technical choices and design trade-offs
└── implementation-plan-insights.md # Phase 4: Implementation learnings and gotchas
`

Each insights file:
- Uses a conversational, stream-of-consciousness format
- Includes timestamps for entries
- Cross-references both primary artifacts and other insights files
- Grows incrementally as the agent works through its protocol

$3

Insights are not a replacement for Architecture Decision Records (ADRs):

| Aspect | Insights | ADRs |
|--------|----------|------|
| Audience | Agents and developers seeking context | Stakeholders and future maintainers |
| Format | Conversational, exploratory | Formal, structured |
| Timing | Written during work | Written after decision is made |
| Scope | Broad (covers all reasoning) | Narrow (one decision per ADR) |
| Status | Always evolving | Immutable once approved |

Insights provide the thinking trail. ADRs provide the decision record.

$3

Here's what a typical insight entry looks like:

`markdown


2026-01-15 14:23 -- Evaluating Authentication Approaches

The PRD specifies "secure user authentication" but doesn't mandate a specific approach.
Exploring three options:

1. Sessions + cookies: Traditional, well-understood, but complicates horizontal scaling.
2. JWT tokens: Stateless, scales easily, but token revocation is tricky.
3. OAuth delegation: Offloads auth to third party (GitHub, Google), simplifies our code
but introduces external dependencies.

Checking non-functional requirements in prd.md...
- NFR-003 specifies 99.9% uptime. External OAuth adds a failure mode.
- NFR-007 requires GDPR compliance. Storing passwords increases our compliance burden.

Leaning toward JWTs with short expiration (15 min) and refresh tokens in httpOnly cookies.
This balances statelessness with acceptable revocation latency.

Cross-refs:
- prd.md § Epic 1: User Management
- architecture.md § 3.2: Authentication Service
- decisions/002-jwt-authentication.md

Open question: Do we need multi-device session management? Not in MVP scope,
but if we add it in v2, JWTs make this easier.
`

$3

To access insights while working:

In GitHub Copilot:
`
#file:specs/insights/architecture-insights.md Why did we choose PostgreSQL over MongoDB?
`

In Claude Code:
`
/jumpstart.insights architecture
`

Manual:
Open specs/insights/-insights.md directly in your editor.

$3

Insights files link to primary artifacts, and primary artifacts link back to insights:

In a PRD:
`markdown


$3

In an insights file:
`markdown


Exploring Notification Delivery

The .jumpstart/config.yaml file controls framework behavior across 28 configuration sections. Key areas:

| Section | What It Controls |
|---------|----------------|
| project | Name, type (greenfield/brownfield), domain |
| roadmap | Non-negotiable engineering principles toggle |
| workflow | Gate approval, phase skipping, Q&A logging |
| agents | Per-agent settings (elicitation depth, story format, diagram format, etc.) |
| testing | 5-layer quality gate thresholds |
| integrations | AI assistant selection (copilot, claude-code, cursor, windsurf) |
| modules | Pluggable module system |
| skills | Skill-based knowledge injection |
| template_inheritance | Organization-wide base template merging |
| design_system | Enterprise design system reference |
| self_evolve | Framework self-improvement proposals |
| hooks | Post-phase triggers (Slack, GitHub Issues, etc.) |
| state | Workflow state persistence |
| locks | Concurrent editing protection |
| adaptive_planning | Domain-complexity-driven planning rigor |
| vscode_tools | VS Code Chat tool preferences |

The file is self-documenting with inline comments. See .jumpstart/config.yaml for full documentation.

---

Greenfield vs. Brownfield

Jump Start adapts its workflow based on whether you're starting from scratch or working with an existing codebase.

$3

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.

$3

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.

$3

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 four AI assistants. The installer creates all of them automatically. See .jumpstart/compat/assistant-mapping.md for the complete portability mapping.

$3

Jump Start uses four of Copilot's customization layers:

Custom Agents (.github/agents/*.agent.md): Six agents appear in the Copilot Chat dropdown, one per phase. Select an agent to activate that phase. Agents support handoffs, so after completing Phase 0 you can hand off directly to Phase 1.

Always-on Instructions (.github/copilot-instructions.md): Applied to every chat request in the workspace. Gives Copilot awareness of the framework's rules, directory structure, and sequential workflow.

Prompt Files (.github/prompts/*.prompt.md): Utility prompts for checking status and reviewing artifacts. Access them with #prompt:jumpstart-status or #prompt:jumpstart-review in chat.

File-specific Instructions (.github/instructions/*.instructions.md): Applied automatically when Copilot is working on files matching a glob pattern. The specs.instructions.md file applies whenever editing spec artifacts.

$3

Uses CLAUDE.md at the project root for slash command routing. Commands like /jumpstart.challenge, /jumpstart.analyze, etc., are mapped to the corresponding agent files.

$3

Uses .cursorrules at the project root, which maps the same slash commands to the agent files. Individual agent rules can also be placed in .cursor/rules/ as .mdc files.

$3

Uses .windsurfrules at the project root. Similar to Claude Code's CLAUDE.md but single-file format.

$3

Any AI coding assistant that can read files will work. Point it at the relevant agent file in .jumpstart/agents/ and it has everything it needs. AGENTS.md at the project root provides a tool-agnostic entry point.

---

VS Code Chat Features

When using GitHub Copilot in VS Code, Jump Start agents can leverage two powerful native tools that enhance the interactive experience. These features are optional—the framework works perfectly in other AI assistants without them.

$3

The ask_questions tool displays interactive UI elements where you can:
- Select from multiple-choice options (single or multi-select)
- See recommended options highlighted when agents guide decisions
- Provide free-text input when choices aren't enough
- Make selections quickly rather than typing responses

Example scenarios:
- Challenger (Phase 0): Categorizing assumptions as Validated/Believed/Untested
- Analyst (Phase 1): Approving personas or flagging ones that need revision
- PM (Phase 2): Validating epic boundaries before story decomposition
- Architect (Phase 3): Choosing between PostgreSQL and MySQL when both fit requirements
- Developer (Phase 4): Selecting how to handle an unanticipated edge case

What it looks like:
`
┌─ Question ────────────────────────────────────────┐
│ Which problem reframe best captures the issue? │
├───────────────────────────────────────────────────┤
│ ○ Sales managers lack real-time pipeline │
│ visibility... │
│ ○ Marketing teams can't measure campaign ROI... │
│ ● Regional managers need consolidated │
│ reporting... [Recommended] │
│ ○ Let me write my own reframe │
└───────────────────────────────────────────────────┘
`

The selected option feeds directly into the conversation, making the workflow more efficient.

$3

The manage_todo_list tool creates visual todo lists that track progress through each phase's protocol:

Example for Phase 0 (Challenger):
`
Jump Start: Phase 0 -- Problem Discovery
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Step 1: Capture the Raw Statement
✓ Step 2: Surface Assumptions
✓ Step 3: Root Cause Analysis (Five Whys)
✓ Step 4: Stakeholder Mapping
◯ Step 5: Problem Reframing
◯ Step 6: Validation Criteria
◯ Step 7: Constraints and Boundaries
◯ Step 8: Compile and Present the Brief

Current: Step 5 -- Exploring alternative problem frames...
`

Example for Phase 4 (Developer):
`
Implementation Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Milestone 1: Project Scaffolding (5/5 tasks)
✓ Milestone 2: Database Models (8/8 tasks)
● Milestone 3: Core API Endpoints (6/12 tasks)
✓ M3-T01: POST /users endpoint
✓ M3-T02: GET /users/:id endpoint
● M3-T03: GET /users/:id/projects endpoint [IN PROGRESS]
◯ M3-T04: PUT /users/:id endpoint
...
◯ Milestone 4: Authentication (0/6 tasks)
◯ Milestone 5: Frontend (0/15 tasks)

Tests: 47 passing, 0 failing
`

Benefits:
- See exactly where you are in a multi-step workflow
- Resume work after interruptions without losing context
- Understand progress at a glance (especially valuable in Phase 4)
- Track completion percentage during long-running phases

$3

These tools are automatically available when using Jump Start custom agents in VS Code Chat. Agents will use them at appropriate moments in their protocols. You don't need to configure anything—they just work.

If you prefer a more conversational workflow without structured prompts, you can disable these features in .jumpstart/config.yaml:

`yaml
vscode_tools:
use_ask_questions: false
use_todo_lists: false
`

Note: These features are VS Code Chat specific. When using Jump Start with Claude Code, Cursor, or other AI assistants, agents will use conversational workflows instead. The framework's core functionality is identical across all platforms.

---

Extending the Framework

$3

Use the agent template at .jumpstart/templates/agent-template.md to scaffold new agents with the required sections (Identity, Mandate, Activation, Protocol, Phase Gate). Validate with npx jumpstart-mode validate to check structure compliance.

$3

Use the built-in skill-creator (.jumpstart/skills/skill-creator/SKILL.md) for guided skill creation. Skills follow the skill-name/SKILL.md directory pattern with optional scripts/, references/, and assets/ subdirectories.

$3

Create a directory in .jumpstart/modules/ with a module.json manifest. Modules can bundle agents, templates, commands, checks, and skills. Validate for marketplace publishing:

`bash
npx jumpstart-mode validate-module .jumpstart/modules/my-module
`

$3

Define organization-wide defaults in .jumpstart/base/ and enable template inheritance in config. Project-level templates override base templates at the section level.

$3

All 70+ templates in .jumpstart/templates/ are editable Markdown. Add fields, remove sections, or restructure to match your team's standards.

$3

Configure post-phase hooks in config.yaml to trigger external actions (Slack notifications, GitHub issues, linter runs, etc.).

$3

Jump Start works across GitHub Copilot, Cursor, Claude Code, and Windsurf. See .jumpstart/compat/assistant-mapping.md for tool-specific configuration mapping.

$3

Enable the self-evolve engine to analyze project usage patterns and generate config improvement proposals:

`bash
npx jumpstart-mode self-evolve
npx jumpstart-mode self-evolve --artifact # Generate a proposal document
`

All proposals require explicit human approval before applying.

---

Philosophy

Problem before solution. Phase 0 exists because the most expensive software failures are bugs in thinking, not bugs in code.

Spec as source of truth. The specification documents are the canonical description of what the system should do and why. Code is a derivative artifact. If there is a mismatch, update the spec first.

Everything in the repo. All artifacts are Markdown files that live alongside your code. They are diffable, reviewable in pull requests, and natively consumable by any LLM.

Sequential with gates. Each phase must be completed and approved before the next begins. This prevents the "telephone game" effect where intent degrades as it passes through layers of abstraction.

Context preservation. Each agent receives the full output of all preceding phases. No decision made upstream is lost or misinterpreted downstream.

Never guess. When any requirement or context is ambiguous, agents tag it with [NEEDS CLARIFICATION] and ask the human rather than making assumptions.

Governed by Roadmap. The .jumpstart/roadmap.md` file defines non-negotiable engineering principles (Library-First, Test-First TDD, Upstream Traceability, Simplicity, Anti-Abstraction, and more). These supersede agent-specific instructions and cannot be modified by agents — only by humans.

---

License

MIT License - see LICENSE file for details.