Skills Overview

Included Skills

This repository currently ships these skills:

• The core task-workflow bundle is spec-loop-plan-task, spec-loop-plan-work-breakdown, spec-loop-clarify-task, spec-loop-prepare-execution-approval, spec-loop-implementation-flow, and spec-loop-write-adr.
• spec-loop-write-glossary is required when a project uses a project glossary in the Spec Loop AsciiDoc format.
• spec-loop-setup-doc-rendering and spec-loop-review-change are optional.

1. spec-loop-plan-task

   • the planning and task-administration skill for non-trivial work;
   • defined by skills/spec-loop-plan-task/SKILL.md, skills/spec-loop-plan-task/planning-form-selection-guidance.md, skills/spec-loop-plan-task/common-task-guidance.md, skills/spec-loop-plan-task/scenario-and-glossary-guidance.md when Scenario or task Glossary work is needed, skills/spec-loop-plan-task/chat-only-path-guidance.md on the chat-only path, and skills/spec-loop-plan-task/task-file-path-guidance.md on the task-file path.

2. spec-loop-plan-work-breakdown

   • the file-based work breakdown skill used after planning-form selection chooses task file with subtasks or multiple task files / backlog items; it enforces independently acceptable items and releasable implementation increments by default, and requires explicit user opt-out for non-releasable items;
   • defined by skills/spec-loop-plan-work-breakdown/SKILL.md.

3. spec-loop-clarify-task

   • the clarification skill for underspecified task creation, task updates, design updates, and ADR decisions; preferred over generic grill-me variants in Spec Loop workflows;
   • defined by skills/spec-loop-clarify-task/SKILL.md.

4. spec-loop-prepare-execution-approval

   • the approval-preparation skill used only on the task-file path before the agent asks for execution approval for implementation or investigation work within the spec-loop-plan-task workflow;
   • defined by skills/spec-loop-prepare-execution-approval/execution-approval-guidance.md.

5. spec-loop-implementation-flow

   • the mandatory implementation-flow skill used after execution approval for implementation work on either planning path when implementation deviates from the approved task, when uncertainty or blocking questions arise, or before handing implemented work over for review or ready-state presentation;
   • defined by the shared core skills/spec-loop-implementation-flow/implementation-flow-guidance.md, plus the path-specific companions skills/spec-loop-implementation-flow/chat-only-path-guidance.md and skills/spec-loop-implementation-flow/task-file-path-guidance.md.

6. spec-loop-write-glossary

   • the Spec Loop AsciiDoc project-glossary-format skill, required when the project uses that glossary format;
   • defined by skills/spec-loop-write-glossary/glossary-format.md.

7. spec-loop-setup-doc-rendering

   • the optional setup and troubleshooting skill for rendering task files and glossary files.

8. spec-loop-write-adr

   • the ADR-writing skill used when planning sends work to an architecture decision record or when the user asks for ADR work;
   • defined by skills/spec-loop-write-adr/SKILL.md and skills/spec-loop-write-adr/adr-format.md.

9. spec-loop-review-change

   • the optional existing-change review skill for pull requests, merge requests, branch diffs, commit ranges, local branch changes, or agent-written code the user wants reviewed; it supports both high-level assessment and file-wise walk-through modes;
   • defined by skills/spec-loop-review-change/SKILL.md, skills/spec-loop-review-change/review-core-guidance.md, skills/spec-loop-review-change/assessment-guidance.md, skills/spec-loop-review-change/walk-through-guidance.md, and skills/spec-loop-review-change/github-gitlab-evidence-guidance.md.

Documentation

1. Check the planning, clarification, and implementation-flow skills briefly.

   • skills/spec-loop-plan-task/SKILL.md defines first classification, approval and escalation rules, ADR and documentation routing, Scenario/task Glossary triggers, and phase rules.
   • skills/spec-loop-plan-task/planning-form-selection-guidance.md defines planning-form selection across taskless, chat-only task, task file, task file with subtasks, and multiple task files / backlog items.
   • skills/spec-loop-plan-work-breakdown/SKILL.md defines file-based work breakdown after subtask or multi-task planning forms are selected, including the default releasable-increment rule.
   • skills/spec-loop-clarify-task/SKILL.md defines how Spec Loop clarifies underspecified task creation, task updates, design updates, and ADR decisions during planning or ADR writing.
   • skills/spec-loop-plan-task/common-task-guidance.md defines the shared no-subtask task form, section semantics, readiness rules, formatting, testing policy, and project-glossary policy used on both planning paths.
   • skills/spec-loop-plan-task/scenario-and-glossary-guidance.md defines how task Scenario and task Glossary are drafted, how existing domain terms are reused, and how task visual glossaries should be written.
   • skills/spec-loop-plan-task/chat-only-path-guidance.md defines the chat-only-path planning mechanics: initial canonical chat-task expression, section-only updates, recovery re-emission, later-work relation handling, and promotion to the task-file path.
   • skills/spec-loop-plan-task/task-file-path-guidance.md defines the task-file-specific rules: task files, lifecycle and traceability requirements, subtasks, and diagram rules.
   • skills/spec-loop-prepare-execution-approval/execution-approval-guidance.md defines task-file approval-readiness preparation before execution approval.
   • skills/spec-loop-implementation-flow/implementation-flow-guidance.md defines the shared implementation-flow core: post-approval route semantics, canonical-section authority, shared review meaning, Implementation notes, and the semantic completion checklist.
   • skills/spec-loop-implementation-flow/chat-only-path-guidance.md defines the chat-only-path implementation-time mechanics: canonical chat updates, recovery re-emission, promotion, and chat-only expression of review.
   • skills/spec-loop-implementation-flow/task-file-path-guidance.md defines the task-file-path implementation-time delta: authorized task-file edits, task-file Implementation notes expression, and task-file expression of review.

2. Study the Wordle example by commit history.

   • The Wordle commit history shows the workflow under real version-control pressure: how task specifications evolve step by step, and how implementation and tests follow approved design.

3. Check Governance, Review, and Traceability. It explains how fileless chat tasks, task files, workflow rules, common task guidance, and the task-file path guidance map to team development practice: boundaries, responsibility, commit linking, and status discipline.

4. Compare framework trade-offs.

   • AI Workflow Framework Comparison compares Spec Loop with OpenSpec, Superpowers, grill-with-docs, and agent-skills by workflow purpose and cost.

5. Follow one of the hands-on tutorials.

   • Wordle Tutorial walks through a compact Java example with staged planning, approvals, implementation, glossary maintenance, and testing.
   • Online Art Game Tutorial walks through a complete browser-oriented example with staged planning, approvals, implementation, and testing.
   • The two tutorials teach the same Spec Loop workflow: planning first, explicit approval before execution, small reviewable tasks or subtasks, verification, and user correction when the LLM misses a supporting update. The main difference is the technical setting: Wordle is a compact Java path, while the online art game is browser-oriented. You can choose either tutorial.

6. Project glossary conventions.

   • See the common task guidance project glossary section above for the project-glossary policy and the fallback to Research plus the existing codebase when no project glossary exists yet.
   • skills/spec-loop-write-glossary/glossary-format.md is the shared project-glossary-format guidance file.
   • Companion glossary examples live under skills/spec-loop-write-glossary/examples/.

Recommended quick-check order:

• README.md
• skills/spec-loop-plan-task/SKILL.md
• skills/spec-loop-plan-task/planning-form-selection-guidance.md
• skills/spec-loop-plan-work-breakdown/SKILL.md
• skills/spec-loop-clarify-task/SKILL.md
• skills/spec-loop-plan-task/common-task-guidance.md
• skills/spec-loop-plan-task/scenario-and-glossary-guidance.md
• skills/spec-loop-plan-task/chat-only-path-guidance.md
• skills/spec-loop-plan-task/task-file-path-guidance.md
• skills/spec-loop-prepare-execution-approval/execution-approval-guidance.md
• skills/spec-loop-implementation-flow/implementation-flow-guidance.md
• skills/spec-loop-implementation-flow/chat-only-path-guidance.md
• skills/spec-loop-implementation-flow/task-file-path-guidance.md
• docs/review-responsibility-and-traceability.md
• docs/skill-framework-comparison.md
• docs/online-art-game-tutorial.md
• docs/wordle-tutorial.md