CodeLoop

10 agent skills for software engineering. Plain markdown - works with any model, any harness that supports the Agent Skills standard. Designed to be forked and adapted.

This README is an explanatory guide for users. Runtime behavior lives in the installed SKILL.md files and their installed ref/ documents.

Skills

Skill	What it's for	What comes out
init	Set up or audit CodeLoop records and route to a useful next skill	Record structure audit, formatting fixes, next-skill recommendation
clarify	Nail down fuzzy requirements one question at a time	Questions, stories, glossary entries, decisions, research notes
overview	Understand code in system context	Inline explanation of callers, callees, rationale, and assumptions
structure	Find shallow modules and deepening opportunities	Candidate list ranked by strength
proto	Test a design choice with the smallest throwaway build	Finding, optional research or decision record; prototype code discarded
spec	Write an actionable spec from resolved context	records/topics/<YYYY-MM-DD>-<topic-slug>/spec.md
slice	Break a spec or clear requirements into vertical tasks	records/topics/<YYYY-MM-DD>-<topic-slug>/tasks/T<N>-<task-slug>.md
tdd	Build or fix one slice test-first	Passing tests, working code, optional task status update
diagnose	Find the root cause of a bug or regression	Diagnosis report, optional research record
handoff	Compact a session so another agent can continue	records/topics/<YYYY-MM-DD>-<topic-slug>/handoffs/<YYYY-MM-DD>-<slug>.md

Collaboration Model

Skills can have strong relationships without becoming a forced pipeline. A skill may work best after another skill, but missing upstream artifacts should not automatically make it unusable.

Dependency levels:

• Preferred input: useful context when present. Example: overview benefits from glossary and decision records.
• Strong dependency: the normal path for best output. Example: slice normally reads a spec, and tdd normally reads a task file.
• Internal hard rule: a rule inside a skill's own method. Example: diagnose finds the cause and does not fix code.

When an upstream artifact is missing, a skill should usually proceed from conversation context, ask one local question, create a minimal local substitute, or suggest another skill for deeper work.

Common Flows

START - What's the situation?
  |
  |- "I want this project to follow CodeLoop"
  |  -> init -> recommended next skill
  |
  |- "I don't know what I want yet"
  |  -> clarify
  |
  |- "I want to understand existing code"
  |  -> overview -> optionally structure
  |
  |- "The codebase hurts and I want to refactor"
  |  -> structure -> optionally proto -> spec -> slice -> tdd
  |
  |- "Something's broken"
  |  -> diagnose -> tdd, or structure if the cause is architectural
  |
  |- "I need to decide between two approaches"
  |  -> proto
  |
  |- "Requirements are clear, time to plan"
  |  -> spec -> slice -> tdd
  |
  `- "I need to switch sessions or hand off"
     -> handoff

Examples:

clarify: Stress-test checkout recovery before writing a spec.
spec: Write a spec from records/topics/2026-06-02-checkout-recovery/questions.md.
slice: Break records/topics/2026-06-02-checkout-recovery/spec.md into vertical tasks.
tdd: Implement records/topics/2026-06-02-checkout-recovery/tasks/T1-reset-link.md.

Records

Records group durable work by topic so a future agent can open one folder and see the questions, spec, tasks, decisions, research, and handoffs for that effort.

records/
├── global/
│   ├── glossary.md
│   └── decisions/
│       └── <slug>.md
└── topics/
    └── <YYYY-MM-DD>-<topic-slug>/
        ├── index.md
        ├── questions.md
        ├── spec.md
        ├── tasks/
        │   ├── T1-<task-slug>.md
        │   └── T2-<task-slug>.md
        ├── decisions/
        │   └── <slug>.md
        ├── research/
        │   └── <slug>.md
        └── handoffs/
            └── <YYYY-MM-DD>-<slug>.md

records/global/glossary.md and records/global/decisions/ hold project-wide context. Topic folders hold durable context for one feature, bug, refactor, investigation, or design question.

Specs and task files have a **Status** field: active, done, or dropped. Glossary, decision, question, research, and handoff records do not use lifecycle status.

Record Flow

Records let skills pass context without requiring a long conversation thread:

• clarify writes questions.md, glossary entries, decisions, and research.
• spec reads topic context and writes spec.md.
• slice reads spec.md or clear inline requirements and writes tasks/T<N>-*.md.
• tdd reads task files or acceptance criteria, then may update task status.
• diagnose can preserve root-cause findings in topic research/.
• proto can preserve prototype findings in topic research/ or decisions.
• overview and structure read glossary and decisions when present.
• handoff reads topic records and writes a pointer document.
• init can create or audit record structure, but it is not required before other skills run.

Acknowledgments

Adapted from Matt Pocock's skills library.