Features

Three layers: user-facing Skills, bundled Subagents they spawn, and lifecycle Hooks that persist sprint state across /clear.

Skills

📐 /todoist-ticket

Convert a plan, PRD, spec, or design file into a structured Todoist user story hierarchy.

  • 🗂️ Guided spec intake — checkbox prompt: type the spec inline or load it from a file path.
  • 🎯 Live project + column picker — fetches projects/sections from Todoist with a "Create new" fallback (default: Backlog).
  • 🧠 Interrogation loop — one deep question per turn surfaces ambiguities and hidden dependencies.
  • 📋 Scrum format — "As a [role], I want [goal], so that [benefit]" with acceptance criteria.
  • 🧱 Vertical feature slices — 1 story = 1 shippable capability across every layer. Per-layer steps live as subtasks.
  • 🔩 Subtasks ordered DB → API → UI → tests so the executor walks them top-down.
  • 🚀 Direct push into Todoist via MCP.

📦 /todoist-sprint

Slice a Todoist backlog into a high-cohesion sprint sized to your context budget.

  • 🎚️ Low / Medium / High — ~60k (3–5 tasks) · ~100k (5–7) · ~150k (7–10).
  • 🧩 Dependency sorting — groups by feature area, sequences DB → API → UI.
  • 🎯 Checkbox project + column selection with "Create new" fallback.
  • 🤝 Pairs with /todoist-execute — batch sizes tuned to the subagent-discard pipeline.

💻 /todoist-execute

Implement sprint tasks autonomously through a token-optimized subagent pipeline.

  • 📁 Workspace coupling with your active local repo.
  • 🧠 Orchestrator + workers — ae-investigator → ae-builder / ae-architect → ae-reviewer. Main thread stays cold.
  • 💸 Tiered models — Haiku for locators/surgical edits, Sonnet for logic/review, optional Opus-boost for multi-file builds.
  • 🛡️ Mandatory quality gate — every diff passes ae-reviewer before migration.
  • 🧱 Auto-classified units — parent + children = slice unit (atomic); orphans = flat unit.
  • 🧠 Repo-persistent contract memory — gitignored .claude/ae/shared_context_execute.md survives /clear.
  • 🪶 Batched distill (5×) cuts ~50 haiku spawns to ~10 on long runs.
  • 🔒 flock-guarded memo writes protect concurrent sessions.
  • ♻️ Discard-after-migrate — subagent transcripts dropped, one-line receipt kept.
  • 🧼 Atomic slice migration — pass moves parent + every child; fail leaves all.

🏁 /todoist-review

Audit QA tickets, verify UI visually, triage failures back into the sprint.

  • 🧪 Toolchain fingerprint — auto-detects Biome, ESLint, Prettier, TS, Vitest, Ruff, Mypy, Pytest, Cargo, Go, Next/Vite/Expo.
  • ⚡ Smoke pass once — format · lint · typecheck · tests · build cached at start, reused across 30–50 tickets.
  • 🎯 Dynamic scope cascade — ticket metadata → working diff → ae-investigator fallback.
  • 🖼️ UI verification — boots dev server once, captures Playwright headless screenshots into .review-artifacts/.
  • 📇 Two-line triage cards + one dispatch prompt: bulk move + rerun, per-ticket, or leave.
  • 🛡️ Non-mutating auditor — --check / --noEmit only.
  • 🧠 Memo-aware reviewer — reads execute's contracts so intentional reuse is not flagged.
  • 🧼 Self-wipe on queue drain or 7-day staleness.

Subagents

Bundled workers spawned by /todoist-execute and /todoist-review. Each enforces a hard scope ceiling and returns a caveman-compressed receipt — the orchestrator pays for the receipt, not the worker's transcript.

locate ae-investigator
→
edit ≤2 ae-builder
or
edit 3+ ae-architect
→
verify ae-reviewer
AgentModelFile scopeWrites?
ae-investigatorHaikuRead-only—
ae-builderHaiku · Sonnet≤ 2 files✓
ae-architectSonnet · Opus3+ files✓
ae-reviewerSonnetDiff or scope—

🔍 ae-investigator

Read-only code locator. Returns a file:line table, refuses to suggest fixes.

  • 📍 Locate-only — Read, Grep, Glob, read-only Bash.
  • 🗜️ Caveman-compressed grouped headers cut ~60% tokens vs vanilla Explore.
  • 🛑 Hard refusals: asked to fix → Read-only. Spawn ae-builder.
  • 🔢 Totals footer: 2 defs, 5 refs.

🛠️ ae-builder

Surgical 1–2 file edit. Typos, renames, single-function rewrites, format-preserving tweaks.

  • 📏 Hard 2-file ceiling — 3+ files terminates as too-big. split: …
  • 🪶 No Bash — pure Read / Edit / Write / Grep / Glob.
  • 📜 CLAUDE.md conventions enforced. No drive-by refactors.
  • 🔁 Read → Edit → Re-Read. Mismatch surfaces as verified: mismatch @ path:line.
  • 📦 Receipt-only output: <path:line-range> — change ≤10 words.

🏗️ ae-architect

Multi-file build (3+ files or cross-cutting refactor). Writes new files when ticket warrants.

  • 📐 Inverse ceiling — <3 files → too-small. use ae-builder.
  • ⚖️ Convention enforcer — Biome, /types, /utils, fn ≤40 LOC, file ≤300 LOC, no console.log, Zod at boundaries.
  • 🧪 Read-only Bash — git status, git diff, rg, tsc --noEmit, biome check.
  • 🚫 Tombstone-free — no // removed comments, no back-compat shims.
  • 📋 Receipt: files: N | new: X | edit: Y | delete: Z + per-file change + summary.

🧑‍⚖️ ae-reviewer

Code reviewer in two input modes: scope (HEAD) or diff (working/branch/commit).

  • 🔀 Dual mode — files: → scope; diff_source: → diff.
  • 🎯 Criteria-driven — every unmet criterion = one finding. 🔴 bug / 🟡 risk / ❓ question.
  • 🧷 State-hook aware — reads .ae-sprint-state.json, filters by task_id + project_id, narrows git log --since=<ts>.
  • 🔬 Dynamic discovery — Grep/Glob + git log -S for half-merged refactors.
  • 📋 Strict output: path:line: emoji severity: problem. fix. Zero findings → No issues.
  • 🛡️ Non-mutating — refuses git checkout, git reset, npm install, formatter --write.

Hooks

Two lifecycle hooks declared in .claude-plugin/plugin.json. They power the persist-across-/clear guarantee: migration timestamps live on disk and re-inject on the next SessionStart.

HookEventTrigger
ae-session-start.jsSessionStartEvery new session / post-/clear
ae-migration-log.jsPostToolUseAfter Todoist update-tasks with section_id

🪝 ae-session-start.js

Injects today's migrated task IDs and shared memo blocks so the orchestrator resumes cleanly after /clear.

  • 📅 Same-day migration replay — filters state.migrations[] by today's ISO date.
  • 🆔 Project-aware skip — matches by project_id before skipping.
  • 🧠 Dual memo injection — execute + review shared contexts.
  • 🪨 4096-byte memo cap; symlinked files refused.
  • 🤫 Silent-fail; never blocks session start.
  • ⏱️ 5s timeout with Loading sprint state... statusline.
  • 🛣️ $CLAUDE_CONFIG_DIR respected.

🪝 ae-migration-log.js

Logs column migrations to ~/.claude/.ae-sprint-state.json whenever a Todoist update-tasks call moves a task to a new section.

  • 🎯 Section-move filter — only fires when section_id is present.
  • 📦 Full lineage — task_id, task_content, section_id, project_id, ISO timestamp.
  • 🔐 Symlink-refusing reader — lstatSync() check before parse.
  • 🧾 Atomic write — .tmp + renameSync.
  • 📉 200-entry FIFO cap.
  • 🤫 Never blocks Claude — failures exit 0.
  • 🛣️ $CLAUDE_CONFIG_DIR respected.

State file shape — ~/.claude/.ae-sprint-state.json

{
  "migrations": [
    {
      "task_id": "1234567890",
      "task_content": "Add JWT refresh endpoint",
      "section_id": "9876",
      "project_id": "5432",
      "timestamp": "2026-05-21T14:32:08.421Z"
    }
  ]
}