diff --git a/.github/agents/devspec.clarify.agent.md b/.github/agents/devspec.clarify.agent.md index 20141e9..7c2aa4f 100644 --- a/.github/agents/devspec.clarify.agent.md +++ b/.github/agents/devspec.clarify.agent.md @@ -16,11 +16,12 @@ handoffs: You create or update `devspec/work-items//clarify.md`. ## Constraints -- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-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), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). +- 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), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). - `story.md` must exist. - 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`. - 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`. - Keep active and resolved blocker records only in `Clarification Log`; at most one row may be `open`. @@ -32,7 +33,7 @@ You create or update `devspec/work-items//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. Ask or resolve the active structured `clarification` question, then 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.story`, 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. diff --git a/.github/agents/devspec.finalize.agent.md b/.github/agents/devspec.finalize.agent.md index 2582a73..9997f76 100644 --- a/.github/agents/devspec.finalize.agent.md +++ b/.github/agents/devspec.finalize.agent.md @@ -16,9 +16,10 @@ handoffs: You create or update `devspec/work-items//finalize.md`. ## Constraints -- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). -- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers. +- 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), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). +- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#change-requests`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, change requests, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers. - Read `decisions.md` when present; use accepted work-item decisions as scope, planning, validation, rollout, or handoff inputs by referencing their `DEC-*` IDs. +- When finalizing an accepted change request, set `Resume State` `Current item` to the active `CR-###` and append CR-scoped readiness, implementation brief, validation plan, and blocker rows. Preserve prior baseline and prior CR rows. - Run the Readiness Gap Scan before setting `finalize.md` to `ready`. - Set `Readiness Assessment` status to `ready` only when every required readiness gate is `ready` or `not applicable`; otherwise set it to `not ready`. - Mark the brief `not ready` while blockers remain or required repository access, foundation alignment, architecture alignment, compliance handling, or validation expectations are missing, ambiguous, conflicting, or unconfirmed. @@ -29,6 +30,7 @@ You create or update `devspec/work-items//finalize.md`. - Ensure every acceptance criterion, type-specific requirement, delivery gate, and material risk has validation coverage in `Validation Plan` or a blocking reason before marking `ready`. - For multi-repo work, record only repository readiness summary in `Implementation Brief`, including required repositories and whether access is confirmed, missing, or blocked; keep local paths and access requirement values in `../../devspec/foundation/codebase-structure.md`. - Do not invent missing requirements or silently change scope. +- Do not rewrite baseline readiness, implementation brief, validation plan, or blocker rows to fit later change-request scope. - Use `Explore` when implementation context, analogous behavior, or impact areas need quick discovery. - Use session memory only for transient notes; `finalize.md` remains canonical. - Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off. @@ -47,7 +49,7 @@ You create or update `devspec/work-items//finalize.md`. 2. Read `meta.md` when present, `decisions.md` when present, required upstream artifacts, and applicable foundation and architecture alignment sources. 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state. 4. Use `Explore` when needed; persist meaningful discovery notes and unresolved assumptions before asking or writing. -5. Run the Readiness Gap Scan, including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers. +5. Run the Readiness Gap Scan for the current item (`baseline` or active `CR-###`), including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers. 6. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern; use `/devspec.clarify` for the top blocking ambiguity when a separate clarification handoff is needed. 7. Apply type-specific readiness gates and write `finalize.md` with `../../devspec/work-items/_template/finalize.md`. 8. Report per Output Format. diff --git a/.github/agents/devspec.implement-task.agent.md b/.github/agents/devspec.implement-task.agent.md index 3e1f122..3c3960a 100644 --- a/.github/agents/devspec.implement-task.agent.md +++ b/.github/agents/devspec.implement-task.agent.md @@ -16,9 +16,10 @@ handoffs: You implement the current work item and update `devspec/work-items//implement.md`. ## Constraints -- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure. +- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure. - `finalize.md` must be `ready` and `tasks.md` must exist. - Implement pending rows from `tasks.md#implementation-tasks` sequentially unless the user stops or skips. +- 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`. - Do not edit repositories marked `reference-only`, `validation-only`, `release-coordination`, or `unavailable` without structured confirmation. @@ -27,7 +28,7 @@ You implement the current work item and update `devspec/work-items//review.md`. ## Constraints -- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure. +- 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. +- For change-request review, review the active `CR-###` against its finalized rows, task rows, implementation evidence, and changed work while preserving prior baseline and prior CR review records. - Record findings with severity and required action when applicable. - Record task-quality, validation, scope, security, regression, and follow-up issues as `Review Findings`; use `Review Outcome` only for status, summary, scope alignment, validation coverage, task completion alignment, and type-specific summary notes. - Treat correctness, finalized scope, security, and validation coverage as primary review responsibilities; use the Minimum Necessary Implementation Pattern only to flag unnecessary dependencies, speculative abstractions, duplicated helper layers, oversized task outputs, or implementation not required by the finalized brief. +- Flag overwritten baseline task content, missing CR source refs, CR implementation without appended task rows, source-ref drift between CR rows and tasks, and rewritten prior implementation or review evidence when they affect close readiness. - Apply review expectations from `../../devspec/foundation/rules.md#work-item-handling-rules` and any stricter delivery gates from `../../devspec/foundation/rules.md#delivery-gate-catalog`. - Update `Workflow State` in `meta.md` and `Resume State` in `review.md` before recording findings, asking for clarification, or handing off. @@ -30,7 +32,7 @@ You review the current work item and update `devspec/work-items//`. ## 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), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Work-Item Folder Naming Pattern](../prompts/PATTERNS.md#work-item-folder-naming-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). +- 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), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Work-Item Folder Naming Pattern](../prompts/PATTERNS.md#work-item-folder-naming-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). - Required user input is mandatory. - Validate provider URLs or identifiers before treating input as resolved. - Use `devspec/foundation/provider-integrations.md` for provider resolution policy, supported inputs, outcome handling, confirmation requirements, manual fallback, integration access expectations, and source-resolution recording; initialize it from `devspec/foundation/_template/provider-integrations.md` when missing. @@ -29,6 +29,10 @@ You create or update work-item intake artifacts under `devspec/work-items//tasks.md`. ## Constraints -- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Explore and Memory, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure. +- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Explore and Memory, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure. - `finalize.md` must exist and be marked `ready`. - Do not change or expand the finalized scope. +- For change-request planning, plan only the active `CR-###` recorded in `Resume State` or finalized source refs. Append new task rows after the highest existing `T-###`; do not regenerate, renumber, remove, or rewrite existing task rows. +- Every task row must record `Scope` as `baseline` or the active `CR-###`. - Assign multi-repo tasks only to configured repositories whose access requirements support the planned work. - For monorepos, keep the work item as the orchestration boundary and distinguish executable tasks by target area, module, layer, or validation surface. - Use `reference-only` repositories for context only; surface a blocker when required repository access is missing, ambiguous, unconfirmed, or insufficient for needed edits or validation. @@ -27,7 +29,7 @@ You create or update `devspec/work-items//tasks.md`. - Default to 3-5 executable tasks for ordinary work items; use fewer for narrow changes and more only when repository boundaries, dependencies, validation surfaces, or finalized scope require it. - Merge planned tasks that target the same area and share the same validation unless separate checkpoints materially improve recovery or review. - Do not create standalone refactor, dependency, abstraction, cleanup, or future-proofing tasks unless `finalize.md` requires them. -- Every task row must name source refs, a concrete target area or files, a specific validation method, an observable done condition, and dependency order. +- Every task row must name scope, source refs, a concrete target area or files, a specific validation method, an observable done condition, and dependency order. - Use `finalize.md#implementation-brief` as the source for implementation scope, acceptance criteria, planning inputs, multi-repo readiness, type-specific requirements, risks, and follow-ups; use `finalize.md#validation-plan` for validation methods. - Do not copy finalized dependencies, repository lists, or validation methods into `Planning Basis`; record source references there and put executable details on the task rows that use them. - Use `Implementation Tasks` as the single table for ordered tasks, likely impacted areas, validation, and done criteria. @@ -39,7 +41,7 @@ You create or update `devspec/work-items//tasks.md`. 4. Use `Explore` when needed; persist meaningful discovery notes, dependency mapping, and unresolved questions before asking or writing. 5. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern. 6. Apply the Task Quality Gate Pattern; block or ask one structured question for material planning gaps. -7. Apply type-specific planning rules and write repository-aware tasks with `../../devspec/work-items/_template/tasks.md`. +7. Apply type-specific planning rules and write repository-aware tasks with `../../devspec/work-items/_template/tasks.md`, appending change-request task rows when the current item is `CR-###`. 8. Report per Output Format. ## Output Format diff --git a/.github/prompts/PATTERNS.md b/.github/prompts/PATTERNS.md index f9dba6e..f3ac195 100644 --- a/.github/prompts/PATTERNS.md +++ b/.github/prompts/PATTERNS.md @@ -122,14 +122,14 @@ Standard stage-specific option sets: ## Task Quality Gate Pattern - Use this pattern across `/devspec.tasks`, `/devspec.implement`, and `/devspec.review` to keep task planning, execution, and review aligned with the finalized brief. -- Keep sequencing, dependency, and traceability information in task rows. +- Keep scope, sequencing, dependency, and traceability information in task rows. - During `/devspec.tasks`, record a compact `Task Quality Review` before `Implementation Tasks` covering scope/source coverage, validation coverage, dependency order, granularity, blockers, ambiguity, and implementation-risk gaps. -- Every executable task must include `Source refs` pointing to the finalized acceptance criteria, implementation brief rows, validation plan rows, risks, or follow-ups that justify the task. +- Every executable task must include `Scope` (`baseline` or `CR-###`) and `Source refs` pointing to the finalized acceptance criteria, implementation brief rows, validation plan rows, risks, or follow-ups that justify the task. - Keep tasks actionable, independently verifiable where practical, and sized for one meaningful checkpoint. Split tasks that are too broad to validate safely; merge tasks that are too small to produce useful implementation or review evidence. - Sequence task rows so dependencies appear before dependents. Use the `Depends on` column for required predecessors, and use `none` only when the task can start without another task's output. - Treat missing coverage, impossible sequencing, vague done criteria, missing validation, ambiguous target areas, unresolved access, and external blockers as task-planning blockers when they would materially change implementation or review. - During `/devspec.implement`, before each task attempt, confirm the task is still actionable, within finalized scope, unblocked, specific enough to implement, and ordered after its dependencies. If implementation reveals task ambiguity, a blocking dependency, or oversized scope, update `implement.md`, update the task checkpoint or status when applicable, and stop for the required structured question instead of silently expanding scope. -- During `/devspec.review`, compare `finalize.md`, `tasks.md`, `implement.md`, and changed code or artifacts. Flag missing source coverage, incomplete or skipped tasks without rationale, blocked tasks treated as done, missing validation evidence, source-ref drift, and implementation beyond task scope as review findings when they affect correctness, delivery risk, or readiness to close. +- During `/devspec.review`, compare `finalize.md`, `tasks.md`, `implement.md`, and changed code or artifacts. Flag missing source coverage, missing or incorrect task scope, incomplete or skipped tasks without rationale, blocked tasks treated as done, missing validation evidence, source-ref drift, and implementation beyond task scope as review findings when they affect correctness, delivery risk, or readiness to close. ## Artifact Content Pattern @@ -524,7 +524,21 @@ Do not use the following Mermaid families regardless of the requested subject. F - Work-item folders must follow the [Work-Item Folder Naming Pattern](#work-item-folder-naming-pattern) when created by `/devspec.story`. - Follow the [Artifact Content Pattern](#artifact-content-pattern) when updating work-item artifacts. - Treat optional user input as additive guidance only. -- Update the target work-item artifact in place. Stay within current stage scope and, after finalization, within finalized scope. +- Update the target work-item artifact in place. Stay within current stage scope and, after finalization, within finalized scope unless the [Work-Item Change Request Pattern](#work-item-change-request-pattern) classifies the input as an accepted append-only change request. + +## Work-Item Change Request Pattern + +- Use this pattern when user input for an existing work item may change scope after baseline intake has already moved beyond early clarification. +- 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. +- 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`. +- 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 diff --git a/.github/prompts/README.md b/.github/prompts/README.md index f05ac0d..47be6ed 100644 --- a/.github/prompts/README.md +++ b/.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` +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. Use `clarify` only when work-item intake or finalization records a blocking question. @@ -42,10 +42,11 @@ Developers invoke registered slash commands from this directory. Agent names are - `PATTERNS.md`: shared workflow, recovery, output, discovery, foundation, work-item, memory, and multi-repo rules. - `../../devspec/adapters/command-registry.md`: provider-neutral registry for every registered `devspec` command, canonical prompt and agent source, output artifacts, mutation level, and handoff. -- `../../devspec/adapters/validation-flows.md`: enterprise acceptance checklists for new repository, existing repository, story lifecycle, and cross-tool recovery validation. +- `../../devspec/adapters/validation-flows.md`: enterprise acceptance checklists for new repository, existing repository, story lifecycle, append-only change requests, and cross-tool recovery validation. - `../../devspec/adapters/gemini-cli.md` and `../../devspec/adapters/antigravity.md`: Gemini CLI and Google Antigravity adapter guidance. - `PATTERNS.md#artifact-content-pattern`: shared structure rules for developer-facing artifacts, source labels, optional sections, and table/bullet/list usage. -- `PATTERNS.md#task-quality-gate-pattern`: shared task planning, implementation, and review alignment rules for source refs, dependency order, granularity, blockers, validation evidence, and task-scope drift. +- `PATTERNS.md#work-item-change-request-pattern`: append-only handling for related post-baseline change requests and structured selection for independent work. +- `PATTERNS.md#task-quality-gate-pattern`: shared task planning, implementation, and review alignment rules for scope, source refs, dependency order, granularity, blockers, validation evidence, and task-scope drift. - `PATTERNS.md#constitution-amendment-pattern`: confirmation-gated durable principle changes, artifact routing, consistency review, and placeholder safety. - `PATTERNS.md#diagram-extraction-consistency-pattern`: shared diagram candidate, naming, default SVG output, optional Mermaid or HTML output, evidence, confidence, dedupe, tags, and diagram queue rules. - `PATTERNS.md#architecture-diagram-intake-pattern`: structured architecture prompt fields, editable SVG inference, authoritative listed-component handling, and compact neutral example. @@ -79,12 +80,12 @@ 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.story.prompt.md` | Create or update one work-item intake. | `meta.md`, `story.md`, `decisions.md`, `notes.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.tasks.prompt.md` | Break a ready brief into source-referenced executable implementation tasks with task-quality review, validation, and done criteria. | `tasks.md` | -| `devspec.implement.prompt.md` | Implement pending tasks and record task-quality checks, task-row progress, implementation evidence, execution history, and handoff details. | `implement.md`, `tasks.md` status updates, code changes | -| `devspec.review.prompt.md` | Review implemented work against the finalized brief, tasks, and implementation record. | `review.md` | +| `devspec.tasks.prompt.md` | Break a ready brief into scoped, source-referenced executable implementation tasks with task-quality review, validation, and done criteria. | `tasks.md` | +| `devspec.implement.prompt.md` | Implement pending tasks and append task-quality checks, task-row progress, implementation evidence, execution history, and handoff details. | `implement.md`, `tasks.md` status updates, code changes | +| `devspec.review.prompt.md` | Review implemented work against the finalized brief, tasks, implementation record, and append-only change-request rules. | `review.md` | | `devspec.diagram.prompt.md` | Generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid or HTML output, or batch-generate queued process-flow diagrams. | `architecture/images/dia-NNN-*.svg` by default; optional `architecture/diagrams/dia-NNN-*.md` for Mermaid and `architecture/html/dia-NNN-*.html`; `architecture/overview.md` for high-level diagram references; work-item `images/*.svg`, optional `diagrams.md`, and optional `html/*.html` for explicit or clearly temporary work-item-specific diagram content | ## Maintenance diff --git a/.github/prompts/devspec.clarify.prompt.md b/.github/prompts/devspec.clarify.prompt.md index 2c7e87e..fa5b82d 100644 --- a/.github/prompts/devspec.clarify.prompt.md +++ b/.github/prompts/devspec.clarify.prompt.md @@ -7,5 +7,7 @@ agent: "devspec.clarify" Create or update `devspec/work-items//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`. + Optional user input: ${input:clarifyInput:Optional: answer the active blocker or add clarifying notes} diff --git a/.github/prompts/devspec.finalize.prompt.md b/.github/prompts/devspec.finalize.prompt.md index 985c556..8d48ceb 100644 --- a/.github/prompts/devspec.finalize.prompt.md +++ b/.github/prompts/devspec.finalize.prompt.md @@ -9,5 +9,7 @@ Create or update `devspec/work-items//finalize.md` for the cur Finalize is the readiness gate before `/devspec.tasks`; mark the work item `ready` only when scope, acceptance criteria, repository readiness, applicable foundation constraints, architecture constraints, delivery gates, and validation expectations are clear enough to plan safely. +For accepted post-baseline change requests, follow the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) and append CR-scoped readiness, implementation brief, and validation rows without rewriting baseline rows. + Optional user input: ${input:finalizeInput:Optional: add reviewer notes, constraints, or finalization guidance} diff --git a/.github/prompts/devspec.implement.prompt.md b/.github/prompts/devspec.implement.prompt.md index 39d9236..7083e0f 100644 --- a/.github/prompts/devspec.implement.prompt.md +++ b/.github/prompts/devspec.implement.prompt.md @@ -7,6 +7,8 @@ agent: "devspec.implement-task" Implement the current work item and update `devspec/work-items//implement.md` with implementation task ledger state, implementation evidence, execution history, blockers, and handoff notes. Keep `tasks.md#implementation-tasks` status, attempt count, and checkpoint fields aligned with implementation progress. +For accepted post-baseline change requests, follow the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) and append CR-scoped evidence without rewriting prior baseline or CR evidence. + Apply the [Minimum Necessary Implementation Pattern](PATTERNS.md#minimum-necessary-implementation-pattern) before each task attempt, including confirming whether the task requires a code change and keeping evidence focused on actual access checks, changes, validation, blockers, risks, retries, and handoff details. Apply the [Task Quality Gate Pattern](PATTERNS.md#task-quality-gate-pattern) before each task attempt. diff --git a/.github/prompts/devspec.review.prompt.md b/.github/prompts/devspec.review.prompt.md index a146422..b845509 100644 --- a/.github/prompts/devspec.review.prompt.md +++ b/.github/prompts/devspec.review.prompt.md @@ -9,6 +9,8 @@ Review the current work item and update `devspec/work-items//r Review correctness, finalized scope, security, validation coverage, and unnecessary implementation complexity. Use the [Minimum Necessary Implementation Pattern](PATTERNS.md#minimum-necessary-implementation-pattern) only to flag unnecessary dependencies, speculative abstractions, duplicated helper layers, oversized task outputs, or implementation not required by the finalized brief. +For accepted post-baseline change requests, follow the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) and flag missing CR source refs, missing appended tasks, source-ref drift, or overwritten baseline evidence. + Apply the [Task Quality Gate Pattern](PATTERNS.md#task-quality-gate-pattern) when reviewing task completion and implementation evidence. Optional user input: diff --git a/.github/prompts/devspec.story.prompt.md b/.github/prompts/devspec.story.prompt.md index be79ab9..a04d26a 100644 --- a/.github/prompts/devspec.story.prompt.md +++ b/.github/prompts/devspec.story.prompt.md @@ -1,11 +1,11 @@ --- name: "devspec.story" -description: "Create or update one devspec work item from a provider URL, identifier, or manual intake." -argument-hint: "Enter one work item, provider URL or identifier, bug report, feature request, task, or PBI" +description: "Create or update one devspec work item, or append a related post-baseline change request." +argument-hint: "Enter one work item, provider URL or identifier, bug report, feature request, task, PBI, or change request" agent: "devspec.story" --- -Create or update the work-item intake artifacts under `devspec/work-items//`. Provide one story, feature, bug, security issue, task, or PBI per run; include summary, description, acceptance criteria, requirements, edge cases, and planning signals when available. +Create or update the work-item intake artifacts under `devspec/work-items//`. Provide one story, feature, bug, security issue, task, PBI, or related post-baseline change request per run; include summary, description, acceptance criteria, requirements, edge cases, and planning signals when available. For existing work items 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). Required user input: -${input:workItemReference:Enter one work item, provider URL or identifier, bug report, feature request, task, or PBI} +${input:workItemReference:Enter one work item, provider URL or identifier, bug report, feature request, task, PBI, or change request} diff --git a/.github/prompts/devspec.tasks.prompt.md b/.github/prompts/devspec.tasks.prompt.md index de2ef20..e75729d 100644 --- a/.github/prompts/devspec.tasks.prompt.md +++ b/.github/prompts/devspec.tasks.prompt.md @@ -9,6 +9,8 @@ Create or update `devspec/work-items//tasks.md` for the curren Apply the [Minimum Necessary Implementation Pattern](PATTERNS.md#minimum-necessary-implementation-pattern): keep tasks scoped to the finalized brief, merge checkpoints that target the same area and validation surface, and avoid standalone refactor, dependency, abstraction, cleanup, or future-proofing tasks unless `finalize.md` requires them. +Apply the [Work-Item Change Request Pattern](PATTERNS.md#work-item-change-request-pattern) for accepted post-baseline change requests: append CR-scoped task rows after the highest existing task ID and preserve completed baseline rows. + Apply the [Task Quality Gate Pattern](PATTERNS.md#task-quality-gate-pattern) before handing off to implementation. Optional user input: diff --git a/README.md b/README.md index b386b80..f246de1 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,8 @@ Then run the work-item flow: /devspec.review ``` +For related scope added after a work item is finalized or later, run `/devspec.story` again with change-request input. Related requests append as `CR-001`, `CR-002`, and so on inside the same work-item folder without rewriting the baseline story, completed tasks, implementation evidence, or review history. Independent requests ask whether to append to the current item, create a new linked work item, or provide `Custom Answer`. + Use `/devspec.clarify` only when a work item records a blocking question. Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, or domain behavior; SVG is the default, with optional Mermaid or HTML via `format=` combinations. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. ## How It Works @@ -78,7 +80,7 @@ Use `/devspec.clarify` only when a work item records a blocking question. Use `/ | Layer | Purpose | Commands | | --- | --- | --- | | Foundation | Capture stable project context, architecture, stack, structure, standards, and rules. | `/devspec.extract`, `/devspec.projectcontext`, `/devspec.techstack`, `/devspec.codebase-structure`, `/devspec.coding-standards`, `/devspec.rules` | -| Work items | Move one feature, bug, or security issue from intake to review. | `/devspec.story`, `/devspec.clarify`, `/devspec.finalize`, `/devspec.tasks`, `/devspec.implement`, `/devspec.review` | +| Work items | Move one feature, bug, security issue, or accepted change request from intake to review while preserving prior scope history. | `/devspec.story`, `/devspec.clarify`, `/devspec.finalize`, `/devspec.tasks`, `/devspec.implement`, `/devspec.review` | ```mermaid flowchart TD @@ -115,7 +117,7 @@ flowchart TD | `/devspec.codebase-structure` | Repository layout, boundaries, multi-repo access, or integration contracts must be recorded. | `devspec/foundation/codebase-structure.md` | | `/devspec.coding-standards` | Engineering standards and observed patterns must be recorded. | `devspec/foundation/coding-standards.md` | | `/devspec.rules` | Operational rules, compliance requirements, governance procedures, and gates must be recorded. | `devspec/foundation/rules.md` | -| `/devspec.story` | A feature, bug, security issue, task, PBI, or provider reference needs intake. | Work-item `meta.md`, `story.md`, `decisions.md`, `notes.md` | +| `/devspec.story` | A feature, bug, security issue, task, PBI, provider reference, or related post-baseline change request needs intake. | Work-item `meta.md`, `story.md`, `decisions.md`, `notes.md` | | `/devspec.clarify` | A blocking question must be resolved. | Work-item `clarify.md` | | `/devspec.finalize` | A work item needs an implementation-ready brief. | Work-item `finalize.md` | | `/devspec.tasks` | A ready brief needs executable tasks. | Work-item `tasks.md` | @@ -238,6 +240,7 @@ Enterprise readiness requires these flows to pass for each supported adapter: - new repository foundation flow - existing repository extraction flow - full story lifecycle +- append-only change-request flow - cross-tool recovery from Git-tracked artifacts Use: diff --git a/devspec/adapters/command-registry.md b/devspec/adapters/command-registry.md index 667c0dc..ebb5053 100644 --- a/devspec/adapters/command-registry.md +++ b/devspec/adapters/command-registry.md @@ -21,12 +21,12 @@ This registry is the provider-neutral contract for all `devspec` adapters. The G | `/devspec.codebase-structure` | Capture repository layout, work areas, boundaries, integration contracts, multi-repo configuration, and access requirements. | Repository layout, work-area, integration, or multi-repo details. | `.github/prompts/devspec.codebase-structure.prompt.md` | `.github/agents/devspec.codebase-structure.agent.md` | `devspec/foundation/codebase-structure.md` | `artifact-write` | `/devspec.coding-standards` | | `/devspec.coding-standards` | Capture evidence-backed engineering standards, observed patterns, anti-patterns, source links, and examples. | Standards input, source links, or evidence to confirm. | `.github/prompts/devspec.coding-standards.prompt.md` | `.github/agents/devspec.coding-standards.agent.md` | `devspec/foundation/coding-standards.md` | `artifact-write` | `/devspec.rules` | | `/devspec.rules` | Capture operational hard constraints, compliance requirements, forbidden patterns, delivery gates, exceptions, enforcement points, source, and confidence. | Rules, gates, governance, compliance, or constraint input. | `.github/prompts/devspec.rules.prompt.md` | `.github/agents/devspec.rules.agent.md` | `devspec/foundation/rules.md` | `artifact-write` | `/devspec.story` | -| `/devspec.story` | Create or update one work-item intake from a provider URL, provider identifier, manual feature request, bug report, security issue, task, or PBI. | One work-item reference or manual intake details. | `.github/prompts/devspec.story.prompt.md` | `.github/agents/devspec.story.agent.md` | `devspec/work-items//meta.md`, `story.md`, `decisions.md`, `notes.md` | `artifact-write` | `/devspec.clarify` if blocked; otherwise `/devspec.finalize` | +| `/devspec.story` | Create or update one work-item intake from a provider URL, provider identifier, manual feature request, bug report, security issue, task, or PBI; append related post-baseline change requests for existing work items without rewriting baseline rows. | One work-item reference, manual intake details, or change-request input for an existing work item. | `.github/prompts/devspec.story.prompt.md` | `.github/agents/devspec.story.agent.md` | `devspec/work-items//meta.md`, `story.md`, `decisions.md`, `notes.md` | `artifact-write` | `/devspec.clarify` if blocked; otherwise `/devspec.finalize` | | `/devspec.clarify` | Ask, resolve, and record one active blocking clarification for an existing work item. | Existing work item with a recorded blocker or clarification need. | `.github/prompts/devspec.clarify.prompt.md` | `.github/agents/devspec.clarify.agent.md` | `devspec/work-items//clarify.md` | `artifact-write` | Repeat until unblocked, then `/devspec.finalize` | -| `/devspec.finalize` | Create or update an implementation readiness brief with readiness assessment, foundation and architecture alignment, implementation brief, validation plan, and blockers. | Existing upstream work-item artifacts. Optional additive readiness input. | `.github/prompts/devspec.finalize.prompt.md` | `.github/agents/devspec.finalize.agent.md` | `devspec/work-items//finalize.md` | `artifact-write` | `/devspec.tasks` when ready | -| `/devspec.tasks` | Break a ready finalized brief into ordered executable implementation tasks with source refs, planning basis, task-quality review, validation, and done criteria. | `finalize.md` marked `ready`; optional task-planning input. | `.github/prompts/devspec.tasks.prompt.md` | `.github/agents/devspec.tasks.agent.md` | `devspec/work-items//tasks.md` | `artifact-write` | `/devspec.implement` | -| `/devspec.implement` | Implement pending tasks for the current ready work item, update implementation and task-quality checkpoints, and confirm after each task. | `finalize.md` marked `ready` and `tasks.md`; optional implementation or validation guidance. | `.github/prompts/devspec.implement.prompt.md` | `.github/agents/devspec.implement-task.agent.md` | `devspec/work-items//implement.md`, task-row status updates in `tasks.md`, code changes when applicable | `code-write` | `/devspec.review` when complete | -| `/devspec.review` | Review implemented work against the finalized brief, tasks, and implementation record, then record review outcome. | `finalize.md`, `tasks.md`, and `implement.md`; optional review focus. | `.github/prompts/devspec.review.prompt.md` | `.github/agents/devspec.review.agent.md` | `devspec/work-items//review.md` | `review-write` | Return to `/devspec.implement` for changes or close the work item | +| `/devspec.finalize` | Create or update an implementation readiness brief with readiness assessment, foundation and architecture alignment, implementation brief, validation plan, and blockers; append CR-scoped readiness and validation rows for accepted post-baseline change requests. | Existing upstream work-item artifacts. Optional additive readiness or change-request input. | `.github/prompts/devspec.finalize.prompt.md` | `.github/agents/devspec.finalize.agent.md` | `devspec/work-items//finalize.md` | `artifact-write` | `/devspec.tasks` when ready | +| `/devspec.tasks` | Break a ready finalized brief into ordered executable implementation tasks with scope, source refs, planning basis, task-quality review, validation, and done criteria; append CR-scoped task rows after existing tasks for accepted change requests. | `finalize.md` marked `ready`; optional task-planning or change-request planning input. | `.github/prompts/devspec.tasks.prompt.md` | `.github/agents/devspec.tasks.agent.md` | `devspec/work-items//tasks.md` | `artifact-write` | `/devspec.implement` | +| `/devspec.implement` | Implement pending tasks for the current ready work item or active CR scope, update implementation and task-quality checkpoints, append evidence, and confirm after each task. | `finalize.md` marked `ready` and `tasks.md`; optional implementation, validation, task-order, scope, or skip guidance. | `.github/prompts/devspec.implement.prompt.md` | `.github/agents/devspec.implement-task.agent.md` | `devspec/work-items//implement.md`, task-row status updates in `tasks.md`, code changes when applicable | `code-write` | `/devspec.review` when complete | +| `/devspec.review` | Review implemented work against the finalized brief, task scope, tasks, implementation record, append-only change-request rules, and changed work, then record review outcome. | `finalize.md`, `tasks.md`, and `implement.md`; optional review focus. | `.github/prompts/devspec.review.prompt.md` | `.github/agents/devspec.review.agent.md` | `devspec/work-items//review.md` | `review-write` | Return to `/devspec.implement` for changes or close the work item | | `/devspec.diagram` | Generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid and HTML output, or batch-generate queued process-flow diagrams when explicitly requested. | Diagram subject, related work item, explicit process-flow batch request, and optional `format=` token containing one or more of `svg`, `html`, and `mermaid` joined by `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. | `.github/prompts/devspec.diagram.prompt.md` | `.github/agents/devspec.diagram.agent.md` | `devspec/architecture/images/dia-NNN-*.svg` by default, optional `devspec/architecture/diagrams/dia-NNN-*.md` for Mermaid, optional `devspec/architecture/html/dia-NNN-*.html`, `devspec/architecture/overview.md` for high-level diagram references, or work-item `images/*.svg`, optional `diagrams.md`, and optional `html/*.html` for temporary work-item diagrams | `diagram-write` | Continue the current workflow | ## Required Flow Gates @@ -35,4 +35,4 @@ This registry is the provider-neutral contract for all `devspec` adapters. The G | --- | --- | --- | | New repository foundation | `/devspec.projectcontext` -> `/devspec.techstack` -> `/devspec.codebase-structure` -> `/devspec.coding-standards` -> `/devspec.rules` | Foundation artifacts exist, no extraction artifact is required, and each command records sources, confidence, blockers, and next action. | | Existing repository foundation | `/devspec.extract` -> `/devspec.projectcontext` -> `/devspec.techstack` -> `/devspec.codebase-structure` -> `/devspec.coding-standards` -> `/devspec.rules` | Extraction evidence is recorded, foundation artifacts are refined, exclusions are respected, blockers are explicit, and confirmations are preserved. | -| Story lifecycle | `/devspec.story` -> optional `/devspec.clarify` -> `/devspec.finalize` -> `/devspec.tasks` -> `/devspec.implement` -> `/devspec.review` | Work-item artifacts exist, readiness is honored, tasks are executable and source-referenced, implementation ledger is current, validation evidence is recorded, task-to-review alignment is checked, and review status uses glossary values. | +| Story lifecycle | `/devspec.story` -> optional `/devspec.clarify` -> `/devspec.finalize` -> `/devspec.tasks` -> `/devspec.implement` -> `/devspec.review` | Work-item artifacts exist, readiness is honored, tasks are executable, scoped, and source-referenced, append-only change requests preserve baseline history, implementation ledger is current, validation evidence is recorded, task-to-review alignment is checked, and review status uses glossary values. | diff --git a/devspec/adapters/validation-flows.md b/devspec/adapters/validation-flows.md index bb4bc9b..70ca588 100644 --- a/devspec/adapters/validation-flows.md +++ b/devspec/adapters/validation-flows.md @@ -51,7 +51,7 @@ Validate one full feature, bug, or security-vulnerability lifecycle after the fo | 1 | `/devspec.story` | `meta.md`, `story.md`, `decisions.md`, and `notes.md` exist under one valid work-item folder; `story.md` records one-story scope, readable intake sections, and observable acceptance criteria or a recorded blocker. | | 2 | `/devspec.clarify` when blocked | `clarify.md` records the active question, answer, resolution, and remaining blockers. | | 3 | `/devspec.finalize` | `finalize.md` records readiness, foundation and architecture alignment, implementation brief, validation plan, assumptions, and blockers. | -| 4 | `/devspec.tasks` | `tasks.md` records task-quality review, source refs, executable tasks with repository, target area, validation, done criteria, dependencies, and status. | +| 4 | `/devspec.tasks` | `tasks.md` records task-quality review, scope, source refs, executable tasks with repository, target area, validation, done criteria, dependencies, and status. | | 5 | `/devspec.implement` | `implement.md` records repository access checks, task quality checks, task ledger, attempts, changed files or areas, validation results, blockers, and resume state; `tasks.md` task-row progress fields stay aligned. | | 6 | `/devspec.review` | `review.md` records findings, scope adherence, task completion alignment, source-ref alignment, validation gaps, rule violations, and review status. | @@ -64,13 +64,41 @@ Acceptance checklist: - `finalize.md` must be `ready` before `/devspec.tasks` plans implementation tasks. - `/devspec.finalize` records or blocks on applicable constitution, foundation, architecture, delivery-gate, repository-readiness, and validation-traceability gaps before marking `ready`. - `/devspec.tasks` does not expand scope beyond the finalized brief and records task-quality checks before implementation handoff. -- `/devspec.tasks` includes source refs from finalized acceptance criteria, implementation brief rows, validation plan rows, risks, or follow-ups for every executable task. +- `/devspec.tasks` includes scope and source refs from finalized acceptance criteria, implementation brief rows, validation plan rows, risks, or follow-ups for every executable task. - `/devspec.implement` respects repository access requirements from `devspec/foundation/codebase-structure.md`. - `/devspec.implement` keeps `tasks.md` task-row status, attempt count, and checkpoint fields aligned with `implement.md`. - `/devspec.implement` records blockers, ambiguity, skipped tasks, oversized task scope, and validation outcomes without silently expanding task scope. - `/devspec.review` reviews against the finalized brief, tasks, implementation record, and changed work instead of re-planning. - `/devspec.review` flags missing task coverage, skipped or blocked tasks without rationale, missing validation evidence, source-ref drift, and implementation beyond task scope when they affect close readiness. +## Append-Only Change Request Scenario + +Validate that post-baseline scope changes preserve the original story ledger. + +| Step | Command | Expected evidence | +| --- | --- | --- | +| 1 | `/devspec.story` with `.NET 10 upgrade` | Baseline `story.md` records the upgrade scope with `AC-*`, `FR-*`, and related planning rows. | +| 2 | `/devspec.finalize` -> `/devspec.tasks` -> `/devspec.implement` | Baseline `finalize.md`, `tasks.md`, and `implement.md` record ready scope, `baseline` task rows such as `T-001..T-003`, and implementation evidence. | +| 3 | `/devspec.story` with `Change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%` | `story.md#change-requests` appends `CR-001`; CR-scoped criteria such as `CR-001-AC-001` are added without rewriting baseline summary, description, or criteria. | +| 4 | `/devspec.finalize` -> `/devspec.tasks` -> `/devspec.implement` | `finalize.md` appends `CR-001` readiness, implementation brief, and validation rows; `tasks.md` appends new `Scope` = `CR-001` rows after the highest existing task ID; `implement.md` appends CR-scoped evidence and execution-log rows while `tasks.md` updates only the matching `CR-001` task rows. | +| 5 | `/devspec.story` with another related request | `story.md#change-requests` appends `CR-002`; task planning later appends new task IDs without renumbering or rewriting `CR-001` or baseline rows. | +| 6 | `/devspec.story` with an unrelated feature request for the same target | The agent asks one structured `selection` question to append to the current item, create a new linked work item, or provide `Custom Answer`; when the linked-item option is chosen, the new work-item folder follows the standard folder naming pattern, its `meta.md#work-item-record` `Parent work item` points to the original item, and the original item does not receive a `CR-###` row for that linked request. | +| 7 | `/devspec.clarify` with post-baseline scope input | `clarify.md` records routing to `/devspec.story`; baseline intake remains unchanged. | +| 8 | `/devspec.review` | Review flags missing CR task rows, missing CR source refs, CR work implemented outside appended tasks, source-ref drift, or overwritten baseline content. | + +Acceptance checklist: + +- `story.md#change-requests` uses disposition values from `devspec/glossary.md#change-request-disposition-values`. +- Related post-baseline changes append `CR-###` rows inside the existing work-item folder. +- Independent or unrelated changes trigger a structured selection before writing. +- Choosing a linked work item creates or updates a separate work-item folder that follows `devspec` folder naming rules and records the original item in `meta.md#work-item-record` `Parent work item`. +- Linked work-item routing does not add a `CR-###` row to the original work item's `story.md#change-requests`. +- Baseline `AC-*`, task rows, implementation evidence, and review evidence remain intact. +- `tasks.md#implementation-tasks` includes `Scope` with `baseline` or `CR-###`. +- New CR task rows append after the highest existing `T-###`. +- `/devspec.implement` processes the active `CR-###` scope without rewriting baseline or prior CR implementation evidence. +- No `/devspec.change` command is introduced or recommended. + ## Cross-Tool Recovery Scenario Use this scenario to prove the framework is tool-neutral. diff --git a/devspec/glossary.md b/devspec/glossary.md index 600d491..d864509 100644 --- a/devspec/glossary.md +++ b/devspec/glossary.md @@ -83,6 +83,17 @@ Use for intake provenance in `meta.md`. | `manual` | User chose manual intake without external resolution. | | `blocked` | Source resolution is required but unavailable or invalid. | +### Change Request Disposition Values + +Use for post-baseline scope changes recorded in `story.md#change-requests`. These values describe the handling decision for a requested scope change, not workflow progress. + +| Status | Meaning | +| --- | --- | +| `accepted` | The request is related to the current work item, or the user explicitly confirmed appending it, and it will be tracked as CR-scoped intake, finalization, tasks, implementation, and review evidence. | +| `rejected` | The request will not be included in the current work item. | +| `superseded` | A later change request or linked work item replaces this request. | +| `withdrawn` | The requester withdrew the change request before implementation or review closure. | + ### Artifact Status Values Use for generated or queued devspec artifacts, including architecture diagram queue rows. diff --git a/devspec/work-items/_template/clarify.md b/devspec/work-items/_template/clarify.md index b348e34..a00077d 100644 --- a/devspec/work-items/_template/clarify.md +++ b/devspec/work-items/_template/clarify.md @@ -10,7 +10,7 @@ Use this artifact only for blocking ambiguity resolution. Keep state in `Resume | Current command | `/devspec.clarify` | | Current agent | devspec.clarify | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | active blocker ID or none | diff --git a/devspec/work-items/_template/finalize.md b/devspec/work-items/_template/finalize.md index 5c410a1..6dbedb1 100644 --- a/devspec/work-items/_template/finalize.md +++ b/devspec/work-items/_template/finalize.md @@ -10,7 +10,7 @@ Use this artifact for readiness, foundation and architecture alignment, implemen | Current command | `/devspec.finalize` | | Current agent | devspec.finalize | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | @@ -45,27 +45,27 @@ Use readiness gates only for checks that decide whether task planning may procee ## Implementation Brief -Use this as the single task-planning input table. Include only facts that affect scope, task decomposition, repository readiness, type-specific requirements, delivery risk, validation, or handoff. Keep local paths and access values in `devspec/foundation/codebase-structure.md`; put validation methods in `Validation Plan`. +Use this as the single task-planning input table. Include only facts that affect scope, task decomposition, repository readiness, type-specific requirements, delivery risk, validation, or handoff. Keep local paths and access values in `devspec/foundation/codebase-structure.md`; put validation methods in `Validation Plan`. Use baseline IDs for original scope and `CR-###-*` IDs for accepted post-baseline change requests; append CR-scoped rows without rewriting prior baseline or CR rows. | Type | ID | Item | Source | Task effect | Status | | --- | --- | --- | --- | --- | --- | -| Scope: in | SCOPE-IN-001 | | | plan within | confirmed | -| Scope: out | SCOPE-OUT-001 | | | exclude | confirmed | -| Acceptance criterion | AC-001 | | | implement and validate | pending | -| Planning input | PI-001 | | | | pending | +| Scope: in | SCOPE-IN-001 or CR-001-SCOPE-IN-001 | | | plan within | confirmed | +| Scope: out | SCOPE-OUT-001 or CR-001-SCOPE-OUT-001 | | | exclude | confirmed | +| Acceptance criterion | AC-001 or CR-001-AC-001 | | | implement and validate | pending | +| Planning input | PI-001 or CR-001-PI-001 | | | | pending | | Foundation constraint | FC-001 | | | | pending | | Architecture constraint | ARCH-001 | | | | pending | | Standards constraint | STD-001 | | | | pending | | Delivery gate | DG-001 | | | | pending | -| Validation requirement | VR-001 | | | validate before completion | pending | +| Validation requirement | VR-001 or CR-001-VR-001 | | | validate before completion | pending | | Repository readiness | MR-001 | | `devspec/foundation/codebase-structure.md` | blocks if missing | pending | | Type-specific requirement | TS-001 | | | plan, validate, or release | pending | -| Risk or follow-up | RISK-001 | | | | open | +| Risk or follow-up | RISK-001 or CR-001-RISK-001 | | | | open | ## Validation Plan -Record validation for acceptance criteria, type-specific requirements, and material risks. Omit unused rows. +Record validation for acceptance criteria, type-specific requirements, and material risks. Omit unused rows. Use `CR-###-VP-###` IDs for change-request validation rows. | ID | Covers | Method or evidence | Expected signal | Status | | --- | --- | --- | --- | --- | -| VP-001 | AC-001 | | | pending | +| VP-001 or CR-001-VP-001 | AC-001 or CR-001-AC-001 | | | pending | diff --git a/devspec/work-items/_template/implement.md b/devspec/work-items/_template/implement.md index 6bcd131..dcd4a32 100644 --- a/devspec/work-items/_template/implement.md +++ b/devspec/work-items/_template/implement.md @@ -10,7 +10,7 @@ Use this artifact for implementation recovery, evidence, and handoff. Keep task | Current command | `/devspec.implement` | | Current agent | devspec.implement-task | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | @@ -21,7 +21,7 @@ Use this artifact for implementation recovery, evidence, and handoff. Keep task ## Implementation Task Ledger -Use this as the recovery view. Keep one row per task from `tasks.md`; source refs, targets, and dependencies stay there. +Use this as the recovery view. Keep one row per task from `tasks.md`; source refs, scope, targets, and dependencies stay there. For change requests, append rows for the active `CR-###` and preserve prior baseline or CR rows. | Field | Value | | --- | --- | @@ -42,7 +42,7 @@ Use this as the recovery view. Keep one row per task from `tasks.md`; source ref ## Implementation Evidence -Record only evidence that exists. Use `Changed file` for targeted edits and `Changed area` for broad edits. +Record only evidence that exists. Use `Changed file` for targeted edits and `Changed area` for broad edits. Append evidence for later `CR-###` work; do not rewrite prior baseline or CR evidence except with explicit correction notes. | Type | Applies to | Item | Evidence or notes | Status | | --- | --- | --- | --- | --- | diff --git a/devspec/work-items/_template/meta.md b/devspec/work-items/_template/meta.md index 85ab8ac..4f91ad7 100644 --- a/devspec/work-items/_template/meta.md +++ b/devspec/work-items/_template/meta.md @@ -53,7 +53,7 @@ Use this section for routing and lookup only; details live in `story.md`. | Current command | | | Current agent | | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | diff --git a/devspec/work-items/_template/review.md b/devspec/work-items/_template/review.md index 0ee4aa2..1dfe1eb 100644 --- a/devspec/work-items/_template/review.md +++ b/devspec/work-items/_template/review.md @@ -10,7 +10,7 @@ Use this artifact for review outcome, actionable findings, and handoff. Omit pla | Current command | `/devspec.review` | | Current agent | devspec.review | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | @@ -21,6 +21,8 @@ Use this artifact for review outcome, actionable findings, and handoff. Omit pla ## Review Outcome +For change-request review, record outcome for the active `CR-###` while preserving prior baseline or CR review evidence. + | Field | Value | | --- | --- | | Status | See `devspec/glossary.md#review-status-values` | @@ -36,7 +38,7 @@ Use this artifact for review outcome, actionable findings, and handoff. Omit pla ## Review Findings -Record only actionable findings; omit placeholder rows when there are none. +Record only actionable findings; omit placeholder rows when there are none. Flag missing CR task rows, missing CR source refs, source-ref drift, CR work implemented outside appended tasks, or overwritten baseline evidence when they affect close readiness. | ID | Severity | Category | Details | Required action | Evidence | Status | | --- | --- | --- | --- | --- | --- | --- | diff --git a/devspec/work-items/_template/story.md b/devspec/work-items/_template/story.md index 3db6b3f..b8f057c 100644 --- a/devspec/work-items/_template/story.md +++ b/devspec/work-items/_template/story.md @@ -10,7 +10,7 @@ Use this artifact for one work item or story at a time. Keep identity and routin | Current command | `/devspec.story` | | Current agent | devspec.story | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | @@ -39,6 +39,14 @@ Use one short statement of the requested story and intended outcome. | --- | --- | | Summary | | +## Change Requests + +Use this section only for post-baseline scope changes after the work item reaches `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`. Append one row per accepted, rejected, superseded, or withdrawn request that is handled inside this work-item folder. Keep baseline story rows unchanged; add CR-scoped acceptance criteria and requirements to the existing tables with IDs such as `CR-001-AC-001`, `CR-001-FR-001`, and `CR-001-NFR-001`. If the user chooses a new linked work item, record the relationship in the linked item's `meta.md#work-item-record` `Parent work item` field instead of adding a `CR-###` row here. + +| ID | Request | Relationship to baseline | Disposition | Source | Recorded | +| --- | --- | --- | --- | --- | --- | +| CR-001 | | related, user-confirmed append, or superseded by linked item | See `devspec/glossary.md#change-request-disposition-values` | user, provider, review, discovery | | + ## Description Record background, user or customer problem, affected scope, impact, and type-specific context. Keep repository access in `devspec/foundation/codebase-structure.md` and rules in `devspec/foundation/rules.md`. @@ -53,7 +61,7 @@ Record background, user or customer problem, affected scope, impact, and type-sp ## Acceptance Criteria -Record specific, testable conditions that must be true for completion. +Record specific, testable conditions that must be true for completion. Use `AC-###` for baseline criteria and `CR-###-AC-###` for change-request criteria. | ID | Criterion | Source | Status | | --- | --- | --- | --- | @@ -61,7 +69,7 @@ Record specific, testable conditions that must be true for completion. ## Functional Requirements -Record expected system behavior. +Record expected system behavior. Use `FR-###` for baseline requirements and `CR-###-FR-###` for change-request requirements. | ID | Requirement | Source | Status | | --- | --- | --- | --- | @@ -69,7 +77,7 @@ Record expected system behavior. ## Nonfunctional Requirements -Record quality attributes such as security, performance, reliability, accessibility, compliance, or scalability. +Record quality attributes such as security, performance, reliability, accessibility, compliance, or scalability. Use `NFR-###` for baseline requirements and `CR-###-NFR-###` for change-request requirements. | ID | Requirement | Source | Status | | --- | --- | --- | --- | @@ -77,7 +85,7 @@ Record quality attributes such as security, performance, reliability, accessibil ## Edge Cases -Record boundary conditions, failure paths, unusual states, and exception handling. +Record boundary conditions, failure paths, unusual states, and exception handling. Use `EDGE-###` for baseline cases and `CR-###-EDGE-###` for change-request cases. | ID | Case | Source | Status | | --- | --- | --- | --- | diff --git a/devspec/work-items/_template/tasks.md b/devspec/work-items/_template/tasks.md index db31fe7..639f796 100644 --- a/devspec/work-items/_template/tasks.md +++ b/devspec/work-items/_template/tasks.md @@ -10,7 +10,7 @@ Use this artifact for executable implementation checkpoints. Keep recovery in `R | Current command | `/devspec.tasks` | | Current agent | devspec.tasks | | Run status | See `devspec/glossary.md#run-status-values` | -| Current item | | +| Current item | baseline or CR-### | | Last completed step | | | Next required action | | | Pending user question | | @@ -36,8 +36,8 @@ Use this gate before handing off. Record material blockers in `Resume State`. ## Implementation Tasks -Use one row per executable checkpoint. Keep rows compact; put traceability in `Source refs`, repository lists in `devspec/foundation/codebase-structure.md`, and only executable proof in `Validation`. +Use one row per executable checkpoint. Keep rows compact; put traceability in `Source refs`, repository lists in `devspec/foundation/codebase-structure.md`, and only executable proof in `Validation`. Use `Scope` to distinguish `baseline` work from append-only change request work such as `CR-001`. For change requests, append new rows after the highest existing `T-###`; do not regenerate, renumber, remove, or rewrite existing task rows. -| ID | Task | Source refs | Target repository | Target area or files | Required access | Depends on | Validation | Done when | Status | Attempt count | Last checkpoint | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| T-001 | | | | | See `devspec/glossary.md#access-requirement-values` | | | | pending | 0 | | +| ID | Scope | Task | Source refs | Target repository | Target area or files | Required access | Depends on | Validation | Done when | Status | Attempt count | Last checkpoint | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| T-001 | baseline or CR-001 | | | | | See `devspec/glossary.md#access-requirement-values` | | | | pending | 0 | | diff --git a/docs/how-to/README.md b/docs/how-to/README.md index d1d41ff..75ab22c 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -15,6 +15,7 @@ This guide is practical usage documentation. The provider-neutral source of trut - [Foundation Flow for a New Repository](#foundation-flow-for-a-new-repository) - [Foundation Flow for an Existing Repository](#foundation-flow-for-an-existing-repository) - [Work-Item Lifecycle](#work-item-lifecycle) +- [Post-Baseline Change Requests](#post-baseline-change-requests) - [Command Examples](#command-examples) - [Diagrams](#diagrams) - [Multi-Repo Work](#multi-repo-work) @@ -249,7 +250,7 @@ Use the work-item lifecycle after the foundation exists. | Step | Command | Gate or note | | --- | --- | --- | -| 1 | `/devspec.story` | Accepts a provider URL, provider identifier, manual feature request, bug report, security issue, task, or PBI. | +| 1 | `/devspec.story` | Accepts a provider URL, provider identifier, manual feature request, bug report, security issue, task, PBI, or related post-baseline change request. | | 2 | `/devspec.clarify` | Use only when intake or finalization records a blocking question. | | 3 | `/devspec.finalize` | Creates the implementation readiness brief. | | 4 | `/devspec.tasks` | Requires `finalize.md` marked `ready`. | @@ -302,6 +303,59 @@ If a blocking question is recorded, resolve it before continuing: /devspec.clarify ``` +Use `/devspec.clarify` only for active blockers inside the current scope. If the user introduces new scope after the work item is finalized or later, route that input through `/devspec.story` as a change request. + +## Post-Baseline Change Requests + +Use `/devspec.story` again when a related request arrives after the baseline work item is finalized, tasks-planned, implementing, implemented, reviewing, or reviewed. Related requests append as `CR-001`, `CR-002`, and so on inside the same work-item folder. The original baseline summary, description, acceptance criteria, completed task rows, implementation evidence, and review history stay intact. + +Canonical command for a related coverage change on an existing .NET 10 upgrade story: + +```text +/devspec.story "Change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%" +``` + +Then continue the normal work-item flow for the active change request: + +```text +/devspec.finalize +/devspec.tasks +/devspec.implement +/devspec.review +``` + +For OpenAI Codex or Cursor, use the same intent as chat input: + +```text +Run /devspec.story with change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%. +Run /devspec.finalize. +Run /devspec.tasks. +Run /devspec.implement. +Run /devspec.review. +``` + +For Gemini CLI: + +```text +/devspec:story "Change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%" +/devspec:finalize +/devspec:tasks +/devspec:implement +/devspec:review +``` + +For Claude Code or Google Antigravity: + +```text +/devspec-story "Change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%" +/devspec-finalize +/devspec-tasks +/devspec-implement +/devspec-review +``` + +If the request appears independent or unrelated, the agent asks one structured selection question before writing: append to the current work item, create a new linked work item, or provide `Custom Answer`. Choose a new linked work item when the request should have its own scope, tasks, implementation record, and review. + ## Command Examples Use these examples as starting points. The command registry remains authoritative for required input, output artifacts, mutation level, and next handoff. @@ -314,12 +368,12 @@ Use these examples as starting points. The command registry remains authoritativ | `/devspec.codebase-structure` | Repository layout, work areas, integration boundaries, access requirements | `devspec/foundation/codebase-structure.md` | `/devspec.coding-standards` | | `/devspec.coding-standards` | Style guides, observed patterns, testing expectations, anti-patterns | `devspec/foundation/coding-standards.md` | `/devspec.rules` | | `/devspec.rules` | Compliance requirements, delivery gates, forbidden patterns, operational governance rules | `devspec/foundation/rules.md` | `/devspec.story` | -| `/devspec.story` | `https://github.com/example/repo/issues/123`; `owner/repo#123`; `JIRA-123`; manual bug report | Work-item `meta.md`, `story.md`, `decisions.md`, `notes.md` | `/devspec.clarify` if blocked, otherwise `/devspec.finalize` | +| `/devspec.story` | `https://github.com/example/repo/issues/123`; `owner/repo#123`; `JIRA-123`; manual bug report; `"Change request for existing .NET 10 upgrade story: increase code coverage from 60% to 80%"` | Work-item `meta.md`, `story.md`, `decisions.md`, `notes.md` | `/devspec.clarify` if blocked, otherwise `/devspec.finalize` | | `/devspec.clarify` | Existing work item with a recorded blocker | Work-item `clarify.md` | Repeat until unblocked, then `/devspec.finalize` | -| `/devspec.finalize` | Existing story artifacts plus optional readiness input | Work-item `finalize.md` | `/devspec.tasks` when ready | -| `/devspec.tasks` | Ready `finalize.md`; optional task-planning guidance | Work-item `tasks.md` | `/devspec.implement` | -| `/devspec.implement` | Ready `finalize.md` and `tasks.md`; optional validation guidance | Work-item `implement.md` and code changes when allowed | `/devspec.review` | -| `/devspec.review` | `finalize.md` and `implement.md`; optional review focus | Work-item `review.md` | Return to `/devspec.implement` for changes or close the work item | +| `/devspec.finalize` | Existing story artifacts plus optional readiness or accepted change-request input | Work-item `finalize.md` | `/devspec.tasks` when ready | +| `/devspec.tasks` | Ready `finalize.md`; optional task-planning or accepted change-request planning guidance | Work-item `tasks.md` | `/devspec.implement` | +| `/devspec.implement` | Ready `finalize.md` and `tasks.md`; optional validation, task-order, or active scope guidance | Work-item `implement.md` and code changes when allowed | `/devspec.review` | +| `/devspec.review` | `finalize.md`, `tasks.md`, and `implement.md`; optional review focus | Work-item `review.md` | Return to `/devspec.implement` for changes or close the work item | | `/devspec.diagram` | Diagram subject, work item, explicit process-flow batch request, or optional `format=` output combination using `svg`, `html`, and `mermaid` | Architecture or work-item SVG diagram artifacts by default, with optional Mermaid or HTML artifacts | Continue the current workflow | ## Diagrams @@ -574,6 +628,7 @@ Before using an adapter for enterprise delivery, validate these flows with the t - New repository foundation flow. - Existing repository extraction flow. - End-to-end story lifecycle. +- Append-only change-request flow. - Cross-tool recovery from Git-tracked artifacts. Use: