From 11ba51537d76708a67898277130a18c3c8a3021f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 16 Jun 2026 15:39:42 +0000 Subject: [PATCH] fix: add missing Copilot converge artifacts --- .github/agents/speckit.converge.agent.md | 253 +++++++++++++++++++++ .github/prompts/speckit.converge.prompt.md | 3 + specs/001-converge-command/research.md | 5 +- 3 files changed, 259 insertions(+), 2 deletions(-) create mode 100644 .github/agents/speckit.converge.agent.md create mode 100644 .github/prompts/speckit.converge.prompt.md diff --git a/.github/agents/speckit.converge.agent.md b/.github/agents/speckit.converge.agent.md new file mode 100644 index 000000000..c435d532b --- /dev/null +++ b/.github/agents/speckit.converge.agent.md @@ -0,0 +1,253 @@ +--- +description: Assess the current codebase against the feature's spec, plan, and tasks, then append any remaining unbuilt work as new tasks to tasks.md so implement can complete it. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Pre-Execution Checks + +**Check for extension hooks (before convergence)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_converge` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Goal. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently + +## Goal + +Close the gap between what a feature's specification, plan, and tasks call for and what the +codebase currently implements. Read `spec.md`, `plan.md`, and `tasks.md` as the **sole +source of intent** (with the constitution as governing constraints), assess the current +state of the code, determine which requirements, acceptance criteria, plan decisions, and +existing tasks are unmet, incomplete, or only partially satisfied, and **append each piece +of remaining work as a new, traceable task** at the bottom of `tasks.md` so that +`/speckit.implement` can complete it. This command MUST run only after +`/speckit.tasks` has produced a complete `tasks.md`. + +This is **not** a diff tool and does **not** track changes. It assesses the present state +of the code relative to the feature's artifacts — no git, no branch comparison, no history. + +## Operating Constraints + +**APPEND-ONLY, NEVER REWRITE**: The command's **only** write is appending a new +`## Phase N — Convergence` section to `tasks.md`. It MUST NOT: + +- modify `spec.md` or `plan.md` in any way; +- rewrite, renumber, reorder, or delete any existing task (including tasks from a prior + Convergence phase); +- modify, create, or delete any application code — completing the appended tasks is the + job of `/speckit.implement`. + +When the codebase already satisfies everything, the command MUST leave `tasks.md` +**byte-for-byte unchanged** (no empty Convergence header) and report a clean result. + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is +**non-negotiable**. Code that violates a MUST principle is the highest-severity finding and +produces a corresponding remediation task. If the constitution is an unfilled template, +skip constitution checks gracefully rather than failing. + +## Execution Steps + +### 1. Initialize Convergence Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md +- CONSTITUTION = `.specify/memory/constitution.md` (if present) +If `plan.md` or `tasks.md` is missing, STOP with a clear, actionable message naming the +prerequisite command to run (`/speckit.plan` for a missing plan, +`/speckit.tasks` for missing tasks). Do not produce partial output. +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Functional Requirements (FR-###) +- Success Criteria (SC-###) — include only items requiring buildable work; exclude + post-launch outcome metrics and business KPIs +- User Stories and their Acceptance Scenarios +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices and technical decisions +- Data Model references +- Phases and named touch-points (files/components the plan says will be created or edited) +- Technical constraints + +**From tasks.md:** + +- Task IDs (to compute the next ID and next phase number) +- Descriptions, phase grouping, and referenced file paths + +**From constitution (if not an unfilled template):** + +- Principle names and MUST/SHOULD normative statements + +### 3. Build the Intent Inventory + +Create an internal model (do not echo raw artifacts): + +- **Requirements inventory**: one stable key per FR-### / SC-### / user-story acceptance + scenario (e.g. `US1/AC2`), plus the plan decisions and constitution principles that + impose buildable obligations. +- **Code-scope map**: from the file paths named in `plan.md` and `tasks.md`, plus a keyword + search for the concepts each requirement describes, derive the set of source files and + components in scope for assessment. Bound the assessment to these — do **not** infer + scope beyond what the artifacts define (FR-001). + +### 4. Assess the Codebase and Classify Findings + +For each item in the intent inventory, inspect the current code in scope and produce a +`Finding` only where there is a gap. Classify every finding by **gap type**: + +- **`missing`**: the required work is absent from the code entirely. +- **`partial`**: the work exists but does not yet fully satisfy the requirement / + acceptance criterion / plan decision. +- **`contradicts`**: the code does something that conflicts with stated intent or a + constitution MUST principle. +- **`unrequested`**: the code contains work not called for by the spec, plan, or tasks + (surfaced for awareness — converge does **not** delete code, it only appends a task to + review/justify or remove it). + +Each `Finding` records: a stable id, the `source-ref` it traces to, the `gap-type`, a +severity, and a short human-readable description with the evidence (the file/area observed). + +**Edge cases:** + +- **Little or no code yet**: treat the entire specified scope as `missing` remaining work + rather than failing. +- **Nothing remains**: produce zero findings and follow the converged branch in Step 7. + +### 5. Assign Severity + +- **CRITICAL**: violates a constitution MUST principle, or a `missing`/`contradicts` gap + that blocks baseline functionality of a P1 user story. +- **HIGH**: a `missing` or `partial` gap on a core functional requirement or acceptance + criterion. +- **MEDIUM**: a `partial` gap on a secondary requirement, or an `unrequested` addition with + unclear justification. +- **LOW**: minor partial gaps, polish, or low-risk `unrequested` additions. + +### 6. Present the In-Session Findings Summary + +Before appending anything, output a compact, severity-graded summary (no file writes yet): + +## Convergence Findings + +| ID | Gap Type | Severity | Source | Evidence | Remaining Work | +|----|----------|----------|--------|----------|----------------| +| F1 | missing | HIGH | FR-008 | converge template has no guardrail text | Add append-only enforcement | + +**Summary metrics:** + +- Requirements / acceptance criteria checked +- Plan decisions checked +- Constitution principles checked (or "skipped — template") +- Findings by gap type (missing / partial / contradicts / unrequested) +- Findings by severity + +### 7. Append Convergence Tasks (or report converged) + +**If there are one or more actionable findings** (`tasks_appended` outcome): + +Append to the **end** of `tasks.md`, per the append contract: + +1. Scan all existing task IDs; let `M` be the maximum. Determine the next phase number `N` + (highest existing phase + 1). +2. Write a single new section header `## Phase N — Convergence`. +3. Emit one checklist item per actionable finding, ordered CRITICAL/HIGH first, assigning + IDs `M+1, M+2, …`: + + ```markdown + - [ ] T: per () + ``` + + - `` traces the task to its origin: e.g. `FR-003`, `SC-002`, `US1/AC2`, + `plan: storage decision`, `Constitution II`. + - `` is one of `missing`, `partial`, `contradicts`, `unrequested`. + - Constitution-violation tasks MUST be emitted first and described as `CRITICAL`. +4. Never reuse or renumber existing IDs. If a prior Convergence phase exists, add a new, + separately-numbered one below it — do not touch the old one. + +**If there are no actionable findings** (`converged` outcome): + +- Do **not** modify `tasks.md` at all — no empty phase header. +- Report: **"✅ Converged — the implementation satisfies the spec, plan, and tasks."** +- Include the summary counts of what was checked. + +### 8. Provide Next Actions (Handoff) + +- On `tasks_appended`: state how many tasks were appended under which phase, and recommend + running `/speckit.implement` to complete them; note that a follow-up converge + run will find fewer or no remaining items. +- On `converged`: recommend proceeding to review / opening a PR. No further implement pass + is needed for this feature's specified scope. + +### 9. Check for extension hooks + +After producing the result, check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.after_converge` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- Pass the convergence outcome (`converged` or `tasks_appended`) to the hook context so an + extension can branch on it. +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently diff --git a/.github/prompts/speckit.converge.prompt.md b/.github/prompts/speckit.converge.prompt.md new file mode 100644 index 000000000..39c7ea1a8 --- /dev/null +++ b/.github/prompts/speckit.converge.prompt.md @@ -0,0 +1,3 @@ +--- +agent: speckit.converge +--- diff --git a/specs/001-converge-command/research.md b/specs/001-converge-command/research.md index dcf59a17f..7d6e26c2f 100644 --- a/specs/001-converge-command/research.md +++ b/specs/001-converge-command/research.md @@ -27,8 +27,9 @@ that shape the design, with rationale and rejected alternatives. `FEATURE_DIR` and confirm `plan.md` + `tasks.md` exist. - **Rationale**: This is the same mechanism `analyze` and `implement` use. It already resolves the feature directory via `SPECIFY_FEATURE_DIRECTORY` → `.specify/feature.json` - → branch-prefix fallback, so it works with or without git (Constitution Principle II). - No new script is introduced, preserving cross-platform parity by construction. + and otherwise exits with a clear prerequisite error, so converge keeps the same + no-git behavior (Constitution Principle II). No new script is introduced, preserving + cross-platform parity by construction. - **Alternatives considered**: - *New `converge`-specific helper script* — rejected: would require Bash + PowerShell parity maintenance for no added capability, violating the "focused contribution"