arc-mcp · Raistlin82 · May 13, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/skills/README.md b/skills/README.md
@@ -4,6 +4,8 @@ Best-practice agent skills for common SAP development workflows with ARC-1.
 
 Each skill is a directory containing a `SKILL.md` file with YAML frontmatter — the format used by [Anthropic Agent Skills](https://code.claude.com/docs/en/skills) and consumed by the [`vercel-labs/skills`](https://github.com/vercel-labs/skills) CLI. Agents discover them by `description` and load them on demand.
 
+> **CAP-side audit toolkit lives in a separate repo.** For audit / hardening / CI gates of CAP + Fiori Elements V4 + BTP applications consuming S/4HANA Tier-2 services, see [`Raistlin82/sap-cap-toolkit`](https://github.com/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`). The skills in `arc-1` focus on ABAP-side custom-code refactoring (`sap-erp-clean-core-refactor` + `modernize-abap-*` chain); they generate CAP code that the audit toolkit in the companion repo verifies.
+
 ## Install via the `skills` CLI (recommended)
 
 The fastest way is `npx skills` — it auto-detects the agents installed in your project (Claude Code, Cursor, GitHub Copilot, OpenCode, Gemini CLI, Codex, …) and installs into the right paths.
@@ -100,6 +102,24 @@ Both skills produce the same RAP artifact stack. The difference is how they get
 | [migrate-custom-code](migrate-custom-code/SKILL.md) | Runs ATC readiness checks, groups findings by priority, and generates replacement code | Preparing custom code for S/4HANA migration or ABAP Cloud readiness |
 | [sap-object-documenter](sap-object-documenter/SKILL.md) | Batch-documents many custom objects at once — purpose, style (Classic/Modern/Mixed), dependencies — as Markdown | Onboarding packages, handoffs, seeding a repo wiki (vs. explain-abap-code which is single-object interactive) |
 
+### SAP ERP — Clean Core Return + Side-by-Side Refactor (Preview)
+
+Plans and executes the refactor of custom ABAP / ERP / S/4HANA code back to Clean Core compliance — discovery via ARC-1, classification via `sap-clean-core-atc`, **just-in-time documentation lookup** against authoritative SAP sources (no pre-crawled KB), and hand-off to `modernize-abap-to-btp-cap` for side-by-side extension scaffolds.
+
+| Skill | What it does | When to use |
+|---|---|---|
+| [sap-erp-clean-core-refactor](sap-erp-clean-core-refactor/SKILL.md) | Inventories Z/Y custom code via ARC-1, classifies Clean Core Level A/B/C/D, consults authoritative SAP sources just-in-time (git-clone of `abap-atc-cr-cv-s4hc` + curated `SAP-samples` + `cloud-sdk`; Apify on-demand for `api.sap.com` / `help.sap.com` / `developers.sap.com` / `cap.cloud.sap` / community / blogs), and emits a per-object refactor plan with rewrite-in-place / extract-to-side-by-side / keep-at-B decisions. Apify lookups bounded per finding (~5 pages); user pays for own Apify account; results cached locally for 30 days | Planning a Clean Core compliance program; pre / post-S/4HANA migration cleanup; quarterly governance review |
+
+The skill ships **four files** so it is fully self-contained: [`SKILL.md`](sap-erp-clean-core-refactor/SKILL.md) (the protocol), [`SOURCES.md`](sap-erp-clean-core-refactor/SOURCES.md) (curated catalog of 23 authoritative SAP sources organized in 4 tiers), [`PATTERNS.md`](sap-erp-clean-core-refactor/PATTERNS.md) (~70 battle-tested production patterns in 8 categories — consulted during target resolution and side-by-side scaffold), and [`INTEGRATIONS.md`](sap-erp-clean-core-refactor/INTEGRATIONS.md) (step-by-step mapping of refactor phase × ARC-1 MCP tool × arc-1 skill × [secondsky/sap-skills](https://github.com/secondsky/sap-skills) plugin × external sources). **No centralized KB is shipped**; documentation lookups happen on-demand within a bounded per-finding budget, charged to the user's own Apify account at ~€0.005-0.02 per lookup (typical refactor: €0.50-€5 total).
+
+**Required companion plugins** (the skill is materially less useful without them — all four enforced as MUST in [`INTEGRATIONS.md`](sap-erp-clean-core-refactor/INTEGRATIONS.md)):
+- **`sap-abap`** ([secondsky/sap-skills](https://github.com/secondsky/sap-skills/tree/main/plugins/sap-abap)) — ABAP language patterns reference, required during Step 6a `rewrite_in_place` so generated ABAP is Cloud-compatible.
+- **`sap-abap-cds`** ([secondsky/sap-skills](https://github.com/secondsky/sap-skills/tree/main/plugins/sap-abap-cds)) — CDS view design reference, required when rewrite introduces new CDS views.
+- **`sap-cap-capire`** ([secondsky/sap-skills](https://github.com/secondsky/sap-skills/tree/main/plugins/sap-cap-capire)) — CAP framework, ships 4 dispatchable agents (`cap-cds-modeler`, `cap-service-developer`, `cap-performance-debugger`, `cap-project-architect`) invoked during Step 6b side-by-side scaffold.
+- **`sap-btp-developer-guide`** ([secondsky/sap-skills](https://github.com/secondsky/sap-skills/tree/main/plugins/sap-btp-developer-guide)) — comprehensive BTP reference, required during target resolution and scaffold generation.
+
+The skill engages **all 12 ARC-1 MCP tools** (`SAPRead` source + VERSIONS, `SAPWrite` in-place rewrite, `SAPContext` impact analysis — the most important call, `SAPLint` ATC + formatting, `SAPDiagnose` unit tests, `SAPTransport`, …) and **9 arc-1 native skills** as a delegation chain (`bootstrap-system-context`, `setup-abap-mirror`, `sap-clean-core-atc`, `sap-unused-code`, `explain-abap-code`, `sap-object-documenter`, `generate-abap-unit-test`, `generate-cds-unit-test`, `generate-rap-logic`, `modernize-abap-to-btp-cap` chain, `convert-ui5-to-fiori-elements`, `analyze-chat-session`). See [`INTEGRATIONS.md`](sap-erp-clean-core-refactor/INTEGRATIONS.md) for the full coverage table.
+
 ### Clean Core & Custom Code Retirement
 
 | Skill | What it does | When to use |
@@ -131,6 +151,42 @@ Both run against the same V4 RAP service produced by `migrate-segw-to-rap`. The
 | **Skill depends on** | ARC-1 + sap-docs + ui5-mcp-server + fiori-mcp | ARC-1 (optional) + sap-docs + ui5-mcp-server + browser MCP |
 | **Maturity** | Driven by `@sap-ux/fiori-mcp-server` 3-step API + annotation-discovery via `mcp__sap-docs__search` | 5 documented Critical Traps from accumulated run learnings; teaches LLM to investigate via Self-help patterns |
 
+### BTP CAP Modernization (Preview)
+
+End-to-end greenfield migration from classic ABAP custom code (Z* packages) to BTP-native CAP applications. Side-by-side approach — leaves the source ABAP system untouched and produces a complete target CAP project (CDS schema, services, Fiori Elements V4 app, CF deployment artifacts) for review and manual activation.
+
+| Skill | What it does | When to use |
+|---|---|---|
+| [modernize-abap-to-btp-cap](modernize-abap-to-btp-cap/SKILL.md) | End-to-end migration orchestrator: Z package → BTP CAP scaffold (CDS + service + Fiori + xs-security + mta.yaml + ADRs) | Planning ECC / on-prem S/4 → BTP CAP greenfield migration |
+| [modernize-abap-cap-schema](modernize-abap-cap-schema/SKILL.md) | Z-tables (SE11) → CAP CDS entities with DDIC→CDS type mapping, FK→association inference, `cuid`/`managed` aspect auto-application | Data-model migration step; standalone for reverse-engineering Z tables to CDS |
+| [modernize-abap-cap-service](modernize-abap-cap-service/SKILL.md) | Z function modules / reports / classes → CAP service definitions + TypeScript handler stubs with TODO markers + ABAP source excerpts | Service-layer migration step; produces compile-clean scaffold ready for business-logic translation |
+
+#### Modernization vs Cloud-Readiness skills
+
+- [sap-clean-core-atc](sap-clean-core-atc.md) classifies whether code **can stay in ABAP and move to S/4HANA Cloud / ABAP Cloud**. Source system stays SAP.
+- [migrate-custom-code](migrate-custom-code.md) **fixes ATC findings in place** to make ABAP cloud-ready. Source system stays SAP.
+- [modernize-abap-to-btp-cap](modernize-abap-to-btp-cap/SKILL.md) **rebuilds the application as BTP CAP** — leaves source ABAP untouched, produces a parallel BTP-native stack. Use when the target architecture is a CAP application, not just cloud-ready ABAP.
+
+#### Typical BTP modernization workflow
+
+```
+1. bootstrap-system-context           →  Capture source SID, release, features
+2. sap-unused-code                    →  Scope: skip dead code from migration
+3. sap-clean-core-atc                 →  Risk assessment per Z object
+4. modernize-abap-to-btp-cap          →  Generate target CAP scaffold (orchestrator)
+   ├── modernize-abap-clean-core-gap  →  (sub-skill, planned) per-edition availability
+   ├── modernize-abap-cap-schema      →  db/schema.cds
+   ├── modernize-abap-cap-service     →  srv/*.cds + handlers stubs
+   ├── modernize-abap-fiori-elements  →  (sub-skill, planned) app/<name>/
+   ├── modernize-abap-auth-mapping    →  (sub-skill, planned) xs-security.json
+   └── modernize-abap-btp-mta         →  (sub-skill, planned) mta.yaml + Dockerfile
+5. Manual: implement handler TODOs    →  Translate ABAP business logic
+6. generate-cds-unit-test             →  Test the new CAP entities
+7. mbt build + cf deploy              →  Ship to BTP CF
+```
+
+> **Status**: Preview / Work-in-Progress. Orchestrator + schema + service skills available now. Remaining sub-skills (`clean-core-gap`, `fiori-elements`, `auth-mapping`, `btp-mta`) tracked in [#TBD upstream issue]. Feedback welcome on the [PR thread].
+
 ### System Context & Local Workflow
 
 | Skill | What it does | When to use |
@@ -191,3 +247,23 @@ For end-to-end legacy SEGW + UI5 modernization (backend + UI):
 ```
 
 The three migration skills are explicitly designed as parallel paths after the backend lands. You don't run both UI skills — you pick the one whose architecture matches your legacy app's complexity and your team's preference.
+
+For SAP CAP enterprise audit (pre-release readiness for a CAP + Fiori Elements + S/4 Tier-2 stack on BTP):
+
+```
+1. sap-cap-stack-audit-full     →  Run the full audit stack in parallel; consolidated report
+                                    (orchestrates all the skills below)
+
+   Composed of:
+   - sap-cap-clean-core-enforce →  Audit Tier-2 S/4 service availability vs released-state repo
+   - sap-cap-customizing-honor  →  Bidirectional CSV↔code parameter consistency
+   - sap-cap-security-rbac-matrix →  OWASP/ASVS/NIST + role coherence across 4 layers
+   - sap-fiori-app-audit (xN)   →  Per-app UI/UX + frontend/backend contract chain
+   - sap-cap-text-polish        →  User-visible text + PII safety + i18n bundle gaps
+
+2. sap-cap-ci-gates-pattern     →  Lock the audit findings into CI gates that prevent regression
+                                    (bidirectional, raise-coverage, availability-drift,
+                                     convention-drift, csv-lint)
+```
+
+The seven CAP audit skills are designed as a single toolkit. Run `sap-cap-stack-audit-full` to dispatch everything at once, or invoke individual skills for a focused investigation. Findings flow into `sap-cap-ci-gates-pattern` so the audit converts to enforced CI gates, not one-off checks.
diff --git a/skills/modernize-abap-cap-schema/SKILL.md b/skills/modernize-abap-cap-schema/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: modernize-abap-cap-schema
+description: Generate a CAP CDS data model (`db/schema.cds`) from a Z* package's ABAP database tables. Maps DDIC types to CDS, infers Associations/Compositions from foreign keys, auto-applies `cuid` / `managed` aspects. Use when asked to "convert Z tables to CDS entities", "generate CAP schema from ABAP TABL", "reverse-engineer Z tables", or as sub-skill of `modernize-abap-to-btp-cap`.
+---
+
+# Modernize ABAP → CAP Schema
+
+Produces `<target>/db/schema.cds` from a Z* package's tables (`TABL`). Greenfield CDS for the **CAP runtime** (`@sap/cds`), NOT ABAP CDS DDL.
+
+Sub-skill of [`../modernize-abap-to-btp-cap/SKILL.md`](../modernize-abap-to-btp-cap/SKILL.md). Also usable standalone for table-only reverse-engineering.
+
+## Input
+
+```
+<Z-package> <target-dir> [--namespace=com.example.foo]
+```
+
+## Defaults
+
+| Aspect | Default |
+|---|---|
+| Output | `<target>/db/schema.cds` |
+| Namespace | derived from package: `com.example.<package_lower>` |
+| `cuid` aspect | auto-applied if PK is `sysuuid_x16` (RAW(16)) |
+| `managed` aspect | auto-applied if table has any of `crusr` / `crdat` / `cruzt` / `chusr` / `chdat` / `chuzt` |
+| `temporal` aspect | NOT auto-applied (rare 1:1 mapping; flag for user review) |
+| Key | first DDIC key field |
+| Currency / Quantity | `@Semantics.amount.currencyCode` / `@Semantics.quantity.unitOfMeasure` |
+| Comments | DDIC short text + field labels → `@Common.Label` |
+
+## DDIC → CDS type mapping (24 mappings)
+
+| DDIC | CDS | Notes |
+|---|---|---|
+| CHAR(n) | `String(n)` | preserve length |
+| NUMC(n) | `String(n)` | leading-zero numeric; CAP-side validation up to user |
+| DEC(p,s) / CURR(p,s) / QUAN(p,s) | `Decimal(p,s)` | currency/quantity get semantic annotation |
+| INT1 / INT2 / INT4 | `Integer` / `Int16` / `Int32` | |
+| INT8 | `Int64` | |
+| FLTP | `Double` | |
+| RAW(n) / SSTRING / STRING | `Binary(n)` / `String` / `LargeString` | |
+| RAW(16) | `UUID` (auto via `cuid`) | UUID convention |
+| RAWSTRING | `LargeBinary` | |
+| DATS | `Date` | |
+| TIMS | `Time` | |
+| TZNTSTMPS | `Timestamp` | with timezone |
+| LCHR / LRAW | `LargeString` / `LargeBinary` | |
+| UNIT (CUKY) | `Association to Currencies` | when associated with amount field |
+| MEINS | `Association to Units` | when associated with quantity field |
+| LANG (SPRAS) | `Association to Languages` | |
+| CLNT | `String(3)` | client field — usually omitted in BTP CAP |
+
+## Workflow
+
+### Step 1 — Enumerate tables
+
+`SAPSearch(tadir_lookup, devclass=<pkg>, object='TABL')` → list of Z tables.
+
+### Step 2 — Read DDIC details (per table)
+
+`SAPRead(type='TABL', name=<table>)` — fields + types + keys + foreign keys + domain references.
+
+For complex domains / data elements: drill in only when the DDIC type alone is insufficient (e.g. fixed value lists → `@assert.range`).
+
+### Step 3 — Apply type mapping + aspects
+
+Walk each field through the table above. For each table, decide aspects:
+- `cuid` if RAW(16) primary key
+- `managed` if audit columns present
+- `localized` if `texts` companion table detected (`<table>T`)
+
+### Step 4 — Infer Associations
+
+From DDIC foreign-key references:
+
+| FK cardinality | Heuristic | CAP relation |
+|---|---|---|
+| Child table with parent FK + parent owns lifecycle | parent has stronger semantics | `Composition of many <Child>` on parent |
+| Lookup / master data (Currencies, Units, Languages) | shared catalog | `Association to <Master>` |
+| Generic FK to entity not owned | independent lifecycle | `Association to <Entity>` |
+
+Bidirectional inference: write both sides (`<parent>.items : Composition of many <child>` AND `<child>.parent : Association to <parent>`).
+
+### Step 5 — Emit + validate
+
+Write `<target>/db/schema.cds` in CAP pretty-print format. Validate via:
+
+```bash
+npx cds compile <target>/db/schema.cds --to edmx > /dev/null && echo "OK"
+```
+
+### Step 6 — Migration notes
+
+Write `<target>/docs/schema-notes.md` with:
+- Tables migrated + their CAP entity name + namespace
+- Aspects auto-applied
+- Associations inferred + cardinality reasoning
+- Manual review items: temporal candidates, ambiguous FKs, `LCHR` / `LRAW` size limits
+
+## Gotchas
+
+- **MANDT (client) field**: drop on BTP CAP (no client concept). Flag if data needs cross-client merge.
+- **`@AbapCatalog` annotations** (DDIC): do NOT carry over; CAP has its own (`@cds.persistence.skip`, `@assert.range`, etc.).
+- **Domain fixed values**: map to `@assert.range` if ≤10 values, otherwise emit a CodeList entity.
+- **Hierarchical / parent-child Z tables**: review `Composition` choice — sometimes Association is safer (no cascade delete).
+
+## When NOT to use
+
+- Greenfield CDS design from scratch → use [`../generate-rap-service/SKILL.md`](../generate-rap-service/SKILL.md) or hand-write
+- View-only entities (no underlying TABL) → not the target of this skill
+- Multi-package data model with cross-package FK → split into multiple invocations, then merge manually
+
+## References
+
+- [SAP CAP — CDS Modeling](https://cap.cloud.sap/docs/cds/cdl)
+- [CAP — Common Reuse Aspects](https://cap.cloud.sap/docs/cds/common) (`cuid`, `managed`, `temporal`, `localized`)
+- DDIC types → CDS types: [SAP — ABAP CDS Types](https://help.sap.com/docs/abap-cloud/abap-data-types) (cross-reference for ABAP CDS vs CAP CDS)