From 5c738bc02c8d4253a9dff0e397f60abb767d5d8c Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sat, 19 Sep 2026 05:18:34 +0200 Subject: [PATCH 01/26] chore: clean up root AGENTS.md Signed-off-by: Kenny Pflug --- AGENTS.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 14fa2aa..882216e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,6 @@ # Repository Instructions -This repository is the canonical distribution of Guided Coding skills. The root package supports -the Agent Plugins standard and generates a dedicated Claude Code marketplace adapter. +This repository contains skills for Guided Coding. The root package supports the Agent Plugins standard and generates a dedicated Claude Code marketplace adapter. ## Skill authoring @@ -10,18 +9,13 @@ the Agent Plugins standard and generates a dedicated Claude Code marketplace ada - Keep the skill directory and frontmatter name identical. - State in every description that the skill runs only when explicitly requested. - Put Codex-specific interface and invocation policy in `agents/openai.yaml`. -- Configure Claude-specific names and frontmatter in - `tools/GuidedCoding.ClaudeGenerator/claude-skills.json`. -- Do not edit `claude-plugin/claude-skills` directly. Regenerate it with - `dotnet run --project tools/GuidedCoding.ClaudeGenerator`. -- Do not hand-author duplicate skill bodies for individual coding-agent harnesses. -- Keep the generated directory named `claude-skills`. A standard `claude-plugin/skills` directory - is also discovered by GitHub CLI and would duplicate the portable skills during publication. +- Configure Claude-specific names and frontmatter in `tools/GuidedCoding.ClaudeGenerator/claude-skills.json`. +- Do not edit `claude-plugin/claude-skills` directly. Regenerate it with `dotnet run --project tools/GuidedCoding.ClaudeGenerator`. +- Keep the generated directory named `claude-skills`. A standard `claude-plugin/skills` directory is also discovered by GitHub CLI and would duplicate the portable skills during publication. ## Manifests and versions -Keep the version synchronized across `plugin.json`, `claude-plugin/.claude-plugin/plugin.json`, -`.claude-plugin/marketplace.json`, and release tags. +Keep the version synchronized across `plugin.json`, `claude-plugin/.claude-plugin/plugin.json`,`.claude-plugin/marketplace.json`, and release tags. Use Conventional Commits messages. From 90f9bc19b5ff77d7ba6ab581c3b74aefae1f4681 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sat, 19 Sep 2026 06:54:50 +0200 Subject: [PATCH 02/26] feat: add guided learning implementation skills --- CHANGELOG.md | 1 + README.md | 2 + .../implement-and-learn-by-example/SKILL.md | 94 ++++++++++++++++ .../implement-and-learn-by-solving/SKILL.md | 104 ++++++++++++++++++ .../SKILL.md | 93 ++++++++++++++++ .../agents/openai.yaml | 7 ++ .../SKILL.md | 103 +++++++++++++++++ .../agents/openai.yaml | 7 ++ .../PackageValidationTests.cs | 4 + .../claude-skills.json | 8 ++ 10 files changed, 423 insertions(+) create mode 100644 claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md create mode 100644 claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md create mode 100644 skills/guided-coding-implement-and-learn-by-example/SKILL.md create mode 100644 skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml create mode 100644 skills/guided-coding-implement-and-learn-by-solving/SKILL.md create mode 100644 skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index ec4e70e..f9a9249 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,3 +10,4 @@ All notable changes to Guided Coding are documented here. - Require Plan Deviations documents for material departures from frozen plans. - Distribute Guided Coding as portable Agent Skills and an Agent Plugin. - Generate a Claude Code adapter with concise, manually invoked skill names. +- Add learning workflows for implementing plans through worked examples or coached problem solving. diff --git a/README.md b/README.md index 17faa49..7b92694 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ The full method is documented at | `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-freeze-plan` | Freeze a plan by timestamping its file name and title. | +| `guided-coding-implement-and-learn-by-example` | Implement a frozen plan through worked code examples that you enter and discuss. | +| `guided-coding-implement-and-learn-by-solving` | Implement a frozen plan yourself through coached, verifiable milestones. | | `guided-coding-write-deviations` | Summarize follow-up plans and record material implementation differences. | All workflows require explicit user invocation. diff --git a/claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md b/claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md new file mode 100644 index 0000000..969a56b --- /dev/null +++ b/claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md @@ -0,0 +1,94 @@ +--- +name: implement-and-learn-by-example +description: "Guide a user through implementing a Frozen Guided Coding Plan by presenting and explaining complete code for one milestone at a time for the user to enter and examine. Run only when explicitly requested by the user." +license: "MIT" +disable-model-invocation: true +--- + +# Implement and Learn by Example + +Your goal is to teach the user how to implement a Frozen Plan through repository-specific worked examples. You provide the complete code for one milestone at a time and explain it; the user enters the code, runs it, and asks questions. + +Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. + +Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +Read: + +- applicable repository instructions and documented feedback loops; +- the target plan and every earlier plan for the same ticket that it refers to or supersedes; +- the relevant implementation and tests; and +- the current git status and diff, including the user's existing changes. + +Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. + +## 2. Create the Milestone Roadmap + +Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. + +Each milestone should: + +- produce one observable behavior or establish one internal invariant; +- introduce one primary mechanism or a tightly related concept cluster; +- include the tests or other verification that make it independently demonstrable; and +- have a completion condition that can be stated in one sentence. + +Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, the user should usually be able to enter, study, and verify one example in 10–30 minutes. Split a milestone when its code or explanation contains multiple independently teachable concepts or verification points. + +## 3. Present One Worked Example + +For the current milestone, provide: + +1. **Outcome:** What the example adds and how the user will observe it. +2. **Placement:** The exact files and locations where each fragment belongs. +3. **Code:** Complete, repository-specific code for this milestone, including tests when they are part of the same coherent example. +4. **Explanation:** What the code does, how its pieces interact, and every language or framework mechanism likely to be new to the user. +5. **Reasoning:** Why this implementation fits the Frozen Plan and the surrounding architecture. Discuss alternatives only when they clarify an important decision. +6. **Verification:** The exact feedback-loop command or manual check, plus the expected result. + +Providing the code is the purpose of this workflow; do not replace it with hints or pseudocode. At the same time, do not provide later milestones or combine fragments into a solution for the entire plan. + +Do not apply the code yourself. After presenting the example, stop so the user can enter it, inspect it, run it, and ask questions. + +## 4. Discuss and Verify the Example + +Answer the user's questions directly and remain on the current milestone until they say they understand it and are ready to continue. Explain unfamiliar syntax when asked, but do not require a quiz or make the user restate every explanation. + +After the user enters the code: + +- inspect their actual changes before evaluating them; +- distinguish transcription or adaptation mistakes from errors in the example you supplied; +- explain any discrepancy and provide a corrected fragment when needed; and +- run the relevant feedback loops, or review their output when the user ran them. + +Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-and-learn-by-solving`. + +## 5. Handle Plan Issues During Implementation + +Routine choices that the plans leave open may be resolved in the worked example. Explain consequential choices so the user can understand them. + +If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: + +- identify the exact decision or criterion and explain why it does not work; +- provide a recommended solution or workaround, including its trade-offs and repository-specific code when code is needed; +- clearly label the approach as provisional rather than silently treating it as a new plan decision; +- state which Acceptance Criteria the workaround satisfies and which remain unmet; and +- retain the issue and provisional approach for the final Guiding Phase handoff. + +Remain in the Implementing Phase and continue the worked-example workflow with the provisional approach. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. + +## 6. Finish the Learning Implementation + +After all milestones: + +- inspect the complete implementation diff; +- compare it with every Acceptance Criterion; +- run all applicable feedback loops and identify any required manual checks; and +- report which criteria are verified and which remain incomplete; and +- summarize every plan issue, its provisional solution or workaround, and its impact. + +Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. diff --git a/claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md b/claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md new file mode 100644 index 0000000..300fc7d --- /dev/null +++ b/claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md @@ -0,0 +1,104 @@ +--- +name: implement-and-learn-by-solving +description: "Guide a user through implementing a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without writing the implementation. Run only when explicitly requested by the user." +license: "MIT" +disable-model-invocation: true +--- + +# Implement and Learn by Solving + +Your goal is to coach the user through implementing a Frozen Plan themselves. You define one bounded problem at a time, explain its context, review the user's solution, and provide progressively stronger hints when needed. The user authors all implementation and test code. + +Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. + +Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +Read: + +- applicable repository instructions and documented feedback loops; +- the target plan and every earlier plan for the same ticket that it refers to or supersedes; +- the relevant implementation and tests; and +- the current git status and diff, including the user's existing changes. + +Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. + +## 2. Create the Milestone Roadmap + +Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without disclosing their solutions, then start with the first incomplete milestone. + +Each milestone should: + +- produce one observable behavior or establish one internal invariant; +- require one meaningful implementation decision; +- include independently useful tests or other verification; and +- have a completion condition that can be stated in one sentence. + +Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, one milestone should usually fit into 20–60 minutes of focused work for the current user. Split it when it introduces multiple unfamiliar concepts, contains independent design decisions, or has more than one useful verification point. Combine steps that are merely mechanical and provide no meaningful feedback on their own. + +## 3. Pose One Implementation Problem + +For the current milestone, provide: + +1. **Outcome:** What must be true when the milestone is complete. +2. **Why:** How the milestone contributes to the plan and what the user can learn from it. +3. **Starting points:** Existing files, types, tests, documentation, or patterns worth inspecting. +4. **Constraints:** Relevant decisions and invariants from the Frozen Plans. +5. **Concepts:** New patterns, principles, APIs, or tooling worth investigating, without applying them to produce the solution. +6. **Verification:** The exact feedback-loop command or manual check and its expected result. + +Do not suggest a complete implementation approach or provide repository-ready code at this point. Stop and let the user design and implement the solution. + +## 4. Review the User's Solution + +When the user returns, inspect their actual changes before evaluating them. Explain specifically: + +- what is correct and why; +- what does not yet satisfy the milestone or plan; +- which design, correctness, testing, or maintainability concerns remain; and +- what the user should reconsider next without supplying the finished code. + +Accept valid approaches that differ from the one you anticipated. Let the user revise their solution, then run the relevant feedback loops or review the output they provide. Advance only after the milestone's outcome is satisfied and verified. + +## 5. Provide Progressive Hints + +When the user is stuck, provide one additional aid at a time: + +1. Ask a focused diagnostic question or restate the relevant invariant. +2. Point to an analogous part of the repository or relevant documentation. +3. Explain the missing language, framework, design, or tooling mechanism and its trade-offs. +4. Provide pseudocode or an API-level outline. +5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. + +After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-and-learn-by-example` rather than changing this workflow's contract. + +Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. + +## 6. Handle Plan Issues During Implementation + +Routine choices that the plans leave open belong to the user. Explain relevant trade-offs without inventing new requirements. + +If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: + +- identify the exact decision or criterion and explain why it does not work; +- recommend a solution or workaround and explain its trade-offs; +- clearly label the approach as provisional rather than silently treating it as a new plan decision; +- state which Acceptance Criteria the workaround satisfies and which remain unmet; and +- retain the issue and provisional approach for the final Guiding Phase handoff. + +Continue the problem-solving workflow using the provisional approach. Describe the workaround precisely enough for the user to implement it, while preserving this skill's rule that the user authors the code. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. + +## 7. Finish the Learning Implementation + +After all milestones: + +- inspect the complete implementation diff; +- compare it with every Acceptance Criterion; +- run all applicable feedback loops and identify any required manual checks; and +- report which criteria are verified and which remain incomplete; and +- summarize every plan issue, its provisional solution or workaround, and its impact. + +Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. diff --git a/skills/guided-coding-implement-and-learn-by-example/SKILL.md b/skills/guided-coding-implement-and-learn-by-example/SKILL.md new file mode 100644 index 0000000..98ef41a --- /dev/null +++ b/skills/guided-coding-implement-and-learn-by-example/SKILL.md @@ -0,0 +1,93 @@ +--- +name: guided-coding-implement-and-learn-by-example +description: Guide a user through implementing a Frozen Guided Coding Plan by presenting and explaining complete code for one milestone at a time for the user to enter and examine. Run only when explicitly requested by the user. +license: MIT +--- + +# Implement and Learn by Example + +Your goal is to teach the user how to implement a Frozen Plan through repository-specific worked examples. You provide the complete code for one milestone at a time and explain it; the user enters the code, runs it, and asks questions. + +Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. + +Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +Read: + +- applicable repository instructions and documented feedback loops; +- the target plan and every earlier plan for the same ticket that it refers to or supersedes; +- the relevant implementation and tests; and +- the current git status and diff, including the user's existing changes. + +Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. + +## 2. Create the Milestone Roadmap + +Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. + +Each milestone should: + +- produce one observable behavior or establish one internal invariant; +- introduce one primary mechanism or a tightly related concept cluster; +- include the tests or other verification that make it independently demonstrable; and +- have a completion condition that can be stated in one sentence. + +Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, the user should usually be able to enter, study, and verify one example in 10–30 minutes. Split a milestone when its code or explanation contains multiple independently teachable concepts or verification points. + +## 3. Present One Worked Example + +For the current milestone, provide: + +1. **Outcome:** What the example adds and how the user will observe it. +2. **Placement:** The exact files and locations where each fragment belongs. +3. **Code:** Complete, repository-specific code for this milestone, including tests when they are part of the same coherent example. +4. **Explanation:** What the code does, how its pieces interact, and every language or framework mechanism likely to be new to the user. +5. **Reasoning:** Why this implementation fits the Frozen Plan and the surrounding architecture. Discuss alternatives only when they clarify an important decision. +6. **Verification:** The exact feedback-loop command or manual check, plus the expected result. + +Providing the code is the purpose of this workflow; do not replace it with hints or pseudocode. At the same time, do not provide later milestones or combine fragments into a solution for the entire plan. + +Do not apply the code yourself. After presenting the example, stop so the user can enter it, inspect it, run it, and ask questions. + +## 4. Discuss and Verify the Example + +Answer the user's questions directly and remain on the current milestone until they say they understand it and are ready to continue. Explain unfamiliar syntax when asked, but do not require a quiz or make the user restate every explanation. + +After the user enters the code: + +- inspect their actual changes before evaluating them; +- distinguish transcription or adaptation mistakes from errors in the example you supplied; +- explain any discrepancy and provide a corrected fragment when needed; and +- run the relevant feedback loops, or review their output when the user ran them. + +Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-and-learn-by-solving`. + +## 5. Handle Plan Issues During Implementation + +Routine choices that the plans leave open may be resolved in the worked example. Explain consequential choices so the user can understand them. + +If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: + +- identify the exact decision or criterion and explain why it does not work; +- provide a recommended solution or workaround, including its trade-offs and repository-specific code when code is needed; +- clearly label the approach as provisional rather than silently treating it as a new plan decision; +- state which Acceptance Criteria the workaround satisfies and which remain unmet; and +- retain the issue and provisional approach for the final Guiding Phase handoff. + +Remain in the Implementing Phase and continue the worked-example workflow with the provisional approach. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. + +## 6. Finish the Learning Implementation + +After all milestones: + +- inspect the complete implementation diff; +- compare it with every Acceptance Criterion; +- run all applicable feedback loops and identify any required manual checks; and +- report which criteria are verified and which remain incomplete; and +- summarize every plan issue, its provisional solution or workaround, and its impact. + +Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. diff --git a/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml b/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml new file mode 100644 index 0000000..2bc8a1d --- /dev/null +++ b/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Implement and Learn by Example" + short_description: "Learn implementation through worked examples" + default_prompt: "Use $guided-coding-implement-and-learn-by-example to help me implement the Frozen Plan through worked code examples that I enter and discuss." + +policy: + allow_implicit_invocation: false diff --git a/skills/guided-coding-implement-and-learn-by-solving/SKILL.md b/skills/guided-coding-implement-and-learn-by-solving/SKILL.md new file mode 100644 index 0000000..31b9ce9 --- /dev/null +++ b/skills/guided-coding-implement-and-learn-by-solving/SKILL.md @@ -0,0 +1,103 @@ +--- +name: guided-coding-implement-and-learn-by-solving +description: Guide a user through implementing a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without writing the implementation. Run only when explicitly requested by the user. +license: MIT +--- + +# Implement and Learn by Solving + +Your goal is to coach the user through implementing a Frozen Plan themselves. You define one bounded problem at a time, explain its context, review the user's solution, and provide progressively stronger hints when needed. The user authors all implementation and test code. + +Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. + +Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +Read: + +- applicable repository instructions and documented feedback loops; +- the target plan and every earlier plan for the same ticket that it refers to or supersedes; +- the relevant implementation and tests; and +- the current git status and diff, including the user's existing changes. + +Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. + +## 2. Create the Milestone Roadmap + +Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without disclosing their solutions, then start with the first incomplete milestone. + +Each milestone should: + +- produce one observable behavior or establish one internal invariant; +- require one meaningful implementation decision; +- include independently useful tests or other verification; and +- have a completion condition that can be stated in one sentence. + +Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, one milestone should usually fit into 20–60 minutes of focused work for the current user. Split it when it introduces multiple unfamiliar concepts, contains independent design decisions, or has more than one useful verification point. Combine steps that are merely mechanical and provide no meaningful feedback on their own. + +## 3. Pose One Implementation Problem + +For the current milestone, provide: + +1. **Outcome:** What must be true when the milestone is complete. +2. **Why:** How the milestone contributes to the plan and what the user can learn from it. +3. **Starting points:** Existing files, types, tests, documentation, or patterns worth inspecting. +4. **Constraints:** Relevant decisions and invariants from the Frozen Plans. +5. **Concepts:** New patterns, principles, APIs, or tooling worth investigating, without applying them to produce the solution. +6. **Verification:** The exact feedback-loop command or manual check and its expected result. + +Do not suggest a complete implementation approach or provide repository-ready code at this point. Stop and let the user design and implement the solution. + +## 4. Review the User's Solution + +When the user returns, inspect their actual changes before evaluating them. Explain specifically: + +- what is correct and why; +- what does not yet satisfy the milestone or plan; +- which design, correctness, testing, or maintainability concerns remain; and +- what the user should reconsider next without supplying the finished code. + +Accept valid approaches that differ from the one you anticipated. Let the user revise their solution, then run the relevant feedback loops or review the output they provide. Advance only after the milestone's outcome is satisfied and verified. + +## 5. Provide Progressive Hints + +When the user is stuck, provide one additional aid at a time: + +1. Ask a focused diagnostic question or restate the relevant invariant. +2. Point to an analogous part of the repository or relevant documentation. +3. Explain the missing language, framework, design, or tooling mechanism and its trade-offs. +4. Provide pseudocode or an API-level outline. +5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. + +After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-and-learn-by-example` rather than changing this workflow's contract. + +Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. + +## 6. Handle Plan Issues During Implementation + +Routine choices that the plans leave open belong to the user. Explain relevant trade-offs without inventing new requirements. + +If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: + +- identify the exact decision or criterion and explain why it does not work; +- recommend a solution or workaround and explain its trade-offs; +- clearly label the approach as provisional rather than silently treating it as a new plan decision; +- state which Acceptance Criteria the workaround satisfies and which remain unmet; and +- retain the issue and provisional approach for the final Guiding Phase handoff. + +Continue the problem-solving workflow using the provisional approach. Describe the workaround precisely enough for the user to implement it, while preserving this skill's rule that the user authors the code. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. + +## 7. Finish the Learning Implementation + +After all milestones: + +- inspect the complete implementation diff; +- compare it with every Acceptance Criterion; +- run all applicable feedback loops and identify any required manual checks; and +- report which criteria are verified and which remain incomplete; and +- summarize every plan issue, its provisional solution or workaround, and its impact. + +Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. diff --git a/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml b/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml new file mode 100644 index 0000000..fca07bf --- /dev/null +++ b/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Implement and Learn by Solving" + short_description: "Solve implementation milestones with coaching" + default_prompt: "Use $guided-coding-implement-and-learn-by-solving to help me implement the Frozen Plan by solving each milestone myself." + +policy: + allow_implicit_invocation: false diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index dd260ed..0d1cc2d 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -16,6 +16,8 @@ public sealed class PackageValidationTests private static readonly string[] ExpectedPortableSkillNames = [ "guided-coding-freeze-plan", + "guided-coding-implement-and-learn-by-example", + "guided-coding-implement-and-learn-by-solving", "guided-coding-review-plan", "guided-coding-setup", "guided-coding-write-deviations", @@ -27,6 +29,8 @@ public sealed class PackageValidationTests ) { ["guided-coding-freeze-plan"] = "freeze-plan", + ["guided-coding-implement-and-learn-by-example"] = "implement-and-learn-by-example", + ["guided-coding-implement-and-learn-by-solving"] = "implement-and-learn-by-solving", ["guided-coding-review-plan"] = "review-plan", ["guided-coding-setup"] = "setup", ["guided-coding-write-deviations"] = "write-deviations", diff --git a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json index 6f4712d..02108a0 100644 --- a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json +++ b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json @@ -4,6 +4,14 @@ "name": "freeze-plan", "disableModelInvocation": true }, + "guided-coding-implement-and-learn-by-example": { + "name": "implement-and-learn-by-example", + "disableModelInvocation": true + }, + "guided-coding-implement-and-learn-by-solving": { + "name": "implement-and-learn-by-solving", + "disableModelInvocation": true + }, "guided-coding-review-plan": { "name": "review-plan", "disableModelInvocation": true From 576992ff75e32065ed21efbfe2899f381467ab14 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sun, 20 Sep 2026 06:38:53 +0200 Subject: [PATCH 03/26] feat: introduce guided-coding-implement skill Signed-off-by: Kenny Pflug --- .../claude-skills/implement/SKILL.md | 32 +++++++++++++++++++ skills/guided-coding-implement/SKILL.md | 31 ++++++++++++++++++ .../agents/openai.yaml | 7 ++++ .../claude-skills.json | 4 +++ 4 files changed, 74 insertions(+) create mode 100644 claude-plugin/claude-skills/implement/SKILL.md create mode 100644 skills/guided-coding-implement/SKILL.md create mode 100644 skills/guided-coding-implement/agents/openai.yaml diff --git a/claude-plugin/claude-skills/implement/SKILL.md b/claude-plugin/claude-skills/implement/SKILL.md new file mode 100644 index 0000000..1ddd8ff --- /dev/null +++ b/claude-plugin/claude-skills/implement/SKILL.md @@ -0,0 +1,32 @@ +--- +name: implement +description: "Implement a Frozen Guided Coding Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user." +license: "MIT" +disable-model-invocation: true +--- + +# Implement a Frozen Plan + +Your goal is to implement a Frozen Plan created in the Planning Phase of Guided Coding. Once you are finished implementing, a reviewer will check your results in the Guiding Phase. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. + +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +## 2. Implement and Verify + +Implement the plan, use the feedback loops to verify your code changes. + +The only allowed plan edit is ticking an Acceptance Criterion from `- [ ]` to `- [x]`. Never check a criterion unless it is genuinely satisfied by a feedback loop. The reviewer would otherwise have to identify the gap later in the Guiding Phase, which is one of the hardest errors to spot. + +## 3. Handle Plan Issues + +If an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. + +In the Guiding Phase, the reviewer can decide how to proceed with your findings. + +## 4. Finish + +Report what was implemented, which feedback loops ran and their results, which Acceptance Criteria are checked, and which remain unchecked and why. Do not create commits, open or update a pull request, publish anything, etc. - unless the user asked you to do so. diff --git a/skills/guided-coding-implement/SKILL.md b/skills/guided-coding-implement/SKILL.md new file mode 100644 index 0000000..c0a3b2b --- /dev/null +++ b/skills/guided-coding-implement/SKILL.md @@ -0,0 +1,31 @@ +--- +name: guided-coding-implement +description: Implement a Frozen Guided Coding Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user. +license: MIT +--- + +# Implement a Frozen Plan + +Your goal is to implement a Frozen Plan created in the Planning Phase of Guided Coding. Once you are finished implementing, a reviewer will check your results in the Guiding Phase. + +## 1. Establish the Target + +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. + +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. + +## 2. Implement and Verify + +Implement the plan, use the feedback loops to verify your code changes. + +The only allowed plan edit is ticking an Acceptance Criterion from `- [ ]` to `- [x]`. Never check a criterion unless it is genuinely satisfied by a feedback loop. The reviewer would otherwise have to identify the gap later in the Guiding Phase, which is one of the hardest errors to spot. + +## 3. Handle Plan Issues + +If an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. + +In the Guiding Phase, the reviewer can decide how to proceed with your findings. + +## 4. Finish + +Report what was implemented, which feedback loops ran and their results, which Acceptance Criteria are checked, and which remain unchecked and why. Do not create commits, open or update a pull request, publish anything, etc. - unless the user asked you to do so. diff --git a/skills/guided-coding-implement/agents/openai.yaml b/skills/guided-coding-implement/agents/openai.yaml new file mode 100644 index 0000000..afc4af0 --- /dev/null +++ b/skills/guided-coding-implement/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Implement Guided Coding Plan" + short_description: "Implement a Frozen Plan with repository feedback loops" + default_prompt: "Use $guided-coding-implement to implement this Frozen Plan and run its documented feedback loops." + +policy: + allow_implicit_invocation: false diff --git a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json index 02108a0..965dd28 100644 --- a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json +++ b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json @@ -4,6 +4,10 @@ "name": "freeze-plan", "disableModelInvocation": true }, + "guided-coding-implement": { + "name": "implement", + "disableModelInvocation": true + }, "guided-coding-implement-and-learn-by-example": { "name": "implement-and-learn-by-example", "disableModelInvocation": true From 569da54fd8ed501ae6af97641da2236b02541806 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sun, 20 Sep 2026 06:55:16 +0200 Subject: [PATCH 04/26] feat: simplify guided-coding-setup skill Signed-off-by: Kenny Pflug --- skills/guided-coding-setup/SKILL.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/skills/guided-coding-setup/SKILL.md b/skills/guided-coding-setup/SKILL.md index f8f4b5b..4d97f5d 100644 --- a/skills/guided-coding-setup/SKILL.md +++ b/skills/guided-coding-setup/SKILL.md @@ -10,9 +10,9 @@ Your goal is to set up or upgrade Guided Coding in the current repository. After Guided Coding needs these artifacts: -- `AGENTS.md` at the repository root, listing the feedback loops and the rules for implementing a Frozen Plan. +- `AGENTS.md` at the repository root, listing the feedback loops and pointing to `ai-plans/AGENTS.md`. - `ai-plans/`, the folder holding all plans and Plan Deviations documents. -- `ai-plans/AGENTS.md`, describing the folder and its file naming rules. +- `ai-plans/AGENTS.md`, describing the folder, its file naming rules, and how Frozen Plans are treated. The outcome must be idempotent. Running this skill on a repository sets the artifacts up from scratch, brings outdated ones up to date, or leaves current ones untouched. Content unrelated to Guided Coding, such as project-specific instructions or user-authored notes, is never changed. @@ -36,9 +36,7 @@ Create `AGENTS.md` in the repository root if it does not exist. Otherwise, make Ensure it contains: 1. `## Feedback Loops`: each command and what it verifies. Report to the user when no feedback loops could be found, and warn that `guided-coding-write-plan` refuses to write plans until at least one is listed. -2. `## Guided Coding`: a link to `ai-plans/AGENTS.md`, and the rules for implementing a Frozen Plan: - - plans in `ai-plans/` are frozen once they carry a timestamp in their file name and a `*Frozen at ...*` line below their title. - - the only permitted edit to a Frozen Plan is checking an Acceptance Criterion from `- [ ]` to `- [x]` after the implementation and the relevant feedback loops verify it. Unmet criteria stay unchecked. +2. `## Guided Coding`: a link to `ai-plans/AGENTS.md`, noting that it holds the file naming conventions and the rules for working with Frozen Plans. Do not restate those rules here; they live next to the plans they govern, and agents pick them up when they read the folder. If both sections already exist and are current, leave the file alone. From 4cbe1f496b43fc51ed44d723194046c2ab92c8c6 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sun, 20 Sep 2026 19:58:50 +0200 Subject: [PATCH 05/26] refactor: rename learning skills to implement-show-me and implement-coach-me Rename `guided-coding-implement-and-learn-by-example` to `guided-coding-implement-show-me` and `guided-coding-implement-and-learn-by-solving` to `guided-coding-implement-coach-me`. The previous names described the mechanism rather than the choice a user has to make, and were too long to type as slash commands. The new names sit alongside `guided-coding-implement` so the three paths through the Implementing Phase read as one family. Align both skills with `guided-coding-implement`: same target selection, same frozen plan verification, and no restated reading list. Add `guided-coding-implement` to the portable and Claude skill name lists in PackageValidationTests, which were missed when the skill was introduced, and to the README skill table. Regenerate the Claude adapter. Co-Authored-By: Claude Opus 5 --- README.md | 5 +++-- .../SKILL.md | 19 +++++------------ .../SKILL.md | 21 ++++++------------- claude-plugin/claude-skills/setup/SKILL.md | 8 +++---- .../agents/openai.yaml | 7 ------- .../agents/openai.yaml | 7 ------- .../SKILL.md | 19 +++++------------ .../agents/openai.yaml | 7 +++++++ .../SKILL.md | 21 ++++++------------- .../agents/openai.yaml | 7 +++++++ .../PackageValidationTests.cs | 10 +++++---- .../claude-skills.json | 8 +++---- 12 files changed, 52 insertions(+), 87 deletions(-) rename claude-plugin/claude-skills/{implement-and-learn-by-solving => implement-coach-me}/SKILL.md (84%) rename claude-plugin/claude-skills/{implement-and-learn-by-example => implement-show-me}/SKILL.md (80%) delete mode 100644 skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml delete mode 100644 skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml rename skills/{guided-coding-implement-and-learn-by-solving => guided-coding-implement-coach-me}/SKILL.md (83%) create mode 100644 skills/guided-coding-implement-coach-me/agents/openai.yaml rename skills/{guided-coding-implement-and-learn-by-example => guided-coding-implement-show-me}/SKILL.md (79%) create mode 100644 skills/guided-coding-implement-show-me/agents/openai.yaml diff --git a/README.md b/README.md index 7b92694..f38febc 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,9 @@ The full method is documented at | `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-freeze-plan` | Freeze a plan by timestamping its file name and title. | -| `guided-coding-implement-and-learn-by-example` | Implement a frozen plan through worked code examples that you enter and discuss. | -| `guided-coding-implement-and-learn-by-solving` | Implement a frozen plan yourself through coached, verifiable milestones. | +| `guided-coding-implement` | Implement a frozen plan and verify it through the repository's feedback loops. | +| `guided-coding-implement-show-me` | Implement a frozen plan through worked code examples that you enter and discuss. | +| `guided-coding-implement-coach-me` | Implement a frozen plan yourself through coached, verifiable milestones. | | `guided-coding-write-deviations` | Summarize follow-up plans and record material implementation differences. | All workflows require explicit user invocation. diff --git a/claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md similarity index 84% rename from claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md rename to claude-plugin/claude-skills/implement-coach-me/SKILL.md index 300fc7d..692561a 100644 --- a/claude-plugin/claude-skills/implement-and-learn-by-solving/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -1,6 +1,6 @@ --- -name: implement-and-learn-by-solving -description: "Guide a user through implementing a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without writing the implementation. Run only when explicitly requested by the user." +name: implement-coach-me +description: "Coach a user how to implement a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without describing the complete implementation. Run only when explicitly requested by the user." license: "MIT" disable-model-invocation: true --- @@ -13,18 +13,9 @@ Remain read-only. Do not edit repository files, check Acceptance Criteria, creat ## 1. Establish the Target -Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. -Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. - -Read: - -- applicable repository instructions and documented feedback loops; -- the target plan and every earlier plan for the same ticket that it refers to or supersedes; -- the relevant implementation and tests; and -- the current git status and diff, including the user's existing changes. - -Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. ## 2. Create the Milestone Roadmap @@ -73,7 +64,7 @@ When the user is stuck, provide one additional aid at a time: 4. Provide pseudocode or an API-level outline. 5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. -After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-and-learn-by-example` rather than changing this workflow's contract. +After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-show-me` rather than changing this workflow's contract. Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. diff --git a/claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md similarity index 80% rename from claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md rename to claude-plugin/claude-skills/implement-show-me/SKILL.md index 969a56b..32e518a 100644 --- a/claude-plugin/claude-skills/implement-and-learn-by-example/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -1,6 +1,6 @@ --- -name: implement-and-learn-by-example -description: "Guide a user through implementing a Frozen Guided Coding Plan by presenting and explaining complete code for one milestone at a time for the user to enter and examine. Run only when explicitly requested by the user." +name: implement-show-me +description: "Instruct a user how to implement a Frozen Guided Coding Plan by presenting and explaining complete code. Run only when explicitly requested by the user." license: "MIT" disable-model-invocation: true --- @@ -13,22 +13,13 @@ Remain read-only. Do not edit repository files, check Acceptance Criteria, creat ## 1. Establish the Target -Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. -Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. - -Read: - -- applicable repository instructions and documented feedback loops; -- the target plan and every earlier plan for the same ticket that it refers to or supersedes; -- the relevant implementation and tests; and -- the current git status and diff, including the user's existing changes. - -Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. ## 2. Create the Milestone Roadmap -Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. +Break the implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. Each milestone should: @@ -65,7 +56,7 @@ After the user enters the code: - explain any discrepancy and provide a corrected fragment when needed; and - run the relevant feedback loops, or review their output when the user ran them. -Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-and-learn-by-solving`. +Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-coach-me`. ## 5. Handle Plan Issues During Implementation diff --git a/claude-plugin/claude-skills/setup/SKILL.md b/claude-plugin/claude-skills/setup/SKILL.md index ea639cb..75f132c 100644 --- a/claude-plugin/claude-skills/setup/SKILL.md +++ b/claude-plugin/claude-skills/setup/SKILL.md @@ -11,9 +11,9 @@ Your goal is to set up or upgrade Guided Coding in the current repository. After Guided Coding needs these artifacts: -- `AGENTS.md` at the repository root, listing the feedback loops and the rules for implementing a Frozen Plan. +- `AGENTS.md` at the repository root, listing the feedback loops and pointing to `ai-plans/AGENTS.md`. - `ai-plans/`, the folder holding all plans and Plan Deviations documents. -- `ai-plans/AGENTS.md`, describing the folder and its file naming rules. +- `ai-plans/AGENTS.md`, describing the folder, its file naming rules, and how Frozen Plans are treated. The outcome must be idempotent. Running this skill on a repository sets the artifacts up from scratch, brings outdated ones up to date, or leaves current ones untouched. Content unrelated to Guided Coding, such as project-specific instructions or user-authored notes, is never changed. @@ -37,9 +37,7 @@ Create `AGENTS.md` in the repository root if it does not exist. Otherwise, make Ensure it contains: 1. `## Feedback Loops`: each command and what it verifies. Report to the user when no feedback loops could be found, and warn that `guided-coding-write-plan` refuses to write plans until at least one is listed. -2. `## Guided Coding`: a link to `ai-plans/AGENTS.md`, and the rules for implementing a Frozen Plan: - - plans in `ai-plans/` are frozen once they carry a timestamp in their file name and a `*Frozen at ...*` line below their title. - - the only permitted edit to a Frozen Plan is checking an Acceptance Criterion from `- [ ]` to `- [x]` after the implementation and the relevant feedback loops verify it. Unmet criteria stay unchecked. +2. `## Guided Coding`: a link to `ai-plans/AGENTS.md`, noting that it holds the file naming conventions and the rules for working with Frozen Plans. Do not restate those rules here; they live next to the plans they govern, and agents pick them up when they read the folder. If both sections already exist and are current, leave the file alone. diff --git a/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml b/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml deleted file mode 100644 index 2bc8a1d..0000000 --- a/skills/guided-coding-implement-and-learn-by-example/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Implement and Learn by Example" - short_description: "Learn implementation through worked examples" - default_prompt: "Use $guided-coding-implement-and-learn-by-example to help me implement the Frozen Plan through worked code examples that I enter and discuss." - -policy: - allow_implicit_invocation: false diff --git a/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml b/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml deleted file mode 100644 index fca07bf..0000000 --- a/skills/guided-coding-implement-and-learn-by-solving/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Implement and Learn by Solving" - short_description: "Solve implementation milestones with coaching" - default_prompt: "Use $guided-coding-implement-and-learn-by-solving to help me implement the Frozen Plan by solving each milestone myself." - -policy: - allow_implicit_invocation: false diff --git a/skills/guided-coding-implement-and-learn-by-solving/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md similarity index 83% rename from skills/guided-coding-implement-and-learn-by-solving/SKILL.md rename to skills/guided-coding-implement-coach-me/SKILL.md index 31b9ce9..c705132 100644 --- a/skills/guided-coding-implement-and-learn-by-solving/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -1,6 +1,6 @@ --- -name: guided-coding-implement-and-learn-by-solving -description: Guide a user through implementing a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without writing the implementation. Run only when explicitly requested by the user. +name: guided-coding-implement-coach-me +description: Coach a user how to implement a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without describing the complete implementation. Run only when explicitly requested by the user. license: MIT --- @@ -12,18 +12,9 @@ Remain read-only. Do not edit repository files, check Acceptance Criteria, creat ## 1. Establish the Target -Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. -Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. - -Read: - -- applicable repository instructions and documented feedback loops; -- the target plan and every earlier plan for the same ticket that it refers to or supersedes; -- the relevant implementation and tests; and -- the current git status and diff, including the user's existing changes. - -Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. ## 2. Create the Milestone Roadmap @@ -72,7 +63,7 @@ When the user is stuck, provide one additional aid at a time: 4. Provide pseudocode or an API-level outline. 5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. -After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-and-learn-by-example` rather than changing this workflow's contract. +After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-show-me` rather than changing this workflow's contract. Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. diff --git a/skills/guided-coding-implement-coach-me/agents/openai.yaml b/skills/guided-coding-implement-coach-me/agents/openai.yaml new file mode 100644 index 0000000..e7a08d2 --- /dev/null +++ b/skills/guided-coding-implement-coach-me/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Coach Me Through a Guided Coding Plan" + short_description: "Solve each milestone yourself with coaching" + default_prompt: "Use $guided-coding-implement-coach-me to coach me through implementing the Frozen Plan by solving each milestone myself." + +policy: + allow_implicit_invocation: false diff --git a/skills/guided-coding-implement-and-learn-by-example/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md similarity index 79% rename from skills/guided-coding-implement-and-learn-by-example/SKILL.md rename to skills/guided-coding-implement-show-me/SKILL.md index 98ef41a..3fb5361 100644 --- a/skills/guided-coding-implement-and-learn-by-example/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -1,6 +1,6 @@ --- -name: guided-coding-implement-and-learn-by-example -description: Guide a user through implementing a Frozen Guided Coding Plan by presenting and explaining complete code for one milestone at a time for the user to enter and examine. Run only when explicitly requested by the user. +name: guided-coding-implement-show-me +description: Instruct a user how to implement a Frozen Guided Coding Plan by presenting and explaining complete code. Run only when explicitly requested by the user. license: MIT --- @@ -12,22 +12,13 @@ Remain read-only. Do not edit repository files, check Acceptance Criteria, creat ## 1. Establish the Target -Use the plan named by the user. If none is named, proceed only when exactly one Frozen Plan with incomplete Acceptance Criteria can be identified in `ai-plans/`; otherwise ask for its path. +Use the plan named by the user. If none is named, proceed only when there is exactly one plan in `ai-plans/` that has all its Acceptance Criteria unchecked, and it has the latest timestamp of all plans. Otherwise, ask for its path. -Verify that the plan is frozen: its file name carries a timestamp and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. - -Read: - -- applicable repository instructions and documented feedback loops; -- the target plan and every earlier plan for the same ticket that it refers to or supersedes; -- the relevant implementation and tests; and -- the current git status and diff, including the user's existing changes. - -Treat later plans as superseding only the decisions they explicitly replace. Preserve all existing changes. +Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. ## 2. Create the Milestone Roadmap -Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. +Break the implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. Each milestone should: @@ -64,7 +55,7 @@ After the user enters the code: - explain any discrepancy and provide a corrected fragment when needed; and - run the relevant feedback loops, or review their output when the user ran them. -Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-and-learn-by-solving`. +Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-coach-me`. ## 5. Handle Plan Issues During Implementation diff --git a/skills/guided-coding-implement-show-me/agents/openai.yaml b/skills/guided-coding-implement-show-me/agents/openai.yaml new file mode 100644 index 0000000..e115b46 --- /dev/null +++ b/skills/guided-coding-implement-show-me/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Show Me How to Implement a Guided Coding Plan" + short_description: "Enter and discuss worked code, one milestone at a time" + default_prompt: "Use $guided-coding-implement-show-me to help me implement the Frozen Plan through worked code examples that I enter and discuss." + +policy: + allow_implicit_invocation: false diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index 0d1cc2d..4376882 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -16,8 +16,9 @@ public sealed class PackageValidationTests private static readonly string[] ExpectedPortableSkillNames = [ "guided-coding-freeze-plan", - "guided-coding-implement-and-learn-by-example", - "guided-coding-implement-and-learn-by-solving", + "guided-coding-implement", + "guided-coding-implement-coach-me", + "guided-coding-implement-show-me", "guided-coding-review-plan", "guided-coding-setup", "guided-coding-write-deviations", @@ -29,8 +30,9 @@ public sealed class PackageValidationTests ) { ["guided-coding-freeze-plan"] = "freeze-plan", - ["guided-coding-implement-and-learn-by-example"] = "implement-and-learn-by-example", - ["guided-coding-implement-and-learn-by-solving"] = "implement-and-learn-by-solving", + ["guided-coding-implement"] = "implement", + ["guided-coding-implement-coach-me"] = "implement-coach-me", + ["guided-coding-implement-show-me"] = "implement-show-me", ["guided-coding-review-plan"] = "review-plan", ["guided-coding-setup"] = "setup", ["guided-coding-write-deviations"] = "write-deviations", diff --git a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json index 965dd28..2b846eb 100644 --- a/tools/GuidedCoding.ClaudeGenerator/claude-skills.json +++ b/tools/GuidedCoding.ClaudeGenerator/claude-skills.json @@ -8,12 +8,12 @@ "name": "implement", "disableModelInvocation": true }, - "guided-coding-implement-and-learn-by-example": { - "name": "implement-and-learn-by-example", + "guided-coding-implement-coach-me": { + "name": "implement-coach-me", "disableModelInvocation": true }, - "guided-coding-implement-and-learn-by-solving": { - "name": "implement-and-learn-by-solving", + "guided-coding-implement-show-me": { + "name": "implement-show-me", "disableModelInvocation": true }, "guided-coding-review-plan": { From a521b74beafca95b10f52eddd13dfbf9364a7648 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Sun, 20 Sep 2026 20:25:38 +0200 Subject: [PATCH 06/26] test: guard the shared Establish the Target section against drift The three implement skills carry an identical `Establish the Target` section. Skills are standalone units, so the duplication is intended, but nothing kept the copies in sync. Compare the skills against each other rather than against an expected string, so that deliberate rewording passes once it is applied everywhere and only a one-sided edit fails. Sections are matched by heading text with the leading number stripped, because the numbering differs per skill. Co-Authored-By: Claude Opus 5 --- .../PackageValidationTests.cs | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index 4376882..c57b8fe 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -39,6 +39,15 @@ public sealed class PackageValidationTests ["guided-coding-write-plan"] = "write-plan" }; + private const string SharedTargetSection = "Establish the Target"; + + private static readonly string[] SkillsSharingTheTargetSection = + [ + "guided-coding-implement", + "guided-coding-implement-coach-me", + "guided-coding-implement-show-me" + ]; + private static readonly string[] ForbiddenFrontmatterFields = [ "allowed-tools", @@ -295,6 +304,33 @@ public void ClaudePluginContainsTheRepositoryLicense() ); } + [Fact] + public void SkillsSharingASectionKeepItIdentical() + { + var sections = SkillsSharingTheTargetSection + .Select( + skillName => ( + SkillName: skillName, + Body: ReadSectionBody( + Path.Combine(RepositoryRoot, "skills", skillName, "SKILL.md"), + SharedTargetSection + ) + ) + ) + .ToArray(); + var reference = sections[0]; + + foreach (var section in sections[1..]) + { + Assert.True( + string.Equals(reference.Body, section.Body, StringComparison.Ordinal), + $"\"{SharedTargetSection}\" differs between {reference.SkillName} and {section.SkillName}. " + + "The section is duplicated on purpose because skills are standalone; " + + "apply the change to every skill that shares it." + ); + } + } + private static string FindRepositoryRoot() { for ( @@ -403,6 +439,39 @@ private static string ParseBody(string content) return string.Join('\n', lines[(end + 1)..]); } + private static string ReadSectionBody(string path, string heading) + { + var lines = File.ReadAllText(path).Replace("\r\n", "\n", StringComparison.Ordinal).Split('\n'); + var start = Array.FindIndex(lines, line => IsSectionHeading(line, heading)); + Assert.True(start >= 0, $"\"{heading}\" is missing from {path}."); + + var end = Array.FindIndex( + lines, + start + 1, + line => line.StartsWith("## ", StringComparison.Ordinal) + ); + var body = end < 0 ? lines[(start + 1)..] : lines[(start + 1)..end]; + return string.Join('\n', body).Trim(); + } + + private static bool IsSectionHeading(string line, string heading) + { + if (!line.StartsWith("## ", StringComparison.Ordinal)) + { + return false; + } + + // Section numbers differ between skills, so match on the heading text alone. + var text = line[3..].Trim(); + var separator = text.IndexOf(". ", StringComparison.Ordinal); + if (separator > 0 && text[..separator].All(char.IsDigit)) + { + text = text[(separator + 2)..]; + } + + return string.Equals(text, heading, StringComparison.Ordinal); + } + private static SortedDictionary EnumerateResourceFiles( string root, bool excludeAgents From 77e21ac6d72f9732bb8444477c8935aa31f9dede Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Mon, 21 Sep 2026 06:23:13 +0200 Subject: [PATCH 07/26] fix: minor change of words in implement skill, section Handle Plan Issues Signed-off-by: Kenny Pflug --- claude-plugin/claude-skills/implement/SKILL.md | 2 +- skills/guided-coding-implement/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/claude-plugin/claude-skills/implement/SKILL.md b/claude-plugin/claude-skills/implement/SKILL.md index 1ddd8ff..ef44e10 100644 --- a/claude-plugin/claude-skills/implement/SKILL.md +++ b/claude-plugin/claude-skills/implement/SKILL.md @@ -23,7 +23,7 @@ The only allowed plan edit is ticking an Acceptance Criterion from `- [ ]` to `- ## 3. Handle Plan Issues -If an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. In the Guiding Phase, the reviewer can decide how to proceed with your findings. diff --git a/skills/guided-coding-implement/SKILL.md b/skills/guided-coding-implement/SKILL.md index c0a3b2b..23727ce 100644 --- a/skills/guided-coding-implement/SKILL.md +++ b/skills/guided-coding-implement/SKILL.md @@ -22,7 +22,7 @@ The only allowed plan edit is ticking an Acceptance Criterion from `- [ ]` to `- ## 3. Handle Plan Issues -If an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround, and report it. If a problem genuinely cannot be solved, that's totally fine - simply report it. In the Guiding Phase, the reviewer can decide how to proceed with your findings. From 772ca7d79a842396bb5743255629422f4ac58859 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Mon, 21 Sep 2026 06:52:47 +0200 Subject: [PATCH 08/26] feat: simplify implement-show-me skill Signed-off-by: Kenny Pflug --- .../claude-skills/implement-show-me/SKILL.md | 73 +++++-------------- .../guided-coding-implement-show-me/SKILL.md | 73 +++++-------------- 2 files changed, 38 insertions(+), 108 deletions(-) diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 32e518a..f77c175 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -1,15 +1,15 @@ --- name: implement-show-me -description: "Instruct a user how to implement a Frozen Guided Coding Plan by presenting and explaining complete code. Run only when explicitly requested by the user." +description: "Instruct a user how to implement a Guided Coding Frozen Plan by presenting and explaining complete code. Run only when explicitly requested by the user." license: "MIT" disable-model-invocation: true --- -# Implement and Learn by Example +# Show the User How to Implement a Frozen Plan -Your goal is to teach the user how to implement a Frozen Plan through repository-specific worked examples. You provide the complete code for one milestone at a time and explain it; the user enters the code, runs it, and asks questions. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by breaking it up into useful teachable milestones. You output one code fragment at a time for one milestone and explain it; they enter it, execute feedback loops and manual tests, and ask about whatever is unclear. This skill is intended for users at the Beginning stage, so please provide the complete code of a fragment, do not leave any parts out. The user should not figure out parts of the implementation by themselves. -Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. +Let the user make every change to the repository themselves. Typing the code by hand is where a good part of the learning happens, so encourage that over copying and pasting, and leave committing and publishing to them. ## 1. Establish the Target @@ -19,67 +19,32 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Create the Milestone Roadmap -Break the implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. +Break the plan into milestones and present them as a short roadmap, not showing any code yet. -Each milestone should: +A good milestone depends on the size of the plan: you could use file-by-file for smaller plans, or break the work into vertical slices if the plan is larger. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -- produce one observable behavior or establish one internal invariant; -- introduce one primary mechanism or a tightly related concept cluster; -- include the tests or other verification that make it independently demonstrable; and -- have a completion condition that can be stated in one sentence. +It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. -Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, the user should usually be able to enter, study, and verify one example in 10–30 minutes. Split a milestone when its code or explanation contains multiple independently teachable concepts or verification points. +## 3. How to Work Through a Single Milestone -## 3. Present One Worked Example +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. -For the current milestone, provide: +Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. -1. **Outcome:** What the example adds and how the user will observe it. -2. **Placement:** The exact files and locations where each fragment belongs. -3. **Code:** Complete, repository-specific code for this milestone, including tests when they are part of the same coherent example. -4. **Explanation:** What the code does, how its pieces interact, and every language or framework mechanism likely to be new to the user. -5. **Reasoning:** Why this implementation fits the Frozen Plan and the surrounding architecture. Discuss alternatives only when they clarify an important decision. -6. **Verification:** The exact feedback-loop command or manual check, plus the expected result. +After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. -Providing the code is the purpose of this workflow; do not replace it with hints or pseudocode. At the same time, do not provide later milestones or combine fragments into a solution for the entire plan. +The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). -Do not apply the code yourself. After presenting the example, stop so the user can enter it, inspect it, run it, and ask questions. +Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]` and move to the next milestone or finish the Implementing Phase. -## 4. Discuss and Verify the Example +## 4. Handle Plan Issues -Answer the user's questions directly and remain on the current milestone until they say they understand it and are ready to continue. Explain unfamiliar syntax when asked, but do not require a quiz or make the user restate every explanation. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. -After the user enters the code: +Ideally, you can catch this directly while you are creating the milestones for the plan, but you might also encounter an issue while the user is working through a milestone. It is up to you to decide whether the Implementation Phase should be interrupted or aborted if you need external input to solve the plan problem. -- inspect their actual changes before evaluating them; -- distinguish transcription or adaptation mistakes from errors in the example you supplied; -- explain any discrepancy and provide a corrected fragment when needed; and -- run the relevant feedback loops, or review their output when the user ran them. +In the Guiding Phase, the reviewer can decide how to proceed with your findings. -Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-coach-me`. +## 5. After the Last Milestone -## 5. Handle Plan Issues During Implementation - -Routine choices that the plans leave open may be resolved in the worked example. Explain consequential choices so the user can understand them. - -If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: - -- identify the exact decision or criterion and explain why it does not work; -- provide a recommended solution or workaround, including its trade-offs and repository-specific code when code is needed; -- clearly label the approach as provisional rather than silently treating it as a new plan decision; -- state which Acceptance Criteria the workaround satisfies and which remain unmet; and -- retain the issue and provisional approach for the final Guiding Phase handoff. - -Remain in the Implementing Phase and continue the worked-example workflow with the provisional approach. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. - -## 6. Finish the Learning Implementation - -After all milestones: - -- inspect the complete implementation diff; -- compare it with every Acceptance Criterion; -- run all applicable feedback loops and identify any required manual checks; and -- report which criteria are verified and which remain incomplete; and -- summarize every plan issue, its provisional solution or workaround, and its impact. - -Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 3fb5361..8fc88b1 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -1,14 +1,14 @@ --- name: guided-coding-implement-show-me -description: Instruct a user how to implement a Frozen Guided Coding Plan by presenting and explaining complete code. Run only when explicitly requested by the user. +description: Instruct a user how to implement a Guided Coding Frozen Plan by presenting and explaining complete code. Run only when explicitly requested by the user. license: MIT --- -# Implement and Learn by Example +# Show the User How to Implement a Frozen Plan -Your goal is to teach the user how to implement a Frozen Plan through repository-specific worked examples. You provide the complete code for one milestone at a time and explain it; the user enters the code, runs it, and asks questions. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by breaking it up into useful teachable milestones. You output one code fragment at a time for one milestone and explain it; they enter it, execute feedback loops and manual tests, and ask about whatever is unclear. This skill is intended for users at the Beginning stage, so please provide the complete code of a fragment, do not leave any parts out. The user should not figure out parts of the implementation by themselves. -Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. +Let the user make every change to the repository themselves. Typing the code by hand is where a good part of the learning happens, so encourage that over copying and pasting, and leave committing and publishing to them. ## 1. Establish the Target @@ -18,67 +18,32 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Create the Milestone Roadmap -Break the implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without revealing all the code up front, then start with the first incomplete milestone. +Break the plan into milestones and present them as a short roadmap, not showing any code yet. -Each milestone should: +A good milestone depends on the size of the plan: you could use file-by-file for smaller plans, or break the work into vertical slices if the plan is larger. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -- produce one observable behavior or establish one internal invariant; -- introduce one primary mechanism or a tightly related concept cluster; -- include the tests or other verification that make it independently demonstrable; and -- have a completion condition that can be stated in one sentence. +It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. -Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, the user should usually be able to enter, study, and verify one example in 10–30 minutes. Split a milestone when its code or explanation contains multiple independently teachable concepts or verification points. +## 3. How to Work Through a Single Milestone -## 3. Present One Worked Example +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. -For the current milestone, provide: +Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. -1. **Outcome:** What the example adds and how the user will observe it. -2. **Placement:** The exact files and locations where each fragment belongs. -3. **Code:** Complete, repository-specific code for this milestone, including tests when they are part of the same coherent example. -4. **Explanation:** What the code does, how its pieces interact, and every language or framework mechanism likely to be new to the user. -5. **Reasoning:** Why this implementation fits the Frozen Plan and the surrounding architecture. Discuss alternatives only when they clarify an important decision. -6. **Verification:** The exact feedback-loop command or manual check, plus the expected result. +After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. -Providing the code is the purpose of this workflow; do not replace it with hints or pseudocode. At the same time, do not provide later milestones or combine fragments into a solution for the entire plan. +The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). -Do not apply the code yourself. After presenting the example, stop so the user can enter it, inspect it, run it, and ask questions. +Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]` and move to the next milestone or finish the Implementing Phase. -## 4. Discuss and Verify the Example +## 4. Handle Plan Issues -Answer the user's questions directly and remain on the current milestone until they say they understand it and are ready to continue. Explain unfamiliar syntax when asked, but do not require a quiz or make the user restate every explanation. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. -After the user enters the code: +Ideally, you can catch this directly while you are creating the milestones for the plan, but you might also encounter an issue while the user is working through a milestone. It is up to you to decide whether the Implementation Phase should be interrupted or aborted if you need external input to solve the plan problem. -- inspect their actual changes before evaluating them; -- distinguish transcription or adaptation mistakes from errors in the example you supplied; -- explain any discrepancy and provide a corrected fragment when needed; and -- run the relevant feedback loops, or review their output when the user ran them. +In the Guiding Phase, the reviewer can decide how to proceed with your findings. -Advance only after the milestone behaves as described and its feedback loops pass. If the user wants to devise the solution rather than receive the next worked example, tell them they can explicitly switch to `guided-coding-implement-coach-me`. +## 5. After the Last Milestone -## 5. Handle Plan Issues During Implementation - -Routine choices that the plans leave open may be resolved in the worked example. Explain consequential choices so the user can understand them. - -If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: - -- identify the exact decision or criterion and explain why it does not work; -- provide a recommended solution or workaround, including its trade-offs and repository-specific code when code is needed; -- clearly label the approach as provisional rather than silently treating it as a new plan decision; -- state which Acceptance Criteria the workaround satisfies and which remain unmet; and -- retain the issue and provisional approach for the final Guiding Phase handoff. - -Remain in the Implementing Phase and continue the worked-example workflow with the provisional approach. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. - -## 6. Finish the Learning Implementation - -After all milestones: - -- inspect the complete implementation diff; -- compare it with every Acceptance Criterion; -- run all applicable feedback loops and identify any required manual checks; and -- report which criteria are verified and which remain incomplete; and -- summarize every plan issue, its provisional solution or workaround, and its impact. - -Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. From ed54a4f869023b6d9f5fd18979a75c8306a42c2e Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Mon, 21 Sep 2026 07:16:38 +0200 Subject: [PATCH 09/26] feat: rewrote implement-coach-me skill Signed-off-by: Kenny Pflug --- .../claude-skills/implement-coach-me/SKILL.md | 83 +++++-------------- .../guided-coding-implement-coach-me/SKILL.md | 83 +++++-------------- 2 files changed, 44 insertions(+), 122 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 692561a..33e9d53 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -1,15 +1,15 @@ --- name: implement-coach-me -description: "Coach a user how to implement a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without describing the complete implementation. Run only when explicitly requested by the user." +description: "Coach a user through implementing a Guided Coding Frozen Plan one milestone at a time, progressively revealing help when needed. Run only when explicitly requested by the user." license: "MIT" disable-model-invocation: true --- -# Implement and Learn by Solving +# Coach the User Through Implementing a Frozen Plan -Your goal is to coach the user through implementing a Frozen Plan themselves. You define one bounded problem at a time, explain its context, review the user's solution, and provide progressively stronger hints when needed. The user authors all implementation and test code. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. -Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. +Let the user make every change to the repository themselves. The implementation and tests are theirs to write, and committing and publishing are theirs to do. ## 1. Establish the Target @@ -19,77 +19,38 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Create the Milestone Roadmap -Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without disclosing their solutions, then start with the first incomplete milestone. +Break the plan into milestones and present them as a short roadmap without giving away their implementations. -Each milestone should: +A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -- produce one observable behavior or establish one internal invariant; -- require one meaningful implementation decision; -- include independently useful tests or other verification; and -- have a completion condition that can be stated in one sentence. +It is totally fine if the plan needs only one milestone. We trust your teaching expertise here. -Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, one milestone should usually fit into 20–60 minutes of focused work for the current user. Split it when it introduces multiple unfamiliar concepts, contains independent design decisions, or has more than one useful verification point. Combine steps that are merely mechanical and provide no meaningful feedback on their own. +## 3. How to Work Through a Single Milestone -## 3. Pose One Implementation Problem +When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. -For the current milestone, provide: +Be available as a teacher while they work. Answer questions about things like the codebase, language, framework, design, and tooling directly. Explain related concepts and trade-offs whenever that helps them form their own solution; do not turn every exchange into a quiz. -1. **Outcome:** What must be true when the milestone is complete. -2. **Why:** How the milestone contributes to the plan and what the user can learn from it. -3. **Starting points:** Existing files, types, tests, documentation, or patterns worth inspecting. -4. **Constraints:** Relevant decisions and invariants from the Frozen Plans. -5. **Concepts:** New patterns, principles, APIs, or tooling worth investigating, without applying them to produce the solution. -6. **Verification:** The exact feedback-loop command or manual check and its expected result. +When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. -Do not suggest a complete implementation approach or provide repository-ready code at this point. Stop and let the user design and implement the solution. +Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan and move to the next milestone or finish the Implementing Phase. -## 4. Review the User's Solution +## 4. Reveal Help Progressively -When the user returns, inspect their actual changes before evaluating them. Explain specifically: +Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. When they ask for help or appear stuck, reveal one useful piece of information at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. -- what is correct and why; -- what does not yet satisfy the milestone or plan; -- which design, correctness, testing, or maintainability concerns remain; and -- what the user should reconsider next without supplying the finished code. +Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. -Accept valid approaches that differ from the one you anticipated. Let the user revise their solution, then run the relevant feedback loops or review the output they provide. Advance only after the milestone's outcome is satisfied and verified. +Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. -## 5. Provide Progressive Hints +## 5. Handle Plan Issues -When the user is stuck, provide one additional aid at a time: +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. -1. Ask a focused diagnostic question or restate the relevant invariant. -2. Point to an analogous part of the repository or relevant documentation. -3. Explain the missing language, framework, design, or tooling mechanism and its trade-offs. -4. Provide pseudocode or an API-level outline. -5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. +Ideally, you can catch this while creating the milestones, but you might also encounter an issue while the user works through one. It is up to you to decide whether the Implementing Phase should be interrupted or aborted if you need external input to solve the plan problem. -After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-show-me` rather than changing this workflow's contract. +In the Guiding Phase, the reviewer can decide how to proceed with your findings. -Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. +## 6. After the Last Milestone -## 6. Handle Plan Issues During Implementation - -Routine choices that the plans leave open belong to the user. Explain relevant trade-offs without inventing new requirements. - -If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: - -- identify the exact decision or criterion and explain why it does not work; -- recommend a solution or workaround and explain its trade-offs; -- clearly label the approach as provisional rather than silently treating it as a new plan decision; -- state which Acceptance Criteria the workaround satisfies and which remain unmet; and -- retain the issue and provisional approach for the final Guiding Phase handoff. - -Continue the problem-solving workflow using the provisional approach. Describe the workaround precisely enough for the user to implement it, while preserving this skill's rule that the user authors the code. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. - -## 7. Finish the Learning Implementation - -After all milestones: - -- inspect the complete implementation diff; -- compare it with every Acceptance Criterion; -- run all applicable feedback loops and identify any required manual checks; and -- report which criteria are verified and which remain incomplete; and -- summarize every plan issue, its provisional solution or workaround, and its impact. - -Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index c705132..1c3d139 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -1,14 +1,14 @@ --- name: guided-coding-implement-coach-me -description: Coach a user how to implement a Frozen Guided Coding Plan by giving them one problem at a time, reviewing their solution, and offering progressive hints without describing the complete implementation. Run only when explicitly requested by the user. +description: Coach a user through implementing a Guided Coding Frozen Plan one milestone at a time, progressively revealing help when needed. Run only when explicitly requested by the user. license: MIT --- -# Implement and Learn by Solving +# Coach the User Through Implementing a Frozen Plan -Your goal is to coach the user through implementing a Frozen Plan themselves. You define one bounded problem at a time, explain its context, review the user's solution, and provide progressively stronger hints when needed. The user authors all implementation and test code. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. -Remain read-only. Do not edit repository files, check Acceptance Criteria, create commits, or publish anything. +Let the user make every change to the repository themselves. The implementation and tests are theirs to write, and committing and publishing are theirs to do. ## 1. Establish the Target @@ -18,77 +18,38 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Create the Milestone Roadmap -Break the remaining implementation into dependency-ordered milestones. Present a concise roadmap of outcomes without disclosing their solutions, then start with the first incomplete milestone. +Break the plan into milestones and present them as a short roadmap without giving away their implementations. -Each milestone should: +A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -- produce one observable behavior or establish one internal invariant; -- require one meaningful implementation decision; -- include independently useful tests or other verification; and -- have a completion condition that can be stated in one sentence. +It is totally fine if the plan needs only one milestone. We trust your teaching expertise here. -Prefer coherent behavioral slices over divisions by file, layer, or line count. As a rough pacing signal, one milestone should usually fit into 20–60 minutes of focused work for the current user. Split it when it introduces multiple unfamiliar concepts, contains independent design decisions, or has more than one useful verification point. Combine steps that are merely mechanical and provide no meaningful feedback on their own. +## 3. How to Work Through a Single Milestone -## 3. Pose One Implementation Problem +When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. -For the current milestone, provide: +Be available as a teacher while they work. Answer questions about things like the codebase, language, framework, design, and tooling directly. Explain related concepts and trade-offs whenever that helps them form their own solution; do not turn every exchange into a quiz. -1. **Outcome:** What must be true when the milestone is complete. -2. **Why:** How the milestone contributes to the plan and what the user can learn from it. -3. **Starting points:** Existing files, types, tests, documentation, or patterns worth inspecting. -4. **Constraints:** Relevant decisions and invariants from the Frozen Plans. -5. **Concepts:** New patterns, principles, APIs, or tooling worth investigating, without applying them to produce the solution. -6. **Verification:** The exact feedback-loop command or manual check and its expected result. +When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. -Do not suggest a complete implementation approach or provide repository-ready code at this point. Stop and let the user design and implement the solution. +Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan and move to the next milestone or finish the Implementing Phase. -## 4. Review the User's Solution +## 4. Reveal Help Progressively -When the user returns, inspect their actual changes before evaluating them. Explain specifically: +Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. When they ask for help or appear stuck, reveal one useful piece of information at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. -- what is correct and why; -- what does not yet satisfy the milestone or plan; -- which design, correctness, testing, or maintainability concerns remain; and -- what the user should reconsider next without supplying the finished code. +Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. -Accept valid approaches that differ from the one you anticipated. Let the user revise their solution, then run the relevant feedback loops or review the output they provide. Advance only after the milestone's outcome is satisfied and verified. +Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. -## 5. Provide Progressive Hints +## 5. Handle Plan Issues -When the user is stuck, provide one additional aid at a time: +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. -1. Ask a focused diagnostic question or restate the relevant invariant. -2. Point to an analogous part of the repository or relevant documentation. -3. Explain the missing language, framework, design, or tooling mechanism and its trade-offs. -4. Provide pseudocode or an API-level outline. -5. Show a small code fragment only when it demonstrates incidental syntax rather than the decision or mechanism the user is trying to learn. +Ideally, you can catch this while creating the milestones, but you might also encounter an issue while the user works through one. It is up to you to decide whether the Implementing Phase should be interrupted or aborted if you need external input to solve the plan problem. -After each hint, let the user try again. Never provide the complete implementation of a milestone, a patch, or a sequence of fragments that collectively reveals the solution. If the user wants a complete worked example, tell them to explicitly switch to `guided-coding-implement-show-me` rather than changing this workflow's contract. +In the Guiding Phase, the reviewer can decide how to proceed with your findings. -Answer direct conceptual questions directly. Do not turn every exchange into a quiz or withhold basic facts merely to make the user discover them. +## 6. After the Last Milestone -## 6. Handle Plan Issues During Implementation - -Routine choices that the plans leave open belong to the user. Explain relevant trade-offs without inventing new requirements. - -If implementation reveals that an explicit plan decision is wrong or an Acceptance Criterion cannot be met as written: - -- identify the exact decision or criterion and explain why it does not work; -- recommend a solution or workaround and explain its trade-offs; -- clearly label the approach as provisional rather than silently treating it as a new plan decision; -- state which Acceptance Criteria the workaround satisfies and which remain unmet; and -- retain the issue and provisional approach for the final Guiding Phase handoff. - -Continue the problem-solving workflow using the provisional approach. Describe the workaround precisely enough for the user to implement it, while preserving this skill's rule that the user authors the code. Do not edit the Frozen Plan or decide whether the departure is accepted. In the Guiding Phase, a senior developer reviews the complete implementation and decides whether to accept the difference and record it in a Plan Deviations document, or return to the Planning Phase and write a Follow-Up Plan. - -## 7. Finish the Learning Implementation - -After all milestones: - -- inspect the complete implementation diff; -- compare it with every Acceptance Criterion; -- run all applicable feedback loops and identify any required manual checks; and -- report which criteria are verified and which remain incomplete; and -- summarize every plan issue, its provisional solution or workaround, and its impact. - -Do not check the criteria yourself or claim that an unmet criterion is satisfied. The implementation pass is ready for the Guiding Phase when its milestones and applicable feedback loops are complete, even when a known plan issue leaves a criterion unmet. State clearly that the senior review must decide whether each provisional departure becomes a Plan Deviation or requires a return to the Planning Phase. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. From cb2454d11fa0d293299328ed1d9d0a8929dd75f6 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Tue, 22 Sep 2026 06:26:34 +0200 Subject: [PATCH 10/26] docs: refine implement-coach-me guidance --- claude-plugin/claude-skills/implement-coach-me/SKILL.md | 4 ++-- skills/guided-coding-implement-coach-me/SKILL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 33e9d53..ce871ee 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -9,7 +9,7 @@ disable-model-invocation: true Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. -Let the user make every change to the repository themselves. The implementation and tests are theirs to write, and committing and publishing are theirs to do. +Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. ## 1. Establish the Target @@ -23,7 +23,7 @@ Break the plan into milestones and present them as a short roadmap without givin A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -It is totally fine if the plan needs only one milestone. We trust your teaching expertise here. +It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. ## 3. How to Work Through a Single Milestone diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index 1c3d139..90e605f 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -8,7 +8,7 @@ license: MIT Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. -Let the user make every change to the repository themselves. The implementation and tests are theirs to write, and committing and publishing are theirs to do. +Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. ## 1. Establish the Target @@ -22,7 +22,7 @@ Break the plan into milestones and present them as a short roadmap without givin A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. -It is totally fine if the plan needs only one milestone. We trust your teaching expertise here. +It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. ## 3. How to Work Through a Single Milestone From fae8bb2ca2a7f16a6b6cc2dde27a1a4f2ceb51bb Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Tue, 22 Sep 2026 06:32:39 +0200 Subject: [PATCH 11/26] chore: remove trailing whitespace in show-me skill Signed-off-by: Kenny Pflug --- skills/guided-coding-implement-show-me/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 8fc88b1..cbeaede 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -26,7 +26,7 @@ It is totally fine if you break up a plan into a single milestone. We trust your ## 3. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. From 49cefa9648deda91f20bf21e564d56ca1c9379c1 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Tue, 22 Sep 2026 06:34:01 +0200 Subject: [PATCH 12/26] feat: slight adjustments regarding wording for the coach-me skill Signed-off-by: Kenny Pflug --- skills/guided-coding-implement-coach-me/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index 90e605f..4919d78 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -6,7 +6,7 @@ license: MIT # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advanced stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. From 7211482df2d14ebeb936342bad05d232ee05c9db Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Tue, 22 Sep 2026 06:47:59 +0200 Subject: [PATCH 13/26] docs: clarify progressive coach guidance --- claude-plugin/claude-skills/implement-coach-me/SKILL.md | 4 ++-- claude-plugin/claude-skills/implement-show-me/SKILL.md | 2 +- skills/guided-coding-implement-coach-me/SKILL.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index ce871ee..b6476db 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users with advanced knowledge: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advanced stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. @@ -37,7 +37,7 @@ Then instruct the user how to run the applicable feedback loops and manual tests ## 4. Reveal Help Progressively -Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. When they ask for help or appear stuck, reveal one useful piece of information at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. +Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index f77c175..acb5a80 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -27,7 +27,7 @@ It is totally fine if you break up a plan into a single milestone. We trust your ## 3. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index 4919d78..a364a97 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -36,7 +36,7 @@ Then instruct the user how to run the applicable feedback loops and manual tests ## 4. Reveal Help Progressively -Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. When they ask for help or appear stuck, reveal one useful piece of information at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. +Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. From 742a12dedecfc95afc195fad828b65f344b69530 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Wed, 23 Sep 2026 07:50:33 +0200 Subject: [PATCH 14/26] feat: track learning progress in a Guided Learning profile The show-me and coach-me skills now read ~/.guided-learning/profile.md before creating the milestone roadmap and update it after each milestone. Both skills ship an empty profile template as an asset, which also carries the agent's rules for reading and maintaining the file. Show-me builds its roadmap layer by layer, coach-me from vertical slices, and every milestone includes its tests. Tests keep the shared profile sections and the duplicated templates identical across both skills. Co-Authored-By: Claude Opus 5.5 --- .../claude-skills/implement-coach-me/SKILL.md | 40 +++- .../implement-coach-me/assets/profile.md | 172 ++++++++++++++++++ .../claude-skills/implement-show-me/SKILL.md | 34 +++- .../implement-show-me/assets/profile.md | 172 ++++++++++++++++++ .../guided-coding-implement-coach-me/SKILL.md | 40 +++- .../assets/profile.md | 172 ++++++++++++++++++ .../guided-coding-implement-show-me/SKILL.md | 34 +++- .../assets/profile.md | 172 ++++++++++++++++++ .../PackageValidationTests.cs | 54 +++++- 9 files changed, 847 insertions(+), 43 deletions(-) create mode 100644 claude-plugin/claude-skills/implement-coach-me/assets/profile.md create mode 100644 claude-plugin/claude-skills/implement-show-me/assets/profile.md create mode 100644 skills/guided-coding-implement-coach-me/assets/profile.md create mode 100644 skills/guided-coding-implement-show-me/assets/profile.md diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index b6476db..ca0f42b 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advanced stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advancing stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. @@ -17,15 +17,27 @@ Use the plan named by the user. If none is named, proceed only when there is exa Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. -## 2. Create the Milestone Roadmap +## 2. Read the Learning Profile + +The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. + +Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. + +If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. + +Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. + +## 3. Create the Milestone Roadmap Break the plan into milestones and present them as a short roadmap without giving away their implementations. -A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. +Build the roadmap from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas - what they practice is fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. + +A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. The user writes the milestone's tests as part of it - they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. -## 3. How to Work Through a Single Milestone +## 4. How to Work Through a Single Milestone When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. @@ -33,17 +45,25 @@ Be available as a teacher while they work. Answer questions about things like th When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. -Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan and move to the next milestone or finish the Implementing Phase. +Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan. Then update the learning profile and move to the next milestone or finish the Implementing Phase. -## 4. Reveal Help Progressively +## 5. Reveal Help Progressively Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. -Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. +Start at the level that fits the situation and the user's stage in the area at hand, rather than mechanically beginning with a question. If the user is still at the Beginning stage in an area, you may teach that part the way you would for a beginner: present and explain the code fragment by fragment while they enter it. This is the one exception to the rule below about providing code. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. -## 5. Handle Plan Issues +## 6. Update the Learning Profile + +Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. + +Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. + +Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. + +## 7. Handle Plan Issues If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. @@ -51,6 +71,6 @@ Ideally, you can catch this while creating the milestones, but you might also en In the Guiding Phase, the reviewer can decide how to proceed with your findings. -## 6. After the Last Milestone +## 8. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/claude-plugin/claude-skills/implement-coach-me/assets/profile.md b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md new file mode 100644 index 0000000..57c37a7 --- /dev/null +++ b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md @@ -0,0 +1,172 @@ +# Guided Learning Profile + +*Updated YYYY-MM-DDTHH:mmZ* + +This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning +aid, not a performance record, and it is not shared, committed to a project repository, or pushed to +a public remote. I can edit or delete anything in it at any time. The last section is written for +the coding agent that maintains it. + +## Goals + +*No entries yet.* + +## Preferences + +*No entries yet.* + +## Carry Forward + +*No entries yet.* + +## Knowledge + +*No entries yet.* + +## Recurring Themes + +*No entries yet.* + +## For the Agent Reading This + +### Stages + +Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: + +- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. +- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. +- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals + themselves. + +### Reading This File + +- Use it to choose an opening: how large the milestones are, how much to explain, and how much help + to offer at the start. What happens in the session overrides this file - record what you observe, + not what you expected. +- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan + deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up + the carry-forward items that apply to the plan. +- **The most specific node wins.** A node's stage applies to everything beneath it except where a + child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the + tree when there is none. The `covers` list of a node tells you which things it includes without + a node of their own. +- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. +- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record + in `records/`, which holds the detail behind it. Read a record only when the node itself is not + enough. +- This file says what I have done and when. It is not a list of things I cannot do. + +### When to Update This File + +After each milestone, once I committed it, and once more when the pass ends - after the last +milestone, or earlier when I stop. Never in the middle of a milestone. + +- **After a milestone:** append the milestone's section to the record, update the nodes it touched, + and add or remove carry-forward items. +- **When the pass ends:** append the outcome to the record and update the recurring themes. + +Ask me once per session whether you may keep this file up to date; if I agree, write each update +without asking again, but show me what you changed. Re-read this file right before each write and +apply your changes to what is there - I or another session may have changed it since you last read +it. If this folder is a git repository, commit each update with a message that names the record. +Replace a `*No entries yet.*` placeholder once its section has content. + +All dates and times in this file and in `records/` are UTC. Take them from the command line rather +than guessing them: + +- `date -u +%FT%H:%MZ` on Unix-based shells +- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell + +This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it +when you change this file. Node dates use only its date part, `2026-09-17`, and record file names +use it as `2026-09-17-0231`. + +### Records + +One file per implementation pass in `records/`, named `--.md` +with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - +never edit what is already there: + +- **Header**, written with the file: the plan's title, the time the pass started, the repository, + the plan's path, the skill that ran, and the number of milestones in the roadmap. +- **One section per milestone**, appended after it: which areas it touched and how each went, where + the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before + running the feedback loops was right, and which questions I asked. +- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were + ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a + pass that is still running or was abandoned. + +Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it +clicked" is useful, "intermediate at TypeScript" is not. + +### Goals and Preferences + +Both are mine to state. Goals are what I want to get better at; preferences are how I like to be +taught - for example, explanation before code, the language to use, or how direct hints should be. +Add an entry only when I told you about it in the session, and reword or remove one only when I ask. + +### Carry Forward + +Short, actionable items for future passes, each naming the record it came from, for example +"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record +you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the +list short; if an item stays untouched for six months, propose removing it. + +### Nodes + +Write each node as a list item, nesting children beneath their parent: + +```markdown +- **** `` · · — covers , +``` + +A node is a body of knowledge a Frozen Plan draws on. Roots are +either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, +such as `Software design and architecture` or `Automated testing`. Check the tree before adding +anything: if the new thing fits inside an existing node, reuse it. + +Nest at most three levels deep - for a technology root, for example platform, technology, area: +`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. +When it would agree, list it in the parent's `covers` instead: the list records what a node includes +without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is +optional when the name says enough. A child that agrees with its parent is noise, so fold it into +the parent's `covers`. Anything finer belongs in a record. + +When a pass touches a node without changing its stage, still update its date and evidence, so that +the decay rule stays meaningful. + +### Stage Changes + +A stage moves for one of two reasons: + +- **Promotion**, because I grew into it: one step per pass, and only on something you observed. + Beginning to Advancing means I carried a milestone in that area without needing the implementation + handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's + approach for a reason that held up. +- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node + that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that + a record backs is worth a sentence in the new record explaining what changed your mind. + +A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the +implementation, so it cannot show that I would manage without. If I seem further along than +Beginning, say so, suggest `coach-me`, and note it in the record. + +Record the change on the node where you saw it. Evidence about structural typing moves that node, +not everything above it. Before you move a parent, check whether your evidence covers the whole +area: everything in its `covers` list and every area without a node of its own moves with it. If +the evidence covers only part of it, add a child for that part instead. + +### Recurring Themes + +A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach +for and whether they help. Mark each theme `candidate` or `established`, and name the records it was +seen in: + +```markdown +- **** `` - . Seen in: ``, ``. +``` + +Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` +when a later pass shows it again, and remove it when later passes contradict it. You only need the +current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most +five themes; when a sixth would be added, propose which one to drop. diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index acb5a80..5254ec4 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -17,15 +17,27 @@ Use the plan named by the user. If none is named, proceed only when there is exa Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. -## 2. Create the Milestone Roadmap +## 2. Read the Learning Profile + +The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. + +Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. + +If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. + +Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. + +## 3. Create the Milestone Roadmap Break the plan into milestones and present them as a short roadmap, not showing any code yet. -A good milestone depends on the size of the plan: you could use file-by-file for smaller plans, or break the work into vertical slices if the plan is larger. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. +Build the roadmap layer by layer, so that each milestone puts one area in focus and builds upon the previous ones. For a backend feature, this could be the domain model first, then database access, followed by a service, and finally the endpoint. This way, the user can take in the concepts of one area at a time. Because nothing runs end-to-end before the last layer is in place, explain in the roadmap how the layers will connect in the end, and remind the user where the current layer sits in that picture whenever a milestone begins. If the plan has no layers, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. + +A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. This includes the milestone's tests - they are part of the code you present, because they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. -## 3. How to Work Through a Single Milestone +## 4. How to Work Through a Single Milestone When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. @@ -35,9 +47,17 @@ After all code fragments are in place, instruct the user how to run feedback loo The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). -Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]` and move to the next milestone or finish the Implementing Phase. +Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. + +## 5. Update the Learning Profile + +Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. + +Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. + +Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. -## 4. Handle Plan Issues +## 6. Handle Plan Issues If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. @@ -45,6 +65,6 @@ Ideally, you can catch this directly while you are creating the milestones for t In the Guiding Phase, the reviewer can decide how to proceed with your findings. -## 5. After the Last Milestone +## 7. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/claude-plugin/claude-skills/implement-show-me/assets/profile.md b/claude-plugin/claude-skills/implement-show-me/assets/profile.md new file mode 100644 index 0000000..57c37a7 --- /dev/null +++ b/claude-plugin/claude-skills/implement-show-me/assets/profile.md @@ -0,0 +1,172 @@ +# Guided Learning Profile + +*Updated YYYY-MM-DDTHH:mmZ* + +This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning +aid, not a performance record, and it is not shared, committed to a project repository, or pushed to +a public remote. I can edit or delete anything in it at any time. The last section is written for +the coding agent that maintains it. + +## Goals + +*No entries yet.* + +## Preferences + +*No entries yet.* + +## Carry Forward + +*No entries yet.* + +## Knowledge + +*No entries yet.* + +## Recurring Themes + +*No entries yet.* + +## For the Agent Reading This + +### Stages + +Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: + +- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. +- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. +- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals + themselves. + +### Reading This File + +- Use it to choose an opening: how large the milestones are, how much to explain, and how much help + to offer at the start. What happens in the session overrides this file - record what you observe, + not what you expected. +- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan + deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up + the carry-forward items that apply to the plan. +- **The most specific node wins.** A node's stage applies to everything beneath it except where a + child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the + tree when there is none. The `covers` list of a node tells you which things it includes without + a node of their own. +- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. +- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record + in `records/`, which holds the detail behind it. Read a record only when the node itself is not + enough. +- This file says what I have done and when. It is not a list of things I cannot do. + +### When to Update This File + +After each milestone, once I committed it, and once more when the pass ends - after the last +milestone, or earlier when I stop. Never in the middle of a milestone. + +- **After a milestone:** append the milestone's section to the record, update the nodes it touched, + and add or remove carry-forward items. +- **When the pass ends:** append the outcome to the record and update the recurring themes. + +Ask me once per session whether you may keep this file up to date; if I agree, write each update +without asking again, but show me what you changed. Re-read this file right before each write and +apply your changes to what is there - I or another session may have changed it since you last read +it. If this folder is a git repository, commit each update with a message that names the record. +Replace a `*No entries yet.*` placeholder once its section has content. + +All dates and times in this file and in `records/` are UTC. Take them from the command line rather +than guessing them: + +- `date -u +%FT%H:%MZ` on Unix-based shells +- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell + +This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it +when you change this file. Node dates use only its date part, `2026-09-17`, and record file names +use it as `2026-09-17-0231`. + +### Records + +One file per implementation pass in `records/`, named `--.md` +with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - +never edit what is already there: + +- **Header**, written with the file: the plan's title, the time the pass started, the repository, + the plan's path, the skill that ran, and the number of milestones in the roadmap. +- **One section per milestone**, appended after it: which areas it touched and how each went, where + the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before + running the feedback loops was right, and which questions I asked. +- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were + ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a + pass that is still running or was abandoned. + +Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it +clicked" is useful, "intermediate at TypeScript" is not. + +### Goals and Preferences + +Both are mine to state. Goals are what I want to get better at; preferences are how I like to be +taught - for example, explanation before code, the language to use, or how direct hints should be. +Add an entry only when I told you about it in the session, and reword or remove one only when I ask. + +### Carry Forward + +Short, actionable items for future passes, each naming the record it came from, for example +"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record +you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the +list short; if an item stays untouched for six months, propose removing it. + +### Nodes + +Write each node as a list item, nesting children beneath their parent: + +```markdown +- **** `` · · — covers , +``` + +A node is a body of knowledge a Frozen Plan draws on. Roots are +either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, +such as `Software design and architecture` or `Automated testing`. Check the tree before adding +anything: if the new thing fits inside an existing node, reuse it. + +Nest at most three levels deep - for a technology root, for example platform, technology, area: +`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. +When it would agree, list it in the parent's `covers` instead: the list records what a node includes +without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is +optional when the name says enough. A child that agrees with its parent is noise, so fold it into +the parent's `covers`. Anything finer belongs in a record. + +When a pass touches a node without changing its stage, still update its date and evidence, so that +the decay rule stays meaningful. + +### Stage Changes + +A stage moves for one of two reasons: + +- **Promotion**, because I grew into it: one step per pass, and only on something you observed. + Beginning to Advancing means I carried a milestone in that area without needing the implementation + handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's + approach for a reason that held up. +- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node + that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that + a record backs is worth a sentence in the new record explaining what changed your mind. + +A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the +implementation, so it cannot show that I would manage without. If I seem further along than +Beginning, say so, suggest `coach-me`, and note it in the record. + +Record the change on the node where you saw it. Evidence about structural typing moves that node, +not everything above it. Before you move a parent, check whether your evidence covers the whole +area: everything in its `covers` list and every area without a node of its own moves with it. If +the evidence covers only part of it, add a child for that part instead. + +### Recurring Themes + +A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach +for and whether they help. Mark each theme `candidate` or `established`, and name the records it was +seen in: + +```markdown +- **** `` - . Seen in: ``, ``. +``` + +Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` +when a later pass shows it again, and remove it when later passes contradict it. You only need the +current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most +five themes; when a sixth would be added, propose which one to drop. diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index a364a97..1a154cf 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -6,7 +6,7 @@ license: MIT # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advanced stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advancing stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. @@ -16,15 +16,27 @@ Use the plan named by the user. If none is named, proceed only when there is exa Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. -## 2. Create the Milestone Roadmap +## 2. Read the Learning Profile + +The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. + +Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. + +If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. + +Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. + +## 3. Create the Milestone Roadmap Break the plan into milestones and present them as a short roadmap without giving away their implementations. -A good milestone depends on the size of the plan: you could use file-by-file milestones for a smaller plan, or vertical slices for a larger one. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. +Build the roadmap from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas - what they practice is fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. + +A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. The user writes the milestone's tests as part of it - they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. -## 3. How to Work Through a Single Milestone +## 4. How to Work Through a Single Milestone When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. @@ -32,17 +44,25 @@ Be available as a teacher while they work. Answer questions about things like th When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. -Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan and move to the next milestone or finish the Implementing Phase. +Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan. Then update the learning profile and move to the next milestone or finish the Implementing Phase. -## 4. Reveal Help Progressively +## 5. Reveal Help Progressively Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. -Start at the level that fits the situation rather than mechanically beginning with a question. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. +Start at the level that fits the situation and the user's stage in the area at hand, rather than mechanically beginning with a question. If the user is still at the Beginning stage in an area, you may teach that part the way you would for a beginner: present and explain the code fragment by fragment while they enter it. This is the one exception to the rule below about providing code. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. -## 5. Handle Plan Issues +## 6. Update the Learning Profile + +Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. + +Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. + +Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. + +## 7. Handle Plan Issues If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. @@ -50,6 +70,6 @@ Ideally, you can catch this while creating the milestones, but you might also en In the Guiding Phase, the reviewer can decide how to proceed with your findings. -## 6. After the Last Milestone +## 8. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-coach-me/assets/profile.md b/skills/guided-coding-implement-coach-me/assets/profile.md new file mode 100644 index 0000000..57c37a7 --- /dev/null +++ b/skills/guided-coding-implement-coach-me/assets/profile.md @@ -0,0 +1,172 @@ +# Guided Learning Profile + +*Updated YYYY-MM-DDTHH:mmZ* + +This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning +aid, not a performance record, and it is not shared, committed to a project repository, or pushed to +a public remote. I can edit or delete anything in it at any time. The last section is written for +the coding agent that maintains it. + +## Goals + +*No entries yet.* + +## Preferences + +*No entries yet.* + +## Carry Forward + +*No entries yet.* + +## Knowledge + +*No entries yet.* + +## Recurring Themes + +*No entries yet.* + +## For the Agent Reading This + +### Stages + +Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: + +- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. +- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. +- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals + themselves. + +### Reading This File + +- Use it to choose an opening: how large the milestones are, how much to explain, and how much help + to offer at the start. What happens in the session overrides this file - record what you observe, + not what you expected. +- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan + deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up + the carry-forward items that apply to the plan. +- **The most specific node wins.** A node's stage applies to everything beneath it except where a + child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the + tree when there is none. The `covers` list of a node tells you which things it includes without + a node of their own. +- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. +- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record + in `records/`, which holds the detail behind it. Read a record only when the node itself is not + enough. +- This file says what I have done and when. It is not a list of things I cannot do. + +### When to Update This File + +After each milestone, once I committed it, and once more when the pass ends - after the last +milestone, or earlier when I stop. Never in the middle of a milestone. + +- **After a milestone:** append the milestone's section to the record, update the nodes it touched, + and add or remove carry-forward items. +- **When the pass ends:** append the outcome to the record and update the recurring themes. + +Ask me once per session whether you may keep this file up to date; if I agree, write each update +without asking again, but show me what you changed. Re-read this file right before each write and +apply your changes to what is there - I or another session may have changed it since you last read +it. If this folder is a git repository, commit each update with a message that names the record. +Replace a `*No entries yet.*` placeholder once its section has content. + +All dates and times in this file and in `records/` are UTC. Take them from the command line rather +than guessing them: + +- `date -u +%FT%H:%MZ` on Unix-based shells +- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell + +This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it +when you change this file. Node dates use only its date part, `2026-09-17`, and record file names +use it as `2026-09-17-0231`. + +### Records + +One file per implementation pass in `records/`, named `--.md` +with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - +never edit what is already there: + +- **Header**, written with the file: the plan's title, the time the pass started, the repository, + the plan's path, the skill that ran, and the number of milestones in the roadmap. +- **One section per milestone**, appended after it: which areas it touched and how each went, where + the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before + running the feedback loops was right, and which questions I asked. +- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were + ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a + pass that is still running or was abandoned. + +Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it +clicked" is useful, "intermediate at TypeScript" is not. + +### Goals and Preferences + +Both are mine to state. Goals are what I want to get better at; preferences are how I like to be +taught - for example, explanation before code, the language to use, or how direct hints should be. +Add an entry only when I told you about it in the session, and reword or remove one only when I ask. + +### Carry Forward + +Short, actionable items for future passes, each naming the record it came from, for example +"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record +you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the +list short; if an item stays untouched for six months, propose removing it. + +### Nodes + +Write each node as a list item, nesting children beneath their parent: + +```markdown +- **** `` · · — covers , +``` + +A node is a body of knowledge a Frozen Plan draws on. Roots are +either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, +such as `Software design and architecture` or `Automated testing`. Check the tree before adding +anything: if the new thing fits inside an existing node, reuse it. + +Nest at most three levels deep - for a technology root, for example platform, technology, area: +`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. +When it would agree, list it in the parent's `covers` instead: the list records what a node includes +without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is +optional when the name says enough. A child that agrees with its parent is noise, so fold it into +the parent's `covers`. Anything finer belongs in a record. + +When a pass touches a node without changing its stage, still update its date and evidence, so that +the decay rule stays meaningful. + +### Stage Changes + +A stage moves for one of two reasons: + +- **Promotion**, because I grew into it: one step per pass, and only on something you observed. + Beginning to Advancing means I carried a milestone in that area without needing the implementation + handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's + approach for a reason that held up. +- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node + that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that + a record backs is worth a sentence in the new record explaining what changed your mind. + +A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the +implementation, so it cannot show that I would manage without. If I seem further along than +Beginning, say so, suggest `coach-me`, and note it in the record. + +Record the change on the node where you saw it. Evidence about structural typing moves that node, +not everything above it. Before you move a parent, check whether your evidence covers the whole +area: everything in its `covers` list and every area without a node of its own moves with it. If +the evidence covers only part of it, add a child for that part instead. + +### Recurring Themes + +A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach +for and whether they help. Mark each theme `candidate` or `established`, and name the records it was +seen in: + +```markdown +- **** `` - . Seen in: ``, ``. +``` + +Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` +when a later pass shows it again, and remove it when later passes contradict it. You only need the +current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most +five themes; when a sixth would be added, propose which one to drop. diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index cbeaede..0055e89 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -16,15 +16,27 @@ Use the plan named by the user. If none is named, proceed only when there is exa Verify that the plan is frozen: its file name has a timestamp, and it has a `*Frozen at ...*` line below its title. If either marker is missing, explain that the Planning Phase is unfinished and stop. -## 2. Create the Milestone Roadmap +## 2. Read the Learning Profile + +The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. + +Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. + +If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. + +Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. + +## 3. Create the Milestone Roadmap Break the plan into milestones and present them as a short roadmap, not showing any code yet. -A good milestone depends on the size of the plan: you could use file-by-file for smaller plans, or break the work into vertical slices if the plan is larger. A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. +Build the roadmap layer by layer, so that each milestone puts one area in focus and builds upon the previous ones. For a backend feature, this could be the domain model first, then database access, followed by a service, and finally the endpoint. This way, the user can take in the concepts of one area at a time. Because nothing runs end-to-end before the last layer is in place, explain in the roadmap how the layers will connect in the end, and remind the user where the current layer sits in that picture whenever a milestone begins. If the plan has no layers, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. + +A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. This includes the milestone's tests - they are part of the code you present, because they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. -## 3. How to Work Through a Single Milestone +## 4. How to Work Through a Single Milestone When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. @@ -34,9 +46,17 @@ After all code fragments are in place, instruct the user how to run feedback loo The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). -Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]` and move to the next milestone or finish the Implementing Phase. +Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. + +## 5. Update the Learning Profile + +Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. + +Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. + +Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. -## 4. Handle Plan Issues +## 6. Handle Plan Issues If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. @@ -44,6 +64,6 @@ Ideally, you can catch this directly while you are creating the milestones for t In the Guiding Phase, the reviewer can decide how to proceed with your findings. -## 5. After the Last Milestone +## 7. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-show-me/assets/profile.md b/skills/guided-coding-implement-show-me/assets/profile.md new file mode 100644 index 0000000..57c37a7 --- /dev/null +++ b/skills/guided-coding-implement-show-me/assets/profile.md @@ -0,0 +1,172 @@ +# Guided Learning Profile + +*Updated YYYY-MM-DDTHH:mmZ* + +This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning +aid, not a performance record, and it is not shared, committed to a project repository, or pushed to +a public remote. I can edit or delete anything in it at any time. The last section is written for +the coding agent that maintains it. + +## Goals + +*No entries yet.* + +## Preferences + +*No entries yet.* + +## Carry Forward + +*No entries yet.* + +## Knowledge + +*No entries yet.* + +## Recurring Themes + +*No entries yet.* + +## For the Agent Reading This + +### Stages + +Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: + +- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. +- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. +- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals + themselves. + +### Reading This File + +- Use it to choose an opening: how large the milestones are, how much to explain, and how much help + to offer at the start. What happens in the session overrides this file - record what you observe, + not what you expected. +- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan + deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up + the carry-forward items that apply to the plan. +- **The most specific node wins.** A node's stage applies to everything beneath it except where a + child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the + tree when there is none. The `covers` list of a node tells you which things it includes without + a node of their own. +- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. +- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record + in `records/`, which holds the detail behind it. Read a record only when the node itself is not + enough. +- This file says what I have done and when. It is not a list of things I cannot do. + +### When to Update This File + +After each milestone, once I committed it, and once more when the pass ends - after the last +milestone, or earlier when I stop. Never in the middle of a milestone. + +- **After a milestone:** append the milestone's section to the record, update the nodes it touched, + and add or remove carry-forward items. +- **When the pass ends:** append the outcome to the record and update the recurring themes. + +Ask me once per session whether you may keep this file up to date; if I agree, write each update +without asking again, but show me what you changed. Re-read this file right before each write and +apply your changes to what is there - I or another session may have changed it since you last read +it. If this folder is a git repository, commit each update with a message that names the record. +Replace a `*No entries yet.*` placeholder once its section has content. + +All dates and times in this file and in `records/` are UTC. Take them from the command line rather +than guessing them: + +- `date -u +%FT%H:%MZ` on Unix-based shells +- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell + +This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it +when you change this file. Node dates use only its date part, `2026-09-17`, and record file names +use it as `2026-09-17-0231`. + +### Records + +One file per implementation pass in `records/`, named `--.md` +with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - +never edit what is already there: + +- **Header**, written with the file: the plan's title, the time the pass started, the repository, + the plan's path, the skill that ran, and the number of milestones in the roadmap. +- **One section per milestone**, appended after it: which areas it touched and how each went, where + the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before + running the feedback loops was right, and which questions I asked. +- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were + ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a + pass that is still running or was abandoned. + +Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it +clicked" is useful, "intermediate at TypeScript" is not. + +### Goals and Preferences + +Both are mine to state. Goals are what I want to get better at; preferences are how I like to be +taught - for example, explanation before code, the language to use, or how direct hints should be. +Add an entry only when I told you about it in the session, and reword or remove one only when I ask. + +### Carry Forward + +Short, actionable items for future passes, each naming the record it came from, for example +"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record +you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the +list short; if an item stays untouched for six months, propose removing it. + +### Nodes + +Write each node as a list item, nesting children beneath their parent: + +```markdown +- **** `` · · — covers , +``` + +A node is a body of knowledge a Frozen Plan draws on. Roots are +either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, +such as `Software design and architecture` or `Automated testing`. Check the tree before adding +anything: if the new thing fits inside an existing node, reuse it. + +Nest at most three levels deep - for a technology root, for example platform, technology, area: +`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. +When it would agree, list it in the parent's `covers` instead: the list records what a node includes +without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is +optional when the name says enough. A child that agrees with its parent is noise, so fold it into +the parent's `covers`. Anything finer belongs in a record. + +When a pass touches a node without changing its stage, still update its date and evidence, so that +the decay rule stays meaningful. + +### Stage Changes + +A stage moves for one of two reasons: + +- **Promotion**, because I grew into it: one step per pass, and only on something you observed. + Beginning to Advancing means I carried a milestone in that area without needing the implementation + handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's + approach for a reason that held up. +- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node + that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that + a record backs is worth a sentence in the new record explaining what changed your mind. + +A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the +implementation, so it cannot show that I would manage without. If I seem further along than +Beginning, say so, suggest `coach-me`, and note it in the record. + +Record the change on the node where you saw it. Evidence about structural typing moves that node, +not everything above it. Before you move a parent, check whether your evidence covers the whole +area: everything in its `covers` list and every area without a node of its own moves with it. If +the evidence covers only part of it, add a child for that part instead. + +### Recurring Themes + +A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach +for and whether they help. Mark each theme `candidate` or `established`, and name the records it was +seen in: + +```markdown +- **** `` - . Seen in: ``, ``. +``` + +Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` +when a later pass shows it again, and remove it when later passes contradict it. You only need the +current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most +five themes; when a sixth would be added, propose which one to drop. diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index c57b8fe..44eace2 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -39,15 +39,19 @@ public sealed class PackageValidationTests ["guided-coding-write-plan"] = "write-plan" }; - private const string SharedTargetSection = "Establish the Target"; - - private static readonly string[] SkillsSharingTheTargetSection = + private static readonly string[] GuidedLearningSkillNames = [ - "guided-coding-implement", "guided-coding-implement-coach-me", "guided-coding-implement-show-me" ]; + private static readonly (string Section, string[] SkillNames)[] SharedSections = + [ + ("Establish the Target", ["guided-coding-implement", .. GuidedLearningSkillNames]), + ("Read the Learning Profile", GuidedLearningSkillNames), + ("Update the Learning Profile", GuidedLearningSkillNames) + ]; + private static readonly string[] ForbiddenFrontmatterFields = [ "allowed-tools", @@ -304,16 +308,22 @@ public void ClaudePluginContainsTheRepositoryLicense() ); } - [Fact] - public void SkillsSharingASectionKeepItIdentical() + public static TheoryData SharedSectionNames => new ( + SharedSections.Select(shared => shared.Section) + ); + + [Theory] + [MemberData(nameof(SharedSectionNames))] + public void SkillsSharingASectionKeepItIdentical(string sectionName) { - var sections = SkillsSharingTheTargetSection + var skillNames = SharedSections.Single(shared => shared.Section == sectionName).SkillNames; + var sections = skillNames .Select( skillName => ( SkillName: skillName, Body: ReadSectionBody( Path.Combine(RepositoryRoot, "skills", skillName, "SKILL.md"), - SharedTargetSection + sectionName ) ) ) @@ -324,13 +334,39 @@ public void SkillsSharingASectionKeepItIdentical() { Assert.True( string.Equals(reference.Body, section.Body, StringComparison.Ordinal), - $"\"{SharedTargetSection}\" differs between {reference.SkillName} and {section.SkillName}. " + + $"\"{sectionName}\" differs between {reference.SkillName} and {section.SkillName}. " + "The section is duplicated on purpose because skills are standalone; " + "apply the change to every skill that shares it." ); } } + [Fact] + public void GuidedLearningSkillsShipTheSameProfileTemplate() + { + var templates = GuidedLearningSkillNames + .Select( + skillName => ( + SkillName: skillName, + Content: File.ReadAllText( + Path.Combine(RepositoryRoot, "skills", skillName, "assets", "profile.md") + ) + ) + ) + .ToArray(); + var reference = templates[0]; + + foreach (var template in templates[1..]) + { + Assert.True( + string.Equals(reference.Content, template.Content, StringComparison.Ordinal), + $"assets/profile.md differs between {reference.SkillName} and {template.SkillName}. " + + "The template is duplicated on purpose because skills are standalone; " + + "apply the change to every skill that ships it." + ); + } + } + private static string FindRepositoryRoot() { for ( From 5ae0c459fd1ccb26ef502ff8a62ecfb072c89ae6 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:01:50 +0200 Subject: [PATCH 15/26] feat: simplify the Guided Learning profile The profile at ~/.guided-learning/profile.md now holds only data: goals, preferences, and the knowledge tree. The rules for reading and maintaining it moved from the template into the shared skill sections, so improving the skills also reaches existing profiles. The profile folder is a mandatory git repository on a single main branch. Commit history replaces the records, the Updated line, node dates, and evidence fields. Carry Forward, Recurring Themes, and decay are gone. Before the roadmap, the skills check the user's goals and preferences. Technology nodes follow ecosystem, technology, and area, and discipline nodes follow a fixed list of roots, then topic and subarea. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Kenny Pflug --- .../claude-skills/implement-coach-me/SKILL.md | 31 +++- .../implement-coach-me/assets/profile.md | 165 ------------------ .../claude-skills/implement-show-me/SKILL.md | 35 ++-- .../implement-show-me/assets/profile.md | 165 ------------------ .../guided-coding-implement-coach-me/SKILL.md | 31 +++- .../assets/profile.md | 165 ------------------ .../guided-coding-implement-show-me/SKILL.md | 35 ++-- .../assets/profile.md | 165 ------------------ 8 files changed, 96 insertions(+), 696 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index ca0f42b..9154834 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -19,13 +19,17 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Read the Learning Profile -The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. +`~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. +It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: -If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. +- **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. +- **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. +- **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. +Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. + +Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. ## 3. Create the Milestone Roadmap @@ -57,11 +61,22 @@ Do not provide code before it is needed. If explanations and outlines are not en ## 6. Update the Learning Profile -Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. +Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. + +Change goals and preferences only as the user says. Write knowledge nodes as nested list items: + +```markdown +- **** `` — covers , +``` + +Knowledge that would survive a switch to another technology stack belongs to a discipline, anything else to a technology. Nest at most three levels: + +- **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. +- **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. +Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues @@ -73,4 +88,4 @@ In the Guiding Phase, the reviewer can decide how to proceed with your findings. ## 8. After the Last Milestone -Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/claude-plugin/claude-skills/implement-coach-me/assets/profile.md b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md index 57c37a7..4a2df76 100644 --- a/claude-plugin/claude-skills/implement-coach-me/assets/profile.md +++ b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md @@ -1,172 +1,7 @@ # Guided Learning Profile -*Updated YYYY-MM-DDTHH:mmZ* - -This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning -aid, not a performance record, and it is not shared, committed to a project repository, or pushed to -a public remote. I can edit or delete anything in it at any time. The last section is written for -the coding agent that maintains it. - ## Goals -*No entries yet.* - ## Preferences -*No entries yet.* - -## Carry Forward - -*No entries yet.* - ## Knowledge - -*No entries yet.* - -## Recurring Themes - -*No entries yet.* - -## For the Agent Reading This - -### Stages - -Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: - -- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. -- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. -- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals - themselves. - -### Reading This File - -- Use it to choose an opening: how large the milestones are, how much to explain, and how much help - to offer at the start. What happens in the session overrides this file - record what you observe, - not what you expected. -- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan - deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up - the carry-forward items that apply to the plan. -- **The most specific node wins.** A node's stage applies to everything beneath it except where a - child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the - tree when there is none. The `covers` list of a node tells you which things it includes without - a node of their own. -- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. -- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record - in `records/`, which holds the detail behind it. Read a record only when the node itself is not - enough. -- This file says what I have done and when. It is not a list of things I cannot do. - -### When to Update This File - -After each milestone, once I committed it, and once more when the pass ends - after the last -milestone, or earlier when I stop. Never in the middle of a milestone. - -- **After a milestone:** append the milestone's section to the record, update the nodes it touched, - and add or remove carry-forward items. -- **When the pass ends:** append the outcome to the record and update the recurring themes. - -Ask me once per session whether you may keep this file up to date; if I agree, write each update -without asking again, but show me what you changed. Re-read this file right before each write and -apply your changes to what is there - I or another session may have changed it since you last read -it. If this folder is a git repository, commit each update with a message that names the record. -Replace a `*No entries yet.*` placeholder once its section has content. - -All dates and times in this file and in `records/` are UTC. Take them from the command line rather -than guessing them: - -- `date -u +%FT%H:%MZ` on Unix-based shells -- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell - -This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it -when you change this file. Node dates use only its date part, `2026-09-17`, and record file names -use it as `2026-09-17-0231`. - -### Records - -One file per implementation pass in `records/`, named `--.md` -with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - -never edit what is already there: - -- **Header**, written with the file: the plan's title, the time the pass started, the repository, - the plan's path, the skill that ran, and the number of milestones in the roadmap. -- **One section per milestone**, appended after it: which areas it touched and how each went, where - the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before - running the feedback loops was right, and which questions I asked. -- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were - ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a - pass that is still running or was abandoned. - -Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it -clicked" is useful, "intermediate at TypeScript" is not. - -### Goals and Preferences - -Both are mine to state. Goals are what I want to get better at; preferences are how I like to be -taught - for example, explanation before code, the language to use, or how direct hints should be. -Add an entry only when I told you about it in the session, and reword or remove one only when I ask. - -### Carry Forward - -Short, actionable items for future passes, each naming the record it came from, for example -"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record -you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the -list short; if an item stays untouched for six months, propose removing it. - -### Nodes - -Write each node as a list item, nesting children beneath their parent: - -```markdown -- **** `` · · — covers , -``` - -A node is a body of knowledge a Frozen Plan draws on. Roots are -either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, -such as `Software design and architecture` or `Automated testing`. Check the tree before adding -anything: if the new thing fits inside an existing node, reuse it. - -Nest at most three levels deep - for a technology root, for example platform, technology, area: -`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. -When it would agree, list it in the parent's `covers` instead: the list records what a node includes -without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is -optional when the name says enough. A child that agrees with its parent is noise, so fold it into -the parent's `covers`. Anything finer belongs in a record. - -When a pass touches a node without changing its stage, still update its date and evidence, so that -the decay rule stays meaningful. - -### Stage Changes - -A stage moves for one of two reasons: - -- **Promotion**, because I grew into it: one step per pass, and only on something you observed. - Beginning to Advancing means I carried a milestone in that area without needing the implementation - handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's - approach for a reason that held up. -- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node - that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that - a record backs is worth a sentence in the new record explaining what changed your mind. - -A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the -implementation, so it cannot show that I would manage without. If I seem further along than -Beginning, say so, suggest `coach-me`, and note it in the record. - -Record the change on the node where you saw it. Evidence about structural typing moves that node, -not everything above it. Before you move a parent, check whether your evidence covers the whole -area: everything in its `covers` list and every area without a node of its own moves with it. If -the evidence covers only part of it, add a child for that part instead. - -### Recurring Themes - -A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach -for and whether they help. Mark each theme `candidate` or `established`, and name the records it was -seen in: - -```markdown -- **** `` - . Seen in: ``, ``. -``` - -Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` -when a later pass shows it again, and remove it when later passes contradict it. You only need the -current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most -five themes; when a sixth would be added, propose which one to drop. diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 5254ec4..3fa9175 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -19,13 +19,17 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Read the Learning Profile -The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. +`~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. +It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: -If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. +- **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. +- **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. +- **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. +Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. + +Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. ## 3. Create the Milestone Roadmap @@ -39,23 +43,34 @@ It is totally fine if you break up a plan into a single milestone. We trust your ## 4. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understand this. Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. -The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). +The user might ask questions about details of the code at any point. Be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. ## 5. Update the Learning Profile -Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. +Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. + +Change goals and preferences only as the user says. Write knowledge nodes as nested list items: + +```markdown +- **** `` — covers , +``` + +Knowledge that would survive a switch to another technology stack belongs to a discipline, anything else to a technology. Nest at most three levels: + +- **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. +- **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. +Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues @@ -67,4 +82,4 @@ In the Guiding Phase, the reviewer can decide how to proceed with your findings. ## 7. After the Last Milestone -Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/claude-plugin/claude-skills/implement-show-me/assets/profile.md b/claude-plugin/claude-skills/implement-show-me/assets/profile.md index 57c37a7..4a2df76 100644 --- a/claude-plugin/claude-skills/implement-show-me/assets/profile.md +++ b/claude-plugin/claude-skills/implement-show-me/assets/profile.md @@ -1,172 +1,7 @@ # Guided Learning Profile -*Updated YYYY-MM-DDTHH:mmZ* - -This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning -aid, not a performance record, and it is not shared, committed to a project repository, or pushed to -a public remote. I can edit or delete anything in it at any time. The last section is written for -the coding agent that maintains it. - ## Goals -*No entries yet.* - ## Preferences -*No entries yet.* - -## Carry Forward - -*No entries yet.* - ## Knowledge - -*No entries yet.* - -## Recurring Themes - -*No entries yet.* - -## For the Agent Reading This - -### Stages - -Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: - -- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. -- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. -- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals - themselves. - -### Reading This File - -- Use it to choose an opening: how large the milestones are, how much to explain, and how much help - to offer at the start. What happens in the session overrides this file - record what you observe, - not what you expected. -- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan - deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up - the carry-forward items that apply to the plan. -- **The most specific node wins.** A node's stage applies to everything beneath it except where a - child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the - tree when there is none. The `covers` list of a node tells you which things it includes without - a node of their own. -- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. -- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record - in `records/`, which holds the detail behind it. Read a record only when the node itself is not - enough. -- This file says what I have done and when. It is not a list of things I cannot do. - -### When to Update This File - -After each milestone, once I committed it, and once more when the pass ends - after the last -milestone, or earlier when I stop. Never in the middle of a milestone. - -- **After a milestone:** append the milestone's section to the record, update the nodes it touched, - and add or remove carry-forward items. -- **When the pass ends:** append the outcome to the record and update the recurring themes. - -Ask me once per session whether you may keep this file up to date; if I agree, write each update -without asking again, but show me what you changed. Re-read this file right before each write and -apply your changes to what is there - I or another session may have changed it since you last read -it. If this folder is a git repository, commit each update with a message that names the record. -Replace a `*No entries yet.*` placeholder once its section has content. - -All dates and times in this file and in `records/` are UTC. Take them from the command line rather -than guessing them: - -- `date -u +%FT%H:%MZ` on Unix-based shells -- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell - -This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it -when you change this file. Node dates use only its date part, `2026-09-17`, and record file names -use it as `2026-09-17-0231`. - -### Records - -One file per implementation pass in `records/`, named `--.md` -with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - -never edit what is already there: - -- **Header**, written with the file: the plan's title, the time the pass started, the repository, - the plan's path, the skill that ran, and the number of milestones in the roadmap. -- **One section per milestone**, appended after it: which areas it touched and how each went, where - the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before - running the feedback loops was right, and which questions I asked. -- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were - ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a - pass that is still running or was abandoned. - -Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it -clicked" is useful, "intermediate at TypeScript" is not. - -### Goals and Preferences - -Both are mine to state. Goals are what I want to get better at; preferences are how I like to be -taught - for example, explanation before code, the language to use, or how direct hints should be. -Add an entry only when I told you about it in the session, and reword or remove one only when I ask. - -### Carry Forward - -Short, actionable items for future passes, each naming the record it came from, for example -"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record -you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the -list short; if an item stays untouched for six months, propose removing it. - -### Nodes - -Write each node as a list item, nesting children beneath their parent: - -```markdown -- **** `` · · — covers , -``` - -A node is a body of knowledge a Frozen Plan draws on. Roots are -either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, -such as `Software design and architecture` or `Automated testing`. Check the tree before adding -anything: if the new thing fits inside an existing node, reuse it. - -Nest at most three levels deep - for a technology root, for example platform, technology, area: -`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. -When it would agree, list it in the parent's `covers` instead: the list records what a node includes -without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is -optional when the name says enough. A child that agrees with its parent is noise, so fold it into -the parent's `covers`. Anything finer belongs in a record. - -When a pass touches a node without changing its stage, still update its date and evidence, so that -the decay rule stays meaningful. - -### Stage Changes - -A stage moves for one of two reasons: - -- **Promotion**, because I grew into it: one step per pass, and only on something you observed. - Beginning to Advancing means I carried a milestone in that area without needing the implementation - handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's - approach for a reason that held up. -- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node - that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that - a record backs is worth a sentence in the new record explaining what changed your mind. - -A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the -implementation, so it cannot show that I would manage without. If I seem further along than -Beginning, say so, suggest `coach-me`, and note it in the record. - -Record the change on the node where you saw it. Evidence about structural typing moves that node, -not everything above it. Before you move a parent, check whether your evidence covers the whole -area: everything in its `covers` list and every area without a node of its own moves with it. If -the evidence covers only part of it, add a child for that part instead. - -### Recurring Themes - -A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach -for and whether they help. Mark each theme `candidate` or `established`, and name the records it was -seen in: - -```markdown -- **** `` - . Seen in: ``, ``. -``` - -Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` -when a later pass shows it again, and remove it when later passes contradict it. You only need the -current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most -five themes; when a sixth would be added, propose which one to drop. diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index 1a154cf..fe95eee 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -18,13 +18,17 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Read the Learning Profile -The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. +`~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. +It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: -If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. +- **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. +- **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. +- **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. +Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. + +Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. ## 3. Create the Milestone Roadmap @@ -56,11 +60,22 @@ Do not provide code before it is needed. If explanations and outlines are not en ## 6. Update the Learning Profile -Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. +Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. + +Change goals and preferences only as the user says. Write knowledge nodes as nested list items: + +```markdown +- **** `` — covers , +``` + +Knowledge that would survive a switch to another technology stack belongs to a discipline, anything else to a technology. Nest at most three levels: + +- **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. +- **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. +Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues @@ -72,4 +87,4 @@ In the Guiding Phase, the reviewer can decide how to proceed with your findings. ## 8. After the Last Milestone -Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-coach-me/assets/profile.md b/skills/guided-coding-implement-coach-me/assets/profile.md index 57c37a7..4a2df76 100644 --- a/skills/guided-coding-implement-coach-me/assets/profile.md +++ b/skills/guided-coding-implement-coach-me/assets/profile.md @@ -1,172 +1,7 @@ # Guided Learning Profile -*Updated YYYY-MM-DDTHH:mmZ* - -This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning -aid, not a performance record, and it is not shared, committed to a project repository, or pushed to -a public remote. I can edit or delete anything in it at any time. The last section is written for -the coding agent that maintains it. - ## Goals -*No entries yet.* - ## Preferences -*No entries yet.* - -## Carry Forward - -*No entries yet.* - ## Knowledge - -*No entries yet.* - -## Recurring Themes - -*No entries yet.* - -## For the Agent Reading This - -### Stages - -Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: - -- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. -- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. -- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals - themselves. - -### Reading This File - -- Use it to choose an opening: how large the milestones are, how much to explain, and how much help - to offer at the start. What happens in the session overrides this file - record what you observe, - not what you expected. -- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan - deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up - the carry-forward items that apply to the plan. -- **The most specific node wins.** A node's stage applies to everything beneath it except where a - child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the - tree when there is none. The `covers` list of a node tells you which things it includes without - a node of their own. -- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. -- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record - in `records/`, which holds the detail behind it. Read a record only when the node itself is not - enough. -- This file says what I have done and when. It is not a list of things I cannot do. - -### When to Update This File - -After each milestone, once I committed it, and once more when the pass ends - after the last -milestone, or earlier when I stop. Never in the middle of a milestone. - -- **After a milestone:** append the milestone's section to the record, update the nodes it touched, - and add or remove carry-forward items. -- **When the pass ends:** append the outcome to the record and update the recurring themes. - -Ask me once per session whether you may keep this file up to date; if I agree, write each update -without asking again, but show me what you changed. Re-read this file right before each write and -apply your changes to what is there - I or another session may have changed it since you last read -it. If this folder is a git repository, commit each update with a message that names the record. -Replace a `*No entries yet.*` placeholder once its section has content. - -All dates and times in this file and in `records/` are UTC. Take them from the command line rather -than guessing them: - -- `date -u +%FT%H:%MZ` on Unix-based shells -- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell - -This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it -when you change this file. Node dates use only its date part, `2026-09-17`, and record file names -use it as `2026-09-17-0231`. - -### Records - -One file per implementation pass in `records/`, named `--.md` -with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - -never edit what is already there: - -- **Header**, written with the file: the plan's title, the time the pass started, the repository, - the plan's path, the skill that ran, and the number of milestones in the roadmap. -- **One section per milestone**, appended after it: which areas it touched and how each went, where - the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before - running the feedback loops was right, and which questions I asked. -- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were - ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a - pass that is still running or was abandoned. - -Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it -clicked" is useful, "intermediate at TypeScript" is not. - -### Goals and Preferences - -Both are mine to state. Goals are what I want to get better at; preferences are how I like to be -taught - for example, explanation before code, the language to use, or how direct hints should be. -Add an entry only when I told you about it in the session, and reword or remove one only when I ask. - -### Carry Forward - -Short, actionable items for future passes, each naming the record it came from, for example -"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record -you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the -list short; if an item stays untouched for six months, propose removing it. - -### Nodes - -Write each node as a list item, nesting children beneath their parent: - -```markdown -- **** `` · · — covers , -``` - -A node is a body of knowledge a Frozen Plan draws on. Roots are -either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, -such as `Software design and architecture` or `Automated testing`. Check the tree before adding -anything: if the new thing fits inside an existing node, reuse it. - -Nest at most three levels deep - for a technology root, for example platform, technology, area: -`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. -When it would agree, list it in the parent's `covers` instead: the list records what a node includes -without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is -optional when the name says enough. A child that agrees with its parent is noise, so fold it into -the parent's `covers`. Anything finer belongs in a record. - -When a pass touches a node without changing its stage, still update its date and evidence, so that -the decay rule stays meaningful. - -### Stage Changes - -A stage moves for one of two reasons: - -- **Promotion**, because I grew into it: one step per pass, and only on something you observed. - Beginning to Advancing means I carried a milestone in that area without needing the implementation - handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's - approach for a reason that held up. -- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node - that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that - a record backs is worth a sentence in the new record explaining what changed your mind. - -A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the -implementation, so it cannot show that I would manage without. If I seem further along than -Beginning, say so, suggest `coach-me`, and note it in the record. - -Record the change on the node where you saw it. Evidence about structural typing moves that node, -not everything above it. Before you move a parent, check whether your evidence covers the whole -area: everything in its `covers` list and every area without a node of its own moves with it. If -the evidence covers only part of it, add a child for that part instead. - -### Recurring Themes - -A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach -for and whether they help. Mark each theme `candidate` or `established`, and name the records it was -seen in: - -```markdown -- **** `` - . Seen in: ``, ``. -``` - -Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` -when a later pass shows it again, and remove it when later passes contradict it. You only need the -current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most -five themes; when a sixth would be added, propose which one to drop. diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 0055e89..2612d8b 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -18,13 +18,17 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr ## 2. Read the Learning Profile -The user's learning progress is tracked across conversations in `~/.guided-learning/profile.md`. Read it before you create the milestone roadmap. It contains the user's goals and teaching preferences, items carried forward from earlier passes, a tree of knowledge areas that are each assigned to one of the stages Beginning, Advancing, or Mastering, and a section for the agent that explains how to read and maintain the file - please follow it. If the file does not exist yet, read `assets/profile.md` relative to this skill file instead: it is the empty template and contains the same instructions. +`~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -Look up the areas the plan draws on and let their stages decide how large you make the milestones, how much you explain, and how much help you offer at the start. Let the goals, preferences, and carry-forward items shape the roadmap as well. If the profile does not cover an area, ask the user how familiar they are with it. The profile is only a starting point, though - what you observe while working with the user always takes precedence. +It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: -If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out and let them decide whether to continue. +- **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. +- **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. +- **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Finally, ask the user once whether you may keep the profile up to date during this session. If they decline, skip the section Update the Learning Profile - that's totally fine. +Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. + +Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. ## 3. Create the Milestone Roadmap @@ -38,23 +42,34 @@ It is totally fine if you break up a plan into a single milestone. We trust your ## 4. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understood this. +When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understand this. Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. -The user might ask questions about details of the code at any point - be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). +The user might ask questions about details of the code at any point. Be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. ## 5. Update the Learning Profile -Update the profile after each milestone, once the user created the commit, and once more when the pass ends - after the last milestone, or earlier when the user stops. The profile's section for the agent explains what each update contains; please follow it, including its rules on how far a stage may move in a single pass. Show the user what you changed, but do not ask for permission again. +Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. + +Change goals and preferences only as the user says. Write knowledge nodes as nested list items: + +```markdown +- **** `` — covers , +``` + +Knowledge that would survive a switch to another technology stack belongs to a discipline, anything else to a technology. Nest at most three levels: + +- **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. +- **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Re-read `~/.guided-learning/profile.md` right before each write and apply your changes to what is there - the user or another session may have changed it in the meantime. If `~/.guided-learning/profile.md` does not exist yet, copy `assets/profile.md` relative to this skill file there before your first update. Add what the user told you about their familiarity with an area during this conversation as `self-reported` nodes. +Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Keep everything inside `~/.guided-learning/`. Learning notes never belong in the repository you are working in. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues @@ -66,4 +81,4 @@ In the Guiding Phase, the reviewer can decide how to proceed with your findings. ## 7. After the Last Milestone -Finish the learning profile for this pass as described in Update the Learning Profile. Then summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-show-me/assets/profile.md b/skills/guided-coding-implement-show-me/assets/profile.md index 57c37a7..4a2df76 100644 --- a/skills/guided-coding-implement-show-me/assets/profile.md +++ b/skills/guided-coding-implement-show-me/assets/profile.md @@ -1,172 +1,7 @@ # Guided Learning Profile -*Updated YYYY-MM-DDTHH:mmZ* - -This file tracks what I have learned across Guided Learning sessions. It is private to me: a learning -aid, not a performance record, and it is not shared, committed to a project repository, or pushed to -a public remote. I can edit or delete anything in it at any time. The last section is written for -the coding agent that maintains it. - ## Goals -*No entries yet.* - ## Preferences -*No entries yet.* - -## Carry Forward - -*No entries yet.* - ## Knowledge - -*No entries yet.* - -## Recurring Themes - -*No entries yet.* - -## For the Agent Reading This - -### Stages - -Every node in the knowledge tree carries one of Guided Coding's three stages, nothing in between: - -- **Beginning** - learning the concepts and mechanisms of an area, mostly by applying them as shown. -- **Advancing** - fluent in the fundamentals and able to adapt them to new problems. -- **Mastering** - able to transform concepts quickly, and to question or replace the fundamentals - themselves. - -### Reading This File - -- Use it to choose an opening: how large the milestones are, how much to explain, and how much help - to offer at the start. What happens in the session overrides this file - record what you observe, - not what you expected. -- **Goals, Preferences, and Carry Forward come first.** Let the goals decide which parts of a plan - deserve to be the explicit subject of a milestone, teach the way the preferences ask, and pick up - the carry-forward items that apply to the plan. -- **The most specific node wins.** A node's stage applies to everything beneath it except where a - child says otherwise. Look for the deepest node covering what the plan needs, and fall back up the - tree when there is none. The `covers` list of a node tells you which things it includes without - a node of their own. -- **Entries decay.** A node dated more than six months ago is a prior worth re-testing, not a fact. -- **Evidence** says where a node came from: `self-reported` (I said so) or the file name of a record - in `records/`, which holds the detail behind it. Read a record only when the node itself is not - enough. -- This file says what I have done and when. It is not a list of things I cannot do. - -### When to Update This File - -After each milestone, once I committed it, and once more when the pass ends - after the last -milestone, or earlier when I stop. Never in the middle of a milestone. - -- **After a milestone:** append the milestone's section to the record, update the nodes it touched, - and add or remove carry-forward items. -- **When the pass ends:** append the outcome to the record and update the recurring themes. - -Ask me once per session whether you may keep this file up to date; if I agree, write each update -without asking again, but show me what you changed. Re-read this file right before each write and -apply your changes to what is there - I or another session may have changed it since you last read -it. If this folder is a git repository, commit each update with a message that names the record. -Replace a `*No entries yet.*` placeholder once its section has content. - -All dates and times in this file and in `records/` are UTC. Take them from the command line rather -than guessing them: - -- `date -u +%FT%H:%MZ` on Unix-based shells -- `(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm'Z'")` on PowerShell - -This gives an ISO 8601 timestamp such as `2026-09-17T02:31Z`. Set the `*Updated ...*` line to it -when you change this file. Node dates use only its date part, `2026-09-17`, and record file names -use it as `2026-09-17-0231`. - -### Records - -One file per implementation pass in `records/`, named `--.md` -with a `YYYY-MM-DD-HHMM` timestamp. Create it after the first milestone and only ever append to it - -never edit what is already there: - -- **Header**, written with the file: the plan's title, the time the pass started, the repository, - the plan's path, the skill that ran, and the number of milestones in the roadmap. -- **One section per milestone**, appended after it: which areas it touched and how each went, where - the time went, and what unblocked it. In a `show-me` pass, also note whether my prediction before - running the feedback loops was right, and which questions I asked. -- **Outcome**, appended when the pass ends: how far the pass got, which Acceptance Criteria were - ticked, and anything worth carrying into the next pass. A record without an outcome belongs to a - pass that is still running or was abandoned. - -Keep to what you observed. Evidence rather than verdicts - "needed the mechanism explained before it -clicked" is useful, "intermediate at TypeScript" is not. - -### Goals and Preferences - -Both are mine to state. Goals are what I want to get better at; preferences are how I like to be -taught - for example, explanation before code, the language to use, or how direct hints should be. -Add an entry only when I told you about it in the session, and reword or remove one only when I ask. - -### Carry Forward - -Short, actionable items for future passes, each naming the record it came from, for example -"Start Satori from problems, not worked examples - the mechanics landed." Add them from the record -you are writing, and remove an item once a pass has addressed it or it no longer applies. Keep the -list short; if an item stays untouched for six months, propose removing it. - -### Nodes - -Write each node as a list item, nesting children beneath their parent: - -```markdown -- **** `` · · — covers , -``` - -A node is a body of knowledge a Frozen Plan draws on. Roots are -either technologies, such as `.NET` or `TypeScript`, or disciplines that cut across technologies, -such as `Software design and architecture` or `Automated testing`. Check the tree before adding -anything: if the new thing fits inside an existing node, reuse it. - -Nest at most three levels deep - for a technology root, for example platform, technology, area: -`.NET` → `EF Core` → `change tracking`. Add a child only when its stage differs from its parent's. -When it would agree, list it in the parent's `covers` instead: the list records what a node includes -without a node of its own, so `Node build tooling` covers `Satori, sharp, tsx`. The `covers` part is -optional when the name says enough. A child that agrees with its parent is noise, so fold it into -the parent's `covers`. Anything finer belongs in a record. - -When a pass touches a node without changing its stage, still update its date and evidence, so that -the decay rule stays meaningful. - -### Stage Changes - -A stage moves for one of two reasons: - -- **Promotion**, because I grew into it: one step per pass, and only on something you observed. - Beginning to Advancing means I carried a milestone in that area without needing the implementation - handed to me. Advancing to Mastering means I shaped the design myself, or pushed back on the plan's - approach for a reason that held up. -- **Correction**, because the node was wrong: any distance, straight away. A `self-reported` node - that turns out to be Mastering was never Beginning, and nobody was promoted. Correcting a node that - a record backs is worth a sentence in the new record explaining what changed your mind. - -A `show-me` pass never sets a node above Beginning, not even as a correction: it hands me the -implementation, so it cannot show that I would manage without. If I seem further along than -Beginning, say so, suggest `coach-me`, and note it in the record. - -Record the change on the node where you saw it. Evidence about structural typing moves that node, -not everything above it. Before you move a parent, check whether your evidence covers the whole -area: everything in its `covers` list and every area without a node of its own moves with it. If -the evidence covers only part of it, add a child for that part instead. - -### Recurring Themes - -A theme is a pattern in how I learn rather than in what I know - for example, which analogies I reach -for and whether they help. Mark each theme `candidate` or `established`, and name the records it was -seen in: - -```markdown -- **** `` - . Seen in: ``, ``. -``` - -Add a theme as `candidate` when the record you are writing shows a pattern. Mark it `established` -when a later pass shows it again, and remove it when later passes contradict it. You only need the -current pass and this list for that - do not re-read old records to hunt for patterns. Keep at most -five themes; when a sixth would be added, propose which one to drop. From 1bb72a643e81d166a1920cca1b79080bc8cd70ab Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:07:51 +0200 Subject: [PATCH 16/26] docs: tighten the Guided Learning skills Remove filler from the intro, roadmap, milestone, and plan-issue sections of the show-me and coach-me skills without dropping any instruction. Both skills now share the same wording for plan issues, and coach-me states its Beginning-stage exception next to the rule about providing code. Co-Authored-By: Claude Opus 5.5 --- .../claude-skills/implement-coach-me/SKILL.md | 34 +++++++------------ .../claude-skills/implement-show-me/SKILL.md | 30 +++++++--------- .../guided-coding-implement-coach-me/SKILL.md | 34 +++++++------------ .../guided-coding-implement-show-me/SKILL.md | 30 +++++++--------- 4 files changed, 50 insertions(+), 78 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 9154834..29d2129 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -7,9 +7,9 @@ disable-model-invocation: true # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advancing stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. -Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. +The user makes every change to the repository: they write the code, run the feedback loops, commit, and tick Acceptance Criteria. ## 1. Establish the Target @@ -33,31 +33,27 @@ Before you create the roadmap, present the goals and preferences and ask the use ## 3. Create the Milestone Roadmap -Break the plan into milestones and present them as a short roadmap without giving away their implementations. +Present the milestones as a short roadmap without giving away their implementations. -Build the roadmap from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas - what they practice is fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. +Build it from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas and practices fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the preferences ask for something else, choose another split that keeps one area in focus per milestone. -A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. The user writes the milestone's tests as part of it - they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. - -It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. +Each milestone leaves a compilable codebase whose feedback loops pass and that can be committed. The user writes the milestone's tests as part of it, since they prove it works; add manual tests where needed, for example, for UI changes. A single milestone is fine if the plan is small enough. ## 4. How to Work Through a Single Milestone -When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. +Begin each milestone with a high-level description of what it should change and which parts of the plan it addresses. Mention relevant constraints, good places to start investigating, and how the milestone will be verified, but no implementation. Ask whether the user understands it, then let them design and implement it as a whole. -Be available as a teacher while they work. Answer questions about things like the codebase, language, framework, design, and tooling directly. Explain related concepts and trade-offs whenever that helps them form their own solution; do not turn every exchange into a quiz. +While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. Do not turn every exchange into a quiz. -When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. +When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan. Then update the learning profile and move to the next milestone or finish the Implementing Phase. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone and the user created a commit, let them tick its Acceptance Criteria. Then update the learning profile and move on. ## 5. Reveal Help Progressively -Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. - -Start at the level that fits the situation and the user's stage in the area at hand, rather than mechanically beginning with a question. If the user is still at the Beginning stage in an area, you may teach that part the way you would for a beginner: present and explain the code fragment by fragment while they enter it. This is the one exception to the rule below about providing code. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. +Give the user room to solve the milestone independently, but do not let it turn into unproductive frustration. Answer questions about concepts and existing code directly, even when the answers help with the milestone. Toward the implementation itself, reveal one hint at a time: ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, name relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation and the user's stage in the area, not mechanically with a question. The user can ask for more direct help at any time; after each hint, let them try again. -Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. +Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The one exception is an area where the user is still at the Beginning stage: teach it the way the show-me skill does, presenting and explaining the code fragment by fragment while they enter it. The goal is productive struggle, not withholding information. ## 6. Update the Learning Profile @@ -80,12 +76,8 @@ Move a stage only on what you observed. Promote at most one step per plan: to Ad ## 7. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. - -Ideally, you can catch this while creating the milestones, but you might also encounter an issue while the user works through one. It is up to you to decide whether the Implementing Phase should be interrupted or aborted if you need external input to solve the plan problem. - -In the Guiding Phase, the reviewer can decide how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 8. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize what you and the user accomplished and point them to the Guiding Phase. Unless you faced plan issues, all Acceptance Criteria should be ticked. diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 3fa9175..3a2a647 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -7,9 +7,9 @@ disable-model-invocation: true # Show the User How to Implement a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by breaking it up into useful teachable milestones. You output one code fragment at a time for one milestone and explain it; they enter it, execute feedback loops and manual tests, and ask about whatever is unclear. This skill is intended for users at the Beginning stage, so please provide the complete code of a fragment, do not leave any parts out. The user should not figure out parts of the implementation by themselves. +Teach the user how to implement a Guided Coding Frozen Plan by splitting it into teachable milestones. For each milestone, you present and explain the code one fragment at a time; the user enters it, runs the feedback loops and manual tests, and asks about whatever is unclear. This skill is intended for the Beginning stage, so always present complete fragments: the user should not have to figure out any part of the implementation. -Let the user make every change to the repository themselves. Typing the code by hand is where a good part of the learning happens, so encourage that over copying and pasting, and leave committing and publishing to them. +The user makes every change to the repository, including commits. Typing the code by hand is where much of the learning happens, so encourage it over copying and pasting. ## 1. Establish the Target @@ -33,25 +33,23 @@ Before you create the roadmap, present the goals and preferences and ask the use ## 3. Create the Milestone Roadmap -Break the plan into milestones and present them as a short roadmap, not showing any code yet. +Present the milestones as a short roadmap without any code. -Build the roadmap layer by layer, so that each milestone puts one area in focus and builds upon the previous ones. For a backend feature, this could be the domain model first, then database access, followed by a service, and finally the endpoint. This way, the user can take in the concepts of one area at a time. Because nothing runs end-to-end before the last layer is in place, explain in the roadmap how the layers will connect in the end, and remind the user where the current layer sits in that picture whenever a milestone begins. If the plan has no layers, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. +Build it layer by layer, each milestone putting one area in focus and building on the previous ones. For a backend feature, this could be the domain model, then database access, a service, and finally the endpoint. Since nothing runs end-to-end before the last layer, explain in the roadmap how the layers will connect, and remind the user where the current layer sits whenever a milestone begins. If the plan has no layers, or the preferences ask for something else, choose another split that keeps one area in focus per milestone. -A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. This includes the milestone's tests - they are part of the code you present, because they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. - -It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. +Each milestone leaves a compilable codebase whose feedback loops pass and that can be committed. Its tests are part of the code you present, since they prove the milestone works; add manual tests where needed, for example, for UI changes. A single milestone is fine if that teaches the plan best. ## 4. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understand this. +Begin each milestone with a high-level description of the changes it introduces and which parts of the plan it addresses, and ask whether the user understands it. -Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. +Then present the code fragment by fragment, never all at once, so that the user builds their mental model of the codebase step by step. Verify each fragment once the user has entered it. -After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. +When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why - one question, not a quiz. It tells you whether your explanation landed. -The user might ask questions about details of the code at any point. Be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). +Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. +Once the milestone behaves as described, you verified it, and the user created a commit, let them tick its Acceptance Criteria from `- [ ]` to `- [x]`. Then update the learning profile and move on. ## 5. Update the Learning Profile @@ -74,12 +72,8 @@ Move a stage only on what you observed. Promote at most one step per plan: to Ad ## 6. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. - -Ideally, you can catch this directly while you are creating the milestones for the plan, but you might also encounter an issue while the user is working through a milestone. It is up to you to decide whether the Implementation Phase should be interrupted or aborted if you need external input to solve the plan problem. - -In the Guiding Phase, the reviewer can decide how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 7. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize what you and the user accomplished and point them to the Guiding Phase. Unless you faced plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index fe95eee..f26ac77 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -6,9 +6,9 @@ license: MIT # Coach the User Through Implementing a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for users at the Advancing stage: describe the milestone, let them implement it as a whole, review their work, and help them progress whenever they get stuck. +Teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. -Let the user make every change to the repository themselves. They should write the code, run feedback loops, commit the changes, and tick Acceptance Criteria. +The user makes every change to the repository: they write the code, run the feedback loops, commit, and tick Acceptance Criteria. ## 1. Establish the Target @@ -32,31 +32,27 @@ Before you create the roadmap, present the goals and preferences and ask the use ## 3. Create the Milestone Roadmap -Break the plan into milestones and present them as a short roadmap without giving away their implementations. +Present the milestones as a short roadmap without giving away their implementations. -Build the roadmap from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas - what they practice is fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. +Build it from vertical slices: each milestone cuts through the layers the plan touches and delivers behavior that runs end-to-end. At the Advancing stage, the user knows the individual areas and practices fitting them together, and a slice exposes a wrong design decision in the first milestone rather than the last. Keep the first slice thin, just enough to connect the layers, and widen it in the following ones. Give each slice one area in focus, ideally the one the user is least practiced in, so that you can tell what the milestone taught. If the plan does not split into slices, or the preferences ask for something else, choose another split that keeps one area in focus per milestone. -A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. The user writes the milestone's tests as part of it - they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. - -It is totally fine if the plan needs only one milestone. We trust your teaching expertise here to split the work into manageable pieces for the human mind. +Each milestone leaves a compilable codebase whose feedback loops pass and that can be committed. The user writes the milestone's tests as part of it, since they prove it works; add manual tests where needed, for example, for UI changes. A single milestone is fine if the plan is small enough. ## 4. How to Work Through a Single Milestone -When you begin a milestone, describe at a high level what it should change in the codebase and which parts of the plan it addresses. Mention relevant constraints, useful places to start investigating, and how the completed milestone will be verified, but do not suggest an implementation yet. Ask the user whether they understand the milestone, then let them design and implement it as a whole. +Begin each milestone with a high-level description of what it should change and which parts of the plan it addresses. Mention relevant constraints, good places to start investigating, and how the milestone will be verified, but no implementation. Ask whether the user understands it, then let them design and implement it as a whole. -Be available as a teacher while they work. Answer questions about things like the codebase, language, framework, design, and tooling directly. Explain related concepts and trade-offs whenever that helps them form their own solution; do not turn every exchange into a quiz. +While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. Do not turn every exchange into a quiz. -When the user signals completion, inspect what they actually changed before evaluating it. Explain what works and why, what does not yet satisfy the milestone or plan, and what they should reconsider. Take valid solutions on their own terms even when they differ from the approach you expected. Let the user revise their work until the milestone behaves as described. +When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then instruct the user how to run the applicable feedback loops and manual tests, or go through the output they bring you. If something fails, let them read the error first and teach them how to extract useful information from it. Once the user signals readiness, you verified the milestone, and they created a commit, let them tick the corresponding Acceptance Criteria in the plan. Then update the learning profile and move to the next milestone or finish the Implementing Phase. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone and the user created a commit, let them tick its Acceptance Criteria. Then update the learning profile and move on. ## 5. Reveal Help Progressively -Give the user room to solve the milestone independently, but do not let that turn into unproductive frustration. Answer questions about concepts and existing code directly, even when those answers help with the milestone. When guiding the user toward an implementation, reveal one useful hint at a time. Depending on what they need, you can ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, identify relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. - -Start at the level that fits the situation and the user's stage in the area at hand, rather than mechanically beginning with a question. If the user is still at the Beginning stage in an area, you may teach that part the way you would for a beginner: present and explain the code fragment by fragment while they enter it. This is the one exception to the rule below about providing code. The user can ask for stronger or more direct help at any time. After each hint, let them try again when they are ready. +Give the user room to solve the milestone independently, but do not let it turn into unproductive frustration. Answer questions about concepts and existing code directly, even when the answers help with the milestone. Toward the implementation itself, reveal one hint at a time: ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, name relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation and the user's stage in the area, not mechanically with a question. The user can ask for more direct help at any time; after each hint, let them try again. -Do not provide code before it is needed. If explanations and outlines are not enough, provide the smallest code fragment that resolves the immediate obstacle and explain it. Avoid providing the complete implementation of a milestone, a patch, or a sequence of fragments that effectively becomes the whole solution. The goal is productive struggle, not withholding information. +Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The one exception is an area where the user is still at the Beginning stage: teach it the way the show-me skill does, presenting and explaining the code fragment by fragment while they enter it. The goal is productive struggle, not withholding information. ## 6. Update the Learning Profile @@ -79,12 +75,8 @@ Move a stage only on what you observed. Promote at most one step per plan: to Ad ## 7. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. - -Ideally, you can catch this while creating the milestones, but you might also encounter an issue while the user works through one. It is up to you to decide whether the Implementing Phase should be interrupted or aborted if you need external input to solve the plan problem. - -In the Guiding Phase, the reviewer can decide how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 8. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize what you and the user accomplished and point them to the Guiding Phase. Unless you faced plan issues, all Acceptance Criteria should be ticked. diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 2612d8b..55b2bc2 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -6,9 +6,9 @@ license: MIT # Show the User How to Implement a Frozen Plan -Your goal is to teach the user how to implement a Guided Coding Frozen Plan by breaking it up into useful teachable milestones. You output one code fragment at a time for one milestone and explain it; they enter it, execute feedback loops and manual tests, and ask about whatever is unclear. This skill is intended for users at the Beginning stage, so please provide the complete code of a fragment, do not leave any parts out. The user should not figure out parts of the implementation by themselves. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by splitting it into teachable milestones. For each milestone, you present and explain the code one fragment at a time; the user enters it, runs the feedback loops and manual tests, and asks about whatever is unclear. This skill is intended for the Beginning stage, so always present complete fragments: the user should not have to figure out any part of the implementation. -Let the user make every change to the repository themselves. Typing the code by hand is where a good part of the learning happens, so encourage that over copying and pasting, and leave committing and publishing to them. +The user makes every change to the repository, including commits. Typing the code by hand is where much of the learning happens, so encourage it over copying and pasting. ## 1. Establish the Target @@ -32,25 +32,23 @@ Before you create the roadmap, present the goals and preferences and ask the use ## 3. Create the Milestone Roadmap -Break the plan into milestones and present them as a short roadmap, not showing any code yet. +Present the milestones as a short roadmap without any code. -Build the roadmap layer by layer, so that each milestone puts one area in focus and builds upon the previous ones. For a backend feature, this could be the domain model first, then database access, followed by a service, and finally the endpoint. This way, the user can take in the concepts of one area at a time. Because nothing runs end-to-end before the last layer is in place, explain in the roadmap how the layers will connect in the end, and remind the user where the current layer sits in that picture whenever a milestone begins. If the plan has no layers, or the user's preferences ask for something else, choose another split that keeps one area in focus per milestone. +Build it layer by layer, each milestone putting one area in focus and building on the previous ones. For a backend feature, this could be the domain model, then database access, a service, and finally the endpoint. Since nothing runs end-to-end before the last layer, explain in the roadmap how the layers will connect, and remind the user where the current layer sits whenever a milestone begins. If the plan has no layers, or the preferences ask for something else, choose another split that keeps one area in focus per milestone. -A single milestone should produce a compilable codebase where all feedback loops pass and at least one commit can be created. This includes the milestone's tests - they are part of the code you present, because they are the feedback loop that proves the milestone works. Additionally, you can instruct the user to do manual testing, e.g., for UI changes. - -It is totally fine if you break up a plan into a single milestone. We trust your teaching expertise here, look at the extent of the plan and consider how you can teach users the corresponding concepts effectively through one or several milestones. +Each milestone leaves a compilable codebase whose feedback loops pass and that can be committed. Its tests are part of the code you present, since they prove the milestone works; add manual tests where needed, for example, for UI changes. A single milestone is fine if that teaches the plan best. ## 4. How to Work Through a Single Milestone -When you begin working with the user on a new milestone, first output a description of the changes it introduces to the codebase from a high-level perspective, and which parts of the plan it addresses. Ask the user whether they understand this. +Begin each milestone with a high-level description of the changes it introduces and which parts of the plan it addresses, and ask whether the user understands it. -Then continue by presenting code to the user. Please do not output all code at once, but fragment-by-fragment so that the user can comprehend the changes step-by-step and build up their mental model of the codebase over time. Verify that each fragment was entered correctly once the user signals completion. +Then present the code fragment by fragment, never all at once, so that the user builds their mental model of the codebase step by step. Verify each fragment once the user has entered it. -After all code fragments are in place, instruct the user how to run feedback loop commands to verify the changes, or how to execute manual tests. Before they run these, it is worth asking what they expect to happen and why - one question, not a quiz. This tells you whether the explanation actually landed. +When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why - one question, not a quiz. It tells you whether your explanation landed. -The user might ask questions about details of the code at any point. Be helpful here. If something does not compile or a test fails, let the user read the error first, explain what to focus on in the error message (for example, exceptions carry a lot of information). +Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the user signals readiness, you verified the milestone behaves as described, and a commit was created by the user, let the user tick the corresponding Acceptance Criteria in the plan from `- [ ]` to `- [x]`. Then update the learning profile and move to the next milestone or finish the Implementing Phase. +Once the milestone behaves as described, you verified it, and the user created a commit, let them tick its Acceptance Criteria from `- [ ]` to `- [x]`. Then update the learning profile and move on. ## 5. Update the Learning Profile @@ -73,12 +71,8 @@ Move a stage only on what you observed. Promote at most one step per plan: to Ad ## 6. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround. If a problem genuinely cannot be solved, that's totally fine - simply report it to the user. - -Ideally, you can catch this directly while you are creating the milestones for the plan, but you might also encounter an issue while the user is working through a milestone. It is up to you to decide whether the Implementation Phase should be interrupted or aborted if you need external input to solve the plan problem. - -In the Guiding Phase, the reviewer can decide how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 7. After the Last Milestone -Summarize everything you and the user have accomplished and tell them to go over to the Guiding Phase. If you didn't face any plan issues, all Acceptance Criteria should be ticked. +Summarize what you and the user accomplished and point them to the Guiding Phase. Unless you faced plan issues, all Acceptance Criteria should be ticked. From 4d7fce76db9f6ff0704dfb9c1afbbb98459111df Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:34:33 +0200 Subject: [PATCH 17/26] feat: drop goals from the Guided Learning profile Milestone design is left to the agent, so the profile keeps only preferences and knowledge. The skills ask for preferences in the session that creates the profile and otherwise restate them with the roadmap. Also remove the stage-mismatch warning, drop the "one question, not a quiz" aside in show-me, and let users tick Acceptance Criteria before committing so that the ticks land in the milestone's commit. Co-Authored-By: Claude Opus 5.5 --- .../claude-skills/implement-coach-me/SKILL.md | 16 ++++++++-------- .../implement-coach-me/assets/profile.md | 2 -- .../claude-skills/implement-show-me/SKILL.md | 16 ++++++++-------- .../implement-show-me/assets/profile.md | 2 -- skills/guided-coding-implement-coach-me/SKILL.md | 16 ++++++++-------- .../assets/profile.md | 2 -- skills/guided-coding-implement-show-me/SKILL.md | 14 +++++++------- .../assets/profile.md | 2 -- 8 files changed, 31 insertions(+), 39 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 29d2129..5395367 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -7,9 +7,9 @@ disable-model-invocation: true # Coach the User Through Implementing a Frozen Plan -Teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. -The user makes every change to the repository: they write the code, run the feedback loops, commit, and tick Acceptance Criteria. +The user makes every change to the repository: they write the code, run the feedback loops, tick Acceptance Criteria, and commit. ## 1. Establish the Target @@ -21,15 +21,15 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr `~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: +It holds the user's **Preferences** for how to be taught, such as the language to speak or explanation before code, and their **Knowledge**: a tree of areas, each at one of three stages: - **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. - **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. - **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. +Teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. -Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. +If you created the profile in this session, ask the user how they like to be taught before you create the roadmap. Otherwise, restate the preferences in one line when you present the roadmap, so that the user can object. ## 3. Create the Milestone Roadmap @@ -47,7 +47,7 @@ While they work, answer questions about the codebase, language, framework, desig When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone and the user created a commit, let them tick its Acceptance Criteria. Then update the learning profile and move on. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick its Acceptance Criteria and commit them together with the milestone. Then update the learning profile and move on. ## 5. Reveal Help Progressively @@ -57,9 +57,9 @@ Provide code only when explanations and outlines are not enough, and then only t ## 6. Update the Learning Profile -Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. +Update the profile whenever something changed: when the user expresses a preference, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. -Change goals and preferences only as the user says. Write knowledge nodes as nested list items: +Change preferences only as the user says. Write knowledge nodes as nested list items: ```markdown - **** `` — covers , diff --git a/claude-plugin/claude-skills/implement-coach-me/assets/profile.md b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md index 4a2df76..829a49a 100644 --- a/claude-plugin/claude-skills/implement-coach-me/assets/profile.md +++ b/claude-plugin/claude-skills/implement-coach-me/assets/profile.md @@ -1,7 +1,5 @@ # Guided Learning Profile -## Goals - ## Preferences ## Knowledge diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 3a2a647..31827df 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true # Show the User How to Implement a Frozen Plan -Teach the user how to implement a Guided Coding Frozen Plan by splitting it into teachable milestones. For each milestone, you present and explain the code one fragment at a time; the user enters it, runs the feedback loops and manual tests, and asks about whatever is unclear. This skill is intended for the Beginning stage, so always present complete fragments: the user should not have to figure out any part of the implementation. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by splitting it into teachable milestones. For each milestone, you present and explain the code one fragment at a time; the user enters it, runs the feedback loops and manual tests, and asks about whatever is unclear. This skill is intended for the Beginning stage, so always present complete fragments: the user should not have to figure out any part of the implementation. The user makes every change to the repository, including commits. Typing the code by hand is where much of the learning happens, so encourage it over copying and pasting. @@ -21,15 +21,15 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr `~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: +It holds the user's **Preferences** for how to be taught, such as the language to speak or explanation before code, and their **Knowledge**: a tree of areas, each at one of three stages: - **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. - **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. - **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. +Teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. -Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. +If you created the profile in this session, ask the user how they like to be taught before you create the roadmap. Otherwise, restate the preferences in one line when you present the roadmap, so that the user can object. ## 3. Create the Milestone Roadmap @@ -45,17 +45,17 @@ Begin each milestone with a high-level description of the changes it introduces Then present the code fragment by fragment, never all at once, so that the user builds their mental model of the codebase step by step. Verify each fragment once the user has entered it. -When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why - one question, not a quiz. It tells you whether your explanation landed. +When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why. Their answer tells you whether your explanation landed. Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the milestone behaves as described, you verified it, and the user created a commit, let them tick its Acceptance Criteria from `- [ ]` to `- [x]`. Then update the learning profile and move on. +Once the milestone behaves as described and you verified it, let the user tick its Acceptance Criteria from `- [ ]` to `- [x]` and commit them together with the milestone. Then update the learning profile and move on. ## 5. Update the Learning Profile -Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. +Update the profile whenever something changed: when the user expresses a preference, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. -Change goals and preferences only as the user says. Write knowledge nodes as nested list items: +Change preferences only as the user says. Write knowledge nodes as nested list items: ```markdown - **** `` — covers , diff --git a/claude-plugin/claude-skills/implement-show-me/assets/profile.md b/claude-plugin/claude-skills/implement-show-me/assets/profile.md index 4a2df76..829a49a 100644 --- a/claude-plugin/claude-skills/implement-show-me/assets/profile.md +++ b/claude-plugin/claude-skills/implement-show-me/assets/profile.md @@ -1,7 +1,5 @@ # Guided Learning Profile -## Goals - ## Preferences ## Knowledge diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index f26ac77..c9d9237 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -6,9 +6,9 @@ license: MIT # Coach the User Through Implementing a Frozen Plan -Teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. +Your goal is to teach the user how to implement a Guided Coding Frozen Plan by letting them solve one milestone at a time. This skill is intended for the Advancing stage: describe each milestone, let the user implement it as a whole, review their work, and help them whenever they get stuck. -The user makes every change to the repository: they write the code, run the feedback loops, commit, and tick Acceptance Criteria. +The user makes every change to the repository: they write the code, run the feedback loops, tick Acceptance Criteria, and commit. ## 1. Establish the Target @@ -20,15 +20,15 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr `~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: +It holds the user's **Preferences** for how to be taught, such as the language to speak or explanation before code, and their **Knowledge**: a tree of areas, each at one of three stages: - **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. - **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. - **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. +Teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. -Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. +If you created the profile in this session, ask the user how they like to be taught before you create the roadmap. Otherwise, restate the preferences in one line when you present the roadmap, so that the user can object. ## 3. Create the Milestone Roadmap @@ -46,7 +46,7 @@ While they work, answer questions about the codebase, language, framework, desig When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone and the user created a commit, let them tick its Acceptance Criteria. Then update the learning profile and move on. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick its Acceptance Criteria and commit them together with the milestone. Then update the learning profile and move on. ## 5. Reveal Help Progressively @@ -56,9 +56,9 @@ Provide code only when explanations and outlines are not enough, and then only t ## 6. Update the Learning Profile -Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. +Update the profile whenever something changed: when the user expresses a preference, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. -Change goals and preferences only as the user says. Write knowledge nodes as nested list items: +Change preferences only as the user says. Write knowledge nodes as nested list items: ```markdown - **** `` — covers , diff --git a/skills/guided-coding-implement-coach-me/assets/profile.md b/skills/guided-coding-implement-coach-me/assets/profile.md index 4a2df76..829a49a 100644 --- a/skills/guided-coding-implement-coach-me/assets/profile.md +++ b/skills/guided-coding-implement-coach-me/assets/profile.md @@ -1,7 +1,5 @@ # Guided Learning Profile -## Goals - ## Preferences ## Knowledge diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 55b2bc2..4973864 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -20,15 +20,15 @@ Verify that the plan is frozen: its file name has a timestamp, and it has a `*Fr `~/.guided-learning/profile.md` is the memory of Guided Learning across sessions. If it is missing, run `git init -b main "$HOME/.guided-learning"` unless that folder already is a git repository, copy `assets/profile.md` relative to this skill file there, and commit it. -It holds the user's **Goals**, their **Preferences** for how to be taught, and their **Knowledge**: a tree of areas, each at one of three stages: +It holds the user's **Preferences** for how to be taught, such as the language to speak or explanation before code, and their **Knowledge**: a tree of areas, each at one of three stages: - **Beginning**: new to a domain, needs to learn the fundamental concepts and mechanisms, mostly by copying information. Adaptation and transformation of these do not happen yet. - **Advancing**: fluent in the fundamentals and able to adapt them to new problems. Does not question the fundamentals. - **Mastering**: able to adapt and transform concepts quickly, and to question or replace the fundamentals themselves. -Let the goals decide which parts of the plan deserve a milestone of their own, and teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. +Teach the way the preferences ask. Let the stages of the areas the plan draws on decide how large you make the milestones, how much you explain, and how much help you offer at the start. The deepest node covering an area wins; technology and discipline nodes each apply to their own part of the work. Treat areas the profile does not cover as being at the stage this skill is intended for. What you observe always takes precedence over the profile. -Before you create the roadmap, present the goals and preferences and ask the user whether anything has changed, or ask for them if there are none yet. If the profile places the user at a different stage than this skill is intended for across most of the plan, point that out in the same message and let them decide whether to continue. +If you created the profile in this session, ask the user how they like to be taught before you create the roadmap. Otherwise, restate the preferences in one line when you present the roadmap, so that the user can object. ## 3. Create the Milestone Roadmap @@ -44,17 +44,17 @@ Begin each milestone with a high-level description of the changes it introduces Then present the code fragment by fragment, never all at once, so that the user builds their mental model of the codebase step by step. Verify each fragment once the user has entered it. -When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why - one question, not a quiz. It tells you whether your explanation landed. +When all fragments are in place, explain how to run the feedback loops or manual tests. Before the user runs them, ask what they expect to happen and why. Their answer tells you whether your explanation landed. Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the milestone behaves as described, you verified it, and the user created a commit, let them tick its Acceptance Criteria from `- [ ]` to `- [x]`. Then update the learning profile and move on. +Once the milestone behaves as described and you verified it, let the user tick its Acceptance Criteria from `- [ ]` to `- [x]` and commit them together with the milestone. Then update the learning profile and move on. ## 5. Update the Learning Profile -Update the profile whenever something changed: after the user answered your question about goals and preferences, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. +Update the profile whenever something changed: when the user expresses a preference, after each milestone once the user committed it, and when the user stops early. Re-read the file right before you edit it, and commit to `main` using `git -C "$HOME/.guided-learning"` with a Conventional Commits message whose body states what you observed. Never create branches or push, and keep learning notes out of the repository you are working in. -Change goals and preferences only as the user says. Write knowledge nodes as nested list items: +Change preferences only as the user says. Write knowledge nodes as nested list items: ```markdown - **** `` — covers , diff --git a/skills/guided-coding-implement-show-me/assets/profile.md b/skills/guided-coding-implement-show-me/assets/profile.md index 4a2df76..829a49a 100644 --- a/skills/guided-coding-implement-show-me/assets/profile.md +++ b/skills/guided-coding-implement-show-me/assets/profile.md @@ -1,7 +1,5 @@ # Guided Learning Profile -## Goals - ## Preferences ## Knowledge From a4b426779f66784e0c3665cfe8f96acbf1b6fe93 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:40:23 +0200 Subject: [PATCH 18/26] test: enforce shared content across skills The Guided Learning skills now share every section by default, and only the sections declared as intentionally different may diverge. A second test keeps that declaration from going stale. Lists that follow a shared lead-in line, such as the timestamp commands in freeze-plan and write-deviations, must also stay identical. Co-Authored-By: Claude Opus 5.5 --- .../PackageValidationTests.cs | 176 +++++++++++++++++- 1 file changed, 167 insertions(+), 9 deletions(-) diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index 44eace2..617db68 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -45,11 +45,26 @@ public sealed class PackageValidationTests "guided-coding-implement-show-me" ]; + // The Guided Learning skills share every section except these, which differ on purpose. + private static readonly string[] GuidedLearningSectionsThatDiffer = + [ + "Create the Milestone Roadmap", + "How to Work Through a Single Milestone", + "Reveal Help Progressively" + ]; + private static readonly (string Section, string[] SkillNames)[] SharedSections = [ - ("Establish the Target", ["guided-coding-implement", .. GuidedLearningSkillNames]), - ("Read the Learning Profile", GuidedLearningSkillNames), - ("Update the Learning Profile", GuidedLearningSkillNames) + ("Establish the Target", ["guided-coding-implement", .. GuidedLearningSkillNames]) + ]; + + // A snippet is the list that follows its lead-in line. + private static readonly (string LeadIn, string[] SkillNames)[] SharedSnippets = + [ + ( + "Use these commands to get it:", + ["guided-coding-freeze-plan", "guided-coding-write-deviations"] + ) ]; private static readonly string[] ForbiddenFrontmatterFields = @@ -69,6 +84,14 @@ private static readonly (string Section, string[] SkillNames)[] SharedSections = private static string RepositoryRoot { get; } = FindRepositoryRoot(); + public static TheoryData SharedSectionNames => new ( + SharedSections.Select(shared => shared.Section) + ); + + public static TheoryData SharedSnippetLeadIns => new ( + SharedSnippets.Select(shared => shared.LeadIn) + ); + [Fact] public void ManifestsUseTheSamePackageMetadata() { @@ -308,10 +331,6 @@ public void ClaudePluginContainsTheRepositoryLicense() ); } - public static TheoryData SharedSectionNames => new ( - SharedSections.Select(shared => shared.Section) - ); - [Theory] [MemberData(nameof(SharedSectionNames))] public void SkillsSharingASectionKeepItIdentical(string sectionName) @@ -341,6 +360,111 @@ public void SkillsSharingASectionKeepItIdentical(string sectionName) } } + [Fact] + public void GuidedLearningSkillsShareAllUndeclaredSections() + { + var skills = GuidedLearningSkillNames + .Select( + skillName => ( + SkillName: skillName, + Path: Path.Combine(RepositoryRoot, "skills", skillName, "SKILL.md") + ) + ) + .Select( + skill => ( + skill.SkillName, + skill.Path, + Headings: ReadSectionHeadings(skill.Path) + .Where(heading => !GuidedLearningSectionsThatDiffer.Contains(heading)) + .ToArray() + ) + ) + .ToArray(); + var reference = skills[0]; + + foreach (var skill in skills[1..]) + { + var unmatched = reference + .Headings + .Except(skill.Headings) + .Concat(skill.Headings.Except(reference.Headings)) + .ToArray(); + Assert.True( + reference.Headings.SequenceEqual(skill.Headings), + $"{reference.SkillName} and {skill.SkillName} have different sections " + + (unmatched.Length > 0 ? + $"(unmatched: {string.Join(", ", unmatched.Select(heading => $"\"{heading}\""))}). " : + "(same sections in a different order). ") + + "Guided Learning skills share every section by default; add the section to the other " + + $"skill or declare it in {nameof(GuidedLearningSectionsThatDiffer)}." + ); + + foreach (var heading in reference.Headings) + { + Assert.True( + string.Equals( + ReadSectionBody(reference.Path, heading), + ReadSectionBody(skill.Path, heading), + StringComparison.Ordinal + ), + $"\"{heading}\" differs between {reference.SkillName} and {skill.SkillName}. " + + "Apply the change to both skills, or declare the section in " + + $"{nameof(GuidedLearningSectionsThatDiffer)} if it should differ." + ); + } + } + } + + [Fact] + public void GuidedLearningSectionsThatDifferExist() + { + var headings = GuidedLearningSkillNames + .SelectMany( + skillName => ReadSectionHeadings( + Path.Combine(RepositoryRoot, "skills", skillName, "SKILL.md") + ) + ) + .ToHashSet(StringComparer.Ordinal); + + foreach (var heading in GuidedLearningSectionsThatDiffer) + { + Assert.True( + headings.Contains(heading), + $"\"{heading}\" is declared in {nameof(GuidedLearningSectionsThatDiffer)} " + + "but no Guided Learning skill has this section anymore." + ); + } + } + + [Theory] + [MemberData(nameof(SharedSnippetLeadIns))] + public void SkillsSharingASnippetKeepItIdentical(string leadIn) + { + var skillNames = SharedSnippets.Single(shared => shared.LeadIn == leadIn).SkillNames; + var snippets = skillNames + .Select( + skillName => ( + SkillName: skillName, + Lines: ReadSnippet( + Path.Combine(RepositoryRoot, "skills", skillName, "SKILL.md"), + leadIn + ) + ) + ) + .ToArray(); + var reference = snippets[0]; + + foreach (var snippet in snippets[1..]) + { + Assert.True( + reference.Lines.SequenceEqual(snippet.Lines, StringComparer.Ordinal), + $"The list after \"{leadIn}\" differs between {reference.SkillName} and " + + $"{snippet.SkillName}. The snippet is duplicated on purpose because skills are " + + "standalone; apply the change to every skill that shares it." + ); + } + } + [Fact] public void GuidedLearningSkillsShipTheSameProfileTemplate() { @@ -491,10 +615,26 @@ private static string ReadSectionBody(string path, string heading) } private static bool IsSectionHeading(string line, string heading) + { + return string.Equals(ReadHeadingText(line), heading, StringComparison.Ordinal); + } + + private static string[] ReadSectionHeadings(string path) + { + return File + .ReadAllText(path) + .Replace("\r\n", "\n", StringComparison.Ordinal) + .Split('\n') + .Select(ReadHeadingText) + .OfType() + .ToArray(); + } + + private static string? ReadHeadingText(string line) { if (!line.StartsWith("## ", StringComparison.Ordinal)) { - return false; + return null; } // Section numbers differ between skills, so match on the heading text alone. @@ -505,7 +645,25 @@ private static bool IsSectionHeading(string line, string heading) text = text[(separator + 2)..]; } - return string.Equals(text, heading, StringComparison.Ordinal); + return text; + } + + private static string[] ReadSnippet(string path, string leadIn) + { + var lines = File.ReadAllText(path).Replace("\r\n", "\n", StringComparison.Ordinal).Split('\n'); + var matches = lines + .Select((line, index) => (Line: line, Index: index)) + .Where(candidate => candidate.Line.TrimEnd().EndsWith(leadIn, StringComparison.Ordinal)) + .ToArray(); + Assert.True(matches.Length == 1, $"{path} must contain \"{leadIn}\" exactly once."); + + var snippet = lines + .Skip(matches[0].Index + 1) + .SkipWhile(string.IsNullOrWhiteSpace) + .TakeWhile(line => line.StartsWith("- ", StringComparison.Ordinal)) + .ToArray(); + Assert.True(snippet.Length > 0, $"No list follows \"{leadIn}\" in {path}."); + return snippet; } private static SortedDictionary EnumerateResourceFiles( From 2a18eefa6af6049650973d14c2a44b321d3e5e27 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:49:09 +0200 Subject: [PATCH 19/26] docs: refine milestone completion in the Guided Learning skills Users now tick only the Acceptance Criteria a milestone fully satisfies, as early layers in show-me often complete none. Plan issues are worked out and taught rather than fixed by the agent, and each milestone adds nodes for areas the profile does not cover yet. Also drop the undefined term "pass" and coach-me's quiz aside. Co-Authored-By: Claude Opus 5.5 --- .../claude-skills/implement-coach-me/SKILL.md | 10 +++++----- claude-plugin/claude-skills/implement-show-me/SKILL.md | 8 ++++---- skills/guided-coding-implement-coach-me/SKILL.md | 10 +++++----- skills/guided-coding-implement-show-me/SKILL.md | 8 ++++---- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 5395367..47f61a6 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -43,11 +43,11 @@ Each milestone leaves a compilable codebase whose feedback loops pass and that c Begin each milestone with a high-level description of what it should change and which parts of the plan it addresses. Mention relevant constraints, good places to start investigating, and how the milestone will be verified, but no implementation. Ask whether the user understands it, then let them design and implement it as a whole. -While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. Do not turn every exchange into a quiz. +While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick its Acceptance Criteria and commit them together with the milestone. Then update the learning profile and move on. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick the Acceptance Criteria it fully satisfies, if any, and commit them together with the milestone. Then update the learning profile and move on. ## 5. Reveal Help Progressively @@ -70,13 +70,13 @@ Knowledge that would survive a switch to another technology stack belongs to a d - **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. - **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. +After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, work out a solution or workaround and teach it like any other part of the plan; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 8. After the Last Milestone diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 31827df..13a0003 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -49,7 +49,7 @@ When all fragments are in place, explain how to run the feedback loops or manual Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the milestone behaves as described and you verified it, let the user tick its Acceptance Criteria from `- [ ]` to `- [x]` and commit them together with the milestone. Then update the learning profile and move on. +Once the milestone behaves as described and you verified it, let the user tick the Acceptance Criteria it fully satisfies, if any, from `- [ ]` to `- [x]`, and commit them together with the milestone. Then update the learning profile and move on. ## 5. Update the Learning Profile @@ -66,13 +66,13 @@ Knowledge that would survive a switch to another technology stack belongs to a d - **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. - **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. +After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, work out a solution or workaround and teach it like any other part of the plan; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 7. After the Last Milestone diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index c9d9237..e7c5c2a 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -42,11 +42,11 @@ Each milestone leaves a compilable codebase whose feedback loops pass and that c Begin each milestone with a high-level description of what it should change and which parts of the plan it addresses. Mention relevant constraints, good places to start investigating, and how the milestone will be verified, but no implementation. Ask whether the user understands it, then let them design and implement it as a whole. -While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. Do not turn every exchange into a quiz. +While they work, answer questions about the codebase, language, framework, design, and tooling directly, and explain concepts and trade-offs whenever that helps them form their own solution. When the user signals completion, inspect what they actually changed. Explain what works and why, what does not yet satisfy the milestone or plan, and what to reconsider. Take valid solutions on their own terms, even when they differ from what you expected, and let the user revise until the milestone behaves as described. -Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick its Acceptance Criteria and commit them together with the milestone. Then update the learning profile and move on. +Then explain how to run the feedback loops and manual tests, or go through the output the user brings. When something fails, let them read the error first and teach them how to extract what matters from it. Once you verified the milestone, let the user tick the Acceptance Criteria it fully satisfies, if any, and commit them together with the milestone. Then update the learning profile and move on. ## 5. Reveal Help Progressively @@ -69,13 +69,13 @@ Knowledge that would survive a switch to another technology stack belongs to a d - **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. - **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. +After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, work out a solution or workaround and teach it like any other part of the plan; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 8. After the Last Milestone diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index 4973864..f739760 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -48,7 +48,7 @@ When all fragments are in place, explain how to run the feedback loops or manual Answer questions about the code at any point. When something does not compile or a test fails, let the user read the error first, then point out what to focus on, for example, the information an exception carries. -Once the milestone behaves as described and you verified it, let the user tick its Acceptance Criteria from `- [ ]` to `- [x]` and commit them together with the milestone. Then update the learning profile and move on. +Once the milestone behaves as described and you verified it, let the user tick the Acceptance Criteria it fully satisfies, if any, from `- [ ]` to `- [x]`, and commit them together with the milestone. Then update the learning profile and move on. ## 5. Update the Learning Profile @@ -65,13 +65,13 @@ Knowledge that would survive a switch to another technology stack belongs to a d - **Technologies**: `` → `` → ``, for example `.NET` → `EF Core` → `change tracking`. The ecosystem is the one whose package manager distributes the technology, so React belongs to `JavaScript`, which includes TypeScript. A technology outside any ecosystem, such as PostgreSQL, is a root itself. - **Disciplines**: `` → `` → ``, for example `Automated testing` → `Test doubles` → `fakes`. Roots are limited to Algorithms and data structures, Software design and architecture, Automated testing, Data modeling and persistence, Security, Concurrency and distributed systems, Performance, Delivery and operations, and User interface design. Ask the user before you add another one. -Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. +After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. A pass with the show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues -If a plan decision is wrong or an Acceptance Criterion cannot be met as written, try to solve it or find a workaround; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. +If a plan decision is wrong or an Acceptance Criterion cannot be met as written, work out a solution or workaround and teach it like any other part of the plan; if you cannot, report it to the user. Ideally, you catch this while creating the roadmap. You decide whether a problem that needs external input interrupts or aborts the Implementing Phase. In the Guiding Phase, the reviewer decides how to proceed with your findings. ## 7. After the Last Milestone From d9ab04af9cefa03c1f1e8527064e4a76df89c201 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Thu, 24 Sep 2026 22:53:10 +0200 Subject: [PATCH 20/26] docs: document Guided Learning in the README and changelog The README explains which Guided Learning skill fits which stage and how the private, git-backed profile at ~/.guided-learning/ works. The changelog records the profile, and the manifests gain a "learning" keyword. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 3 ++- CHANGELOG.md | 1 + README.md | 18 ++++++++++++++++++ claude-plugin/.claude-plugin/plugin.json | 3 ++- plugin.json | 3 ++- 5 files changed, 25 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3eb0176..4bea828 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -22,7 +22,8 @@ "tags": [ "guided-coding", "software-engineering", - "planning" + "planning", + "learning" ] } ] diff --git a/CHANGELOG.md b/CHANGELOG.md index f9a9249..b4f1afd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,3 +11,4 @@ All notable changes to Guided Coding are documented here. - Distribute Guided Coding as portable Agent Skills and an Agent Plugin. - Generate a Claude Code adapter with concise, manually invoked skill names. - Add learning workflows for implementing plans through worked examples or coached problem solving. +- Track learning progress across sessions in a private, git-backed Guided Learning profile. diff --git a/README.md b/README.md index f38febc..abe891b 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,24 @@ The full method is documented at All workflows require explicit user invocation. +## Guided Learning + +With `guided-coding-implement-show-me` and `guided-coding-implement-coach-me`, you implement a +frozen plan yourself while the agent teaches you. Pick the skill that matches your stage in the +plan's domain: + +| Stage | Skill | How the agent teaches | +| --- | --- | --- | +| **Beginning**: new to the domain, learning its fundamental concepts | `guided-coding-implement-show-me` | Splits the plan into layers and presents complete code, fragment by fragment, for you to type and discuss. | +| **Advancing**: fluent in the fundamentals, adapting them to new problems | `guided-coding-implement-coach-me` | Splits the plan into vertical slices that you implement yourself, reviews your work, and reveals hints progressively. | +| **Mastering**: questioning and replacing the fundamentals themselves | `guided-coding-implement` | Implements the plan while you guide it. | + +Both skills track your progress in `~/.guided-learning/profile.md`: 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 (Git 2.28 or later), commits every update with a +message stating what it observed, and never pushes. The profile never ends up in your project +repository, and you can edit or delete it at any time. + ## Install ### Agent Skills diff --git a/claude-plugin/.claude-plugin/plugin.json b/claude-plugin/.claude-plugin/plugin.json index 32372f2..bbe18c6 100644 --- a/claude-plugin/.claude-plugin/plugin.json +++ b/claude-plugin/.claude-plugin/plugin.json @@ -14,7 +14,8 @@ "keywords": [ "guided-coding", "software-engineering", - "planning" + "planning", + "learning" ], "skills": "./claude-skills" } diff --git a/plugin.json b/plugin.json index db95967..2d5dcd1 100644 --- a/plugin.json +++ b/plugin.json @@ -13,6 +13,7 @@ "keywords": [ "guided-coding", "software-engineering", - "planning" + "planning", + "learning" ] } From 77afa6cfcbb207a9cb1a6d1df77aa252ee45708d Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:02:05 +0200 Subject: [PATCH 21/26] docs: restructure infos about Guided Learning skills Signed-off-by: Kenny Pflug --- README.md | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index abe891b..da4a520 100644 --- a/README.md +++ b/README.md @@ -21,29 +21,23 @@ The full method is documented at | `guided-coding-review-plan` | Review a plan draft against the repository (use in fresh conversation). | | `guided-coding-freeze-plan` | Freeze a plan by timestamping its file name and title. | | `guided-coding-implement` | Implement a frozen plan and verify it through the repository's feedback loops. | -| `guided-coding-implement-show-me` | Implement a frozen plan through worked code examples that you enter and discuss. | -| `guided-coding-implement-coach-me` | Implement a frozen plan yourself through coached, verifiable milestones. | +| `guided-coding-implement-show-me` | (Guided Learning) Implement a frozen plan step-by-step where the agent shows you complete code fragments that you enter and discuss. | +| `guided-coding-implement-coach-me` | (Guided Learning) Implement a frozen plan yourself through coached, verifiable milestones. The agent reveals implementation hints progressively. | | `guided-coding-write-deviations` | Summarize follow-up plans and record material implementation differences. | -All workflows require explicit user invocation. +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 -With `guided-coding-implement-show-me` and `guided-coding-implement-coach-me`, you implement a -frozen plan yourself while the agent teaches you. Pick the skill that matches your stage in the -plan's domain: +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. | Stage | Skill | How the agent teaches | | --- | --- | --- | -| **Beginning**: new to the domain, learning its fundamental concepts | `guided-coding-implement-show-me` | Splits the plan into layers and presents complete code, fragment by fragment, for you to type and discuss. | -| **Advancing**: fluent in the fundamentals, adapting them to new problems | `guided-coding-implement-coach-me` | Splits the plan into vertical slices that you implement yourself, reviews your work, and reveals hints progressively. | -| **Mastering**: questioning and replacing the fundamentals themselves | `guided-coding-implement` | Implements the plan while you guide it. | +| **Beginning** | `guided-coding-implement-show-me` | Splits the plan into layers and presents complete code, fragment by fragment, for you to type and discuss. This is useful when you are new to a topic and want to quickly learn the fundamental concepts. The agent is always ready for your questions. | +| **Advancing** | `guided-coding-implement-coach-me` | Splits the plan into vertical slices that you implement yourself, reviews your work, and reveals hints progressively. This is useful when you are proficient at a topic and want more of a challenge to master your skills. | +| **Mastering** | `guided-coding-implement` | Regular Guided Coding: the Coding Agent implements the plan for you. No teaching involved. | -Both skills track your progress in `~/.guided-learning/profile.md`: 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 (Git 2.28 or later), commits every update with a -message stating what it observed, and never pushes. The profile never ends up in your project -repository, and you can edit or delete it at any time. +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. ## Install @@ -56,7 +50,7 @@ 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. +repositories. If you want to update, use the following command: @@ -85,7 +79,7 @@ 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. +> ⚠️ Restart Claude Code afterwards. Only then will the updated skills be picked up. ### Agent Plugin clients From a650c23c32e57aa010b0f65ed105bbb2536aeed5 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:25:35 +0200 Subject: [PATCH 22/26] feat: remove references between show-me and coach-me skill Signed-off-by: Kenny Pflug --- claude-plugin/claude-skills/implement-coach-me/SKILL.md | 4 ++-- claude-plugin/claude-skills/implement-show-me/SKILL.md | 2 +- skills/guided-coding-implement-coach-me/SKILL.md | 4 ++-- skills/guided-coding-implement-show-me/SKILL.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/claude-plugin/claude-skills/implement-coach-me/SKILL.md b/claude-plugin/claude-skills/implement-coach-me/SKILL.md index 47f61a6..27cde9d 100644 --- a/claude-plugin/claude-skills/implement-coach-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-coach-me/SKILL.md @@ -53,7 +53,7 @@ Then explain how to run the feedback loops and manual tests, or go through the o Give the user room to solve the milestone independently, but do not let it turn into unproductive frustration. Answer questions about concepts and existing code directly, even when the answers help with the milestone. Toward the implementation itself, reveal one hint at a time: ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, name relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation and the user's stage in the area, not mechanically with a question. The user can ask for more direct help at any time; after each hint, let them try again. -Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The one exception is an area where the user is still at the Beginning stage: teach it the way the show-me skill does, presenting and explaining the code fragment by fragment while they enter it. The goal is productive struggle, not withholding information. +Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The goal is productive struggle, not withholding information. ## 6. Update the Learning Profile @@ -72,7 +72,7 @@ Knowledge that would survive a switch to another technology stack belongs to a d After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues diff --git a/claude-plugin/claude-skills/implement-show-me/SKILL.md b/claude-plugin/claude-skills/implement-show-me/SKILL.md index 13a0003..c905f0e 100644 --- a/claude-plugin/claude-skills/implement-show-me/SKILL.md +++ b/claude-plugin/claude-skills/implement-show-me/SKILL.md @@ -68,7 +68,7 @@ Knowledge that would survive a switch to another technology stack belongs to a d After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. This skill never moves a node above Beginning, because it hands over the implementation. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues diff --git a/skills/guided-coding-implement-coach-me/SKILL.md b/skills/guided-coding-implement-coach-me/SKILL.md index e7c5c2a..a3a7b69 100644 --- a/skills/guided-coding-implement-coach-me/SKILL.md +++ b/skills/guided-coding-implement-coach-me/SKILL.md @@ -52,7 +52,7 @@ Then explain how to run the feedback loops and manual tests, or go through the o Give the user room to solve the milestone independently, but do not let it turn into unproductive frustration. Answer questions about concepts and existing code directly, even when the answers help with the milestone. Toward the implementation itself, reveal one hint at a time: ask a focused question, restate an important invariant, point to similar code or documentation, teach the missing concept, name relevant APIs or types, describe how responsibilities interact, or give a precise implementation outline. Start at the level that fits the situation and the user's stage in the area, not mechanically with a question. The user can ask for more direct help at any time; after each hint, let them try again. -Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The one exception is an area where the user is still at the Beginning stage: teach it the way the show-me skill does, presenting and explaining the code fragment by fragment while they enter it. The goal is productive struggle, not withholding information. +Provide code only when explanations and outlines are not enough, and then only the smallest fragment that resolves the immediate obstacle, with an explanation. Never hand over the milestone's complete implementation, a patch, or a series of fragments that amounts to one. The goal is productive struggle, not withholding information. ## 6. Update the Learning Profile @@ -71,7 +71,7 @@ Knowledge that would survive a switch to another technology stack belongs to a d After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 7. Handle Plan Issues diff --git a/skills/guided-coding-implement-show-me/SKILL.md b/skills/guided-coding-implement-show-me/SKILL.md index f739760..7dde13a 100644 --- a/skills/guided-coding-implement-show-me/SKILL.md +++ b/skills/guided-coding-implement-show-me/SKILL.md @@ -67,7 +67,7 @@ Knowledge that would survive a switch to another technology stack belongs to a d After each milestone, add a node for every area it drew on that the profile does not cover yet. Reuse existing nodes, and name technologies the way their official documentation does. Add a child only when its stage differs from its parent's; otherwise, list it in the parent's optional `covers`. -Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. The show-me skill never moves a node above Beginning, because it hands over the implementation; suggest the coach-me skill instead. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. +Move a stage only on what you observed. Promote at most one step per plan: to Advancing when the user carried a milestone in that area without being handed the implementation, to Mastering when they shaped the design or pushed back on the plan for a reason that held up. Correct a wrong node any distance. This skill never moves a node above Beginning, because it hands over the implementation. Change the node where you saw the evidence, and a parent only when your evidence covers all of it. ## 6. Handle Plan Issues From d3de286ad4fcf7269783c59ed61856c00a3d7d1c Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:26:43 +0200 Subject: [PATCH 23/26] chore: fix Guided Coding Frozen Plan wording in implement skill Signed-off-by: Kenny Pflug --- claude-plugin/claude-skills/implement/SKILL.md | 2 +- skills/guided-coding-implement/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/claude-plugin/claude-skills/implement/SKILL.md b/claude-plugin/claude-skills/implement/SKILL.md index ef44e10..d06ee4b 100644 --- a/claude-plugin/claude-skills/implement/SKILL.md +++ b/claude-plugin/claude-skills/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: "Implement a Frozen Guided Coding Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user." +description: "Implement a Guided Coding Frozen Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user." license: "MIT" disable-model-invocation: true --- diff --git a/skills/guided-coding-implement/SKILL.md b/skills/guided-coding-implement/SKILL.md index 23727ce..2330b11 100644 --- a/skills/guided-coding-implement/SKILL.md +++ b/skills/guided-coding-implement/SKILL.md @@ -1,6 +1,6 @@ --- name: guided-coding-implement -description: Implement a Frozen Guided Coding Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user. +description: Implement a Guided Coding Frozen Plan independently and verify the implementation through the repository's feedback loops. Run only when explicitly requested by the user. license: MIT --- From 02c2385ec6dced0c05be4162cdc2deaa77851b2b Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:27:21 +0200 Subject: [PATCH 24/26] chore: rephrase Guided Learning entry in CHANGELOG.md Signed-off-by: Kenny Pflug --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4f1afd..6dab3d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,5 +10,4 @@ All notable changes to Guided Coding are documented here. - Require Plan Deviations documents for material departures from frozen plans. - Distribute Guided Coding as portable Agent Skills and an Agent Plugin. - Generate a Claude Code adapter with concise, manually invoked skill names. -- Add learning workflows for implementing plans through worked examples or coached problem solving. -- Track learning progress across sessions in a private, git-backed Guided Learning profile. +- Add Guided Learning skills for Beginners and Advanced devs, track learning progress across sessions in a private, git-backed Guided Learning profile located at `$HOME/.guided-learning/profile.md`. From a41326c731f90b8061a950a76329d7b807322694 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:27:39 +0200 Subject: [PATCH 25/26] docs: fix missing whitespace in AGENTS.md Signed-off-by: Kenny Pflug --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 882216e..89b7d89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ This repository contains skills for Guided Coding. The root package supports the ## Manifests and versions -Keep the version synchronized across `plugin.json`, `claude-plugin/.claude-plugin/plugin.json`,`.claude-plugin/marketplace.json`, and release tags. +Keep the version synchronized across `plugin.json`, `claude-plugin/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and release tags. Use Conventional Commits messages. From c82d888eeff0435cc30622ab03b33178bbc56805 Mon Sep 17 00:00:00 2001 From: Kenny Pflug Date: Fri, 25 Sep 2026 07:33:27 +0200 Subject: [PATCH 26/26] test: the "Update the Learning Profile" are no longer considered equal Signed-off-by: Kenny Pflug --- tests/GuidedCoding.Tests/PackageValidationTests.cs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/GuidedCoding.Tests/PackageValidationTests.cs b/tests/GuidedCoding.Tests/PackageValidationTests.cs index 617db68..05e9f51 100644 --- a/tests/GuidedCoding.Tests/PackageValidationTests.cs +++ b/tests/GuidedCoding.Tests/PackageValidationTests.cs @@ -50,7 +50,8 @@ public sealed class PackageValidationTests [ "Create the Milestone Roadmap", "How to Work Through a Single Milestone", - "Reveal Help Progressively" + "Reveal Help Progressively", + "Update the Learning Profile" ]; private static readonly (string Section, string[] SkillNames)[] SharedSections =