| name | klum-implement-issue |
| description | Implement one approved KlumAST issue or tracer-bullet slice with module-appropriate Spock coverage, Groovy 3/4/5 compatibility checks, and synchronized release-facing documentation. Use after issue intent and architectural decisions are settled. |
Implement a KlumAST Issue
Deliver one approved behavior slice without silently making new architecture decisions.
Load the contract
Read AGENTS.md, CONTEXT.md, docs/agents/coding-style.md, docs/agents/testing.md, docs/agents/commits.md, docs/agents/pull-requests.md, the canonical issue, architecture map, linked ADRs, implementation plan, and wiki contract. Confirm the requested slice and its acceptance criteria before editing.
Stop and report a decision conflict when the requested behavior contradicts an ADR, Builder-first lifecycle invariant, generated/public contract, or confirmed issue. Route unresolved design back to $klum-grill-issue or $klum-plan-design.
Create a new branch dedicated to the issue from the agreed base, or confirm the current branch was newly created for this issue. Commit completed reasoning steps without asking, following docs/agents/commits.md; every TDD commit must complete its red-to-green cycle.
Implement at the correct seam
Respect module boundaries and existing conventions. Put coverage where the behavior lives:
- ordinary Spock specifications in
<module>/src/test/groovy/
- reusable harnesses in existing
src/testFixtures/groovy/ trees
- compilation or lifecycle scenarios in
klum-ast/src/test/scenarios/
- Gradle behavior in
klum-ast-gradle-plugin/src/test/groovy/
Keep the change focused. Preserve Java 17, license headers, generated-code conventions, structural immutability, Construction-session ownership, and Materialization/validation ordering unless the accepted contract explicitly changes them.
Verify progressively
Follow docs/agents/testing.md: start with the narrowest Groovy 3 test, then the affected module suite. Run Groovy 4 and 5 compatibility lanes when touching compiler APIs, AST behavior, Groovy syntax, dependencies, or before final handoff. Run root check for repository-wide or release-critical changes.
Synchronize durable artifacts
Update only what the behavior requires:
- formal decision in
docs/adr/
- implementation reasoning in
docs/implementation/
- user behavior or migration in
wiki/, including _Sidebar.md when navigation changes
- implemented release change in
CHANGES.md
- canonical issue/PR links according to
docs/agents/pull-requests.md
Run the applicable local code review against the issue branch base, commit its fixes, then review and improve the commit sequence under docs/agents/commits.md before first publication. Re-run the required checks after rewriting history.
When responding to pull-request review feedback, preserve the commits in the reviewed revision and add focused follow-up
commits. Cluster related findings in one commit, such as Address SonarCloud findings, or split independent concerns when
that improves reviewability. Push the resulting changes and post the consolidated disposition required by
docs/agents/pull-requests.md, including addressed and intentionally unchanged observations plus validation evidence.
Finish with changed behavior, affected modules, tests and results, documentation changes, compatibility implications, commit-history review, and remaining follow-ups. Finish only when every acceptance criterion has evidence, the final documentation matches the branch state unless explicitly excluded, and the worktree contains no unrelated edits.
