Trails

Trails is a development process for agentic coding, available as agent skills for Claude Code and Codex, and as an npm package for automated workflows.

The workflow is a chain of steps that you repeat for every unit of work — usually a larger feature, an iteration, or an "epic" of an application.

Everything trails produces is plain markdown that you commit alongside your code in the specs folder, so the workflow is resumable, reviewable in diffs, and survives across sessions. Each unit of work gets one parent folder named after a slug, such as specs/my-first-mvp-iteration.

Requirements

You need Claude Code or Codex, and a project that's a git repo — the skills write to specs, and the code review step uses git. Run the skills from inside the project you want to change, and create one feature branch per unit of work.

Install trails

Claude Code

This repo is a self-contained Claude Code plugin (.claude-plugin/plugin.json at the root). Symlink it into ~/.claude/skills/:

ln -s /path/to/trails ~/.claude/skills/trails

It loads on your next session as trails@skills-dir, and its skills become available as /trails:spec, /trails:plan, /trails:implement, and /trails:deslop. To confirm:

claude plugin list

Codex

This repo is also a self-contained Codex plugin (.codex-plugin/plugin.json), with its own marketplace file at .agents/plugins/marketplace.json. Add the repo as a marketplace, then install the plugin from it:

codex plugin marketplace add /path/to/trails    # or the git URL
codex plugin add trails@trails

Codex namespaces plugin skills by plugin name, so the skills become available as trails:spec, trails:plan, trails:implement, and trails:deslop — no collisions with any other spec, plan, or implement skills you have installed. Start a new Codex task in the project you want to work on, then invoke a skill with a $ mention, for example $trails:spec add rate limiting to the public API. If the skills don't appear right away, start a new task.

The workflow artifacts and arguments are the same as in Claude Code. Only invocation differs.

Note: codex plugin add caches a snapshot of the plugin. After you pull or edit trails locally, reinstall to pick up your changes — codex plugin remove trails then codex plugin add trails@trails, or codex plugin marketplace upgrade for git-sourced marketplaces.

How the workflow works

flowchart LR
    SPEC[SPEC] --> PLAN[PLAN] --> IMPLEMENT

    subgraph BUILD [IMPLEMENT]
        direction LR
        IMPLEMENT[IMPLEMENT] --> REVIEW[REVIEW]
    end

Loading

Step 1: Write a spec

spec turns a rough idea, a new feature, or a bug description into a written spec: problem statement, numbered features with acceptance criteria, technical solution, and out-of-scope items. It works for greenfield projects as well as features and bugfixes in an existing codebase — when there's existing code, it explores that first so the proposed approach fits your conventions.

Expect clarifying questions. The skill drafts the spec, reviews it with you, then runs a self-sufficiency check. Keep talking to the agent until you're happy with the result.

In Claude Code:

/trails:spec add rate limiting to the public API

In Codex:

$trails:spec add rate limiting to the public API

The spec is saved to specs/<slug>/spec.md.

Step 2: Create a plan

plan reads a spec and produces a phased implementation plan: small, concrete tasks grouped under each spec feature, with dependencies tracked at the feature level. Plans are plain markdown checkboxes, so they're easy to read, diff, and hand-edit.

In Claude Code:

/trails:plan rate-limiting

In Codex:

$trails:plan rate-limiting

The plan lands in specs/<slug>/plan.md, for example:

- [ ] 1. Request counting (depends on: none)
  - [ ] 1.1 Add a token-bucket counter keyed by client ID
  - [ ] 1.2 Wire the counter into the API middleware
- [ ] 2. Limit responses (depends on: 1)
  - [ ] 2.1 Return 429 with a Retry-After header when exceeded

Step 3: Implement the plan

implement runs one task at a time, verifies the change, and ticks the plan's checkboxes as it goes. Pass the spec or plan slug; leave it out and the skill lists the specs it finds and asks which one you mean.

In Claude Code:

/trails:implement rate-limiting          # picks the next open task
/trails:implement rate-limiting 1.2      # runs a specific task
/trails:implement rate-limiting 1        # runs every remaining task in feature 1

In Codex:

$trails:implement rate-limiting          # picks the next open task
$trails:implement rate-limiting 1.2      # runs a specific task
$trails:implement rate-limiting 1        # runs every remaining task in feature 1

For each task it claims the parent feature with a [~] in-progress marker, implements the change, runs the relevant tests and checks, and gets an independent report-only review in a fresh context. The task is then marked [x], and the feature once all of its tasks are done. Blocked work stays open with a Blocked: <reason> note instead of a checkmark.

The spec is single-writer: implement never edits spec.md. When implementing reveals a gap in the spec, or the plan needs to change, it appends an [open] entry to specs/<slug>/proposals.md — an inbox where the implementer gives you feedback on the spec and the implementation. What happens next is your call: act on a proposal, update the spec, reject it, or spin it out as a new unit of work. Record the decision by flipping the marker to [applied] or [rejected].

Committing and opening a pull request usually ends the implementation step. That's deliberately left out of the skill, so you can decide how to parallelize — one pull request for the whole spec, one per feature, or something else.

Experimental: deslop

Outside the spec → plan → implement chain, deslop scrubs typical AI-generated patterns — "slop" — out of existing code. Point it at a file or directory, or run it without an argument to target the working diff:

/trails:deslop src/api/        # Claude Code
$trails:deslop src/api/        # Codex

Safe, behavior-preserving removals are applied directly and then verified against your project's tests: comments that only narrate the code, defensive checks against impossible states, leftover debug logging, and similar surface tells.

Riskier findings come back as reports instead. Duplication, god modules, overengineering, and misused abstraction are written up as concrete refactor proposals, and tests that assert implementation details rather than the interface or contract are flagged. Nothing structural changes until you say so.

Notes

• Plans track dependencies at the feature level only. Tasks within a feature run in list order.
• The [~] in-progress marker is a soft coordination signal, not a lock — it doesn't prevent two sessions from picking up the same feature.
• All state lives in specs/<slug>/ in your project (spec.md, plan.md, and proposals.md if any proposals were filed), not in the plugin. Trails itself is stateless.