Getting Started with little-loops¶

What Is little-loops?¶

little-loops turns Claude Code into a structured development workflow engine. The core idea: instead of one-shot prompts, you write issues — Markdown files that travel with your code and serve as rich context for AI-driven implementation. A well-formed issue tells the agent why something needs to change, where in the codebase to look, and how to verify it worked. The agent can then plan, implement, test, and archive the change with minimal back-and-forth from you.

The system has three layers you can use independently or together:

Issues — Markdown files in .issues/ that capture bugs, features, and enhancements. The atomic unit of work. You can use this layer alone indefinitely.
Sprints — Named batch runs with dependency-aware execution ordering. Useful when you have four or more issues, or issues that must run in sequence.
Loops — YAML-defined FSM automations that run recurring workflows (quality gates, scheduled scans) without repeated prompting.

The core flow in one line: observe → capture → refine → implement → complete.

Installation¶

Step 1: Install the Plugin¶

# Add the GitHub repository as a marketplace source
/plugin marketplace add BrennonTWilliams/little-loops

# Install the plugin
/plugin install ll@little-loops

For local development, use a local path instead:

/plugin marketplace add /path/to/little-loops
/plugin install ll@little-loops

Step 2: Install the Python CLI Tools¶

The slash commands run inside Claude Code sessions. The CLI tools (ll-auto, ll-sprint, ll-loop, etc.) run from your terminal and drive automated execution.

pip install little-loops

Step 3: Verify¶

# Terminal: confirm CLI tools are installed
ll-auto --help

# Claude Code session: confirm plugin is loaded
/ll:help

Set Up Your Project¶

Run /ll:init once per project. It auto-detects your project type and generates a starter configuration.

/ll:init

Detected project types: Python, JavaScript/TypeScript, Go, Rust, Java (Maven or Gradle), and .NET. For each type, it infers sensible defaults for test commands, lint commands, and source directories. Unrecognized projects fall back to a generic template.

What gets created:

.issues/
  bugs/
  features/
  enhancements/
  epics/
.ll/ll-config.json

What else happens: /ll:init also appends little-loops state files to your .gitignore (e.g. .auto-manage-state.json, .ll/ll-context-state.json) so runtime state never ends up committed.

Flags¶

Flag	What it does	When to use it
(none)	Auto-detects project type, previews settings, and asks for confirmation	Default — works for most projects
`--interactive`	Launches a guided wizard to configure every option step by step	First setup when auto-detection won't cover non-standard tooling
`--yes`	Accepts all auto-detected defaults without any confirmation prompts	When you trust the defaults and want a fast, non-interactive setup
`--force`	Overwrites an existing `.ll/ll-config.json`	Re-initializing a project that already has a config
`--dry-run`	Previews what would be generated without writing any files	Checking what `/ll:init` would produce before committing
`--codex`	Also installs the OpenAI Codex CLI hook adapter (writes `.codex/hooks.json`). Auto-enabled when the `codex` binary is on `PATH` or a `.codex/` directory already exists.	Setting up little-loops for a project you also use with Codex CLI

--interactive and --yes are mutually exclusive. All other combinations are valid — for example, --interactive --force runs the wizard and overwrites the existing config, --dry-run --force previews what an overwrite would produce, and --codex --dry-run previews the Codex hook adapter without touching .codex/.

Use --interactive the first time you set up a project with non-standard tooling. The wizard walks through source directories, test and lint commands, parallel worker counts, GitHub sync, and more. For a straightforward project where auto-detection gets it right, --yes is faster.

Key Config Fields¶

The three fields most relevant to beginners:

Field	Purpose	Example
`project.test_cmd`	Command to run tests	`pytest scripts/tests/`
`project.lint_cmd`	Command to run lint/format	`ruff check scripts/`
`project.src_dir`	Primary source directory	`scripts/`

Start with the auto-detected defaults. Use /ll:configure later to tune individual settings.

Your First Workflow: Fix a Bug¶

The simplest complete workflow — from observation to committed fix.

Step 1: Capture¶

Describe the bug in plain language. The skill creates a properly formatted issue file.

/ll:capture-issue "login button doesn't respond on mobile Safari"
#    → Creates .issues/bugs/P3-BUG-001-login-button-doesnt-respond-on-mobile-safari.md

The file gets a priority prefix (P3), type (BUG), globally unique ID (001), and a kebab-case description. Open it to review — capture fills in what it can from context and leaves placeholders for what it can't determine.

Step 2: Validate (Optional but Recommended)¶

Before implementing, run a quality check. This catches missing context, vague reproduction steps, or implementation gaps that would slow down the agent.

/ll:ready-issue BUG-001
#    → Checks quality, auto-corrects what it can, flags open questions

For a trivial bug, skip this step and go straight to implementation. For anything you'll hand off to automated tools, the quality check pays for itself.

Step 3: Implement¶

/ll:manage-issue handles the full implementation cycle: plan, implement, run tests, and mark the issue complete.

/ll:manage-issue bug fix BUG-001
#    → Plans → implements → runs tests → sets status: done in frontmatter

When it finishes, the issue file remains in .issues/bugs/ with status: done in its frontmatter.

Step 4: Commit¶

Review the diff, approve the commit message, and commit.

/ll:commit
#    → Reviews diff, proposes commit message, asks for approval before committing

The commit message follows conventional commit format. You approve before anything is written to the repo.

Understanding Issue Files¶

A few things that trip up new users:

Filenames¶

P2-BUG-042-sprint-runner-ignores-failed-issues.md
│  │   │   └─ kebab-case description
│  │   └─── globally unique issue number
│  └─────── type: BUG, FEAT, ENH, or EPIC
└────────── priority: P0 (critical) to P5 (low)

IDs are globally unique across all types — you won't have both BUG-007 and FEAT-007.

Status and Priority¶

Priority levels run from P0 (critical, must fix immediately) to P5 (low, nice-to-have). The priority prefix in the filename determines ordering in automated runs — ll-auto and ll-sprint process lower numbers first. You can reassign priority at any time by renaming the file or running /ll:prioritize-issues.

The status field inside the issue file tracks where the issue is in the workflow: open, in_progress, blocked, deferred, done, or cancelled. Automated tools read and update this field; you rarely need to edit it directly. See ISSUE_MANAGEMENT_GUIDE.md for the full table and meanings.

Directory Structure¶

All issues live in type directories regardless of their lifecycle state. Status is tracked via the status frontmatter field.

.issues/
  bugs/             ← BUG issues (open, in_progress, done, deferred, etc.)
  features/         ← FEAT issues (any status)
  enhancements/     ← ENH issues (any status)
  epics/            ← EPIC coordination containers (any status)

A completed bug stays in .issues/bugs/ with status: done in its frontmatter — it is not moved.

Use Anchors, Not Line Numbers¶

Code references in issue files use function and class names, not line numbers.

# Correct
Root cause is in function `_run_wave()` in `scripts/little_loops/sprint.py`.

# Wrong — line numbers drift
Root cause is at line 1847 in sprint.py.

Minimal vs. Full Template¶

/ll:capture-issue uses the template style set in ll-config.json (issues.capture_template, default: "full"). The full template includes all v2.0 sections; the minimal template has only Summary, Current Behavior, Expected Behavior, Impact, and Status. Pass --quick to force minimal regardless of config. Run /ll:format-issue later to promote a minimal issue to the full template when you're ready to implement.

Discovering Issues You Didn't Know Existed¶

Three commands for finding problems and gaps proactively, without waiting for them to surface in production.

Scanning Your Codebase¶

/ll:scan-codebase
#    → Static analysis: finds bugs, tech debt, and missing error handling

Creates issue files for anything it finds. Run this periodically or after major refactors.

/ll:audit-architecture
#    → Identifies structural problems: coupling, missing abstractions, consistency issues

Analyzes code organization and design patterns rather than individual bugs. Good for understanding systemic issues in an unfamiliar codebase.

Goal-Oriented Scanning¶

/ll:scan-product
#    → Compares codebase against your goals document, finds feature gaps

Uses product goals file if present (.ll/ll-goals.md), or discovers goals automatically from README and roadmap docs. Useful for identifying what the codebase is missing relative to what you said you wanted to build.

Manual Capture¶

For issues you spot yourself — a bug you just hit, a feature request from a stakeholder, or a code smell you noticed during review — use /ll:capture-issue directly:

/ll:capture-issue "description of the problem or idea"

This skips scanning entirely and creates a single issue file from your description. It's the fastest path from observation to a tracked issue.

After Scanning¶

A scan often produces more issues than you want to implement. Two commands to reduce the list:

/ll:prioritize-issues
#    → Adds P0-P5 priority prefixes to filenames based on severity and impact

/ll:tradeoff-review-issues
#    → Evaluates utility vs. complexity; recommends which to implement, update, or close

When to Escalate¶

Situation	Tool
1-3 issues, no dependencies	`/ll:manage-issue` directly
4+ issues, or issues with blockers	`/ll:create-sprint` + `ll-sprint run`
Recurring quality check (lint, tests, scans)	`ll-loop run <loop-name>`

/ll:manage-issue works well for a few issues. It's interactive and handles one issue at a time.

Sprints shine when issues have dependencies. The sprint system computes execution order automatically from blocked_by fields, runs independent issues in parallel, and can resume after interruption.

Loops are for automation you'd otherwise run by hand on a schedule — a nightly quality gate, a weekly scan, a fix-and-verify cycle. You define the workflow once as a YAML file; the FSM engine executes it without prompting.

Quick Reference¶

The ten commands you'll use most often:

Command	What It Does
`/ll:init`	Auto-detect project type and create config + issue directories
`/ll:capture-issue`	Create an issue file from a natural-language description
`/ll:ready-issue`	Validate an issue for implementation readiness
`/ll:manage-issue`	Plan, implement, test, and complete an issue end-to-end
`/ll:commit`	Review diff, propose commit message, and commit with approval
`/ll:scan-codebase`	Static analysis to discover bugs and tech debt
`/ll:prioritize-issues`	Assign P0-P5 priorities to issue files
`/ll:create-sprint`	Create a sprint from active issues for batch execution
`/ll:format-issue`	Validate and normalize issue file structure
`/ll:refine-issue`	Fill knowledge gaps with codebase research

For the full list: /ll:help or see Command Reference.

What's Next?¶

Once you're comfortable with the basic workflow, each guide covers a deeper area:

Guide	Go here when...
Issue Management Guide	You want the full refinement pipeline: normalize → prioritize → format → refine → verify
Sprint Guide	You have multiple issues with dependencies and want batch execution with waves
Loops Guide	You want to automate a recurring workflow (quality gate, fix cycle) as an FSM
Session Handoff Guide	Your sessions are hitting context limits and you need seamless continuation