mach10

Mach 10

A development methodology for agentic coding -- and a Claude Code plugin that implements it.

What is Mach 10?

In agentic coding, the AI is not an autocomplete engine -- it is an active collaborator that writes code, reviews it, manages GitHub issues and PRs, runs tests, and documents its work. The human's role shifts from writing code to directing, aligning, and reviewing. You describe requirements, approve architectural decisions, and steer direction. The AI handles the searching, writing, testing, and bookkeeping.

This changes the failure mode. The bottleneck is no longer typing speed or syntax recall -- it is context management. LLM context windows are finite. A deep code review can consume most of the available context, leaving little room for implementation. Multi-session feature development requires persistent memory across sessions. And without a structured workflow, agentic coding produces inconsistent results: missed edge cases, orphaned TODOs, reviews that never converge.

Mach 10 is a methodology that addresses these constraints directly: fresh sessions for each step, GitHub as persistent memory, staged implementation, and iterative review-fix cycles. This repository contains a Claude Code plugin that codifies the methodology into 14 slash commands, but the methodology stands on its own -- you can follow it manually with any agentic coding tool.

Because the methodology builds entirely on standard developer practices -- issues, PRs, comments, feature branches, frequent commits -- there is no vendor lock-in. Every artifact Mach 10 produces is a normal GitHub artifact. If you stop using the plugin, you're left with well-documented issues, structured PRs, and a clean commit history. Nothing is stored in a proprietary format or locked behind a tool-specific layer.

The methodology

Your role as the human

You are directing, not spectating. The AI handles the mechanical work -- searching, writing, testing, documenting -- but you own the decisions:

• Push back on designs. When the AI presents a plan, you don't have to accept it. Ask why it chose a particular approach. Ask it to present alternatives. If the architecture doesn't feel right, say so -- before implementation is the cheapest place to catch mistakes.
• Don't guess when the AI asks questions. When it presents clarifying questions with options, ask it to explain the tradeoffs of each option rather than picking one blindly. You have a collaborator that can reason about the implications -- use it.
• Review plans, not just code. Plans can be reviewed by AI agents just like code can. Catching a design flaw before implementation saves far more effort than catching it in code review.
• GitHub is the shared medium. Plans, assessments, and reviews are posted as GitHub comments. Any future session -- yours or a teammate's -- can read and build on prior work. The persistence layer is GitHub, not your local machine.

GitHub as shared memory

Each CLI session starts with a fresh context window. Multi-session feature development requires persistent memory. Rather than maintaining bespoke planning documents on disk, the methodology uses GitHub's existing infrastructure -- issues, PRs, and comments -- as the inter-session communication layer:

• Issues capture requirements, analysis, and staged implementation plans.
• PR descriptions summarize what was built.
• PR comments carry reviews, fix documentation, and design discussions.

Everything persists across sessions and is accessible via gh. When a new session starts, it reads the relevant issue or PR and has full context without any filesystem state or memory.

Fresh sessions for every step

LLM context windows are finite. A deep code review can consume most of the available context, leaving little room for implementation. If you try to review and fix in the same session, the fixes suffer from a starved context budget.

The methodology is designed around this constraint:

• Planning explores the codebase and persists its plan as a GitHub comment before the context fills up.
• Review posts its findings as a PR comment and does not fix anything.
• Fixing starts fresh with the full context budget available for implementation.
• Implementation runs one stage per session so each stage gets full context depth.

Staged implementation

Large features are broken into numbered stages during the planning step. Each stage is implemented in its own session. This significantly improves one-shot success rates compared to attempting an entire feature in a single session -- each stage gets full context depth for codebase exploration, architecture design, implementation, and quality review.

Iterative review-fix cycles

Code review is not a single pass. The methodology uses an iterative cycle:

1. Review + Assess -- Run specialized review agents in parallel (code quality, test coverage, error handling, type design, comment accuracy, complexity). Post findings as a PR comment. Then independently assess each finding, classifying it as genuine, nitpick, false positive, or deferred. The assessment is the convergence signal.
2. Fix -- In a new session, read the review comment and fix the genuine issues. Batch size depends on complexity: ~10 simple fixes, ~6 moderate, ~3 complex.
3. Re-review -- Run the review suite again. Each review includes a fresh assessment.

This continues until the assessment shows no genuine issues remaining.

The workflow

The methodology in action across a feature's lifecycle. Each step below runs in a fresh CLI session. GitHub comments carry context between sessions -- no filesystem state or memory is required. This also means other team members' sessions can pick up where yours left off by reading the same issue or PR.

                     ┌───────────┐
                     │  Create   │
                     │   Issue   │
                     └─────┬─────┘
                           │
                         Issue
                           │
                     ┌─────▼─────┐
                     │  Assess   │
                     └─────┬─────┘
                           │
                     ┌─────▼─────┐
                     │   Plan    │
                     └─────┬─────┘
                           │
                     ┌─────▼─────┐
                     │  Review   │
                     │   Plan    │
                     └─────┬─────┘
                           │
            ┌──────────────┴──────────────┐
            │      for each stage:        │
            │                             │
            │   ┌─────────────────────┐   │
            │   │  Implement → Push   │───┤
            │   └─────────────────────┘   │
            └──────────────┬──────────────┘
                           │
                     ┌─────▼─────┐
                     │  Create   │
                     │    PR     │
                     └─────┬─────┘
                           │
            ┌──────────────┴──────────────┐
            │   until no genuine issues:  │
            │                             │
            │   ┌─────────────────────┐   │
            │   │ Review → Fix → Push │───┤
            │   └─────────────────────┘   │
            └──────────────┬──────────────┘
                           │
                     ┌─────▼─────┐
                     │Doc Review │
                     └─────┬─────┘
                           │
                     ┌─────▼─────┐
                     │ Pre-merge │
                     └─────┬─────┘
                           │
                     ┌─────▼─────┐
                     │   Merge   │
                     └───────────┘

Phase 0: Create the issue

Command: /mach10:issue-create [context]

When no issue exists yet, start here. Claude helps you draft a structured GitHub issue from a description of the problem or feature you have in mind. The command walks you through title, body, and labels, then creates the issue. If you already have an issue, skip directly to Phase 1.

Your role: Provide the context -- what needs to be built or fixed and why. Review the drafted issue before it's created to make sure scope and requirements are right.

Phase 1: Understand the issue

Command: /mach10:issue-assessment <number> [context]

Claude reads the issue, explores the relevant parts of the codebase, and presents its findings -- scope, risks, ambiguities, critical evaluation, and a recommended next step.

Your role: Read the assessment critically. Push back if the scope is wrong, if risks are missed, if important ambiguities aren't surfaced, or if the critical evaluation raises legitimate concerns about the issue's premise. The assessment is posted as a GitHub comment, so it becomes shared context for every future session on this issue.

Phase 2: Plan the implementation

Command: /mach10:issue-plan <number> [context]

Claude explores the codebase, asks clarifying questions about underspecified requirements, then presents multiple architecture approaches (minimal changes, clean architecture, pragmatic balance) for you to choose from before drafting a staged implementation plan. The plan is posted as a GitHub comment, and a feature branch is created. If the project has a CONTRIBUTING.md (or DEVELOPMENT.md / .github/CONTRIBUTING.md), the plan incorporates its guidance on project layers and testing expectations (see Customizing with CONTRIBUTING.md below).

The plan is staged because each stage will get its own session with a full context budget. Trying to implement everything at once starves later work of context depth. The plan is posted to GitHub so that any future session -- yours or a teammate's -- can read it and pick up the work.

Your role: This is the most important moment to invest your attention. The command will present clarifying questions and architecture alternatives automatically -- answer the questions thoughtfully rather than deferring, and evaluate the architecture options carefully before choosing. Before approving the final plan:

• Scrutinize the selected architecture. Ask Claude to explain trade-offs if the choice isn't clear.
• Push back on anything that doesn't feel right. This is the cheapest point to catch bad design decisions -- before any code is written.

Phase 3: Review the plan

Command: /mach10:issue-plan-review <number> [context]

A fresh Claude session independently reviews the plan against the codebase. If the project has contributing guidelines, the review checks the plan against their requirements for layer coverage and testing. Plans can be reviewed just like code -- this is a second pair of eyes on the architecture before implementation begins.

Your role: Read both the plan and the review. If the review raises valid concerns, direct Claude to revise the plan. You can iterate on plan-review cycles until the design is solid.

Phase 4: Implement stage by stage

Commands: /mach10:issue-implement <issue> <stage> [context] then /mach10:push [context] (one session per stage)

Each stage is implemented in its own fresh session, then committed and pushed with a progress comment on the issue. One stage per session means full context budget for codebase exploration, implementation, and testing.

Your role: Review each stage's output before moving to the next. If something deviates from the plan or introduces problems, raise it now rather than letting it compound.

Phase 5: Create a PR

Command: /mach10:pr-create [issue] [context]

Create a PR linking back to the issue with a structured description summarizing what was built.

Phase 6: Review-fix cycle