AGENTS.md

Guidance for coding agents working on AB Framework, a reusable starter kit that generates multi-repository application suites.

Project Overview

The framework distills a server, mobile app, public web app, admin app, shared contracts, and deploy scaffolding into a generator. Generated suites keep repo boundaries separate:

• *-server: Node ESM API server with domain modules, routes, HTTP helpers, PostgreSQL migrations, and focused tests.
• *-mobile: Expo React Native app with feature modules, reusable components, typed API core, and i18n copy.
• *-web: public Next.js web app with thin routes and a centralized API client.
• *-admin: Next.js App Router operator console with custom network-gated server, BFF routes, and upstream API client.
• *-contracts: shared HTTP contract files.
• *-deploy: Docker Compose and deploy environment scaffolding.

Setup Commands

bashnode .claude/scripts/create-suite.mjs --name acme --out <output-dir>/acme
node .claude/scripts/create-suite.mjs --topic "secure analytics dashboard"
node .claude/scripts/lint-claude-harness.mjs
node .claude/scripts/lint-harness-md.mjs
node .claude/scripts/verify-framework.mjs
node .claude/scripts/lint-manifest.mjs <generated-suite-dir>
node .claude/scripts/plan-write-sets.mjs <generated-suite-dir>

Use placeholders such as <output-dir> and <generated-suite-dir> in docs; do not publish machine-specific absolute paths.

Generator Rules

• Preserve generated repo separation. Repos should not import shared runtime code from each other outside the generated contract boundary.
• Generated dev and production environments run through Docker images.
• Generated server runtimes use PostgreSQL through Docker Compose.
• Generated host ports should remain unique and above the reserved low-number range.
• --force is only for scratch destinations that can be overwritten.
• --git initializes generated repos separately; do not assume a single monorepo output.

Claude Code Harness

The harness lives under .claude:

• .claude/CLAUDE.md
• .claude/settings.json
• .claude/agents/*
• .claude/commands/*
• .claude/skills/ab-framework-orchestrator/SKILL.md
• .claude/policies/*.yaml
• .claude/scripts/*

Read the relevant harness agent, command, skill, and policy before changing generation behavior.

Code Style

• Keep template output boring and predictable.
• Prefer verifier checks over comments that merely describe intended output.
• Avoid adding a generator option unless it changes generated files in a testable way.
• Keep suite-manifest output current when generated structure changes.

Testing

Use:

bashnode .claude/scripts/lint-claude-harness.mjs
node .claude/scripts/lint-harness-md.mjs
node .claude/scripts/verify-framework.mjs

For generator changes, inspect the temporary suite or a generated scratch suite and verify required files, Dockerfile/Compose wiring, package manifests, PostgreSQL policy, security headers, rate limiting, source modularity, and placeholder cleanup.

Security And Privacy

• Do not publish local absolute paths or generated private env values.
• Generated admin auth, network gating, and httpOnly session behavior should stay explicit.
• Generated deployment scaffolding should make secrets placeholders, not sample real values.

Commit And PR Rules

• State which generated repos are affected.
• Include verifier output or the exact verifier failure.
• If write-set planning changes, include an example of the new ownership slices.