Skip to content

README.md

Latest commit

 

History

History
351 lines (252 loc) · 17.7 KB

README.md

File metadata and controls

351 lines (252 loc) · 17.7 KB
Raw
Make Bold Solutions

DevSpark

A structured development process for AI coding assistants.
Just markdown files — no install required.

Current Release Release GitHub stars License Documentation

Live Site: https://dev.makeboldspark.com

Not a program. Not a subscription. Copy 28 slash-command prompts plus the helper templates and scripts into your project and your AI coding assistant gets a repeatable workflow — from requirements through release. Works with Claude, Copilot, Cursor, Gemini, and 14 more.

What's In This Repo

devspark/
├── agents-registry.json  ← Canonical metadata for supported agent integrations
├── templates/commands/   ← 28 slash-command prompt files (THE PRODUCT)
├── scripts/              ← Context-gathering scripts (PowerShell + Bash)
├── src/devspark_cli/     ← Optional CLI for automated setup
└── .documentation/       ← Guides, media, and GitHub Pages site

DevSpark Vocabulary

  • Prompt: A workflow command surface, usually a slash-command file, that orchestrates DevSpark lifecycle behavior such as specification, planning, implementation, review, or release.
  • Agent: An AI runtime or client integration such as Codex, Claude, Copilot, Cursor, or Gemini. Agent metadata lives in agents-registry.json and describes supported integrations, not team responsibilities.
  • Skill: A reusable portable capability package that a prompt can delegate to when specialized task knowledge is useful.
  • Participant: A human or AI-filled team member carrying responsibility for work, review, approval, critique, or decision capture in a workflow.
  • Role: A responsibility label assigned to a participant, such as owner, planner, implementer, reviewer, critic, or scribe.

Participant metadata is optional advisory context in artifacts. It does not change prompt resolution, script resolution, command behavior, or the existing customization process.

Agent Skills

DevSpark treats skills as portable capability packages within a governed lifecycle orchestration system. Commands invoke skills; DevSpark governs the lifecycle around them.

The dual-surface model:

command -> adapter -> skill -> context scripts -> agent reasoning -> artifact
  • Slash-commands (templates/commands/) own DevSpark-specific lifecycle behavior: route classification, branch creation, multi-app scoping, artifact placement, and gate enforcement.
  • Agent Skills (templates/skills/) own portable capability instructions that run in any skills-compatible client without DevSpark installed.

The adapter contract (templates/skills/ADAPTER-contract.md) defines how a command invokes a skill. The skill validation contract (templates/skills/SKILL-validation-contract.md) defines the rules every SKILL.md must satisfy. See templates/skills/references/devspark-skills-guide.md for the contributor walkthrough for adding new skills.

Get Started

DevSpark v2 ships three flagship aliases that are the recommended entrypoints for every new feature. Run them via devspark run <alias> (note: devspark run is a CLI command — there is no /devspark.run slash command):

Alias What it runs
create-spec specify → plan → tasks → analyze (pauses after analyze for review)
execute-plan implement → create-pr → pr-review (pauses after create-pr)
suggest-improvement capture-context → classify-improvement → create-issue (files an issue against markhazleton/devspark)

A fourth, more advanced alias, full-cycle, chains the entire lifecycle (specify → plan → tasks → critic → analyze → tasks (remediate) → implement → create-pr → pr-review) with autonomy.level: autonomous and guardrails instead of mandatory pauses — for users who want fewer checkpoints, not more. devspark run full-cycle still expects an agent already driving the conversation to act on each step; for genuinely unattended execution (no agent watching), use devspark harness run full-cycle.harness.yaml --adapter claude_code --hands-off instead.

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

For one-off work outside a workflow, the legacy entry command remains: /devspark.specify. It classifies the request as a one-off fix, a quick spec, or a full spec, explains the recommendation, and lets the human confirm the route before proceeding.

Option A — Agent Quickstart (recommended — no install)

Point your AI agent at the quickstart prompt for your platform:

The agent asks a few questions, then pulls and installs all DevSpark prompts.

For ongoing updates, use the same no-install approach:

  • Paste this upgrade prompt URL into your agent chat
  • Ask it to run an upgrade in your current repository

This keeps upgrades prompt-first and does not require the CLI.

Option B — Download and Drop

  1. Download the latest release zip for your agent and unzip into your project
  2. Start using /devspark.* commands in your AI assistant

Option C — CLI (advanced/optional)

uv tool install devspark-cli --from git+https://github.com/markhazleton/devspark.git
devspark init my-project          # new project
devspark init --here --ai claude  # existing project

The CLI also exposes the optional harness runtime and environment checks:

devspark doctor
devspark harness validate sample.harness.yaml
devspark harness run sample.harness.yaml --dry-run
devspark adapter list

For the full unattended lifecycle (specify through pr-review, no human checkpoints), see full-cycle.harness.yaml:

devspark adapter doctor                                   # confirm a write-capable adapter is ready
devspark harness validate full-cycle.harness.yaml
devspark harness run full-cycle.harness.yaml --adapter claude_code --hands-off

For a full walkthrough see the Implementation Lifecycle Guide.

Recommended review loop: specify → implement → pr-review → address-pr-review → pr-review UPDATE → merge.

Harness Runtime

DevSpark also ships an additive CLI runtime for repeatable engineering workflows. This runtime is separate from the 28 slash commands and is available when you install the optional CLI or work from a compatible source checkout.

The harness runtime adds:

  • devspark harness run to execute a declarative workflow spec
  • devspark harness validate to check spec structure without execution
  • devspark harness trace to inspect the event log from a prior run
  • devspark adapter list and devspark adapter default to inspect and persist adapter preferences
  • devspark doctor to verify the local environment is ready for harness workflows

Harness runs write structured artifacts to .documentation/devspark/runs/ by default, preserve partial state on abort, and support repository or app-scoped execution when a multi-app registry is present.

See Harness Engineering for the runtime model, command reference, artifact layout, adapters, and spec design guidance.

Slash Commands

Core Workflow

Command Purpose
/devspark.constitution Establish project principles and guidelines
/devspark.specify Define what you want to build (requirements & user stories)
/devspark.plan Create a technical implementation plan
/devspark.tasks Break the plan into actionable task lists
/devspark.implement Execute tasks and build the feature
/devspark.create-pr Draft or update a spec-aware pull request
/devspark.update-pr Refresh an existing pull request description from the current branch delta

Constitution-Powered (no spec required)

Command Purpose
/devspark.pr-review Constitution-based PR review
/devspark.address-pr-review Apply PR review fixes with mandatory commit isolation gates
/devspark.site-audit Comprehensive codebase audit
/devspark.quickfix Lightweight workflow for bug fixes
/devspark.critic Adversarial risk analysis
/devspark.release Archive dev artifacts and prepare releases
/devspark.harvest Canonical knowledge-preserving cleanup and archival workflow
/devspark.evolve-constitution Propose constitution amendments
/devspark.repo-story Generate narrative from commit history
/devspark.commit-audit Analyze commit history for workflow, hygiene, and delivery signals
/devspark.taskstoissues Convert tasks.md into dependency-ordered GitHub issues

Quality & Personalization

Command Purpose
/devspark.clarify Ask structured questions to de-risk ambiguity
/devspark.analyze Cross-artifact consistency check
/devspark.checklist Generate quality validation checklists
/devspark.personalize Create per-user command overrides
/devspark.discover-constitution Generate a constitution from existing code
/devspark.upgrade Pull latest DevSpark prompts into your project

/devspark.harvest is the canonical cleanup and archival workflow. /devspark.archive remains available only as a deprecated compatibility alias during migration.

Multi-App (Optional)

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

See .documentation/index.md for full command details.

Multi-App Monorepo Support (Optional)

Single-app repositories need nothing here. Multi-app is entirely optional — if your repo has one application, skip this section entirely. Everything works out of the box.

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

When to Use Multi-App

Scenario Recommendation
Single application or library Skip multi-app — standard DevSpark is all you need
Monorepo with shared conventions Skip multi-app — one constitution covers everything
Monorepo with different platforms (e.g., .NET API + React UI) Consider multi-app — each app can have tailored rules
Monorepo with different governance (e.g., PCI service + internal tool) Use multi-app — app-specific constitutions and profiles

How It Works

  1. Create a registry at .documentation/devspark.json — or run /devspark.add-application to create one interactively
  2. Assign profiles — reusable rule bundles (e.g., api-profile, web-profile) that apps inherit
  3. Scope commands — use --app <id> to target a specific application, or --repo-scope for repo-wide operations
  4. App-local overrides — each app can have its own .documentation/ directory and optional app.json manifest

Multi-App Commands

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

For the full specification, see the Monorepo Guide.

Customization Without Risk

DevSpark cleanly separates your work from its installation:

.devspark/                 ← Installation (removable, upgrade-safe)
├── defaults/commands/     ← Stock prompts
├── scripts/              ← Stock helper scripts
├── templates/            ← Spec/plan templates
└── VERSION               ← Installed version stamp

.documentation/            ← Your work (never touched by DevSpark)
├── memory/constitution.md
├── specs/
├── commands/             ← Team command overrides
├── scripts/              ← Team script overrides (optional)
├── devspark.json         ← Multi-app registry (optional)
└── {git-user}/commands/  ← Personal overrides

Multi-app layout (optional): When using multi-app, each application also gets {app-path}/.documentation/ for app-local constitutions and overrides.

3-tier prompt resolution (first match wins):

  1. .documentation/{git-user}/commands/ — Personal tweaks
  2. .documentation/commands/ — Team customizations
  3. .devspark/defaults/commands/ — Stock prompts

2-tier script resolution (first match wins):

  1. .documentation/scripts/ — Team script overrides (e.g., Azure DevOps adapter)
  2. .devspark/scripts/ — Stock scripts

There is no third ownership tier. If an organization wants a shared baseline in .documentation/, it manages that through its own repo practices; DevSpark still only writes to .devspark/.

Participant metadata uses these existing repository-owned artifacts when present. It does not change how prompts or scripts are found; customization layers and precedence are unchanged.

Clean removal: devspark uninstall removes .devspark/ and agent shims, leaves .documentation/ untouched.

Supported AI Agents

DevSpark is agent-agnostic. Every agent below gets thin shims that resolve personal overrides, team overrides, and stock prompts through the same command contract.

Agent Agent Agent
Claude Code ✅ Cursor ✅ Gemini CLI ✅
GitHub Copilot ✅ Codex CLI ✅ Windsurf ✅
Amp ✅ Roo Code ✅ Kilo Code ✅
Auggie CLI ✅ opencode ✅ Qwen Code ✅
SHAI ✅ Amazon Q ⚠️ IBM Bob ✅
CodeBuddy ✅ Qoder CLI ✅ Antigravity ✅

Learn More

Topic Link
Implementation lifecycle implementation-lifecycle.md
Harness engineering harness-engineering.md
Quickstart quickstart.md
Constitution guide constitution-guide.md
CLI reference installation.md
Upgrading upgrade.md
PR review guide pr-review-usage.md
Site audit guide site-audit-usage.md
Critic guide critic-usage.md
Harvest guide harvest-usage.md
Repo story repo-story-usage.md

Prerequisites

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Acknowledgements

DevSpark is maintained by Mark Hazleton and the open-source community.

Built by Mark Hazleton — Mark Hazleton, Solutions Architect DevSpark is part of the Make Bold Spark portfolio of technical demonstrations.

A Make Bold Solutions project, part of the Make Bold Spark family.

License

MIT — see LICENSE.