esper:apply

You are implementing a backlog item.

The user's argument (if any): $ARGUMENTS

Step 1: Check setup

Run esperkit config check. If it exits non-zero, tell the user to run /esper:init first and stop.

Run esperkit plan list --dir active --format json to check for active plans. If the JSON contains any entries:

• •The JSON includes title and branch fields.
• •Tell the user: "There is already an active plan: [title] on branch [branch]."
• •Ask (using AskUserQuestion): "Continue with it, or suspend it and start a new one?"
  • •Continue: Skip to Step 6 (skip the plan-mode gate — infer progress from git log --oneline -10 and the plan's ## Progress section, then resume from remaining steps)
  • •Suspend: Run esperkit plan suspend <filename>, then continue to Step 2

Step 2: Select the plan

Run esperkit plan list --dir pending --format json to get all pending plans (already sorted by priority then id).

If the list is empty: "No pending items in the backlog." Suggest /esper:plan or /esper:fix to add one. Stop.

If an argument was given: Match against each plan's id or title field (substring, case-insensitive). If no match, display the list and ask the user to clarify.

If no argument: Select the first plan in the list (already sorted by lowest priority, then lowest id).

Show the selected plan title and use AskUserQuestion to confirm before proceeding.

Step 3: Create the git branch

Use the branch field from the plan JSON obtained in Step 2. Attempt BEFORE modifying plan state:

git checkout -b <branch-name>

If the branch already exists:

git checkout <branch-name>

If checkout fails for any other reason, stop and report the error. Do NOT proceed.

Step 4: Activate the plan

Only after the git branch is confirmed:

Run esperkit plan activate <filename> — this moves the file from pending/ to active/ and sets status: active.

Step 5: Read plan context

Read:

• •The active plan file (full content)
• •.esper/CONSTITUTION.md
• •.esper/phases/<current_phase>.md (get current_phase by running esperkit config get current_phase)

Step 6: Plan-mode gate — generate todo list

Do not skip this step. Do not start writing code until the todo list is approved.

Use the EnterPlanMode tool.

While in plan mode:

1. •

   Read each file listed in the plan's ## Files to change section

2. •

   Read any additional files referenced in the plan's ## Approach section (imports, parent modules, config files)

3. •

   Based on the exploration, use TodoWrite to generate a comprehensive implementation checklist.

   Structure the todos as concrete, code-level tasks. Each todo should be one logical unit of work that will result in a milestone commit. Examples:

   • •"Create src/auth/middleware.ts with JWT validation logic"
   • •"Wire middleware into src/app.ts route registration"
   • •"Add test cases to test/auth.test.ts"
   • •"Update plan ## Progress section"

   If the exploration reveals anything the plan didn't anticipate (missing deps, conflicting patterns), add those as todos and note the deviation.

4. •

   Show the TodoWrite checklist alongside the plan's ## Approach section. If they differ, explain why.

Use the ExitPlanMode tool (this presents the todo list for user approval).

After the user approves: continue to Step 7.

Step 7: Implement with milestone commits

Implement the todos in order, following the plan's ## Approach and the project's CONSTITUTION principles.

Rules during implementation:

• •Read each file before modifying it
• •Follow existing code patterns and conventions
• •Do not add features beyond what the plan describes
• •Do not refactor surrounding code unless the plan explicitly requires it

Mandatory milestone commits — after each todo item is completed, commit immediately:

git add <specific files changed for this milestone — never git add -A>
git commit -m "$(cat <<'EOF'
<feat|fix|chore>: <what this milestone accomplished>

plan <id> — <title> (milestone <N>/<total>)
EOF
)"

If something unexpected is discovered mid-implementation (missing dependency, conflicting pattern, ambiguous requirement):

1. •Stop and describe the discovery to the user via AskUserQuestion
2. •Agree on a revised approach
3. •Update the plan's ## Approach and ## Files to change to reflect what will actually be built
4. •Update TodoWrite to reflect the change
5. •Continue

The plan is a living document — keep it accurate as the implementation evolves.

Step 8: Update Progress and wrap up

After all todos are implemented:

Add or update the ## Progress section in the active plan file:

## Progress
- Milestones: [N] commits
- Modified: [list of files changed]
- Verification: not yet run — run /esper:finish to verify and archive

Tell the user:

• •"Implementation complete — [N] milestone commits made."
• •Next: /esper:finish to run verification, commit any remaining changes, and archive the plan.