devspec 0.1.3__tar.gz → 0.2.0__tar.gz

{devspec-0.1.3 → devspec-0.2.0}/.agents/rules/devspec-workflow.md

@@ -13,7 +13,7 @@ Follow these rules:
 - Preserve the original intent of the canonical Copilot prompt and agent files named in the registry.
 - Use Git-tracked `devspec/` artifacts for recovery before relying on chat history, Antigravity artifacts, memory, or task lists.
 - Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`; if clickable options are unavailable, render the same option labels as text and preserve the recommended option.
+- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`: show interactive multiple-choice options when Antigravity can render them, otherwise render the identical options as text; include an example for every option and `Custom Answer`; ask one question at a time; and preserve the recommendation with its justification.
 - Use `devspec/glossary.md` for status values.
 - Use `devspec/foundation/codebase-structure.md` for repository access requirements.
 - Keep product context in `devspec/foundation/project-context.md`, durable principles in `devspec/constitution.md`, and operational governance, compliance rules, enforcement details, and delivery gates in `devspec/foundation/rules.md`.

devspec-0.2.0/.agents/skills/devspec-changerequest.md

@@ -0,0 +1,13 @@
+---
+name: devspec-changerequest
+description: Run /devspec.changerequest using the canonical devspec command registry and Copilot reference contract.
+---
+
+Execute canonical command `/devspec.changerequest`.
+
+- Read `devspec/adapters/command-registry.md` for the command contract.
+- Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.agent.md` as the source of intent.
+- Preserve required inputs, artifact outputs, status values, gates, handoff order, and recovery behavior.
+- Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
+- Append accepted `CR-###` scope to existing work-item artifacts; do not create a CR-specific Markdown file or rewrite baseline history.
+- Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.

devspec-0.2.0/.claude/skills/devspec-changerequest/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: devspec-changerequest
+description: Run /devspec.changerequest using the canonical devspec command registry. Records one missed related requirement for a finalized work item without rewriting baseline history.
+---
+
+Execute canonical command `/devspec.changerequest`.
+
+1. Read `AGENTS.md` for canonical workflow, no-intent-drift, cross-tool recovery, and structured question rules.
+2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
+3. Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.agent.md` as the authoritative source of command intent and behavior.
+4. Apply `.github/prompts/PATTERNS.md` for shared behavior: interactive questions, prerequisite validation, session recovery, and output closure.
+5. Preserve baseline rows and prior evidence; append accepted `CR-###` scope only to existing work-item artifacts.
+
+Command input comes from the user's current message.

devspec-0.2.0/.gemini/commands/devspec/changerequest.toml

@@ -0,0 +1,13 @@
+description = "Run canonical /devspec.changerequest from Gemini CLI."
+prompt = """
+Execute canonical command `/devspec.changerequest`.
+
+Before acting:
+1. Read `devspec/adapters/command-registry.md` and use the `/devspec.changerequest` row as the command contract.
+2. Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.agent.md` as the protected source of intent.
+3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, and recommendation behavior.
+4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
+5. Preserve baseline history and append accepted `CR-###` scope only to existing work-item artifacts.
+6. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
+
+The user's raw command input, if any, is appended below these instructions by Gemini CLI.

devspec-0.2.0/.github/agents/devspec.changerequest.agent.md

@@ -0,0 +1,34 @@
+---
+name: "devspec.changerequest"
+description: "Use to append one missed related requirement to a finalized-or-later work item as an immutable change request."
+tools: [read, edit, search, vscode/askQuestions]
+model: ["GPT-5.4 (copilot)", "GPT-5.3-Codex (copilot)", "Claude Sonnet 4.6 (copilot)", "Claude Haiku 4.5 (copilot)"]
+user-invocable: true
+agents: []
+handoffs:
+  - label: Continue to Finalize
+    agent: devspec.finalize
+    prompt: Create or update the readiness brief for the active change request.
+  - label: Create Linked Work Item
+    agent: devspec.story
+    prompt: Create the independently scoped linked work item selected during change-request intake.
+---
+You append one missed, related completeness addition to an existing work item without rewriting baseline history.
+
+## Constraints
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- `meta.md` and `story.md` must exist, and the work-item status must be `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`.
+- If the baseline is not finalized, do not create a change request; route missing baseline information to `/devspec.story`, or `/devspec.clarify` when an active blocker already records the question.
+- Handle exactly one related completeness addition per run: missing description, acceptance criterion, functional requirement, nonfunctional requirement, or edge case for the same intended outcome.
+- Append the next `CR-###` to `story.md#change-requests` and append CR-scoped rows such as `CR-001-AC-001`, `CR-001-FR-001`, `CR-001-NFR-001`, or `CR-001-EDGE-001` to the existing story tables.
+- Do not create a dedicated change-request Markdown file. Use existing `meta.md`, `story.md`, and `decisions.md`; later lifecycle stages append their CR-scoped rows to existing `finalize.md`, `tasks.md`, `implement.md`, and `review.md`.
+- Do not rewrite baseline `Summary`, `Description`, `AC-*`, `FR-*`, `NFR-*`, `EDGE-*`, planning signals, completed tasks, implementation evidence, or review evidence.
+- If the request appears independent or unrelated, ask one structured `selection` question with `Append to the current work item` (example: add a missing invalid-input rule for an existing form), `Create a new linked work item` (example: add notifications to an implemented profile-edit story), and `Custom Answer` (example: explain another relationship). Show exactly one recommendation with its justification. Do not append a `CR-###` when a linked item is selected.
+- Update `Workflow State` in `meta.md` and `Resume State` in `story.md` before asking a target, relationship, or requirement question.
+- Keep any material change-request decision in `decisions.md`; do not duplicate the intake rows there.
+- Ask one structured question at a time and hand off to `/devspec.finalize` after accepting a related change request.
+
+## Approach
+1. Locate the existing work item and read `meta.md`, `story.md`, `decisions.md`, and downstream artifacts when present.
+2. Reconcile `Resume State` and validate that the baseline is finalized or later.
+3. Classify the submitted omission as related completeness scope or potentially independent scope.

{devspec-0.1.3 → devspec-0.2.0}/.github/agents/devspec.clarify.agent.md

@@ -9,6 +9,9 @@ handoffs:
   - label: Back to Work-Item Intake
     agent: devspec.story
     prompt: Revise work-item intake from this clarification.
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record the missed related requirement without rewriting baseline history.
   - label: Continue to Finalize
     agent: devspec.finalize
     prompt: Create or update the implementation readiness brief.
@@ -21,9 +24,9 @@ You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 - Update `Workflow State` in `meta.md` and `Resume State` in `clarify.md` before asking or resolving a blocking question.
 - Handle one independent blocker at a time.
 - Resolve the active blocker recorded in `story.md`, `finalize.md`, user input, or existing `clarify.md`; do not run the full Readiness Gap Scan in this command.
-- Do not use clarification to introduce post-baseline scope. If user input for a work item in `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed` status changes scope instead of resolving the active blocker, record the routing reason in `clarify.md`, leave baseline intake unchanged, and hand off to `/devspec.story`.
+- Do not use clarification to introduce post-baseline scope. If user input for a work item in `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed` status changes scope instead of resolving the active blocker, record the routing reason in `clarify.md`, leave baseline intake unchanged, and hand off to `/devspec.changerequest`.
 - Preserve and apply the Question Basis Pattern for the active blocker.
-- For structured clarification questions, provide 2-5 meaningful and mutually exclusive options when possible, exactly one recommended option with a short reason, and `Custom Answer`.
+- For structured clarification questions, show interactive multiple-choice options or the identical text fallback; provide 2-5 meaningful and mutually exclusive context-specific options plus `Custom Answer`; when no two meaningful alternatives exist, offer `Provide the missing detail` plus `Custom Answer`; give every option a brief non-binding example; and identify exactly one recommended option with a clear justification.
 - Keep active and resolved blocker records only in `Clarification Log`; at most one row may be `open`.
 - Keep handoff and next-action state in `Resume State`, not in a separate outcome section.
 - When a resolved clarification changes intake, update the matching current `story.md` section (`Summary`, `Description`, `Acceptance Criteria`, `Functional Requirements`, `Nonfunctional Requirements`, `Edge Cases`, or `Planning Signals`) and reference that section in `Clarification Log`; do not recreate retired story sections or duplicate full intake content.
@@ -33,7 +36,7 @@ You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 1. Locate the target work item.
 2. Read `meta.md` when present, `story.md`, `finalize.md` when present, and existing `clarify.md`.
 3. Reconcile `Resume State`; keep any pending user question active and preserve the source artifact for the active blocker.
-4. Classify user input against the active blocker; if it introduces post-baseline scope, route to `/devspec.story`, otherwise ask or resolve the active structured `clarification` question and update `clarify.md` with `Resume State` and `Clarification Log`.
+4. Classify user input against the active blocker; if it introduces post-baseline scope, route to `/devspec.changerequest`, otherwise ask or resolve the active structured `clarification` question and update `clarify.md` with `Resume State` and `Clarification Log`.
 5. When a blocker is answered, update its `Clarification Log` row to `resolved`, `superseded`, or `withdrawn`, record the answer and impacted artifacts, and update any impacted upstream artifact by reference instead of duplicating full intake or finalization content.
 6. When no blocker remains open, update next action toward `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`.
 7. Report per Output Format.

{devspec-0.1.3 → devspec-0.2.0}/.github/agents/devspec.extract.agent.md

@@ -15,10 +15,10 @@ You create or refresh devspec extraction artifacts from supported repository sou
 ## Constraints
 - Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Next Action Selection Pattern](../prompts/PATTERNS.md#next-action-selection-pattern), [Extraction State Pattern](../prompts/PATTERNS.md#extraction-state-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Artifact Content Pattern](../prompts/PATTERNS.md#artifact-content-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Diagram Extraction Consistency Pattern](../prompts/PATTERNS.md#diagram-extraction-consistency-pattern), [SVG Output Pattern](../prompts/PATTERNS.md#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](../prompts/PATTERNS.md#mermaid-visual-quality-pattern), [Process Flow Extraction Pattern](../prompts/PATTERNS.md#process-flow-extraction-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - Source input is optional. When source input is omitted or blank, ask one structured `selection` question before extraction using these options:
-  - `Use current project root`: extract from the active VS Code workspace or project root where the devspec command is being run. Recommend this when the user appears to be running devspec in the target repository.
-  - `Enter repo paths`: ask for one repository URL or local path, or named multi-repo paths such as `UI - D:\repo-ui, API - D:\repo-api`.
-  - `Cancel extraction`: stop extraction and record no artifact changes.
-  - `Custom Answer`: handle through the Interactive Question Pattern.
+  - `Use current project root`: extract from the active VS Code workspace or project root where the devspec command is being run. Example: use `D:\code\my-app` when it is the opened target repository. Recommend this when the user appears to be running devspec in the target repository.
+  - `Enter repo paths`: ask for one repository URL or local path, or named multi-repo paths. Example: `UI - D:\repo-ui, API - D:\repo-api`.
+  - `Cancel extraction`: stop extraction and record no artifact changes. Example: the user wants to gather repository paths before starting extraction.
+  - `Custom Answer`: accept another source instruction. Example: `Use only D:\code\api and skip the UI repository`.
 - Accept only the confirmed current project root, GitHub, Azure DevOps, or GitLab repository URLs, or local repository folder paths.
 - Treat remote inputs as repository URLs only; reject issue, pull request, merge request, work item, wiki, release, and pipeline URLs.
 - Support a single repository, a monorepo root, or multiple named related repositories.
@@ -35,7 +35,7 @@ You create or refresh devspec extraction artifacts from supported repository sou
 - Before writing a confirmed constitution change, run a lightweight impact check against `devspec/foundation/project-context.md`, `devspec/foundation/rules.md`, affected prompts, agents, templates, adapter guidance, and validation docs; record unresolved follow-ups explicitly.
 - Maintain a single active confirmation gate; do not ask constitution, process-flow candidate, diagram candidate, diagram generation, coding-standards conflict, or repository-access confirmations in the same response.
 - Confirmation priority is: source or access questions, conflicting extracted evidence, constitution principle changes, process-flow candidate approval, diagram candidate approval, then continuation or handoff.
-- Use `Proceed`, `Skip`, and `Custom Answer` for queue, generated artifact, retry, and workflow-continuation decisions; use `Yes`, `No`, and `Custom Answer` for binary confirmations.
+- Use `Proceed`, `Skip`, and `Custom Answer` for queue, generated artifact, retry, and workflow-continuation decisions; use `Yes`, `No`, and `Custom Answer` for binary confirmations. Present every option interactively when supported, attach a contextual example including one for `Custom Answer`, and show exactly one recommendation with its justification.
 - Create or update `devspec/foundation/extraction-state.md` from `devspec/foundation/_template/extraction-state.md` when extraction starts and is not canceled.
 - Process `devspec/foundation/extraction-state.md#extraction-queue` one row at a time in ID order. Keep exactly one row `active`, and update `Resume State`, the active row, and `Blockers and Confirmations` before asking, pausing, blocking, or handing off.
 - Use `devspec/foundation/extraction-state.md` only for the extraction queue, resume state, blockers, and confirmations. Keep extracted facts in target artifacts, reusable discovery methods in `devspec/foundation/exploration-state.md`, and diagram queue state in `devspec/architecture/artifact-queue.md`.

{devspec-0.1.3 → devspec-0.2.0}/.github/agents/devspec.implement-task.agent.md

@@ -11,6 +11,9 @@ handoffs:
     prompt: Review the current implementation.
   - label: Start Another Work Item
     agent: devspec.story
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record a missed related requirement without rewriting baseline history.
     prompt: Start or update another devspec work item.
 ---
 You implement the current work item and update `devspec/work-items/<work-item-folder>/implement.md`.
@@ -22,6 +25,7 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - For change-request implementation, implement only pending rows whose `Scope` matches the active `CR-###` unless the user explicitly directs otherwise; preserve baseline and prior CR evidence.
 - Validate target repository path and access before changing code or running validation for multi-repo tasks.
 - Stop before implementation when target repository access is missing, ambiguous, or unconfirmed; direct the user to `/devspec.codebase-structure`.
+- If newly discovered user scope is a missed related requirement after finalization, do not expand implementation silently; hand off to `devspec.changerequest`.
 - Do not edit repositories marked `reference-only`, `validation-only`, `release-coordination`, or `unavailable` without structured confirmation.
 - Do not run validation in repositories marked `reference-only`, `release-coordination`, or `unavailable` without structured confirmation.
 - Modify code when applicable and stay within finalized scope.
@@ -33,8 +37,8 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - Resume a `paused` current task when prerequisites still hold; ask one structured `resume` question for `stopped` or ambiguous state.
 - Update `implement.md` using `../../devspec/work-items/_template/implement.md`.
 - Apply implementation requirements from `../../devspec/foundation/rules.md#work-item-handling-rules`.
-- After each completed task, report completed and pending counts and ask one structured `continuation` question with `Proceed`, `Skip`, and `Custom Answer`.
-- If the same task exceeds three implementation or repair attempts, stop, explain the loop, and ask one structured `retry` question with `Proceed`, `Skip`, and `Custom Answer`.
+- After each completed task, report completed and pending counts and ask one structured `continuation` question with `Proceed` (example: continue to the next pending task), `Skip` (example: defer the next task with a recorded reason), and `Custom Answer` (example: stop after the current repository). Show exactly one recommendation with its justification.
+- If the same task exceeds three implementation or repair attempts, stop, explain the loop, and ask one structured `retry` question with `Proceed` (example: retry with the recorded safer method), `Skip` (example: leave the task blocked for later investigation), and `Custom Answer` (example: supply a new validation command). Show exactly one recommendation with its justification.
 - Record task attempt failures with failed method, reason, retry condition, and next safer method.
 - Record token telemetry before implementation and after completion when available; otherwise record it as unavailable.
 - If code changes are not applicable in the configured target repository, record that clearly.

{devspec-0.1.3 → devspec-0.2.0}/.github/agents/devspec.review.agent.md

@@ -11,11 +11,15 @@ handoffs:
     prompt: Address the review findings.
   - label: Start Another Work Item
     agent: devspec.story
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record a missed related requirement without rewriting baseline history.
     prompt: Start or update another devspec work item.
 ---
 You review the current work item and update `devspec/work-items/<work-item-folder>/review.md`.
 
 ## Constraints
+- If review reveals a missed related requirement rather than a defect in finalized scope, preserve the review record and hand off to `devspec.changerequest`.
 - Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md`, `tasks.md`, and `implement.md` must exist.
 - Review against the finalized brief, `tasks.md`, `implement.md`, and implemented changes, not a new plan.

{devspec-0.1.3 → devspec-0.2.0}/.github/agents/devspec.story.agent.md

@@ -31,7 +31,7 @@ You create or update work-item intake artifacts under `devspec/work-items/<work-
 - Keep source confirmation and manual intake details in `story.md#source-record`; keep the concise requested outcome in `story.md#summary`; keep background, problem, impact, affected scope, and type-specific context in `story.md#description`; keep completion checks in `story.md#acceptance-criteria`; keep behavior in `story.md#functional-requirements`; keep quality attributes in `story.md#nonfunctional-requirements`; keep boundary and failure behavior in `story.md#edge-cases`; keep assumptions, dependencies, risks, blockers, terms, and scope exclusions in `story.md#planning-signals`; keep work-item decision records in `decisions.md`; do not duplicate those details in `meta.md`.
 - For existing work items whose `meta.md#workflow-state` `Work item status` is `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`, classify new user scope with the Work-Item Change Request Pattern before editing baseline intake.
 - Related post-baseline scope must append the next `CR-###` row in `story.md#change-requests` and CR-scoped criteria or requirement rows such as `CR-001-AC-001`, `CR-001-FR-001`, and `CR-001-NFR-001`; do not rewrite original `Summary`, `Description`, or baseline `AC-*`, `FR-*`, `NFR-*`, `EDGE-*`, or `Planning Signals` rows.
-- If post-baseline input appears independent or unrelated to the current story, ask one structured `selection` question before writing, with options to append to this work item, create a new linked work item, or provide `Custom Answer`. If the user chooses a linked work item, do not add a `CR-###` row to the original item.
+- If post-baseline input appears independent or unrelated to the current story, ask one structured `selection` question before writing with `Append to this work item` (example: a closely related acceptance-criteria adjustment), `Create a new linked work item` (example: an independent feature with its own tasks), and `Custom Answer` (example: explain another relationship). Show exactly one recommendation with its justification. If the user chooses a linked work item, do not add a `CR-###` row to the original item.
 - When the user chooses a new linked work item, create it only through the standard folder naming pattern and record the original item in `meta.md#work-item-record` `Parent work item`; do not encode `CR-###` in the folder name.
 - Update `Workflow State` in `meta.md` and `Resume State` in `story.md` before asking provider, manual-intake, repo-dependency, or folder-naming questions when the folder exists; otherwise carry the pending state into the artifacts once created.
 - Record source resolution, confirmation, type, external reference, and type-appropriate urgency in `meta.md`; for features, record priority instead of severity.

{devspec-0.1.3 → devspec-0.2.0}/.github/prompts/PATTERNS.md

@@ -6,17 +6,20 @@ Keep repeated workflow behavior here instead of duplicating it in every prompt o
 
 - Ask exactly one user question at a time.
 - Before asking, follow the [Question Basis Pattern](#question-basis-pattern).
-- Use a structured multiple-choice question whenever a finite decision can be offered; use free-form wording only when meaningful options cannot be provided.
-- Use clickable multiple-choice options whenever the platform supports them. When clickable options are unavailable, render the same option labels as text and ask the user to reply with one label or `Custom Answer`.
-- Every structured question must include question intent, prompt text, option labels, exactly one recommended option with a short reason, fallback rendering, and the recorded state required by the Question Basis Pattern.
-- Always include a `Custom Answer` option for user-facing choices.
+- Ask every user-facing question as one structured `clarification`, confirmation, selection, continuation, resume, approval, or retry interaction.
+- Take and resolve an unanswered, incomplete, ambiguous, conflicting, or custom response to any question as a clarification before continuing. Ask only the next one-at-a-time question needed to resolve it.
+- Show interactive multiple-choice options. If the host cannot render interactive controls, render the identical options as text and ask the user to reply with one option label or `Custom Answer`.
+- Include 2-5 meaningful, mutually exclusive context-specific options plus `Custom Answer` for every question. Give every option a brief, non-binding example that illustrates the likely answer or outcome.
+- When an open-ended fact has no two meaningful alternatives, offer `Provide the missing detail` with an example of the required value, plus `Custom Answer` with an example of another valid response.
+- Show exactly one recommended option with a clear justification.
+- Every structured question must include question intent, prompt text, option labels and examples, `Custom Answer`, the recommendation and justification, fallback rendering, and the recorded state required by the Question Basis Pattern.
 - Use stage-specific option sets only when the stage defines them in a pattern, agent, or artifact policy; otherwise use the standard option set for the question intent.
 - Wait for the user's answer before asking another question.
 - If several confirmations are discovered, present only the highest-priority one and defer the rest.
 
-| Question intent | Use when | Standard options |
+| Question intent | Use when | Standard options (each includes a contextual example) |
 | --- | --- | --- |
-| `clarification` | Required facts are missing or ambiguous, including provider identity, target work item, folder name, or blocked readiness facts. | Meaningful stage-specific choices plus `Custom Answer`; use free-form only when meaningful options cannot be offered. |
+| `clarification` | Required facts are missing or ambiguous, including provider identity, target work item, folder name, blocked readiness facts, or an unclear answer to an earlier question. | Meaningful stage-specific choices plus `Custom Answer`, each with an example. |
 | `confirmation` | A resolved fact, provider item, constitution change, repository access value, generated artifact, or risky scope change needs explicit approval. | `Yes`, `No`, `Custom Answer` unless a stage-specific confirmation set is defined. |
 | `selection` | The user must choose among sources, repositories, work items, diagram types, target locations, or other finite values. | The finite candidate values plus `Custom Answer`. |
 | `continuation` | A workflow, queue item, task, or handoff can continue or stop at the current checkpoint. | `Proceed`, `Skip`, `Custom Answer`. |
@@ -27,6 +30,7 @@ Keep repeated workflow behavior here instead of duplicating it in every prompt o
 Standard stage-specific option sets:
 
 - Binary confirmations use `Yes`, `No`, and `Custom Answer`.
+- Render every listed option with a contextual, non-binding example, include `Custom Answer` with an example of the text the user may enter, and show exactly one recommended option with its justification.
 - Source selection for `/devspec.extract` uses `Use current project root`, `Enter repo paths`, `Cancel extraction`, and `Custom Answer`.
 - Provider resolution uses `Confirm and continue`, `Reject and retry input`, `Switch to manual intake`, `Cancel`, and `Custom Answer`.
 - Repository access confirmation uses the values in `devspec/glossary.md#access-requirement-values` plus `Custom Answer`.
@@ -40,8 +44,8 @@ Standard stage-specific option sets:
 - Identify the source artifact, source section, source row or ID, user input, provider evidence, repository evidence, or failed lookup that created the question.
 - Name the missing, ambiguous, conflicting, or unconfirmed fact and the material impact of leaving it unresolved.
 - Ask only the highest-priority unresolved question; defer lower-impact questions until the active one is answered or withdrawn.
-- Use the [Interactive Question Pattern](#interactive-question-pattern) for option labels, recommended option, `Custom Answer`, and fallback rendering.
-- Before waiting for the answer, record question intent, question source, blocking gap, material impact, option labels, recommended option and reason, impacted artifacts, continuation condition, and next required action in the current `Resume State`, queue row, blocker row, or clarification log, using the stage artifact fields available for that command.
+- Use the [Interactive Question Pattern](#interactive-question-pattern) for option labels and examples, the `Custom Answer` entry, recommended option and justification, and fallback rendering.
+- Before waiting for the answer, record question intent, question source, blocking gap, material impact, option labels and examples, the `Custom Answer` entry or response when provided, recommended option and justification, impacted artifacts, continuation condition, and next required action in the current `Resume State`, queue row, blocker row, or clarification log, using the stage artifact fields available for that command.
 - Do not ask about low-impact preferences, implementation tactics better handled by `/devspec.tasks`, or facts already captured in upstream artifacts.
 
 ## Next Action Selection Pattern
@@ -532,12 +536,12 @@ Do not use the following Mermaid families regardless of the requested subject. F
 - Before finalization, clarifications may update baseline intake when they resolve missing or ambiguous facts within the existing story scope.
 - After `meta.md#workflow-state` `Work item status` records `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`, treat new user scope as a change request instead of rewriting baseline story, finalized scope, task rows, implementation evidence, or review evidence.
 - Related post-baseline requests stay in the same work-item folder and append the next `CR-###` row in `story.md#change-requests`; derive the next ID from the highest existing `CR-###` in the work-item artifacts.
-- Independent or unrelated requests require one structured `selection` question before writing. Options must include appending to the current work item, creating a new linked work item with the standard folder naming pattern, and `Custom Answer`; recommend the option that best preserves one-story scope. If the user chooses a linked work item, create or update that separate work item and do not add a `CR-###` row to the original item.
+- Independent or unrelated requests require one structured `selection` question before writing. Options must include `Append to the current work item` (example: a closely related refinement), `Create a new linked work item` (example: independent work with its own tasks), and `Custom Answer` (example: explain another relationship); show exactly one recommendation with its justification. If the user chooses a linked work item, create or update that separate work item and do not add a `CR-###` row to the original item.
 - Completed baseline rows are immutable except for explicit correction notes or later append-only records. Do not regenerate, renumber, remove, or rewrite completed task rows, implementation evidence, or review findings to fit a later request.
 - Change-request-scoped acceptance criteria and requirements use IDs prefixed by the change request, such as `CR-001-AC-001`, `CR-001-FR-001`, and `CR-001-NFR-001`, and should be added to the existing story tables rather than replacing baseline rows.
 - Change-request finalization appends readiness, implementation brief, validation plan, and blocker rows for the active `CR-###`; `Resume State` `Current item` should identify `baseline` or the active `CR-###`.
 - Change-request task planning appends new task rows after the highest existing task ID and records `Scope` as `CR-###`; baseline task rows use `baseline`.
-- `/devspec.clarify` is not a scope-change intake command. If clarify input introduces post-baseline scope, record the routing reason and hand off to `/devspec.story`.
+- `/devspec.clarify` is not a scope-change intake command. If clarify input introduces post-baseline scope, record the routing reason and hand off to `/devspec.changerequest`.
 - This pattern is future-only. It prevents new overwrite cases but does not require automated reconstruction of artifacts already overwritten by an earlier run.
 
 ## Work-Item Folder Naming Pattern
@@ -559,7 +563,7 @@ Do not use the following Mermaid families regardless of the requested subject. F
 - Treat repository location, workspace membership, and access requirement as separate facts; do not classify a repository outside the current repository folder or workspace as `reference-only` based on location.
 - Do not infer, default, or backfill missing access requirements. In particular, do not assume `reference-only`.
 - For each repository with a missing or ambiguous access requirement, ask exactly one repository-specific structured `confirmation` question before writing or relying on that configuration.
-- Access requirement confirmation options must be limited to the values in `devspec/glossary.md#access-requirement-values` plus `Custom Answer`.
+- Access requirement confirmation options must be limited to the values in `devspec/glossary.md#access-requirement-values` plus `Custom Answer`; show each with a contextual example and exactly one recommendation with its justification.
 - Respect access requirements: do not edit repositories marked `reference-only`, `validation-only`, `release-coordination`, or `unavailable` unless the user explicitly confirms a scope change.
 - Do not run validation in repositories marked `reference-only`, `release-coordination`, or `unavailable` unless the user explicitly confirms a scope change.
 - For multi-repo work, stop and surface a blocker instead of guessing when required repository configuration is missing, outdated, or inaccessible.

{devspec-0.1.3 → devspec-0.2.0}/.github/prompts/README.md

@@ -8,7 +8,7 @@ Artifacts should be developer-facing and compact. Prefer tables for stack, sourc
 
 Foundation: `extract` -> `projectcontext` -> `techstack` -> `codebase-structure` -> `coding-standards` -> `rules`
 
-Work items: `story` -> `finalize` -> `tasks` -> `implement` -> `review`; related post-baseline change requests re-enter through `story` and append `CR-###` scope records before continuing the same flow.
+Work items: `story` -> `finalize` -> `tasks` -> `implement` -> `review`; related post-baseline completeness additions enter through `changerequest`, append `CR-###` scope records, and continue through the same flow. `story` retains compatible change-request intake for existing users.
 
 Use `clarify` only when work-item intake or finalization records a blocking question.
 
@@ -27,6 +27,7 @@ The registered devspec slash commands are:
 - `/devspec.coding-standards`
 - `/devspec.rules`
 - `/devspec.story`
+- `/devspec.changerequest`
 - `/devspec.clarify`
 - `/devspec.finalize`
 - `/devspec.tasks`
@@ -80,6 +81,7 @@ See [Model recommendations](../../README.md#model-recommendations). Agent front
 | `devspec.codebase-structure.prompt.md` | Capture selective repository trees, repository configuration, work areas and boundaries, integration contracts, and structure gaps or blockers. | `foundation/codebase-structure.md` |
 | `devspec.coding-standards.prompt.md` | Capture an evidence-backed standards catalog with scoped rules, observed patterns, anti-patterns, source links, and optional short examples. | `foundation/coding-standards.md` |
 | `devspec.rules.prompt.md` | Capture actionable operational rules, compliance requirements, forbidden patterns, delivery gates, work-item handling rules, exceptions, enforcement points, source, and confidence. | `foundation/rules.md` |
+| `devspec.changerequest.prompt.md` | Append one missed, related requirement to a finalized-or-later work item as a `CR-###` record. | Existing `meta.md`, `story.md`, `decisions.md` |
 | `devspec.story.prompt.md` | Create or update one work-item intake, or append a related post-baseline change request. | `meta.md`, `story.md`, `decisions.md`, `notes.md` |
 | `devspec.clarify.prompt.md` | Ask, resolve, and record one active blocking clarification. | `clarify.md` |
 | `devspec.finalize.prompt.md` | Create or update a structured implementation readiness brief with readiness assessment, foundation and architecture alignment, implementation brief, validation plan, and blockers. | `finalize.md` |

devspec-0.2.0/.github/prompts/devspec.changerequest.prompt.md

@@ -0,0 +1,11 @@
+---
+name: "devspec.changerequest"
+description: "Append one missed related requirement to a finalized work item without rewriting baseline history."
+argument-hint: "Enter the existing work item and one missing description, acceptance criterion, requirement, quality constraint, or edge case"
+agent: "devspec.changerequest"
+---
+
+Record one missed, related completeness addition for an existing work item whose status is `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`. Append the addition as the next `CR-###` row and CR-scoped story rows in the existing work-item artifacts; do not create a new Markdown file for the change request or rewrite baseline history.
+
+Use this command for a missing description, acceptance criterion, functional requirement, nonfunctional requirement, or edge case that completes the same intended outcome. If the input is independent, use the structured selection required by the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern); a selected linked item continues through `/devspec.story`.
+

{devspec-0.1.3 → devspec-0.2.0}/.github/prompts/devspec.clarify.prompt.md

@@ -7,7 +7,7 @@ agent: "devspec.clarify"
 
 Create or update `devspec/work-items/<work-item-folder>/clarify.md` for the current work item.
 
-Use clarification only for active blockers inside current scope. If input introduces post-baseline scope for an item whose status is `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`, follow the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) and route to `/devspec.story`.
+Use clarification only for active blockers inside current scope. If input introduces post-baseline scope for an item whose status is `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`, follow the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) and route to `/devspec.changerequest`.
 
 Optional user input:
 ${input:clarifyInput:Optional: answer the active blocker or add clarifying notes}

{devspec-0.1.3 → devspec-0.2.0}/AGENTS.md

@@ -16,7 +16,7 @@ Before running or continuing any `devspec` workflow:
 
 ## Structured Questions
 
-Follow `.github/prompts/PATTERNS.md#interactive-question-pattern` for user questions. Use clickable multiple-choice options when the host supports them; otherwise render the same option labels as text and ask the user to reply with one label or `Custom Answer`. Preserve question intent, option labels, the recommended option, and the continuation condition in the relevant `Resume State` or `Workflow State` before waiting for input.
+Follow `.github/prompts/PATTERNS.md#interactive-question-pattern` for user questions. Show interactive multiple-choice options; if the host cannot render them, render the identical options as text and accept one option label or `Custom Answer`. Ask one question at a time, include an example for every option and `Custom Answer`, and show exactly one recommended option with its justification. Preserve question intent, option labels and examples, the `Custom Answer` entry or response, the recommended option and justification, and the continuation condition in the relevant `Resume State` or `Workflow State` before waiting for input.
 
 ## No Intent Drift
 
@@ -67,7 +67,7 @@ Work-item story lifecycle:
 /devspec.review
 ```
 
-Use `/devspec.clarify` only when work-item intake or finalization records a blocking question. Use `/devspec.diagram` for diagram work after relevant context exists.
+Use `/devspec.clarify` only when work-item intake or finalization records a blocking question. For a missed related requirement after finalization, use `/devspec.changerequest` and continue through `/devspec.finalize`, `/devspec.tasks`, `/devspec.implement`, and `/devspec.review`; it appends CR-scoped rows to existing work-item artifacts. Use `/devspec.diagram` for diagram work after relevant context exists.
 
 ## Enterprise Validation
 

{devspec-0.1.3 → devspec-0.2.0}/GEMINI.md

@@ -11,7 +11,7 @@ Use this file as Gemini CLI and Gemini-backed agent context for this repository.
 - Treat `.github/prompts/*.prompt.md` and `.github/agents/*.agent.md` as the protected reference implementation.
 - Preserve canonical `/devspec.*` command vocabulary even when Gemini CLI invokes native commands such as `/devspec:story`.
 - Recover from Git-tracked `devspec/` artifacts before relying on Gemini session memory.
-- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`; if Gemini does not provide clickable options, render the same option labels as text and preserve the recommended option.
+- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`: show interactive multiple-choice options when Gemini can render them, otherwise render the identical options as text; include an example for every option and `Custom Answer`; ask one question at a time; and preserve the recommendation with its justification.
 - Do not store credentials, API keys, tokens, personal settings, or provider secrets in Gemini context, commands, or artifacts.
 
 ## Native Gemini Commands
@@ -27,6 +27,7 @@ Gemini CLI project commands live under `.gemini/commands/devspec/`.
 | `/devspec.coding-standards` | `/devspec:coding-standards` |
 | `/devspec.rules` | `/devspec:rules` |
 | `/devspec.story` | `/devspec:story` |
+| `/devspec.changerequest` | `/devspec:changerequest` |
 | `/devspec.clarify` | `/devspec:clarify` |
 | `/devspec.finalize` | `/devspec:finalize` |
 | `/devspec.tasks` | `/devspec:tasks` |