Skip to main content

Getting Started

This page walks through the Opinionated Path — my own setup, packaged as six Agent Skills that live at github.com/feO2x/guided-coding.

Read this first

The skills are optional. Guided Coding is a methodology, and everything below can be done by hand with markdown files and git. What the skills give you is consistency: the same plan structure, the same filenames, and a commit at exactly the moment the Planning Phase ends.

They are also opinionated. They assume the three-section plan structure (Rationale, Acceptance Criteria, Technical Details) and the append-only plan record. If you want a different structure, don't fight the skills — write your own instructions instead, and read the phase pages for the reasoning behind each rule.

Above all: no skill reviews code for you. The Guiding Phase is still yours.

Install​

Add the repository as a marketplace and install the plugin:

/plugin marketplace add feO2x/guided-coding
/plugin install guided-coding@guided-coding

Claude Code namespaces plugin skills, so you invoke them with the plugin prefix and a short name:

/guided-coding:setup

Every skill invocation further down this page offers the same three tabs, and they all follow the choice you make here. Pick your install method once and the walkthrough spells each skill the way your agent expects it.

All skills are manually invoked

Every skill declares that it runs only when you explicitly ask for it. Your agent will not decide on its own to write a plan, commit one, or create an issue. Guided Coding depends on you choosing the moment each phase ends, and that choice is not delegated.

When to Call What​

Timeline of the Guided Coding skills. Run guided-coding-setup once per repository. The Planning Phase starts with a discussion of the approach. Once you agree on the direction, run guided-coding-prepare-issue-for-plan, then guided-coding-write-plan once to produce the draft. Discuss the draft further and prompt the agent to revise it directly, optionally run guided-coding-review-plan in a fresh conversation, and discuss again. Discussion, review, and revision repeat until the plan stabilizes, after which guided-coding-finish-plan commits and freezes it. In the Implementing Phase, hand the frozen plan to a fresh conversation without any skill. In the Guiding Phase, review every changed file, then run guided-coding-write-deviations whenever follow-up plans exist or the code materially departs from the plans. Two arrows lead back from the Guiding Phase: a small issue returns to the Implementing Phase, and a large issue returns to the start of the Planning Phase. Finally, review the record and use a normal prompt to commit it and create the pull request.ONCE PER REPOSITORYguided-coding-setupWrites AGENTS.md and ai-plans/, records feedback loops.repeat untilit stabilizes1. PLANNING PHASEDiscuss the approach"As an expert architect, how would you tackle this?"guided-coding-prepare-issue-for-planAfter you agree: empty issue, clean local branch.guided-coding-write-planWrites the draft. Invoked once per plan.Further discussionQuestion the draft; revise it with plain prompts.guided-coding-review-planOptional second opinion, in a fresh conversation.Further discussion"Would you change anything about the plan?"guided-coding-finish-planCommits and freezes the plan; offers to publish it to the issue.2. IMPLEMENTING PHASEHand over the plan in a fresh conversationNo skill. The frozen plan and feedback loops steer it.3. GUIDING PHASEReview every changed fileRead it yourself; optionally add an agent review.IterateSmall issue: to Implementing. Large: to Planning.guided-coding-write-deviationsAlways for follow-ups; otherwise for material departures.Review the record and open the PRCommit and publish with a normal prompt after approval.small issuelarge issue

Filled dots are skills. Hollow dots are the parts you do yourself — which, not coincidentally, are the parts that matter most.

The two arrows on the right are the same iteration loops as in the phase diagram. A small issue sends you back into the Implementing Phase with a targeted prompt. A large one sends you back to the top of the Planning Phase — not to guided-coding-write-plan, but to the discussion, because a follow-up plan deserves the same conversation the first one got.

Notice how much of the Planning Phase is conversation. The skills bracket the discussion; they don't replace it. If your Planning Phase consists of running three skills back to back, you have automated the paperwork and skipped the work.

guided-coding-write-plan runs once per plan. The repetition in the Planning Phase is conversational: you revise the draft by prompting the agent, exactly as you would ask it to change any other file in the repository. The other skills run at the transitions described below.

The Walkthrough​

Step 0: Set up the repository​

Run this once per repository, and again after upgrading to a new Guided Coding version:

/guided-coding:setup

The skill reads your existing instruction files, build manifests, scripts, and CI configuration to discover the feedback loops that already exist. It then writes or updates four small pieces of root guidance: how frozen plans are treated during implementation, the confirmed feedback-loop commands, a link to the plan-writing instructions, and a "this is your space" section for the agent's own notes. It also creates ai-plans/ with its own AGENTS.md.

It does not invent commands. It runs them only when they are safe and reasonably bounded, reports which commands it could not run, and never claims that an unexecuted command passed. It never touches existing plans.

Read the resulting diff before you commit it. This file steers every future conversation, so it is worth the two minutes. See What Belongs in a Rules File for how to decide what earns a place there.

Step 1: Discuss the approach​

The Planning Phase starts with a conversation, not a skill. Start a fresh one, describe the context, and ask for an investigation rather than an implementation:

"With you being an expert .NET architect, can you please investigate the codebase and report back how you would tackle this problem?"

Now discuss. Ask why. Push back. Propose alternatives. Ask what it considered and discarded. Keep going until you understand the suggested approach well enough to defend it to a colleague.

Nothing has been created yet at this point — no issue, no branch, no file. That is on purpose. This conversation may well end with "actually, we shouldn't build this", and an untouched repository is the right outcome when it does.

Don't use your agent's built-in planning mode here. See the Planning Phase for why.

Step 2: Open the issue and the branch​

Once you agree with the agent on the general direction:

/guided-coding:prepare-issue-for-plan

This creates an empty tracker issue — no summary, no placeholder acceptance criteria — and a clean local branch named <issue-id>-<topic>. The issue body stays empty on purpose: it gets filled with the finished plan at the end of the Planning Phase.

The skill stops if your worktree has uncommitted changes, and it updates the default branch before branching off it.

Step 3: Write the plan​

Still in the same conversation:

/guided-coding:write-plan

The skill writes the approach you already agreed on into ai-plans/, using the three-section structure and a UTC-timestamped filename. It is explicitly not meant to start or replace the planning conversation — it records its outcome.

Invoke this once per plan. Everything that follows is ordinary conversation: you ask for changes and the agent edits the draft in place. Re-running the skill is neither needed nor wanted — it resolves a fresh UTC timestamp each time, so you would get a second plan file next to the one you are working on rather than an updated draft. You reach for it again only when starting a genuinely new document, such as a follow-up plan after the Guiding Phase or the initial plan for a new feature.

Step 4: Further discussion​

The draft is a starting point, not a result. Read it properly and go back at it with plain prompts — no skill involved:

  • Does every acceptance criterion describe something you could actually verify?
  • Did anything discussed in step 1 quietly not make it into the plan?
  • Does it reference types, files, or extension points that really exist?
  • Is it prescribing implementation steps a senior engineer wouldn't need?

Prompt the agent to revise the draft as you go, the same way you would ask it to change any other file. The plan is still an ordinary working file at this point — it does not freeze until step 7. Expect several rounds here.

Step 5: Review the plan​

For larger or riskier plans, add a second opinion from a fresh conversation with another agent:

/guided-coding:review-plan

The fresh conversation matters: an agent that just wrote a plan is a poor judge of it. The skill reports findings only and never edits anything. It checks acceptance criteria for verifiability, validates claims about existing types and files, and looks for omissions around error handling, migration, performance, and security.

Step 6: Further discussion​

Take those findings back to the main conversation and work through them. Then ask, repeatedly:

"With you being the expert, would you change anything about the plan?"

This one question has caught more things for me than any review checklist. Ask it until the answer stops producing changes you care about. If it does, loop back to step 4.

Steps 4 through 6 are a cycle, not a checklist. Note what is not in that cycle: guided-coding-write-plan ran once, back in step 3. The loop is discussion, review, and revision by prompt. You are done when you and the agent both stop finding things.

Step 7: Finish the plan​

/guided-coding:finish-plan

This validates the filename and structure, commits the plan with a path-limited commit so nothing else sneaks in, and offers to publish the plan body as the issue description.

The commit ends the Planning Phase. From this moment the plan is frozen: the only edit anyone may make is ticking an acceptance criterion once the implementation actually satisfies it. Corrections happen through follow-up plans, not edits. See The Plan Record.

Only the first plan for an issue becomes the issue description. Follow-up plans are not published there.

Step 8: Implement​

No skill here either. Start a fresh conversation and hand over the committed plan:

"With you being an expert .NET developer, could you please implement plan ai-plans/2026-08-13-1420-42-cancelled-events.md for me?"

Then let it run. The frozen plan and your feedback loops are what keep the agent on track — see the Implementing Phase.

Step 9: Guide​

This is the phase you actually spend most of your time in. Read every changed file, evaluate the design, run the tests yourself, and smoke-test the app. Optionally add a code review from a fresh agent conversation.

Then decide:

  • Small issue → prompt the agent to fix it. Back to the Implementing Phase.
  • Large issue (wrong data structure, misused framework mechanism, design flaw) → back to the Planning Phase. Steps 1 through 7 again, producing a follow-up plan with the same issue ID.

The Guiding Phase page covers what to look for.

Step 10: Write and review the deviations, then open the PR​

Once you are satisfied with the implementation, run:

/guided-coding:write-deviations

The skill reads every plan for the issue, inspects the full implementation delta and commit history, and decides what record is required:

  • If follow-up plans exist, it always writes a Plan Deviations document that summarizes which earlier decisions they superseded and where the implementation ended up.
  • With a single plan, it writes one only when the implementation materially departed from an explicit decision. Routine implementation choices still don't count.
  • With a single plan and no material deviations, it reports that conclusion and writes nothing.

The skill only writes the document and reports its path. It does not commit anything, create a pull request, or publish the contents. Review the draft and revise it with ordinary prompts until you accept it.

After approval, either finish the work yourself or use a normal prompt:

"Please commit the Plan Deviations document, create a pull request, and use the document's contents as the pull request description."

When no document was required, create the pull request normally.

The goal: a reviewer should need to read only the issue's first plan and, when one exists, the Plan Deviations document to understand the whole change. Follow-up plans always cause that final document to be created, so their decisions are not hidden from the reviewer.

A Compressed Cheat Sheet​

MomentSkill
New repository, or after an upgradeguided-coding-setup
Starting a feature or bugfix— talk to the agent first
You agree on the general directionguided-coding-prepare-issue-for-plan
The agreed approach needs writing downguided-coding-write-plan (once per plan)
Draft written, and after every revision— discuss and revise by prompt
The draft wants a second opinionguided-coding-review-plan
Nobody is finding anything anymoreguided-coding-finish-plan
Plan committed and frozen— implement, then review
Implementation reviewedguided-coding-write-deviations
Deviations reviewed, or no document required— commit and open the pull request

This table uses the portable names. On the Claude Code plugin they are /guided-coding:setup, /guided-coding:write-plan, and so on — the prefix becomes a namespace and the rest of the name stays put.

The rows without a skill are not gaps in the tooling. They are where Guided Coding actually happens: the discussion that produces the plan, and the review that decides whether the result is good enough. Everything with a skill next to it is bookkeeping around those two activities.