sapcc-skill: Instructions file for Codex

AGENTS.md

This file helps AI agents (Claude, Copilot, Cursor, Codex, Pi, Gemini…) understand this codebase quickly and work on it effectively. Following the agents.md standard.

---

Project Overview

sapcc-skill is an Agent Skills-compatible skill that lets any AI agent interact with a SAP Commerce Cloud (Hybris / CCv2) instance using natural language, across two complementary surfaces:

1. HAC (Hybris Administration Console) — application data & business logic. The agent translates intent into either:

   • a FlexibleSearch query (SQL-like, read-only, fast)
   • a Groovy script (business logic, service calls, writes, ImpEx, cronjobs)

   …executed via sapcc-hac-client (handles HAC authentication: CSRF token, JSESSIONID, ROUTE cookie).

2. Cloud Portal API — CCv2 DevOps/platform operations (environments, builds, deployments, backups, scaling, endpoints, certificates, scheduled activities, service properties, user roles), executed via sapcc-portal-cli (handles OAuth2 client_credentials auth).

The skill is designed to keep growing with additional SAP CC capabilities over time (monitoring, etc.).

---

Repository Structure

sapcc-skill/
├── SKILL.md                          # Agent Skills manifest — name, description, metadata
├── package.json                      # npm package (name: sapcc-skill, v2.1.0)
├── .env.example                      # Credentials template (HAC_* and PORTAL_*)
├── .gitignore                        # Excludes .env, node_modules, *.stamp
│
├── scripts/
│   ├── execute.js                    # ★ HAC ENTRY POINT — Groovy / FlexSearch CLI runner
│   ├── portal.js                     # ★ CLOUD PORTAL ENTRY POINT — builds/deployments/envs/... CLI runner
│   └── setup.js                      # Setup health checker (deps + .env validation, both HAC & Portal)
│
├── references/                       # Agent-readable reference docs (loaded on demand)
│   ├── decision-guide.md             # FlexSearch vs Groovy decision matrix
│   ├── flexsearch-guide.md           # FlexibleSearch syntax, types, 30+ example queries
│   ├── groovy-patterns.md            # Groovy patterns, Spring bean names, service examples
│   ├── sap-cc-types.md               # SAP CC type reference (Product, Order, User…)
│   └── portal-guide.md               # Cloud Portal command reference & DevOps workflows
│
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
│
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE                           # MIT
├── README.md                         # English documentation
└── README_AR.md                      # Arabic documentation