abapgit-agent 1.13.3 → 1.13.4

package/abap/CLAUDE.md

@@ -70,24 +70,93 @@ abapgit-agent ref --list-topics
 ```
 
 The folder is configured in `.abapGitAgent` (property: `folder`):
-- If `folder` is `/src/` → files go in `src/` (e.g., `src/zcl_my_class.clas.abap`)
-- If `folder` is `/abap/` → files go in `abap/` (e.g., `abap/zcl_my_class.clas.abap`)
+- If `folder` is `/src/` → files go in `src/`
+- If `folder` is `/abap/` → files go in `abap/`
 
 **Also check naming conventions before creating any new object:**
 
 ```
-1. Check guidelines/objects.local.md  ← project-specific overrides (if file exists)
-2. Fall back to guidelines/objects.md ← default Z/Y prefix conventions
+1. Check guidelines/objects.local.md  ← this project's actual conventions (if file exists)
+2. No objects.local.md?               ← customer namespace project, use Z/Y defaults
 ```
 
-`objects.local.md` is created by `abapgit-agent init` and is never overwritten by updates — it holds project-specific prefixes (e.g. `YCL_` instead of `ZCL_`).
+`objects.local.md` is never overwritten by updates. It specifies the production naming
+pattern — which may be customer namespace (`ZCL_*`, `YCL_*`), SAP namespace (`CL_*`),
+or SAP registered namespace (`/NAMESPACE/CL_*` — also SAP namespace, not customer).
+Never assume Z/Y prefix without checking.
+
+**SAP namespace vs customer namespace:**
+- **Customer namespace**: `Z*`, `Y*` objects; `Z*`, `Y*`, `$*` packages — owned by the customer
+- **SAP namespace**: everything else (`CL_*`, `IF_*`, `/NAMESPACE/*`) — delivered by SAP
 
 ---
 
-### 3. Create XML Metadata / Local Classes
+### 3. Creating a New ABAP Object — Files to Write and Package Assignment
 
-Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
-→ See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
+```
+❌ WRONG: Only write the .abap source file
+✅ CORRECT: Every object needs both a source file AND an XML metadata file
+           XML-only objects (TABL, STRU, DTEL, TTYP) need ONLY the XML file
+```
+
+Use the object name from `objects.local.md` (or `objects.md` as fallback) in place of `<name>`:
+
+| Object Type | Source File | XML File |
+|-------------|-------------|----------|
+| Class (CLAS) | `<name>.clas.abap` | `<name>.clas.xml` |
+| Interface (INTF) | `<name>.intf.abap` | `<name>.intf.xml` |
+| Program (PROG) | `<name>.prog.abap` | `<name>.prog.xml` |
+| CDS View (DDLS) | `<name>.ddls.asddls` | `<name>.ddls.xml` |
+| Table (TABL) | *(none)* | `<name>.tabl.xml` |
+| Structure (STRU) | *(none)* | `<name>.stru.xml` |
+| Data Element (DTEL) | *(none)* | `<name>.dtel.xml` |
+| Table Type (TTYP) | *(none)* | `<name>.ttyp.xml` |
+
+**Package assignment — determine the package, then follow the confirmation rule below:**
+
+```
+1. Check objects.local.md for package rules  ← use them directly
+2. No package rules in objects.local.md?
+   └── Read .abapGitAgent → get the package property → use as root
+       Run: abapgit-agent tree --package <root>
+       ├── Only one package found   →  use it directly
+       └── Multiple packages found  →  present options, ask user to choose
+3. No package in .abapGitAgent?
+   └── Ask the user for the root package
+```
+
+**Confirmation before writing files — depends on namespace:**
+
+```
+Object name starts with Z* or Y*  AND  package starts with Z*, Y*, or $*?
+  └── Customer namespace object in customer package
+      → Write files directly. No confirmation needed.
+
+Anything else (SAP namespace object, or SAP-delivered package)?
+  └── Show a creation summary and wait for explicit confirmation:
+
+      "I'm going to create the following:
+
+        Object:   <NAME> (<Type>)
+        Package:  <PACKAGE>
+        Files:    <folder>/<name>.<ext>.abap
+                  <folder>/<name>.<ext>.xml
+
+      Shall I proceed?"
+```
+
+```
+❌ WRONG: Write files without showing the summary for SAP namespace objects
+❌ WRONG: Run abapgit-agent tree and pick a package yourself
+✅ CORRECT: Customer namespace → write directly
+✅ CORRECT: SAP namespace → always show summary, wait for confirmation
+```
+
+> **Tip for project setup**: Add package rules to `objects.local.md` so Claude never
+> needs to ask. See `guidelines/objects.md` for examples.
+
+→ For exact XML templates: `abapgit-agent ref --topic abapgit`
+→ For local helper/test-double class files: `abapgit-agent ref --topic object-creation`
 
 ---
 
@@ -102,14 +171,15 @@ Each ABAP object needs an XML metadata file. Local helper/test-double classes us
 
 ```bash
 # Check syntax of local code (no commit/push needed)
-abapgit-agent syntax --files src/zcl_my_class.clas.abap
-abapgit-agent syntax --files src/zc_my_view.ddls.asddls
+# Use the actual filename from your project (name comes from objects.local.md)
+abapgit-agent syntax --files src/<name>.clas.abap
+abapgit-agent syntax --files src/<name>.ddls.asddls
 
 # Check multiple INDEPENDENT files
-abapgit-agent syntax --files src/zcl_utils.clas.abap,src/zcl_logger.clas.abap
+abapgit-agent syntax --files src/<name1>.clas.abap,src/<name2>.clas.abap
 ```
 
-**For other types (DDLS, FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
+**For other types (FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
 
 **Why use syntax command?**
 - Catches syntax errors BEFORE polluting git history with fix commits
@@ -126,11 +196,11 @@ When checking multiple files, each is validated in isolation:
 **For dependent files, skip `syntax` and use `pull` instead:**
 ```bash
 # ❌ BAD - Interface and implementing class (may show false errors)
-abapgit-agent syntax --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 
 # ✅ GOOD - Use pull instead for dependent files
 git add . && git commit && git push
-abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+abapgit-agent pull --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 ```
 
 **Note**: `inspect` still runs against ABAP system (requires pull first). Use `syntax` for pre-commit checking.
@@ -256,11 +326,29 @@ After activating a class, stop and tell the user: `"Class is activated. Run with
 
 ---
 
-### 10. Probe Classes — Use `scratchWorkspace` When Required
+### 10. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
+
+```
+❌ WRONG: Create a probe/PoC object with the project's SAP namespace prefix
+❌ WRONG: Assign a probe/PoC object to an SAP-delivered package
+✅ CORRECT: Probe/PoC objects always use Z* or Y* prefix
+✅ CORRECT: Always assign to a customer namespace package (Z*, Y*, or $*)
+```
+
+This rule applies even on projects where production objects use SAP namespace (`CL_*`, `/NAMESPACE/*`).
+
+**Trigger — when `objects.local.md` shows a SAP namespace prefix (`CL_*`, `IF_*`, `/NAMESPACE/*`)
+and the user asks to create a new object, always ask first:**
 
-By default, probe/throwaway classes may be created in the current project. When `disableProbeClasses: true` is set in `.abapgit-agent.json`, they must go to `scratchWorkspace` instead. If `scratchWorkspace` is also not configured, refuse and guide the user to set it up.
+```
+"Is this a production object, a PoC (will persist, needs its own package/repo),
+ or a probe (throwaway, run once)?"
+```
 
-→ See `guidelines/run-probe-classes.md` — run: `abapgit-agent ref --topic run-probe-classes`
+Never assume — wait for the user's answer before proceeding.
+
+→ For full decision flow (how to determine namespace, probe vs PoC, scratchWorkspace,
+  pocWorkspace, setup instructions): `abapgit-agent ref --topic probe-poc`
 
 ---
 
@@ -355,11 +443,11 @@ If workflow mode is `"trunk"` or not set, commit directly to the default branch:
 ```bash
 git checkout main  # or master/develop (auto-detected)
 git pull origin main
-edit src/zcl_auth_handler.clas.abap
-abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
-git add . && git commit -m "feat: add authentication handler"
+# edit your ABAP file (name from objects.local.md)
+abapgit-agent syntax --files src/<name>.clas.abap
+git add . && git commit -m "feat: description"
 git push origin main
-abapgit-agent pull --files src/zcl_auth_handler.clas.abap --sync-xml
+abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 ```
 
 ### AI Tool Guidelines
@@ -400,7 +488,14 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap --sync-xml
 2. ✓ Inform the user that run is disabled for this project
 
 **When `safeguards.disableProbeClasses = true`:**
-1. ✗ Do not create probe classes in the current project — see Rule 10 and `guidelines/run-command.md`
+1. ✗ Do not create probe classes in the current project
+2. ✓ If `scratchWorkspace` is configured → create probe class there (see Rule 10)
+3. ✗ If `scratchWorkspace` is NOT configured → refuse, tell user to configure it in `.abapGitAgent`
+
+**When user requests a PoC object:**
+1. ✓ Read `pocWorkspace.path` from `.abapGitAgent`
+2. ✓ If configured → read `{path}/.abapGitAgent` for package, show confirmation summary, wait for user
+3. ✗ If NOT configured → refuse, tell user to set up a PoC repo and configure `pocWorkspace.path`
 
 **When `conflictDetection.mode = "ignore"` or not set:**
 1. ✓ Run `pull` normally — no conflict flags needed
@@ -443,10 +538,14 @@ Modified ABAP files?
 │  │  └─ ✅ Use: syntax → commit → push → pull --sync-xml
 │  └─ Dependent files (interface + class, class uses class)?
 │     └─ ✅ Use: skip syntax → commit → push → pull --sync-xml
-└─ Other types (DDLS, FUGR, TABL, etc.)?
-   └─ ✅ Use: skip syntax → commit → push → pull --sync-xml → (if errors: inspect)
+└─ Other types (FUGR, TABL, STRU, DTEL, TTYP, etc.)?
+   ├─ XML-only objects (TABL, STRU, DTEL, TTYP)?
+   │  └─ ✅ Use: skip syntax → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
+   └─ FUGR and other complex objects?
+      └─ ✅ Use: skip syntax → commit → push → pull --sync-xml → (if errors: inspect)
 ```
 
+→ For creating new objects (what files to write): `abapgit-agent ref --topic object-creation`
 → See `guidelines/workflow-detailed.md` — run: `abapgit-agent ref --topic workflow-detailed`
 
 ---
@@ -479,6 +578,7 @@ Detailed guidelines are available in the `guidelines/` folder:
 | `guidelines/debug-session.md` | Debug Session Guide |
 | `guidelines/debug-dump.md` | Dump Analysis Guide |
 | `guidelines/run-probe-classes.md` | run Command — AI Guidelines (probe classes, scratchWorkspace) |
+| `guidelines/probe-poc.md` | Probe and PoC — Full Decision Flow |
 | `guidelines/branch-workflow.md` | Branch Workflow |
 | `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
 | `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |

package/abap/guidelines/abapgit.md

@@ -19,13 +19,17 @@ Class              | zcl_*.clas.abap              | zcl_*.clas.xml
 Test Class         | zcl_*.clas.testclasses.abap | zcl_*.clas.xml
 Interface          | zif_*.intf.abap             | zif_*.intf.xml
 Program            | z*.prog.abap                | z*.prog.xml
-Table              | z*.tabl.abap                | z*.tabl.xml
 CDS View (DDLS)    | zc_*.ddls.asddls            | zc_*.ddls.xml
-Data Element       | z*.dtel.abap                | z*.dtel.xml
-Structure          | z*.stru.abap                | z*.stru.xml
-Table Type         | z*.ttyp.abap                | z*.ttyp.xml
+Table (TABL)       | (no .abap file)             | z*.tabl.xml
+Structure (STRU)   | (no .abap file)             | z*.stru.xml
+Data Element (DTEL)| (no .abap file)             | z*.dtel.xml
+Table Type (TTYP)  | (no .abap file)             | z*.ttyp.xml
 ```
 
+> **XML-only objects (TABL, STRU, DTEL, TTYP)** have **no ABAP source file**. abapGit serializes
+> them as XML metadata only. When using `--files`, pass the `.xml` file directly:
+> `abapgit-agent pull --files abap/zmy_table.tabl.xml --sync-xml`
+
 > **CRITICAL: Always write XML files with a UTF-8 BOM (`\ufeff`) as the very first character**, before `<?xml ...`.
 > Without the BOM, abapGit shows the object as **"M" (modified)** after every pull because the
 > serializer always produces XML with BOM — and every byte matters.
@@ -244,6 +248,8 @@ abapGit's serializer **omits fields that have their default value**. Writing ext
 
 **Filename**: `src/zmy_table.tabl.xml`
 
+> **XML-only object** — no `.abap` source file. Pull with: `pull --files src/zmy_table.tabl.xml`
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_TABL" serializer_version="v1.0.0">
@@ -313,6 +319,8 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
 
 **Filename**: `src/zmy_dtel.dtel.xml`
 
+> **XML-only object** — no `.abap` source file. Pull with: `pull --files src/zmy_dtel.dtel.xml`
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
@@ -323,9 +331,9 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
     <DDLANGUAGE>E</DDLANGUAGE>
     <DDTEXT>Description of data element</DDTEXT>
     <REPTEXT>Description</REPTEXT>
-    <SCRTEXT_S>Short</SCRTEXT_S>
-    <SCRTEXT_M>Medium</SCRTEXT_M>
-    <SCRTEXT_L>Long Description</SCRTEXT_L>
+    <SCRTEXT_S>Short text</SCRTEXT_S>
+    <SCRTEXT_M>Medium text</SCRTEXT_M>
+    <SCRTEXT_L>Long description text</SCRTEXT_L>
     <DTELMASTER>E</DTELMASTER>
     <DATATYPE>CHAR</DATATYPE>
     <LENG>000010</LENG>
@@ -338,9 +346,84 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
 **Key Fields**:
 - `ROLLNAME`: Data element name
 - `DDTEXT`: Description (**not** `DESCRIPT`)
+- `REPTEXT` / `SCRTEXT_S` / `SCRTEXT_M` / `SCRTEXT_L`: Field labels (report heading, short, medium, long)
+- `DTELMASTER`: Language key for label master (`E` for English)
 - `DATATYPE`: Data type (`CHAR`, `NUMC`, `DATS`, `TIMS`, `INT4`, etc.)
 - `LENG`: Length padded to 6 digits (e.g. `000010` for 10 characters)
 
+**Omit `<PARAMID>`** unless you specifically need a SET/GET parameter ID — the serializer omits it when empty, so including an empty tag causes a permanent diff.
+
+---
+
+### Structure (STRU)
+
+**Filename**: `src/zmy_struct.stru.xml`
+
+> **XML-only object** — no `.abap` source file. abapGit uses the same TABL serializer for STRU.
+> Pull with: `pull --files src/zmy_struct.stru.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_TABL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD02V>
+    <TABNAME>ZMY_STRUCT</TABNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <TABCLASS>INTTAB</TABCLASS>
+    <DDTEXT>Description of the structure</DDTEXT>
+    <CONTFLAG>A</CONTFLAG>
+   </DD02V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key difference from TABL**: `TABCLASS` is `INTTAB` (internal table / structure) instead of `TRANSP`.
+
+**Note**: Like TABL, after the first pull abapGit expands the XML with `<DD03P_TABLE>` field definitions. When creating a new structure you only need the `<DD02V>` header.
+
+---
+
+### Table Type (TTYP)
+
+**Filename**: `src/zmy_ttyp.ttyp.xml`
+
+> **XML-only object** — no `.abap` source file.
+> Pull with: `pull --files src/zmy_ttyp.ttyp.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_TTYP" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD40V>
+    <TYPENAME>ZMY_TTYP</TYPENAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>Description of table type</DDTEXT>
+    <ROWTYPE>ZMY_STRUCT</ROWTYPE>
+    <ROWKIND>S</ROWKIND>
+    <DATATYPE>TABLE_T</DATATYPE>
+    <ACCESSMODE>T</ACCESSMODE>
+    <KEYDEF>D</KEYDEF>
+    <KEYKIND>N</KEYKIND>
+   </DD40V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `TYPENAME`: Table type name
+- `ROWTYPE`: Row type (a structure or data element name)
+- `ROWKIND`: Row kind — `S`=Structure/Type, `D`=Data element, `R`=Reference
+- `DATATYPE`: Always `TABLE_T` for table types
+- `ACCESSMODE`: Table kind — `T`=Standard, `S`=Sorted, `H`=Hashed
+- `KEYDEF`: Key definition — `D`=Default (standard key), `K`=User-defined
+- `KEYKIND`: Key uniqueness — `N`=Non-unique, `U`=Unique
+
+**Note**: After the first pull abapGit may expand the XML with `<DD42V>` (component definitions) if key fields are explicitly defined.
+
 ---
 
 ## Important Notes

package/abap/guidelines/object-creation.md

@@ -12,14 +12,23 @@ grand_parent: ABAP Development
 
 **Each ABAP object requires an XML metadata file for abapGit to understand how to handle it.**
 
-| Object Type | ABAP File (if folder=/src/) | XML File | Details |
-|-------------|------------------------------|----------|---------|
-| Class | `src/zcl_*.clas.abap` | `src/zcl_*.clas.xml` | See `guidelines/abapgit.md` |
-| Interface | `src/zif_*.intf.abap` | `src/zif_*.intf.xml` | See `guidelines/abapgit.md` |
-| Program | `src/z*.prog.abap` | `src/z*.prog.xml` | See `guidelines/abapgit.md` |
-| Table | `src/z*.tabl.abap` | `src/z*.tabl.xml` | See `guidelines/abapgit.md` |
-| **CDS View Entity** | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | **Use by default** - See `guidelines/cds.md` |
-| CDS View (legacy) | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | Only if explicitly requested - See `guidelines/cds.md` |
+Replace `<name>` with the actual object name from this project's naming conventions
+(`guidelines/objects.local.md`, or `guidelines/objects.md` as fallback).
+
+| Object Type | ABAP Source File | XML File | Details |
+|-------------|-----------------|----------|---------|
+| Class | `<name>.clas.abap` | `<name>.clas.xml` | See `guidelines/abapgit.md` |
+| Interface | `<name>.intf.abap` | `<name>.intf.xml` | See `guidelines/abapgit.md` |
+| Program | `<name>.prog.abap` | `<name>.prog.xml` | See `guidelines/abapgit.md` |
+| **CDS View Entity** | `<name>.ddls.asddls` | `<name>.ddls.xml` | **Use by default** - See `guidelines/cds.md` |
+| CDS View (legacy) | `<name>.ddls.asddls` | `<name>.ddls.xml` | Only if explicitly requested - See `guidelines/cds.md` |
+| Table (TABL) | *(none — XML-only)* | `<name>.tabl.xml` | See `guidelines/abapgit.md` |
+| Structure (STRU) | *(none — XML-only)* | `<name>.stru.xml` | See `guidelines/abapgit.md` |
+| Data Element (DTEL) | *(none — XML-only)* | `<name>.dtel.xml` | See `guidelines/abapgit.md` |
+| Table Type (TTYP) | *(none — XML-only)* | `<name>.ttyp.xml` | See `guidelines/abapgit.md` |
+
+> **XML-only objects (TABL, STRU, DTEL, TTYP)**: create only the `.xml` file — there is no `.abap` source file.
+> After committing and pushing, pull with: `pull --files <folder>/<name>.tabl.xml --sync-xml`
 
 **IMPORTANT: When user says "create CDS view", create CDS View Entity by default.**
 
@@ -37,14 +46,14 @@ When a class needs local helper classes or test doubles, use separate files:
 
 | File | Purpose |
 |------|---------|
-| `zcl_xxx.clas.locals_def.abap` | Local class definitions |
-| `zcl_xxx.clas.locals_imp.abap` | Local class implementations |
+| `<name>.clas.locals_def.abap` | Local class definitions |
+| `<name>.clas.locals_imp.abap` | Local class implementations |
 
 **XML Configuration**: Add `<CLSCCINCL>X</CLSCCINCL>` to the class XML to include local class definitions:
 
 ```xml
 <VSEOCLASS>
-  <CLSNAME>ZCL_XXX</CLSNAME>
+  <CLSNAME>MY_CLASS_NAME</CLSNAME>
   ...
   <CLSCCINCL>X</CLSCCINCL>
 </VSEOCLASS>

package/abap/guidelines/objects.md

@@ -8,67 +8,78 @@ grand_parent: ABAP Development
 
 # ABAP Object Naming Conventions
 
-> **Project-specific overrides**: Add your naming conventions to `guidelines/objects.local.md`.
-> That file is never overwritten by `abapgit-agent init --update` and is searched by the `ref` command.
+**Searchable keywords**: naming convention, prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS, SAP namespace, customer namespace, PoC, probe
 
-**Searchable keywords**: naming convention, Z prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS
+## SAP Namespace vs Customer Namespace
 
-## TOPICS IN THIS FILE
-1. Naming Conventions
-2. ABAP Object Types
-3. XML Metadata (see guidelines/abapgit.md)
+| | SAP Namespace | Customer Namespace |
+|---|---|---|
+| **Object prefix** | `CL_*`, `IF_*`, `/NAME/CL_*`, `/NAME/IF_*`, etc. | `Z*`, `Y*` |
+| **Package prefix** | SAP-delivered (e.g. `SFIN`, `CA_*`, `/NAME/*`) | `Z*`, `Y*`, `$*` |
+| **Ownership** | Delivered and maintained by SAP | Owned by the customer |
+| **In git repo** | Objects from an SAP-delivered package | Custom development objects |
 
-## Naming Conventions
+> **Rule**: Never add customer-created objects (including PoC/probe classes) into SAP namespace
+> packages. PoC objects always use `Z*`/`Y*` prefix and always go in a `Z*`, `Y*`, or `$*` package
+> — even on a project where production objects use SAP namespace.
 
-Use `Z_` or `Y_` prefix for custom objects:
+## How to Determine This Project's Naming Convention
 
-| Object Type | Prefix | Example |
-|-------------|--------|---------|
-| Class | ZCL_ | ZCL_MY_CLASS |
-| Interface | ZIF_ | ZIF_MY_INTERFACE |
-| Program | Z | ZMY_PROGRAM |
-| Package | $ | $MY_PACKAGE |
-| Table | Z | ZMY_TABLE |
-| CDS View | ZC | ZC_MY_VIEW |
-| CDS Entity | ZE | ZE_MY_ENTITY |
-| Data Element | Z | ZMY_ELEMENT |
-| Structure | Z | ZMY_STRUCTURE |
-| Table Type | Z | ZMY_TABLE_TYPE |
+```
+1. Check guidelines/objects.local.md  ← this project's actual conventions (always check first)
+2. No objects.local.md exists?        ← assume customer namespace project, use Z/Y defaults below
+```
 
-## ABAP Object Types
+`objects.local.md` is never overwritten by `abapgit-agent init --update`. It specifies the
+naming pattern for production objects in this project — which could be customer namespace
+(`ZCL_*`, `YCL_*`) or SAP namespace (`CL_*`, `/NAMESPACE/CL_*`).
 
-Common object types in this project:
+## Default Naming Conventions (Z/Y customer namespace)
 
-| Type | Description | File Suffix |
-|------|-------------|-------------|
-| CLAS | Classes | .clas.abap |
-| PROG | Programs | .prog.abap |
-| FUGR | Function Groups | .fugr.abap |
-| INTF | Interfaces | .intf.abap |
-| TABL | Tables | .tabl.abap |
-| STRU | Structures | .stru.abap |
-| DTEL | Data Elements | .dtel.abap |
-| TTYP | Table Types | .ttyp.abap |
-| DDLS | CDS Views | .ddls.asddls |
-| DDLX | CDS Entities | .ddlx.asddlx |
+Applied when no `objects.local.md` exists:
 
-## XML Metadata
+| Object Type | Default Prefix | Default Example |
+|-------------|---------------|-----------------|
+| Class | `ZCL_` | `ZCL_MY_CLASS` |
+| Interface | `ZIF_` | `ZIF_MY_INTERFACE` |
+| Program | `Z` | `ZMY_PROGRAM` |
+| Package | `$` | `$MY_PACKAGE` |
+| Table | `Z` | `ZMY_TABLE` |
+| CDS View Entity | `ZC_` | `ZC_MY_VIEW` |
+| Data Element | `Z` | `ZMY_ELEMENT` |
+| Structure | `Z` | `ZMY_STRUCTURE` |
+| Table Type | `Z` | `ZMY_TABLE_TYPE` |
 
-**See guidelines/abapgit.md for XML templates.**
+## Project-Specific Conventions (`objects.local.md`)
 
-Each ABAP object requires an XML metadata file for abapGit. Quick reference:
+`objects.local.md` should define both the naming prefix **and the correct package(s)** for
+new objects. When package rules are present, Claude uses them directly without asking. When
+absent, Claude must ask the user which package to use.
+
+Examples of what `objects.local.md` might contain:
 
 ```
-Class:         zcl_*.clas.xml
-Interface:     zif_*.intf.xml
-Table:         z*.tabl.xml
-CDS View:      zc_*.ddls.xml
-```
+# Customer namespace — Y prefix
+Class prefix:     YCL_    e.g. YCL_MY_CLASS
+Interface prefix: YIF_    e.g. YIF_MY_INTERFACE
+Default package:  YMYPROJECT
 
-**Important**: Always push to git BEFORE running pull:
-```bash
-git add .
-git commit -m "Changes"
-git push           # CRITICAL: Push FIRST
-abapgit-agent pull --files abap/zcl_my_class.clas.abap
+# SAP namespace project — single package
+Class prefix:     CL_     e.g. CL_MY_CLASS
+Interface prefix: IF_     e.g. IF_MY_INTERFACE
+Default package:  MY_PACKAGE
+
+# SAP namespace project — multiple packages
+Class prefix:     CL_     e.g. CL_MY_CLASS
+Interface prefix: IF_     e.g. IF_MY_INTERFACE
+Packages:
+  - Feature A objects → MY_PACKAGE_A
+  - Feature B objects → MY_PACKAGE_B
+
+# SAP registered namespace
+Class prefix:     /MYNAMESPACE/CL_
+Default package:  /MYNAMESPACE/MAIN
 ```
+
+→ For file structure (what files to create): `abapgit-agent ref --topic object-creation`
+→ For XML templates: `abapgit-agent ref --topic abapgit`

package/abap/guidelines/probe-poc.md

@@ -0,0 +1,146 @@
+---
+layout: default
+title: Probe and PoC Guide
+nav_order: 19
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# Probe and PoC — Full Decision Flow
+
+**Searchable keywords**: probe, PoC, proof of concept, scratchWorkspace, pocWorkspace,
+disableProbeClasses, SAP namespace, customer namespace, throwaway class
+
+## Probe vs PoC — Key Difference
+
+| | Probe | PoC |
+|---|---|---|
+| Intent | Throwaway — run once to test something | Validate an idea — may persist, needs proper home |
+| Naming | Auto-derived (`ZCL_{USER}_*`) | Developer chooses a meaningful name |
+| Location | `scratchWorkspace` (separate repo) | `pocWorkspace` (separate repo, manually set up) |
+| Config | `scratchWorkspace` in `.abapGitAgent` | `pocWorkspace` in `.abapGitAgent` |
+
+Both always use `Z*`/`Y*` prefix and a customer namespace package (`Z*`, `Y*`, `$*`).
+Never use SAP namespace prefix or SAP-delivered package for probe/PoC objects.
+
+---
+
+## How to Determine the Project Namespace
+
+Before applying the decision flow, determine the project namespace from `objects.local.md`:
+
+```
+objects.local.md shows Z*/Y* prefix  OR  no objects.local.md exists
+  → Customer namespace project
+
+objects.local.md shows CL_*, IF_*, /NAMESPACE/* prefix
+  → SAP namespace project
+```
+
+---
+
+## Full Decision Flow
+
+```
+User asks to create an object
+│
+├── SAP namespace project AND user provides a Z*/Y* name
+│   └── Ask: "Production objects here use CL_* prefix. Did you mean CL_MY_HELPER?
+│           Or is this a PoC/probe object?"
+│       ├── "PoC/probe"   →  continue as PoC or probe flow below
+│       └── "Production"  →  correct the name to match project prefix, then proceed
+│
+├── User confirms PROBE
+│   ├── Customer namespace project
+│   │   ├── disableProbeClasses = false / not set
+│   │   │   └── Create in current project (Z*/Y* prefix, Z*/Y*/$* package)
+│   │   └── disableProbeClasses = true
+│   │       ├── scratchWorkspace configured  →  create there (see workflow below)
+│   │       └── scratchWorkspace NOT configured
+│   │           └── STOP — tell user to configure scratchWorkspace in .abapGitAgent
+│   │
+│   └── SAP namespace project
+│       ├── scratchWorkspace configured  →  create there (see workflow below)
+│       └── scratchWorkspace NOT configured
+│           └── STOP — tell user to configure scratchWorkspace in .abapGitAgent
+│           (disableProbeClasses is irrelevant for SAP namespace projects —
+│            they have no customer namespace packages to host probes)
+│
+└── User confirms POC
+    ├── pocWorkspace.path configured in .abapGitAgent
+    │   └── Read {pocWorkspace.path}/.abapGitAgent → get package property
+    │       Show confirmation:
+    │         "I'll create this PoC object in:
+    │            Repo:    {pocWorkspace.path}
+    │            Package: {package from that repo's .abapGitAgent}
+    │          Is this correct, or do you want a different PoC repo?"
+    │       ├── Confirmed        →  work in that repo using its naming/package rules
+    │       └── Different repo   →  ask user for the path, then confirm again
+    └── pocWorkspace.path NOT configured
+        └── STOP — tell user to set up a PoC repo first (see setup below)
+```
+
+---
+
+## Probe Workflow (scratchWorkspace)
+
+**Naming** — derive from `scratchWorkspace` config in `.abapGitAgent`:
+- `classPrefix` (default: `ZCL_{USER}_`) + `<PURPOSE>`, max 30 chars
+- Example: user=`JOHN`, purpose=`OPEN_TRANSPORTS` → `ZCL_JOHN_OPEN_TRANSPORTS`
+- If name already exists in `{path}/src/`, append `_2`, `_3`, etc.
+
+**Workflow:**
+1. Read `{scratchWorkspace.path}/.abapGitAgent` to confirm `folder` property (e.g. `/src/`)
+2. Write class files in `{path}/src/`
+3. Commit and push from `{path}`:
+   ```bash
+   cd {path} && git add . && git commit -m "probe: <description>" && git push
+   ```
+4. Activate:
+   ```bash
+   cd {path} && abapgit-agent pull --files src/<classname>.clas.abap
+   ```
+5. Tell user (do NOT auto-run):
+   ```
+   Class activated. Run with: abapgit-agent run --class <CLASSNAME>
+   ```
+   Run the command from the original project directory, not `{path}`.
+
+---
+
+## PoC Workflow (pocWorkspace)
+
+Once the user confirms the repo and package:
+
+1. Read `{pocWorkspace.path}/.abapGitAgent` → get `folder` and `package`
+2. Read `{pocWorkspace.path}/guidelines/objects.local.md` if it exists → use its naming rules
+3. Write object files in `{pocWorkspace.path}/{folder}/`
+4. Commit and push from `{pocWorkspace.path}`:
+   ```bash
+   cd {pocWorkspace.path} && git add . && git commit -m "poc: <description>" && git push
+   ```
+5. Activate:
+   ```bash
+   cd {pocWorkspace.path} && abapgit-agent pull --files {folder}/<name>.<ext> --sync-xml
+   ```
+
+---
+
+## PoC Repo Setup (one-time, manual)
+
+When `pocWorkspace.path` is not configured, tell the user to:
+
+```
+1. Create a git repo for the PoC:
+     mkdir my-poc && cd my-poc && git init && git remote add origin <url>
+
+2. Link it to an ABAP package:
+     abapgit-agent init --package <POC_PACKAGE>
+
+3. Add pocWorkspace to .abapGitAgent in the main project:
+     "pocWorkspace": { "path": "/absolute/path/to/my-poc" }
+```
+
+**Switching PoCs**: update `pocWorkspace.path` to point to the new PoC repo.
+Claude always shows the current repo and package before creating anything —
+a stale path is caught before any files are written.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.13.3",
+  "version": "1.13.4",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",
@@ -28,6 +28,7 @@
     "test:cmd:syntax": "node tests/run-all.js --cmd --command=syntax",
     "test:cmd:pull": "node tests/run-all.js --cmd --command=pull",
     "test:sync-xml": "node tests/run-all.js --sync-xml",
+    "test:xml-only": "node tests/run-all.js --xml-only",
     "test:cmd:inspect": "node tests/run-all.js --cmd --command=inspect",
     "test:cmd:unit": "node tests/run-all.js --cmd --command=unit",
     "test:cmd:view": "node tests/run-all.js --cmd --command=view",

package/src/commands/pull.js

@@ -98,21 +98,31 @@ module.exports = {
     if (filesArgIndex !== -1 && filesArgIndex + 1 < args.length) {
       files = args[filesArgIndex + 1].split(',').map(f => f.trim());
 
-      // Validate that every file has a recognised ABAP source extension
-      // (.abap or .asddls) — XML metadata files must NOT be passed here
+      // Validate that every file has a recognised extension:
+      // - .abap / .asddls  — ABAP source files
+      // - name.type.xml    — XML-only objects (TABL, STRU, DTEL, TTYP, ...)
+      //   Must have exactly 3 dot-separated parts with a non-empty name part
+      //   to exclude .abapgit.xml, package.devc.xml, plain .xml, etc.
       const ABAP_SOURCE_EXTS = new Set(['abap', 'asddls']);
+      const isXmlOnlyObject = (f) => {
+        const base = f.split('/').pop();
+        const parts = base.split('.');
+        return parts.length === 3 && parts[0].length > 0 && parts[2].toLowerCase() === 'xml';
+      };
       const nonSourceFiles = files.filter(f => {
         const base = f.split('/').pop(); // strip directory
         const parts = base.split('.');
         const ext = parts[parts.length - 1].toLowerCase();
-        return parts.length < 3 || !ABAP_SOURCE_EXTS.has(ext);
+        if (ABAP_SOURCE_EXTS.has(ext)) return false;  // .abap / .asddls — valid
+        if (isXmlOnlyObject(f)) return false;          // name.type.xml — valid
+        return true;                                   // everything else — invalid
       });
       if (nonSourceFiles.length > 0) {
-        console.error('❌ Error: --files only accepts ABAP source files (.abap, .asddls).');
-        console.error('   The following file(s) are not ABAP source files:');
+        console.error('❌ Error: --files only accepts ABAP source files (.abap, .asddls) or XML-only object files (name.type.xml).');
+        console.error('   The following file(s) are not recognised:');
         nonSourceFiles.forEach(f => console.error(`     ${f}`));
-        console.error('   Tip: pass the source file, not the XML metadata file.');
-        console.error('   Example: --files src/zcl_my_class.clas.abap');
+        console.error('   Tip: for source objects pass the .abap file; for XML-only objects (TABL, STRU, DTEL, TTYP)');
+        console.error('   pass the .xml file, e.g. --files abap/ztable.tabl.xml');
         process.exit(1);
       }