Guided Coding 2.0.0 Update

.agents/skills/guided-coding-finish-plan/SKILL.md

@@ -0,0 +1,65 @@
+---
+description: Validate and freeze a Guided Coding plan, then optionally publish it to its tracker issue. Run only when explicitly requested by the user.
+license: MIT
+metadata:
+    github-path: skills/guided-coding-finish-plan
+    github-ref: refs/heads/main
+    github-repo: https://github.com/feO2x/guided-coding
+    github-tree-sha: 991dbf3c4edc54ba093457a75a53b23a52e9501b
+name: guided-coding-finish-plan
+---
+# Finish a Plan
+
+Finish the plan named by the user. If none is named, proceed only when exactly one uncommitted plan
+draft exists in `ai-plans/`; otherwise ask for its path.
+
+## 1. Validate
+
+Read the repository instructions and confirm that:
+
+- The filename is either
+  `YYYY-MM-DD-HHMM-<issue-id>-<kebab-case-description>.md` or, without an issue,
+  `YYYY-MM-DD-HHMM-<kebab-case-description>.md`.
+- Variable filename segments contain only lowercase ASCII letters, digits, and single hyphens, and
+  do not start or end with a hyphen.
+- The file starts with `# Title`, followed by exactly `## Rationale`,
+  `## Acceptance Criteria`, and `## Technical Details`, in that order.
+- Every acceptance criterion is an unticked task (`- [ ]`).
+- Referenced plan documents exist, and claims about existing source files are accurate. Paths for
+  files the plan intends to create are valid references when identified as planned work.
+
+Report validation failures. Fix them only after the user agrees; the Planning Phase is still open
+until the plan is committed.
+
+## 2. Commit and freeze
+
+Inspect `git status` and the staged diff. Preserve unrelated working-tree and staged changes. Stage
+the plan if needed, then use a path-limited commit so the commit contains only the plan file. Verify
+the resulting commit's file list before continuing; if it contains anything else, stop and report
+the problem without rewriting history. Follow repository commit conventions and do not push. The
+successful commit ends the Planning Phase and freezes the plan.
+
+## 3. Optionally publish the first plan
+
+The first plan for a tracked issue may become that issue's description. Follow-up plans are not
+published there.
+
+Use the tracker and target project documented by the repository. If neither is documented, infer
+them only when the git remote and tracker clearly agree, state the inferred target, and ask the
+user to confirm it. If the project has no tracker, skip this step.
+
+Read the current issue title and description before asking to publish. Explain that publishing
+replaces the complete issue description. If it is non-empty, show or summarize what would be
+replaced and require explicit confirmation to overwrite it. Publish the plan body only. For GitHub:
+
+```sh
+gh issue edit <issue-id> --body-file <plan-path>
+```
+
+If the plan and issue titles differ, report it without renaming either. Treat the tracker body as
+a publication snapshot, never as the source from which the committed plan is amended. Never change
+the tracker without the user's approval.
+
+## 4. Report
+
+Report the committed plan path and state that its Planning Phase has ended and it is now frozen.

.agents/skills/guided-coding-finish-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Finish Guided Coding Plan"
+  short_description: "Validate, commit, and freeze a completed plan"
+  default_prompt: "Use $guided-coding-finish-plan to validate and finish this plan."
+
+policy:
+  allow_implicit_invocation: false

.agents/skills/guided-coding-prepare-issue-for-plan/SKILL.md

@@ -0,0 +1,77 @@
+---
+description: Create an empty tracker issue and a clean local branch for a Guided Coding plan. Run only when explicitly requested by the user.
+license: MIT
+metadata:
+    github-path: skills/guided-coding-prepare-issue-for-plan
+    github-ref: refs/heads/main
+    github-repo: https://github.com/feO2x/guided-coding
+    github-tree-sha: 67b76327f9be129189afe9d8390f64044d3d69c5
+name: guided-coding-prepare-issue-for-plan
+---
+# Prepare an Issue for a Plan
+
+Create the issue and branch only. Leave planning to the user and the planning conversation.
+
+## 1. Check prerequisites
+
+Read the repository instructions. Before creating the issue:
+
+1. Run `git status`. If the worktree has uncommitted changes, stop before creating the issue.
+2. Determine the repository's default branch.
+3. Determine the issue tracker and target project from repository instructions. If they are not
+   documented, infer them only when the git remote and tracker clearly agree, such as `gh` with a
+   GitHub remote. State the inferred target and ask the user to confirm it.
+4. When a tracker exists, confirm that its CLI is available and authenticated for the target
+   project. Check its help rather than guessing flags.
+
+Use the title supplied by the user. If none is provided, ask for a short title. Derive a lowercase,
+hyphen-separated topic of at most four words.
+
+Example: `Support cancelled events` becomes `cancelled-events`.
+
+## 2. Update the default branch
+
+Switch to the default branch and update it before creating the external issue:
+
+```sh
+git switch <default-branch>
+git pull --ff-only
+```
+
+Stop if either command fails.
+
+## 3. Create the issue
+
+Create the issue with the agreed title and an empty description. Do not add a summary,
+acceptance criteria, or placeholder text. Use the tracker's documented CLI. For GitHub:
+
+```sh
+gh issue create --title "<title>" --body ""
+```
+
+Read the identifier and URL from the command output. Normalize the identifier for filenames and
+branches: convert it to lowercase, remove a leading `#`, replace each run of characters other than
+`a-z` and `0-9` with one hyphen, trim leading and trailing hyphens, and do not add zero padding. Stop
+if normalization produces an empty identifier.
+
+If the project has no issue tracker, skip issue creation and use the topic alone for the branch
+and later plan filename.
+
+## 4. Create the branch
+
+Create `<issue-id>-<topic>` or, without an issue, `<topic>`. Validate the complete name before
+creating it:
+
+```sh
+git check-ref-format --branch "<branch-name>"
+git switch -c <branch-name>
+```
+
+Stop if the intended branch already exists; do not reuse or rename it implicitly. If validation or
+branch creation fails after the issue was created, do not close or delete the issue automatically.
+Report the issue and the failure so the user can choose the recovery action.
+
+## 5. Report
+
+Report the issue identifier and URL, when present, and the branch name. Then stop. Do not write
+the plan.

.agents/skills/guided-coding-prepare-issue-for-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Prepare Guided Coding Issue"
+  short_description: "Create a tracker issue and clean planning branch"
+  default_prompt: "Use $guided-coding-prepare-issue-for-plan to create an issue and branch for this work."
+
+policy:
+  allow_implicit_invocation: false

.agents/skills/guided-coding-review-plan/SKILL.md

@@ -0,0 +1,38 @@
+---
+description: Review a completed Guided Coding plan draft against the codebase before its Planning Phase ends. Run only when explicitly requested by the user.
+license: MIT
+metadata:
+    github-path: skills/guided-coding-review-plan
+    github-ref: refs/heads/main
+    github-repo: https://github.com/feO2x/guided-coding
+    github-tree-sha: f02d971824425244e54bb006335f8b2885cb7b6b
+name: guided-coding-review-plan
+---
+# Review a Plan
+
+Review the plan named by the user. If none is named, proceed only when exactly one uncommitted plan
+draft exists in `ai-plans/`; otherwise ask for its path. Report findings only; never edit the plan
+or any other file.
+
+Read the plan, applicable repository instructions, the code it discusses, and every earlier
+document for the same issue, including legacy filenames. Verify assertions about existing types,
+members, files, APIs, and extension points. Do not reject files or types merely because the plan
+intends to create them.
+
+Amongst other things, check for:
+
+- **Acceptance criteria:** Each criterion describes an observable, verifiable outcome rather
+  than an implementation step. Behavior changes require appropriate automated test coverage.
+- **Verifiability:** The required feedback loops exist in repository instructions, build files,
+  scripts, or CI configuration.
+- **Technical decisions:** Data structures, abstractions, and framework mechanisms fit the
+  surrounding architecture without unnecessary indirection.
+- **Level of detail:** The plan records non-obvious decisions and interactions without
+  prescribing routine implementation.
+- **Omissions:** Judge relevant risks such as error handling, compatibility, migration,
+  performance, security boundaries, and observability against the change at hand.
+- **History:** A follow-up plan explicitly identifies and explains any earlier decisions it
+  supersedes.
+
+Say explicitly when there are no findings. If the plan is already frozen, note that corrections
+require a follow-up plan rather than edits.

.agents/skills/guided-coding-review-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Review Guided Coding Plan"
+  short_description: "Review a plan draft against the repository"
+  default_prompt: "Use $guided-coding-review-plan to review this plan draft against the repository."
+
+policy:
+  allow_implicit_invocation: false

.agents/skills/guided-coding-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: Set up or upgrade Guided Coding repository instructions, plan storage, and documented feedback-loop commands. Run only when explicitly requested by the user.
+license: MIT
+metadata:
+    github-path: skills/guided-coding-setup
+    github-ref: refs/heads/main
+    github-repo: https://github.com/feO2x/guided-coding
+    github-tree-sha: 45dc5336407039c7a5c1422eb37ad7069a11724f
+name: guided-coding-setup
+---
+# Set Up Guided Coding
+
+Set up or upgrade Guided Coding in the current repository. Preserve project-specific instructions
+and user-authored content. Never modify existing plan or Plan Deviations documents.
+
+## 1. Inspect the repository
+
+Read the root `AGENTS.md` when present, `ai-plans/AGENTS.md` when present, nested instruction
+files, build manifests, task runners, scripts, and CI configuration.
+
+Identify feedback loops and their exact commands. Look for:
+
+- compilers, transpilers, type checkers, static analyzers, and linters;
+- unit, integration, end-to-end, coverage, and mutation tests;
+- benchmarks and performance tests; and
+- dependency, secret, container, and source-code security scans.
+
+Do not invent commands or list tools merely because they are common for the detected language.
+Prefer the repository's documented entry points. When a command is safe, non-destructive, and
+reasonably bounded, run it to detect stale instructions. Do not claim that a command passed unless
+it was executed successfully; report why any documented command was not run. If existing Guided
+Coding instructions conflict with this version and resolving them would discard a project-specific
+decision, ask before editing.
+
+## 2. Update the root instructions
+
+Create `AGENTS.md` if it does not exist. Otherwise make the smallest idempotent update that
+preserves unrelated sections.
+
+Ensure it contains:
+
+1. `## When you implement a plan`, stating that:
+   - plans in `ai-plans/` are frozen after their Planning Phase;
+   - only acceptance criteria may change, from `- [ ]` to `- [x]`;
+   - a criterion is checked only after the implementation and relevant feedback loops verify it;
+   - unmet criteria remain unchecked and their wording is never changed; and
+   - material departures from explicit plan decisions require a Plan Deviations document rather
+     than edits to the frozen plan.
+2. `## Feedback loops`, listing each repository-confirmed command and what it verifies. State
+   plainly when no automated feedback-loop command can be confirmed.
+3. `## How to write plans`, linking to `ai-plans/AGENTS.md`.
+4. `## This is your space` as the final section, inviting agents to record noteworthy repository
+   discoveries for later discussion. Preserve any notes already in that section.
+
+Consolidate equivalent existing sections instead of adding duplicates.
+
+## 3. Update the plan record
+
+Create `ai-plans/` when missing. Create or update `ai-plans/AGENTS.md` from
+`assets/ai-plans-AGENTS.md`.
+
+Keep the version marker and portable Guided Coding rules current while preserving repository-
+specific additions and notes about legacy plan filenames. Do not rename, rewrite, or reorganize
+historical documents during an upgrade.
+
+## 4. Report
+
+Report the files created or updated, the feedback loops documented, which commands were executed
+and their results, why any were not run, and any unresolved conflicts. Then stop.

.agents/skills/guided-coding-setup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Guided Coding Setup"
+  short_description: "Set up or upgrade Guided Coding in a repository"
+  default_prompt: "Use $guided-coding-setup to set up or upgrade Guided Coding in this repository."
+
+policy:
+  allow_implicit_invocation: false

.agents/skills/guided-coding-setup/assets/ai-plans-AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md for AI plans
+
+<!-- guided-coding-version: 2.0.0 -->
+
+This directory is the append-only record of how work in this repository was planned and how it
+turned out. It follows the [Guided Coding](https://kenny-codes.net/docs/guided-coding/) approach.
+
+Plan filenames use `YYYY-MM-DD-HHMM-<issue-id>-<kebab-case-description>.md`, timestamped in UTC
+when written. Omit the issue segment when work has no tracker issue. Plan Deviations filenames use
+`YYYY-MM-DD-HHMM-<issue-id>-plan-deviations.md`, or the corresponding topic when there is no issue.
+Do not rename historical documents solely to conform to the current format.
+
+Plans are frozen when their Planning Phase ends. From then on, the only permitted edit is checking
+an acceptance criterion (`- [ ]` to `- [x]`) after the implementation and relevant feedback loops
+verify it. Never reword, add, remove, or reorder criteria in a frozen plan. Plan Deviations
+documents are frozen once committed. Never rename or delete a plan or Plan Deviations document.
+
+Every plan starts with `# Title` followed by exactly `## Rationale`, `## Acceptance Criteria`, and
+`## Technical Details`, in that order. Acceptance criteria are observable, verifiable outcomes
+written as unchecked Markdown tasks. Technical Details record important decisions, constraints,
+affected components, and non-obvious interactions without prescribing routine implementation.
+
+Use a follow-up plan to correct or supersede a frozen plan. Always write a Plan Deviations document
+when at least one follow-up plan exists, summarizing which earlier decisions they superseded and the final
+outcome. Also use a Plan Deviations document when the final implementation materially changes or
+rejects an explicit plan decision. Plan Deviations must identify the compared plans and describe
+what was planned, what changed, why it changed, the final implementation, and the impact.
+
+Before writing a plan or Plan Deviations document, use the corresponding Guided Coding skill.

.agents/skills/guided-coding-write-deviations/SKILL.md

@@ -0,0 +1,62 @@
+---
+description: Decide whether a completed Guided Coding cycle needs a Plan Deviations document and write it when required. Run only when explicitly requested by the user.
+license: MIT
+metadata:
+    github-path: skills/guided-coding-write-deviations
+    github-ref: refs/heads/main
+    github-repo: https://github.com/feO2x/guided-coding
+    github-tree-sha: da0a168bf4404594f4c22291bc8f07f3c1f8432c
+name: guided-coding-write-deviations
+---
+# Write Plan Deviations
+
+## Inspect
+
+- Read all plans for the current work, oldest first.
+- Determine the implementation range from its PR/MR, or the target branch's merge base with the
+  implementation branch.
+- Inspect its commits, all committed/staged/unstaged changes, and relevant earlier history. Verify
+  every document and source-file reference.
+
+## Decide
+
+Create the Plan Deviation Document if:
+
+- **Follow-up plans exist:** summarize changes from the first plan so it and this document explain
+  the complete work.
+- **The implementation materially changes or rejects an explicit plan decision** about an
+  acceptance outcome; public contract or data model; architectural or component boundary; security
+  or performance constraint; or another design decision future maintainers need.
+
+Exclude routine choices the plans left open. A documented but unmet acceptance criterion remains
+incomplete unless an accepted follow-up plan explicitly supersedes it.
+
+Otherwise, with one plan and no material deviations, report that conclusion and create nothing.
+
+## Write
+
+Use `YYYY-MM-DD-HHMM-<issue-id>-plan-deviations.md`; without a tracker issue, use
+`YYYY-MM-DD-HHMM-<topic>-plan-deviations.md`. Get UTC from the shell, never the conversation:
+`date -u +%F-%H%M`, or PowerShell `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd-HHmm")`.
+Normalize issue identifiers like the related plans. Resolve the full unused path. If any plan or
+Plan Deviations document already uses it, report the collision and stop; never overwrite or reuse.
+
+Write:
+
+1. `# <issue-id or topic> Plan Deviations`.
+2. An opening paragraph naming every compared plan by exact filename and the implementation branch,
+   and identifying unimplemented plans.
+3. `## Summary`: what held up and how many material decisions changed.
+4. `## Changes Across Follow-Up Plans`, when applicable: one numbered `###` per superseded decision
+   with **Original decision**, **Superseded by** (exact filename and replacement), **Why**, and
+   **Final outcome**.
+5. `## Deviations From the Accepted Plans`, when applicable: one numbered `###` per material
+   implementation deviation with **Plan decision** (exact filename and decision), **Implemented**,
+   **Why** (required), and **Impact** (trade-offs, consequences, or deferred work; omit only if none).
+
+Name affected types, members, and files. Exclude work matching the accepted plans. If all follow-up
+plans match, say so in the Summary and omit `## Deviations From the Accepted Plans`.
+
+## Stop
+
+Report the path. Do not commit, publish, or create/update a PR/MR. The user reviews and finalizes it.

.agents/skills/guided-coding-write-deviations/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Write Guided Coding Plan Deviations"
+  short_description: "Summarize follow-up plans and code deviations"
+  default_prompt: "Use $guided-coding-write-deviations to compare the implementation with its plans."
+
+policy:
+  allow_implicit_invocation: false