The /start command is a 1,400 line markdown state machine with 15 numbered steps that takes a Linear ticket ID and produces a ready-to-test implementation. I type /start AUTM-123 and walk away. When I come back, there’s a feature branch, an implementation plan posted to Linear, working code, and passing tests.

The previous post covered optimizing /commit for the 1M context window. This one covers /start - the command that runs before commit, and the one where defensive overhead had the most room to shrink.

What /start Actually Does

The 15 steps, in sequence:

0. Parse arguments, check for existing sessions 0.5. Create 9 workflow tasks with dependency wiring
1. Detect project type from working directory
2. Pre-flight validation (clean worktree, valid repo)
3. Validate ticket ID format
4. Fetch ticket from Linear
5. Fetch comments (for reopened ticket detection)
6. Detect reopened tickets with feedback context
7. Validate team-repository match, auto-switch if needed 7.1. Load Workflow Profile from CLAUDE.md 7.5. Detect session rules from user message
8. Create implementation plan (via Plan subagent on Sonnet)
9. Get user approval on plan
10. Create feature branch
11. Update Linear to In Progress, post plan comment
12. Confirm branch ready
13. Implement changes (the actual coding)
14. Run quality gates 14.5. Verification gate
15. Hand off for user testing

Steps 4 through 7.1 were the problem. Five sequential operations, each waiting for the previous one to complete, despite most of them being independent.

The Sequential Tax

I mapped the data dependencies between steps. The question was simple: which operations actually need results from previous operations, and which are just sequential because I wrote them that way?

Step 4 (fetch ticket) returns the UUID and team prefix. Step 5 (fetch comments) needs the UUID. Step 7 (validate team-repo) needs the prefix. Step 7.1 (load profile) needs TARGET_DIR, which Step 7 might change. So there’s a real dependency chain: 4 → 5, 4 → 7 → 7.1.

But Step 7.1 (reading CLAUDE.md) doesn’t actually need Step 7’s result in most cases. Most of the time, you’re already in the right repo. The profile read could start immediately - and if Step 7 later discovers a repo mismatch, the profile gets re-read from the correct directory.

This gave me the restructured flow.

Five Changes

1. Parallel Ticket Fetch + Profile Load

Before: Five sequential MCP/file calls across Steps 4, 5, and 7.1.

After: Two parallel messages.

Message 1 dispatches three calls simultaneously:

• get_issue (Linear MCP)
• Read(CLAUDE.md) (profile load - moved from Step 7.1)
• Project detection (already happened in Step 1, but formalizes the parallel structure)

Message 2 dispatches two calls that need the UUID from Message 1:

• list_comments (needs UUID)
• Team-repo validation (needs prefix)

The total wall-clock time drops from about 8 seconds of serial calls to about 3 seconds of two parallel batches. The profile load that previously waited until Step 7.1 now runs concurrently with the ticket fetch. If Step 7 later discovers a repo mismatch (rare), the profile gets re-loaded from the new TARGET_DIR - a small cost paid only in the uncommon case.

2. Conditional Task Creation

Step 0.5 creates 9 tasks with full dependency wiring. That’s 2 messages and 17 tool calls. At 200K tokens, this made sense - tasks survive context compaction, so they’re the recovery mechanism when Claude loses its place mid-workflow.

At 1M tokens, a single /start workflow rarely compacts. The 9 tasks are overhead for the majority of tickets.

I added conditions. Tasks are created when:

• Chain mode is active (multiple tickets need per-ticket tracking)
• The ticket is an epic child (complex, multi-file work)
• Resuming a previous session (tasks already exist)

For a simple single-ticket /start - the most common case - task creation is skipped entirely. If the plan turns out to have 5+ implementation tasks, tasks get created retroactively at that point.

The TaskUpdate calls throughout subsequent steps guard against the no-tasks case: if (t1) TaskUpdate(t1.id, ...). This is a no-op pattern - it adds no overhead when tasks exist, and silently skips when they don’t.

3. Reduced Checkpoints

The old /start wrote session state after Steps 7, 7.5, 8, 9, 10, 11, 12, 13, 14, and 15. That’s roughly 10 file writes during a single workflow run. Each write is cheap individually, but collectively they add up - and more importantly, they represent 10 assumptions that context might compact between any two adjacent steps.

With 1M tokens, I reduced to 3 critical checkpoints:

1. After plan approval (Step 9) - the first irreversible decision
2. After branch creation (Step 10) - git state is now established
3. At handoff (Step 15) - implementation complete

Everything between these points can be reconstructed from git state and the Linear API if context does compact. The plan file is on disk. The branch exists in git. The ticket status is in Linear. The session file doesn’t need to track what’s already tracked elsewhere.

4. Inline Plans for Simple Tickets

Step 8 always dispatched a Plan subagent on Sonnet. The subagent explores the codebase, reads relevant files, and synthesizes an implementation plan. This keeps verbose search output out of the main context window - a significant concern at 200K tokens, less so at 1M.

For tickets where the description clearly scopes to 1-3 files - “fix the button color on the settings page” or “add a loading spinner to the dashboard” - the subagent dispatch overhead (10-15 seconds) isn’t justified. The main context has plenty of room for a few file reads and a short plan.

The new logic is conditional:

• 3 or fewer files in scope AND clear description → generate the plan inline using Glob/Grep/Read directly
• 4+ files, ambiguous description, reopened ticket, epic child → dispatch the Plan subagent as before

This trades a small amount of Opus context (the inline plan uses the more expensive model) for 10-15 seconds of wall-clock time on simple tickets. Since simple tickets are the majority, the aggregate savings are meaningful.

5. Early Profile Load

This isn’t a separate optimization - it falls out of Change 1. But it’s worth calling out because it changes the step ordering in a way that matters for the rest of the workflow.

The Workflow Profile (base branch, quality gates, review settings, deploy hints) previously loaded at Step 7.1 - after team-repo validation. Now it loads in Message 1 of the parallel fetch, alongside the ticket fetch. The Step 7.1 heading still exists in the command file for documentation purposes, but it notes that execution moved to the parallel fetch.

This means the profile is available earlier. Steps 2-3 (pre-flight validation) still use the basic PROJECT_TYPE from Step 1, but anything from Step 4 onward has full profile access. No behavior change in normal flow - the profile was always available by Step 8 when it was first needed - but the earlier load eliminates a category of bugs where profile fields are referenced before the profile is parsed.

What I Didn’t Change

The session state schema stays the same. All those fields - stashCreated, stashOriginalBranch, chainInvokingDir, ticketContext - are still valuable when context does compact. The schema isn’t the problem. Writing it 10 times per workflow was.

The Plan subagent stays for complex tickets. The 1M window is large but not infinite. A thorough codebase exploration for a 10-file feature change produces thousands of lines of Grep and Read output. Keeping that in a subagent’s context (on cheaper Sonnet) rather than the main context (on Opus) is still the right trade-off for complex work.

The verification gate at Step 14.5 stays mandatory. This is the one that catches skipped unit tests - a real problem I documented after a production incident. Context compaction making Claude skip tests was the original motivation, and even with 1M tokens reducing compaction frequency, the verification gate costs seconds and prevents hours of debugging.

Performance Target

The range depends on ticket complexity. Simple tickets save the most (inline plan + no tasks = ~22s). Complex tickets save the least (subagent + tasks + full checkpoints = ~12s from the parallel fetch alone).

The Pattern

The same lesson from the /commit optimization applies here: defensive machinery built for one constraint persists after the constraint changes. The difference with /start is that the machinery is more deeply embedded. Session checkpoints aren’t a single function call - they’re woven into the control flow between every pair of steps. Removing them required reasoning about what’s reconstructable from external state (git, Linear) versus what exists only in the session file.

The next two posts cover /staging and /production - the deployment commands. The pattern shifts there from “remove defensive overhead” to “parallelize independent external checks” - Sentry queries, smoke tests, worktree resets. Different shape of optimization, same underlying principle.

Yesterday I laid out the case for rewriting my four deployment commands around the 1M token context window. This post covers the first and highest-impact rewrite: /commit.

If you haven’t read the deep dive on how /commit works , the short version is: it’s a 1,170-line markdown state machine that handles quality gates, review triage, agent dispatch, commit message generation, pushing, and Linear updates. One command, twelve steps.

The 1M context window didn’t change what /commit does. It changed what /commit needs to defend against. And that defense was expensive.

The Audit

I mapped every operation in /commit by type: sequential Bash calls, MCP round-trips, agent dispatches, session file writes. Then I identified which operations were sequential because they had to be (data dependency) versus sequential because they were written that way at 200K tokens when keeping context small mattered more than speed.

The results were clarifying. Three categories of waste:

1. Independent operations running sequentially — type-check and lint, simplify agents and review agents, Linear read calls
2. Redundant computation — the git diff computed three separate times across three steps
3. Defensive overhead — ten session file writes during a single commit flow, most of which exist for a compaction scenario that almost never happens at 1M tokens

Six Changes

1. Parallel Quality Gates

The simplest win. Step 2 ran pnpm run type-check then pnpm run lint sequentially. Both are read-only operations that don’t modify files. They don’t depend on each other.

Before:

pnpm run type-check    # ~30s
pnpm run lint           # ~30s
# Total: ~60s

After:

pnpm turbo type-check lint --concurrency=2    # ~35s

Turbo handles the parallelism natively. Both tasks run simultaneously, bounded by whichever finishes last. The --concurrency=2 flag is explicit about what we want — it’s not a magic number, it’s “these two specific tasks, in parallel.”

Savings: ~25 seconds per commit.

2. Collapsed Simplify + Review Pipeline

This was the biggest conceptual change. Previously, /commit had a two-phase pipeline:

1. Phase 1 (Step 2.5): Dispatch 3 simplify agents on Sonnet. Wait for all to complete. Re-stage any changes they made.
2. Phase 2 (Step 4): Dispatch N review agents on Sonnet. Wait for all to complete.

The rationale was that review agents should see the “improved” diff after simplify fixed things. But in practice, simplify finds nothing on the majority of commits. The review agents were waiting 30-45 seconds for a phase that usually produced no changes.

After: Triage runs first (it needs the file list to determine which agents to dispatch), then ALL agents — simplify and review — launch simultaneously in a single message. In the common case where simplify finds nothing, review agents already see the final diff. If simplify does modify files, only the review agents whose findings overlap with modified files get re-dispatched.

The key insight came from a review comment on the Linear ticket: triage must run before dispatch (you need to know the review level to know which agents to launch), but triage only reads file names — it doesn’t need file content. So the sequence is: cache the diff once, run triage on the file list, then dispatch everything in parallel.

This created a new step numbering. The old Step 2.5 (Simplify) and Step 4 (Review Dispatch) merged into Step 2.75 (Parallel Simplify + Review Dispatch). The old Steps 3 and 4 still exist as documentation of the triage logic and agent selection — they just note that execution moved to Step 2.75.

Savings: ~30-45 seconds on commits where simplify finds nothing (majority). ~15-25 seconds when simplify does modify files (targeted re-dispatch instead of full re-run).

3. Cached Git Diff

The diff was computed three times:

• Step 2.5: passed to simplify agents
• Step 3: used for triage signal-gathering
• Step 4: passed to review agents

Now it’s computed once in Step 2.5 (“Compute and Cache Diff”) and the cached DIFF_CONTENT and ALL_FILES variables are reused by all downstream consumers.

Savings: Tokens, not seconds. But fewer tokens means faster processing throughout the pipeline.

4. Batched Linear MCP Calls

Step 8 (Update Linear) was making 4-6 serial MCP calls: fetch the issue, update status, fetch all workspace labels, update with merged labels, fetch comments (for threading), post progress comment.

A review comment caught my initial design: I’d planned 2 messages, but list_comments needs the UUID from get_issue. The corrected design uses 3 messages:

1. get_issue (returns UUID)
2. list_issue_labels + list_comments (both need UUID, dispatched in parallel)
3. save_issue (status + labels) + save_comment (dispatched in parallel)

Savings: ~5-8 seconds per commit.

5. Aggressive Learning Capture Skip

Step 1.5 scans the conversation for learnings to capture before committing. It already skipped in chain mode and short conversations. I added one more skip condition: NONE-level review triage (only docs/config changed). If you’re committing a markdown file, there’s unlikely to be a novel technical insight worth capturing.

Savings: ~3-5 seconds on doc/config commits.

6. Reduced Checkpointing

The old /commit wrote session state at multiple points throughout the flow — after quality gates, after triage, after review, after staging. With 200K tokens, this made sense: if context compacted mid-commit, the session file told you where to resume.

With 1M tokens, context compaction during a single /commit run is extremely rare. Two writes are sufficient:

1. Entry: awaiting_user_test → committing
2. Exit: committing → committed

If context does compact between these two points (unlikely but possible for enormous commits), the session shows committing and you re-run /commit — all steps are idempotent.

Savings: ~2-3 seconds per commit.

Bonus: Timing Instrumentation

A review comment on the ticket suggested adding baseline measurements before optimizing. I added COMMIT_START at Step 0 and COMMIT_DURATION at Step 10, displayed in every commit’s success summary. This gives us the “before” numbers to compare against, and — critically — feeds into the pipeline automation system (PLA-781) which uses average commit duration as an advancement criterion.

What I Learned

The biggest lesson isn’t about any specific optimization. It’s about how constraints shape architecture in ways that persist long after the constraint changes.

Every one of these sequential patterns had a reason at 200K tokens. Serializing simplify → review kept context smaller. Multiple session checkpoints enabled recovery. Separate diff computations avoided storing large strings in variables. The architecture was correct for its constraint.

When the constraint changed — 200K to 1M, a 5x increase — the architecture didn’t automatically adapt. The code still worked. It was just slow. And “slow but correct” feels fine until you measure it and realize you’re spending two minutes on overhead that could take thirty seconds.

The meta-lesson: when a foundational constraint changes by an order of magnitude, audit everything built on that constraint. Don’t fix one thing — map the entire dependency chain. I found six optimizations in /commit because I looked at every operation type, not just the one that felt slowest.

Performance Target

I’ll update this table with measured numbers after a week of real usage. The timing instrumentation makes that straightforward — every commit logs its duration now.

What’s Next

Three more commands to optimize: /start (parallel ticket fetch, conditional task creation, inline plans for simple tickets), /staging (parallel test+build, parallel Sentry queries, parallel worktree resets), and /production (parallel verification, slimmer health audit). Same theme throughout: identify independent operations, run them concurrently, remove defensive overhead that 1M tokens makes unnecessary.

The implementations are done — all four commands are updated. The next three posts will cover what changed and what I learned in each one.

I’ve spent the few months building (and endlessly iterating to improve) four markdown state machines - /start , /commit , /staging, and /production - that together manage my development lifecycle. They total about 4,700 lines of structured decision trees. I wrote about the first two already.

Now I’m rewriting all four.

The reason is a single number: 1,000,000.

The 200K Constraint Shaped Everything

The commands didn’t start as 4,700 lines of state machines. They started as simple prose instructions - “fetch the ticket, create a branch, make a plan.” That worked until I hit the 200,000 token context window regularly. Claude would be halfway through implementing a feature and the conversation would compact - Claude Code’s way of compressing old messages to make room. After compaction, Claude would lose track of which tasks were done, forget what files it had already modified, or skip steps entirely. I’d come back to find it had re-implemented something it already finished, or worse, started writing code without ever getting plan approval.

The state machine structure evolved as a direct response to this. Numbered steps with explicit decision trees replaced prose paragraphs. Disk-based session files captured progress after every step so Claude could recover. Claude Code added features that helped - task lists that survive compaction, for instance - but for long-running workflows like /start that span ticket fetch through implementation through testing, the state machine was still essential. Even with task lists, Claude needed explicit checkpoints and file-based progress tracking to stay on course after compaction. The machinery made the system reliable. It also added a lot of overhead.

This pressure drove almost every architectural decision. Session state files that checkpoint after every single step. Task creation with full dependency wiring so Claude can recover after compaction. Plan subagents that exist partly to keep verbose codebase exploration out of the main context window. Disk-based progress tracking with checkbox files because in-memory state couldn’t be trusted to survive.

All of that machinery works. It’s also slow.

What Changes With 1M Tokens

The 1M context window landed as generally available on Opus 4.6 with no long-context premium. In practical terms, a full /start workflow - command loading, ticket fetch, codebase exploration, plan generation, implementation, and quality gates - can now fit in a single context window without compaction about 85% of the time. The elaborate recovery machinery that made the system reliable at 200K is now overhead for most tickets.

I sat down with Claude and did a systematic analysis of all four commands. I reviewed the commands, the recent blog posts, fetched the Claude Code documentation on context management, and mapped every bottleneck. The shift from “context pressure” to “wall-clock time” as the primary constraint reframes every optimization opportunity.

Here’s what I found - the highest-impact changes are parallelization:

• /commit: Quality gates (type-check and lint) run sequentially despite being independent read-only operations. Parallelizing them saves 20-30 seconds on every single commit. The simplify-then-review pipeline serializes two phases that could overlap. Batching Linear MCP calls from 6 serial round-trips to 2 parallel messages saves another 5-10 seconds.

• /start: Ticket fetching, comment loading, and profile reading are three sequential MCP/file operations that could all run in the first parallel message. For simple tickets, nine task creations with dependency wiring add 4 seconds of overhead that’s rarely needed with 1M context.

• /staging: Local validation runs tests then builds sequentially - that’s 40-60 seconds of unnecessary waiting since they operate on different output directories. Six sequential Sentry queries for post-deploy error checking could be one parallel dispatch.

• /production: Sentry monitoring and smoke tests run back-to-back despite being completely independent. The environment health audit dispatches a full Sonnet subagent when a few curl commands would catch the same critical issues.

Total estimated savings across one full cycle - start a ticket, commit, stage, deploy: about 170 seconds. That’s meaningful when the cycle happens dozens of times per day.

A Quick Note About the Table of Contents Bug

If you read the first two posts in this series, you might have noticed the table of contents behaving strangely. I added a sticky sidebar TOC with auto-collapse - when you scrolled past a section, it would collapse to save space. The feature shipped and looked great in testing.

Then it created a scroll trap in Chrome.

The auto-collapse used an IntersectionObserver to watch heading elements. When you scrolled past a heading, the observer fired and collapsed a TOC section. But collapsing a section changed the page height, which shifted the scroll position, which triggered the observer again, which collapsed another section. The page would lock up in a feedback loop - the exact kind of bug that manual testing doesn’t catch because it only triggers at specific scroll positions with specific content lengths.

I tried fixing the observer logic twice. The first fix added a debounce. The second fix tracked whether the collapse was user-initiated versus observer-initiated. Both reduced the frequency but didn’t eliminate the loop. The third fix was the right one: I removed auto-collapse entirely. The TOC stays expanded. It’s less clever and completely reliable.

This is the kind of bug that slips through because the feature worked perfectly in the happy path. I tested it with short posts and long posts, scrolled up and down, clicked TOC links. The feedback loop only appeared with specific combinations of heading density, viewport height, and scroll speed. An automated scroll test or a longer manual session would have caught it - but I was excited about the feature and shipped it fast.

The lesson is one I keep relearning: the clever version of a feature is rarely the right version. A static table of contents does everything users need. The auto-collapse was solving a non-problem.

What’s Next

Four posts, one per command. Each will cover the analysis, the implementation changes, performance measurements, and what the 1M context window specifically enables. The order follows the dependency chain:

1. /commit - the highest-impact optimizations (parallel quality gates, collapsed review pipeline)
2. /start - parallel ticket fetching, reduced checkpointing
3. /staging - parallel test+build, parallel Sentry queries
4. /production - parallel verification, slimmer health audit

The theme across all four is the same: the 200K context window made reliability the primary engineering challenge. Elaborate recovery mechanisms, defensive checkpointing, aggressive context delegation to subagents. With 1M tokens, reliability is largely solved by having enough room. The engineering challenge shifts to speed - and speed comes from parallelism.

I type /commit after finishing a feature. Claude scans the diff, counts eight changed files across two directories, checks that none of them touch auth or migrations, classifies the review as LIGHT, dispatches a code reviewer and a UI consistency checker in parallel on Sonnet, runs a three-agent simplify pass that catches a redundant API call, generates a commit message referencing the Linear ticket, pushes to origin, posts a threaded progress update under the implementation plan comment, applies an auto-detected frontend label, and sets the status to In Progress.

One command. Twelve steps. A review pipeline that would take me twenty minutes runs in about forty seconds.

/commit is 1,170 lines of markdown. Like /start , it’s not a script - it’s a structured decision tree that Claude reads and executes. And like /start, every rule in it exists because something went wrong.

The Three-Level Review Triage

The first version of /commit ran a full code review on every commit. Five parallel agents analyzing every diff, even when the only change was a CSS color value. It was thorough and spectacularly wasteful.

The fix was triage. /commit now classifies every commit into one of three levels based on what actually changed:

NONE  → Only docs, tests, config, CSS. No review agents. Just commit.
LIGHT → Source code changed, under 10 files. Code reviewer + selective agents.
FULL  → 10+ files, shared packages, or sensitive paths. Full agent battery.

The classification isn’t a guess. Claude runs two bash commands in parallel - one counts files and lines, the other checks every file path against a set of pattern matchers:

=== Critical Files ===    middleware.ts, auth.ts, /auth/
=== Security Paths ===    payment, billing, webhook
=== Platform Packages === packages/*
=== Migrations ===        supabase/migrations/

Any hit on a critical path forces FULL review regardless of file count. A single-line change to middleware.ts gets the same scrutiny as a twenty-file feature.

The rule that matters most is that NONE never applies to source code. Even a one-file .tsx change gets at least LIGHT review. I added this after a “small” prop rename broke a component in production. The change looked trivial - rename isOpen to isVisible - but the prop was used in three other files that weren’t updated. A LIGHT review would have caught the missing references in seconds.

Signals are evaluated in priority order. Path-based overrides win over everything else:

1. Path-based override? (middleware, auth, migrations, payments, packages)
   → YES → FULL (regardless of file count)

2. All files non-source? (only .md, .css, .test.ts, config)
   → YES → NONE (no agents needed)

3. package.json changed? (NOT exempt - supply chain risk)
   → YES → At least LIGHT

4. File count under 10?
   → YES → LIGHT
   → NO  → FULL

5. Over 200 lines changed?
   → YES → Bump one level up (LIGHT → FULL)

After determining the level, content-based signals select which agents run. .tsx files add a UI consistency reviewer. API routes and custom hooks add a silent-failure-hunter. Auth and migration changes add a security auditor at FULL level.

Agents That Fix vs Agents That Report

Before the review agents see the diff, a simplify pass runs. This is three agents dispatched in parallel - a code reuse checker, a code quality checker, and an efficiency checker. They look for different failure modes.

The reuse agent searches the existing codebase for utilities that could replace newly written code. I wrote a custom formatDate() helper in a component and the reuse agent pointed out that @platform/ui already exports one with identical behavior.

The quality agent catches redundant state, copy-paste with slight variation, and parameter sprawl. It found a component that accepted eight props when four of them could be derived from the other four.

The efficiency agent looks for unnecessary work - redundant computations, duplicate API calls, N+1 patterns, and independent operations that run sequentially when they could be parallel. It caught an action that fetched user data, then fetched the same user data again two functions deep.

The key distinction is that simplify agents fix the code. Review agents report on it. The simplify pass edits files directly, re-stages them, and proceeds. The review agents produce findings and a verdict - pass, warn, or fail - that determines whether the commit goes through. I separated these because the review agents were generating reports that said “you should extract this utility” but never actually doing it. The reports were accurate and completely ignored. Now the fixable stuff gets fixed before review, and the review agents focus on things that require human judgment - architectural decisions, security patterns, spec compliance.

The sequence is deliberate:

Step 2:   Quality gates (type-check, lint)
Step 2.5: Simplify pass (3 parallel agents → fix issues → re-stage)
Step 3:   Review triage (classify as NONE/LIGHT/FULL)
Step 4:   Review dispatch (parallel agents → findings → verdict)
Step 4.1: Synthesis (merge agent findings → single pass/warn/fail)
Step 6:   Stage and commit

Simplify runs before review because it changes the diff. If simplify extracts a utility, the review agents see the cleaner version. If review ran first, its findings would reference code that no longer exists after simplify fixed it.

The synthesis step (4.1) exists because multiple agents can disagree. The code reviewer might say PASS while the silent-failure-hunter says FAIL on a swallowed error. Synthesis produces a single verdict from the combined findings, deduplicates overlapping issues, and applies any review overrides from .claude/review-overrides.json - a file where I can suppress known false positives without editing agent prompts.

The Change Relevance Problem

I was on branch feature/INT-28-waitlist-entries building a waitlist feature. Partway through, I noticed some stale Claude command files and cleaned them up. I ran /commit. Claude staged everything - the waitlist code and the unrelated command file cleanup - and committed it all under the INT-28 ticket.

The Linear ticket now had a progress comment about changes to .claude/commands/ files that had nothing to do with waitlist entries. The git history for the ticket included commits with unrelated cleanup. It wasn’t harmful, but it made the history harder to follow.

Now /commit has a change relevance check at Step 5.75. After extracting the ticket ID from the branch name, it compares the changed files against the ticket’s purpose:

Changes appear related to ticket?
├─ YES → Continue to Step 6
├─ UNCLEAR → Ask user to confirm
└─ NO → Prompt with options

Red flags include .claude/ changes on an app feature ticket, different app directories than the ticket prefix suggests (an AUTM ticket but only medicaremagic/ changes), and config-only changes on an implementation ticket.

When unrelated changes are detected, the prompt gives three options: create a separate branch for the unrelated work, continue on the current branch anyway, or cancel and review what to commit. I almost always pick “create a separate branch” - it takes five seconds and keeps the git history clean.

There’s a complementary check at Step 5.5 - branch/ticket mismatch detection. If the session file says I’m working on AUTM-677 but I’m on branch feature/INT-28-waitlist-entries, that’s almost certainly a mistake. This catches the scenario where I switch worktrees, forget I’m in the wrong one, and try to commit. The mismatch prompt saved me from committing IntensityMagic changes to an AuthorMagic ticket at least three times.

Chain Mode: Multi-Ticket Commits

/start-chain INT-366 INT-367 INT-368 INT-369 kicks off a chain of related tickets. Claude works through them sequentially - implement, test, commit, advance to the next ticket. The /commit command needs to know when it’s inside a chain because the behavior changes in specific ways.

Chain detection happens in Step 0.5. /commit checks for a chain-state.json file and verifies that the current ticket matches the chain’s current index:

chain-state.json exists AND current ticket matches
chain.tickets[chain.currentIndex]?
├─ YES → Set IN_CHAIN = true
│        Display: "Chain mode detected (ticket 2/4)"
└─ NO  → Set IN_CHAIN = false (standard commit)

When IN_CHAIN is true, three things change. The batch learning capture (Step 1.5) is skipped because chain commits happen rapidly and capturing after each one is noisy - learnings get captured at the end of the chain instead. The success output is abbreviated - no “next steps” section, no deploy hints, just the commit SHA and a “returning to chain orchestrator” message. And the chain-state.json is updated with the commit SHA and status for the completed ticket.

Everything else stays identical. Quality gates run. Simplify runs. Review triage runs at the appropriate level. I was tempted to skip reviews for chain commits because they happen in rapid succession and the context pressure builds - but that’s exactly when shortcuts cause problems. A chain of four tickets means four separate feature implementations, and each one deserves the same scrutiny as a standalone commit.

The tricky part is cross-repo chains. If /start-chain was invoked in magic3 but one of the tickets routes to ~/Code/companyos-intensitymagic, the chain-state.json lives in magic3 while the actual work happens in companyos. The per-ticket session file stores a chainInvokingDir field that points back to magic3:

Session file has chainInvokingDir set?
├─ YES → CHAIN_STATE_DIR = chainInvokingDir
│        Check: ls "$CHAIN_STATE_DIR/.claude-session/chain-state.json"
└─ NO  → CHAIN_STATE_DIR = (current directory)
         Check: ls .claude-session/chain-state.json

One important guardrail: /commit updates the per-ticket entry in chain-state.json (status, commitSha, branch) but does not update the summary counts. The chain orchestrator in /start owns the summary tracking and reads the updated ticket status after /commit returns. If both sides incremented summary.completed, the count would be wrong.

One Command, Twelve Repositories

/commit works in every repository I use - Magic Platform, CompanyOS, MagicEA, Freshell, Adventures in Claude, and seven more. Each has different conventions for branching, quality gates, review levels, and deployment. The first version of /commit was written for Magic Platform only. When I tried to use it in CompanyOS, it complained about not being on a feature branch (CompanyOS uses main) and tried to run pnpm run type-check (CompanyOS uses bash scripts/validate.sh).

The fix was the same one /start uses: Workflow Profiles. /commit detects the project from the working directory, reads the profile from that project’s CLAUDE.md, and adapts every step. The detection is a simple prefix match:

Working directory starts with ~/Code/magicea?
  → PROJECT = "magicea"
Working directory starts with ~/Code/content/aic?
  → PROJECT = "adventuresinclaude"
Working directory starts with ~/Code/magic*?
  → PROJECT = "magic-platform"

The profile drives everything downstream. Branch protection: direct_to_main is true for Adventures in Claude, so committing on main is allowed. Quality gates: Magic Platform runs type-check and lint, CompanyOS runs a single validation script, Adventures in Claude runs nothing. Review triage: Magic Platform can go up to FULL with five parallel agents, non-platform projects cap at LIGHT with a single code reviewer. Ship method: Magic Platform pushes and defers PR creation to /staging, MagicEA creates a PR immediately, Adventures in Claude just pushes.

Linear integration adapts too. The status update uses profile.ship.linear_status - “In Progress” for pipeline repos where the commit is a checkpoint, “Done” for direct-to-main repos where the commit is the final step. The progress comment format changes: pipeline repos say “Ready for staging deployment via /staging,” direct-to-main repos say “Committed to main and pushed.”

The final success message is entirely templated from the profile:

[HEADER - choose one:]
  PR created:        Committed and PR created!
  direct_to_main:    Done -- TICKET-XXX committed and marked Done
  all others:        Work committed for TICKET-XXX

[REVIEW - pipeline repos only:]
  NONE:  Review: Skipped (non-source only)
  LIGHT: Review: LIGHT: code-reviewer PASS, ui-consistency-reviewer PASS
  FULL:  Spec Review: PASS (attempt 1/3)

[CORE - all templates:]
  Branch: feature/INT-391-overlay-cleanup
  Commit: abc1234 - feat: add overlay cleanup

[SHIP - choose one:]
  PR created:        PR: https://github.com/...
  direct_to_main:    Pushed: origin/main
  all others:        Pushed: origin/feature/INT-391-overlay-cleanup

[ALL:]
  Linear: Status -> In Progress, comment added

[NEXT STEPS - most specific match wins:]
  pipeline:      - Deploy to staging: run /staging from magic0
  PR repos:      - Review and merge the PR
  all others:    - [deploy_hint from profile]

Adding a new project means writing a Workflow Profile. No changes to /commit itself. The same markdown file runs the same algorithm across twelve repositories, producing twelve different behaviors.

Auto-Labels and Threaded Comments

Two small features in /commit that I use constantly and almost didn’t build.

Auto-labeling detects what area of the codebase changed and applies Linear labels. .tsx and .css files get frontend. API routes and services get backend. Migrations get database. The detection runs on path patterns - simple grep checks against the file list. The labels are then merged with existing labels on the ticket, because Linear’s save_issue replaces labels rather than appending them. That gotcha cost me an afternoon of debugging silent label drops before I figured out the merge-first pattern.

Threaded comments were added because Linear tickets accumulate noise. Every /start posts an implementation plan comment. Every /commit posts a progress update. If I commit three times during a feature, the ticket has four top-level comments (plan plus three updates) and scanning for the actual discussion becomes tedious.

Now /commit checks for an existing “Implementation Plan” comment posted by /start. If it finds one, the progress update is posted as a reply threaded under it. The ticket timeline shows one expandable thread for all the automated activity, keeping top-level comments clean for human discussion.

const planComment = comments.find(
  c => c.body.includes("## Implementation Plan")
);

mcp__linear__save_comment({
  issueId: "<uuid>",
  body: progressUpdate,
  ...(planComment ? { parentId: planComment.id } : {})
});

Both features are profile-gated. Auto-labeling only runs when profile.labels.auto_detect is true. Threading only happens when a plan comment exists. Neither is visible unless you go looking for it - they just make the project management side of development a little less noisy.

The Pattern: Separation of Concerns in Markdown

/start and /commit are two halves of a workflow. /start goes from ticket to implementation - fetch, plan, branch, code. /commit goes from implementation to ship - review, commit, push, update. They share session state through JSON files and share project configuration through Workflow Profiles, but neither knows the other’s internal logic.

This separation came from trying to put everything in one file. A 2,500-line /start that also handled committing was unmanageable - not because Claude couldn’t read it, but because every change to the review pipeline risked breaking the planning logic. Splitting them made each file independently iterable. I’ve rewritten the review triage three times without touching /start at all.

The integration contract is simple. /start creates a session file and a plan file. /commit reads them, updates the session status, and cleans up when done. If /start adds a new field to the session file, /commit ignores it until it has a reason to read it. If /commit adds a new review level, /start doesn’t need to know. They communicate through files with stable schemas - the same approach that makes Unix pipes composable.

The markdown-as-state-machine pattern from yesterday’s post is the same one at work here. Decision trees, not prose. State on disk, not in memory. Step numbers, not transitions. The only difference is what the machine does - /start orchestrates the beginning of work, /commit orchestrates the end of it.

Subscribe via RSS to follow along. The source is always on GitHub .

I type /start INT-391 and walk away for thirty seconds. When I come back, Claude has fetched the ticket from Linear, read the description and all comments, detected that it belongs to the magic-platform monorepo, checked out a fresh feature branch from preview, explored the codebase to understand what needs to change, generated a detailed implementation plan, posted that plan as a comment on the Linear ticket, set the status to “In Progress,” and is now waiting for me to approve the plan before it writes any code.

One command. Fifteen steps. Across any of twelve repositories and twelve parallel worktrees.

The /start command is a markdown file. Not a shell script, not a Python program, not a GitHub Action. It’s 1,400 lines of structured documentation that Claude Code reads and executes. Every design decision in it came from a real failure.

A Markdown File Is a State Machine

The first version of /start was about fifty lines of prose. “Fetch the ticket from Linear. Read the description. Create a branch. Explore the codebase and make a plan.” It worked - sometimes. Claude would forget to create the branch before starting the plan. It would skip posting the plan to Linear. It would start writing code without waiting for approval. The instructions were clear to a human reader, but Claude treated them as suggestions.

The fix was structure. Not more words - more explicit control flow.

Session file exists?
├─ YES → Read session file
│        ├─ Steps 0-7 → Restart from Step 1
│        ├─ Step 8+ → Load Workflow Profile first, then resume
│        └─ status = "awaiting_user_test" → Skip to Step 15
└─ NO  → Fresh start, continue with Step 1

Decision trees with explicit branching replaced prose paragraphs. Step numbers replaced “next, do…” transitions. Checkpoint markers told Claude exactly when to save state. The markdown became less readable to humans and more reliable for Claude.

This is the core insight: a markdown file can be a state machine. Not metaphorically - literally. Each step has a number, preconditions, actions, a decision tree for branching, and a checkpoint that persists state to disk. Claude reads the file, identifies which step it’s on, and follows the branches. The structure does the work that an interpreter would do in a traditional programming language.

Session file exists?
├─ YES → Read session file
│        ├─ Check stored targetDir value
│        │   ├─ If targetDir differs from $PWD:
│        │   │   → Display: "Session found but for different directory"
│        │   │   → Set TARGET_DIR from session's targetDir
│        │   └─ If targetDir matches $PWD:
│        │       → Set TARGET_DIR = $PWD
│        │
│        ├─ Display: "Found existing session at Step N (status: X)"
│        │
│        └─ Jump to appropriate step based on currentStep:
│            ├─ Steps 0-7 → Restart from Step 1 (no side effects yet)
│            ├─ Step 8+ → Always load Workflow Profile first,
│            │             then resume at stored step
│            └─ status = "awaiting_user_test" → Skip to Step 15
│
└─ NO  → Fresh start, continue with Step 1

The key detail: steps 0-7 have no side effects (no branches created, no Linear updates), so they’re safe to restart. Steps 8+ have created branches and modified external state, so they must resume exactly where they left off - but only after loading the Workflow Profile, because later steps reference profile fields like base_branch and quality_gates.

Context Compaction Ate My Progress

Claude Code compresses old messages as conversations grow long. This is called context compaction, and it’s necessary - without it, long coding sessions would hit the context window limit and stop. But compaction means Claude can forget things. Important things. Like which step of a fifteen-step workflow it’s on, what the implementation plan says, and which files have already been modified.

The first time I lost an hour of work to compaction, I added session files.

Every /start invocation creates a JSON file on disk: .claude-session/TICKET-XXX.json. It tracks the ticket ID, the current step, the workflow status, the target directory, and whether the user has been asked to test. When context compacts and Claude loses its in-memory state, it re-reads the session file and picks up where it left off.

But the session file only tracks workflow state. The implementation plan is a separate file - .claude-session/TICKET-XXX-plan.md - with checkbox-style tasks:

## Implementation Tasks
- [x] Add overlay state to landing page store
- [x] Create InlineEditableText component
- [ ] Wire up save action for section headings
- [ ] Add optimistic update with rollback on error

After completing each task, Claude edits the plan file to check the box. When context compacts, Claude re-reads the plan, sees which boxes are checked, and resumes from the first unchecked task. The plan file is the canonical progress tracker - not Claude’s memory.

{
  "schemaVersion": 1,
  "ticket": "INT-391",
  "ticketUUID": "<uuid-from-linear>",
  "title": "Overlay cleanup",
  "branch": "feature/INT-391-overlay-cleanup",
  "project": "magic-platform",
  "targetDir": "/Users/bfeld/Code/magic7",
  "stashCreated": false,
  "createdAt": "2026-03-10T10:00:00Z",
  "updatedAt": "2026-03-10T10:15:00Z",
  "sessionRules": [],
  "ticketContext": {
    "description": "...",
    "comments": [],
    "isReopened": false,
    "feedbackToAddress": [],
    "previousImplementation": null
  },
  "workflow": {
    "currentStep": 13,
    "status": "implementing",
    "blockedActions": [],
    "nextAction": "Continue implementation"
  },
  "plan": {
    "file": "/Users/bfeld/Code/magic7/.claude-session/INT-391-plan.md",
    "postedToLinear": true
  },
  "progress": {
    "filesModified": ["src/app/admin/landing/page.tsx"],
    "testsStatus": {}
  }
}

Every field exists because something went wrong without it. targetDir was added after cross-repo sessions lost track of which directory to work in. stashCreated was added after users forgot they’d stashed uncommitted changes before starting a ticket. ticketContext.isReopened was added after Claude kept ignoring feedback comments on reopened tickets.

I Kept Starting Tickets in the Wrong Repo

I have twelve repositories. Magic Platform is a monorepo with seven apps. CompanyOS is a standalone repo for business operations. Adventures in Claude is a Hugo blog. MagicEA, Freshell, Overwatch, txvotes, Techstars OS - each lives in its own directory with its own conventions.

The problem: I’d type /start COS-87 from a Magic Platform worktree and Claude would try to create a feature branch in the wrong repository, explore the wrong codebase, and generate a plan for code that didn’t exist there.

The solution is the Team Registry - a YAML block at the top of the /start file that maps every ticket prefix to its repository:

- prefix: [AUTM, MED, MYH, NEW, PLA, INT, CURE]
  project_type: magic-platform
  directory: (current worktree)
  description: "Magic Platform monorepo apps"

- prefix: COS
  project_type: companyos
  directory: ~/Code/companyos-intensitymagic
  description: "Company operations"

- prefix: AIC
  project_type: adventuresinclaude
  directory: ~/Code/content/aic
  description: "Adventures in Claude blog"

When I type /start COS-87 from a Magic Platform worktree, the algorithm looks up COS in the registry, finds it maps to companyos, sees that doesn’t match the current project type, and switches. All subsequent commands use git -C "$TARGET_DIR" and absolute paths - because Claude can’t persist a cd between tool calls. Each Bash invocation starts in the original directory, so the workaround is to never rely on the working directory at all.

The interesting edge case is BAF - Brad’s Todos. It’s a heterogeneous team in Linear where tickets can route to different repositories depending on what they are. A BAF ticket might be a blog post for feld.com, a feature for CompanyOS, or content for Adventures in Claude. There’s no single correct repository, so /start asks:

- prefix: BAF
  project_type: (heterogeneous)
  routing: ask_user
  routing_options:
   - label: "feld.com blog"
      target_dir: ~/Code/content/feld
   - label: "Adventures in Claude"
      target_dir: ~/Code/content/aic
   - label: "CompanyOS"
      target_dir: ~/Code/companyos-intensitymagic

1. Look up the ticket's team prefix in the Team Registry
2. No matching entry? → Stay in current directory (unknown team)
3. Entry has routing: ask_user? → Show options, let user pick
4. Entry's project_type matches current? → Stay (already correct)
5. MISMATCH → Set TARGET_DIR from registry entry
   └─ Display: "Ticket COS-87 belongs to team CompanyOS"
      "Target: ~/Code/companyos-intensitymagic"
      "All operations will use absolute paths in the target directory."

After switching, /start runs a post-switch pre-flight: check for uncommitted changes in the target repo, offer to stash them, and verify the repo is in a clean state before proceeding.

The Ticket Said One Thing, Reality Said Another

A ticket gets worked on, shipped, and then comes back. I found a bug, an edge case was missed, or the behavior isn’t quite right. The ticket gets reopened with feedback in the comments.

Early versions of /start would just read the ticket description and start fresh. The description says “add overlay editing to the landing page.” Claude reads that, explores the codebase, and generates a plan for adding overlay editing - ignoring the three comments that say “the overlay doesn’t close when you click outside it” and “save action fires twice on double-click.”

Now /start scans comments for feedback signals:

A ticket is "reopened" if ANY of these are true:
1. Status is "In Progress" AND comments contain implementation content
2. Comments contain keywords: "sent back", "bug", "fix needed",
   "doesn't work", "regression", "not working"
3. A "Progress Update" comment exists followed by feedback comments

When a reopened ticket is detected, /start extracts the specific issues and passes them to the Plan subagent as structured input - not just “here’s a ticket” but “here’s what was built before and here’s what’s wrong with it.”

The Plan subagent itself is a design choice. It runs on Sonnet (nearly identical SWE-bench scores to Opus at a fraction of the cost) in a separate context window. The subagent explores the codebase - grepping for patterns, reading files, tracing code paths - and all that verbose search output stays in the subagent’s context, not the main conversation. The main conversation gets back a clean, structured plan. This matters because codebase exploration can easily consume half the context window, leaving less room for the actual implementation.

The Plan subagent receives a structured prompt with the full ticket context:

## Previous Work & Feedback
This ticket was previously worked on and sent back.

### Issues to Address
- Bug: overlay doesn't close on outside click
- Issue: save action fires twice on double-click

### Previous Implementation
Added overlay editing with InlineEditableText component,
section heading save action, and optimistic updates.

Focus your implementation on addressing the feedback above.

This ensures the Plan subagent searches for the right files - not just the feature files, but the specific code paths that caused issues. Without this context, the subagent would generate a plan for the original ticket, not the reopened one.

Every Project Is Different

Magic Platform uses preview as its base branch, requires user testing before commits, runs type-check, lint, and unit tests as quality gates, and ships via pull request. CompanyOS commits via PR to main with a single validation script and no manual testing. Adventures in Claude auto-deploys on push to main with no quality gates at all.

Hardcoding these differences would mean maintaining separate /start commands - or a single command full of if (project === "magic-platform") branches. Instead, each project declares a Workflow Profile in its CLAUDE.md:

# Magic Platform
workflow:
  base_branch: preview
  direct_to_main: false
  quality_gates:
   - pnpm run type-check
   - pnpm run lint
  user_testing: required
  ship:
    method: pr
    target: preview
    deploy_hint: "/staging"

# CompanyOS
workflow:
  base_branch: main
  direct_to_main: false
  quality_gates: ["bash scripts/validate.sh"]
  user_testing: skip
  ship:
    method: pr
    target: main
    deploy_hint: "PR created - review and merge on GitHub"

/start reads the Workflow Profile at runtime (Step 7.1) and stores the parsed fields. Every subsequent step references the profile instead of hardcoded values: git checkout -b feature/TICKET origin/[profile.base_branch], run profile.quality_gates in sequence, set Linear status to profile.ship.linear_status on commit. The command is generic. The profile makes it specific.

Adding a new project means adding one entry to the Team Registry and writing a Workflow Profile in the project’s CLAUDE.md. No changes to /start itself.

Superpowers: The Methodology Plugin

/start doesn’t try to be a complete development methodology. It manages the lifecycle - ticket to deployment. The methodology comes from somewhere else.

Jesse Vincent built superpowers , an open-source plugin that gives coding agents a complete development workflow. The core idea is that your agent shouldn’t just jump into writing code - it should brainstorm the design with you first, get your sign-off, write a plan detailed enough for an enthusiastic junior engineer to follow, then execute it with subagents while you watch. Jesse has been iterating on this relentlessly, and the result is one of the most thoughtful pieces of AI tooling I’ve seen - not because it’s flashy, but because it encodes hard-won lessons about where agents go wrong and how to keep them on track.

Superpowers installs as a single line in settings:

{ "superpowers@superpowers-marketplace": true }

It auto-updates via the plugin marketplace and provides skills for debugging, verification, brainstorming, plan writing, code review, and TDD. The integration points with /start are specific and deliberate:

Planning (Step 8): The Plan subagent follows superpowers’ plan-writing patterns - required sections (Key Decisions, Rejected Approaches, Edge Cases, Codebase Patterns), task granularity rules (each task is one atomic action), and the principle that a plan must be approved before implementation begins.

Approval (Step 9): The “present the full plan, get explicit approval, re-present after any revision” loop mirrors superpowers’ brainstorming skill, which requires presenting designs and getting sign-off before touching code.

Verification (Step 14.5): This step invokes superpowers’ verification-before-completion skill. It exists because of a specific failure mode: context compaction would cause Claude to skip quality gates - especially unit tests - and claim “done” without evidence. The verification skill forces a final check: did all quality gates actually run? Are all plan tasks checked off? It won’t let Claude proceed until there’s evidence, not just assertions.

The circuit breaker (Step 15): After implementation, /start sets the session status to awaiting_user_test and blocks git commit. Even if context compacts and Claude forgets the original instructions, the session file on disk enforces the gate. This is the same principle from the CompanyOS post - irreversible actions need explicit approval. Claude can implement, test, and prepare all day long. But the moment a commit needs to leave the working directory, a human says yes.

{
  "workflow": {
    "status": "awaiting_user_test",
    "blockedActions": ["git commit", "git push"],
    "nextAction": "User tests manually, then runs /commit"
  }
}

The relationship between /start and superpowers is like a project manager and a methodology framework. /start knows the sequence: fetch ticket, plan, branch, implement, test, hand off. Superpowers knows the standards: how plans should be structured, when verification is required, what counts as evidence. Neither embeds the other’s logic. They compose through well-defined integration points - skill invocations and pattern conventions.

Markdown as a Programming Language for AI Behavior

There’s no interpreter executing this markdown. No runtime, no compiler, no AST. Claude reads the file, identifies which step it’s on from the session state, and follows the decision trees. The “execution engine” is Claude’s ability to read structured documentation and act on it.

This works because of specific structural choices:

Decision trees, not prose. “If the session file exists and the current step is 8 or higher, load the Workflow Profile first, then resume at the stored step” is unambiguous. “Resume where you left off” is not.

State on disk, not in memory. Everything that matters - the current step, the plan, task completion status, the target directory - is persisted to files. Claude’s memory is unreliable across long sessions. The filesystem is not.

Step numbers, not transitions. “Step 14.5: Verification Gate” is a fixed location in the workflow. “After testing, verify everything” is a suggestion that can be skipped or reinterpreted.

Integration points, not monolithic logic. /start invokes superpowers skills at specific steps. It reads Workflow Profiles from project CLAUDE.md files. It delegates codebase exploration to a Plan subagent. Each piece does one thing and communicates through structured interfaces - files, JSON schemas, skill invocations.

The broader pattern is this: if you want an AI to do something complex and do it reliably, the answer isn’t better prose instructions. It’s more structured ones. Decision trees instead of paragraphs. Checkpoints instead of assumptions. State machines encoded in markdown - because that’s the format your AI agent already knows how to read.

Subscribe via RSS to follow along. The source is always on GitHub .