Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (91 loc) · 7.21 KB

AGENTS.md

File metadata and controls

109 lines (91 loc) · 7.21 KB
Raw

Agent guide

Operating brief for AI coding agents (Claude Code, Codex, Cursor) working in this repo. It points into the canonical docs rather than restating them — follow the links for detail.

What this is

provision-sitecore-ai-component provisions a SitecoreAI component from one reviewed manifest. The manifest — drafted from a BA functional spec in Confluence — drives both sides of setup from a single source of truth: the CMS items via the Authoring GraphQL API (templates, fields, rendering + datasource bindings, insert options, placeholder settings) and a TSX handoff scaffold (Component.tsx + Component.types.ts) for the front-end pipeline. Because one manifest creates both, the front-end boundary contract mirrors the CMS by construction. See README.md for the full picture; the CLI runtime is dependency-free CommonJS.

Layout

  • src/ — the dependency-free CLI runtime (.cjs): cli, validate-manifest, build-plan, executor, emit-tsx, type-map, util.
  • skills/provision-sitecore-ai-component/ — the agent skill (SKILL.md) and its references/ docs; skills/_meta/ holds vendored authoring templates (do not edit here).
  • test/ — node:test suites plus golden fixtures under test/fixtures/ (byte-compared plans + TSX). Regenerate goldens with the tool, never by hand.
  • wiki/ — the committed context wiki (history, decisions, wiring). Start at wiki/INDEX.md; the write-side protocol is wiki/MECHANICS.md.
  • scripts/ — repo automation (graph/, wiki/, hooks/, release/); no user-facing runtime.

Run it

pnpm 10.33.0 via Corepack, Node ≥ 24.14.0 (corepack enable && pnpm install).

  • pnpm test — full suite (goldens, executor units, skills-lint, wiki conformance, graph freshness).
  • pnpm commit — Conventional Commits via @verndale/ai-commit (husky-enforced).
  • pnpm graph:build / pnpm graph:view — rebuild the knowledge graph (+ the generated wiki/connections* pages) / serve the viewer at localhost:4173.
  • bash setup.sh [claude] [codex] [cursor] [--uninstall] — symlink the skill into your tool's user skills dir, register the PreToolUse guard for Claude Code/Codex, and offer the one-time credential bootstrap (~/.config/provision-sitecore-ai-component/.env).

Context wiki navigation

Never bulk-load wiki/ or open scripts/graph/data/graph.json as reading context.

  • For a direct history or rationale question, start at wiki/INDEX.md and open only the page it routes to.
  • For a cross-page question, silently run node scripts/wiki/navigate.cjs --intent <intent> --query "<term>": use why for rationale, wiring for dependency or ownership, and impact for change reach.
  • For known endpoints, use --from <node-id> --to <node-id>. Read only the returned itinerary; its per-page and total byte counts are the reading budget.
  • If navigation is ambiguous, choose only from the returned candidates or ask one focused question. If it has no match, use targeted rg <term> wiki, then git log or gh; never guess a route.
  • Wiki history explains decisions. Source and tests remain authoritative for current runtime behavior.

The CLI needs no install: node src/cli.cjs <plan|check|push> <manifest.json> — plan (offline; writes <slug>.plan.json + the TSX pair), check (read-only preflight), push (mutating, add-only, gated).

Config, manifest, auth

  • Config resolves first-hit-wins: --config <path> → ./provision.config.json → ./build.config.json (pipeline repos; requires stackAdapter: "sitecore-ai") → none, in which case every path comes from manifest.sitecorePaths.
  • Manifest is the single reviewed contract for one component. Normative schema + semantics: manifest-contract.md; the Sitecore-type → TS → renderer table is type-mapping.md.
  • Auth (only check/push): OAuth2 client-credentials for a SitecoreAI automation client, via SITECORE_AUTHORING_* env vars in a gitignored .env (see .env.example). Missing required vars fail before any network call. Contract: authoring-api.md.

Hard boundaries

  • Add-only reconcile — the tool creates and updates only; it never deletes, renames, or retypes CMS items/fields, and never removes entries from list fields (__Masters, Allowed Controls, validation bars). Conflicts and extra fields are reported as manual follow-ups, never "fixed." (authoring-api.md, SKILL.md)
  • Push gate — never run push without the in-session step-6 gate approval; check is the only online mode allowed before it. push mutates a shared CMS environment. (SKILL.md)
  • Secrets never echoed — never print SITECORE_AUTHORING_* values into chat, logs, or files.
  • Don't invent spec values — Source strings, datasource locations, and field types the spec doesn't state are review questions, written verbatim once answered — never guessed.
  • Version control (deliver-and-handoff) — leave an uncommitted working tree plus a suggested Conventional Commits message; the repo owner performs commit/push/merge/tag and releases (semantic-release on main; wiki-sync lands via PR, never a direct push).
  • Don't hand-edit generated or vendored files — wiki/connections* (regenerated by pnpm graph:build), skills/_meta/* + references/retry-contract.md (vendored from ai-orchestration; re-sync from source, don't edit here), and generated <slug>.plan.json plan artifacts (fix the manifest and re-run node src/cli.cjs plan).
  • Mechanically enforced on supported paths — trusted Claude Code/Codex hook definitions run scripts/hooks/pretooluse-guard.cjs before supported shell/edit calls (git mutations, secret reads, and protected-file edits deny). Codex skips definitions until their current hash is reviewed through /hooks and denies push without --yes; Claude Code can prompt. Husky refuses agent-shell commits, and the CLI independently refuses non-interactive push without --yes. Hooks are defense-in-depth, not a complete security boundary. Policy changes go through scripts/hooks/guard-core.cjs + test/hooks.test.cjs together. Cursor relies on this prose alone.

Where to look next