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.

Skills

Skill Purpose
guided-coding-setup Set up or upgrade Guided Coding in a repository.
guided-coding-prepare-issue-for-plan Create a tracker issue and clean local branch for planning.
guided-coding-write-plan After discussing an issue with your agent, write a plan or follow-up plan.
guided-coding-review-plan Review a plan draft against the repository (use in fresh conversation).
guided-coding-finish-plan Validate, commit, and freeze a plan.
guided-coding-write-deviations Summarize follow-up plans and record material implementation differences.

All workflows require explicit user invocation.

Install

Agent Skills

Install all skills into the shared project-level .agents/skills directory with 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. GitHub CLI's skill commands are currently in preview.

Claude Code marketplace

Add this repository 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.

Agent Plugin clients

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

Development

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

Keep plugin.json, claude-plugin/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, and the release tag on the same Semantic Version.