Skip to main content

Guided Coding: 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. Two more skills let you implement a plan yourself while the agent teaches you - see Guided Learning: Getting Started.

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 frozen, timestamped plan 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​

Install the skills with the GitHub CLI. The --agent flag decides where they land. Claude Code reads skills only from its own .claude/skills directory, while all other major agents share the .agents/skills directory:

# Claude Code
gh skill install feO2x/guided-coding --all --agent claude-code --scope project

# Any other agent
gh skill install feO2x/guided-coding --all --agent universal --scope project

Add --scope user to make them available across all your repositories, or name a single skill instead of --all. Installed this way, the skills keep their full names:

/guided-coding-setup

To update, check for changes first and then update all skills. The GitHub CLI finds the installed skills in both directories on its own:

gh skill update --dry-run
gh skill update --all

The skills follow the Agent Skills specification, so any agent that implements it can use them. GitHub CLI's skill commands are currently in preview.

The repository is also a package for the Agent Plugins standard. Clients that support the standard can install it directly; the installation and marketplace commands are client-specific. These clients use the skills' full names, so pick the Agent Skills tab.

Every skill invocation further down this page offers the same two 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, freeze one, or record deviations. 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-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. Create a ticket if the work needs one, then guided-coding-freeze-plan timestamps and freezes the plan, and you commit it. In the Implementing Phase, run guided-coding-implement with the frozen plan in a fresh conversation. 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-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-freeze-planCreate any ticket first. Commit the frozen plan afterwards.2. IMPLEMENTING PHASEguided-coding-implementIn a fresh conversation. 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 ensures two sections in the root AGENTS.md: the confirmed feedback-loop commands with what each one verifies, and the rules for implementing a frozen plan together with a link to ai-plans/AGENTS.md. It also creates ai-plans/ with its own AGENTS.md. Running it again after an upgrade brings outdated sections up to date and leaves everything else untouched, including your own rules and existing plans.

It does not invent commands. It lists only commands that are immediately executable in the repository, and it tells you when it could not find any feedback loops at all. Take that warning seriously: guided-coding-write-plan refuses to write a plan until at least one feedback loop is listed.

The defaults are a starting point, and the skill ends with the same customization tips you see here:

  • Plan structure. guided-coding-write-plan uses Rationale, Acceptance Criteria, and Technical Details by default. Describe a different structure in ai-plans/AGENTS.md to override it.
  • Filenames. The skills build names from <timestamp> (UTC, YYYY-MM-DD-HHMM), <ticket-id>, and <short-title>. Conventions such as a ticket ID format or a maximum length for the short title belong in ai-plans/AGENTS.md.
  • Feedback loops. Plans reference the feedback loops in the root AGENTS.md to make acceptance criteria verifiable. Adding or removing one later only means updating that list.
  • Deviations. The threshold for what counts as a material deviation can be tightened or relaxed in ai-plans/AGENTS.md.

Repository-specific conventions in your AGENTS.md files take precedence over the skills' defaults.

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: Write the plan​

Still in the same conversation:

/guided-coding-write-plan

The skill writes the approach you already agreed on into ai-plans/<short-title>.md, using the three-section structure. The plain short title is deliberate: it identifies a mutable draft on the file level. The timestamp is added only when the plan freezes in step 6. The skill 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 would write a fresh draft instead of revising the one you are working on. 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 3: 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 6. Expect several rounds here.

Step 4: 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 5: 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 3.

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

Step 6: Freeze the plan​

If the work should have a tracker issue, create it now, before you freeze. The skill asks for the ticket ID and puts it into the filename, and the stable draft makes a good issue description. Skip this when the work has no ticket; the filename then simply omits the ID.

Then freeze the plan:

/guided-coding-freeze-plan

The skill takes the current UTC timestamp from the shell, renames the draft to <timestamp>-<ticket-id>-<short-title>.md (or without the ticket ID when there is none), and inserts a *Frozen at ...* line below the title. It refuses to overwrite an existing file.

The freeze 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.

Now commit the frozen plan. The skill does not do that for you, so commit it yourself or use a normal prompt, and keep the plan file alone in that commit so the record stays readable.

Step 7: Implement​

Start a fresh conversation and hand over the committed plan:

/guided-coding-implement ai-plans/2026-08-13-1420-42-cancelled-events.md

When you don't name a plan, the skill picks the latest one with all acceptance criteria unchecked, and asks otherwise. It refuses to start on a plan that isn't frozen. Then it implements the plan, verifies the changes with your feedback loops, and ticks an acceptance criterion only when a feedback loop genuinely satisfies it. When a plan decision turns out to be wrong, it looks for a workaround and reports it instead of silently building something else. At the end, it reports what it implemented, which feedback loops ran, and which criteria remain unchecked and why. It does not commit anything or open a pull request unless you ask it to.

The skill adds little to a plain prompt, and that is on purpose. A prompt works just as well:

"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 8: 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 6 again, producing a follow-up plan with the same ticket ID.

The Guiding Phase page covers what to look for.

Step 9: 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.