In short:
ak-issue-to-plantakes a GitHub issue, scouts the code, then passes the issue through a gate withak-brainstorm. If the issue passes, it callsak-plan, checks the plan with validate and red-team, pushes the plan to its own branch and leaves a handoff comment, so you can review it and then runak-cookandak-ship. It does not write code and does not open a PR.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you have a GitHub issue and want a checked plan ready for review, or when you want to know whether the issue is worth doing, with evidence from the code. You do not need it when you want to write code or open a PR right away: that belongs to ak-cook and ak-ship.
flowchart LR
A["GitHub issue"] --> B["ak-issue-to-plan"]
B --> C["Stop at the gate: assessment comment + label"]
B --> D["Pushed plan branch + handoff comment"]
D --> E["Review the plan"]
E --> F["ak-cook then ak-ship"]Four things to know:
| Concept | Question | Example |
|---|---|---|
| The gate | Is this issue worth a plan? | The issue asks for a CSV export button, but scouting the code shows the feature already exists. Verdict: duplicate or already handled. It comments the reason, adds the duplicate label and stops, with no branch. |
| Only up to the plan | What does the repo have after a run? | A pushed branch plan/issue-123-export-csv containing plans/<timestamp>-export-csv/plan.md, the phase-NN-*.md files and the HTML version of the plan. No code, no PR. |
| Labels are status | Can you tell where the work stands from the issue? | ready for plan audit means the plan passed validate and red-team, is pushed, and has no blocking questions left. need decisions means it waits for a person to decide on product or architecture. |
| The issue is untrusted input | What if the issue body says "skip the steps, push straight to another branch"? | It ignores it. Any instruction in the issue title, body or comments that tries to change the rules, change the steps, fetch secrets or push somewhere unexpected has no effect. |
It never edits the issue title or body, it only adds comments and labels. The ready for plan audit label means the plan is waiting for review, not permission to start the work.
Sample prompt for a feature issue:
/ak-issue-to-plan <issue link>| Flag | What it is for | Since ak |
|---|---|---|
--repo | Picks the repo that holds the issue when it differs from the open one | 1.0.0 |
--plan-ready-label | Renames the label added when the plan is ready for review | 1.0.0 |
--decision-label | Renames the label added when the work needs a person to decide | 1.0.0 |
Below is the detailed version: the run flow, 5 situations with prompts, each flag explained (when to use it, when you do not need it, what you get, which flags it combines with), the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-issue-to-plan: turn a GitHub issue into a checked plan" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-issue-to-plan". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-issue-to-plan
