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, spec-loop-write-adr, and spec-loop-write-readable-tests.
• The testing skill's test design and writing guidance also works without Spec Loop.
• 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

   • plans non-trivial work and manages its tasks. A task file is the default; a lighter form needs to meet the rules and have the user's permission. Chat-only tasks have exactly Scope, Design, and Test specification;
   • task-file Design class diagrams prefix each displayed type and member with + (add), = (reuse unchanged), or ± (modify). PlantUML wraps each bold marker in <plain>; Mermaid uses plain literal indicators without HTML or Markdown wrappers. These show planned changes, not implementation progress;
   • 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 standalone tasks and subtasks, with implementation tasks and subtasks releasable by default, and requires explicit user opt-out for non-releasable implementation work;
   • 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 skill for creating, updating, or superseding a Spec Loop AsciiDoc project glossary;
   • 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; high-level assessments check required living-project-document actions, and file-wise walk-through mode explains the changed files;
   • 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.

10. spec-loop-write-readable-tests

    • the testing skill for coverage, case selection, case purposes and behavioral names, visible setup/action/result, explicit mock outcomes, appropriate helpers and parameterization, and preservation of assertions;
    • also defines Spec Loop task verification entries and readiness requirements. Only that part depends on Spec Loop;
    • Spec Loop Automated tests entries prefix every file or other verification container and case anchor with +, =, or ± for planned additions, unchanged reuse, or modifications. Containers and cases are classified independently; the markers are not executable names or test results;
    • defined by skills/spec-loop-write-readable-tests/SKILL.md, which directly links test-design-and-writing.md for test design, naming, and writing, and spec-loop-task-verification.md for Spec Loop task-recording and readiness rules.

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 selection across taskless, chat-only task, task file, task file with subtasks, and multiple task files / backlog items; uses a task file by default and asks permission before using a lighter form. When the form no longer fits, change it and apply the new form's rules. Permission to use a form does not approve execution.
   • 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 rule that implementation tasks and subtasks must be releasable unless the user explicitly opts out.
   • 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 full no-subtask task form, shared section semantics, readiness rules, formatting, and task rules for the project list and for project glossaries and other living project documents.
   • skills/spec-loop-write-readable-tests/SKILL.md selects test design and writing guidance and Spec Loop task-recording and readiness rules. The invoking workflows still control scope, phases, approvals, and completion.
   • skills/spec-loop-plan-task/scenario-and-glossary-guidance.md defines how task Scenario and task Glossary are drafted, how terms are checked for semantic identity with existing abstractions, and how task visual glossaries should be written.
   • skills/spec-loop-plan-task/chat-only-path-guidance.md defines exactly three chat-only sections (Scope including context and constraints, Design, Test specification), how to write and update the current task, repeat it when needed, handle later work, and move to a task file when chat-only no longer fits.
   • 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 how to update a chat-only task during implementation, repeat it when needed, move it to a file, and present work for review. Useful notes stay outside the three-section task. File-only preparation steps apply only when the work uses a task file.
   • 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 planning skill's project-list and project-glossary sections, plus the common task guidance, for glossary planning and the fallback to Research plus the existing codebase when no project glossary exists.
   • 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-write-readable-tests/SKILL.md for Test specification work or automated tests
• 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