Simplify DevSpark quickstart bootstrap and reduce hidden setup work

[markhazleton]

Problem Statement

The DevSpark quickstart/bootstrap flow feels much more complex than a quickstart should. During a real repository bootstrap in VS Code/Copilot, the flow required multiple hidden decisions, extra prompts, and several repair passes before it completed cleanly.

What should have been a short, deterministic setup turned into a mini framework-installation pipeline. The user had to answer install-critical questions, then the system had to inspect repository state, infer mode, refresh generated files, validate them, and repair malformed artifacts.

What We Observed

1. The bootstrap flow combines too many responsibilities.

   • It detects repository state.
   • It selects a shell/runtime.
   • It decides whether the repo is fresh, update, or repair.
   • It generates prompts, scripts, and shims.
   • It validates the result.

2. The process is too opaque.

   • The user sees a short quickstart prompt, but the actual behavior depends on version stamps, helper scripts, repo state, and generated artifacts.
   • The agent shims and prompt files hide a large amount of logic behind a small surface area.

3. The generated artifacts are fragile.

   • We encountered malformed YAML frontmatter in generated Copilot agent shims.
   • The setup flow lacked a clean preflight and a clear post-write validation gate.

4. The quickstart asks for more input than necessary.

   • On Windows, PowerShell should be the default without asking.
   • Same-version installs should default to targeted repair, not a broad refresh flow.
   • Many decisions can be inferred instead of prompted.

Root Cause Analysis

The main problem is not one bug. It is the shape of the bootstrap architecture:

• The quickstart prompt is doing both user onboarding and framework maintenance.
• The implementation is spread across a large helper surface (common.ps1, update-agent-context.ps1, check-prerequisites.ps1, etc.).
• The output is generated from multiple moving parts rather than one canonical manifest.
• Validation happens late, after files are already written, rather than early as a preflight.
• The success criteria are not surfaced clearly enough to the user.

Recommended Plan

Phase 1: Split the bootstrap into explicit modes

Create a single, obvious entry path that classifies the current run into one of three modes:

• Fresh install
• Update
• Repair

This should be shown to the user up front before any file writes happen. The quickstart should not silently branch into a complex state machine.

Acceptance criteria

• The user can see which mode is being executed.
• A same-version repo goes directly to repair mode if files are missing or malformed.
• A fresh install does not run update logic.
• A normal update does not re-run fresh-install prompts.

Phase 2: Add a real preflight preview

Add a dry-run / preview mode that lists what will happen before anything changes:

• Files to create
• Files to overwrite
• Files to skip
• Files that need validation
• Files that are user-owned and must never be touched

This reduces surprise and lets the user understand the blast radius.

Acceptance criteria

• Preview output appears before writes.
• The preview is readable and grouped by file type.
• The user can cancel after seeing the plan.

Phase 3: Move to a manifest-driven generator

Instead of relying on many ad hoc scripts and per-command copies, define a canonical manifest that drives generation of:

• Agent shims
• Prompt files
• Default templates
• Script inventory
• Version stamp and compatibility metadata

This would make the setup far less error-prone and would reduce drift between generated files.

Acceptance criteria

• One source of truth for command names, shim names, and prompt destinations.
• Agent shims are generated from structured metadata rather than handwritten per-file logic.
• Template and script inventories come from the same manifest used by the bootstrap flow.

Phase 4: Reduce interactive prompts

Only ask questions when they materially change the output.

Suggested defaults:

• PowerShell on Windows
• Bash on macOS/Linux
• Repair mode for same-version installs with missing framework files
• No constitution bootstrap questions if a constitution already exists

Acceptance criteria

• Script preference is inferred from OS unless explicitly overridden.
• The quickstart asks fewer questions overall.
• The user can complete a typical bootstrap with minimal interruption.

Phase 5: Validate immediately after generation

Any generated YAML, markdown, or prompt shim should be validated before the flow reports success.

Suggested checks:

• Frontmatter validation for .github/agents/*.agent.md
• Markdown lint pass for generated markdown
• Presence checks for required stock files
• Version stamp verification after refresh

Acceptance criteria

• Invalid generated files are caught before success is reported.
• The system auto-repairs simple generation defects when possible.
• The user is never told the setup is done if the generated files are broken.

Phase 6: Make success output explicit

The final output should clearly say:

• Which mode ran
• Which files were created or refreshed
• Which files were untouched
• Which validation checks passed
• What to do next

Acceptance criteria

• The user can tell exactly what happened in one read.
• The output includes next steps and any remaining caveats.

Suggested Implementation Targets

Likely files/components to revise:

• .github/agents/devspark.specify.agent.md
• .github/prompts/devspark.specify.prompt.md
• .devspark/scripts/powershell/common.ps1
• .devspark/scripts/powershell/check-prerequisites.ps1
• .devspark/scripts/powershell/update-agent-context.ps1
• .devspark/scripts/powershell/create-new-feature.ps1
• .devspark/scripts/powershell/setup-plan.ps1
• .devspark/scripts/powershell/harvest.ps1
• .devspark/templates/*.md
• .vscode/settings.json

Priority Order

1. Simplify bootstrap mode selection.
2. Add preview/dry-run output.
3. Replace ad hoc generation with manifest-driven generation.
4. Cut unnecessary prompts.
5. Validate generated artifacts earlier.
6. Improve final reporting.

Expected User Impact

If this work is done well, quickstart should feel like this:

• One short question or zero questions.
• A clear explanation of what the system is about to do.
• A fast, deterministic bootstrap.
• Immediate validation with no confusing repairs after the fact.
• A clean end state with obvious next steps.

Why This Matters

This is not just polish. The current quickstart experience makes DevSpark feel more complicated than the workflow it is trying to enable. If quickstart is the first thing users see, it should behave like a sharp onboarding path, not an installer/debugger hybrid.

Notes From the Real Run

This feedback came from bootstrapping a real workspace with the Copilot quickstart flow on Windows. The setup eventually succeeded, but only after multiple hidden decisions, a version check, a repair pass, and manual inspection of generated shims.

That means the issue is reproducible enough to be treated as a product problem, not just a one-off inconvenience.