diff --git a/.github/workflows/release-preset-trigger.yml b/.github/workflows/release-preset-trigger.yml new file mode 100644 index 0000000..1f04bae --- /dev/null +++ b/.github/workflows/release-preset-trigger.yml @@ -0,0 +1,75 @@ +name: Release Preset Trigger + +# Manually dispatch with a preset id + version; it validates and pushes a +# `-vX.Y.Z` tag, which fires release-preset.yml. + +on: + workflow_dispatch: + inputs: + preset_id: + description: 'Preset directory name under spec-kit-presets/ (e.g., copilot-sub-agents)' + required: true + type: string + version: + description: 'Version to release (e.g., 1.0.0)' + required: true + type: string + +jobs: + tag-and-release: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Validate inputs + env: + PRESET_ID: ${{ github.event.inputs.preset_id }} + VERSION: ${{ github.event.inputs.version }} + run: | + # Strip optional v prefix + VERSION="${VERSION#v}" + + # Validate version format + if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "Error: Invalid version format '$VERSION'. Must be X.Y.Z" >&2 + exit 1 + fi + + # Validate preset directory exists + if [[ ! -d "spec-kit-presets/$PRESET_ID" ]]; then + echo "Error: Preset directory 'spec-kit-presets/$PRESET_ID' not found" >&2 + exit 1 + fi + + # Validate preset.yml exists + if [[ ! -f "spec-kit-presets/$PRESET_ID/preset.yml" ]]; then + echo "Error: spec-kit-presets/$PRESET_ID/preset.yml not found" >&2 + exit 1 + fi + + TAG="${PRESET_ID}-v${VERSION}" + + # Check if tag already exists + if git rev-parse "$TAG" >/dev/null 2>&1; then + echo "Error: Tag '$TAG' already exists" >&2 + exit 1 + fi + + echo "tag=$TAG" >> "$GITHUB_ENV" + echo "Will create tag: $TAG" + + - name: Configure Git + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + + - name: Create and push tag + run: | + git tag "$tag" + git push origin "$tag" + echo "Pushed tag $tag — release workflow will handle the rest" diff --git a/.github/workflows/release-preset.yml b/.github/workflows/release-preset.yml new file mode 100644 index 0000000..6071e0f --- /dev/null +++ b/.github/workflows/release-preset.yml @@ -0,0 +1,93 @@ +name: Release Preset + +# Pushing a `-vX.Y.Z` tag builds that preset's zip inline and publishes it +# as a release asset — matching the `download_url` entries in +# spec-kit-presets/catalog.json. + +on: + push: + tags: + - '*-v[0-9]+.[0-9]+.[0-9]+' + +jobs: + release: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Parse tag + id: parse + run: | + TAG="${GITHUB_REF#refs/tags/}" + # Extract preset id (everything before the last -vX.Y.Z) + PRESET_ID="${TAG%-v*}" + VERSION="${TAG#*-v}" + + # Validate version format + if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "Error: Invalid version format '$VERSION'" >&2 + exit 1 + fi + + # Validate preset directory exists + if [[ ! -d "spec-kit-presets/$PRESET_ID" ]]; then + echo "Error: Preset directory 'spec-kit-presets/$PRESET_ID' not found" >&2 + exit 1 + fi + + # Validate preset.yml exists + if [[ ! -f "spec-kit-presets/$PRESET_ID/preset.yml" ]]; then + echo "Error: spec-kit-presets/$PRESET_ID/preset.yml not found" >&2 + exit 1 + fi + + echo "tag=$TAG" >> "$GITHUB_OUTPUT" + echo "preset_id=$PRESET_ID" >> "$GITHUB_OUTPUT" + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + echo "Releasing $PRESET_ID v$VERSION" + + - name: Create preset zip + run: | + cd "spec-kit-presets/${{ steps.parse.outputs.preset_id }}" + zip -r "$GITHUB_WORKSPACE/${{ steps.parse.outputs.preset_id }}.zip" . \ + -x '.*' '__pycache__/*' + + - name: Generate release notes + id: notes + run: | + PRESET_ID="${{ steps.parse.outputs.preset_id }}" + VERSION="${{ steps.parse.outputs.version }}" + CHANGELOG="spec-kit-presets/$PRESET_ID/CHANGELOG.md" + + { + echo 'body<> "$GITHUB_OUTPUT" + + - name: Create GitHub Release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PRESET_ID="${{ steps.parse.outputs.preset_id }}" + TAG="${{ steps.parse.outputs.tag }}" + VERSION="${{ steps.parse.outputs.version }}" + + gh release create "$TAG" \ + "$PRESET_ID.zip" \ + --title "$PRESET_ID v$VERSION" \ + --notes "${{ steps.notes.outputs.body }}" diff --git a/AGENTS.md b/AGENTS.md index 1a8c31f..42c9c63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,42 @@ runs the CLI. and automatically on the next session start. This is distinct from this plugin's own skills, which are refreshed with `copilot plugin install` / `/plugin`. +## Spec Kit presets (`spec-kit-presets/`) — keep the plumbing boundary + +`spec-kit-presets/` holds **Copilot-specific Spec Kit presets** — this repo is their +canonical, sole home. Guard the boundary so contributors never conflate the two +toolchains: + +- **Two different consumers.** Copilot plumbing (`plugin.json`, `skills/`, `plugins/`, + `.github/plugin/marketplace.json`) is consumed by the **`copilot plugin`** CLI/App. + Presets are consumed by the **`specify` CLI** (`specify preset add`). They are *not* + Copilot plugins, skills, canvases, or marketplace entries. +- **Isolate, don't scatter.** All preset content — including its `catalog.json` — lives + **inside** `spec-kit-presets/`. Do **not** put a preset `catalog.json` at the repo + root, and do not mix it up with the Copilot marketplace manifest at + `.github/plugin/marketplace.json`. Keep the boundary note in + `spec-kit-presets/README.md`. +- **Naming convention: `copilot-[-]`.** Preset ids (directory, + `preset.yml` `id`, `catalog.json` key) carry a short **`copilot-`** prefix marking + them Copilot-specific (e.g. `copilot-sub-agents`, `copilot-assess-ask-questions`), + and display names lead with **"Copilot"** (e.g. "Copilot Sub-Agent Delegation"). + Do **not** use the full `spec-kit-copilot-*` plugin prefix for preset ids — that + namespace is Copilot plugins (`copilot plugin`), and reusing it here would re-blur + the plumbing boundary and bloat `specify preset add`. +- **Promotion criterion: Copilot-specific only.** A preset belongs here only if it + depends on Copilot's own agent mechanisms (e.g. `copilot-sub-agents` uses the VS Code + `runSubagent` tool / Copilot CLI sub-agents / `.github/agents/`; `copilot-assess-ask-questions` + requires Copilot's interactive `ask_user` tool with no plain-text fallback). + Agent-agnostic presets (generic themes, or workflows tied to an extension rather + than to Copilot's tools) do **not** belong here. Do not import them. +- **Independent versioning & release.** Each preset carries its own `version` in + `preset.yml` and a matching `catalog.json` entry, separate from plugin versions. + Releases are cut by CI (`.github/workflows/release-preset.yml`), which zips the + preset **inline** (no build script) on a pushed `-v` tag; use the + **Release Preset Trigger** workflow to create that tag from a preset id + version. + When revving a preset, bump `preset.yml` + the `catalog.json` entry together + **before** tagging. + ## When revving the core skills plugin 1. Re-enumerate the `specify` CLI surface for the **latest** release diff --git a/README.md b/README.md index 17dada5..8fdd939 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,23 @@ The plugins are independently installable and versioned. Install the core skills the assessment canvas, the bug fix canvas, the spec-driven development canvas, or any combination. +## Spec Kit presets + +This repo also hosts **Copilot-specific Spec Kit presets** under +[`spec-kit-presets/`](spec-kit-presets). These are *not* Copilot plugins — they are +consumed by the **`specify` CLI** (`specify preset add`), and are kept in their own +isolated subtree (with their own `catalog.json`) so Spec Kit plumbing is never +confused with Copilot plugin/marketplace plumbing. + +| Preset | Requires | Why it is Copilot-specific | +| --- | --- | --- | +| [`copilot-sub-agents`](spec-kit-presets/copilot-sub-agents) | Spec Kit `>= 0.2.0` | Uses Copilot delegation — VS Code `runSubagent`, Copilot CLI sub-agents, `.github/agents/` | +| [`copilot-assess-ask-questions`](spec-kit-presets/copilot-assess-ask-questions) | Spec Kit `>= 0.9.0`, `assess` extension | Drives the assess pipeline through Copilot's interactive `ask_user` tool (no plain-text fallback) | + +See [`spec-kit-presets/README.md`](spec-kit-presets/README.md) for the plumbing +boundary, install commands, and versioning. Only Copilot-specific presets are hosted +here; agent-agnostic presets do not belong in this Copilot integration hub. + ## Core skills plugin `spec-kit-copilot` gives Copilot focused skills—one per `specify` command group—so @@ -170,10 +187,10 @@ See this plugin driving Spec-Driven Development end to end with this community-c ```javascript spec-kit-copilot/ -├── plugin.json # Core skills plugin manifest +├── plugin.json # Core skills plugin manifest (Copilot plumbing) ├── README.md ├── .github/plugin/ -│ └── marketplace.json # Marketplace manifest (for distribution) +│ └── marketplace.json # Copilot marketplace manifest (NOT the preset catalog) ├── plugins/ │ ├── spec-kit-copilot-assess/ │ │ ├── plugin.json # Assessment canvas plugin manifest @@ -187,6 +204,11 @@ spec-kit-copilot/ │ ├── plugin.json # Spec-driven development canvas plugin manifest │ └── extensions/ │ └── sdd-canvas/ +├── spec-kit-presets/ # Spec Kit plumbing — consumed by `specify preset add` +│ ├── README.md # plumbing boundary note +│ ├── catalog.json # preset catalog (NOT the Copilot marketplace) +│ ├── copilot-sub-agents/ +│ └── copilot-assess-ask-questions/ └── skills/ ├── speckit-cli-setup/SKILL.md ├── speckit-init/SKILL.md diff --git a/skills/speckit-preset/SKILL.md b/skills/speckit-preset/SKILL.md index 1376695..02c25a8 100644 --- a/skills/speckit-preset/SKILL.md +++ b/skills/speckit-preset/SKILL.md @@ -41,13 +41,19 @@ specify preset remove # Catalogs (sources presets are resolved from) specify preset catalog list -specify preset catalog add +specify preset catalog add --name [--install-allowed] specify preset catalog remove ``` ## Notes - Resolution priority: **lower number = higher precedence** (default `10`). +- **Catalogs are added discovery-only by default.** `specify preset catalog add` + requires `--name` and defaults to `--no-install-allowed`; presets from a + discovery-only catalog can be browsed but not installed (install errors with a + "discovery-only" message). Pass `--install-allowed` to permit installs — only for + catalogs you trust. The `install_allowed` policy lives in the consumer's + `.specify/preset-catalogs.yml`, not in the catalog's own `catalog.json`. - A preset can also be installed at project creation: `specify init --integration copilot --integration-options="--skills" --script sh --preset ` (use `--script ps` on Windows; see the speckit-init skill for the full OS-aware form and diff --git a/spec-kit-presets/README.md b/spec-kit-presets/README.md new file mode 100644 index 0000000..f8e0de4 --- /dev/null +++ b/spec-kit-presets/README.md @@ -0,0 +1,100 @@ +# Spec Kit presets (Copilot-specific) + +> [!IMPORTANT] +> **This directory is Spec Kit plumbing, not Copilot plumbing.** Everything here is +> consumed by the **`specify` CLI** via `specify preset add` — it is *not* a Copilot +> plugin, skill, extension, or marketplace entry. Do not confuse the `catalog.json` +> in this directory with the Copilot marketplace manifest at +> [`.github/plugin/marketplace.json`](../.github/plugin/marketplace.json), and do not +> confuse a preset here with a Copilot plugin under [`plugins/`](../plugins) or a +> skill under [`skills/`](../skills). + +| Plumbing | Consumed by | Lives in | +| --- | --- | --- | +| **Copilot** plugins / skills / canvases | `copilot plugin …` (Copilot CLI & App) | root `plugin.json`, `skills/`, `plugins/`, `.github/plugin/marketplace.json` | +| **Spec Kit** presets (this folder) | `specify preset …` (Spec Kit `specify` CLI) | `spec-kit-presets/` | + +## What lives here + +These are the **Copilot-specific** Spec Kit presets — presets that depend on +**Copilot's own agent mechanisms** rather than being agent-agnostic. This directory is +their canonical home. + +| Preset | Requires | Why it is Copilot-specific | +| --- | --- | --- | +| [`copilot-sub-agents`](copilot-sub-agents) | Spec Kit `>= 0.2.0` | Built around Copilot delegation mechanisms — VS Code's `runSubagent` tool, Copilot CLI sub-agent processes, and custom agents in `.github/agents/` / `~/.copilot/agents/`. | +| [`copilot-assess-ask-questions`](copilot-assess-ask-questions) | Spec Kit `>= 0.9.0`, the `assess` extension | Drives the assess pipeline through Copilot's interactive `ask_user` tool (App, CLI, VS Code). No plain-text fallback — not meant for agents without an interactive question tool. | + +Only Copilot-specific presets belong here. Agent-agnostic presets (generic themes, +extension-specific workflows that don't rely on Copilot's tools) do **not** belong in +this Copilot integration hub. + +## Installing a preset + +**Recommended — register the catalog once, then install by id.** Catalogs are +discovery-only by default, so `--install-allowed` is required to install from them +(and `--name` is required): + +```bash +specify preset catalog add https://raw.githubusercontent.com/github/spec-kit-copilot/main/spec-kit-presets/catalog.json \ + --name spec-kit-copilot --install-allowed + +# then add by id — the normal way: +specify preset add copilot-sub-agents +specify preset add copilot-assess-ask-questions # also: specify extension add assess +``` + +The two methods below are escape hatches, not the primary path: + +- **One-off, without registering a catalog** — install straight from a release zip + (`--from` requires an HTTPS URL): + + ```bash + specify preset add --from https://github.com/github/spec-kit-copilot/releases/download/copilot-sub-agents-v1.0.0/copilot-sub-agents.zip + specify preset add --from https://github.com/github/spec-kit-copilot/releases/download/copilot-assess-ask-questions-v1.0.0/copilot-assess-ask-questions.zip + ``` + +- **Local development only** — install from a working clone of this repo: + + ```bash + specify preset add --dev ./spec-kit-presets/copilot-sub-agents + specify preset add --dev ./spec-kit-presets/copilot-assess-ask-questions + ``` + +## Layout + +```text +spec-kit-presets/ +├── README.md # this file (the plumbing boundary note) +├── catalog.json # Spec Kit preset catalog (NOT the Copilot marketplace) +├── copilot-sub-agents/ +│ ├── preset.yml +│ └── commands/ +└── copilot-assess-ask-questions/ + ├── preset.yml + └── commands/ +``` + +## Versioning & distribution + +Presets are versioned and released **independently** of the Copilot plugins in this +repo. Each preset carries its own `version` in `preset.yml` and its own +`catalog.json` entry. `specify preset add ` (catalog install) resolves a +release-asset zip via each entry's `download_url`, tagged +`-v` (e.g. `copilot-sub-agents-v1.0.0`). + +Releases are cut by CI — there is no local build script. The zip is built **inside** +the release workflow (`.github/workflows/release-preset.yml`) from the preset +directory, so `preset.yml` and `commands/` sit at the archive root. To publish: + +- **Preferred:** run the **Release Preset Trigger** workflow + (`.github/workflows/release-preset-trigger.yml`) via *Actions → Run workflow* with + the preset id and version; it validates, then creates and pushes the + `-v` tag. +- **Or** push the tag yourself (`git tag copilot-sub-agents-v1.0.0 && git push origin + copilot-sub-agents-v1.0.0`). + +Either path fires `release-preset.yml`, which builds the zip and creates the GitHub +release with that asset. When revving a preset, bump its `preset.yml` version and the +matching `catalog.json` entry together **before** tagging. + diff --git a/spec-kit-presets/catalog.json b/spec-kit-presets/catalog.json new file mode 100644 index 0000000..22be294 --- /dev/null +++ b/spec-kit-presets/catalog.json @@ -0,0 +1,59 @@ +{ + "schema_version": "1.0", + "updated_at": "2026-08-06T00:00:00Z", + "catalog_url": "https://raw.githubusercontent.com/github/spec-kit-copilot/main/spec-kit-presets/catalog.json", + "presets": { + "copilot-sub-agents": { + "name": "Copilot Sub-Agent Delegation", + "id": "copilot-sub-agents", + "version": "1.0.0", + "description": "Adds sub-agent delegation instructions to all core Spec Kit commands, enabling parallel execution of independent steps via Copilot sub-agents (CLI and VS Code).", + "author": "mnriem", + "repository": "https://github.com/github/spec-kit-copilot", + "download_url": "https://github.com/github/spec-kit-copilot/releases/download/copilot-sub-agents-v1.0.0/copilot-sub-agents.zip", + "homepage": "https://github.com/github/spec-kit-copilot", + "documentation": "https://github.com/github/spec-kit-copilot/blob/main/spec-kit-presets/copilot-sub-agents/README.md", + "license": "MIT", + "requires": { + "speckit_version": ">=0.2.0" + }, + "provides": { + "templates": 0, + "commands": 8 + }, + "tags": [ + "copilot", + "sub-agents", + "parallelism", + "performance" + ] + }, + "copilot-assess-ask-questions": { + "name": "Copilot Assess Clarifying Questions", + "id": "copilot-assess-ask-questions", + "version": "1.0.0", + "description": "Adds an interactive #askQuestions-style clarifying round to every stage of the assess extension. Before writing each artifact, the agent asks the user a focused batch of multiple-choice clarifying questions via GitHub Copilot's ask_user tool (App, CLI, and VS Code).", + "author": "mnriem", + "repository": "https://github.com/github/spec-kit-copilot", + "download_url": "https://github.com/github/spec-kit-copilot/releases/download/copilot-assess-ask-questions-v1.0.0/copilot-assess-ask-questions.zip", + "homepage": "https://github.com/github/spec-kit-copilot", + "documentation": "https://github.com/github/spec-kit-copilot/blob/main/spec-kit-presets/copilot-assess-ask-questions/README.md", + "license": "MIT", + "requires": { + "speckit_version": ">=0.9.0", + "extensions": ["assess"] + }, + "provides": { + "templates": 0, + "commands": 5 + }, + "tags": [ + "assess", + "clarifying-questions", + "askquestions", + "discovery", + "interactive" + ] + } + } +} diff --git a/spec-kit-presets/copilot-assess-ask-questions/README.md b/spec-kit-presets/copilot-assess-ask-questions/README.md new file mode 100644 index 0000000..b424d47 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/README.md @@ -0,0 +1,120 @@ +# Copilot Assess Clarifying Questions Preset + +A [Spec Kit](https://github.com/github/spec-kit) preset that layers an interactive +**`#askQuestions`-style clarifying round** onto every stage of the +[assess extension](https://github.com/github/spec-kit/tree/main/extensions/assess). + +In VS Code, GitHub Copilot can pause and ask you a focused batch of clarifying +questions *before* it does the work. This preset brings that behavior to the assess +pipeline by driving it through Copilot's interactive **`ask_user`** question tool: +before each stage writes its artifact, the agent asks you targeted multiple-choice +questions and folds your answers into the result — instead of guessing. + +## Built for GitHub Copilot + +This preset is **specific to GitHub Copilot — the App, the CLI, and VS Code** — where the +interactive `ask_user` question tool is always available. It has **no plain-text +fallback**: questions are always presented through the tool as multiple-choice prompts. +It is not meant for agents that lack an interactive question capability. + +## When to Use This Preset + +Use it when you want the assess pipeline to be **conversational and interrogative** — +when you'd rather answer a few sharp multiple-choice questions per stage than review a +draft full of guesses and clarification markers. + +## What It Does + +This preset uses the `wrap` composition strategy to place a **Clarifying Questions +Protocol** around each of the five assess commands. It wraps the core stage so the agent +sees a short **gate at the top** — *"don't write the artifact until you've done the +clarifying round"* — reads the unchanged stage logic in the middle, and finds the **full +`ask_user` protocol at the bottom**. The top primes the pause; the bottom (read last) +carries the detail and the recency that makes the agent actually stop and ask. + +| Command | Questions focus on… | +|---------|---------------------| +| `speckit.assess.intake` | The idea's origin & trigger, its type, the slug, and the boundary of what's proposed (capture only — never evaluates) | +| `speckit.assess.research` | Which evidence lenses matter, sources you can point to, verified-vs-assumption claims, and known counter-evidence | +| `speckit.assess.define` | Primary users & stakeholders, concrete success metrics, non-goals, and the cost of inaction | +| `speckit.assess.shape` | Appetite/budget, hard constraints, whether "do nothing / buy" is on the table, and the trade-off that matters most | +| `speckit.assess.decide` | Relative weight of criteria & any must-pass bar, risk tolerance, strategic context, and which stage to revisit | + +## The Protocol + +Each command is wrapped with the same rules: + +- **Always ask through `ask_user`.** Every question is put to the user with Copilot's + `ask_user` tool as an interactive multiple-choice prompt — never hand-formatted as + chat text. +- **One question per call, up front.** The agent asks up to 3–5 highest-impact questions + for the stage, one at a time, before writing the artifact, and waits for each answer. +- **Concrete choices.** Each question carries 2–4 context-specific options with the + likely one listed first and marked `(Recommended)`. No "Other" catch-all — Copilot + adds a free-text answer automatically. +- **Answers are authoritative.** They're folded straight into the artifact. If you + genuinely don't know, that gap becomes a `[NEEDS CLARIFICATION: …]` marker. No + guardrail is relaxed — path safety, slug rules, the URL Trust Policy, and output + formats all still apply. + +## Prerequisites + +- GitHub Copilot (App, CLI, or VS Code) — the environment providing the `ask_user` tool +- [Spec Kit](https://github.com/github/spec-kit) >= 0.9.0 +- [assess extension](https://github.com/github/spec-kit/tree/main/extensions/assess) installed + +```bash +specify extension add assess +``` + +## Installation + +**Recommended — register the catalog once, then install by id.** Catalogs are +discovery-only by default, so `--install-allowed` (and `--name`) is required: + +```bash +specify preset catalog add https://raw.githubusercontent.com/github/spec-kit-copilot/main/spec-kit-presets/catalog.json \ + --name spec-kit-copilot --install-allowed + +specify extension add assess # this preset requires the assess extension +specify preset add copilot-assess-ask-questions +``` + +The two methods below are escape hatches, not the primary path: + +- **One-off, without registering a catalog** — install straight from the release zip + (`--from` requires an HTTPS URL): + + ```bash + specify preset add --from https://github.com/github/spec-kit-copilot/releases/download/copilot-assess-ask-questions-v1.0.0/copilot-assess-ask-questions.zip + ``` + +- **Local development only** — install from a working clone: + + ```bash + specify preset add --dev ./copilot-assess-ask-questions + ``` + +## Usage + +The workflow is identical to the standard assess pipeline — same five commands, same +order. The preset only changes *how* each command gathers its input: + +```bash +/speckit.assess.intake "Let users work offline and sync when they reconnect" +# → agent asks (via ask_user) about origin, type, slug, boundary; you pick answers; +# intake.md is written + +/speckit.assess.research slug=offline-mode +/speckit.assess.define slug=offline-mode +/speckit.assess.shape slug=offline-mode +/speckit.assess.decide slug=offline-mode +# → on a "go" verdict, hand decision.md to /speckit.specify +``` + +If a stage already has everything it needs, the agent says so and proceeds without +asking. + +## License + +MIT diff --git a/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.decide.md b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.decide.md new file mode 100644 index 0000000..a0dba50 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.decide.md @@ -0,0 +1,41 @@ +> **copilot-assess-ask-questions preset — GitHub Copilot (App, CLI, VS Code).** Gate: **do not write `decision.md` until you have completed the interactive Clarifying Questions round defined at the end of this command.** That round asks the user targeted multiple-choice questions through Copilot's `ask_user` tool — reproducing VS Code's `#askQuestions` — and its answers are required input for `decision.md`. Read the full stage first, run the round, *then* write. + +--- + +{CORE_TEMPLATE} + +--- + +## Clarifying Questions Protocol (copilot-assess-ask-questions preset) + +Now execute the gate flagged at the top of this command. This round runs **before the Execution step above writes `decision.md`** — resolve ambiguity **by asking the user through the `ask_user` tool**. Do not guess, and do not jump straight to `[NEEDS CLARIFICATION: …]` markers without asking first. + +### When to run it + +- Run it **once, up front**: after reading this stage's inputs (the prerequisites and any prior assessment artifacts described above) but **before** you write `decision.md`. +- Ask **only** about gaps that would **materially change** `decision.md`. If everything you need is already unambiguous, say so in one line and proceed — never ask questions for their own sake. + +### How to ask — always use the `ask_user` tool + +- Put every question to the user with the **`ask_user`** tool so it renders as an interactive prompt. Never hand-format questions as plain chat text — the tool is always available on the Copilot App, CLI, and VS Code. +- Ask **one question per `ask_user` call**, and ask at most the **3–5 highest-impact questions** for this stage. +- Give each question a **`choices`** array of **2–4 concrete options** drawn from the actual context. List the most likely option **first** and suffix it with **`(Recommended)`** when you have a basis for one. +- **Do not** add an "Other" / "Something else" catch-all option — Copilot automatically offers a free-text answer alongside the choices. +- Keep each question **closed and decision-shaped**: every answer must change what you write. +- Ask the questions one at a time and **wait** for each answer before moving on. + +### After the answers + +- Treat the answers as **authoritative input** and fold them directly into `decision.md`. +- If the user genuinely does not know an answer, record that gap as a `[NEEDS CLARIFICATION: …]` marker in `decision.md` — never invent an answer to fill it. +- Do **not** re-ask anything the user already answered earlier in this session; reuse those answers. +- Everything in the stage above (path safety, slug resolution, URL Trust Policy, output format, and guardrails) still applies **unchanged** — this round only gathers input; it never relaxes a guardrail. + +### What to ask about at the `decide` stage + +- The **relative weight** of the scoring criteria, and any **must-pass bar** — a single criterion whose failure alone should force a `kill`. +- The team's **risk tolerance** for this specific idea. +- Any **strategic context** not already captured in the artifacts — roadmap fit, timing, or who owns the go/kill call. +- If the evidence is trending toward **needs-clarification**, which earlier stage (intake / research / define / shape) the user wants to revisit. + +The round only surfaces the judgment context; the verdict rules are unchanged — a `go` still requires a valid problem, `adequate`+ evidence, and a shaped concept, or it is honestly downgraded to `needs-clarification`. diff --git a/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.define.md b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.define.md new file mode 100644 index 0000000..292797e --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.define.md @@ -0,0 +1,41 @@ +> **copilot-assess-ask-questions preset — GitHub Copilot (App, CLI, VS Code).** Gate: **do not write `problem.md` until you have completed the interactive Clarifying Questions round defined at the end of this command.** That round asks the user targeted multiple-choice questions through Copilot's `ask_user` tool — reproducing VS Code's `#askQuestions` — and its answers are required input for `problem.md`. Read the full stage first, run the round, *then* write. + +--- + +{CORE_TEMPLATE} + +--- + +## Clarifying Questions Protocol (copilot-assess-ask-questions preset) + +Now execute the gate flagged at the top of this command. This round runs **before the Execution step above writes `problem.md`** — resolve ambiguity **by asking the user through the `ask_user` tool**. Do not guess, and do not jump straight to `[NEEDS CLARIFICATION: …]` markers without asking first. + +### When to run it + +- Run it **once, up front**: after reading this stage's inputs (the prerequisites and any prior assessment artifacts described above) but **before** you write `problem.md`. +- Ask **only** about gaps that would **materially change** `problem.md`. If everything you need is already unambiguous, say so in one line and proceed — never ask questions for their own sake. + +### How to ask — always use the `ask_user` tool + +- Put every question to the user with the **`ask_user`** tool so it renders as an interactive prompt. Never hand-format questions as plain chat text — the tool is always available on the Copilot App, CLI, and VS Code. +- Ask **one question per `ask_user` call**, and ask at most the **3–5 highest-impact questions** for this stage. +- Give each question a **`choices`** array of **2–4 concrete options** drawn from the actual context. List the most likely option **first** and suffix it with **`(Recommended)`** when you have a basis for one. +- **Do not** add an "Other" / "Something else" catch-all option — Copilot automatically offers a free-text answer alongside the choices. +- Keep each question **closed and decision-shaped**: every answer must change what you write. +- Ask the questions one at a time and **wait** for each answer before moving on. + +### After the answers + +- Treat the answers as **authoritative input** and fold them directly into `problem.md`. +- If the user genuinely does not know an answer, record that gap as a `[NEEDS CLARIFICATION: …]` marker in `problem.md` — never invent an answer to fill it. +- Do **not** re-ask anything the user already answered earlier in this session; reuse those answers. +- Everything in the stage above (path safety, slug resolution, URL Trust Policy, output format, and guardrails) still applies **unchanged** — this round only gathers input; it never relaxes a guardrail. + +### What to ask about at the `define` stage + +- Who the **primary affected users and stakeholders** are (users experience the problem; stakeholders decide, fund, or are impacted). +- What **success concretely looks like** — which measurable signals or metrics, and their current baseline if known. +- Explicit **non-goals / boundaries** to bound the work and prevent scope creep. +- The **cost of inaction** — what happens, and how urgent it is, if nothing is built. + +Keep every question in the **problem space** — no features, APIs, or architecture. If the idea arrived as a solution, ask what underlying problem it is meant to solve. diff --git a/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.intake.md b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.intake.md new file mode 100644 index 0000000..40edea9 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.intake.md @@ -0,0 +1,41 @@ +> **copilot-assess-ask-questions preset — GitHub Copilot (App, CLI, VS Code).** Gate: **do not write `intake.md` until you have completed the interactive Clarifying Questions round defined at the end of this command.** That round asks the user targeted multiple-choice questions through Copilot's `ask_user` tool — reproducing VS Code's `#askQuestions` — and its answers are required input for `intake.md`. Read the full stage first, run the round, *then* write. + +--- + +{CORE_TEMPLATE} + +--- + +## Clarifying Questions Protocol (copilot-assess-ask-questions preset) + +Now execute the gate flagged at the top of this command. This round runs **before the Execution step above writes `intake.md`** — resolve ambiguity **by asking the user through the `ask_user` tool**. Do not guess, and do not jump straight to `[NEEDS CLARIFICATION: …]` markers without asking first. + +### When to run it + +- Run it **once, up front**: after reading this stage's inputs (the prerequisites and any prior assessment artifacts described above) but **before** you write `intake.md`. +- Ask **only** about gaps that would **materially change** `intake.md`. If everything you need is already unambiguous, say so in one line and proceed — never ask questions for their own sake. + +### How to ask — always use the `ask_user` tool + +- Put every question to the user with the **`ask_user`** tool so it renders as an interactive prompt. Never hand-format questions as plain chat text — the tool is always available on the Copilot App, CLI, and VS Code. +- Ask **one question per `ask_user` call**, and ask at most the **3–5 highest-impact questions** for this stage. +- Give each question a **`choices`** array of **2–4 concrete options** drawn from the actual context. List the most likely option **first** and suffix it with **`(Recommended)`** when you have a basis for one. +- **Do not** add an "Other" / "Something else" catch-all option — Copilot automatically offers a free-text answer alongside the choices. +- Keep each question **closed and decision-shaped**: every answer must change what you write. +- Ask the questions one at a time and **wait** for each answer before moving on. + +### After the answers + +- Treat the answers as **authoritative input** and fold them directly into `intake.md`. +- If the user genuinely does not know an answer, record that gap as a `[NEEDS CLARIFICATION: …]` marker in `intake.md` — never invent an answer to fill it. +- Do **not** re-ask anything the user already answered earlier in this session; reuse those answers. +- Everything in the stage above (path safety, slug resolution, URL Trust Policy, output format, and guardrails) still applies **unchanged** — this round only gathers input; it never relaxes a guardrail. + +### What to ask about at the `intake` stage + +- The idea's **origin and trigger** — who raised it and what prompted it *now* (a complaint, outage, sales ask, strategy shift). +- The **idea type** when the input does not make it obvious — new-capability / improvement / fix / exploration / cost-saving / compliance / other. +- The **slug** to file the idea under, if one was not supplied — offer a 2–4 word kebab-case default derived from the idea. +- The **boundary of what is being proposed** — which parts of the stated idea are in vs. out — captured verbatim. + +Keep every question about **what the idea is and where it came from**. Intake captures; it does not evaluate, size, or solutionize — never ask whether the idea is a good one here. diff --git a/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.research.md b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.research.md new file mode 100644 index 0000000..6297fe0 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.research.md @@ -0,0 +1,41 @@ +> **copilot-assess-ask-questions preset — GitHub Copilot (App, CLI, VS Code).** Gate: **do not write `research.md` until you have completed the interactive Clarifying Questions round defined at the end of this command.** That round asks the user targeted multiple-choice questions through Copilot's `ask_user` tool — reproducing VS Code's `#askQuestions` — and its answers are required input for `research.md`. Read the full stage first, run the round, *then* write. + +--- + +{CORE_TEMPLATE} + +--- + +## Clarifying Questions Protocol (copilot-assess-ask-questions preset) + +Now execute the gate flagged at the top of this command. This round runs **before the Execution step above writes `research.md`** — resolve ambiguity **by asking the user through the `ask_user` tool**. Do not guess, and do not jump straight to `[NEEDS CLARIFICATION: …]` markers without asking first. + +### When to run it + +- Run it **once, up front**: after reading this stage's inputs (the prerequisites and any prior assessment artifacts described above) but **before** you write `research.md`. +- Ask **only** about gaps that would **materially change** `research.md`. If everything you need is already unambiguous, say so in one line and proceed — never ask questions for their own sake. + +### How to ask — always use the `ask_user` tool + +- Put every question to the user with the **`ask_user`** tool so it renders as an interactive prompt. Never hand-format questions as plain chat text — the tool is always available on the Copilot App, CLI, and VS Code. +- Ask **one question per `ask_user` call**, and ask at most the **3–5 highest-impact questions** for this stage. +- Give each question a **`choices`** array of **2–4 concrete options** drawn from the actual context. List the most likely option **first** and suffix it with **`(Recommended)`** when you have a basis for one. +- **Do not** add an "Other" / "Something else" catch-all option — Copilot automatically offers a free-text answer alongside the choices. +- Keep each question **closed and decision-shaped**: every answer must change what you write. +- Ask the questions one at a time and **wait** for each answer before moving on. + +### After the answers + +- Treat the answers as **authoritative input** and fold them directly into `research.md`. +- If the user genuinely does not know an answer, record that gap as a `[NEEDS CLARIFICATION: …]` marker in `research.md` — never invent an answer to fill it. +- Do **not** re-ask anything the user already answered earlier in this session; reuse those answers. +- Everything in the stage above (path safety, slug resolution, URL Trust Policy, output format, and guardrails) still applies **unchanged** — this round only gathers input; it never relaxes a guardrail. + +### What to ask about at the `research` stage + +- Which **evidence lenses** matter most for this idea — users & demand / prior art / market & context / data & constraints. +- **Sources the user can point you to** — internal tickets, dashboards, analytics, competitor products, or prior specs/decisions in `.specify/`. +- Which existing claims the user already treats as **verified** vs. **assumptions** (so you tag confidence honestly). +- The **strongest reason against** the idea that the user is already aware of — this feeds the mandatory *Evidence Against the Idea* section. + +Ask only to aim the evidence-gathering; research still **cites or flags every claim** and never decides the idea's fate. diff --git a/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.shape.md b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.shape.md new file mode 100644 index 0000000..d26a369 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/commands/speckit.assess.shape.md @@ -0,0 +1,41 @@ +> **copilot-assess-ask-questions preset — GitHub Copilot (App, CLI, VS Code).** Gate: **do not write `concept.md` until you have completed the interactive Clarifying Questions round defined at the end of this command.** That round asks the user targeted multiple-choice questions through Copilot's `ask_user` tool — reproducing VS Code's `#askQuestions` — and its answers are required input for `concept.md`. Read the full stage first, run the round, *then* write. + +--- + +{CORE_TEMPLATE} + +--- + +## Clarifying Questions Protocol (copilot-assess-ask-questions preset) + +Now execute the gate flagged at the top of this command. This round runs **before the Execution step above writes `concept.md`** — resolve ambiguity **by asking the user through the `ask_user` tool**. Do not guess, and do not jump straight to `[NEEDS CLARIFICATION: …]` markers without asking first. + +### When to run it + +- Run it **once, up front**: after reading this stage's inputs (the prerequisites and any prior assessment artifacts described above) but **before** you write `concept.md`. +- Ask **only** about gaps that would **materially change** `concept.md`. If everything you need is already unambiguous, say so in one line and proceed — never ask questions for their own sake. + +### How to ask — always use the `ask_user` tool + +- Put every question to the user with the **`ask_user`** tool so it renders as an interactive prompt. Never hand-format questions as plain chat text — the tool is always available on the Copilot App, CLI, and VS Code. +- Ask **one question per `ask_user` call**, and ask at most the **3–5 highest-impact questions** for this stage. +- Give each question a **`choices`** array of **2–4 concrete options** drawn from the actual context. List the most likely option **first** and suffix it with **`(Recommended)`** when you have a basis for one. +- **Do not** add an "Other" / "Something else" catch-all option — Copilot automatically offers a free-text answer alongside the choices. +- Keep each question **closed and decision-shaped**: every answer must change what you write. +- Ask the questions one at a time and **wait** for each answer before moving on. + +### After the answers + +- Treat the answers as **authoritative input** and fold them directly into `concept.md`. +- If the user genuinely does not know an answer, record that gap as a `[NEEDS CLARIFICATION: …]` marker in `concept.md` — never invent an answer to fill it. +- Do **not** re-ask anything the user already answered earlier in this session; reuse those answers. +- Everything in the stage above (path safety, slug resolution, URL Trust Policy, output format, and guardrails) still applies **unchanged** — this round only gathers input; it never relaxes a guardrail. + +### What to ask about at the `shape` stage + +- The **appetite / budget** the team is willing to spend — small (days) / medium (weeks) / large (months) — treated as a budget, not an estimate. +- **Hard constraints** every option must respect — technology, compliance, timeline, or existing systems. +- Whether a **"do nothing / buy instead of build"** option should be on the table. +- Which **trade-off matters most** — e.g. speed vs. completeness, reversibility vs. reach, or lowest risk vs. highest upside. + +Questions stay at the **concept level** — they shape options and appetite, never a spec, architecture, data model, or task breakdown. diff --git a/spec-kit-presets/copilot-assess-ask-questions/preset.yml b/spec-kit-presets/copilot-assess-ask-questions/preset.yml new file mode 100644 index 0000000..ad97467 --- /dev/null +++ b/spec-kit-presets/copilot-assess-ask-questions/preset.yml @@ -0,0 +1,59 @@ +schema_version: "1.0" + +preset: + id: "copilot-assess-ask-questions" + name: "Copilot Assess Clarifying Questions" + version: "1.0.0" + description: "Adds an interactive #askQuestions-style clarifying round to every stage of the assess extension. Before writing each artifact, the agent asks the user multiple-choice clarifying questions via GitHub Copilot's ask_user tool (App, CLI, and VS Code)." + author: "mnriem" + repository: "https://github.com/github/spec-kit-copilot" + license: "MIT" + +requires: + speckit_version: ">=0.9.0" + extensions: + - assess + +provides: + templates: + - type: "command" + name: "speckit.assess.intake" + file: "commands/speckit.assess.intake.md" + description: "Wrap the stage with an #askQuestions-style clarifying round (ask_user) about the idea's origin, type, slug, and boundary before writing intake.md" + replaces: "speckit.assess.intake" + strategy: "wrap" + + - type: "command" + name: "speckit.assess.research" + file: "commands/speckit.assess.research.md" + description: "Wrap the stage with an #askQuestions-style clarifying round (ask_user) about evidence lenses, sources, and known counter-evidence before writing research.md" + replaces: "speckit.assess.research" + strategy: "wrap" + + - type: "command" + name: "speckit.assess.define" + file: "commands/speckit.assess.define.md" + description: "Wrap the stage with an #askQuestions-style clarifying round (ask_user) about users, success metrics, non-goals, and cost of inaction before writing problem.md" + replaces: "speckit.assess.define" + strategy: "wrap" + + - type: "command" + name: "speckit.assess.shape" + file: "commands/speckit.assess.shape.md" + description: "Wrap the stage with an #askQuestions-style clarifying round (ask_user) about appetite, constraints, and trade-offs before writing concept.md" + replaces: "speckit.assess.shape" + strategy: "wrap" + + - type: "command" + name: "speckit.assess.decide" + file: "commands/speckit.assess.decide.md" + description: "Wrap the stage with an #askQuestions-style clarifying round (ask_user) about criteria weight, risk tolerance, and strategic context before writing decision.md" + replaces: "speckit.assess.decide" + strategy: "wrap" + +tags: + - "assess" + - "clarifying-questions" + - "askquestions" + - "discovery" + - "interactive" diff --git a/spec-kit-presets/copilot-sub-agents/README.md b/spec-kit-presets/copilot-sub-agents/README.md new file mode 100644 index 0000000..cfb9296 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/README.md @@ -0,0 +1,58 @@ +# Copilot Sub-Agent Delegation + +A Spec Kit preset that adds sub-agent delegation instructions to all core commands, enabling parallel execution of independent steps when using GitHub Copilot. + +## What It Does + +This preset uses the `prepend` composition strategy to inject sub-agent delegation instructions at the top of each core Spec Kit command. When Copilot processes a command, it sees the delegation instructions first and can dispatch independent work items to parallel sub-agents. + +## Compatibility + +The instructions call out the specific Copilot mechanism per environment: + +- **VS Code Copilot**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context +- **Copilot CLI**: Delegate to a subsidiary sub-agent process — Copilot CLI automatically manages sub-agent execution, and can target custom agents defined in `.github/agents/` or `~/.copilot/agents/` + +## Parallelism by Command + +| Command | What Runs in Parallel | +|---------|----------------------| +| **plan** | Phase 0 research tasks (each unknown independently); Phase 1 artifacts (data-model, contracts, quickstart) | +| **implement** | All tasks marked `[P]` within the same phase; context loading | +| **analyze** | Six detection passes (Duplication, Ambiguity, Underspecification, Constitution, Coverage, Inconsistency) | +| **tasks** | Document loading; per-user-story task generation | + +| **taskstoissues** | GitHub issue creation (batches of 5) | +| **specify** | Quality validation checklist generation | +| **checklist** | Feature context loading (spec, plan, tasks) | +| **clarify** | Ambiguity scan categories (functional/domain, quality/integration, UX/edge cases) | + +## Installation + +```bash +specify preset add copilot-sub-agents +``` + +## Requirements + +- Spec Kit >= 0.2.0 +- GitHub Copilot (CLI or VS Code) with sub-agent support + +## How It Works + +Each command file contains only the sub-agent delegation instructions. The `prepend` strategy places these instructions before the core command content, so the agent sees them first and knows which steps to parallelize. + +The core command logic is unchanged — the preset only adds guidance for _how_ to execute existing steps more efficiently. + +## Example + +When running `speckit.plan`, instead of sequentially researching each unknown in Technical Context, the agent will: + +1. Identify all `NEEDS CLARIFICATION` items +2. Dispatch a `runSubagent` call for each one in parallel +3. Collect results and consolidate into `research.md` +4. Then dispatch parallel sub-agents for `data-model.md`, `contracts/`, and `quickstart.md` + +## License + +MIT diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.analyze.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.analyze.md new file mode 100644 index 0000000..5a05ec5 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.analyze.md @@ -0,0 +1,26 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Parallel Detection Passes + +After loading artifacts and building semantic models, dispatch each detection pass as a **separate sub-agent**. All six passes are independent and can run in parallel: + +1. **Sub-agent: Duplication Detection** — "Analyze these artifacts for near-duplicate requirements. Identify lower-quality phrasings for consolidation. Artifacts: {spec summary}, {plan summary}, {tasks summary}. Return findings as rows: ID, Severity, Location(s), Summary, Recommendation." + +2. **Sub-agent: Ambiguity Detection** — "Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria and unresolved placeholders (TODO, TKTK, ???). Artifacts: {spec summary}, {plan summary}, {tasks summary}. Return findings as rows." + +3. **Sub-agent: Underspecification** — "Find requirements with verbs but missing objects or measurable outcomes, user stories missing acceptance criteria, and tasks referencing undefined components. Artifacts: {spec summary}, {plan summary}, {tasks summary}. Return findings as rows." + +4. **Sub-agent: Constitution Alignment** — "Check all requirements and plan elements against constitution principles. Flag any conflicts with MUST principles. Constitution: {constitution content}. Artifacts: {spec summary}, {plan summary}, {tasks summary}. Return findings as rows." + +5. **Sub-agent: Coverage Gaps** — "Identify requirements with zero associated tasks, tasks with no mapped requirement/story, and success criteria requiring buildable work not reflected in tasks. Requirements inventory: {inventory}. Task coverage mapping: {mapping}. Return findings as rows." + +6. **Sub-agent: Inconsistency** — "Detect terminology drift, data entities referenced in plan but absent in spec (or vice versa), task ordering contradictions, and conflicting requirements. Artifacts: {spec summary}, {plan summary}, {tasks summary}. Return findings as rows." + +Collect all sub-agent results, assign severities, and merge into the unified analysis report. Cap at 50 total findings. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.checklist.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.checklist.md new file mode 100644 index 0000000..3629761 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.checklist.md @@ -0,0 +1,18 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Feature Context Loading in Parallel + +When loading feature context (step 4), dispatch parallel reads: + +1. **Sub-agent: Spec analysis** — "Read spec.md at {FEATURE_DIR}/spec.md. Extract requirements, user stories, edge cases, and non-functional attributes relevant to the checklist domain: '{domain}'. Return a structured summary focused on requirement quality signals." + +2. **Sub-agent: Plan and tasks analysis** — "Read plan.md and tasks.md at {FEATURE_DIR}/ (if they exist). Extract technical details, dependencies, and implementation tasks relevant to the checklist domain: '{domain}'. Return a structured summary." + +Use the consolidated results to generate higher-quality, context-aware checklist items. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.clarify.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.clarify.md new file mode 100644 index 0000000..8937773 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.clarify.md @@ -0,0 +1,20 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Parallel Ambiguity Scan + +When performing the structured ambiguity & coverage scan (step 2), dispatch independent scan categories as parallel sub-agents: + +1. **Sub-agent: Functional & Domain scan** — "Analyze the spec for ambiguity in: Functional Scope & Behavior (core goals, out-of-scope, user roles) and Domain & Data Model (entities, identity rules, state transitions, scale). Mark each category Clear/Partial/Missing. Return the coverage map and candidate questions." + +2. **Sub-agent: Quality & Integration scan** — "Analyze the spec for ambiguity in: Non-Functional Quality Attributes (performance, scalability, reliability, observability, security, compliance) and Integration & External Dependencies (external services, data formats, protocols). Mark each category Clear/Partial/Missing. Return the coverage map and candidate questions." + +3. **Sub-agent: UX & Edge Cases scan** — "Analyze the spec for ambiguity in: Interaction & UX Flow (user journeys, error/loading states, a11y), Edge Cases & Failure Handling (negative scenarios, rate limiting, conflicts), Constraints & Tradeoffs, Terminology & Consistency, and Completion Signals. Mark each category Clear/Partial/Missing. Return the coverage map and candidate questions." + +Merge the coverage maps from all sub-agents and prioritize the combined candidate questions into the final queue of up to 5 questions. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.implement.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.implement.md new file mode 100644 index 0000000..b478d70 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.implement.md @@ -0,0 +1,32 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Parallel Task Execution + +When processing tasks within a phase, identify all tasks marked with `[P]` (parallel-safe). Dispatch each parallel-safe task as a **separate sub-agent**: + +- For each `[P]` task in the current phase: + → Sub-agent: "Implement task {TaskID}: {description}. Context: {relevant plan/spec excerpts}. File path: {target file}. Return: confirmation of completion, files created/modified, and any issues encountered." + +**Rules for sub-agent dispatch:** + +- Only dispatch tasks within the **same phase** — never cross phase boundaries +- Sequential tasks (without `[P]`) must run in the main agent, in order +- If a parallel task depends on a sequential task in the same phase, wait for the sequential task first +- After all sub-agents for a phase complete, **verify results** in the main agent before moving to the next phase +- Mark each completed task as `[X]` in tasks.md after verifying the sub-agent's output + +### Context Loading in Parallel + +When loading implementation context (step 3), dispatch parallel reads: + +1. **Sub-agent: Load plan context** — "Read plan.md and extract tech stack, architecture decisions, and file structure. Return a structured summary." +2. **Sub-agent: Load supporting docs** — "Read data-model.md, contracts/, research.md, and quickstart.md (whichever exist). Return a consolidated context summary." + +Use the consolidated results to inform implementation. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.plan.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.plan.md new file mode 100644 index 0000000..91c03f3 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.plan.md @@ -0,0 +1,30 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Phase 0 — Research in Parallel + +When generating research tasks for unknowns in Technical Context, dispatch each research topic as a **separate sub-agent**: + +- For each NEEDS CLARIFICATION item in Technical Context: + → Sub-agent: "Research {unknown} for {feature context}. Return: Decision, Rationale, Alternatives considered." + +- For each technology choice needing best-practices review: + → Sub-agent: "Find best practices for {tech} in {domain}. Return: recommended patterns, pitfalls, configuration guidance." + +Launch all research sub-agents in parallel, then consolidate their results into `research.md`. + +### Phase 1 — Design Artifacts in Parallel + +After research.md is complete, generate these artifacts via parallel sub-agents: + +1. **Sub-agent: Data Model** — "Extract entities from the feature spec and research findings. Generate `data-model.md` with entity names, fields, relationships, validation rules, and state transitions." +2. **Sub-agent: Interface Contracts** — "Define interface contracts for the project based on the spec and research. Generate files under `contracts/` documenting exposed interfaces." +3. **Sub-agent: Quickstart** — "Create `quickstart.md` with integration scenarios and getting-started guidance based on the spec, data model, and contracts." + +Wait for all three to complete, then proceed to agent context update and constitution re-evaluation. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.specify.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.specify.md new file mode 100644 index 0000000..7e6ca57 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.specify.md @@ -0,0 +1,16 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Spec Quality Validation + +After writing the specification to SPEC_FILE (step 6), dispatch the quality validation as a sub-agent while the main agent prepares the completion report: + +- **Sub-agent: Quality Validation** — "Validate the specification at {SPEC_FILE} against these quality criteria: no implementation details, focused on user value, testable requirements, measurable success criteria, all scenarios defined, edge cases identified, scope bounded. Generate a checklist at {FEATURE_DIR}/checklists/requirements.md. Return: pass/fail status for each item and specific issues found." + +If the sub-agent reports failures, address them in the main agent before finalizing. diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.tasks.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.tasks.md new file mode 100644 index 0000000..60bb331 --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.tasks.md @@ -0,0 +1,27 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Document Loading in Parallel + +When loading design documents (step 2), dispatch parallel reads for all available documents: + +1. **Sub-agent: Core docs** — "Read plan.md and spec.md. Extract tech stack, libraries, project structure, user stories with priorities (P1, P2, P3). Return structured summaries of both." +2. **Sub-agent: Supporting docs** — "Read data-model.md, contracts/, research.md, and quickstart.md (whichever exist under {FEATURE_DIR}). Extract entities, interface contracts, technical decisions, and test scenarios. Return a consolidated summary." + +### Per-User-Story Task Generation + +After loading all documents, generate tasks for independent user stories in parallel: + +- For each user story (P1, P2, P3, ...) from spec.md: + → Sub-agent: "Generate implementation tasks for User Story {N}: '{story title}'. Tech stack: {from plan.md}. Related entities: {from data-model.md if applicable}. Related contracts: {from contracts/ if applicable}. Follow the strict checklist format: - [ ] [TaskID] [P?] [USN] Description with file path. Return: ordered task list with dependency notes and parallel markers." + +Collect all sub-agent results, then: +- Assign sequential Task IDs (T001, T002, ...) across all phases +- Resolve cross-story dependencies +- Assemble into the final tasks.md using the template structure diff --git a/spec-kit-presets/copilot-sub-agents/commands/speckit.taskstoissues.md b/spec-kit-presets/copilot-sub-agents/commands/speckit.taskstoissues.md new file mode 100644 index 0000000..cf0b10f --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/commands/speckit.taskstoissues.md @@ -0,0 +1,19 @@ +## Sub-Agent Delegation + +When executing this command, delegate independent work to parallel sub-agents to reduce total execution time. + +**How to dispatch sub-agents in Copilot:** + +- **VS Code**: Use the `runSubagent` tool to spawn each sub-agent in an isolated context. +- **CLI**: Delegate to a sub-agent process — Copilot CLI automatically manages subsidiary sub-agent execution. You can also target custom agents defined in `.github/agents/` or `~/.copilot/agents/`. + +### Parallel Issue Creation + +After parsing the tasks file and validating the GitHub remote, dispatch issue creation in parallel batches: + +- For each task in tasks.md: + → Sub-agent: "Create a GitHub issue in {owner}/{repo} for task {TaskID}: '{description}'. Phase: {phase name}. Dependencies: {dependency list if any}. Parallel marker: {yes/no}. Use the GitHub MCP server (issue_write tool). Return: issue number and URL." + +**Batch size**: Dispatch up to 5 sub-agents at a time to avoid rate limiting. Wait for each batch to complete before dispatching the next. + +Collect all sub-agent results and report the created issues with their numbers and URLs. diff --git a/spec-kit-presets/copilot-sub-agents/preset.yml b/spec-kit-presets/copilot-sub-agents/preset.yml new file mode 100644 index 0000000..a7c270a --- /dev/null +++ b/spec-kit-presets/copilot-sub-agents/preset.yml @@ -0,0 +1,77 @@ +schema_version: "1.0" + +preset: + id: "copilot-sub-agents" + name: "Copilot Sub-Agent Delegation" + version: "1.0.0" + description: "Adds sub-agent delegation instructions to all core Spec Kit commands, enabling parallel execution of independent steps via Copilot sub-agents (CLI and VS Code)." + author: "mnriem" + repository: "https://github.com/github/spec-kit-copilot" + license: "MIT" + +requires: + speckit_version: ">=0.2.0" + +provides: + templates: + - type: "command" + name: "speckit.specify" + file: "commands/speckit.specify.md" + description: "Prepend sub-agent delegation for spec quality validation" + replaces: "speckit.specify" + strategy: "prepend" + + - type: "command" + name: "speckit.plan" + file: "commands/speckit.plan.md" + description: "Prepend sub-agent delegation for parallel research and design artifact generation" + replaces: "speckit.plan" + strategy: "prepend" + + - type: "command" + name: "speckit.tasks" + file: "commands/speckit.tasks.md" + description: "Prepend sub-agent delegation for parallel document loading and per-user-story task generation" + replaces: "speckit.tasks" + strategy: "prepend" + + - type: "command" + name: "speckit.implement" + file: "commands/speckit.implement.md" + description: "Prepend sub-agent delegation for parallel [P] task execution" + replaces: "speckit.implement" + strategy: "prepend" + + - type: "command" + name: "speckit.analyze" + file: "commands/speckit.analyze.md" + description: "Prepend sub-agent delegation for parallel detection passes" + replaces: "speckit.analyze" + strategy: "prepend" + + - type: "command" + name: "speckit.checklist" + file: "commands/speckit.checklist.md" + description: "Prepend sub-agent delegation for parallel context loading" + replaces: "speckit.checklist" + strategy: "prepend" + + - type: "command" + name: "speckit.clarify" + file: "commands/speckit.clarify.md" + description: "Prepend sub-agent delegation for parallel ambiguity scan categories" + replaces: "speckit.clarify" + strategy: "prepend" + + - type: "command" + name: "speckit.taskstoissues" + file: "commands/speckit.taskstoissues.md" + description: "Prepend sub-agent delegation for parallel GitHub issue creation" + replaces: "speckit.taskstoissues" + strategy: "prepend" + +tags: + - "copilot" + - "sub-agents" + - "parallelism" + - "performance"