commit 543f2befd9c8e7b7f8394aaff1a2cf83287208d5 Author: Erhan Keseli Date: Sun Aug 23 15:58:41 2026 +0200 Initial commit: ABAP playbook skill diff --git a/README.md b/README.md new file mode 100644 index 0000000..befb2b1 --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# abap-playbook + +A Claude Code skill for ABAP development through the +[EPOD ADT MCP Server](https://git.epod.dev/erhan/epod-adt-mcp-updatesite). + +The skill runs larger development tasks through a phased playbook: +discovery, plan, user approval, implementation, verification. Each phase is +bound to the token-efficient MCP tools — member lists before source, element +reads and writes instead of full pulls, one combined check call — and each +phase ends with a gate. + +Small tasks do not open the playbook. The skill applies process only where +the task creates a new object, changes two or more objects, or must keep +the current behaviour. + +## Installation + +Copy the skill folder into your Claude Code skills directory: + +``` +git clone https://git.epod.dev/erhan/abap-playbook.git +cp -r abap-playbook ~/.claude/skills/abap-playbook +``` + +Requirements: Claude Code with the EPOD ADT MCP Server connected. The skill +uses `sap_object_members`, `sap_pull_source` with `element`, +`sap_push_element`, `sap_push_source`, `sap_check_object`, and +`sap_usage_references`. + +## Contents + +``` +SKILL.md the skill: phases, gates, tool bindings +templates/playbook-template.md the empty playbook a task fills in +``` + +## The short version of the rules + +1. Read structure before source. A full pull needs a written reason. +2. The filled playbook goes to the user before implementation. Always. +3. The object list in the plan is a contract. +4. One combined check call per object, not three. +5. A gate that fails two times stops the work. A third attempt costs more + than a question. + +## License + +Apache License 2.0. Copyright 2026 Erhan Keseli. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..fef9e83 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,100 @@ +--- +name: abap-playbook +description: > + Use this skill for ABAP development tasks that run through the EPOD ADT MCP + Server. Trigger it when a task creates a new object, changes two or more + objects, or must keep the current behaviour of an object (a refactoring, a + correction in shared code). Do not trigger it for a small task: one method, + one clear fix, no behaviour risk. The skill runs a phased playbook with + gates, binds each phase to the token-efficient MCP tools, and stops for + user approval before implementation. +--- + +# ABAP Development Playbook + +The playbook has five phases. Each phase ends with a gate. Do not start the +next phase before the gate passes. If a gate fails two times, stop and ask. +A third attempt costs more than a question. + +## When to open the playbook + +Open it when at least one of these is true: + +- The task creates a new repository object. +- The task changes two or more objects. +- The task must keep the current behaviour (refactoring, shared code, + correction reports). + +For everything else: work directly. Do not add process to a small task. + +## Phase 1 — Discovery + +Read structure before source. In this order: + +1. `sap_object_members` for each object in scope. Not `sap_pull_source`. +2. For the package pattern: `sap_object_members` on two or three similar + objects. Do not read their bodies. +3. `sap_usage_references` for each object that changes. +4. Read a method body only when a gate needs it: + `sap_pull_source` with `element=`. A full pull needs a written + reason in the playbook. + +Record the results in the playbook tables (template: +`templates/playbook-template.md`). The tables are the memory. Do not read +the same object twice. + +**Gate A:** every object in scope has a caller list, the naming convention +is written down, and no open question needs a system read. + +## Phase 2 — Plan + +Fill the template: impact table, object plan, test cases, acceptance +criteria. Every object gets an exact name. Every new object gets one +responsibility sentence. For a refactoring: state how the current behaviour +is captured (a saved result list, a comparison run) before any change. + +**Gate B/C:** show the filled playbook to the user and STOP. Do not start +Phase 3 without an explicit approval. This gate is never skipped: if the +playbook is open, the approval is required. + +## Phase 3 — Implementation + +Rules: + +- The object list in the plan is a contract. Do not touch an object that + the plan does not name. If a new object becomes necessary, stop, update + the plan, ask again. +- Change one method: `sap_push_element`. Change a signature and a body: + one `sap_push_element` call with `signature`. Push a full source only for + a new object, with `sap_push_source`. +- One object per step. Verify before the next object. +- Move logic without improving it when the task is a refactoring. A fix + found on the way goes to the open-points list, not into the code. + +## Phase 4 — Verification + +- `sap_check_object` after each object: syntax, ATC, unit tests in one + call. Do not call the three tools separately. +- Priority 1 findings block the gate. An open priority 2 finding needs a + written reason. +- Stop rule: the same finding after two fix attempts stops the phase. + +**Gate D:** all objects active, checks clean or explained, all planned +tests green, no object outside the plan changed. + +## Phase 5 — Close + +Fill the change summary table: object, action, one line of reason. List the +open points, or state that the list is empty. Confirm the transport holds +the planned objects and nothing else. + +## Token rules (always active) + +- Keep one session for the task. Do not clear the session between phases. +- Read the part, not the file. `sap_object_members` before source, + `element=` before a class. +- After each phase, keep the tables and drop the raw source from the + working context. +- Give the system, the object, and the scope in every sub-task you + formulate. Do not grep and do not run shell commands against pulled + sources when a tool answers the question. diff --git a/templates/playbook-example.md b/templates/playbook-example.md new file mode 100644 index 0000000..03b394b --- /dev/null +++ b/templates/playbook-example.md @@ -0,0 +1,253 @@ +# Development Playbook: EDOC-REFACT-01 — ZEDOC_REPAIR_REPORT test coverage + +Status: draft +Author: I301710 +Model tier for execution: sonnet for phases 5 and 6, opus for phases 1 and 2 +Transport: +Package: + +> All lines marked ASSUMED hold placeholder data. Replace them with system data +> before the agent starts phase 1. + +The agent runs the phases in order. Each phase ends with a gate. The agent must +not start the next phase before the gate passes. If a gate fails twice, the +agent stops and reports. It does not try a third time. + +--- + +## 0. Context + +Business need: +ZEDOC_REPAIR_REPORT has no unit tests. The logic sits in the report and reads +the database directly, so a test needs a system connection. The refactoring +must reach 70% coverage without a change to the behaviour that the user sees. + +Related objects (known before analysis): + +| Object | Type | Role | +|---|---|---| +| ZEDOC_REPAIR_REPORT | report | selection screen, logic, output — ASSUMED ~1400 lines | +| EDOC_HDR | table | eDocument header — ASSUMED | +| EDOC_STATUS | table | status history — ASSUMED | +| CL_EDOCUMENT | standard class | status change API — ASSUMED | + +Out of scope: +- The selection screen fields and their names. +- The ALV output layout. +- Any standard SAP object. +- The repair rules themselves. This change moves logic. It does not correct it. + +--- + +## 1. Analysis + +Input: section 0. + +Actions: +1. Read the report structure: FORM routines, local classes, global data. +2. Find a similar refactored report in the package. Record the pattern that it + uses for data access and for test doubles. +3. Record which FORM routine reads the database and which one only computes. + +Output: + +| Object | Direction | Caller / callee | Risk if changed | +|---|---|---|---| +| ZEDOC_REPAIR_REPORT | entry | started by user and by job variant EDOC_REP_D — ASSUMED | job variant breaks if the selection screen changes | +| f_select_documents | callee | reads EDOC_HDR | pure database access, move behind an interface | +| f_determine_repair | callee | called by f_select_documents | pure logic, move to the processor class | +| f_apply_repair | callee | calls CL_EDOCUMENT | write access, move behind an interface | +| f_display | callee | ALV | keep in the report | + +Naming pattern found in the package — ASSUMED: +- Classes: `ZCL_EDOC__` +- Interfaces: `ZIF_EDOC__` +- Test classes: local `ltcl_` in the class include + +Framework pattern found in the package — ASSUMED: +- Data access sits behind an interface. The production class carries the SELECT. +- Test doubles are local classes in the test include. +- The constructor takes the interface. It defaults to the production class. + +Gate A: +- [ ] Every FORM routine has a category: read, write, or compute. +- [ ] The job variant list is complete. +- [ ] The naming convention is written down, not assumed. + +--- + +## 2. Impact analysis + +| Change | Type | Downstream effect | Mitigation | +|---|---|---|---| +| Move the logic out of the report | behaviour risk | wrong result if a global variable holds state between FORM routines | list every global variable in phase 1 and pass it as a parameter | +| New interface for the read access | new object | none, the report is the only caller | — | +| New interface for the write access | new object | CL_EDOCUMENT calls move into one class | one place to check for the update task | +| The report keeps the selection screen | none | job variant stays valid | do not rename a selection screen field | +| No existing unit test | none | nothing to break | — | + +Known risk: the report may run inside an update task. If the write happens in +`IN UPDATE TASK`, the sequence must not change. Confirm this in phase 1 before +phase 5 starts. + +Gate B: +- [ ] Every global variable in the report is listed with its readers. +- [ ] The update task behaviour is confirmed, not assumed. +- [ ] The selection screen stays unchanged. + +--- + +## 3. Object plan + +### 3.1 Objects to change + +| Object | Type | Change | Verification | +|---|---|---|---| +| ZEDOC_REPAIR_REPORT | report | keep the selection screen, the ALV, and the START-OF-SELECTION shell. Delegate the rest to the processor. | run with the job variant, compare the result list with the result before the change | + +### 3.2 Objects to create + +| Object | Type | Responsibility | Package | Naming rule applied | +|---|---|---|---|---| +| ZIF_EDOC_REPAIR_DATA | interface | declare the read and write operations for repair data | | ZIF_EDOC__ | +| ZCL_EDOC_REPAIR_DATA | class | run the SELECT and the status update against the database | | ZCL_EDOC__ | +| ZCL_EDOC_REPAIR_PROCESSOR | class | decide which document needs a repair and which repair it needs | | ZCL_EDOC__ | + +The processor holds no SELECT. It receives data and returns a decision. This is +the condition that makes a database-free test possible. + +Gate C: +- [ ] Every object has an exact name. +- [ ] The processor class has no database access in its plan. +- [ ] The package and the transport are set for each new object. + +--- + +## 4. Coding standards + +The agent applies these rules. It does not restate them in the code. + +- Clean ABAP naming and structure. +- No comment that restates what the code does. +- No Given/When/Then comment headers in tests. +- Method length: keep below 40 statements. +- No new global variable. +- Exception classes: use the package pattern. Do not create a new base class. +- Text elements for user-facing text. + +Project-specific rules recorded in section 1: +- Class and interface names follow `Z(CL|IF)_EDOC__`. +- The constructor takes the data interface and defaults to the production class. +- Test doubles are local classes in the test include. + +--- + +## 5. Implementation + +Order: +1. `ZIF_EDOC_REPAIR_DATA` — create, activate, syntax check. +2. `ZCL_EDOC_REPAIR_DATA` — implement the interface with the SELECT and the + update that phase 1 recorded. Activate, syntax check. +3. `ZCL_EDOC_REPAIR_PROCESSOR` — move the compute logic from the FORM routines. + Activate, syntax check. +4. `ZEDOC_REPAIR_REPORT` — replace the FORM bodies with calls to the processor. + Keep the selection screen and the ALV. Activate, syntax check. + +Rules: +- One object per step. +- Do not change an object that section 3 does not list. +- If the implementation needs another object, stop and update section 3 first. +- Move the logic. Do not improve it. A behaviour change here breaks the + comparison test in section 8. + +Gate D: +- [ ] All four objects are active. +- [ ] The syntax check returns no error. +- [ ] The report holds no SELECT statement. +- [ ] No object outside section 3 changed. + +--- + +## 6. Unit tests + +Target coverage: 70% or higher on ZCL_EDOC_REPAIR_PROCESSOR. + +Actions: +1. Create a local test double for `ZIF_EDOC_REPAIR_DATA` in the processor test + include. +2. Write the cases below. +3. Run ABAP Unit. + +| Case | Object | Expected result | +|---|---|---| +| document with a status that needs a repair | processor | the processor returns the repair action | +| document with a status that needs no repair | processor | the processor returns no action | +| document with a status outside the known set | processor | the processor raises the package exception | +| empty input table | processor | the processor returns an empty result, no exception | +| two documents, one needs a repair | processor | the result holds one entry | +| document already repaired on the same day | processor | the processor returns no action | + +Gate E: +- [ ] All tests pass. +- [ ] Coverage on the processor is 70% or higher. +- [ ] No test opens a database connection. +- [ ] The test double holds no SELECT. + +--- + +## 7. ATC + +Actions: +1. Run ATC with the project variant on the four objects. +2. Report priority 1 and priority 2 findings, grouped by check. +3. Fix each finding, or record the reason for an open finding. + +| Check | Priority | Object | Decision | +|---|---|---|---| + +Stop rule: if the same finding returns after two fix attempts, the agent stops +and reports it. + +--- + +## 8. Acceptance criteria + +- [ ] The report started with job variant EDOC_REP_D returns the same document + list as before the change. Compare with a saved result list. +- [ ] The status update writes the same records as before, in the same + sequence, and in the same update task mode. +- [ ] The selection screen shows the same fields with the same names. +- [ ] A document with an unknown status raises the package exception. The report + shows the message and does not dump. +- [ ] The ALV layout and the column order stay unchanged. + +The first criterion needs a result list from before the change. Save it before +phase 5 starts. Without it the criterion is not testable. + +--- + +## 9. Definition of done + +- [ ] Gates A to F pass. +- [ ] All acceptance criteria pass. +- [ ] The transport holds the four objects and no other object. +- [ ] The agent produced a change summary. +- [ ] Open points are listed, or the list is empty. + +--- + +## Token rules for the agent + +- Read method signatures and the FORM list before the full report source. +- Read a FORM body only in the step that moves it. +- Do not repeat a read that the tables above already record. +- After each phase, keep the tables and drop the raw source. +- If two attempts at a gate fail, stop. + +## Change summary (agent fills this at the end) + +| Object | Type | Action | Reason | +|---|---|---|---| + +Open points: +- diff --git a/templates/playbook-template.md b/templates/playbook-template.md new file mode 100644 index 0000000..5ffbb48 --- /dev/null +++ b/templates/playbook-template.md @@ -0,0 +1,224 @@ +# Development Playbook: — + +Status: draft | approved | in progress | done +Author: I301710 +Model tier for execution: +Transport: +Package: + +The agent runs the phases in order. Each phase ends with a gate. The agent must +not start the next phase before the gate passes. If a gate fails twice, the +agent stops and reports. It does not try a third time. + +--- + +## 0. Context + +Business need: + + +Related objects (known before analysis): +| Object | Type | Role | +|---|---|---| +| ZCL_... | class | ... | +| ZBR_... | report | ... | + +Out of scope: +- + +--- + +## 1. Analysis + +Input: section 0. + +Actions: +1. Run `sap_object_members` for each object in the table above. Read a method + body only when a gate needs it: `sap_pull_source` with `element=`. +2. Run `sap_object_members` on two or three similar objects in the package. + Record the naming pattern and the framework pattern. Do not read bodies. +3. Run `sap_usage_references` for each object that changes. Record the call + chain in the table. + +Output — fill this table: + +| Object | Direction | Caller / callee | Risk if changed | +|---|---|---|---| + +Gate A: +- [ ] Every object in scope has a known caller list. +- [ ] The naming convention is written down, not assumed. +- [ ] No open question remains that needs a system read. + +If a gate item fails, the agent asks one question. It does not guess. + +--- + +## 2. Impact analysis + +Actions: +1. List the objects that change behaviour. +2. List the objects that change signature. A signature change needs a caller + update list. +3. List the DDIC and customizing dependencies. +4. State the effect on existing unit tests. + +Output: + +| Change | Type | Downstream effect | Mitigation | +|---|---|---|---| + +Gate B: +- [ ] Every signature change has a complete caller list. +- [ ] The effect on existing tests is stated for each change. +- [ ] No change touches an object in the "out of scope" list. + +--- + +## 3. Object plan + +### 3.1 Objects to change + +| Object | Type | Change | Verification | +|---|---|---|---| + +### 3.2 Objects to create + +| Object | Type | Responsibility | Package | Naming rule applied | +|---|---|---|---|---| + +Each new object needs one sentence of responsibility. If the sentence needs the +word "and", split the object. + +Gate C: +- [ ] Every object has an exact name. No placeholder names remain. +- [ ] Every object has one responsibility. +- [ ] The package and the transport are set for each new object. + +--- + +## 4. Coding standards + +The agent applies these rules. It does not restate them in the code. + +- Clean ABAP naming and structure. +- No comment that restates what the code does. Keep only comments that explain + a non-obvious reason. +- No Given/When/Then comment headers in tests. +- Method length: keep below 40 statements. Split if longer. +- No new global variable. +- Exception classes: use the pattern that section 1 recorded, not a new one. +- Text elements for user-facing text. No hardcoded literal. + +Project-specific rules recorded in section 1: +- +- + +--- + +## 5. Implementation + +Actions, in order, for each object in section 3: +1. Change one method with `sap_push_element` (use `signature` when the + declaration changes too). Push a full source only for a new object, with + `sap_push_source` — it runs lock, write, unlock, and activate in one call. +2. Run `sap_check_object` for the object. +3. Fix errors before the next object. + +Rules: +- One object per step. Do not create several objects and activate them together. +- Do not change an object that section 3 does not list. +- If the implementation needs an object that section 3 does not list, stop. + Return to section 3 and update it first. + +Gate D: +- [ ] Every object in section 3 is active. +- [ ] The syntax check returns no error. +- [ ] No object outside section 3 changed. + +--- + +## 6. Unit tests + +Target coverage: <70% or higher> + +Actions: +1. Write tests for each public method that section 3 lists. +2. Keep the tests free of database access. Use test doubles. +3. Run ABAP Unit. Record the result. + +Test cases to cover: +| Case | Object | Expected result | +|---|---|---| + +Gate E: +- [ ] All tests pass. +- [ ] Coverage meets the target. +- [ ] No test needs a database connection. + +--- + +## 7. ATC + +Actions: +1. Run `sap_check_object` with the project ATC variant and `runUnitTest=true`. +2. Report only priority 1 and priority 2 findings. Group them by check. +3. Fix each finding, or record why the agent does not fix it. + +Output: + +| Check | Priority | Object | Decision | +|---|---|---|---| + +Gate F: +- [ ] No priority 1 finding remains open. +- [ ] Every open priority 2 finding has a written reason. + +Stop rule: if the same ATC finding returns after two fix attempts, the agent +stops and reports the finding. It does not try a third fix. + +--- + +## 8. Acceptance criteria + +The change is correct when all of these are true: + +- [ ] +- [ ] +- [ ] + +Each criterion must be testable from outside the code. "The code is clean" is +not a criterion. + +--- + +## 9. Definition of done + +- [ ] Gates A to F pass. +- [ ] All acceptance criteria pass. +- [ ] The transport holds every changed object and no other object. +- [ ] The agent produced a change summary: object, type, one line of reason. +- [ ] Open points are listed, or the list is empty. + +--- + +## Token rules for the agent + +- `sap_object_members` before source. `element=` before a class. Read a full + include only when a gate needs the body, and write the reason into this + playbook. +- Ask for a targeted change. Do not rewrite a whole object to fix one method. +- Do not repeat a read that this playbook already recorded. The tables above + are the memory. +- After each phase, keep the tables and drop the raw source from the working + context. +- If two attempts at a gate fail, stop. A third attempt costs more than a + question. + +## Change summary (agent fills this at the end) + +| Object | Type | Action | Reason | +|---|---|---|---| + +Open points: +-