Skip to content

devspark_quickstart_copilot.md

Latest commit

 

History

History
607 lines (434 loc) · 26.1 KB

devspark_quickstart_copilot.md

File metadata and controls

607 lines (434 loc) · 26.1 KB
Raw

DevSpark Quickstart — GitHub Copilot

You are bootstrapping DevSpark, a spec-driven development process, into this repository. No CLI installation is required. You will pull prompt files from the DevSpark repo and place them in the correct directories.

Step 1: Gather Project Context

Detect the current OS to determine the active runtime for the plan preview — both script sets (PowerShell and Bash) are always installed regardless of OS.

OS detection (in priority order):

  1. If the workspace path contains a drive letter (e.g., C:\) or backslash separators → Windows (active runtime: PowerShell)
  2. If $env:OS is Windows_NT or $IsWindows is true → Windows (active runtime: PowerShell)
  3. If the shell environment is bash/zsh/sh → macOS/Linux (active runtime: Bash)
  4. If none of the above can be determined → assume macOS/Linux

State the detected OS before proceeding:

"Detected: Windows — active runtime PowerShell. Installing both PowerShell and Bash scripts." "Detected: macOS/Linux — active runtime Bash. Installing both PowerShell and Bash scripts."

Step 2: Detect Existing Installation

Before creating anything, check for prior legacy / DevSpark installations:

Check for What it means
.devspark/ exists DevSpark already installed. See "Version Check" below.
.documentation/ exists User artifacts exist. Preserve everything — never overwrite.
.specify/ exists Legacy layout detected. Needs migration.
.documentation/defaults/commands/ exists Pre-separation DevSpark. Stock commands need to move to .devspark/.
Root memory/ (without .documentation/memory/) Legacy structure. Needs migration.
Root scripts/ or templates/ (without .devspark/scripts/) Legacy structure. Needs migration.
.github/agents/specify.*.agent.md files Legacy shims detected. Rename to devspark.* prefix.

If nothing is found, skip ahead to Step 3.

Migration: .specify/ (legacy layout)

Tell the user what you found and ask for confirmation before proceeding.

  1. Copy .specify/memory/* → .documentation/memory/ (skip files that already exist at destination)
  2. Copy .specify/specs/* → .documentation/specs/ (skip files that already exist)
  3. Copy any .specify/ root-level .md files → .documentation/ (skip files that already exist)
  4. Rename .specify/ → .specify.old/ (preserve as backup)
  5. Report: "Migrated .specify/ → .documentation/. Backup at .specify.old/"

Migration: .documentation/defaults/ (pre-separation DevSpark)

  1. Create .devspark/ directory structure
  2. Move .documentation/defaults/commands/* → .devspark/defaults/commands/
  3. Move .documentation/defaults/templates/* → .devspark/templates/ if present
  4. Move .documentation/scripts/* → .devspark/scripts/ (only stock DevSpark scripts with framework header comments — leave user-created scripts)
  5. Move .documentation/templates/* → .devspark/templates/ (only stock DevSpark templates)
  6. Delete empty .documentation/defaults/ if nothing remains
  7. Report: "Migrated framework files from .documentation/ → .devspark/"

Migration: Root-level directories (legacy layout)

  1. Copy memory/* → .documentation/memory/ (skip existing)
  2. Copy specs/* → .documentation/specs/ (skip existing)
  3. Rename migrated directories → {name}.old/ (e.g., memory.old/)

Migration: Old agent shims

  1. Rename .github/agents/specify.*.agent.md → .github/agents/devspark.*.agent.md
  2. Rename .github/prompts/specify.*.prompt.md → .github/prompts/devspark.*.prompt.md
  3. In all shim files, replace .documentation/defaults/commands/ → .devspark/defaults/commands/
  4. Check .claude/commands/specify.* and .cursor/commands/specify.* — rename to devspark.* prefix if found

After migration, continue with Step 3.

Step 2b: Announce Mode and Preview Plan

Before writing any files, output a mode banner so the user knows exactly what is about to happen.

Mode Banner

Choose the banner that matches the detected state from Step 2:

Detected state Banner to output
No .devspark/ found, no legacy ▶ Mode: FRESH INSTALL
.devspark/ found, version older than latest ▶ Mode: UPDATE (vX.Y.Z → vY.Y.Y)
.devspark/ found, version matches latest, all files present ▶ Mode: ALREADY CURRENT (vX.Y.Z) — nothing to do. Skipping to Step 12.
.devspark/ found, version matches latest, files missing ▶ Mode: REPAIR (vX.Y.Z — re-fetching missing framework files)
Legacy layout detected ▶ Mode: MIGRATION → FRESH INSTALL

Output the banner, then immediately output a brief plan preview — one line per action group:

Plan:
  • Create directories: .devspark/, .documentation/, .github/, .vscode/
  • Fetch N stock prompts → .devspark/defaults/commands/
  • Fetch N templates → .devspark/templates/
  • Fetch N scripts → .devspark/scripts/bash/ + .devspark/scripts/powershell/ (both always)
  • Generate N agent shims → .github/agents/ and .github/prompts/
  • Seed constitution → .documentation/memory/constitution.md  [if needed]
  • Write VERSION stamp → .devspark/VERSION
  • Update .gitignore

For Update and Repair modes, show only the steps that will actually run.

Proceed immediately after outputting the banner and plan — no additional confirmation needed unless you are about to perform a migration that renames or deletes directories.

Constitution bootstrap questions (only if needed — Fresh Install only)

After detection and any migration work above, check whether .documentation/memory/constitution.md already exists.

  • If it exists already, or was migrated into place, do not ask for project name, tech stack, or core principles.
  • If it does not exist, ask these additional questions before Step 3:
    1. Project name — What is this project called?
    2. Tech stack — What languages, frameworks, and tools does this project use?
    3. Core principles — Name 3–5 non-negotiable principles for this project (e.g., "test-first", "accessibility", "API-first", "simplicity"). If unsure, say "use defaults" and you'll get a starter set.

If .devspark/ already exists — Version Check

  1. Read .devspark/VERSION. If the file is missing or version: is not semver (X.Y.Z), treat the installed version as unknown.
  2. Fetch https://raw.githubusercontent.com/markhazleton/devspark/main/CHANGELOG.md and extract the most recent ## [X.Y.Z] heading as LATEST_VERSION.
  3. Compare and act:
Installed version Latest version Action
Same as latest — Verify framework files. If any stock prompt, template, script, or agent shim is missing, run repair mode below. Otherwise report: "DevSpark is already at vX.Y.Z — nothing to update." Skip to Step 12 (Verify & Report).
Older than latest Newer Report the version gap, then run update mode below.
unknown (VERSION missing) Any Treat as outdated. Run update mode.

Update Mode

Tell the user: "Updating DevSpark from vX.Y.Z → vY.Y.Y. Your .documentation/ files will not be touched."

Execute only these steps in order, then skip to Step 12 (Verify & Report):

  • Step 4 — Re-fetch all stock prompts into .devspark/defaults/commands/ (overwrite)
  • Step 5 — Re-fetch all helper templates into .devspark/templates/ (overwrite)
  • Step 5.5 — Re-fetch all Agent Skill packages into .devspark/templates/skills/ (overwrite)
  • Step 6 — Re-fetch all scripts into .devspark/scripts/ (overwrite)
  • Step 7 — Re-create all agent shim files (overwrite — shims are framework files)
  • Step 10 — Update .devspark/VERSION with new version and today's date

Never touch .documentation/, the constitution, .gitignore, or platform guide files (VS Code settings, etc.).

Repair Mode

If the installed version matches LATEST_VERSION but framework files are missing, tell the user: "DevSpark is already at vX.Y.Z, but the framework install is incomplete. Re-fetching stock files to repair it. Your .documentation/ files will not be touched."

Execute only these steps in order, then skip to Step 12 (Verify & Report):

  • Step 4 — Re-fetch all stock prompts into .devspark/defaults/commands/ (overwrite missing or stale copies)
  • Step 5 — Re-fetch all helper templates into .devspark/templates/ (overwrite missing or stale copies)
  • Step 5.5 — Re-fetch all Agent Skill packages into .devspark/templates/skills/ (overwrite missing or stale copies)
  • Step 6 — Re-fetch all scripts into .devspark/scripts/ (overwrite missing or stale copies)
  • Step 7 — Re-create all agent shim files (overwrite missing or stale copies)
  • Step 10 — Re-write .devspark/VERSION using the current LATEST_VERSION and today's date

Step 3: Create Directory Structure

Create these directories (skip any that already exist):

.devspark/
├── defaults/commands/
├── scripts/
└── templates/

.documentation/
├── memory/
├── specs/
├── commands/          ← team-level overrides (optional)
└── decisions/

.github/
├── agents/
└── prompts/

.vscode/

Step 4: Pull Stock Prompts

Live manifest (preferred): Before fetching individual files, query the GitHub API to get the authoritative command list: https://api.github.com/repos/markhazleton/devspark/contents/templates/commands Use the name field of each returned entry (strip .md suffix) as the command list. This keeps the install in sync with the latest release automatically. Fall back to the static table below only if the API is unreachable.

Fetch each file from https://raw.githubusercontent.com/markhazleton/devspark/main/templates/commands/ and save to .devspark/defaults/commands/ with the devspark. prefix:

Source file Destination
specify.md .devspark/defaults/commands/devspark.specify.md
plan.md .devspark/defaults/commands/devspark.plan.md
tasks.md .devspark/defaults/commands/devspark.tasks.md
implement.md .devspark/defaults/commands/devspark.implement.md
create-pr.md .devspark/defaults/commands/devspark.create-pr.md
constitution.md .devspark/defaults/commands/devspark.constitution.md
pr-review.md .devspark/defaults/commands/devspark.pr-review.md
address-pr-review.md .devspark/defaults/commands/devspark.address-pr-review.md
quickfix.md .devspark/defaults/commands/devspark.quickfix.md
harvest.md .devspark/defaults/commands/devspark.harvest.md
release.md .devspark/defaults/commands/devspark.release.md
critic.md .devspark/defaults/commands/devspark.critic.md
clarify.md .devspark/defaults/commands/devspark.clarify.md
analyze.md .devspark/defaults/commands/devspark.analyze.md
checklist.md .devspark/defaults/commands/devspark.checklist.md
personalize.md .devspark/defaults/commands/devspark.personalize.md
site-audit.md .devspark/defaults/commands/devspark.site-audit.md
evolve-constitution.md .devspark/defaults/commands/devspark.evolve-constitution.md
discover-constitution.md .devspark/defaults/commands/devspark.discover-constitution.md
repo-story.md .devspark/defaults/commands/devspark.repo-story.md
archive.md .devspark/defaults/commands/devspark.archive.md (deprecated compatibility alias for harvest)
upgrade.md .devspark/defaults/commands/devspark.upgrade.md
update-pr.md .devspark/defaults/commands/devspark.update-pr.md
taskstoissues.md .devspark/defaults/commands/devspark.taskstoissues.md
add-application.md .devspark/defaults/commands/devspark.add-application.md
list-applications.md .devspark/defaults/commands/devspark.list-applications.md
validate-registry.md .devspark/defaults/commands/devspark.validate-registry.md

Step 4 Validation (required)

After fetching, verify every expected command file landed successfully:

$expected = Get-ChildItem .devspark/defaults/commands/devspark.*.md -ErrorAction SilentlyContinue
Write-Host "Commands installed: $($expected.Count)"
$expected | ForEach-Object { if (-not (Test-Path $_.FullName)) { Write-Host "MISSING: $_" } }
count=$(ls .devspark/defaults/commands/devspark.*.md 2>/dev/null | wc -l)
echo "Commands installed: $count"

If any command file is missing, re-fetch it before continuing.

Step 5: Pull Helper Templates

Fetch from https://raw.githubusercontent.com/markhazleton/devspark/main/templates/ and save to .devspark/templates/:

  • spec-template.md
  • plan-template.md
  • tasks-template.md
  • quick-spec-template.md
  • checklist-template.md
  • agent-file-template.md
  • vscode-settings.json

Also fetch https://raw.githubusercontent.com/markhazleton/devspark/main/agents-registry.json and save it to agents-registry.json at the repository root.

Step 5 Validation (required)

After fetching, verify each template file is present:

@('spec-template.md','plan-template.md','tasks-template.md','quick-spec-template.md',
  'checklist-template.md','agent-file-template.md','vscode-settings.json') | ForEach-Object {
    if (-not (Test-Path ".devspark/templates/$_")) { Write-Host "MISSING: $_" }
}
for f in spec-template.md plan-template.md tasks-template.md quick-spec-template.md \
         checklist-template.md agent-file-template.md vscode-settings.json; do
  [ -f ".devspark/templates/$f" ] || echo "MISSING: $f"
done

If any file is missing, re-fetch it before continuing.

Step 5.5: Pull Agent Skills

DevSpark 2.4.0+ delegates some command reasoning to portable Agent Skill packages under .devspark/templates/skills/. /devspark.specify requires the write-spec skill — without it, the command silently degrades to legacy inline behaviour.

Fetch each file below from https://raw.githubusercontent.com/markhazleton/devspark/main/ and save it to the matching path under .devspark/templates/skills/ (preserve the subdirectory structure):

  • templates/skills/README.md
  • templates/skills/ADAPTER-contract.md
  • templates/skills/SKILL-validation-contract.md
  • templates/skills/references/devspark-skills-guide.md
  • templates/skills/write-spec/SKILL.md
  • templates/skills/write-spec/references/spec-template.md
  • templates/skills/write-spec/scripts/gather-context.ps1
  • templates/skills/write-spec/scripts/gather-context.sh

Skills are framework-owned and safe to overwrite on every install or upgrade. They never touch .documentation/.

Step 5.5 Validation (required)

After fetching, verify the critical skill files landed:

@(
  'ADAPTER-contract.md',
  'SKILL-validation-contract.md',
  'write-spec/SKILL.md',
  'write-spec/scripts/gather-context.ps1',
  'write-spec/scripts/gather-context.sh',
  'write-spec/references/spec-template.md'
) | ForEach-Object {
  if (-not (Test-Path ".devspark/templates/skills/$_")) { Write-Host "MISSING: skills/$_" }
}
for f in ADAPTER-contract.md SKILL-validation-contract.md \
         write-spec/SKILL.md write-spec/scripts/gather-context.ps1 \
         write-spec/scripts/gather-context.sh write-spec/references/spec-template.md; do
  [ -f ".devspark/templates/skills/$f" ] || echo "MISSING: skills/$f"
done

If any skill file is missing, re-fetch it before continuing. A missing write-spec/SKILL.md will cause /devspark.specify to silently fall back to pre-2.4 behaviour.

Step 6: Pull Scripts

Fetch both script sets from https://raw.githubusercontent.com/markhazleton/devspark/main/scripts/ — always install both PowerShell and Bash, regardless of the current OS. This ensures the repository works for developers on macOS, Linux, and Windows without requiring a reinstall when switching machines.

Save to .devspark/scripts/powershell/:

  • powershell/common.ps1
  • powershell/platform.ps1
  • powershell/check-prerequisites.ps1
  • powershell/create-new-feature.ps1
  • powershell/setup-plan.ps1
  • powershell/get-pr-context.ps1
  • powershell/address-pr-review.ps1
  • powershell/create-pr.ps1
  • powershell/update-agent-context.ps1
  • powershell/archive-context.ps1 (deprecated compatibility wrapper around harvest)
  • powershell/evolution-context.ps1
  • powershell/harvest.ps1
  • powershell/quickfix-context.ps1
  • powershell/release-context.ps1
  • powershell/repo-story-context.ps1
  • powershell/site-audit.ps1

Save to .devspark/scripts/bash/:

  • bash/common.sh
  • bash/platform.sh
  • bash/check-prerequisites.sh
  • bash/create-new-feature.sh
  • bash/setup-plan.sh
  • bash/get-pr-context.sh
  • bash/create-pr.sh
  • bash/update-agent-context.sh
  • bash/archive-context.sh (deprecated compatibility wrapper around harvest)
  • bash/evolution-context.sh
  • bash/harvest.sh
  • bash/quickfix-context.sh
  • bash/release-context.sh
  • bash/repo-story-context.sh
  • bash/site-audit.sh

Runtime OS selection: Commands define both sh and ps script variants. The AI agent selects the appropriate variant at execution time based on the active OS — PowerShell on Windows, Bash on macOS/Linux. Because both sets are always installed, switching between machines never requires a reinstall.

Script override layer: If the team later needs to customize a script (e.g., for Azure DevOps instead of GitHub), they copy the script to .documentation/scripts/{bash|powershell}/ and edit it there. The team copy takes priority over the stock version in .devspark/scripts/. Upgrades only overwrite .devspark/scripts/ and never touch .documentation/scripts/.

Step 6 Validation (required)

After fetching, verify both script directories are populated:

$ps = (Get-ChildItem .devspark/scripts/powershell/*.ps1 -ErrorAction SilentlyContinue).Count
$sh = (Get-ChildItem .devspark/scripts/bash/*.sh -ErrorAction SilentlyContinue).Count
Write-Host "PowerShell scripts: $ps  Bash scripts: $sh"
if ($ps -eq 0 -or $sh -eq 0) { Write-Host "WARNING: one or both script sets are missing — re-fetch before continuing" }
ps=$(ls .devspark/scripts/powershell/*.ps1 2>/dev/null | wc -l | tr -d ' ')
sh=$(ls .devspark/scripts/bash/*.sh 2>/dev/null | wc -l | tr -d ' ')
echo "PowerShell scripts: $ps  Bash scripts: $sh"
[ "$ps" -eq 0 ] || [ "$sh" -eq 0 ] && echo "WARNING: one or both script sets are missing — re-fetch before continuing"

If either count is 0, re-fetch the missing set before continuing.

Step 7: Create Copilot Agent Shims

For each command in .devspark/defaults/commands/devspark.{name}.md, create two files:

.github/agents/devspark.{name}.agent.md

---
name: devspark.{name}
description: DevSpark {name} command shim
---

## Prompt Resolution

Determine the current git user by running `git config user.name`.
Normalize to a folder-safe slug: lowercase, replace spaces with hyphens, strip non-alphanumeric/hyphen chars.

Read and execute the instructions from the **first file that exists**:
1. `.documentation/{git-user}/commands/devspark.{name}.md` (personalized override)
2. `.documentation/commands/devspark.{name}.md` (team customization)
3. `.devspark/defaults/commands/devspark.{name}.md` (stock default)

## User Input

{{input}}

Pass the user input above to the resolved prompt.

Important frontmatter rule:

  • Use valid YAML scalars for name and description.
  • Never emit doubled quotes such as ""devspark.specify"".
  • If you choose to quote values, use one pair only: "devspark.specify".

.github/prompts/devspark.{name}.prompt.md

Create a companion prompt file with the same 3-tier resolution content (without YAML frontmatter).

Step 7 Validation (required)

After generating shims, verify no malformed doubled-quote frontmatter exists.

PowerShell:

Get-ChildItem .github/agents/devspark.*.agent.md -ErrorAction SilentlyContinue |
  Select-String -Pattern '^name:\s*""|^description:\s*""' |
  ForEach-Object { $_.Path + ":" + $_.LineNumber + " -> " + $_.Line }

Bash:

grep -nE '^name:[[:space:]]*""|^description:[[:space:]]*""' .github/agents/devspark.*.agent.md || true

If any matches are found, fix those lines to valid YAML and re-run the check until it reports no matches.

Step 8: VS Code Settings

Copy .devspark/templates/vscode-settings.json to .vscode/settings.json. If the file already exists, merge the github.copilot settings into it without overwriting other settings.

Step 9: Seed the Constitution

If .documentation/memory/constitution.md does not already exist, fetch https://raw.githubusercontent.com/markhazleton/devspark/main/.documentation/memory/constitution.md and save it there.

If the file was migrated from .specify/ or already existed, preserve it and do not overwrite it.

Only when creating a new constitution, use the project name, tech stack, and core principles collected after Step 2 to customize .documentation/memory/constitution.md:

  • Replace [PROJECT_NAME] with the actual project name
  • Fill in the core principles the user provided
  • Add the tech stack as a "Technology" or "Stack" section

Step 10: Write VERSION Stamp

Use the LATEST_VERSION you already fetched in Step 2.

Create .devspark/VERSION:

version: {LATEST_VERSION}
installed: {today's date YYYY-MM-DD}
method: copilot-quickstart
migrated-from: {legacy-layout | documentation-defaults | fresh}

Step 11: Update .gitignore

Append to .gitignore if not already present:

# DevSpark — personal overrides (never commit)
.documentation/*/commands/

Step 12: Verify & Report

Run a final presence check across all installed framework files and output a structured summary.

12a — Presence checks (stop and repair if any fail)

  • Every stock prompt from Step 4 exists in .devspark/defaults/commands/
  • Every helper template from Step 5 exists in .devspark/templates/
  • The selected script set from Step 6 exists under .devspark/scripts/
  • Agent shim files from Step 7 exist in both .github/agents/ and .github/prompts/
  • Shim frontmatter is valid YAML (no doubled-quote defects)
  • .devspark/VERSION exists and contains a semver version
  • .gitignore contains the personal-overrides exclusion

If any check fails, run Repair Mode before reporting success. Do not tell the user the setup is done if framework files are broken or missing.

12b — Output a structured completion banner

Output the following summary (adapt counts and status to what actually ran):

✔ DevSpark {LATEST_VERSION} — {MODE} complete

Mode:          {FRESH INSTALL | UPDATE vX.Y.Z → vY.Y.Y | REPAIR | MIGRATION → FRESH INSTALL}
Script type:   {PowerShell (Windows) | Bash (macOS/Linux)}

Files written:
  • {N} stock prompts   → .devspark/defaults/commands/
  • {N} templates       → .devspark/templates/
  • {N} scripts         → .devspark/scripts/{powershell|bash}/
  • {N} agent shims     → .github/agents/
  • {N} prompt files    → .github/prompts/
  • VERSION stamp       → .devspark/VERSION
  • .gitignore updated

Files preserved (never touched by DevSpark):
  • .documentation/    — all user artifacts untouched
  {IF migration: • Backup at .specify.old/ (safe to delete once satisfied)}

Validation:
  • Shim frontmatter — {ok | repaired N file(s)}
  • Framework files  — all present
  • VERSION stamp    — {LATEST_VERSION}

Constitution: {seeded fresh | migrated from .specify/ | already existed — not touched}

12c — Next steps

Tell the user:

Start DevSpark: type @devspark.specify in Copilot Chat.

Recommended entrypoints (DevSpark v2):
  @devspark.run create-spec     — specify → plan → tasks → analyze
  @devspark.run execute-plan    — implement → create-pr → pr-review
  @devspark.run suggest-improvement  — file an improvement against markhazleton/devspark

To upgrade later (no CLI required):
  @workspace Follow the instructions at
  https://raw.githubusercontent.com/markhazleton/devspark/main/templates/commands/upgrade.md

See .documentation/workflows/getting-started.md for the full walkthrough.

Also explain the 3-tier override system in one sentence:

Personal overrides in .documentation/{git-user}/commands/ take priority over team overrides in .documentation/commands/, which take priority over stock prompts in .devspark/defaults/commands/. Run @devspark.personalize {command} to create a personal override.

Multi-App Monorepo Support (Optional)

This section is entirely optional. If your repository contains a single application, skip this section — DevSpark works perfectly without it.

For repositories containing multiple applications with different platforms, runtimes, or governance rules, DevSpark offers opt-in multi-app support.

When to Consider Multi-App

  • Your monorepo has apps with different tech stacks (e.g., .NET API + React UI)
  • Different apps need different governance rules or risk profiles
  • You want per-app constitutions, profiles, or code review scopes

Quick Setup

  1. Run /devspark.add-application to create a registry at .documentation/devspark.json interactively
  2. Each application gets its own .documentation/ directory at {app-path}/.documentation/
  3. Use --app <id> with any DevSpark command to scope it to a specific application
  4. Use --repo-scope for repository-wide operations

Key Concepts

  • Registry: .documentation/devspark.json defines all applications, profiles, and dependencies
  • Profiles: Reusable rule bundles (e.g., api-profile, web-profile) that apps inherit
  • App-local manifest: Optional {app-path}/app.json for app-specific overrides
  • Scope: Every workflow runs in repo, single-app, or cross-app scope

Commands

Command Purpose
/devspark.add-application Register a new application in the registry
/devspark.list-applications View all registered applications and profiles
/devspark.validate-registry Validate registry schema, references, and consistency

For details, see the Multi-App Specification.