diff --git a/.github/agents/devspec.clarify.agent.md b/.github/agents/devspec.clarify.agent.md index d470ef9..20141e9 100644 --- a/.github/agents/devspec.clarify.agent.md +++ b/.github/agents/devspec.clarify.agent.md @@ -16,14 +16,16 @@ 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), [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), [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, recording question intent, option labels, recommended option, and continuation condition. +- 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. +- 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`. - 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. - If no blocking question remains, set `Pending user question` to `none` and record the next handoff in `Next required action`; return to `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`. ## Approach diff --git a/.github/agents/devspec.finalize.agent.md b/.github/agents/devspec.finalize.agent.md index ac2796e..2582a73 100644 --- a/.github/agents/devspec.finalize.agent.md +++ b/.github/agents/devspec.finalize.agent.md @@ -16,21 +16,27 @@ 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), [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#work-item-brief` and `story.md#work-item-details` as the source for intake narrative, acceptance criteria, dependencies, type-specific notes, risks, and blockers. +- 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. - Read `decisions.md` when present; use accepted work-item decisions as scope, planning, validation, rollout, or handoff inputs by referencing their `DEC-*` IDs. - 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 is missing, ambiguous, or unconfirmed. +- 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. - Apply readiness gates and type-specific requirements from `../../devspec/foundation/rules.md`. +- Check applicable alignment sources before readiness: `../../devspec/constitution.md`, `../../devspec/foundation/project-context.md`, `../../devspec/foundation/tech-stack.md`, `../../devspec/foundation/codebase-structure.md`, `../../devspec/foundation/coding-standards.md`, `../../devspec/foundation/rules.md`, `../../devspec/architecture/overview.md`, and relevant `../../devspec/architecture/decisions/*.md` files when their scope intersects the work item. +- Block on conflicts with durable principles, product scope, stack or support constraints, repository boundaries, coding standards, delivery gates, architecture decisions, or unresolved architecture gaps that would materially change scope, task decomposition, validation design, repository readiness, delivery risk, compliance handling, or type-specific rule handling. +- Record material foundation, standards, delivery-gate, validation, and architecture constraints in `Implementation Brief` by source path, section, row ID, or decision ID; do not duplicate full foundation or architecture content. +- 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. - 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; record question intent, option labels, recommended option, and continuation condition when a question is pending. +- Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off. - Keep `finalize.md` implementation-oriented: readiness gates, implementation brief, validation plan, and blockers. +- Do not create a separate command or readiness/alignment artifact for this stage; preserve required `meta.md` workflow-state updates and keep readiness evidence in `finalize.md`. - Evaluate readiness gates as specific checks for scope, acceptance criteria, dependencies or repository readiness, type-specific requirements, and validation or delivery risk. Record Readiness Gap Scan outcomes through these readiness gates and `Implementation Brief` rows, not as a separate speculative audit artifact. - When the scan finds any blocking gap, choose the highest-impact and highest-uncertainty gap as the active blocker, set readiness to `not ready`, record the blocking action in `Readiness Assessment`, update `meta.md` and `finalize.md` resume state, and hand off to `/devspec.clarify`. +- Before surfacing a readiness blocker or structured question, apply the Question Basis Pattern. - Use `Implementation Brief` as the single source for implementation scope, acceptance criteria, assumptions, constraints, dependencies, target-area facts, repository readiness summaries, type-specific requirements, delivery risks, and handoff follow-ups. - Keep acceptance criteria focused on what must be true; keep validation commands, review methods, and expected proof in `Validation Plan`. - Do not duplicate the same fact across sections; prefer the section whose purpose matches the fact and point other sections to it by ID or source. @@ -38,10 +44,10 @@ You create or update `devspec/work-items//finalize.md`. ## Approach 1. Locate the target work item. -2. Read `meta.md` when present, `decisions.md` when present, and required upstream artifacts. +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 and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers. +5. Run the Readiness Gap Scan, 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. @@ -49,6 +55,6 @@ You create or update `devspec/work-items//finalize.md`. ## Output Format - Work-item path updated - Ready status -- Key scope, readiness, validation, and blocker changes +- Key scope, foundation or architecture alignment, readiness, validation, and blocker changes - Blockers or next step - Single registered command, handoff, file update, or structured question diff --git a/.github/agents/devspec.implement-task.agent.md b/.github/agents/devspec.implement-task.agent.md index 1389a32..3e1f122 100644 --- a/.github/agents/devspec.implement-task.agent.md +++ b/.github/agents/devspec.implement-task.agent.md @@ -16,7 +16,7 @@ handoffs: You implement the current work item and update `devspec/work-items//implement.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), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-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 [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. - `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. - Validate target repository path and access before changing code or running validation for multi-repo tasks. @@ -26,6 +26,9 @@ You implement the current work item and update `devspec/work-items//review.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), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-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). -- `finalize.md` and `implement.md` must exist. -- Review against the finalized brief and implemented changes, not a new plan. +- 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. +- `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. - Record findings with severity and required action when applicable. -- Record validation gaps, missing tests, scope drift, security risks, regressions, and follow-ups as `Review Findings`; use `Review Outcome` only for status, summary, scope alignment, validation coverage, and type-specific summary notes. +- 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. - 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; record question intent, option labels, recommended option, and continuation condition when a question is pending. +- Update `Workflow State` in `meta.md` and `Resume State` in `review.md` before recording findings, asking for clarification, or handing off. ## Approach 1. Locate the target work item. -2. Read `meta.md` when present, `finalize.md`, `tasks.md` when present, `implement.md`, existing `review.md`, and relevant code context. +2. Read `meta.md` when present, `finalize.md`, `tasks.md`, `implement.md`, existing `review.md`, and relevant code context. 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state. 4. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern. -5. Check scope adherence, bugs, regressions, security risks, validation gaps, and missing tests. +5. Check task completion alignment, source refs, scope adherence, bugs, regressions, security risks, validation gaps, missing tests, and unnecessary implementation complexity. 6. Record reusable review discovery methods and write `review.md` with `../../devspec/work-items/_template/review.md`. 7. Report per Output Format. ## Output Format -- Work-item path updated -- Review status -- Top findings -- Validation gaps or missing tests -- Next step or handoff -- Single registered command, handoff, file update, or structured question +- Updated work-item artifact path +- Review status with approval, follow-up, or changes-requested outcome +- Task completion and source-reference alignment summary +- Top findings, validation gaps, or unverified risks with severity, evidence, and required action +- Non-blocking follow-ups, if any +- Next action: one registered command, handoff, file update, or structured question diff --git a/.github/agents/devspec.story.agent.md b/.github/agents/devspec.story.agent.md index 52d2241..69c7a00 100644 --- a/.github/agents/devspec.story.agent.md +++ b/.github/agents/devspec.story.agent.md @@ -1,6 +1,6 @@ --- name: "devspec.story" -description: "Use to create or update a devspec work item from a provider URL, identifier, or manual intake." +description: "Use to create or update one devspec work item from a provider URL, identifier, or manual intake." 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 @@ -16,7 +16,7 @@ handoffs: You create or update work-item intake artifacts under `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), [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 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. @@ -24,18 +24,23 @@ You create or update work-item intake artifacts under `devspec/work-items//tasks.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), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-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). +- 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. - `finalize.md` must exist and be marked `ready`. - Do not change or expand the finalized scope. - Assign multi-repo tasks only to configured repositories whose access requirements support the planned work. @@ -22,8 +22,12 @@ You create or update `devspec/work-items//tasks.md`. - Apply planning requirements from `../../devspec/foundation/rules.md#work-item-handling-rules`. - Use `Explore` for quick discovery of impacted code paths, analogous implementations, or verification surfaces. - Use session memory only for transient dependency mapping, open questions, and decomposition notes. -- Update `Workflow State` in `meta.md` and `Resume State` in `tasks.md` before recording a blocker, asking for clarification, or handing off; record question intent, option labels, recommended option, and continuation condition when a question is pending. -- Write tasks as executable checkpoints in `Implementation Tasks` with target repository, target area or files, dependency, validation, and done condition. +- Update `Workflow State` in `meta.md` and `Resume State` in `tasks.md` before recording a blocker, asking for clarification, or handing off. +- Apply the Task Quality Gate Pattern when writing `Task Quality Review` and source-referenced `Implementation Tasks`. +- 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. - 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. @@ -34,11 +38,13 @@ You create or update `devspec/work-items//tasks.md`. 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state. 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 type-specific planning rules and write repository-aware tasks with `../../devspec/work-items/_template/tasks.md`. -7. Report per Output Format. +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`. +8. Report per Output Format. ## Output Format -- Work-item path updated -- Key executable tasks, validations, and done criteria -- Blockers or next step -- Single registered command, handoff, file update, or structured question +- Updated work-item artifact path +- Task quality review result, including any coverage, validation, dependency, or blocker gaps +- Planned task summary with key task IDs, target areas, validation methods, and done criteria +- Open blockers or assumptions that affect implementation +- Next action: one registered command, handoff, file update, or structured question diff --git a/.github/prompts/PATTERNS.md b/.github/prompts/PATTERNS.md index cbb7605..e043a33 100644 --- a/.github/prompts/PATTERNS.md +++ b/.github/prompts/PATTERNS.md @@ -5,9 +5,10 @@ Keep repeated workflow behavior here instead of duplicating it in every prompt o ## Interactive Question Pattern - 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 state that must be recorded before waiting for the 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. - 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. @@ -32,6 +33,17 @@ Standard stage-specific option sets: - Workflow continuation, queue processing, task continuation, generated artifact approval, and retry decisions use `Proceed`, `Skip`, and `Custom Answer` unless a narrower stage-specific set applies. - Resume from `stopped` or ambiguous state uses `Continue`, `Pause`, `Skip`, and `Custom Answer`. +## Question Basis Pattern + +- Use this pattern to justify and record any structured user or developer question. +- Ask only when durable artifacts, configured sources, or repository evidence cannot resolve the issue and the answer would materially change intake, readiness, task planning, validation, repository access, compliance handling, delivery risk, or handoff. +- 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. +- 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 - Recommend one next step. @@ -67,7 +79,7 @@ Standard stage-specific option sets: - Use `paused` when the user expects to continue from the same task or question. - Use `stopped` when the run intentionally ended and should ask one structured `resume` question before resuming. - Use `blocked` only when evidence, access, or prerequisites are insufficient; record the blocker and continuation condition. -- Before any blocking question, handoff, retry-loop stop, or run end, update `Resume State` with stage, item, last completed step, question intent, pending question, exact option labels, recommended option, resume command, continuation condition, and next required action. +- Before any blocking question, handoff, retry-loop stop, or run end, update `Resume State` with stage, item, last completed step, resume command, and the applicable fields required by the [Question Basis Pattern](#question-basis-pattern). - On rerun, resume a `paused` item directly when prerequisites still hold; for `stopped` or ambiguous state, ask one structured `resume` question first. - Retry only when the recorded retry condition is met, the user gives custom direction, or the method materially changed. Do not replay recorded failed methods just because the session changed. - When stage tasks or queue items are complete, mark the stage `complete` and hand off to the next registered command or configured agent. @@ -87,7 +99,7 @@ Standard stage-specific option sets: - Use `extraction-state.md` only for the extraction queue, resume state, blockers, and confirmations. - Keep exactly one extraction queue row `active`. Use existing task status values from `devspec/glossary.md#task-status-values`. - Process extraction queue rows in ID order unless a blocker, confirmation, or explicit user direction changes the next action. -- Before asking a question, blocking, pausing, or handing off, update `Resume State`, the active extraction queue row, and `Blockers and Confirmations` with the question intent, exact option labels, recommended option, and continuation condition. +- Before asking a question, blocking, pausing, or handing off, update `Resume State`, the active extraction queue row, and `Blockers and Confirmations` with the applicable fields required by the [Question Basis Pattern](#question-basis-pattern). - Do not store extracted facts in `extraction-state.md`; write them to the target artifact named by the active queue row. - Do not store reusable discovery methods in `extraction-state.md`; use `devspec/foundation/exploration-state.md`. - Do not store diagram queue state in `extraction-state.md`; use `devspec/architecture/artifact-queue.md`. @@ -99,6 +111,26 @@ Standard stage-specific option sets: - Do not duplicate content already captured in another devspec artifact. Link or name the source instead. - Preserve user-authored content with targeted edits instead of whole-file rewrites. +## Minimum Necessary Implementation Pattern + +- Before planning or changing code, confirm whether the current task requires a repository code change or can be satisfied by artifact updates, configuration already present, documentation, validation, or no action. +- Prefer existing repository patterns, language or platform capabilities, and already-installed dependencies before introducing new abstractions, helper layers, generated code, or dependencies. +- Choose the smallest change that satisfies `finalize.md`, `tasks.md`, applicable validation, and `devspec/foundation/rules.md`; do not add speculative flexibility, cleanup, refactors, or future work unless the finalized brief requires it. +- Never reduce repository access checks, readiness gates, validation, error handling, security, privacy, accessibility, compliance handling, or required recovery state to save tokens or lines. +- Record the selected implementation path, evidence, blockers, validation, and material tradeoffs; omit rejected alternatives unless they explain a risk, blocker, retry, or review finding. + +## 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. +- 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. +- 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. + ## Artifact Content Pattern - Write artifacts for developers who need to plan, implement, review, or recover work. Every captured item should make clear what is true, where it applies, what evidence or source supports it, and what a developer should do with it. @@ -123,7 +155,7 @@ Standard stage-specific option sets: ## Readiness Gap Scan Pattern - Use this pattern during `/devspec.finalize` before marking a work item `ready`; other stages may record obvious blockers, but they must not run a broad readiness audit unless their command contract says so. -- Scan the upstream work-item artifacts, accepted decisions, applicable foundation artifacts, and available repository evidence for gaps in scope boundaries, acceptance criteria, actors or personas, domain and data rules, lifecycle or state behavior, UX/error/empty/loading states, non-functional needs, integrations and external dependencies, security/privacy/compliance, validation testability, terminology consistency, TODO markers, and ambiguous placeholders. +- Scan the upstream work-item artifacts, accepted decisions, applicable foundation artifacts, `devspec/constitution.md`, `devspec/architecture/overview.md`, relevant `devspec/architecture/decisions/*.md`, and available repository evidence for gaps in scope boundaries, acceptance criteria, actors or personas, domain and data rules, lifecycle or state behavior, UX/error/empty/loading states, non-functional needs, integrations and external dependencies, security/privacy/compliance, validation testability, terminology consistency, TODO markers, ambiguous placeholders, and conflicts with durable principles, foundation constraints, delivery gates, or architecture decisions. - Treat a gap as blocking only when resolving it would materially change implementation scope, task decomposition, validation design, repository readiness, delivery risk, compliance handling, or type-specific rule handling. - Do not ask about low-impact preferences, purely stylistic choices, implementation tactics better left to `/devspec.tasks`, or facts already captured in upstream artifacts. - When one or more blocking gaps remain, prioritize by highest implementation impact and uncertainty, then surface only the top unresolved blocking clarification through the current stage's single-question or handoff flow. diff --git a/.github/prompts/README.md b/.github/prompts/README.md index ead0665..70d0116 100644 --- a/.github/prompts/README.md +++ b/.github/prompts/README.md @@ -45,6 +45,7 @@ Developers invoke registered slash commands from this directory. Agent names are - `../../devspec/adapters/validation-flows.md`: enterprise acceptance checklists for new repository, existing repository, story lifecycle, 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#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, output format, Mermaid declaration, SVG target, evidence, confidence, dedupe, tags, and diagram queue rules. - `PATTERNS.md#svg-output-pattern`: standalone SVG output rules, folders, template selection, validation, and forbidden elements. @@ -77,12 +78,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 work-item intake artifacts. | `meta.md`, `story.md`, `decisions.md`, `notes.md` | +| `devspec.story.prompt.md` | Create or update one work-item intake. | `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, implementation brief, validation plan, and blockers. | `finalize.md` | -| `devspec.tasks.prompt.md` | Break a ready brief into executable implementation tasks with planning basis, validation, and done criteria. | `tasks.md` | -| `devspec.implement.prompt.md` | Implement pending tasks and record implementation task ledger state, implementation evidence, execution history, and handoff details. | `implement.md`, code changes | -| `devspec.review.prompt.md` | Review implemented work against the finalized brief. | `review.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.diagram.prompt.md` | Generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, or batch-generate queued process-flow diagrams. | `architecture/diagrams/dia-NNN-*.md` by default; optional `architecture/images/dia-NNN-*.svg` for `format=svg` or `format=mermaid+svg`; `architecture/overview.md` for high-level architecture diagrams; work-item `diagrams.md` and optional `images/*.svg` for explicit or clearly temporary work-item-specific diagram content | ## Maintenance diff --git a/.github/prompts/devspec.finalize.prompt.md b/.github/prompts/devspec.finalize.prompt.md index 66d91fa..985c556 100644 --- a/.github/prompts/devspec.finalize.prompt.md +++ b/.github/prompts/devspec.finalize.prompt.md @@ -5,7 +5,9 @@ argument-hint: "Optional: add reviewer notes, constraints, or finalization guida agent: "devspec.finalize" --- -Create or update `devspec/work-items//finalize.md` for the current work item with implementation-oriented readiness, implementation brief, validation plan, and blockers. +Create or update `devspec/work-items//finalize.md` for the current work item with implementation-oriented readiness, foundation and architecture alignment, implementation brief, validation plan, and blockers. + +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. 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 61298c0..39d9236 100644 --- a/.github/prompts/devspec.implement.prompt.md +++ b/.github/prompts/devspec.implement.prompt.md @@ -5,7 +5,11 @@ argument-hint: "Optional: add implementation, validation, task-order, or skip gu 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. +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. + +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. Optional user input: ${input:implementInput:Optional: add implementation, validation, task-order, or skip guidance} diff --git a/.github/prompts/devspec.review.prompt.md b/.github/prompts/devspec.review.prompt.md index 44b85c3..a146422 100644 --- a/.github/prompts/devspec.review.prompt.md +++ b/.github/prompts/devspec.review.prompt.md @@ -7,5 +7,9 @@ agent: "devspec.review" Review the current work item and update `devspec/work-items//review.md`. +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. + +Apply the [Task Quality Gate Pattern](PATTERNS.md#task-quality-gate-pattern) when reviewing task completion and implementation evidence. + Optional user input: ${input:reviewInput:Optional: add review focus areas, risk notes, or changed files} diff --git a/.github/prompts/devspec.story.prompt.md b/.github/prompts/devspec.story.prompt.md index 1d17f7b..be79ab9 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 a devspec work item from a provider URL, identifier, or manual intake." -argument-hint: "Enter a work item, provider URL or identifier, bug report, feature request, task, or PBI" +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" agent: "devspec.story" --- -Create or update the work-item intake artifacts under `devspec/work-items//`. +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. Required user input: -${input:workItemReference:Enter a 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, or PBI} diff --git a/.github/prompts/devspec.tasks.prompt.md b/.github/prompts/devspec.tasks.prompt.md index 17a9dc5..de2ef20 100644 --- a/.github/prompts/devspec.tasks.prompt.md +++ b/.github/prompts/devspec.tasks.prompt.md @@ -7,5 +7,9 @@ agent: "devspec.tasks" Create or update `devspec/work-items//tasks.md` for the current work item with planning basis and executable implementation tasks. +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 [Task Quality Gate Pattern](PATTERNS.md#task-quality-gate-pattern) before handing off to implementation. + Optional user input: ${input:tasksInput:Optional: add task decomposition guidance} diff --git a/devspec/adapters/command-registry.md b/devspec/adapters/command-registry.md index 0ea9a2a..916232a 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 work-item intake artifacts from a provider URL, provider identifier, manual feature request, bug report, security issue, task, or PBI. | 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. | 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.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, 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 planning basis, 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 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`, code changes when applicable | `code-write` | `/devspec.review` when complete | -| `/devspec.review` | Review implemented work against the finalized brief and record review outcome. | `finalize.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. | 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.diagram` | Generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, or batch-generate queued process-flow diagrams when explicitly requested. | Diagram subject, related work item, explicit process-flow batch request, and optional `format=svg` or `format=mermaid+svg` token. | `.github/prompts/devspec.diagram.prompt.md` | `.github/agents/devspec.diagram.agent.md` | `devspec/architecture/diagrams/dia-NNN-*.md`, optional `devspec/architecture/images/dia-NNN-*.svg`, `devspec/architecture/overview.md` for high-level diagrams, or work-item `diagrams.md` and optional work-item `images/*.svg` 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, implementation ledger is current, validation evidence is recorded, 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 and source-referenced, 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 790bfcb..bb4bc9b 100644 --- a/devspec/adapters/validation-flows.md +++ b/devspec/adapters/validation-flows.md @@ -48,20 +48,28 @@ Validate one full feature, bug, or security-vulnerability lifecycle after the fo | Step | Command | Expected evidence | | --- | --- | --- | -| 1 | `/devspec.story` | `meta.md`, `story.md`, `decisions.md`, and `notes.md` exist under one valid work-item folder. | +| 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, implementation brief, validation plan, assumptions, and blockers. | -| 4 | `/devspec.tasks` | `tasks.md` records executable tasks with repository, target area, validation, done criteria, dependencies, and status. | -| 5 | `/devspec.implement` | `implement.md` records repository access checks, task ledger, attempts, changed files or areas, validation results, blockers, and resume state. | -| 6 | `/devspec.review` | `review.md` records findings, scope adherence, validation gaps, rule violations, and review status. | +| 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. | +| 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. | Acceptance checklist: - Work-item state uses values from `devspec/glossary.md`. +- `/devspec.story` handles one independent story, feature, bug, security issue, task, or PBI per work-item folder. +- `story.md` keeps source tracking, summary, description, acceptance criteria, functional requirements, nonfunctional requirements, edge cases, and planning signals in distinct sections without duplicating routing details from `meta.md`. +- Acceptance criteria captured during intake are specific and testable, or the missing criteria are recorded as a blocker. - `finalize.md` must be `ready` before `/devspec.tasks` plans implementation tasks. -- `/devspec.tasks` does not expand scope beyond the finalized brief. +- `/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.implement` respects repository access requirements from `devspec/foundation/codebase-structure.md`. -- `/devspec.review` reviews against the finalized brief instead of re-planning. +- `/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. ## Cross-Tool Recovery Scenario diff --git a/devspec/foundation/_template/provider-integrations.md b/devspec/foundation/_template/provider-integrations.md index fcc57ba..fecbf80 100644 --- a/devspec/foundation/_template/provider-integrations.md +++ b/devspec/foundation/_template/provider-integrations.md @@ -89,6 +89,6 @@ Offer only these structured `confirmation` actions: | Manual intake | Require external reference, manual description, and manual acceptance criteria. | | Resolved items | Require structured confirmation after showing resolved details. | | Blocked status | Use when input is invalid or required resolution failed. | -| Confirmation result | Record it in `meta.md` and record the shown summary in `story.md`. | +| Confirmation result | Record it in `meta.md` and record the shown provider summary in `story.md#source-record`. | | Provider policy ownership | Keep provider-specific details here instead of duplicating them across prompt files. | | Maintenance trigger | Update this file when provider formats, supported tools, authentication expectations, or fallback policy changes. | diff --git a/devspec/foundation/provider-integrations.md b/devspec/foundation/provider-integrations.md index fcc57ba..fecbf80 100644 --- a/devspec/foundation/provider-integrations.md +++ b/devspec/foundation/provider-integrations.md @@ -89,6 +89,6 @@ Offer only these structured `confirmation` actions: | Manual intake | Require external reference, manual description, and manual acceptance criteria. | | Resolved items | Require structured confirmation after showing resolved details. | | Blocked status | Use when input is invalid or required resolution failed. | -| Confirmation result | Record it in `meta.md` and record the shown summary in `story.md`. | +| Confirmation result | Record it in `meta.md` and record the shown provider summary in `story.md#source-record`. | | Provider policy ownership | Keep provider-specific details here instead of duplicating them across prompt files. | | Maintenance trigger | Update this file when provider formats, supported tools, authentication expectations, or fallback policy changes. | diff --git a/devspec/work-items/_template/clarify.md b/devspec/work-items/_template/clarify.md index 1bd39e4..b348e34 100644 --- a/devspec/work-items/_template/clarify.md +++ b/devspec/work-items/_template/clarify.md @@ -1,6 +1,6 @@ # Clarification Record -Use this artifact only for blocking ambiguity resolution. Keep resumability, handoff, and next action in `Resume State`. Keep active and resolved blockers in `Clarification Log`. Do not duplicate intake or finalization details; reference the impacted artifact and section instead. +Use this artifact only for blocking ambiguity resolution. Keep state in `Resume State`; keep active and resolved blockers in `Clarification Log`. Reference impacted artifact sections instead of duplicating intake or finalization content. ## Resume State @@ -21,8 +21,8 @@ Use this artifact only for blocking ambiguity resolution. Keep resumability, han ## Clarification Log -Use one row per blocker. Keep at most one row with `open` status; resolved, superseded, and withdrawn rows are the history. When no blocker is active, set `Pending user question` in `Resume State` to `none` and use `Next required action` for the handoff target. Open blockers must preserve the structured question intent, exact option labels, `Custom Answer`, and the recommended option with its reason. +Use one row per blocker and at most one `open` row. Open blockers must preserve the question basis: source artifact or evidence, blocking gap, material impact, question intent, option labels including `Custom Answer`, recommended option with reason, impacted artifacts, continuation condition, and next action. When no blocker is active, set `Pending user question` to `none` and put the handoff in `Next required action`. -| ID | Status | Source artifact | Blocking gap | Question | Options | Recommended option and reason | User answer | Impacted artifacts | Updated | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| CLAR-001 | open, resolved, superseded, withdrawn | `story.md`, `finalize.md`, user input, or other source | | | intent; option labels including `Custom Answer` | | | | | +| ID | Status | Source artifact or evidence | Blocking gap | Material impact | Question intent and prompt | Options | Recommended option and reason | User answer | Impacted artifacts | Continuation condition or next action | Updated | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| CLAR-001 | open, resolved, superseded, withdrawn | `story.md`, `finalize.md`, user input, provider evidence, repository evidence, or other source | | | intent and prompt text | option labels including `Custom Answer` | | | | | | diff --git a/devspec/work-items/_template/diagrams.md b/devspec/work-items/_template/diagrams.md index 961909d..e7cedca 100644 --- a/devspec/work-items/_template/diagrams.md +++ b/devspec/work-items/_template/diagrams.md @@ -1,10 +1,8 @@ # Work-Item Diagrams -Use this file only for explicit or clearly temporary work-item diagrams, such as a one-off bug reproduction flow, migration path, security incident or threat flow, temporary implementation plan, or experiment. +Use this file only for explicit or clearly temporary work-item diagrams. -Reusable process flows, feature workflows, module workflows, user journeys, sequences, and state diagrams should live under `devspec/architecture/diagrams/` and be referenced from the work item. Durable SVG companions should live under `devspec/architecture/images/`. - -Do not keep a separate diagram index or status here. `devspec/architecture/artifact-queue.md` owns diagram status from `devspec/glossary.md#artifact-status-values`. This file owns only temporary work-item-specific diagram content and the resume state needed to continue the diagram command. Temporary SVG images belong under `devspec/work-items//images/`. +Reusable diagrams live under `devspec/architecture/diagrams/`; durable SVGs live under `devspec/architecture/images/`. `devspec/architecture/artifact-queue.md` owns diagram status. Temporary SVGs for this work item belong under `devspec/work-items//images/`. ## Resume State @@ -39,24 +37,11 @@ Do not keep a separate diagram index or status here. `devspec/architecture/artif | Assumptions | none or listed below | | Notes | | +Follow `.github/prompts/PATTERNS.md#diagram-extraction-consistency-pattern`, `#mermaid-internal-naming-and-readability-pattern`, `#mermaid-visual-quality-pattern`, and `#svg-output-pattern` when generating content. + ```mermaid -%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#f8fafc', 'lineColor': '#64748b', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155'}}}%% flowchart TD - %% classDef palette - include only roles present in this diagram - classDef ui fill:#083344,stroke:#22d3ee,color:#e2e8f0 - classDef svc fill:#064e3b,stroke:#34d399,color:#e2e8f0 - classDef db fill:#4c1d95,stroke:#a78bfa,color:#e2e8f0 - classDef ext fill:#78350f,stroke:#fbbf24,color:#e2e8f0 - classDef sec fill:#881337,stroke:#fb7185,color:#e2e8f0 - classDef evt fill:#7c2d12,stroke:#fb923c,color:#e2e8f0 - classDef actor fill:#1e293b,stroke:#94a3b8,color:#e2e8f0 - classDef gen fill:#1e293b,stroke:#64748b,color:#e2e8f0 - - %% Pad all node labels and edge labels with   on each side for readability - %% e.g. Svc[" Auth Service "] -->|" Validates "| - %% nodes and subgraphs here - %% cross-subgraph arrows after all subgraph...end blocks - %% class assignments at the end: class Node1,Node2 className + Placeholder["  "] ``` For `format=svg`, omit the Mermaid block content and reference the generated SVG target above. For `format=mermaid+svg`, keep both the Mermaid block and SVG target reference. diff --git a/devspec/work-items/_template/finalize.md b/devspec/work-items/_template/finalize.md index a42ab84..5c410a1 100644 --- a/devspec/work-items/_template/finalize.md +++ b/devspec/work-items/_template/finalize.md @@ -1,6 +1,6 @@ # Implementation Readiness Brief -Use this artifact as the implementation readiness brief. Keep only details that affect readiness, implementation scope, task planning, validation, delivery risk, or handoff. Put lifecycle recovery in `Resume State`, readiness gating in `Readiness Assessment`, implementation facts in `Implementation Brief`, and proof expectations in `Validation Plan`. +Use this artifact for readiness, foundation and architecture alignment, implementation scope, validation expectations, and handoff. Keep lifecycle recovery in `Resume State`, readiness gating in `Readiness Assessment`, task-planning facts in `Implementation Brief`, and proof expectations in `Validation Plan`. Omit unused placeholder rows and reference facts already owned by upstream artifacts. ## Resume State @@ -28,37 +28,43 @@ Use this artifact as the implementation readiness brief. Keep only details that | Priority | features should record priority | | Status | See `devspec/glossary.md#readiness-status-values`; use only `ready` or `not ready` for the overall decision | | Blocking gates | gate IDs or none | -| Next action | `/devspec.tasks` when ready; `/devspec.clarify` or required foundation update when not ready | +| Next action | `/devspec.tasks` when ready; `/devspec.clarify` or required `devspec/foundation/*` or `devspec/architecture/*` artifact update when not ready | | Decision note | | -| Decision inputs | `story.md`, `clarify.md`, accepted `decisions.md` records, `devspec/foundation/rules.md` | +| Decision inputs | `story.md`, `clarify.md`, accepted `decisions.md` records, `devspec/constitution.md`, applicable foundation artifacts, `devspec/architecture/overview.md`, applicable `devspec/architecture/decisions/*.md`, `devspec/foundation/rules.md` | -Use readiness gates only for checks that decide whether task planning may proceed. Populate gates from the Readiness Gap Scan, using only readiness values from `devspec/glossary.md#readiness-status-values`. Record the missing fact or blocking action here; record implementation content in `Implementation Brief`. +Use readiness gates only for checks that decide whether task planning may proceed. Use readiness values from `devspec/glossary.md#readiness-status-values`; put implementation facts in `Implementation Brief`. Overall readiness is `ready` only when every applicable gate is `ready` or `not applicable`. -| ID | Check | Evidence source | Ready condition | Status | Blocking action | -| --- | --- | --- | --- | --- | --- | -| RG-001 | Scope boundary | Implementation Brief | In-scope and out-of-scope boundaries are explicit and do not expand the work item. | See `devspec/glossary.md#readiness-status-values` | | -| RG-002 | Acceptance criteria | Implementation Brief | Criteria are observable or testable enough for task planning and validation. | See `devspec/glossary.md#readiness-status-values` | | -| RG-003 | Dependencies and repository readiness | Implementation Brief; `devspec/foundation/codebase-structure.md` | Dependencies are captured and required repository configuration or access is confirmed or not applicable. | See `devspec/glossary.md#readiness-status-values` | | -| RG-004 | Type-specific facts | Implementation Brief; `devspec/foundation/rules.md` | Feature priority, bug facts, or security-vulnerability facts required by project rules are captured or explicitly blocked. | See `devspec/glossary.md#readiness-status-values` | | -| RG-005 | Validation and delivery risk | Implementation Brief; Validation Plan | Validation expectations and material delivery risks are known enough to plan tasks, or marked not applicable. | See `devspec/glossary.md#readiness-status-values` | | +| ID | Check | Evidence source | Status | Blocking action | +| --- | --- | --- | --- | --- | +| RG-001 | Scope boundary | Implementation Brief | See `devspec/glossary.md#readiness-status-values` | | +| RG-002 | Acceptance criteria | Implementation Brief | See `devspec/glossary.md#readiness-status-values` | | +| RG-003 | Dependencies and repository readiness | Implementation Brief; `devspec/foundation/codebase-structure.md` | See `devspec/glossary.md#readiness-status-values` | | +| RG-004 | Type-specific facts | Implementation Brief; `devspec/foundation/rules.md` | See `devspec/glossary.md#readiness-status-values` | | +| RG-005 | Validation and delivery risk | Implementation Brief; Validation Plan | See `devspec/glossary.md#readiness-status-values` | | +| RG-006 | Foundation and architecture alignment | `devspec/constitution.md`; applicable foundation artifacts; `devspec/architecture/overview.md`; applicable ADRs | See `devspec/glossary.md#readiness-status-values` | | ## Implementation Brief -Use this as the single task-planning input table. Include only facts that affect scope, acceptance criteria, task decomposition, repository readiness, type-specific requirements, delivery risk, or handoff. For multi-repo work, summarize readiness here and keep local paths and access requirement 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`. -| Type | ID | Item | Source | Task-planning or delivery effect | Status | +| Type | ID | Item | Source | Task effect | Status | | --- | --- | --- | --- | --- | --- | -| Scope: in | SCOPE-IN-001 | | | Tasks may be created only for this work. | confirmed | -| Scope: out | SCOPE-OUT-001 | | | Tasks must not be created for this work. | confirmed | -| Acceptance criterion | AC-001 | | | Drives implementation tasks and validation coverage. | pending | -| Planning input | PI-001 | | | | pending | -| Repository readiness | MR-001 | | `devspec/foundation/codebase-structure.md` | Missing or blocked repository readiness prevents task planning. | pending | -| Type-specific requirement | TS-001 | | | Required for task planning, validation, or release handling. | pending | -| Risk or follow-up | RISK-001 | | | | open | +| 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 | +| 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 | +| 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 | ## Validation Plan -Record how acceptance criteria, type-specific requirements, and material risks should be validated. +Record validation for acceptance criteria, type-specific requirements, and material risks. Omit unused rows. | ID | Covers | Method or evidence | Expected signal | Status | | --- | --- | --- | --- | --- | diff --git a/devspec/work-items/_template/implement.md b/devspec/work-items/_template/implement.md index 4c34585..6bcd131 100644 --- a/devspec/work-items/_template/implement.md +++ b/devspec/work-items/_template/implement.md @@ -1,6 +1,6 @@ # Implementation Record -Use this artifact for recovery, audit, and handoff during implementation. Keep lifecycle recovery in `Resume State`, per-task progress in `Implementation Task Ledger`, changed files and validation evidence in `Implementation Evidence`, and attempt history in `Implementation Execution Log`. Omit optional evidence rows with no entries. +Use this artifact for implementation recovery, evidence, and handoff. Keep task targets in `tasks.md`; omit evidence rows with no entries. ## Resume State @@ -21,7 +21,7 @@ Use this artifact for recovery, audit, and handoff during implementation. Keep l ## Implementation Task Ledger -Use this as the single recovery view for implementation progress, current task, last safe checkpoint, and next handoff. Keep one row per task from `tasks.md`. +Use this as the recovery view. Keep one row per task from `tasks.md`; source refs, targets, and dependencies stay there. | Field | Value | | --- | --- | @@ -36,18 +36,19 @@ Use this as the single recovery view for implementation progress, current task, | Roll-forward notes | | | Completion note | | -| Task | Target repository | Target area | Depends on | Status | Attempt count | Last checkpoint | Validation last run | Next action | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | -| T-001 | | | | pending | 0 | | | | +| Task | Status | Attempt count | Last checkpoint | Task quality notes | Validation last run | Next action | +| --- | --- | --- | --- | --- | --- | --- | +| T-001 | pending | 0 | | | | | ## Implementation Evidence -Record only evidence that exists. Use this section for repository access checks, changed files, validation results, type-specific handling, residual risks, follow-ups, and review/audit snippets. Repository path and access requirement source is `devspec/foundation/codebase-structure.md`; type-specific rule source is `devspec/foundation/rules.md`. +Record only evidence that exists. Use `Changed file` for targeted edits and `Changed area` for broad edits. | Type | Applies to | Item | Evidence or notes | Status | | --- | --- | --- | --- | --- | | Repository access | | | | confirmed, missing, blocked | | Changed file | | | | modified | +| Changed area | | | | modified | | Validation | | | | pending, passed, failed, skipped | | Type-specific handling | | | | pending, complete | | Risk or follow-up | | | | open, pending, complete | @@ -56,8 +57,8 @@ Record only evidence that exists. Use this section for repository access checks, ## Implementation Execution Log -Record one row per task attempt, validation run, blocker, retry escalation, pause, skip, completion, or handoff. Failed methods, retry conditions, and next safer methods belong here. +Record one row per task-quality check, attempt, validation, blocker, retry escalation, pause, skip, completion, or handoff. Put recovery details in `Summary` or `Next action`. -| Date | Task | Event | Attempt count | Status | Summary | Evidence refs | Blockers | Failed method and reason | Retry condition or next safer method | Confirmation or handoff | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| | T-001 | attempt, validation, blocker, retry-escalation, pause, skip, completion, handoff | 0 | pending | | | | | | | +| Date | Task | Event | Attempt | Status | Summary | Evidence refs | Next action | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | T-001 | task-quality-check, attempt, validation, blocker, retry-escalation, pause, skip, completion, handoff | 0 | pending | | | | diff --git a/devspec/work-items/_template/meta.md b/devspec/work-items/_template/meta.md index 500a3a4..85ab8ac 100644 --- a/devspec/work-items/_template/meta.md +++ b/devspec/work-items/_template/meta.md @@ -1,10 +1,10 @@ # Work-Item Metadata -Use this artifact as the work-item control record. Keep only the stable work-item record, routing index, and current workflow state. Put detailed intake content in `story.md`, work-item decisions in `decisions.md`, implementation readiness in `finalize.md`, and execution state in `tasks.md` or `implement.md`. +Use this artifact for identity, routing, and workflow state only. Keep narrative, criteria, dependencies, and execution details in their stage artifacts. ## Work-Item Record -Use this section for durable identity, classification, intake provenance, ownership, dates, and links. +Use this section for stable identity, classification, ownership, dates, and links. | Field | Value | | --- | --- | @@ -31,13 +31,13 @@ Use this section for durable identity, classification, intake provenance, owners ## Triage Index -Use this section for routing and lookup only. Keep narrative impact, acceptance criteria, and dependency details in `story.md`. +Use this section for routing and lookup only; details live in `story.md`. | Field | Value | | --- | --- | | Customer impact summary | | -| Affected scope | | -| Affected versions | | +| Routing scope summary | | +| Affected versions source | `story.md#description` | | Multi-repo dependency | yes, no | | Related repositories | repository names only | | Detail source | `story.md` | diff --git a/devspec/work-items/_template/review.md b/devspec/work-items/_template/review.md index 546f9bb..0ee4aa2 100644 --- a/devspec/work-items/_template/review.md +++ b/devspec/work-items/_template/review.md @@ -1,6 +1,6 @@ # Review Record -Use this artifact for review outcome, actionable findings, and handoff. Keep lifecycle recovery in `Resume State`, overall review judgment and non-actionable notes in `Review Outcome`, and required changes or tracked gaps in `Review Findings`. +Use this artifact for review outcome, actionable findings, and handoff. Omit placeholder finding rows when there are no findings. ## Resume State @@ -29,13 +29,15 @@ Use this artifact for review outcome, actionable findings, and handoff. Keep lif | Summary | | | Finalized scope alignment | aligned, drift found, not reviewed | | Validation coverage | complete, gaps found, not reviewed | +| Task completion alignment | aligned, gaps found, not reviewed | +| Source-ref alignment | aligned, drift found, not reviewed | | Type-specific review notes | bug/security/rule notes or n/a | | Follow-up summary | | ## Review Findings -Record required changes, validation gaps, missing tests, scope drift, security risks, regressions, and follow-ups here. Use `Status` values such as `open`, `fixed`, `accepted-risk`, or `follow-up`. +Record only actionable findings; omit placeholder rows when there are none. | ID | Severity | Category | Details | Required action | Evidence | Status | | --- | --- | --- | --- | --- | --- | --- | -| F-001 | critical, high, medium, low | bug, regression, security, validation, test-gap, scope, maintainability, follow-up | | | | open | +| F-001 | critical, high, medium, low | bug, regression, security, validation, test-gap, scope, task-coverage, source-ref, maintainability, follow-up | | | | open | diff --git a/devspec/work-items/_template/story.md b/devspec/work-items/_template/story.md index 118afda..3db6b3f 100644 --- a/devspec/work-items/_template/story.md +++ b/devspec/work-items/_template/story.md @@ -1,6 +1,6 @@ # Work-Item Intake -Use this artifact for detailed work-item intake. Keep identity, classification, source provenance, and routing summaries in `meta.md`; keep work-item decisions in `decisions.md`; keep implementation-ready scope in `finalize.md`. +Use this artifact for one work item or story at a time. Keep identity and routing in `meta.md`; keep decisions in `decisions.md`; keep implementation-ready scope in `finalize.md`. ## Resume State @@ -19,7 +19,7 @@ Use this artifact for detailed work-item intake. Keep identity, classification, | Resume notes | | | Updated | | -## Intake Source Record +## Source Record | Field | Value | | --- | --- | @@ -31,29 +31,66 @@ Use this artifact for detailed work-item intake. Keep identity, classification, | Manual description | | | Manual acceptance criteria | | -## Work-Item Brief +## Summary -Use this section for the durable work-item narrative. Keep it concise but specific enough for clarification and finalization. +Use one short statement of the requested story and intended outcome. | Field | Value | | --- | --- | -| Problem | | -| Intended outcome | | +| Summary | | + +## 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`. + +| Field | Value | +| --- | --- | +| Problem or opportunity | | | User or customer impact | | | Affected components | | | Affected versions | | +| Type-specific context | | + +## Acceptance Criteria + +Record specific, testable conditions that must be true for completion. + +| ID | Criterion | Source | Status | +| --- | --- | --- | --- | +| AC-001 | | confirmed, provider, manual, user | pending | + +## Functional Requirements + +Record expected system behavior. + +| ID | Requirement | Source | Status | +| --- | --- | --- | --- | +| FR-001 | | confirmed, provider, manual, user, discovery | open | + +## Nonfunctional Requirements + +Record quality attributes such as security, performance, reliability, accessibility, compliance, or scalability. + +| ID | Requirement | Source | Status | +| --- | --- | --- | --- | +| NFR-001 | | foundation, intake, rule, user, discovery | open | + +## Edge Cases + +Record boundary conditions, failure paths, unusual states, and exception handling. + +| ID | Case | Source | Status | +| --- | --- | --- | --- | +| EDGE-001 | | confirmed, provider, manual, user, discovery | open | -## Work-Item Details +## Planning Signals -Use this table for facts that affect clarification, readiness, task planning, or validation. Keep repository paths and access requirements in `devspec/foundation/codebase-structure.md`; keep rule definitions in `devspec/foundation/rules.md`. +Record assumptions, dependencies, risks, blockers, type-specific facts, terms, and scope exclusions that affect clarification, finalization, planning, or validation. Omit low-impact notes and unused placeholder rows. | Type | ID | Item | Source | Status | | --- | --- | --- | --- | --- | -| Acceptance criterion | AC-001 | | confirmed, provider, manual, user | pending | | Assumption | ASM-001 | | confirmed, inferred, user | open | -| Constraint | CON-001 | | foundation, intake, user | open | | Dependency | DEP-001 | | intake, user, discovery | open | | Multi-repo dependency | DEP-REPO-001 | yes, no; related repositories: | confirmed, user | open | -| Type-specific note | TS-001 | ; rule source: `devspec/foundation/rules.md` | intake, user, rule | open | | Risk | RISK-001 | | intake, user, discovery | open | | Blocker | BLK-001 | | intake, user, discovery | open | diff --git a/devspec/work-items/_template/tasks.md b/devspec/work-items/_template/tasks.md index 363e823..db31fe7 100644 --- a/devspec/work-items/_template/tasks.md +++ b/devspec/work-items/_template/tasks.md @@ -1,6 +1,6 @@ # Implementation Task Plan -Use this artifact as the executable implementation plan. Keep lifecycle recovery in `Resume State`, source references in `Planning Basis`, and all executable task details in `Implementation Tasks`. Each task should include target, dependency, impacted area, validation, and done condition. +Use this artifact for executable implementation checkpoints. Keep recovery in `Resume State`; keep all task details in `Implementation Tasks`. ## Resume State @@ -21,18 +21,23 @@ Use this artifact as the executable implementation plan. Keep lifecycle recovery ## Planning Basis -| Field | Value | -| --- | --- | -| Implementation brief source | `finalize.md#implementation-brief` | -| Validation source | `finalize.md#validation-plan` | -| Readiness source | `finalize.md#readiness-assessment` | -| Access requirement source | `devspec/foundation/codebase-structure.md` | -| Type-specific rule source | `devspec/foundation/rules.md` | +Sources: `finalize.md#implementation-brief`, `finalize.md#validation-plan`, `finalize.md#readiness-assessment`, `devspec/foundation/codebase-structure.md`, and `devspec/foundation/rules.md`. + +## Task Quality Review + +Use this gate before handing off. Record material blockers in `Resume State`. + +| Check | Evidence or gap | Next action | +| --- | --- | --- | +| Scope and source coverage | | | +| Validation coverage | | | +| Dependency order and granularity | | | +| Blockers, ambiguity, and risk | | | ## Implementation Tasks -Use one row per executable checkpoint. Put likely files or areas, validation steps, and done criteria on the task that owns them. Keep validation commands or methods specific enough for `implement.md` to execute or record. +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`. -| ID | Task | 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 | 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 | |