Spexso

Appearance

Quickstart: CAP + UI5 on BTP ​

From npm install to your first merged MR. Five minutes to read, one small feature to try it on.

Before you start

  • Claude Code installed
  • A GitLab project cloned locally (spexso needs a git repo) with glab auth login done
  • Node.js ≥ 18 and git on your PATH

1. Install ​

@flexso/spexso lives in Flexso's private GitLab npm registry, not on npmjs.com — so point the @flexso scope at GitLab first. Once per machine (or per project):

  1. Create a GitLab Personal Access Token with the read_api scope (Flexso GitLab → User settings → Access tokens) and copy the value.
  2. Put it in an environment variable, so it never lands in git:
    powershell
    $env:NPM_REGISTRY_READ_TOKEN = "<your-token>"      # Windows PowerShell
    bash
    export NPM_REGISTRY_READ_TOKEN=<your-token>        # macOS/Linux
    Set it permanently in your shell profile ($PROFILE, ~/.zshrc) — a token that only lives in one terminal window means npm install fails in the next one.
  3. Create an .npmrc — ~/.npmrc for all your projects, or one in the project root:
    ini
    @flexso:registry=https://flexso.gitlab.host/api/v4/packages/npm/
//flexso.gitlab.host/api/v4/packages/npm/:_authToken="${NPM_REGISTRY_READ_TOKEN}"
    That's GitLab's instance-level endpoint: it resolves any @flexso package, no group or project ID needed. Reference ${NPM_REGISTRY_READ_TOKEN} — never a literal token — in a committed .npmrc.

Then install:

bash
npm install -D @flexso/spexso
npx @flexso/spexso init
npm ERR! 404 @flexso/spexso or E401

404 → the .npmrc scope line isn't being picked up (npm config get @flexso:registry should print the GitLab URL). E401 → the token is missing, expired, or lacks read_api. Full walkthrough: Team onboarding.

init scaffolds everything: the 18 slash commands and 6 subagents into .claude/, spec templates and tuneable rulebooks (CAP, UI5, UX, TypeScript, testing, and the cross-cutting doctrine) into .spexso/, GitLab labels and boards, and the Claude Code hooks that work invisibly from then on — every session is logged for the latency report, and the engineering doctrine is injected into every agent automatically.

2. Configure once ​

Open Claude Code in the project and run:

/spexso-setup

Setup writes your project instructions (AGENTS.md), detects your test framework and stores the right test commands in .spexso/config.json, recommends the SAP MCP plugins (CDS, UI5, Fiori docs), and triages any existing GitLab issues into the spexso lifecycle labels.

3. Spec a small feature ​

/spexso-brainstorm Add a "duplicate order" action to the orders list

A short interview turns your idea into a written spec on a GitLab issue — acceptance criteria included — and sizes it (size::xs … size::xl). The size label matters: it dials which model implements each task later (small task → fast model, big task → strong model).

4. Build it ​

/spexso-start 42        # lock the issue, create an isolated worktree, pick "pilot" mode
/spexso-plan            # planner decomposes the spec into tasks — approve the plan
/spexso-build            # per task: failing test first (RED), then minimum code (GREEN)

Pilot mode gives you two checkpoints (plan approval, first task result) and runs the rest autonomously. Two safety rails are enforced in code, not prose: after 3 failed attempts on a task the build stops and asks you, and a task that exceeds its time budget (budgets.perTaskMinutes, default 30) stops instead of silently grinding for an hour.

5. Review and ship ​

/spexso-review          # calibrated findings; CRITICAL/HIGH auto-fixed, the rest commented
/spexso-finish          # full test gate → push → MR → auto-merge → cleanup

The reviewer checks your diff against the spec and the project rulebooks (including Fiori floorplan compliance for UI5 work). Finish refreshes the committed debt ledger (.spexso/debt.md), opens and merges the MR, posts a manual-test checklist on the issue, archives the spec, and writes a learning card to docs/learning/ — a short Socratic recap that helps you truly own the change.

Felt slow? Measure it ​

bash
npx spexso observe report

Every session is logged automatically. The report shows where the time went — wall clock, subagent hops, test runs — before anyone reads a transcript.

Where to go next ​