Use this skill for planning-form selection and task planning before execution.

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.
• A Spec Loop task is a planned, approval-gated, reviewable unit of work.
• Non-trivial implementation work requires a task.
• Investigation work requires a task only when it needs explicit planning, separate tracking, or a reviewable output.
• Starting EXECUTION requires explicit user approval. A directive such as implement, investigate, go ahead, proceed, or apply counts as approval only when the active task is ready and the directive clearly refers to that task. If readiness or the referent is unclear, ask.
• 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 planning form, planning procedure, or sectioned task format, do not simplify it unless the user explicitly agrees.

After execution approval for implementation work, follow spec-loop-implementation-flow/SKILL.md. After execution approval for investigation work, do only the approved investigation. Record the final output in Findings for task files or Scope for chat-only tasks. Complete any required Test specification checks, then present or move the task/subtask to review under the chosen form's rules.

First classification

Classify each work item as one of:

• standalone documentation;
• trivial implementation work;
• non-trivial implementation work; or
• investigation work.

Separate test-focused tasks are allowed when adding or extending coverage as standalone scope.

Treat implementation 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.

Investigation work means research, spike, prototype, catalog, proof, or similar evidence-gathering whose output is knowledge or a reviewable artifact rather than product change. It needs a task only when the investigation itself needs explicit planning, separate tracking, or a reviewable output. Ordinary planning research stays in PLAN inside the current task or chat state. Investigation work must not ship product, test, build, config, runtime, or coupled documentation changes; plan that scope as implementation work.

Planning-form selection

A task file is the default. A lighter form must meet the rules and have the User's permission.

After first classification, read and follow planning-form-selection-guidance.md.

Current-first detailed planning for file-based multi-item work

When planning-form selection chooses task file with subtasks or multiple task files / backlog items, first do only the whole-work clarification needed for Scope, Motivation, and a sound rough breakdown. Then use spec-loop-plan-work-breakdown/SKILL.md to identify the current task, or the current subtask when subtasks are in use, and lightweight later tasks or subtasks. Do full clarification and detailed planning only for that current task, or for that current subtask plus any required shared context.

Phase model

Phases:

• PLAN = research, design/spec, test specification, and investigation planning for tasks.
• EXECUTION = approved task work. For implementation work, this means implementation 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 implementation change to behavior, tests, build or config, dependencies, packaging, runtime assets, or coupled documentation is EXECUTION and needs explicit user instruction;
• phases are exclusive unless the user allows combined planning and execution.

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

Mandatory clarification gate

Before creating or revising task or current-subtask planning content, apply the clarification skill's mandatory decision screening from spec-loop-clarify-task/SKILL.md. Use that skill's definition of important open decision.

Apply this gate proactively; do not wait for the User to ask for clarification.

For file-based multi-item work, apply this gate twice:

• before rough breakdown, only for whole-work Scope, Motivation, planning-form selection, and task or subtask boundaries, ordering, releasability, or coherence;
• after the current task is identified — or, for subtask-based work, after the current subtask is identified — apply the gate fully to that current task, or to that current subtask plus any required shared context, before drafting implementation-ready Design or Test specification.

For subtasks, apply this gate only to the current subtask and required task-level context. Apply it to future subtasks when they become current.

If clarification returns an unresolved blocker that needs ADR work or separate investigation work, route that work before continuing the blocked task plan.

If drafting later exposes an important open decision, stop and clarify before continuing.

Planning content

Use the task format for the chosen form. Cover scope, final decisions, research, constraints, Design, review expectations, and verification. This applies to implementation and investigation tasks.

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

Before drafting or revising Test specification, follow spec-loop-write-readable-tests/SKILL.md for testing guidance.

Planning-form-specific handling

Chat-only

When this planning form 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 planning form before continuing.

Task-file

When this planning form 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 EXECUTION starts; and
• use tasks/ as the default task directory when project instructions do not define one.

For task file with subtasks or multiple task files / backlog items, apply the rule above: fully plan only the current task, or the current subtask plus required shared context when subtasks are in use.

Before requesting execution approval for task-file work, use spec-loop-prepare-execution-approval/SKILL.md.

ADR routing

For ADR-only work, use spec-loop-write-adr/SKILL.md for ADR location, naming, structure, and update rules.

If task planning or accepted investigation findings show that a durable architecture or policy decision is needed, route ADR work through spec-loop-write-adr/SKILL.md. Do not hide ADR work inside clarification.

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

Living project documents

Living project documents hold current project truth: specifications, API contracts, architecture and operations documents, project glossaries, and current ADRs. Historical, archived, and incidental documents do not count.

Spec Loop does not require a project to have living project documents. If none exist, do not create documents or a Living Project Documents list solely to satisfy this policy.

Project list

Projects with multiple living project documents should keep one list named Living Project Documents as their entry point:

• use an existing list in a loaded project instruction file; otherwise use the root README.md;
• let entries identify individual documents or collections by path, role, and scope;
• treat the file containing the list as implicit; and
• if more than one list exists, ask which one should be used.

Use the list as the starting point for relevant Research. If current work names or depends on an unlisted living document, ask how to handle it. If a project has multiple living documents but no list, ask the User before creating the default list in the root README.md.

A project glossary is a living project document. Search for glossary.adoc and glossary.md even when no list exists. If an existing glossary is omitted from a list that covers other living documents, ask how to handle it. If the glossary is the only living document, use it and update it when affected without requiring a list.

A living-project-document action does not by itself require a task. Include required actions in the same increment as the implementation. For task-based work, record the check in Research (or Scope for chat-only work) and list the actions in Design. For taskless implementation or standalone documentation work, complete the actions together and list each action and resulting file or files in the final response, or state None affected. See common-task-guidance.md for task content.

Glossary policy

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

For a Spec Loop AsciiDoc glossary, use spec-loop-write-glossary/SKILL.md. For other glossary formats, follow the project's format.

An existing project glossary is the shared domain-language source above individual tasks and code. Without one, use Research plus the existing codebase until a project glossary is created.

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

When approved work changes, clarifies, or implements shared domain terms, record required task Glossary content in its own task-file section or in chat-only Scope. If an existing project glossary is affected, plan its update in the same increment. Creating, updating, or superseding a project glossary is living-project-document work. Create or supersede one only when approved by the User, project instructions, or the task plan.

When a task or subtask needs Scenario or Glossary, read scenario-and-glossary-guidance.md and follow it. Task Glossary content is a planning artifact; project glossary actions happen only during EXECUTION.

Related skills

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