Guided Coding

Guided Coding is a lightweight approach to working with Coding Agents. Version 2 treats ai-plans/ as an append-only decision record: plans become immutable when their Planning Phase ends, acceptance criteria record verified progress, and material implementation changes are captured in Plan Deviations documents.

The repository is both an Agent Plugin and a Claude Code plugin. Its skills follow the Agent Skills specification and can also be installed independently into .agents/skills.

The full method is documented at kenny-codes.net/docs/guided-coding.

In most Agent Harnesses, these workflows must be invoked explicitly. All workflows set allow_implicit_invocation: false for Agent Plugins and disable-model-invocation: true for Claude Plugins, respectively.

Guided Learning is a variation of Guided Coding where the agent does not implement the plan itself but teaches you how to implement it. The guided-coding-implement-show-me and guided-coding-implement-coach-me skills give you two approaches for Beginning and Advanced developers that want to increase their capabilities. The regular guided-coding-implement skill should be used for regular Guided Coding.

Both skills track your progress in ~/.guided-learning/profile.md: this file contains your preferences for how to be taught and a tree of knowledge areas, each at one of the three stages. On first use, the agent creates this folder as a local git repository (requires Git 2.28 or later) and commits every update locally with a message stating what it observed. This repo is never pushed by default, but you could share it across different machines. We recommend pushing to a private repository. The profile never ends up in your project repository, and you can edit or delete it at any time.

Many of the following commands use gh which refers to the GitHub CLI.

All major harnesses except Claude Code support Agent Skills. Install all skills into the shared project-level .agents/skills directory with the GitHub CLI:

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

Install one skill by naming it or add --scope user to make the installation available across repositories.

If you want to update, use the following command:

gh skill update --dir .agents/skills --dry-run # checks for changes
gh skill update --dir .agents/skills --all # updates all local skills

You can use gh to install the skills, too:

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

Install one skill by naming it or add --scope user to make the installation available across repositories.

Alternatively, you can add Guided Coding as a marketplace and install the plugin:

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

Claude namespaces plugin skills with the plugin name. For example, invoke the setup workflow as /guided-coding:setup. The other skill names similarly omit the redundant guided-coding- prefix used by the portable Agent Skills.

If you want to update, use the following commands:

claude plugin marketplace update guided-coding
claude plugin update guided-coding@guided-coding --scope project

⚠️ Restart Claude Code afterwards. Only then will the updated skills be picked up.

Clients supporting the Agent Plugins standard can install this repository as a plugin package. Installation and marketplace commands are client-specific.

Run the .NET 10 xUnit v3 validation suite with Microsoft.Testing.Platform v2:

dotnet test

Generate the Claude Code adapter from the canonical portable skills, or verify that the committed adapter is current:

dotnet run --project tools/GuidedCoding.ClaudeGenerator
dotnet run --project tools/GuidedCoding.ClaudeGenerator -- --check

Configure Claude-specific skill names and frontmatter in tools/GuidedCoding.ClaudeGenerator/claude-skills.json. Do not edit claude-plugin/claude-skills directly.

When the corresponding tools are installed, also run:

claude plugin validate . --strict
gh skill publish --dry-run

Releases are made from a main branch that matches origin/main, so the release pushes nothing but its own commit. Describe the changes under ## [Unreleased] in CHANGELOG.md first, then run:

dotnet run --project tools/GuidedCoding.Release -- --dry-run          # show the proposed version
dotnet run --project tools/GuidedCoding.Release                       # release the proposed version
dotnet run --project tools/GuidedCoding.Release -- --version 3.0.0    # release a specific version

The tool derives the next version from the Conventional Commits since the last MAJOR.MINOR.PATCH tag: breaking changes release a major version, feat a minor version, and fix or perf a patch version. After you confirm, it updates plugin.json, claude-plugin/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, and CHANGELOG.md, runs the validations, commits, tags, pushes main together with the tag, and publishes the Agent Skills with gh skill publish. Pushing the new version to main releases the Claude Code plugin. The first release needs --version because there is no release tag to start from. Pass --yes to skip the confirmation.

Every tag in the repository must be a plain MAJOR.MINOR.PATCH version, and the tool refuses to release while any other tag exists. If you ever publish by hand, pass --tag MAJOR.MINOR.PATCH to gh skill publish, because its interactive prompt suggests v-prefixed tags.

The repository must carry the agent-skills topic for gh skill publish. It is already set; the tool does not set it because GitHub's workflow token lacks the required admin permission.

Maintainers with write access can also release from the Actions tab by running the Release workflow on main. It runs the same tool with --yes. Leave Version empty to use the proposed version. Dry run is enabled by default, so a first run only shows the proposal; run the workflow again with Dry run unchecked to release.