feat(skills): ABAP refactoring chain — modernize-abap + sap-erp-clean-core-refactor#283
Open
Raistlin82 wants to merge 23 commits into
Open
feat(skills): ABAP refactoring chain — modernize-abap + sap-erp-clean-core-refactor#283Raistlin82 wants to merge 23 commits into
Raistlin82 wants to merge 23 commits into
Conversation
Introduces a side-by-side modernization workflow that takes a custom ABAP
package (Z*) on S/4HANA / ECC and produces a complete BTP-native CAP
project scaffold (CDS schema + service + handler stubs + Fiori Elements V4
+ MTA deployment artifacts) without touching the source ABAP system.
This is the MVP foundation. Orchestrator + 2 core sub-skills (schema +
service) included. Remaining 4 sub-skills (clean-core-gap, fiori-elements,
auth-mapping, btp-mta) tracked as follow-up.
## What's included
### New skills (3 markdown files, 1211 lines)
- skills/modernize-abap-to-btp-cap.md (orchestrator, 357 lines)
- End-to-end workflow: inventory → schema → service → fiori → auth → mta → ADR
- Smart Defaults table, BTP vs On-Premise comparison, error handling
- References sub-skills via inline markdown links
- skills/modernize-abap-cap-schema.md (370 lines)
- DDIC → CDS type mapping table (24 types)
- Foreign-key → Association/Composition inference
- cuid / managed aspect auto-application (sysuuid_x16 + audit fields)
- Currency / Quantity semantic annotations
- mandt / CLNT exclusion (single-tenant per service)
- skills/modernize-abap-cap-service.md (484 lines)
- FM/program/class → CAP service action mapping
- Bound vs unbound action classification
- TypeScript handler stubs with TODO + ABAP source excerpts
- 13 common ABAP → CAP handler pattern mappings (SELECT, MODIFY,
LOOP AT, READ TABLE, CALL FUNCTION, etc.)
- Type extraction to srv/types.cds for complex inline types
### README update
- New "BTP CAP Modernization (Preview)" section in skills/README.md
- Explains relationship vs sap-clean-core-atc, migrate-custom-code
(those keep source in SAP; this rebuilds as BTP CAP)
- Typical workflow chain documented (7 steps)
## Design decisions
- **Side-by-side, NOT in-place**: leaves source ABAP system read-only.
Generates parallel CAP target — no SAPWrite calls needed.
- **Skill-first contribution**: aligned with arc-1's 17-skill community
pattern; NO new MCP tool, NO core code change. Honors the 12-tool
token-efficient principle (CLAUDE.md §"Design Principles").
- **Markdown orchestration**: skills chain via inline markdown links
(consistent with sap-clean-core-atc → migrate-custom-code pattern).
- **Sandbox output by default**: writes to <target>/.target-cap-staging/
for review before apply. Reversible.
- **Smart Defaults**: every decision documented with rationale; avoid
asking the user unless ambiguous.
- **TODO scaffolds, NOT auto-implementation**: handler bodies are stubs
with embedded ABAP source excerpts; user implements business logic
in a second pass. Honest about what the LLM can/cannot translate.
## Use cases addressed
- Greenfield BTP CAP migration of a Z* package from ECC / on-prem S/4
- Lift-and-redesign for BTP-native architecture
- POC / pilot for evaluating BTP CAP as target
- Quarterly modernization assessment (run with --skip flags for analysis-only)
- Pre-deployment audit before committing to BTP roadmap
## NOT addressed (intentionally out of scope)
- No SAP write operations
- No CF deployment automation (cf push stays manual)
- No HANA service provisioning
- No XSUAA service creation
- No automatic handler logic generation
- No regression test execution
- No transport-coordinated migration
- No Kyma target (CF only for v1)
- No CAP Java target (Node.js only for v1)
- No Freestyle UI5 (Fiori Elements V4 only)
## Follow-up
Track sub-skill development:
- modernize-abap-clean-core-gap (~400 lines)
Batch Clean Core L-A per-edition compliance check + replacement suggestions
- modernize-abap-fiori-elements (~500 lines)
Service → Fiori Elements V4 LROP scaffold (manifest + annotations)
- modernize-abap-auth-mapping (~300 lines)
AUTHORITY-CHECK → XSUAA scopes + @restrict annotations
- modernize-abap-btp-mta (~300 lines)
CAP project → mta.yaml + Dockerfile + manifest.yml
## Testing
This is a skill (markdown), no automated tests apply per arc-1 convention.
Smoke-testable manually by:
1. Connecting ARC-1 to a system with Z packages
2. Invoking the skill via Claude Code / Cursor / Copilot
3. Verifying scaffold output compiles (npx cds compile)
## Acknowledgments
Inspired by:
- generate-rap-service-researched (research-first pattern)
- sap-clean-core-atc (Clean Core classification)
- migrate-custom-code (ATC-driven fix pattern)
…AML frontmatter arc-1 main migrated skills from flat .md files to directory + SKILL.md + YAML frontmatter format (compatible with vercel-labs/skills CLI and the Anthropic Agent Skills standard). This PR's skills now follow the new format. ## Changes - `skills/modernize-abap-to-btp-cap.md` → `skills/modernize-abap-to-btp-cap/SKILL.md` - `skills/modernize-abap-cap-schema.md` → `skills/modernize-abap-cap-schema/SKILL.md` - `skills/modernize-abap-cap-service.md` → `skills/modernize-abap-cap-service/SKILL.md` Each SKILL.md now starts with YAML frontmatter: ```yaml --- name: <skill-name> description: <discovery description with "Use when..." pattern> --- ``` Cross-links between skills updated from `[name](name.md)` to `[name](../name/SKILL.md)` for sibling skills, matching the pattern used in existing skills (e.g., sap-clean-core-atc/SKILL.md → ../migrate-custom-code/SKILL.md). skills/README.md links updated to point to the new directory paths. ## Verification - All 3 skills have YAML frontmatter with discovery-friendly descriptions - All inline cross-links resolved to new paths - No orphan `*.md` files (git mv handled the rename, history preserved) - skills/README.md reflects new paths This is a zero-content-change refactor — only structural reorganization to align with the new arc-1 skill format introduced in upstream main.
…core + customizing) Introduces 2 read-only audit skills for SAP CAP applications deployed on BTP consuming S/4HANA Tier-2 services. Skill-first, no MCP tool changes, zero code dependencies. ## What's included ### skills/sap-cap-clean-core-enforce/SKILL.md (386 lines) Discovery-driven Clean Core Level A enforcement audit. - Scans cds.connect.to() runtime + @cds.external service contracts - 4-source dynamic discovery (runtime + externals + catalog + CSV) - Probe identification heuristics (catalog explicit > naming convention > MCP search) - 3-edition MCP verification matrix (public_cloud × private_cloud × on_premise) - Catalog drift detection (over-declared / under-declared / missing-field) - Multi-dimensional compliance rollup (per-service / per-SAP_COM / coverage summary) - Safe auto-fix mode for under-declared availability + missing probeObject ### skills/sap-cap-customizing-honor/SKILL.md (494 lines) Bidirectional CSV ↔ code customizing audit. - Forward orphans (CSV seeded but never consumed) - Inverse orphans (code reads parameter but no CSV seed) - Hardcoded business decisions sweep (thresholds, timeouts, retry policies, UX timing) - Adapter factory dual-source verification (SystemParameter → cds.env → env → hardcoded) - Master-data FK ValueList enforcement (filter bar + edit form + TextArrangement cascade) - Catalog raise-site coverage check (ProcessStepCheck pattern, if applicable) - Safe auto-fix mode: add missing CSV seed rows + add filter-bar ValueList annotations ### skills/README.md update New "SAP CAP Enterprise Audit (Preview)" section listing both skills with discovery descriptions. Marked as Preview / WIP since full audit cluster (planned 6+ skills total) is iterative. ## Design decisions - **Read-only / idempotent** — no SAP write operations needed; both skills work against any ARC-1 deployment without --allow-writes - **mcp-sap-docs dependency** — clean-core-enforce uses mcp-sap-docs for SAP API release-state queries; customizing-honor uses no MCP (pure code analysis) - **Zero project-specific naming** — 100% generic, suitable for any CAP+S/4 stack; auto-detects project-specific patterns (compatibility policy file, CSV path) - **Safe-by-default auto-fix** — only additive changes auto-applied (expand availability, add ValueList annotations); destructive changes (remove catalog entries, remove CSV seeds) require manual decision - **Quarterly cadence** — designed for Q-review compliance checks + ad-hoc pre-deployment audits ## Follow-up Additional skills planned (separate PRs): - [ ] sap-cap-security-rbac-matrix (~600 lines) Multi-area parallel security audit + RBAC matrix + OWASP/ASVS mapping - [ ] sap-cap-lifecycle-matrix-audit (~500 lines) Workflow phase × step × check × state × role × policy matrix audit - [ ] sap-fiori-app-audit (~450 lines) End-to-end Fiori Elements V4 app audit (manifest + annotations + flags + EDMX) - [ ] sap-cap-text-polish (~400 lines) User-visible text polish for CAP + Fiori (i18n + microcopy + PII sanitize) - [ ] sap-cap-stack-audit-full (~400 lines) Multi-tool SAP stack audit orchestrator (UI5 + Fiori + CAP + BTP) - [ ] sap-cap-ci-gates-pattern (~400 lines) Library of 5 CI gate patterns for CAP projects ## Compatibility - Zero code changes - Zero new dependencies - Zero new MCP tools - Zero new ACTION_POLICY entries - Compatible with all ARC-1 versions (read-only SAPRead/SAPSearch/SAPContext) - Optional mcp-sap-docs dependency (clean-core-enforce only) ## Inspired by - sap-clean-core-atc (ABAP-side companion pattern) - migrate-custom-code (audit-style structure) - generate-rap-service-researched (research-first / smart-defaults pattern)
Adds the operational complement to PR marianfoo#279 (Waves 1: clean-core + customizing): - sap-cap-security-rbac-matrix — multi-area parallel security scan + role coherence matrix across 4 layers (xs-security <-> IdP realm <-> services-auth <-> handlers) + OWASP / ASVS / NIST CSF / CIS / SAP-SOM / GDPR / SOX mapping. - sap-fiori-app-audit — single Fiori Elements V4 app audit: user journey, frontend/backend contract chain, manifest/annotations/EDMX alignment, computed flag matrix, i18n coverage, action availability, draft behaviour. Safe quick-win fixes on a dedicated branch. - sap-cap-text-polish — user-visible text audit (backend reject/throw, helper rejects, toasts/dialogs, i18n bundles, CDS labels, CodeList descr). Detects ten anti-patterns including PII leak. Locale-aware, tone-profile- driven, additive safe rewrites only. - sap-cap-stack-audit-full — orchestrator that runs UI5 linter, manifest validation, CDS compile, TS typecheck, hardcoded-customizing sweep, test suite + the specialized audit skills above in parallel, with deduplicated consolidated report. - sap-cap-ci-gates-pattern — library of five reusable CI gate patterns (bidirectional CSV<->code, catalog raise-coverage, API-availability drift, convention-matrix drift, CSV schema lint). Generates portable shell scripts + GitHub Actions / GitLab CI / Jenkins workflow YAML. README updated with the seven-skill toolkit overview and a typical workflow chain entry point. All skills are read-only by default; fix modes are limited to safe additive corrections on dedicated branches. None modify production code or open PRs without explicit user opt-in. Discovery-driven (no hardcoded entity names); each skill explains the conditions under which it applies and degrades gracefully when sources are absent. Cross-references: - depends on / complements PR marianfoo#279 (Waves 1: clean-core-enforce + customizing-honor) - Original Wave 2 plan included a lifecycle-matrix-audit skill, dropped after review: too domain-specific to a particular process-engine pattern (template + step + check + override-policy catalog) to generalize cleanly. [skip ci]
…lugin sections Adds a new master skill that distills institutional knowledge — ~60 production- discovered patterns and gotchas across eight categories — into a navigable reference catalog, and cross-links it from the five operational audit skills. New master skill: - sap-cap-fiori-battle-tested-patterns (~620 lines): UI5/FE V4 traps, CAP/ TypeScript pitfalls, BTP/Kyma deployment lessons, security defense-in-depth, customizing-driven patterns, lifecycle/process discipline, post-commit events /messaging, ecosystem plugin landscape. Each pattern: symptom + root cause + generic remedy. Internally anchored so other skills can deep-link by pattern number (e.g. "matches pattern 1.2 — @UI.Hidden on OperationAvailable"). Enrichment of the five Wave 2-3 operational audit skills: - "Battle-Tested Patterns Referenced" section: each skill names the 3-12 patterns most relevant to its audit and explains the connection. - "Recommended Companion Plugins" section: tailored list of external skills / MCP servers that complement the audit (sap-cap-capire, sapui5, sap-fiori- tools, sap-btp-*, sap-docs, context7, playwright). Cross-link to Category 8 of the master skill for the full ecosystem map. README update: master skill added to the SAP CAP Enterprise Audit (Preview) table; status note clarifies the toolkit is now eight skills and the Recommended Companion Plugins convention. Rationale: prior to this commit the operational audit skills carried only their immediate guidance; the institutional knowledge from production deployments (which patterns recur, which gotchas burn teams) lived in private project lore. The master skill makes that knowledge generic, reviewable, and linkable. The companion plugin sections make the ecosystem dependencies explicit — downstream users know which external skills to install for the full experience. All content is 100% generic (no project / domain references). Discovery-driven where applicable; degrades gracefully when the documented preconditions are absent. [skip ci]
… gate Master skill `sap-cap-fiori-battle-tested-patterns` Category 3 expanded with the four canonical deployment targets, ~17 new patterns, and Clean Core as a CI-blocking deployment gate. Category 3 restructure: - 3.0 Deployment target decision matrix (BTP CF / BTP Kyma / OnPrem Kyma / OnPrem CF) with column for each: when-to-choose, CDS profile, auth, DB, UI delivery, remote service binding. - 3.A BTP Cloud Foundry — 5 patterns: mta.yaml atomic deploy, xs-security scope wiring, Destination service for Tier-2 S/4 proxies, html5-apps-repo (Free plan limits), CF health check endpoints. - 3.B BTP Kyma — 7 patterns: APIRule CRD (not Ingress YAML), Service Manager bindings via secrets, CronJob CRD (not BTP Job Scheduler), Bitnami PG Helm chart for in-cluster persistence, KYMA_APP_URL + KYMA_KUBECONFIG multi-region pattern, HPA + PDB + NetworkPolicy, approuter session stickiness via nginx cookie affinity. - 3.C On-Premise Kyma — 6 patterns: cluster flavor detection (k3d/Rancher/ Gardener/OpenShift), Keycloak realm + customer IdP federation, secrets.env + envsubst per-customer config, sizing wizard (xs/s/m/l tiers), pre-flight check (Docker RAM, DNS, storage class), in-cluster service URLs (*.svc.cluster.local). - 3.D On-Premise CF — 1 pattern: legacy continuity only, EOL warning, shim list. - 3.1-3.10 cross-cutting patterns preserved. - 3.11 NEW — Clean Core Level A as deployment gate (not just audit). Cites the three authoritative sources: SAP/abap-atc-cr-cv-s4hc README, SAP API Hub (api.sap.com), project compatibility catalog. Hard-fail CI semantics. Cross-links to sap-cap-clean-core-enforce + ci-gates-pattern Pattern 3. Orchestrator `sap-cap-stack-audit-full` gets a new Step 0: - 0a Auto-detect deployment target from project state (mta.yaml, k8s manifests, CDS profile, auth indicators). - 0b If ambiguous, ask the user explicitly — never guess; the wrong target produces inapplicable advice. - 0c Persist target as $TARGET; subsequent phases dispatch differently per target (Phase 2 manifest validation, Phase 3 agent selection, Phase 4 profile filter, Phase 5 best-practice set). - Pre-flight Clean Core catalog detection added — warning emitted when absent so the dispatch of sap-cap-clean-core-enforce knows to run in discovery mode only. Rationale: prior to this commit the master skill's deployment guidance was target-agnostic, leading to advice that applied somewhere but not always (e.g. "use html5-apps-repo" → broken on Kyma free; "use APIRule" → broken on BTP CF). Making target explicit is a precondition for any actionable deployment guidance. Clean Core gate elevation: previously documented as "an audit you might want to run". Now codified as a HARD pre-deployment gate consulting three authoritative sources. This is the single most important deployment gate for CAP + S/4 projects — a non-released service that ships becomes a multi-quarter migration debt. [skip ci]
Strengthens `sap-cap-clean-core-enforce` from a read-only audit into a
proper deployment gate.
Step 4 (Matrix verification) — now consults two authoritative sources in
priority order:
1. SAP/abap-atc-cr-cv-s4hc — the ABAP API Release State repository (JSON
files per object class). Authoritative for ABAP object classification
(released / Clean Core level / per-edition availability). Already
queried via mcp-sap-docs.
2. api.sap.com — the SAP API Hub. Authoritative for OData service
lifecycle (released / sandbox / deprecated), Communication Scenario
membership, version history, deprecation timeline. Queried via
mcp-sap-docs:sap_search_objects OR scraped via Apify Website Content
Crawler into a refreshable offline cache.
3. Project's own compatibility catalog (e.g.
srv/integration/s4CompatibilityPolicy.js) — authoritative only for the
*declared* claim, which the audit verifies against sources 1 + 2.
When sources 1 and 2 disagree: API Hub wins for OData service questions;
abap-atc repo wins for raw ABAP object questions. Resolution rationale is
recorded in the report.
New Step 9 — Enforcement mode (`--enforce` flag):
| Mode | Exit on HIGH | Exit on MED | Exit on LOW | Use case |
|------------------|--------------|-------------|-------------|----------|
| report (default) | 0 | 0 | 0 | Audit |
| --apply | 0 | 0 | 0 | Audit+fix|
| --enforce | 1 | 0 (warn) | 0 (info) | CI gate |
| --enforce --strict | 1 | 1 | 0 | Tightest |
HIGH severity criteria (gate-blocking):
- Consumed service NOT released for the deployment target's edition.
- Consumed service deprecated with sunset inside the release window.
- Catalog declares availability that MCP-verification refutes
(OVER_DECLARED drift).
- Direct DB-table or RFC/BAPI consumption against non-released artifact.
CI integration patterns (GitHub Actions YAML example) included; pairs
with sap-cap-ci-gates-pattern Pattern 3 for the full wiring (per-PR fast
feedback + per-deploy safety net).
Sources refresh discipline: weekly cron pulls fresh abap-atc snapshot;
weekly Apify scrape of api.sap.com package pages. Stale (>7d) cache is
treated as a finding. Drift caused by SAP-side changes is flagged as
"upstream drift" with a 90-day window to remediate.
Side-by-side extension fallback: when --enforce blocks on a genuinely
needed non-released service, the finding is reclassified as a
"side-by-side extension candidate" — the consumption belongs in a
separate extension service on BTP (or out of ABAP entirely), not in the
CAP service that ships through the gate.
Frontmatter description updated to surface the enforcement semantics in
discovery patterns ("enforce Clean Core in CI", "block deployment if
non-released API is consumed").
References section reorganized: primary authoritative sources called out
explicitly (abap-atc-cr-cv-s4hc README pinned link + api.sap.com),
methodology references kept, related skills cross-linked
(sap-cap-ci-gates-pattern Pattern 3 + battle-tested-patterns §3.11).
[skip ci]
Plans the refactor of custom ABAP / ERP / S/4HANA code back to Clean Core
compliance, with documentation lookups happening just-in-time only when a
specific finding needs them — no centralized pre-crawled knowledge base.
Why JIT instead of pre-crawl:
- Volume: help.sap.com alone is ~50k pages; full crawl produces gigabytes
that 99% of users never read.
- Cost: weekly Apify crawl of 18 sources ~ EUR 400-780/year. No clear
funding model for OSS centralized infra; nobody wants to maintain it.
- Staleness: even a weekly crawl is N days behind; SAP releases new APIs
monthly. Day-7 snapshot is already outdated for time-sensitive
decisions.
The skill ships two files:
- SKILL.md: the protocol. Step-by-step from ARC-1 discovery through
sap-clean-core-atc classification to JIT lookup to per-object refactor
plan. Three modes: discover, plan (default), execute. Bounded per-
finding lookup budget (5 Apify pages + 1 git + 1 MCP). Budget exhaust
surfaces as research-required, never as a guess.
- SOURCES.md: the curated catalog of 23 authoritative SAP documentation
sources organized in 4 tiers:
* Tier 1 (8 entries) - git-cloneable, free, weekly pull: abap-atc-cr-cv-
s4hc + 6 SAP-samples repos + cloud-sdk.
* Tier 2 (15 entries) - JIT Apify, user pays at lookup time: api.sap.com
(puppeteer, SPA), help.sap.com family (website-content-crawler), cap.
cloud.sap, sapui5.hana.ondemand.com, developers.sap.com, community
(recent-90d), blogs (tag-filtered), Fiori design, Discovery Center,
learning.sap.com / openSAP.
* Tier 3 (3 entries) - manual consultation (auth-gated, S-user
required): launchpad-support, me.sap.com, support.sap.com.
* Tier 4 (2 entries) - MCP-server-backed when installed:
mcp-sap-docs, context7.
Cost model: per-finding ~5 lookups x EUR 0.005-0.02 = EUR 0.025-0.10
per finding. Typical customer refactor of 50-200 findings = EUR 0.5-5
total, charged to user's own Apify account. Cache TTL 30d for stable
docs, 7d for community / blogs. Within TTL, repeat lookups are free.
The skill complements:
- sap-clean-core-atc (classification - delegate)
- sap-unused-code (dead-code identification - delegate)
- migrate-custom-code (ATC fix patterns - sibling)
- modernize-abap-to-btp-cap (side-by-side scaffold generator - handoff)
- sap-cap-fiori-battle-tested-patterns Category 3 (target deployment
patterns for the side-by-side - reference)
README.md updated with a new "SAP ERP - Clean Core Return + Side-by-Side
Refactor (Preview)" section between Analyzing/Understanding and Clean
Core/Custom Code Retirement sections.
This PR is structurally independent of marianfoo#279 (Wave 1 audit) and marianfoo#280
(Wave 2-3 audit). Cross-links resolve once marianfoo#280 lands (battle-tested-
patterns Category 3); until then they degrade gracefully to a "see also"
hint.
[skip ci]
…lags Lets the user override the default "Level B kept as B" behaviour and explore Level A escalation paths (rewrite via Customizing OR side-by-side extraction) per object. Why this matters: Level B is already Clean-Core compliant, so by default the skill emits keep_at_level_b for Level B objects. But there are real scenarios where the customer needs to push further to A: - Governance mandate "zero custom logic in ERP" - Target deployment is S/4HANA Public Cloud strict mode - Customer has strong BTP team and wants to consolidate logic out of ERP - The B pattern was an accident (Customizing alternative exists) - The B pattern uses a deprecated BAdI being sunset Three escalation mechanisms (least invasive first): 1. Per-object override via plan-file editing (already supported): After plan emission, edit docs/refactor/<date>-clean-core-plan.md to change any keep_at_level_b row to rewrite_in_place or extract_to_side_by_side. Execute mode reads the edited file. Finest grained, no re-run, no extra Apify cost. 2. --push-to-a=A,B,C (selective): only listed object names get the expanded analysis. Cheaper than --aggressive (+€0.05-€0.10 per object). Use when you know upfront which objects to escalate. 3. --aggressive (global): every Level B gets the expanded analysis. +30-50% on plan generation cost. Use for governance-driven full review. New Step 4e — escalation criteria and when-to / when-not-to tables: documents when push-to-A is appropriate and when keep-at-B is correct (many B objects use SAP-blessed patterns where A means "abandon SAP recommendation" — not always the right call). New Step 4f — extended decision logic for escalated findings: emits a multi-option proposal (default_decision + escalation_options array + recommended option with reasoning) instead of a single decision. The recommendation considers consistency with other decisions in the same plan (if plan already has 5 side-by-side extensions in the same domain, recommend side-by-side for the escalated B too). New Step 4g — post-plan editing as the finest-grained override mechanism, complementary to the flags. Plan output template (Step 5) updated: - New "Level B escalation proposals" section (only when --aggressive or --push-to-a was used) - New "Effort estimate" section showing per-decision-path deltas - New "Sequencing" entry for user-chosen escalations Cost model updated with delta lines for --aggressive (+30-50%) and --push-to-a (€0.05-€0.10 per listed object). Smart Defaults updated with explicit "Level B handling = keep by default" entry explaining why escalation is opt-in. Examples section adds two new invocations: - `ZFI plan --target=btp-kyma --aggressive` - `ZFI plan --target=btp-kyma --push-to-a=ZTABLE_TAX_RATES_LOCAL,ZCL_VENDOR_LOOKUP_EXT` [skip ci]
…ision tree Adds the --target-level=A|B flag and makes the per-object decision tree explicit in the skill (Step 4d-bis), so users understand exactly how Level C and Level D findings land at A vs B by default. New flag --target-level=A|B: - --target-level=A (ambitious): always prefer A. For D, forces side-by- side extraction over BAdI-rewrite. For C, forces released-API replacement over BAdI substitution even when BAdI is cheaper. For B, activates escalation analysis (same as --aggressive — now a synonym). - --target-level=B (minimal compliance): settle for B everywhere. For C, prefer cheaper BAdI path even if released-API replacement lands at A. For D, BAdI-rewrite only — never side-by-side just for "purity". Useful when customer wants "good enough" with minimum disruption. Default behavior (no flag): cost-minimizing per object. D → B via BAdI when feasible. C → A via released API when feasible. Falls back to side- by-side or keep-at-B based on lookup results. New Step 4d-bis "Decision tree (per-object)" with explicit pseudo-code showing exactly how Start Level + flags → Target Level + Decision is computed. Captures the five key invariants: - A stays A - B stays B (default) or A (only via opt-in escalation) - C goes to A (default) / B (--target-level=B) / side-by-side (no equiv) - D goes to B via BAdI (default) / A via side-by-side (--target-level=A or no BAdI option) / accept_as_d as last resort - Unused removed Smart Defaults table extended with three new rows: - Level C target: A via released-API by default, B fallback - Level D target: B via BAdI by default, side-by-side fallback - Mixed-findings objects: object level = MAX of finding levels Plan output template now shows an explicit table with columns: | Object | Start Level | Target Level | Decision | Replacement | Effort | Risk | KB evidence | This makes the refactor outcome immediately visible per object — no more "outcome: rewrite_in_place" hiding the actual target level. Concrete examples in the plan template: - ZCL_INVOICE_HANDLER: D → A via API_SUPPLIERINVOICE_PROCESS_SRV - ZCL_VENDOR_RISK_SCORE: C → A (ERP-side) via side-by-side - ZTABLE_TAX_RATES_LOCAL: D → B via BAdI BADI_TAX_RATE_DETERMINATION Clarifies "ERP-side A" semantics: when an object is extracted to BTP, the ERP no longer contains it (A by absence). The logic on BTP is governed by separate Clean Core gates (see sap-cap-clean-core-enforce). [skip ci]
Updates the master skill (Category 3.0 decision matrix narrative) and
the stack-audit orchestrator (Step 0b ask-user template) to recommend
BTP Cloud Foundry as the default when the customer's target is
ambiguous or unspecified.
Rationale:
- BTP CF is the most widely-adopted SAP-managed runtime — broadest
customer reach.
- BTP CF has the broadest service ecosystem (Free + paid tiers for
xsuaa, html5-apps-repo, destination, connectivity, event-mesh,
audit-log, job-scheduling, …) — many of those have Free tiers that
Kyma cannot consume.
- BTP CF tooling is the most mature (mta.yaml + mbt build + cf deploy).
- BTP CF has the lowest operational ceremony for teams without
dedicated Kubernetes expertise — most SAP customers do not have a
K8s operations team.
BTP Kyma stays as the right choice when the customer explicitly wants
the Kubernetes operational model (pay-tier services, more runtime
flexibility, container-native eventing, CronJob CRDs). The skill
describes those use cases so a deliberate Kyma choice is well-supported.
On-Premise targets unchanged: explicit data-sovereignty mandate or
existing Kubernetes investment (Kyma on-prem); legacy continuity only
(CF on-prem, EOL).
Stack-audit orchestrator (sap-cap-stack-audit-full) Step 0b: the ask-
user template now annotates option 1 as *(default)* and adds best-for
context per option. When the user defers ("I don't know yet"), the
orchestrator defaults to BTP CF and emits a finding recommending the
customer confirm the target before deployment-readiness sign-off.
[skip ci]
…em-cf Two coordinated changes to align the skill's deployment-target story with operational reality: 1. Default target is now BTP Cloud Foundry (was implicit BTP Kyma in the original examples). Rationale: - BTP CF is the most widely-adopted SAP-managed runtime — broadest customer reach. - BTP CF has the broadest service ecosystem (Free + paid tiers for xsuaa, html5-apps-repo, destination, connectivity, event-mesh, audit-log, job-scheduling, …) — many of those have Free tiers that Kyma cannot consume. - BTP CF tooling is the most mature (mta.yaml + mbt build + cf deploy). - BTP CF has the lowest operational ceremony for teams without dedicated Kubernetes expertise — most SAP customers do not have a K8s operations team. BTP Kyma remains the right choice when the customer explicitly wants the Kubernetes operational model (pay-tier services, more runtime flexibility, container-native eventing, CronJob CRDs). The Examples section now shows --target=btp-kyma as an explicit override, with the default invocation `ZFI plan` going to BTP CF. 2. Removed `onprem-cf` from the supported targets. Rationale: SAP Cloud Foundry On-Premise reached end-of-maintenance. The skill should not propose deployment plans against an EOL target. Customers with existing CF on-prem investment should be advised to migrate to BTP CF (managed) or BTP Kyma, not to keep extending on the EOL runtime. Changes: - Input table: --target= now lists btp-cf (default) / btp-kyma / onprem-kyma — onprem-cf removed. - Examples updated to use `ZFI plan` (no explicit target) for the default case, and `--target=btp-kyma` for the explicit override. - Plan output template: side-by-side runtime variable list now reads <btp-cf | btp-kyma | onprem-kyma>. - BTP vs On-Premise Differences table: onprem-cf row removed; btp-cf marked as default. This is a coordinated change with the master skill and orchestrator on the Wave 2-3 branch (PR marianfoo#280, separate commit f24b31e + follow-up). [skip ci]
Removes the On-Premise Cloud Foundry deployment target from both the master skill (sap-cap-fiori-battle-tested-patterns Category 3) and the orchestrator (sap-cap-stack-audit-full Step 0). Rationale: SAP Cloud Foundry On-Premise reached end of maintenance. The skills should not propose deployment plans against an EOL runtime. Customers with existing on-prem CF investment should be advised to migrate to BTP CF (managed) or BTP Kyma, not to extend the EOL footprint. Changes: Master skill (sap-cap-fiori-battle-tested-patterns): - Category 3.0 decision matrix: On-Premise CF row removed; added a callout block "Not supported: On-Premise Cloud Foundry" with migration recommendation. - Narrative paragraph: "Choose On-Premise CF only for legacy continuity" sentence removed. - Section 3.D On-Premise CF patterns + 3.D.1 EOL pattern: fully removed (no longer relevant once the target is unsupported). Orchestrator (sap-cap-stack-audit-full): - Step 0a auth indicator detection: XSUAA hint now reads "BTP CF" only (was "BTP CF or On-Prem CF"). - Step 0b ask-user template: option 4 (On-Premise CF) removed. Added "Not supported" note: if auto-detection finds an on-prem CF environment, the orchestrator emits a strategic finding recommending migration and stops. - Step 0c valid $TARGET values: now btp-cf / btp-kyma / onprem-kyma (onprem-cf removed). Coordinated with the corresponding change on the erp-clean-core-refactor skill (PR marianfoo#281, commit 589d10f) which made the same removal there. [skip ci]
…dsky integration Deep integration with the surrounding tooling — ARC-1 MCP, arc-1 native skills, and secondsky/sap-skills plugins — to make the Level A refactor workflow rigorously grounded instead of relying on agent intuition. New SKILL.md additions: - Step 1e — Bootstrap system context (prereq). Runs bootstrap-system- context once per system to ground subsequent decisions in system-info.md (release, components, ATC preset, formatter). - Step 2e — Impact / dependency analysis via SAPContext(action=impact). THE most important MCP call: fan-in count drives effort × risk multipliers (0 callers = orphan/remove; 50+ = mandatory architectural review). Without this, the rewrite-vs-extract decision is blind. - Step 4d-quater — Pattern mining via SAPRead(VERSIONS, VERSION_SOURCE). Mines the customer's own history for refactor patterns already emerged (ZCL_*_OLD, ZCL_*_V2, version-history on the package). Reduces rewrite effort 30-50% on customers with established conventions. The mined pattern is cited in the plan alongside the SAP-released-API citation. - Step 4d (extended) — `explain-abap-code` invocation for research_required findings; narrows human research scope ~50%. - Step 6-pre — Generate regression tests BEFORE rewrite via generate-abap-unit-test (CLAS/FUGR) / generate-cds-unit-test (DDLS). The tests capture current behaviour as a baseline; after rewrite they become the regression gate. Objects where test generation is infeasible are flagged `rewrite_in_place_no_tests`. - Step 6a — Adds SAPLint(format) to honor project formatter, SAPDiagnose(run_unit_tests) for regression validation, generate- rap-logic + generate-rap-service-researched delegation when rewrite goes to RAP. - Step 6b — Cross-link convert-ui5-to-fiori-elements for the UI side of the side-by-side scaffold. - Step 6c — Delegate Level B documentation to sap-object-documenter (was inline SAPWrite(attach_sktd); now uses the dedicated skill that produces structured rationale). - Step 6.5 — Transport management: SAPTransport(requirement_check) before activate, SAPTransport(create|reassign) with phase/cluster strategy. Optional gCTS/abapGit auto-commit via SAPGit when SAP_ALLOW_GIT_WRITES=true. - Step 7 — Cumulative ATC regression + unit test full run + analyze-chat-session for learnings capture. Recommended Companion Plugins section restructured into MUST / SHOULD / OPTIONAL tiers: MUST (4 secondsky plugins): - sap-abap: ABAP language patterns reference, required during every rewrite_in_place so the generated ABAP is Cloud-compatible. - sap-abap-cds: CDS view design reference, required when rewrite introduces new CDS views. - sap-cap-capire: CAP framework with 4 dispatchable agents (cap-cds-modeler, cap-service-developer, cap-performance-debugger, cap-project-architect) invoked during side-by-side scaffold. - sap-btp-developer-guide: comprehensive BTP reference for target resolution and scaffold. SHOULD (5 plugins): sapui5, sap-fiori-tools, sapui5-linter, sap-btp-cloud-platform, sap-btp-connectivity, sap-cloud-sdk, sap-cloud-sdk-ai. OPTIONAL (8 plugins): Apify MCP, mcp-sap-docs, context7, sap-btp-job-scheduling, sap-btp-cloud-logging, sap-btp- master-data-integration, sap-btp-cloud-transport-management, sap-btp-cias, sap-btp-business-application-studio, sap-btp- integration-suite, sap-btp-build-work-zone-advanced, sap-btp-intelligent-situation-automation. arc-1 native skill chain (12 skills cross-linked in the steps): bootstrap-system-context, setup-abap-mirror, explain-abap-code, sap-clean-core-atc, sap-unused-code, sap-object-documenter, generate-abap-unit-test, generate-cds-unit-test, generate-rap- logic, generate-rap-service-researched, migrate-segw-to-rap, migrate-custom-code, modernize-abap-to-btp-cap chain, convert-ui5-to-fiori-elements, analyze-chat-session. New file INTEGRATIONS.md (173 lines): - Architectural roles (ARC-1 MCP = hands; arc-1 skills = playbook; secondsky = library of patterns; this skill = orchestrator). - Step-by-step integration map (7 tables, one per workflow step, columns: ARC-1 MCP × arc-1 skills × secondsky plugin × external). - Coverage assessment: this skill engages all 12 ARC-1 MCP tools at least once (only SAPNavigate is implicit via SAPContext). - Coverage assessment: 4 secondsky MUST + 7 SHOULD + 12 OPTIONAL plugins mapped; clear "NOT used by this skill" exclusion list. - Cost model by integration layer: €0 for ARC-1 / arc-1 skills / secondsky; €0.50-€5 for Apify JIT lookups (user-paid). README.md update: - Skill ships THREE files (was two): SKILL.md + SOURCES.md + INTEGRATIONS.md. - Required companion plugins section calls out the 4 secondsky MUST plugins with hyperlinks to their secondsky repo paths. - Notes the engagement of all 12 ARC-1 MCP tools and 12+ arc-1 native skills as a delegation chain. [skip ci]
Adds docs/sap-cap-toolkit.md (~770 lines) — a single navigation guide consolidating the 13-skill toolkit contributed across PRs marianfoo#278, marianfoo#279, marianfoo#280, and marianfoo#281. The doc is the entry point for users who want to understand the toolkit holistically rather than reading each SKILL.md in isolation. Structure (10 sections): 1. Mission — what problem the toolkit solves, audience, in/out of scope. 2. Quick start — 30-second setup + 3 most common invocations. 3. Toolkit at a glance — ASCII visual map showing 6 layers (reference, orchestration, audit, refactor, support, execution); skill count and provenance table. 4. Skill catalog — detailed per-skill description grouped by layer: - Reference (1): sap-cap-fiori-battle-tested-patterns (~70 patterns in 8 categories). - Orchestration (2): sap-cap-stack-audit-full, sap-cap-ci-gates- pattern. - Audit (5): sap-cap-clean-core-enforce, sap-cap-customizing-honor, sap-cap-security-rbac-matrix, sap-fiori-app-audit, sap-cap-text-polish. - Refactor (4): sap-erp-clean-core-refactor (with SOURCES.md + INTEGRATIONS.md companions), modernize-abap-to-btp-cap chain. 5. Strategies — 6 architectural patterns: - JIT lookups (no pre-built KB) with cost rationale. - Defense-in-depth (audit → enforcement → CI gates). - Three-layer architecture (hands × playbook × library). - Decision tree D→B / C→A / B-keep with 3 escalation mechanisms. - Target deployment matrix (btp-cf default, btp-kyma, onprem-kyma; onprem-cf dropped). - Cost model (€0.50-€5 per refactor, user-paid). 6. Dependencies — mandatory ARC-1 MCP, 4 MUST secondsky plugins (sap-abap, sap-abap-cds, sap-cap-capire, sap-btp-developer-guide), 7 SHOULD plugins, optional Apify/mcp-sap-docs/context7/playwright, Tier-1 git clones, Tier-2 JIT Apify. 7. Usage examples — 7 worked end-to-end scenarios: A. End-to-end Clean Core refactor of a Z* package B. Pre-release stack audit (BTP CAP project) C. Security & compliance review (OWASP/NIST/GDPR evidence) D. Single Fiori app audit E. Text polish before release + PII safety check F. Setting up CI gates from scratch G. Side-by-side extension scaffold from a Z FM 8. PR roadmap — the 4 open PRs + this consolidation, total ~6800 lines, 100% generic. 9. FAQs — 8 common questions (why JIT? what if no BTP? differences between sap-clean-core-atc / sap-erp-clean-core-refactor / sap-cap-clean-core-enforce? why no on-prem CF? etc.). 10. References — links to every skill SKILL.md, supporting arc-1 native skills, external documentation, methodology references. skills/README.md updated with a top-of-file link to the toolkit doc so readers landing on the skills index see the consolidated overview. This PR is structurally independent of PRs marianfoo#278/marianfoo#279/marianfoo#280/marianfoo#281. The toolkit doc references skills that ship in those PRs; cross-links degrade gracefully to dead links until those PRs merge. Once all four ship, the toolkit doc becomes fully navigable. [skip ci]
…p-toolkit-all-in-one
…olkit-all-in-one # Conflicts: # skills/README.md
…toolkit-all-in-one # Conflicts: # skills/README.md
…oolkit-all-in-one
This was referenced May 13, 2026
This commit narrows the PR scope to ABAP-side refactoring skills only. The CAP-side audit / hardening / CI-gate skills move to a separate companion repository at: https://github.com/Raistlin82/sap-cap-toolkit Rationale: cleaner separation of concerns. arc-1 is fundamentally an ABAP-focused MCP server, so the skills shipped here focus on ABAP custom-code refactoring (Z* → Clean Core compliance + side-by-side BTP extensions). CAP audit / Fiori audit / security / text polish / CI gates are a complementary toolkit that lives in its own repository. Removed from this PR (moved to Raistlin82/sap-cap-toolkit): - skills/sap-cap-clean-core-enforce - skills/sap-cap-customizing-honor - skills/sap-cap-security-rbac-matrix - skills/sap-fiori-app-audit - skills/sap-cap-text-polish - skills/sap-cap-stack-audit-full - skills/sap-cap-ci-gates-pattern - skills/sap-cap-fiori-battle-tested-patterns - docs/sap-cap-toolkit.md Retained in this PR: - skills/modernize-abap-to-btp-cap (orchestrator) - skills/modernize-abap-cap-schema (Z-table → CDS entity) - skills/modernize-abap-cap-service (FM/program → CAP service action) - skills/sap-erp-clean-core-refactor (ABAP Z* refactor planner) sap-erp-clean-core-refactor is now fully self-contained — ships FOUR files instead of three: - SKILL.md — the refactor protocol (~680 lines) - SOURCES.md — 23 SAP source catalog in 4 tiers (~85 lines) - PATTERNS.md — NEW: ~70 battle-tested patterns in 8 categories, ~1070 lines. Inlined from the sap-cap-fiori-battle-tested-patterns skill so the refactor skill doesn't depend on the companion repo for its target-resolution / side-by-side scaffold logic. Same content also published as a standalone skill in Raistlin82/sap-cap-toolkit for CAP-only audiences. - INTEGRATIONS.md — ARC-1 MCP × arc-1 skill × secondsky plugin mapping (~175 lines) Cross-references from the refactor skill files to the CAP-side audit skills (sap-cap-clean-core-enforce, sap-cap-stack-audit-full, etc.) are now external URLs pointing to github.com/Raistlin82/sap-cap-toolkit/blob/main/skills/<name>/SKILL.md — these are "see also" / coordinate-with references, not critical dependencies. The refactor skill works standalone; the CAP toolkit links provide context if both repos are installed. skills/README.md updated: - Top-of-file callout now redirects CAP-toolkit users to Raistlin82/sap-cap-toolkit instead of the local doc. - "SAP CAP Enterprise Audit" section removed (skills no longer here). - "SAP ERP — Clean Core Return" section updated to mention the new four-file ship (was three). [skip ci]
Raistlin82
changed the title
added 2 commits
May 13, 2026 18:15
Replaces project-specific names that had leaked into generic skill documentation with neutral terminology: - `NOVAEvents` declarative service → `BusinessEvents` (in PATTERNS.md Category 7 declarative event service pattern + connection cache example) - `emitNovaEvent(...)` helper → `emitBusinessEvent(...)` - "the target NOVA-style project" → "the target project" (in modernize-abap-to-btp-cap Step describing CI gate detection) - Prometheus metric names `nova_events_emit_total` / `nova_events_replay_total` → `business_events_emit_total` / `business_events_replay_total` (in outbox replay mirror pattern) The skills are designed to be 100% generic. Project-specific names shouldn't appear in examples even when they reflect production patterns — pick neutral domain words instead. Verified clean: grep -rniE 'nova' returns no matches in the refactor skill directory or modernize-abap-* skills. [skip ci]
Significant simplification of the 4 protocol files in the refactor PR. The original SKILL.md files were process-heavy with deep step-by-step pseudo-code that read like a NASA launch checklist. They worked but were intimidating to humans and largely redundant with the agent's own ability to infer steps from the structured tables. Strategy: - Lead with a 1-line description + a 3-row "what's in here" table. - Replace verbose step prose with compact tables (decision trees, type mappings, flag → effect, caller pattern → service shape). - Move every implementation detail that was duplicated across sections to a single canonical place (the table). - Keep all critical contracts: the per-object decision tree, the 3 modes, the ARC-1 MCP call patterns, the cross-skill delegation chain, the cost model, the gates. - Remove repeated "Why this matters" prose — the user landing here already knows. Per-file deltas: | Skill | Before | After | Δ | |-----------------------------------|--------|-------|--------| | sap-erp-clean-core-refactor | 675 | 161 | -76% | | modernize-abap-to-btp-cap | 362 | 118 | -67% | | modernize-abap-cap-schema | 375 | 117 | -69% | | modernize-abap-cap-service | 489 | 151 | -69% | | TOTAL SKILL.md | 1901 | 547 | -71% | Detail kept in reference docs (unchanged): - SOURCES.md (84 lines) — 23-source catalog - PATTERNS.md (1065 lines) — 70 battle-tested patterns - INTEGRATIONS.md (173 lines) — MCP × skill × secondsky mapping The agent reads the lean SKILL.md for the protocol, then consults the reference docs only when needed for a specific lookup. Same end-to-end behavior, much easier to navigate. [skip ci]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ABAP-side refactoring skills: take legacy custom code (Z*/Y*) and produce a refactor plan + executable migration to Clean Core compliance, including hand-off to side-by-side BTP CAP extensions.
4 new skills, all generic, no project-specific names.
Skills
sap-erp-clean-core-refactordiscover/plan/execute). Decision tree D→B / C→A / B-keep with 3 escalation mechanisms (--aggressive,--push-to-a,--target-level=A|B)modernize-abap-to-btp-capmodernize-abap-cap-schemamodernize-abap-cap-servicesap-erp-clean-core-refactorships four self-contained filesSKILL.md— the protocol (~680 lines)SOURCES.md— 23 authoritative SAP source catalog in 4 tiers (~85 lines)PATTERNS.md— ~70 production-distilled battle-tested patterns in 8 categories (UI5/FE V4 traps, CAP/TS pitfalls, BTP/Kyma/OnPrem deployment with 4-target decision matrix, security defense-in-depth, customizing-driven patterns, lifecycle/process, post-commit events/messaging, ecosystem plugins) — consulted during Step 1c target resolution + Step 6b side-by-side scaffold (~1070 lines)INTEGRATIONS.md— step-by-step mapping of refactor phase × ARC-1 MCP tool × arc-1 native skill × secondsky/sap-skills plugin × external sources (~175 lines)Strategies (architectural patterns)
--aggressive/--push-to-a/--target-level=A).Required companion plugins (4 from secondsky/sap-skills)
sap-abap— ABAP language patterns referencesap-abap-cds— CDS view designsap-cap-capire— CAP framework (4 dispatchable agents)sap-btp-developer-guide— comprehensive BTP referenceEngagement
Companion repository for CAP-side audits
For audit / hardening / CI gates of the CAP applications generated by the refactor skills, see the separate companion repository
Raistlin82/sap-cap-toolkit(8 skills:sap-cap-clean-core-enforce,sap-cap-customizing-honor,sap-cap-security-rbac-matrix,sap-fiori-app-audit,sap-cap-text-polish,sap-cap-stack-audit-full,sap-cap-ci-gates-pattern,sap-cap-fiori-battle-tested-patterns).Cross-references from this PR's skills to the CAP toolkit are external URLs ("see also" / coordinate-with references), not critical dependencies. The refactor skill works standalone.
Stats