Spec Templates

Full Spec (M / L / XL)

.spexso/templates/spec-full.md:

## Summary
{What are we building and why? One paragraph.}

## User Stories
- As a {role}, I want {action} so that {benefit}

## Acceptance Criteria (EARS)
- AC-1: {one of the five EARS patterns: The system shall… / When…, / While…, / Where…, / If…, then…}
- AC-2: …

## Data Model
{CDS entities, fields, types, associations}

## API Contract
{Endpoints, methods, request/response shapes}

## Integration Points
- System: {SAP SF / S4 / Sales Cloud}
- Auth: {XSUAA / Destination / API key}
- Direction: {inbound / outbound}

## UI/UX requirements
{Floorplan per app: Fiori Elements or freestyle}

| Screen / section | User goal | Data shape | Control or building block (§5b) | Header key figures |
|---|---|---|---|---|
| {Assessment history} | {see how my level evolved} | {chronological events} | {Timeline, newest first} | {current level as rating} |

{Key fields, actions, navigation}

## Edge Cases
{What happens when X fails / is missing / is unexpected?}

## Out of Scope
{What this does NOT cover}

## Dependencies & Size
Size: {M/L/XL} | Blocked by: {#id} | Blocks: {#id}

Lite Spec (XS / S)

.spexso/templates/spec-lite.md:

## What
{One sentence: what to do}

## Why
{One sentence: why it matters}

## Acceptance criteria (EARS)
- AC-1: {EARS clause — max 3 on a lite spec}
- AC-2: {EARS clause}

## UI
{Optional: per screen the data shape → control (ux.md §5b)}

## Files likely affected
{List of files to change}

EARS acceptance criteria

Both spec templates number their acceptance criteria (AC-1…) and write each in one of the five EARS patterns — ubiquitous ("The system shall…"), event-driven ("When…"), state-driven ("While…"), optional ("Where…"), unwanted behavior ("If…, then…"). The point is mechanical testability and traceability, not ceremony:

• the planner lists per task which clauses it covers (Covers: AC-1, AC-3) — every clause maps to exactly one task;
• the UI table (spec-full) or ## UI line (spec-lite) names per screen the data shape and the control for it, picked by ux.md §5b ("a table is not the default for everything"). It is a contract: the planner carries it into each UI task's UI: line, the builder builds it, and the reviewer flags a missing or replaced control as HIGH "UI contract drift";
• the tester derives exactly one test per clause with the id in the test name (it('AC-1: …')); a clause whose faithful test already passes routes through the already-implemented terminal state;
• the reviewer walks the clauses as a drift check — unimplemented/deviating clauses are HIGH "spec drift" findings, uncalled-for behavior is a LOW "over-build" finding, and the report carries a per-clause traceability line.

Lite specs are capped at 3 clauses — needing more means the issue is not XS/S. Hard length budgets apply: lite ≤ ~1 page, full ≤ ~3 pages; the reviewer rejects over-length specs (comment-only HIGH).

Bugfix track

bug-report.md is structured as Current / Expected / Unchanged behavior. "Unchanged" is the tester's regression scope: one regression test per line (green before the fix), while the Expected-behavior test is the RED one.

Constitution

npx spexso constitution seeds .spexso/constitution.md — a one-page, code-enforced (≤40 content lines / ≤3500 chars) list of project principles. The planner cites the articles a plan relies on; the reviewer flags violations with the article number. Principles that stop earning their place get deleted, not appended to.

Project registries (BTP services / tenant requirements)

Two optional living registries — not spec templates, but planner-consulted project documents seeded from the same src/templates/ layer:

• btp-services.md — seeded to docs/architecture/btp-services.md. Tracks every BTP service instance and binding the project uses (service, plan, instance name, what it's bound to, bindings used vs. limit), a "Known critical limits" table (e.g. Object Store s3-standard caps at 5 bindings), and a change log. The planner reads it before any task that adds a service or binding and runs a Binding Impact Assessment — within 1 of a plan's binding limit, it flags the plan as an infrastructure blocker before task breakdown proceeds.
• tenant-requirements.md — seeded to docs/architecture/tenant-requirements.md. For multi-tenant projects: four scope classes (Platform Core / Platform Configurable / Tenant Optional / Tenant Custom), seven red flags that force a clarifying question before planning (customer named by name, a changed default, an added toggle, workflow-specific behavior, unconfigurable domain-specific behavior, a changed entity/API contract tenant integrations may depend on, or "for now"/"temporarily" wording — temporary scope tends to calcify), and a guiding question ("is this needed because a specific customer asked for it, or because it makes the platform better for everyone?"). The planner classifies every new feature's scope and records the verdict in the plan.

One code template ships alongside them:

• wizard-lib.mjs — the helper library behind /spexso-wizard. The skill copies it to scripts/wizards/_lib.mjs in the product repo; every wizard imports it. Node stdlib only, so a wizard runs with nothing but Node and the repo (no spexso, no npm install). It provides staged prompts (secret input hidden and redacted), btp/cf/glab execution with confirmation and a cockpit click-path fallback, .env / default-env.json writes, and glab variable set for CI/CD variables. Never edit the copy — the skill refreshes it from the template.

Both are conditional — the planner checks for their existence with a cheap file lookup and skips silently when absent; seed either one from .spexso/templates/ only on projects that actually run multiple BTP service bindings or serve multiple tenants.

Learning Card

.spexso/templates/learning-card.md seeds the Socratic template /spexso-finish fills in and writes to docs/learning/{YYYY-MM-DD}-issue-{id}.md for every completed issue — see Finish Flow for the write step.

CLAUDE.md Spexso Section

When npx spexso init runs, it appends a Spexso section to the project's AGENTS.md (CLAUDE.md is a thin @AGENTS.md import shim). This gives Claude Code awareness of the framework without bloating context. Below is an abbreviated illustration of the shape — the full shipped section (language policy, SAP grounding rules, domain rulebooks, configuration, releasing) lives verbatim in src/snippets/AGENTS-snippet.md.

## Spexso Framework

This project uses Spexso — spec-driven development for Flexso teams.

### Active work
See .spexso/index.json for all active issues, their stages, and assigned worktrees.
Do NOT read full specs unless you are actively working on that issue.

### Commands available
/spexso-setup, /spexso-kickstart, /spexso-report, /spexso-brainstorm, /spexso-tinder, /spexso-start,
/spexso-plan, /spexso-build, /spexso-review, /spexso-finish, /spexso-stop,
/spexso-sync, /spexso-docs, /spexso-demo, /spexso-wizard, /spexso-architecture

### Modes
yolo (autonomous) | pilot (guided) | copilot (pair programming)

### Rules
- Strict TDD: tests BEFORE implementation, always
- One worktree per issue, enforced
- Code review: critical+high auto-rewrite, low comment only
- All stage transitions synced to the tracker via the spexso CLI (`npx spexso stage` / `npx spexso issue …`)
- Commit format: feat|fix|refactor(spexso): description