Spec Loop Plan Task

Use this skill for new work before implementation.

Read this file fully unless it is already loaded in the current session context. Apply project instructions such as AGENTS.md when present.

If these rules are already in context, keep a short digest and re-read only if the digest is missing or the user says the rules changed.

Core rules

• Work starts in PLAN.
• PLAN may change planning artifacts only.
• IMPLEMENTATION requires explicit user approval.
• Non-trivial executable work requires a Spec Loop task.
• Only the user may override these rules.

If AGENTS.md conflicts with these rules, stop and ask the user. If the assistant stops or pauses, explain why.

If the user explicitly asks for a route, planning procedure, or sectioned task format, do not simplify it unless the user explicitly agrees.

After implementation approval, follow spec-loop-implementation-flow/SKILL.md.

Mandatory clarification gate

Before drafting or revising a planning artifact as current truth, check whether any important open decision remains about scope, behavior, policy, conceptual model, conceptual contract boundaries, constraints, route, acceptance logic, or verification.

If yes, do only enough research to frame the open decision clearly and use spec-loop-clarify-task/SKILL.md before continuing. Do not wait for the user to ask for clarification explicitly.

First classification

Classify each work item as one of:

• standalone documentation;
• trivial executable work; or
• non-trivial executable work.

Treat executable work as non-trivial when any of these hold:

• it spans multiple files and is not a straightforward mechanical

edit;

• it needs research or exploration before editing;
• it spans modules, packages, or plugins;
• it changes public or shared APIs;
• it needs targeted test design or verification beyond a mechanical

edit; or

• more than one plausible implementation path exists.

Standalone documentation work is taskless by default unless the user or project rules require a task.

For executable work:

• if it looks trivial, ask: `This looks trivial. May I do this without

a plan?`

• if it is non-trivial, ask: `This looks non-trivial. We should use a

Spec Loop task. May it be chat-only, or do you want a task file?`

Before drafting a task or starting implementation, state the route:

• Planning route: chat-only task
• Planning route: task-file
• Proposed route: taskless, pending your agreement

Do not ask extra permission questions for already requested work, except the route-selection prompts required here.

Phase model

Phases:

• PLAN = research, design/spec, and test specification for

executable work.

• IMPLEMENTATION = approved executable changes and their coupled

updates.

• DONE = verified and accepted.

Rules:

• work starts in PLAN and returns to PLAN after each work item unless

the user says otherwise;

• during PLAN, commands may be used for research or verification only

if they do not change repository contents outside planning artifacts;

• any change to executable behavior, tests, build or config,

dependencies, packaging, runtime assets, or coupled documentation is IMPLEMENTATION and needs explicit user instruction;

• phases are exclusive unless the user allows combined planning and

implementation.

Standalone documentation work is outside this phase model unless the user or project instructions say otherwise.

Re-run the mandatory clarification gate whenever later drafting exposes a new material branch.

Route selection

Choose among:

• taskless handling;
• chat-only task; or
• task-file.

Non-trivial executable work must use either the chat-only route or the task-file route.

Use task-file if any of these hold:

• an active task file already governs the same work item;
• subtasks are needed;
• final clarification or plan state would be unsafe to keep only in

chat;

• research or design is complex enough that a durable artifact is

safer;

• project rules require a task file; or
• the user prefers a task file.

Otherwise chat-only is allowed.

When later executable follow-up appears after a task or subtask already in review or done, or after a chat-only task already presented as ready for User review, return to PLAN and re-run route selection. Reuse the existing task artifact only when the shared follow-up rule in common-task-guidance.md still allows it to govern the same active work item.

Planning content

For executable work, planning must cover:

• current scope;
• material clarified decisions;
• design or implementation direction;
• acceptance logic; and
• verification approach.

Use the shared task guidance from common-task-guidance.md.

Route-specific handling

Taskless

Taskless by default:

• standalone non-executable documentation work; and
• ADR-only work.

For executable work, taskless is allowed only when the work is trivial and the user explicitly agrees.

Chat-only

Use the chat-only route only while canonical task state can safely remain in chat.

When this route is in use:

• read chat-only-path-guidance.md fully; and
• follow it together with common-task-guidance.md.

If durable state becomes unsafe to keep only in chat, switch to the task-file route before continuing.

Task-file

When this route is in use:

• read task-file-path-guidance.md fully;
• use it together with common-task-guidance.md;
• create or update the active task file before executable changes; and
• use tasks/ as the default task directory when project

instructions do not define one.

Before requesting implementation approval on the task-file path, use spec-loop-prepare-implementation-approval/SKILL.md.

Special routing

ADR-only work is taskless by default. Use spec-loop-write-adr/SKILL.md for ADR location, naming, structure, and update rules.

If ADR work is part of a larger executable change, keep it in that task and use spec-loop-write-adr/SKILL.md during IMPLEMENTATION.

Glossary policy

Default glossary policy:

• glossary use is opted in;
• project or session instructions may opt out;
• when the project uses the Spec Loop AsciiDoc glossary format, use

spec-loop-write-glossary/SKILL.md;

• otherwise follow the project's glossary format.

Recognize glossary.adoc and glossary.md as project glossary files. If both exist, ask which one is canonical before updating either.

Once a project glossary exists, treat it as the shared domain-language source above individual tasks and code. If no explicit project glossary exists, use Research plus the existing codebase as the source of current domain language until a project glossary is created.

The presence or absence of a project glossary does not by itself determine whether a task or subtask needs task Glossary. It determines only which shared domain-language source task vocabulary and task-glossary deltas are compared against.

When approved work changes, clarifies, or implements shared domain terms, include any required glossary work in the plan. Perform project glossary file edits during IMPLEMENTATION. If no project glossary exists, create one during IMPLEMENTATION only when the task plan, project instructions, or the User requires project-level glossary work.

When a task or subtask needs Scenario or Glossary, read scenario-and-glossary-guidance.md and follow it. Task Glossary sections are planning artifacts; project glossary file edits happen only during IMPLEMENTATION.

Related skills

Use spec-loop-setup-doc-rendering/SKILL.md for rendering setup.

Chat-only Path Guidance

This file applies only on the chat-only planning path of spec-loop-plan-task.

Read common-task-guidance.md first. That file defines the shared no-subtask main-task form, section semantics, current-increment readiness rules, context-preservation rules, formatting conventions, and the required use of detailed Test specification guidance for both planning paths.

This file covers only chat-only path mechanics: the chat task, Task changes:, reconstruction, later-work handling, and promotion to the task-file path.

User-facing term: chat-only. This is still a full structured Spec Loop task kept in chat, not taskless work.

If the User asks for the sectioned task format, emit the full task in chat. Do not replace a requested chat-only task with an informal short plan.

The task-file prose-wrap requirement does not apply to chat-only work unless the User asks for wrapped lines. Keep chat-only tasks readable and structurally clear.

After implementation approval on the chat-only path, follow spec-loop-implementation-flow/SKILL.md and its chat-only path companion for implementation-time handling, task revisions, Implementation notes, and chat-only review.

Chat-only path mechanics

On the chat-only path, keep the work in chat only while confirmed state can safely remain in chat.

If final clarification decisions kept only in chat would risk loss through compaction or context loss, promote the work to the task-file path before continuing. After that, do not return to the chat-only path for that task.

Canonical chat-only task

• emit an initial canonical chat-only task in chat using the shared

no-subtask main-task form and no diagrams;

• always include the title line and exactly one identifier;
• include any established sections in the exact shared order; on

this initial emission, omitted sections mean not yet established;

• treat that emitted task as the current canonical chat-only task;
• keep only one active chat-only task in the conversation at a

time;

• when the current increment reaches implementation readiness,

present the canonical chat-only task to the User as a request to approve both continuing on the chat-only planning path without creating a task file and moving from planning into implementation from that chat-only task.

When proposing the chat-only path to a User who may not already be informed, include one brief inline note that chat-only avoids task-file overhead for simple work but carries higher chat-alignment risk and may require a full task re-emission or promotion if confidence drops. Do not repeat that note when the User is already informed unless the risk basis materially changes.

Chat-only task revisions

The first chat-only task for a work item is a full task.

Later revisions normally use Task changes: instead of reprinting the full task.

Use this marker:

Task changes:

List only changed sections, in the normal shared task section order. Omitted sections mean unchanged.

Inside each changed section, either:

• use one or more of these labels:
• Added:
• Removed:
• Replaced:

or

• provide the full new section body with no change labels.

Rules:

• Added: adds new text under that section.
• Removed: removes old text from that section.
• Replaced: includes both:
• from: ...
• to: ...
• If a changed section uses no change labels, treat the shown content

as the full new section body.

• Do not mix unlabeled full-section text with Added, Removed, or

Replaced in the same section.

Quote the old and new text so the current chat-only task can be reconstructed without guessing.

The most recent full chat-only task plus later Task changes: blocks is the current task state.

Reprint the full current chat-only task only when:

• the User asks for it;
• reconstruction is no longer safe;
• promotion to a task file needs a full current version; or
• the change cannot be expressed clearly as a change list.

Reconstruction and recovery

If the current chat-only task cannot be reconstructed safely from the most recent full task plus later Task changes: blocks, re-emit a fresh full current task in chat with title, identifier, and all current sections before continuing. If that still does not restore a safe state, promote the work to the task-file path.

Later work relation handling

When new work appears after a chat-only task, first decide whether that earlier task is still an active planning task or has already been presented as ready for User review.

If it has already been presented as ready for User review, use the shared follow-up rule in common-task-guidance.md to decide whether later executable follow-up may stay in the current chat-only task, needs task-file promotion for separate tracked history, or is a new follow-up task.

If it is still an active planning task, use the User's message or later clarification to decide whether the new work extends that task or is a new follow-up task. Ask only when that relation is not clear.

If the work stays in the same chat-only task, keep it there only while chat-only safety still holds. Do not force task-file promotion solely because the earlier implementation created an intermediate state.

If separate tracking within the same overall task is needed, use the task-file path because chat-only work has no subtasks.

If it is a new follow-up task, re-run route selection for that new work item. A new chat-only task may start in chat without creating any task file only when the earlier chat-only task is no longer active and the new task independently still fits the chat-only criteria.

Do not allow two active chat-only tasks at once. If the new work extends the active task or the combined work stops being simple, stay in the same task or promote to the task-file path.

Promotion triggers

If the chat-only path later needs heavier research, more than one plausible implementation path, heavier verification, more than one active task, diagrams that would materially help, or final clarification decisions that would be unsafe to keep only in chat, use spec-loop-plan-task again and promote the task to a task file before continuing.

Example

Good fit because the change is local, there is one clear implementation path, and verification is one targeted regression test plus the normal test run.

# Task: Fix read-only viewer line truncation

- **Task Identifier:** 2026-05-24-viewer-truncation

- **Scope:**
  Prevent the read-only viewer from failing on overlong rendered
  lines.

- **Motivation:**
  The current viewer can fail on long lines. The fix is local and has
  one clear implementation path.

- **Constraints:**
  Keep existing viewer behavior unchanged apart from safe truncation.

- **Briefing:**
  Relevant files: the read-only viewer render path and its tests.

- **Research:**
  The viewer can return lines wider than the terminal width.

- **Design:**
  Truncate rendered lines to the available width before display and
  add one regression test.

- **Test specification:**
  - **Automated tests:**
    - Overlong read-only viewer lines are truncated to the available
      terminal width.
  - **Manual tests:**
    - N/A.

Later clarification on the same task:

Task changes:

- **Constraints:**
  - Added:
    - `Preserve existing color rendering while truncating width.`

- **Design:**
  Truncate only the rendered line width. Do not change content before
  color formatting. Add one regression test.

Example: non-trivial follow-up after a reviewed task-file task

Observed shape:

• an earlier task-file task is already in review or done;
• the User asks for a follow-up change;
• the follow-up spans multiple files or needs exploration; and
• the User wants the next Spec Loop task in chat.

Required assistant behavior:

1. classify the follow-up as non-trivial; 2. say that a Spec Loop task should be used; 3. ask whether it may be chat-only or should use a task file; 4. if the User chooses chat-only, emit the canonical full chat-only task in the shared sectioned format; and 5. do not shorten the work to an informal plan or taskless handling just because the requested change is concrete.

Common Task Guidance

This file applies to executable task planning on both planning paths of spec-loop-plan-task.

It defines the shared no-subtask main-task form, section meanings, current-increment readiness rules, context-preservation rules, formatting conventions, and the required use of detailed Test specification guidance for both planning paths, with any task-file-only formatting rules called out explicitly:

• the chat-only planning path kept in chat; and
• the task-file path.

Task-file-only lifecycle, folders, tracked moves, subtasks, diagrams, and other task-file administration stay in task-file-path-guidance.md.

Current-increment readiness

The active task artifact is the source of truth for the current increment. Design-first allows learning during implementation while the approved Design stays authoritative. Findings that change the intended target lead to updates to the active task artifact and renewed approval before implementation continues.

• On the chat-only path, that artifact is the current canonical

chat-only task in chat.

• On the task-file path, that artifact is the active task file.

Before IMPLEMENTATION, the active task needs: Scope, Motivation, Briefing, implementation-ready Design, Test specification, and any required Research, Scenario, Glossary, Analysis, or Constraints for the current increment — even when the User allows combined phases.

Before asking the User to approve a task for IMPLEMENTATION, the LLM must self-check that the content for the current implementation increment meets all applicable requirements of this file and any path-specific companion rules, and is correct, internally consistent, and compliant with AGENTS.md and applicable glossary rules.

At any point while drafting or revising the active task for the current increment, if any content would depend on an unresolved material branch about scope, behavior, policy, conceptual model, conceptual contract boundaries, constraints, migration, acceptance logic, or verification expectations, it must return to clarification instead of guessing.

If drafting or reviewing Design exposes a new material boundary decision, return to clarification before continuing.

If asking the User to review a draft instead, say so explicitly and list the known gaps, open questions, and unresolved decisions.

Later executable follow-up from review or done

On the chat-only path, the equivalent starting point is a task already presented as ready for User review.

When a task or subtask already in review or done, or a chat-only task already presented as ready for User review, receives a later executable change request, return to PLAN before more implementation.

From review, or from a chat-only task already presented as ready for User review, keep the same task or subtask by default when the User's message or later clarification shows that the follow-up is still the same overall task and the work is not a distinct work item.

From done, ask whether to reuse the same task or subtask or use separate tracking unless the User already specified that choice.

Otherwise ask only when that relation is unclear.

Significant scope change or widening is evidence that the work may be a distinct work item. If that boundary is unclear, clarify in PLAN before choosing whether to keep the same task or use separate tracking.

Discard implementation-created intermediate states from canonical planning artifacts by default. An implementation-created intermediate state alone is not a reason to force separate tracking.

Preserve such a state only when the User explicitly wants history-preserving separate tracking or when a separate governed starting state is actually required.

If separate tracking is needed while the work is still part of the same overall task, recommend a new subtask and wait for explicit User confirmation before creating it. If the work is a distinct work item, recommend a new task and wait for explicit User confirmation before creating it.

If the same task or subtask is kept, update the governing artifact in PLAN, discard any implementation-created intermediate state from canonical planning sections, and seek renewed implementation approval before more executable work.

Task artifact structure and sections

Each task without subtasks uses this exact order and layout. Do not add extra metadata fields or custom readiness markers unless the User explicitly requests them. Use the exact bold-label section labels below.

• Title line: # Task: <title>.
• One identifier (mutually exclusive):
• - **Ticket:** Ticket ID, preferred.
• - **Task Identifier:** if no Ticket;

YYYY-MM-DD-<slug> where <slug> is 1-2 keywords from the task title or intended filename.

• Value present = Primary Identifier for commit messages.
• Main task sections as bold-label list items in this order:
• - **Scope:**
• - **Motivation:**
• - **Scenario:** (conditional; use when behavior, flow,

boundaries, or user-visible outcomes need grounding)

• - **Glossary:** (conditional; use with Scenario when shared

domain terms are introduced, changed, or redefined)

• - **Constraints:** (optional; important limits Design and

implementation must obey)

• - **Briefing:**
• - **Research:**
• - **Analysis:** (conditional; include it when final

clarification decisions exist for the current increment)

• - **Design:**
• - **Test specification:**
• - **Implementation notes:** (conditional; include it when the

post-implementation checkpoint finds meaningful notes content) When a conditional or optional section is omitted, omit it entirely and keep the remaining sections in the order listed above.

The ### headings below are guidance-document headings only. In task artifacts, these sections must be bold-label list items such as - **Design:**, not Markdown headings. This keeps task files with subtasks from creating extra heading levels under each subtask.

Task-file-only subtask rules stay in task-file-path-guidance.md.

Task-section descriptions below follow this order. Extra cross-section guidance appears near the sections it affects. This is not drafting order. Draft sections in whatever order gives accurate content. For example, finalize Briefing after research when research identifies relevant modules, conventions, or risks.

Scope

Defines the current increment's boundaries: what is included, what is excluded, and which user-visible or system behavior is in scope.

Motivation

Explains why the change is needed. Use confirmed user intent, observed defects, project goals, or clearly marked inference.

Scenario

Scenario explains what happens and grounds domain language before implementation. Keep it concise, implementation-free, and behavior-first.

Use Scenario when behavior, flow, boundaries, or user-visible outcomes are introduced, changed, or clarified.

If behavior changes but shared vocabulary does not, keep Scenario only. If neither behavior nor shared vocabulary changes, omit both Scenario and Glossary. Prefer Scenario over Glossary when only one section is needed. Do not use Glossary without Scenario by default.

Across the whole task artifact, use domain-related words for planned behavior and structure. When referring to planned or changed production types, use exact intended class, interface, and enum names, not stand-ins or generic role placeholders.

Research may mention legacy terms. Analysis and Design use only canonical Scenario and Glossary terms except explicit legacy-to-target mapping tables. If code uses different names, align incrementally and document intentional mismatch in the active task artifact.

Glossary

Use task Glossary when the current increment introduces or changes review-relevant shared domain terms, or exact external technical terms whose precise type or API is part of the reviewed contract, relative to the current shared domain-language source.

Before approval seeking, if the term-reduction and classification pass finds such a qualifying term delta and task Glossary is absent, add Scenario and task Glossary before continuing.

When used:

• include Scenario too;
• write or update both together;
• place Glossary immediately after Scenario; and
• follow

scenario-and-glossary-guidance.md.

Task Glossary is delta-only relative to the current shared domain-language source. Do not redefine unchanged terms from that source.

For glossary sources, extension points, and candidate-term selection rules, follow scenario-and-glossary-guidance.md.

Project glossary policy

Follow SKILL.md for glossary-file recognition and glossary-format routing.

Current shared domain-language source:

• if a project glossary exists, use it;
• otherwise use Research plus the existing codebase until a project

glossary is created.

Once a project glossary exists, use it as shared task language above individual tasks and code. Do not add helper names, implementation details, framework terms, or terms not needed to explain project rules, behavior, or subsystem boundaries.

If glossary work is required for the current task:

• reflect it in the task plan; and
• during IMPLEMENTATION, follow SKILL.md rules for project glossary

creation or update.

If a project glossary update would change approved meaning rather than record it, return to PLAN first.

If the task plan is missing required glossary work, return to PLAN, update the task, get approval, and continue.

Constraints

Use for important limits Design and implementation must obey. Typical content: semantic invariants, non-goals, compatibility limits, performance limits, identity rules, forbidden simplifications.

Briefing

Short orientation for someone unfamiliar with the codebase: relevant modules, important classes, framework context, repo conventions, risk areas.

Finalize Briefing late in PLAN, shortly before seeking implementation approval, after Research, Design, and Test specification are coherent. Keep target-state plans in Design, not Briefing.

Research

Research and clarification are iterative. Do enough clarification to know the research scope, then research the current system and return to clarification whenever findings expose material choices about intent, scope, constraints, design, acceptance logic, or verification.

Record observations, constraints, verified facts, and findings about the original pre-implementation state only. Plans go in Design. Documents the original pre-implementation system state for the governed increment: behavior, implementation, legacy arch, flows, data structures, findings, and constraints.

Do not record repository states created during the current increment in canonical Research. If later clarification, implementation, or review reveals new relevant facts about the original pre-implementation state, extend Research with those facts only.

Do not repeat Analysis points here in decision-and-reason form.

Analysis

Authoritative ledger of final clarification decisions and reasons.

Use one short bullet per final decision: - <decision> because <reason>.

Keep only final decisions here. Move structural, behavioral, contract, and verification consequences into the affected canonical sections and diagrams.

Analysis is read together with the other sections:

• do not repeat Analysis points in other narrative text; but
• the affected sections and diagrams must still contain names,

structures, contracts, lists, tables, diagram content, and test cases when those are the actual consequences of the decision. Do not put open questions, options, confidence values, tentative assumptions, or transient working notes here.

When a final clarification decision changes another section or diagram, update that section or diagram to reflect the resulting state. Diagrams should reflect any relevant textual decisions they own. Clarification workflow and recording procedure belong to spec-loop-clarify-task.

Design

Documents target system: architecture, data structures, data flow, interactions, implementation boundaries. Draft from validated Research and Scenario behavior, using Glossary when present.

Design = implementation contract. Must be reviewable and implementation-ready.

Design must follow Constraints and Analysis when they are present. If Design conflicts with either, fix Design or return to clarification.

Design must describe only the current intended end state for the governed increment. Do not describe repository states created during the current increment, including staged refactor states or transformations such as S1 -> S2. If such an intermediate state must be preserved, use a new task or subtask where that state can appear as Research. Implementation detours that do not belong in canonical sections may go in Implementation notes when relevant.

Use only final intended names for design-owned terms, units, config keys, tool/API names, request/response fields, enum values, etc. Prefer domain-related words and exact intended class names. No placeholders, temp names, candidate names, example names, or generic stand-ins such as Controller, Collaborator, Helper, Manager, or Processor unless they are established domain or framework terms that the design explicitly depends on. Undecided name/unit/boundary = not ready for implementation.

If finding an exact name is hard, treat that as a design defect. Change the design until responsibilities and boundaries admit precise names, and immediately plan the required refactoring in the active artifact. Resolving precise domain language and exact structural names is the highest priority during design work.

When production structure changes, Design must make the structural inventory explicit for every planned new or changed top-level production class, interface, enum, and every new or changed externally meaningful identifier in scope. In class diagrams, put review-relevant methods and fields of displayed types in the diagram itself. On the task-file path, follow task-file-path-guidance.md for the rules that govern diagrams, allowed non-diagram text, and local ordering between a diagram and its related text in Research and Design. Examples of externally meaningful identifiers include persisted file names, serialized field names, config keys, action keys, menu placeholder names, and shared session/state flags.

Local variables, private methods, private fields contained within one class, and other purely internal implementation details are excluded from this inventory unless the User explicitly requests lower-level review.

Test-only elements go in Test specification, not Design, unless task changes test infrastructure.

When changing tools/APIs/serialized payloads, Design must show full target request/response structures and enums. Examples supplement, don't replace spec.

When Scenario or Glossary exists, Design uses their canonical terms. Do not redefine Glossary terms in Design.

Every new review-relevant term introduced in Design must remain classifiable under scenario-and-glossary-guidance.md. Before approval seeking, the active task must complete the term-reduction and classification pass required there. If any such term cannot be classified, treat it as a design defect.

Internal implementation terms may appear only in implementation-level design such as class-level structure. Do not use them as if they were domain language in Scenario, task Glossary, or behavior-level diagrams and prose.

Test specification

Specifies how the current task's requirements and task-relevant modified code paths are verified.

Before drafting or revising Test specification, you must read and follow test-specification-guidance.md.

Separate automated verification cases from optional human-reader hints:

• Automated tests = task-specific automated verification cases, not

execution commands, framework names, or pass/fail status.

• Manual tests = optional checks a human reviewer may perform after

handoff. They do not block review and must not be reported as done unless actually performed.

Implementation notes

Conditional execution-phase notes. This section is filled only at the post-implementation checkpoint under the spec-loop-implementation-flow skill. It is not part of the canonical planning truth. If present, it describes the current implementation state, not the target state in canonical sections. Its content may still be relevant context for follow-up tasks and, on the task-file path, subtasks. Detailed behavior is governed by that skill and is not repeated here.

Iterative discovery

Iterate across Research, Scenario (if used), Glossary (if used), Analysis (if used), Design, and Test specification until coherent. Record intermediate alternatives only when they aid reasoning or review. No implementation during this loop.

Context Preservation

• Re-read relevant task sections before implementation or when

requirements are unclear.

• When a task uses subtasks, re-read the relevant main-task sections

and diagrams before working from the active subtask. Do not assume the subtask repeats all required context.

• Active task artifact = working source of truth for the current

item.

• Older task files or superseded chat-only task states = historical

records; they need not stay consistent with the active artifact when superseded.

• Keep only relevant task content in active context.

Formatting

• Task-file artifacts must wrap prose to roughly 72-80 characters and

avoid horizontal scrolling. Chat-only work in chat does not need a fixed wrap width unless the User asks for it, but it must remain readable and structurally clear.

• Preserve semantic line breaks and consistent list indentation.
• Fenced code blocks: start/end with backticks. For top-level content,

use flush-left fenced code blocks. When a fenced code block belongs to a list item, indent the opening fence, block content, and closing fence to that list item's content indentation so the block remains inside the list item.

• Standalone paragraphs unindented. List continuation lines may

indent to align. After a fenced code block inside a list item, resume either the same list-content indentation or true top-level indentation.

• Render correctly in chat markdown and in GitHub and GitLab task

views.

Intent: readable in plain text editors (vim, less, nano), chat views, and rendered markdown views.

Example task: Wordle CLI adapter with embedded diagrams

This compact example task shows valid embedded Mermaid and PlantUML for common task-diagram needs. It is primarily a collection of valid diagram patterns in a realistic task context, not a required minimum task size and not a signal that every first planning pass should be this detailed.

It covers:

• task Glossary with Mermaid visual glossary
• filesystem / project structure
• component interaction
• class structure
• sequence flow

It also demonstrates the Markdown-sensitive case where task sections are list items, diagrams stay inside those list items, and more bullets follow the diagrams without rendering as code blocks.

Keep different concerns in separate diagram blocks instead of mixing diagram types.

PlantUML writing hints:

• Follow the PlantUML-specific rules in

task-file-path-guidance.md.

• This example keeps line-oriented PlantUML statements on one physical

line.

• If rendering fails, fix the diagram before treating the task as ready

for review.

• Scope: Add a CLI adapter for Wordle that starts a game, reads

guesses from standard input, renders CLI feedback, and keeps gameplay rules in the existing engine and domain classes.

• Motivation: This example demonstrates current task structure and

diagram patterns that render reliably in Markdown task files.

• Scenario: A player starts the application in CLI mode, enters

guesses one line at a time, sees CLI feedback after each guess, and the session ends when the word is solved or attempts are exhausted. Optional flags choose the word list path and attempt count.

• Glossary:
• CLI mode: application mode where the player enters guesses

through standard input and reads CLI feedback in the terminal.

• In CLI mode, the player enters one guess per input line.
• In CLI mode, the session ends when the word is solved or

attempts are exhausted.

• CLI feedback: terminal-visible rendering of one guess result.
• CLI feedback is shown after each guess.
• CLI feedback belongs to the CLI adapter, not to the gameplay

rules.

• Word list path: optional CLI input selecting the source word

list.

• The word list path is chosen through a CLI flag.
• Attempt count: optional CLI input selecting the allowed number

of guesses.

• The attempt count is chosen through a CLI flag.

  flowchart LR
      subgraph actor[Actor]
          P[Player]
      end

      subgraph cli[CLI concepts]
          CM[CLI mode]
          FT[CLI feedback]
          WLP[Word list path]
          AC[Attempt count]
      end

      P -->|uses| CM
      CM -->|shows| FT
      CM -->|selects| WLP
      CM -->|selects| AC

• Constraints:
• Gameplay rules remain in domain classes.
• The CLI adapter may format output, but it must not reimplement

evaluation logic.

• The UI path must stay replaceable by a later Swing adapter.
• Briefing: The project already contains a reusable game engine and

a packaged word list. The CLI adapter must depend on the application and domain layers without moving gameplay logic into the UI path.

• Research:

  @startuml
  left to right direction

  folder "wordle-tutorial" {
    file "settings.gradle.kts"
    file "build.gradle.kts"
    folder "src/main/java" {
      folder "wordle/tutorial/app" {
        file "WordleApplication.java"
      }
      folder "wordle/tutorial/domain" {
        file "Game.java"
        file "GameEngine.java"
        file "Guess.java"
        file "Feedback.java"
        file "Word.java"
      }
    }
    folder "src/main/resources" {
      file "wordlist.txt"
    }
    folder "src/test/java" {
      folder "wordle/tutorial/domain" {
        file "GameEngineTest.java"
      }
    }
  }
  @enduml

  @startuml
  component "CLI Adapter" as cli
  component "Application Entry Point" as app
  component "Game Engine" as engine
  component "Word List Loader" as loader
  database "Packaged Word List" as words

  cli --> app : start game / submit guess
  app --> engine : create game / evaluate guess
  app --> loader : load candidate words
  loader --> words : read resource
  @enduml

Research notes:

• The repository already separates application wiring from domain

logic.

• No CLI-specific adapter classes exist yet.

• Analysis:
• CLI mode stays a thin adapter because gameplay logic must remain

reusable in the existing engine.

• CLI feedback is rendered in adapter classes because presentation

belongs in the UI path, not in domain classes.

• Only --cli, --wordlist, and --attempts are supported because

the example should keep the external CLI contract minimal and reviewable.

• Design:

  @startuml
  left to right direction

  folder "src/main/java" {
    folder "wordle/tutorial/app" {
      file "WordleApplication.java"
      file "CommandLineOptions.java"
    }
    folder "wordle/tutorial/cli" {
      file "CliGameLoop.java"
      file "FeedbackRenderer.java"
    }
    folder "wordle/tutorial/domain" {
      file "Game.java"
      file "GameEngine.java"
      file "Feedback.java"
      file "Word.java"
    }
  }
  @enduml

  @startuml
  set separator none

  package "wordle.tutorial" {
    package "app" {
      class WordleApplication {
        + main(args)
      }
      class CommandLineOptions {
        + cliMode : boolean
        + wordListPath : String
        + attempts : int
      }
    }

    package "cli" {
      class CliGameLoop {
        + run()
      }
      class FeedbackRenderer {
        + render(feedback) : String
      }
    }

    package "domain" {
      class Game {
        + applyGuess(guess)
      }
      class GameEngine {
        + submitGuess(guess) : Feedback
      }
      class Feedback
      class Word
    }
  }

  WordleApplication --> CommandLineOptions : parses CLI options
  WordleApplication --> CliGameLoop : starts
  CliGameLoop --> GameEngine : uses
  CliGameLoop --> FeedbackRenderer : uses
  GameEngine --> Game : creates / updates
  GameEngine --> Word : validates
  Game --> Feedback : records
  @enduml

  @startuml
  actor Player
  participant "CliGameLoop" as CliGameLoop
  participant "GameEngine" as GameEngine
  participant "Game" as Game
  participant "FeedbackRenderer" as FeedbackRenderer

  Player -> CliGameLoop : enter guess
  CliGameLoop -> GameEngine : submitGuess(guess)
  GameEngine -> Game : applyGuess(guess)
  Game --> GameEngine : updated state + feedback
  GameEngine --> CliGameLoop : game state + feedback
  CliGameLoop -> FeedbackRenderer : render(feedback)
  FeedbackRenderer --> Player : CLI feedback
  @enduml

Externally meaningful identifiers:

• --cli
• --wordlist
• --attempts

• Test specification:
• Automated tests:
• Missing optional CLI arguments use default wordlist and attempt

values.

• Invalid CLI argument values are rejected with user-facing

feedback.

• CLI feedback rendering matches the engine guess result.
• CLI mode delegates valid guess validation and scoring to the

existing engine.

• Manual tests:
• Start the CLI and complete one short game from the terminal.

Scenario and Glossary Guidance

This file applies only after common-task-guidance.md has already established that the current task or subtask needs Scenario or Glossary.

This file covers only the extra drafting guidance. It does not repeat:

• when these sections are required;
• task section order; or
• project glossary update timing.

Working method

1. Draft Scenario first. 2. If Glossary is present or becomes required, draft or update it using the Glossary drafting rules below. 3. Before approval seeking, complete the term-reduction, term-classification, and glossary-repair pass defined in Glossary drafting. 4. Re-read Scenario, Glossary, Research, Design, and Test specification together and remove term drift.

Scenario drafting

• Write behavior, boundaries, and outcomes.
• Keep it concise and implementation-free.
• Make terms understandable through usage in the scenario.
• Do not describe review workflow, document workflow, or code

structure there.

• Reuse unchanged current domain terms instead of inventing local

synonyms.

• If no explicit project glossary exists, use Research plus the

existing codebase as the source of current domain terms.

Glossary drafting

• Place Glossary immediately after Scenario.
• Keep it delta-only relative to the current shared domain-language

source:

• the project glossary, when one exists; otherwise
• Research plus the existing codebase.
• Do not redefine unchanged terms from that source.
• Reuse existing canonical terms from the shared domain-language

source whenever they fit. If none fits, use ordinary prose unless the design introduces a new review-relevant design element that needs a stable exact name. If a new term is still needed, add it to task Glossary when it qualifies under the glossary rules.

• Build glossary candidates from:
• Scenario;
• Design and Test specification when they introduce shared

domain terms needed to understand or verify behavior; and

• Research and Design when they reference exact external types

or APIs that are part of the reviewed contract.

• For this guidance, review-relevant excludes local variables, private

members contained within one class, and other implementation-local details already excluded from Design review.

• Term reduction decides whether a coined term should remain.

Classification answers what a kept term is.

• Before approval seeking, explicitly classify every new

review-relevant term kept in Design, diagrams, or Test specification as exactly one of:

• shared domain term = stable behavior or contract concept shared

across Scenario, Design, or Test specification;

• exact external technical term = exact external type or API; or
• internal implementation term.
• Record that classification by repairing the canonical sections,

rather than by adding a separate classification table, unless the User asks for one:

• shared domain term = ensure Scenario uses the term; when the

current increment introduces or changes it relative to the shared source, include it in task Glossary;

• exact external technical term = include it in task Glossary only

when the exact external type or API is part of the reviewed contract;

• internal implementation term = keep it only in

implementation-level design such as class-level structure. Do not use it in Scenario, task Glossary, or behavior-level diagrams and prose.

• Task Glossary may also include task-specific usage constraints not

yet canonicalized project-wide.

• If a new review-relevant term in Design, diagrams, or `Test

specification` is missing this classification or the classification is ambiguous after that pre-approval pass, the task is not approval-ready.

• For each entry, write:
• the term;
• a short meaning; and
• usage bullets grounded in the reviewed behavior or contract.
• For an exact external technical term added to task Glossary, keep

the term text unchanged. In the short meaning, use the words shared term from <source>, where <source> names the external library, API, or contract. Do not put the source in the term label itself.

Task-file visual glossary

• On the task-file path, when Glossary is present, include at least

one focused Mermaid visual glossary directly under it.

• Apply the Mermaid diagram rules from

spec-loop-write-glossary/glossary-format.md to task visual glossaries too.

• In particular:
• keep the diagram consistent with the glossary text;
• update the diagram in the same change when glossary

relationships, boundaries, actors, or flows change;

• use the diagram as focused visual context, not as the source of

truth;

• prefer several small diagrams over one crowded graph;
• if the diagram has nodes outside the main area, group them into

semantically correct subgraphs;

• label every Mermaid connection;
• keep Mermaid node labels as plain text; and
• do not rely on Mermaid click or href links for navigation.

Quality checks

Consistent reuse of approved terms across the shared glossary source, Scenario, Design, and Test specification keeps meaning, behavior, design contracts, and verification aligned.

• Scenario and Glossary use one vocabulary, not parallel synonyms.
• Glossary terms are grounded in the reviewed behavior or contract.
• Design and Test specification reuse approved terms.
• Design does not redefine Glossary terms.
• Task visual glossaries follow the Mermaid rules above.

Task-file Path Guidance

This file applies only on the task-file path of spec-loop-plan-task.

Read common-task-guidance.md first. That file defines the shared no-subtask main-task form, section semantics, current-increment readiness rules, context-preservation rules, formatting conventions, and the required use of detailed Test specification guidance for both planning paths.

This file adds only task-file-specific mechanics: task files, lifecycle, tracked moves, subtasks, task-file-only testing additions, and diagram rules.

After implementation approval on the task-file path, follow spec-loop-implementation-flow/SKILL.md and its task-file path companion for implementation-time handling, task-file updates, Implementation notes, and the move into review.

Task-file path readiness

On the task-file path, the task file is the source of truth for the current increment.

When a task file has or may have subtasks, do not infer the active increment or subtask status from the folder path. Before identifying the active increment, claiming lifecycle status, moving a task or subtask status, seeking implementation approval, or presenting completion, search the file for subtask heading and status lines:

rg -n '^## Subtask:|^- \*\*Status:\*\*' <task-file>

Use the folder path as task-level status only. Use subtask - **Status:** lines as subtask-level status. If a task in review has an in-progress subtask, state both statuses explicitly and use the active subtask plus needed task-level context as the controlling increment.

Backlog tasks may keep Research and Design high-level or To be done until current. Omit Analysis until final clarification decisions exist.

In tasks with subtasks, the shared readiness rules apply to the active subtask and any task-level context it depends on, not to future subtasks that are not yet current.

During clarification on the task-file path, the active task file is the governing artifact. Follow spec-loop-clarify-task/SKILL.md for clarification batching and recording rules.

Keep the task file aligned with the current final clarification state, including the Analysis section and every affected canonical section. Sync at a clean checkpoint before that state would be hard to reconstruct safely from chat alone, and always before clarification returns control to another workflow.

These sync edits preserve state. Do not ask the User to review them separately during clarification. If unresolved questions remain after a sync, continue clarification from the updated task file.

Task Artifacts and Administration

1. Task files

Task files live under the project task directory.

Top-level folders: backlog, in-progress, review, done.

• Only backlog may have subfolders.
• Backlog subfolder names are organizational only.
• Backlog numbering optional; if used, readable three-digit prefix

local to containing folder.

• done uses required three-digit completion-order prefix, one

global sequence.

Task base names: no ticket IDs, abbreviations; use readable descriptive words.

Backlog and done numbering independent. Same number may appear in multiple backlog folders, once in done.

2. Task administration

Status moves

Move task files between folders to reflect lifecycle state.

Backlog subfolder moves: organizational only. Adjust backlog prefixes to fit target. Remove backlog prefix only when moving out of backlog. Moving into done: assign next global done prefix independently.

Later executable follow-up from a task or subtask already in review or done returns to PLAN and follows the shared follow-up rule in common-task-guidance.md before more implementation.

If that shared rule keeps the same task or subtask from review, it stays in place by default during that planning and renewed-approval work. Do not require a move back to in-progress or separate tracking solely because the earlier implementation created an intermediate state. Briefly mention that the User may instead request a new task or subtask, a task move, or a subtask status change.

Tasks in done stay in place. If the User has not already specified whether to reuse the same task or subtask or use separate tracking, ask. Do not substantially rework done sections or subtasks unless the User asks.

Tracked moves

Use git mv for tracked task files, stage move immediately before editing. Preserves rename tracking. Don't unstage until ready to review and commit. For new untracked files: move in filesystem, then git add -A.

Commit checks

Update subtask status on lifecycle state change. Before each task-scoped commit: check relevant task files. If relevant task files are modified, those modifications must be staged and included in the same commit. Do not invent synthetic task-file edits solely to satisfy this coupling. Propose needed status or folder changes. Apply only after explicit User confirmation, except LLM applies in-progress -> review directly when implementation and required automated verification are complete under spec-loop-implementation-flow.

No generated or local-only artifacts in commits. If accidentally tracked: untrack, add or update ignore rule before continuing, unless intentionally versioned.

Before writing commit message: review full change set and purpose. Message must accurately describe purpose unless User says otherwise. No misleading commit messages. Task commits: start with Primary Identifier (Ticket ID if present, else full Task Identifier). Non-task updates may omit identifiers if AGENTS.md allows. If User asks to skip identifiers, honor it.

After code or config changes: run relevant module tests before reporting.

Done cleanup

Keep done tasks under done with global three-digit prefix (independent of backlog prefix). Delete from working tree after release tag created.

Task States

Tasks and subtasks share one lifecycle: backlog, in-progress, review, done. These status values are an exact enum. No other task or subtask status values are allowed.

Phases = what work may happen now. Lifecycle states = where tracked work sits.

Representation:

• Task state = top-level folder.
• Tasks in review or done stay there by default.
• Later executable follow-up from review or done returns to PLAN.

During that planning and renewed-approval work, a review item may stay in place without a new subtask. A done item is reused only when the User chooses that.

• Only subtasks have status fields. The task status itself is

indicated only by its folder.

• Subtask lifecycle: - **Status:** <status>.

Lifecycle definitions:

• backlog — planned or deferred. New tasks default here.
• in-progress — active research, design, implementation, or

verification.

• review — in the User review cycle. By default, a task or

subtask stays in review once that cycle is reached, including same-task executable follow-up that planning keeps on that task or subtask, unless the User explicitly asks for more formal tracking.

• done — User-verified completion.

Lifecycle and transition rules:

• Same transition guards as SKILL.md and the shared readiness rules.
• Allowed task-file moves: backlog <-> in-progress -> review ->

done, plus explicit User-requested review -> in-progress.

• If in-progress is empty and only one new task is being created,

place it in in-progress, otherwise in backlog.

• LLM moves in-progress -> review when implementation and

required automated verification are complete under spec-loop-implementation-flow.

• Later executable follow-up from review or done returns to PLAN

before more implementation.

• During that planning and renewed-approval work, a review item

stays in review by default. The LLM must not move a task back to in-progress or change a subtask from review to in-progress unless the User explicitly asks.

• For follow-up from done, if the User has not already chosen

whether to reuse the same task or subtask or use separate tracking, ask before revising the artifact.

• When the User explicitly changes a subtask from review to

in-progress during that follow-up, the overall task may stay in review unless the User also requests a task-level move.

• Subtask status changes apply only to that subtask unless the User

explicitly says otherwise.

• Task with subtasks: move task to review when no unfinished

task-level or subtask-level work remains and at least one subtask is in review.

• Task with subtasks: move task to done only when every subtask is

done and the User explicitly requests moving the task to done.

• The LLM may propose a task-level move when its guard becomes true,

but must not assume an unrequested task-level done move.

• Moving into done is user-only, always. The LLM must never move a

task or subtask to done without explicit User request.

Task Structure on the task-file path

Use the shared no-subtask main-task structure from common-task-guidance.md.

When a task uses subtasks:

• keep subtasks after all global task sections;
• main-task Research, Analysis, Design, Test specification, and

empty Implementation notes may be omitted;

• when a conditional or optional section is omitted, omit it entirely

and keep the remaining sections in the shared order.

• For later executable follow-up from review or done, first apply

the shared follow-up rule in common-task-guidance.md.

• Do not create a new subtask by default when that shared rule keeps

the same task or subtask.

• An implementation-created intermediate state alone does not force a

new subtask.

• If the shared rule keeps the same overall task but the User wants

separate tracking or a separate governed starting state is actually required, recommend a new subtask and wait for explicit User confirmation before creating it.

• When a new subtask is created to preserve a separate governed

starting state or history-preserving intermediate state, that state may appear only in the new subtask's Research as its starting state.

• If a task without subtasks needs its first separately tracked

follow-up within the same overall task, convert it to subtask form by default.

• During that conversion, keep only shared context at task level and

move subtask-specific Research, Analysis, Design, and Test specification into the relevant subtask.

• If the original no-subtask task already describes a concrete

functional increment, promote that increment into its own subtask.

• Do not create a synthetic "original task" subtask when the former

top-level content was only broad shared context and not a distinct functional increment.

Every Subtask

• must start with ## Subtask: <title> followed by

- **Status:** <status>,

• must use the same bold-label list-item labels and ordering as the

shared main task form, including conditional Scenario, conditional Glossary, optional Constraints, conditional Analysis, and conditional Implementation notes,

• must not convert those section labels into Markdown headings,
• must represent a separately tracked work unit within the same

overall task; for implementation tasks it must include executable work; this is usually a functional increment, but a history-preserving review follow-up may also justify a subtask,

• for feature implementation, implementation subtasks must be

vertical slices: each implementation subtask must cover the cross-layer work needed for one reviewable behavior and its own automated tests,

• do not split a feature into scaffolding-only or layer-only

implementation subtasks such as separate scaffolding, model, logic, or UI subtasks unless the User explicitly requests that structure or a governed history-preserving follow-up truly requires it,

• is not assumed to be self-sufficient; before working from a

subtask, read the relevant task-level sections and diagrams needed to understand it correctly;

• must satisfy the testing policy in

test-specification-guidance.md.

• No planning-only subtasks unless User explicitly asks.

Implementation notes placement:

• without subtasks: task level;
• with subtasks: active implementation subtask, unless a genuine

task-level note is needed.

Task Context Hygiene

• No redundant duplication across main task and subtasks. Reused

context: reference briefly, state only local adaptation, risk, or decision.

• The Research and Design diagram rules do not justify repeating the

same content at both task and subtask level; keep shared context at task level and local context at subtask level.

• Future subtasks may keep Research, Design, and Test specification

lightweight until current. Analysis may stay omitted or minimal until final clarification decisions exist. Placeholders like To be done or See main task are allowed for Research, Design, and Test specification.

• Current implementation subtask must have detail needed for review

and execution.

• Once a decision is made, remove obsolete or superseded

alternatives.

• Repeat diagrams, types, payloads, or prose only when it adds local

reasoning value or shows genuinely different behavior, ownership, or contract.

Task Compaction

Use spec-loop-compact-task-file/SKILL.md when:

• converting a task from no-subtask form to subtask form;
• adding a new subtask after earlier subtasks already contain full

section content; or

• the active task file has become too large to use safely.

Diagrams

Diagrams are task-file-only planning artifacts. If diagrams would materially help because research, glossary grounding, or design is no longer simple, promote chat-only work to the task-file path before using them.

• Governs diagrams in task Research and Design, plus Mermaid

visual glossaries in task Glossary.

• Use PlantUML by default for Research and Design.
• Use Mermaid only when User or governing instruction explicitly

prefers it, except for task Glossary visual glossaries required by scenario-and-glossary-guidance.md.

• Research = current state. Design = target state.

Glossary Mermaid diagrams = domain-language grounding.

• Research must include diagram when analyzing current behavior,

message flow, context selection, component interaction, or current class design.

• Design must include diagram when change affects structure,

component interaction, or target class design.

• When Scenario or Glossary exists, Design diagrams must show the

relevant units and names in the diagram itself, not only in non-diagram text.

• Non-diagram text means text outside diagram blocks.
• These rules apply only within task-file Research and

Design. They do not change Analysis, Test specification, or other sections.

• They apply to both main-task and subtask Research and

Design sections and do not override the task context hygiene rules against duplication across task and subtask levels.

• In Research and Design, diagrams are primary because they

are compact. No notes or legends inside diagrams.

• Whatever can be expressed clearly in a diagram without notes or

legends belongs only in the diagram; non-diagram text, lists, and tables there may cover only what cannot be expressed clearly that way.

• If non-diagram text explains a specific diagram or diagram group,

use this local order:

• relevant diagram or diagram group;
• immediately following related non-diagram text, if any; and
• next relevant diagram or diagram group.
• Do not place explanatory non-diagram text before the diagram or

diagram group it explains.

• If any non-diagram points in Research or Design are not tied

to a specific diagram or diagram group, place them at the end of that section, after the last diagram-related block.

• Omit diagrams only when the task is confined to a single method or

a trivially local change with no meaningful flow or interaction.

• No test classes, fixtures, or test-only helpers in diagrams.
• Each diagram in its own paragraph under the owning section.
• Structure and behavior both matter: use separate diagrams.
• Declare component and sequence diagrams with explicit language

keywords.

• Use class diagrams whenever current or target class design is

materially relevant.

• In Research, show the current classes, interfaces, enums,

relationships, and review-relevant members needed for review.

• In Design, show the target classes, interfaces, enums,

relationships, and review-relevant members needed for review.

• Treat the class diagram as the primary structural inventory for those

types, relationships, and review-relevant members.

• Put review-relevant operations in interface and class boxes.
• Put review-relevant fields in DTO, request, response, result,

value-object, and similar data-type boxes.

• Do not restate those members in non-diagram text, lists, or tables

unless the diagram would become unreadable or the information is not naturally owned by a class box.

• Do not add a companion table or list just to compensate for content

that should be in the diagram.

• Add a companion compact list or table only when the diagram is

already complete and some exact facts still need a precise inventory.

• Class diagrams: show only elements needed for change or structural

interaction, meaningful dependency labels, and at most one connector per class pair.

PlantUML-specific rules

• Prefer separate diagrams over allowmixing; keep file or folder

tree, component, class, and sequence diagrams separate unless one mixed diagram is genuinely required.

• Do not apply normal prose line wrapping inside PlantUML fences.
• Keep each line-oriented PlantUML statement on one physical line.
• Use multiple physical lines only for syntax that is explicitly

block-based, such as package { ... } and class { ... }.

• note ... end note and legend ... endlegend are not allowed in

task diagrams.

• If inline text on a line-oriented statement becomes too long,

shorten it or use \n inside the same statement.

• In sequence diagrams, each A -> B : message line is one

statement and must stay on one physical line.

• Class diagrams: one outer package with nested inner packages and

set separator none.

• Use escape character ~ for text matching creole markup like --.

Mermaid-specific rules

• Task Glossary Mermaid diagrams must follow

scenario-and-glossary-guidance.md.

• Class diagrams: use classDiagram.
• Only single-level namespace blocks; no nesting.
• Hierarchical boundaries: flatten namespace names instead of

nesting.

Testing Policy on tasks with subtasks

Use the shared Testing Policy from test-specification-guidance.md for all no-subtask tasks.

For task-file subtasks:

• Implementation subtasks must include testing. Don't split

implementation and testing across separate subtasks for the same functional increment.

• Separate test-focused tasks allowed when adding or extending

coverage as standalone scope.

• Each implementation subtask: include an explicit Automated tests

sublist of task-specific verification cases.

• Include a Manual tests sublist only for useful optional

human-reader checks that cannot be covered adequately by automated tests; otherwise set Manual tests: N/A.

• Manual tests are reviewer hints, not agent review gates. Do not

move automatable verification into Manual tests; list it under Automated tests.

• Do not list test execution commands, framework names, or pass/fail

status in Test specification.

• Run and fix the automated tests that implement the specified cases

and any required project-level checks before moving a task or subtask to review, unless the User waives them.

Test specification guidance

Read and follow this file just before drafting or revising a task Test specification. Return to common-task-guidance.md afterward.

This file defines the testing policy and what belongs in Automated tests and Manual tests. It is not a separate workflow and does not change route, phase, or approval rules.

Purpose

Test specification specifies how the current task's requirements and task-relevant modified code paths are verified.

Aim for broad task-relevant coverage: cover the described requirements, changed behavior, affected contracts, important edge cases, regressions, and modified decision branches with meaningful assertions for each expected outcome where practical.

When formal numbered requirements exist, tests may reference them. Otherwise, the requirements are the behavior, contracts, constraints, edge cases, and risks described in the task.

Testing Policy

• Keep Test specification in each task without subtasks. No-code

tasks: set Automated tests: N/A and Manual tests: N/A.

• Separate test-focused tasks allowed when adding or extending

coverage as standalone scope.

• Prefer automated tests and automated checks. Manual tests are

optional human-reader hints for post-handoff review. Use them only when the same verification purpose cannot be covered adequately by automated tests.

• Do not list test execution commands, framework names, or pass/fail

status in Test specification.

• Each implementation task without subtasks: include an explicit

Automated tests sublist of task-specific verification cases. Include a Manual tests sublist only for useful optional human-reader checks that cannot be automated enough for the task; otherwise set Manual tests: N/A.

• Run and fix the automated tests that implement the specified cases

and any required project-level checks before moving a task-file task to review, before presenting chat-only work as ready, or before otherwise implying implementation closure, unless the User waives them.

Automated tests

Automated tests is a list of task-specific automated verification cases. It is not a test execution plan, test log, framework inventory, or pass/fail report.

For example-based automated tests, use concise behavior/assertion bullets. Each bullet must make the tested condition and expected observable result clear enough to implement meaningful assertions. Use Given / When / Then only when it makes the case clearer, such as for multi-step flows, state transitions, or otherwise ambiguous cases.

Good examples:

• Visible session completion persists the session in the

visible-session list.

• Background run completion does not add the run to the

visible-session list.

• Background path failure leaves the visible-session list unchanged.

For property-based, stateful, model-based, or similar automated tests, state the properties, invariants, generated input spaces, state transitions, or contracts being checked.

For supported external contracts, such as user-facing APIs, CLIs, serialized formats, configuration, persistence, plugin extension points, documented integration points, and compatibility promises, include relevant invalid input, boundary, compatibility, and expected error-handling cases.

For internal implementation code, even when classes or methods are language-public, do not over-specify tests for impossible or unsupported illegal arguments. Focus on valid reachable states, happy paths, important logic branches, invariants, and behavior observable through the supported external or task-relevant integration boundary. Test invalid internal inputs only when they are reachable, intentionally handled, or part of the approved internal contract.

Do not list test execution commands, framework names, or statements such as "tests pass" in Test specification. Those are project-level execution details or implementation-time verification results, not the task-level Test specification.

If a check can be automated enough for the task, put it under Automated tests, not Manual tests.

Manual tests

Manual tests are optional human-review hints after handoff. They do not block review and must not be reported as done unless actually performed.

Use Manual tests only for useful human checks that cannot be automated enough for the task. Otherwise set Manual tests: N/A.

Do not move automatable verification into Manual tests.

Relation to other task sections

Do not restate Analysis points in decision-and-reason form. Record the resulting verification consequences instead.

When task Glossary exists, Test specification must reuse approved terms from Scenario, Glossary, and Design.