Skip to content

CLAUDE.md

Latest commit

 

History

History
702 lines (498 loc) · 26.5 KB

CLAUDE.md

File metadata and controls

702 lines (498 loc) · 26.5 KB
Raw

DevSpark

Spec-driven development process for AI coding assistants. Just markdown files — no install required.

Constitution

Read .documentation/memory/constitution.md before making changes — it defines non-negotiable principles.

Dogfooding Note

This IS the DevSpark source repo. All /devspark.* commands resolve directly to templates/commands/ — the source prompts you are iterating on. There is no .devspark/defaults/commands/ copy. Edits to prompts take effect immediately.

Agent Skills Architecture

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

Internal architecture: command → invokes → skill → context scripts → artifact

  • templates/skills/ — Agent Skills surface: portable capability packages
  • templates/skills/ADAPTER-contract.md — How commands invoke skills
  • templates/skills/SKILL-validation-contract.md — Validation rules for SKILL.md files
  • templates/skills/references/devspark-skills-guide.md — Contributor walkthrough

Skill validation: devspark skills list / devspark skills validate [path]

Repository Structure

  • templates/commands/ — 28 slash-command prompt files (the product)
  • templates/skills/ — Agent Skills (portable capability packages)
  • scripts/ — Context-gathering scripts (PowerShell + Bash)
  • src/devspark_cli/ — Optional CLI for automated setup
  • quickstart/ — Agent-specific bootstrap guides
  • .documentation/ — Guides, media, and GitHub Pages site

Commands

Use /devspark.{command} to invoke workflows:

Flagship aliases (recommended entrypoints, v2)

  • /devspark.run create-spec — specify → plan → tasks → analyze (pauses after analyze)
  • /devspark.run execute-plan — implement → create-pr → pr-review (pauses after create-pr)
  • /devspark.run suggest-improvement — file an improvement issue in markhazleton/devspark

Atomic prompts

  • /devspark.specify — Define requirements and user stories
  • /devspark.plan — Create implementation plan
  • /devspark.tasks — Break plan into actionable tasks
  • /devspark.implement — Execute tasks
  • /devspark.create-pr — Draft or update a pull request
  • /devspark.pr-review — Constitution-based PR review
  • /devspark.address-pr-review — Author-side PR review remediation with commit-isolation gates
  • /devspark.quickfix — Lightweight bug fix workflow
  • /devspark.add-application — Register app in multi-app registry (optional)
  • /devspark.list-applications — Display registered applications (optional)
  • /devspark.validate-registry — Validate registry consistency (optional)

Full list in templates/commands/.

Git Workflow Rules

  • HARD RULE — Branch Sync: Before creating a PR or running /devspark.pr-review, the source (head) branch MUST be fully in sync with the target (base) branch. If the source branch is behind the target, do NOT proceed — rebase or merge first.
    • Check: git fetch origin && git status
    • Fix: git rebase origin/main or gh pr update-branch {PR_NUMBER}

Coding Standards

  • Python 3.11+, typed with typer/rich/click
  • Markdown linted via markdownlint-cli2 (config: .markdownlint-cli2.jsonc)
  • Scripts in both PowerShell and Bash (keep parity); context scripts support GitHub, AzDO, and GitLab
  • Never overwrite .documentation/ user artifacts during CLI operations

AGENTS.md

About DevSpark

DevSpark is an Adaptive System Life Cycle Development (ASLCD) toolkit. It provides specification-driven workflows with constitution-powered quality gates, right-sized execution paths, and operational lifecycle guidance.

DevSpark CLI is the command-line interface that bootstraps projects with the DevSpark framework. It sets up the necessary directory structures, templates, and AI agent integrations to support ASLCD workflows.

The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.

Canonical Layout and Platform Shims

DevSpark uses a strict two-tier ownership model:

  • .devspark/ holds framework-managed stock prompts, scripts, and templates
  • .documentation/ holds repository-owned work product, overrides, constitutions, and specs

Platform-specific directories (.claude/, .github/, .cursor/, etc.) contain only thin shims plus hydrated agent context.

Agent Registry (agents-registry.json)

To prevent hardcoding AI agent identifiers across different workflow scripts and command templates, DevSpark leverages a centralized agents-registry.json file located in the repository root.

Key Features:

  1. Centralized Configuration: Defines available agents (e.g., Copilot, Claude Code, Cursor) and their capabilities.
  2. Cross-Editor Support: Simplifies extending DevSpark to support new IDEs or agent implementations.
  3. Workflow Integration: Used dynamically by create-pr and other workspace scripts to understand which agent platforms are available or active.

When adding a new AI assistant integration to DevSpark, simply append the agent's definition and configuration details to agents-registry.json.

File Layout

`.devspark/`
├── defaults/commands/           ← Stock command prompts (framework-managed)
├── scripts/                     ← Stock helper scripts
└── templates/                   ← Stock templates

.documentation/
├── commands/                    ← Team command overrides
│   ├── devspark.specify.md
│   ├── devspark.plan.md
│   ├── devspark.implement.md
│   ├── devspark.personalize.md
│   └── ...
├── {git-user}/                  ← Per-user personalized overrides
│   └── commands/
│       └── devspark.specify.md   ← Takes priority over shared default
├── scripts/
├── templates/
├── memory/
└── specs/

.claude/commands/                ← Thin shims only
.github/agents/                  ← Thin shims only
.cursor/commands/                ← Thin shims only

Shim Behavior

Each platform shim:

  1. Resolves the current git user (git config user.name, slug-normalized)
  2. Checks for a personalized override at .documentation/{git-user}/commands/devspark.{cmd}.md
  3. Falls back to the shared default at .documentation/commands/devspark.{cmd}.md
  4. Falls back again to .devspark/defaults/commands/devspark.{cmd}.md
  5. Passes through user input ($ARGUMENTS / {{args}}) to the resolved prompt

Multi-User Personalization

Team members can customize any command prompt without affecting others:

  • Run /devspark.personalize {command} to create a user-scoped copy
  • Personalized prompts live in .documentation/{git-user}/commands/
  • Committed to git so team members can share and review customizations
  • Delete the personalized file to revert to the shared default

Personalize Command

The /devspark.personalize command creates per-user prompt overrides:

/devspark.personalize specify       # Personalize the /devspark.specify command
/devspark.personalize plan          # Personalize the /devspark.plan command
/devspark.personalize implement     # Personalize the /devspark.implement command

General practices

  • Any changes to __init__.py for the DevSpark CLI require a version rev in pyproject.toml and addition of entries to CHANGELOG.md.

Lightweight Workflow Commands

These commands support the Adaptive System Life Cycle Development (ASLCD) approach, providing right-sized processes for tasks of varying complexity.

Quickfix Command

The /devspark.quickfix command enables rapid fixes without full spec overhead:

Key Features:

  1. Auto-Classification: Automatically classifies tasks as bug-fix, hotfix, minor-feature, config-change, or docs-update
  2. Targeted Validation: Only validates against constitution principles relevant to the task type
  3. Lightweight Records: Creates minimal documentation at /.documentation/quickfixes/QF-{YYYY}-{NNN}.md
  4. Completion Tracking: Supports marking quickfixes complete with commit/PR references
  5. Scope Detection: Warns when work expands beyond classification limits

Usage:

/devspark.quickfix fix null pointer in UserService
/devspark.quickfix urgent: payment timeout in checkout
/devspark.quickfix complete QF-2026-001
/devspark.quickfix list

Release Command

The /devspark.release command manages documentation lifecycle at release boundaries:

Key Features:

  1. Artifact Archival: Archives completed specs and quickfixes to /.documentation/releases/v{VERSION}/
  2. ADR Extraction: Distills key architectural decisions from specs into ADR format
  3. CHANGELOG Generation: Auto-generates changelog entries from completed work
  4. Version Calculation: Auto-determines MAJOR/MINOR/PATCH based on content
  5. Clean Slate: Resets specs directory for next development cycle
  6. Dry Run Mode: Preview changes before committing

Usage:

/devspark.release              # Auto-calculate version
/devspark.release 2.0.0        # Explicit version
/devspark.release --dry-run    # Preview only

Harvest Command

The /devspark.harvest command cleans up stale documentation and completed delivery artifacts while preserving useful knowledge in living docs:

Key Features:

  1. Knowledge-Preserving Cleanup: Captures durable guidance in CHANGELOG, instructions, and living docs before archival
  2. Documentation Triage: Scores and classifies stale drafts, reviews, audits, backups, and legacy-root docs
  3. Comment Rewriting: Finds spec-linked code comments and rewrites them into self-contained explanations
  4. Archive Safety: Moves obsolete artifacts to /.archive/ instead of deleting them
  5. Approval Gate: Requires an explicit user confirmation step before any edits or archival moves
  6. Scan Mode: Supports dry-run style inventory via --scope=scan

Usage:

/devspark.harvest
/devspark.harvest --scope=docs
/devspark.harvest --scope=comments
/devspark.harvest --scope=scan

Constitution Evolution Command

The /devspark.evolve-constitution command facilitates constitution amendments:

Key Features:

  1. Pattern Analysis: Scans PR reviews and audits for recurring violation patterns
  2. Gap Detection: Identifies issues not mapped to existing principles
  3. Proposal Generation: Creates CAP (Constitution Amendment Proposal) documents
  4. History Tracking: Maintains amendment history at /.documentation/memory/constitution-history.md
  5. Approval Workflow: Supports approve/reject actions with reasons

Usage:

/devspark.evolve-constitution                          # Full analysis
/devspark.evolve-constitution --from-pr #123           # From specific PR
/devspark.evolve-constitution suggest "API versioning" # Manual suggestion
/devspark.evolve-constitution approve CAP-2026-001     # Approve proposal
/devspark.evolve-constitution reject CAP-2026-002 "Too restrictive"

PR Review Command

The /devspark.pr-review command is a special command that works independently of the spec-driven development workflow:

Unique Characteristics

  1. Constitution-Only: Requires only /.documentation/memory/constitution.md - no spec, plan, or tasks needed
  2. Repository-Wide: Works for any PR in any branch (main, develop, feature, etc.)
  3. Persistent Storage: Reviews saved to /.documentation/specs/pr-review/pr-{id}.md with metadata
  4. Version Tracking: Tracks commit SHA and timestamp for each review
  5. Update Logic: Handles multiple reviews of same PR with history
  6. GitHub Integration: Uses GitHub CLI (gh) for PR data extraction

Implementation Notes

  • Script: Uses dedicated get-pr-context.{sh,ps1} scripts (not check-prerequisites)
  • No Feature Context: Doesn't require feature branch or spec directory
  • JSON Output: Scripts return PR metadata including commit SHA, files changed, diff availability
  • Error Handling: Graceful degradation when constitution missing or GitHub CLI unavailable

Agent Integration

When adding new agents, include /devspark.pr-review following the same pattern as other commands:

  • Markdown format for most agents
  • TOML format for Gemini/Qwen
  • Script placeholders: {SCRIPT} replaced with get-pr-context script path
  • Argument placeholder: $ARGUMENTS for PR number

See templates/commands/pr-review.md for the canonical template.

Adding New Agent Support

This section explains how to add support for new AI agents/assistants to the DevSpark CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.

Overview

Specify supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for:

  • Command file formats (Markdown, TOML, etc.)
  • Directory structures (.claude/commands/, .windsurf/workflows/, etc.)
  • Command invocation patterns (slash commands, CLI tools, etc.)
  • Argument passing conventions ($ARGUMENTS, {{args}}, etc.)

Current Supported Agents

agents-registry.json is the source of truth (release.commands_dir per agent). This table is a human-readable mirror — if it ever disagrees with the registry, trust the registry and fix this table.

Agent Directory Format CLI Tool Description
Claude Code .claude/commands/ Markdown claude Anthropic's Claude Code CLI
Gemini CLI .gemini/commands/ TOML gemini Google's Gemini CLI
GitHub Copilot .github/agents/ + .github/prompts/ Markdown N/A (IDE-based) GitHub Copilot in VS Code
Cursor .cursor/commands/ Markdown cursor-agent Cursor CLI
Qwen Code .qwen/commands/ TOML qwen Alibaba's Qwen Code CLI
opencode .opencode/command/ Markdown opencode opencode CLI
Codex CLI .codex/prompts/ Markdown codex Codex CLI
Windsurf .windsurf/workflows/ Markdown N/A (IDE-based) Windsurf IDE workflows
Kilo Code .kilocode/workflows/ Markdown N/A (IDE-based) Kilo Code IDE
Auggie CLI .augment/commands/ Markdown auggie Auggie CLI
Roo Code .roo/commands/ Markdown N/A (IDE-based) Roo Code IDE
CodeBuddy CLI .codebuddy/commands/ Markdown codebuddy CodeBuddy CLI
Qoder CLI .qoder/commands/ Markdown qodercli Qoder CLI
Amazon Q Developer CLI .amazonq/prompts/ Markdown q Amazon Q Developer CLI
Amp .agents/commands/ Markdown amp Amp CLI
SHAI .shai/commands/ Markdown shai SHAI CLI
IBM Bob .bob/commands/ Markdown N/A (IDE-based) IBM Bob IDE
Antigravity .gemini/commands/ Markdown N/A (built-in) DeepMind Antigravity

Step-by-Step Integration Guide

Follow these steps to add a new agent (using a hypothetical new agent as an example):

1. Add to the shared registry

IMPORTANT: Use the actual CLI tool name as the key, not a shortened version.

Add the new agent to agents-registry.json. This is the single source of truth for CLI setup, release packaging, and context generation:

{
  "key": "new-agent-cli",
  "name": "New Agent Display Name",
  "folder": ".newagent/",
  "context_file": "AGENTS.md",
  "requires_cli": true,
  "install_url": "https://example.com/install",
  "release": {
    "commands_dir": ".newagent/commands",
    "extension": "md",
    "arg_format": "$ARGUMENTS"
  }
}

Key Design Principle: The dictionary key should match the actual executable name that users install. For example:

  • ✅ Use "cursor-agent" because the CLI tool is literally called cursor-agent
  • ❌ Don't use "cursor" as a shortcut if the tool is cursor-agent

This eliminates the need for special-case mappings throughout the codebase.

Field Explanations:

  • name: Human-readable display name shown to users
  • folder: Directory where agent-specific files are stored (relative to project root)
  • install_url: Installation documentation URL (set to None for IDE-based agents)
  • requires_cli: Whether the agent requires a CLI tool check during initialization

2. Update CLI Help Text

Update the --ai parameter help text in the init() command to include the new agent:

ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, new-agent-cli, or q"),

Also update any function docstrings, examples, and error messages that list available agents.

3. Update README Documentation

Update the Supported AI Agents section in README.md to include the new agent:

  • Add the new agent to the table with appropriate support level (Full/Partial)
  • Include the agent's official website link
  • Add any relevant notes about the agent's implementation
  • Ensure the table formatting remains aligned and consistent

4. Update Release Package Script

Modify .github/workflows/scripts/create-release-packages.sh:

Add to ALL_AGENTS array
ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q)
Add case statement for directory structure
case $agent in
  # ... existing cases ...
  windsurf)
    mkdir -p "$base_dir/.windsurf/workflows"
    generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
esac

4. Update GitHub Release Script

Modify .github/workflows/scripts/create-github-release.sh to include the new agent's packages:

gh release create "$VERSION" \
  # ... existing packages ...
  .genreleases/devspark-template-windsurf-sh-"$VERSION".zip \
  .genreleases/devspark-template-windsurf-ps-"$VERSION".zip \
  # Add new agent packages here

5. Update Agent Context Scripts

Bash script (scripts/bash/update-agent-context.sh)

Add file variable:

WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/devspark-rules.md"

Add to case statement:

case "$AGENT_TYPE" in
  # ... existing cases ...
  windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;
  "")
    # ... existing checks ...
    [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf";
    # Update default creation condition
    ;;
esac
PowerShell script (scripts/powershell/update-agent-context.ps1)

Add file variable:

$windsurfFile = Join-Path $repoRoot '.windsurf/rules/devspark-rules.md'

Add to switch statement:

switch ($AgentType) {
    # ... existing cases ...
    'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' }
    '' {
        foreach ($pair in @(
            # ... existing pairs ...
            @{file=$windsurfFile; name='Windsurf'}
        )) {
            if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name }
        }
        # Update default creation condition
    }
}

6. Update CLI Tool Checks (Optional)

For agents that require CLI tools, add checks in the check() command and agent validation:

# In check() command
tracker.add("windsurf", "Windsurf IDE (optional)")
windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker)

# In init validation (only if CLI tool required)
elif selected_ai == "windsurf":
    if not check_tool("windsurf", "Install from: https://windsurf.com/"):
        console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects")
        agent_tool_missing = True

Note: CLI tool checks are now handled automatically based on the requires_cli field in AGENT_CONFIG. No additional code changes needed in the check() or init() commands - they automatically loop through AGENT_CONFIG and check tools as needed.

Important Design Decisions

Using Actual CLI Tool Names as Keys

CRITICAL: When adding a new agent to AGENT_CONFIG, always use the actual executable name as the dictionary key, not a shortened or convenient version.

Why this matters:

  • The check_tool() function uses shutil.which(tool) to find executables in the system PATH
  • If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
  • This creates unnecessary complexity and maintenance burden

Example - The Cursor Lesson:

❌ Wrong approach (requires special-case mapping):

AGENT_CONFIG = {
    "cursor": {  # Shorthand that doesn't match the actual tool
        "name": "Cursor",
        # ...
    }
}

# Then you need special cases everywhere:
cli_tool = agent_key
if agent_key == "cursor":
    cli_tool = "cursor-agent"  # Map to the real tool name

✅ Correct approach (no mapping needed):

AGENT_CONFIG = {
    "cursor-agent": {  # Matches the actual executable name
        "name": "Cursor",
        # ...
    }
}

# No special cases needed - just use agent_key directly!

Benefits of this approach:

  • Eliminates special-case logic scattered throughout the codebase
  • Makes the code more maintainable and easier to understand
  • Reduces the chance of bugs when adding new agents
  • Tool checking "just works" without additional mappings

7. Update Devcontainer files (Optional)

For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:

VS Code Extension-based Agents

For agents available as VS Code extensions, add them to .devcontainer/devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        // ... existing extensions ...
        // [New Agent Name]
        "[New Agent Extension ID]"
      ]
    }
  }
}
CLI-based Agents

For agents that require CLI tools, add installation commands to .devcontainer/post-create.sh:

#!/bin/bash

# Existing installations...

echo -e "\n🤖 Installing [New Agent Name] CLI..."
# run_command "npm install -g [agent-cli-package]@latest" # Example for node-based CLI
# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
echo "✅ Done"

Quick Tips:

  • Extension-based agents: Add to the extensions array in devcontainer.json
  • CLI-based agents: Add installation scripts to post-create.sh
  • Hybrid agents: May require both extension and CLI installation
  • Test thoroughly: Ensure installations work in the devcontainer environment

Agent Categories

CLI-Based Agents

Require a command-line tool to be installed:

  • Claude Code: claude CLI
  • Gemini CLI: gemini CLI
  • Cursor: cursor-agent CLI
  • Qwen Code: qwen CLI
  • opencode: opencode CLI
  • Amazon Q Developer CLI: q CLI
  • CodeBuddy CLI: codebuddy CLI
  • Qoder CLI: qodercli CLI
  • Amp: amp CLI
  • SHAI: shai CLI

IDE-Based Agents

Work within integrated development environments:

  • GitHub Copilot: Built into VS Code/compatible editors
  • Windsurf: Built into Windsurf IDE
  • IBM Bob: Built into IBM Bob IDE

Command File Formats

Markdown Format

Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, SHAI, IBM Bob

Standard format:

---
description: "Command description"
---

Command content with {SCRIPT} and $ARGUMENTS placeholders.

GitHub Copilot Chat Mode format:

---
description: "Command description"
mode: devspark.command-name
---

Command content with {SCRIPT} and $ARGUMENTS placeholders.

TOML Format

Used by: Gemini, Qwen

description = "Command description"

prompt = """
Command content with {SCRIPT} and {{args}} placeholders.
"""

Directory Conventions

  • CLI agents: Usually .<agent-name>/commands/
  • IDE agents: Follow IDE-specific patterns:
    • Copilot: .github/agents/
    • Cursor: .cursor/commands/
    • Windsurf: .windsurf/workflows/

Argument Patterns

Different agents use different argument placeholders:

  • Markdown/prompt-based: $ARGUMENTS
  • TOML-based: {{args}}
  • Script placeholders: {SCRIPT} (replaced with actual script path)
  • Agent placeholders: __AGENT__ (replaced with agent name)

Testing New Agent Integration

  1. Build test: Run package creation script locally
  2. CLI test: Test devspark init --ai <agent> command
  3. File generation: Verify correct directory structure and files
  4. Command validation: Ensure generated commands work with the agent
  5. Context update: Test agent context update scripts

Common Pitfalls

  1. Using shorthand keys instead of actual CLI tool names: Always use the actual executable name as the AGENT_CONFIG key (e.g., "cursor-agent" not "cursor"). This prevents the need for special-case mappings throughout the codebase.
  2. Forgetting update scripts: Both bash and PowerShell scripts must be updated when adding new agents.
  3. Incorrect requires_cli value: Set to True only for agents that actually have CLI tools to check; set to False for IDE-based agents.
  4. Wrong argument format: Use correct placeholder format for each agent type ($ARGUMENTS for Markdown, {{args}} for TOML).
  5. Directory naming: Follow agent-specific conventions exactly (check existing agents for patterns).
  6. Help text inconsistency: Update all user-facing text consistently (help strings, docstrings, README, error messages).

Future Considerations

When adding new agents:

  • Consider the agent's native command/workflow patterns
  • Ensure compatibility with the Spec-Driven Development process
  • Document any special requirements or limitations
  • Update this guide with lessons learned
  • Verify the actual CLI tool name before adding to AGENT_CONFIG

This documentation should be updated whenever new agents are added to maintain accuracy and completeness.