Empire Teas CRM — Team Guide
One-page reference for how this project’s team operates.
For the framework workflow itself (phases, gates, session management, compounding engineering, troubleshooting), see
.forge/forge-harness-framework.md— the full framework reference synced into this repo. This document is the project-specific layer on top of that.
The Team
Delivery team confirmed 2026-08-18; Nanndish Satgunarajah joined on 2026-09-29.
| Role | Person | GitHub | Machine |
|---|---|---|---|
| Lead · full-stack developer | Tharinda Rajapaksha | tharinda-altrium |
macOS |
| Full-stack developer | Dinil Gamage | dinil-gamage |
Windows |
| Full-stack developer | Biseni Perera | biseni-droid |
Windows |
| Full-stack developer | Nanndish Satgunarajah | nanndish-altrium |
Windows |
The test records run on these machines, not in CI. The browser gate runs on the lead’s Mac every night, and on a developer’s machine when they run it (.claude/CLAUDE.md § Common Commands). So a test can fail on one operating system and pass on the other.
- A flaky failure is filed once for each operating system (
.claude/rules/tracker.md § Bug Tracking), and a fix is checked on the kind of machine where it failed. - The browser gate and the test records refuse to start while other work keeps the CPU more than 0.65 busy, and they name the busiest processes. Stop another session’s gate, build or containers and run again. Or pass
--ignore-loadto run anyway; Claude passes it only when you say so (.claude/rules/git-conventions.md § Pull Requests).
All four carry the full role — development, QA, and harness/Forge work, across the app repos. The lead is Empire Teas’ single point of contact. There is no backend/frontend ownership split: everyone works every repo, and waves are sliced vertically (see the Gate-3 standing instruction in CLAUDE.md).
Extended contacts
Not part of the core delivery crew, but named people around the project — contributors, contacts, and Altrium leadership/escalation (this table is the home for their roles — reference them by name only elsewhere):
| Role | Person | Org |
|---|---|---|
| DevOps engineer — AWS environments, Terraform, the Entra login certificate (weekly-update recipient) | Shyamin Ayesh | Altrium |
DevOps engineer — works with Shyamin Ayesh on the AWS estate; changes the Terraform in forge-et-iaac (GitHub senuthmi07) |
Senuthmi Thimansa | Altrium |
| Delivery lead / director (weekly-update recipient) | Rukshan Salgado | Altrium |
| Principal software architect (built the capture-app POC; weekly-update recipient) | Thilina Abeyrathna | Altrium |
| Senior software architect; oversees the DevOps team (weekly-update recipient) | Malinda Wellalage | Altrium |
| CEO — former software architect, strongly technical (top escalation) | Yohan Liyanage | Altrium |
| Head of Information Technology (weekly-update recipient; the client’s IT contact for Microsoft 365 and DNS; holds Empire’s AWS account) | Kavindu Anthony | Empire Teas |
| Director – Operations (weekly-update recipient) | Sajeev De Silva | Empire Teas |
| Head of Sales (weekly-update recipient) | Praveen Madugalle | Empire Teas |
Director – Marketing (saham@empire.lk; not a weekly-update recipient) |
Sahampathy Dissanayake | Empire Teas |
Managing Director / CEO (lushantha@empire.lk; not a weekly-update recipient; heads Empire Teas (Pvt) Ltd, Empire Brands (Pvt) Ltd and Empire Kenya (Pvt) Ltd) |
Lushantha De Silva | Empire Teas |
Executive – International Business (brands@empire.lk; not a weekly-update recipient) |
Malindi Hidellaarachchi | Empire Teas |
| Business Development Manager (email not known; not a weekly-update recipient) | Thilanga Dilsan Weerasooriya | Empire Teas |
Senior Brand Manager – International Business (parththipan@empire.lk; not a weekly-update recipient) |
Kumarasamy Parththipan | Empire Teas |
Review Pairings
- Specs and plans: the author runs
/forge-spec-reviewor/forge-plan-reviewand may approve their own; no teammate’s approval is needed to continue (.claude/CLAUDE.md § Review Ownership). For foundational work (auth, data model, extension points), asking the lead or a teammate to look is encouraged; verify/e2e work items rotate across the team like any other work - Security-sensitive (auth, data handling, external APIs, file upload, AI boundary): security review mandatory —
/forge-review-prstep 6a runs it on every such app-repo PR (.claude/CLAUDE.md § Quality Gates) - Every PR: review is requested from the other three team members automatically (
git-conventions.md § Pull Requests). No approval is needed to merge intomainfor now: the author can merge once CI is green. Asking a teammate to look first is still good practice.
Working in Parallel — Four Developers
Recorded 2026-09-29, when the team grew to four.
Nobody has a fixed lane. Each of the four developers takes the next feature from tracker.yaml whose blocked_by items are all done, or an open bug. Claim it before any work starts, with /et-claim <ticket> (several at once: /et-claim BUG-153 BUG-154 F1-e):
- It checks that nobody owns the ticket, has an open PR for it, or has pushed a branch named after it.
- It sets the ticket’s
owner(and a bug’sstatus: in-progress, or a feature’sstarted) onmain, through a small harness PR. - You merge that PR (
.claude/commands/et-claim.md).
/forge-deliver runs the same check at its start. A ticket you stop working on is released with /et-claim --release <ticket>. Nanndish works the same way as the other three.
To keep two people off the same code at the same time, prefer the next feature on a dependency chain you are already on — it builds on code you just wrote. The chains, as the tracker’s blocked_by draws them on 2026-10-26 (the Access and Prices chains are done):
| Chain | Phase 1 features, in dependency order |
|---|---|
| Accounts | F3-a (the other Accounts features are done) |
| Leads and AI | F11-g (F11-c, which it waits on, is done) |
| Import | F4-b → F32-c (the bulk hand-out of imported records) |
| F20-i, F20-l → F20-f → F20-j, F20-k | |
| Cloud (the critical path) | F38-a → F38-b → F38-d, then F38-e, F38-f, F38-g → F38-h, alongside the Terraform Shyamin Ayesh and Senuthmi Thimansa write |
The cloud chain still comes first: dev deploys every merge and the first upload on dev succeeded on 2026-10-26, but the mailbox is not yet proved on dev (.forge/active-context.md). The blocked_by fields are the source of truth; this table only groups them.
The capture app (F36-a to F36-d) moved from Phase 2 to Phase 1 on 2026-11-11 (PRD Rev 91), in its own chain: F36-a → F36-b → F36-c, and F36-a → F36-d; F36-b and F36-c also wait on F43. Specs and plans may be written ahead of the features they describe. Moving a Phase 2 feature to dev while its phase is locked needs the lead’s agreement (.claude/rules/tracker.md § Delivery Phase Rules).
Phase 1 work comes before any Phase 2 feature. Time left in Phase 1 goes first to:
- the remaining Phase 1 features;
- bug fixes and UI fixes;
- the issues and improvements Empire Teas raise when the Phase 1 work is shown to them, and those raised by Altrium stakeholders;
- thorough regression testing;
- the Phase 1 release work and the cloud work.
A Phase 2 feature is taken into Phase 1’s duration only when all of that is done (lead’s instruction, 2026-10-12; R-ARCH-001 in tracker.yaml).
Where parallel work has collided before, and the rule for each:
-
Flyway version numbers. A plan names the migration version it expects and re-checks it against
mainat dispatch, and again before its PR opens, because another branch may have taken it in between. -
tracker.yaml. Each person edits only the rows of the features they own, through.claude/lib/tracker-write.sh; a conflict is resolved by hand (.claude/rules/tracker.md). -
The shared lists — the permission catalog (FS-6 Appendix A), the audit event codes (
forge-et-be/docs/audit/README.md) and the frontend’s navigation and route registration: add entries and never reorder existing ones, so that two branches’ additions merge cleanly. -
A merged tree that neither branch tested. Two branches can merge cleanly and still break each other’s tests. A PR is not refreshed from
mainbefore it merges; the nightly full run onmainor the next PR’s own tests catch the break, and it is fixed before new work starts (git-conventions.md § Branching). -
The nightly full run. Every night at 02:00 Sri Lanka time, the lead’s Mac runs every suite of the three app repos on
main(.claude/lib/nightly/run-nightly.py; design:.forge/design/harness/test-run-cost.mdN-3):- a secret scan (gitleaks) and a dependency scan (Trivy) of every repo;
- the backend build;
- each frontend’s static checks and build;
- both Vitest suites, and both browser gates in the full profile.
It is the only run of every test, and of the browser suites, for
main. A PR’s record runs only the tests its change needs. A PR intomainruns no full browser gate, only the browser tests a frontend change selects (PRD Rev 81, Rev 93).A red suite opens a
nightly-redissue assigned to all four of us. Whoever picks it up re-runs only the failing tests (never the whole suite) to sort the failure, fixes it before new work starts, and files aBUG-NNNfor a defect (.forge/guides/test-runs-explained.md § The nightly full run).The run needs the lead’s Mac on, plugged in and open overnight. A closed lid or a flat battery puts it to sleep (2026-10-31 to 2026-11-03). A missed or interrupted night is run again by hand the next morning (
run-nightly.py --now,git-conventions.md § Pull Requests). Each session start lists an opennightly-redissue. The night’s figures are a comment on the harness issue labellednightly-log.
Where to Find Things
| What | Where |
|---|---|
| Project constitution | .claude/CLAUDE.md |
| Workspace rules | .claude/rules/ |
| Forge slash commands | .claude/commands/ |
| Project PRD | .forge/project-prd.md |
| System architecture | .forge/design/architecture.md |
| Discovery artifacts | .forge/discovery/ |
| Feature specs | .forge/specs/ |
| Implementation plans | .forge/plans/ |
| Project tracker | .forge/tracker.yaml |
| Quality checklist | .forge/checklists/quality-checklist.md |
| Data model, ER diagrams, API contracts | forge-et-be/docs/ (first artifact: the SP-ARCH-003 pricing data model) |
| Style spec, design tokens, component patterns | .forge/design/ui/design-system.md (harness) — condensed into forge-et-fe at Foundation slice 3 |
| Capture-app prototype + its docs | ../forge-et-pwa-poc/ — read-only reference; port into forge-et-pwa, never write to it |
Repos on This Project
Six repos, and every team member clones all six as siblings under one plain parent
directory (plus the ephemeral worktrees/). Cross-repo tooling — the worktree commands,
/forge-deliver, the capture stream reading the POC — resolves paths relative to this
layout, so the layout itself is the convention:
et/ # plain directory — NOT a git repo
├── forge-et-harness/ # this repo
├── forge-et-be/ # backend — Java 21 + Spring Boot 4.2.x + PostgreSQL (Gradle, Groovy DSL — team convention)
├── forge-et-fe/ # frontend — TypeScript + React SPA on Vite (pnpm)
├── forge-et-pwa/ # trade-show capture PWA (pnpm) — own repo + own hosting/URL; delivered in Phase 1
├── forge-et-pwa-poc/ # capture-app POC — READ-ONLY reference (see below)
├── forge-et-iaac/ # DevOps — all Terraform and infrastructure code (AD #23); worked in by Shyamin Ayesh and Senuthmi Thimansa
└── worktrees/ # ephemeral task isolation
forge-et-iaac is the DevOps repository (added 2026-09-29): all Terraform and other
infrastructure code for the AWS estate lives there, not in forge-et-be (AD #23). Shyamin Ayesh
builds the environments in it, and Senuthmi Thimansa, who works with him, also changes it (her
first PRs there opened on 2026-10-02); the delivery team reads it for the F38 cloud work, and
Tharinda, Dinil and Nanndish also have write access (Biseni does not yet). Its trunk is dev: a developer’s change is a PR to dev (the DevOps team, Shyamin and Senuthmi, may push to it directly),
with review requested from the other people who have write access (Shyamin, Senuthmi, Tharinda,
Dinil) — .claude/rules/forge-et-iaac.md. Which of the other delivery-repo
conventions it takes on (CODEOWNERS, branch protection, a PR template) is still open.
forge-et-pwa-poc is read-only. It holds the capture stream’s starting point, and it is
much further along than a prototype — its own docs/plans/README.md records most of
its epics Done (verified). What’s in it:
apps/web— the PWA frontend (React + Vite + Tailwind). API-integrated, not hardcoded; the oldsrc/data/leads.jsmock is gone. This is the portable half.apps/api— a working Python/FastAPI backend (Supabase Postgres + pgmq queue, SES mail, Supabase auth, in-process worker), deployed to Fly.io. This does not port: its ADRs 3/4/5/8/9 all yield to AD #19–#23. Treat it as a proven reference for the enrichment pipeline, the API contract and the prompt design — not as reusable code.docs/— the POC’s own docs set (concept/spec, backend technical scope, feature breakdown, 15 epic plans, 11 ADRs) anddesign/— the clickable pitch prototypes.
Read it and port what’s needed into forge-et-pwa; never commit, push, or open a PR
against it. It carries none of the delivery conventions (no CODEOWNERS, no branch
protection, no tickets), and its internal decisions are input material only — where they
disagree with this project’s architecture or proposal, this project wins
(.claude/rules/source-trust.md).
Running it locally — two servers. Because every screen now fetches from the API, the web app on its own renders an empty shell.
The short way, from a session in the harness repo: /et-run-pwa-poc (--no-seed for an
empty app, --stop to shut down). It runs exactly the steps below, checks the ports first,
seeds a campaign and a few leads, and verifies the app responds before telling you it’s up.
Seed on every run, not once. The mock API keeps everything in memory, so it comes up empty each time — which is why the command seeds by default. Skipping it gives you blank screens on every tab, and a blank POC reads as a broken one.
By hand, from the workspace parent directory:
# once
cd forge-et-pwa-poc && npm install && make api-install
# terminal 1 — mock API, no credentials needed (localhost-bound; vite proxies to it)
cd forge-et-pwa-poc/apps/api && USE_MOCKS=true AUTH_ENABLED=false \
.venv/bin/uvicorn app.main:app --port 8000
# terminal 2 — PWA on https://localhost:5173, and on the LAN IP for phone testing
cd forge-et-pwa-poc && npm run dev:web
AUTH_ENABLED=false is load-bearing: make api-dev sets only USE_MOCKS=true, but
auth_enabled defaults to true (apps/api/app/config.py), so with no Supabase
configured every data route 401s and the PWA loops on “your session has expired”. Carry a
first-class mock target into forge-et-pwa so nobody rediscovers this.
Two further notes for anyone walking through it. The mock enrichment always returns the same contact regardless of the card photographed, so repeat captures correctly show up as duplicates. And the Plan screen stays empty until a specific campaign is selected in the campaign bar — “All leads” has no exhibitor list to show.
Generated Artifacts — You Should Never Have to Think About These
Three things in this repo are generated and gitignored: the rendered doc site (docs-html/),
the dashboard data files (.forge/dashboard/{tracker,signals,metrics}.js) and the harness
reference graph (.forge/dashboard/harness-reference-graph.{html,md} — open the HTML to see which
document points at which, plus dangling references and unattached docs). Each is a whole-file
rebuild of the tree it runs over, so every machine produces the same output from the same tree —
and that is also why they are not committed: two branches that both regenerated them conflicted
byte-for-byte on every merge while never disagreeing about anything real.
Three mechanisms keep the local views fresh, so in normal work you do nothing:
- A fresh clone —
./forge-start.shbuilds whatever is missing the first time you run it. - In a Claude Code session —
Stophooks regenerate them at the end of every turn. - Editing outside a session —
.githooks/pre-commitregenerates the doc site and the reference graph with your commit (the dashboard data refreshes the next time a session runs; the hook stages nothing).forge-start.shpoints git at it (core.hooksPath=.githooks); if you never runforge-start.sh, set it once yourself:
git config core.hooksPath .githooks
Note core.hooksPath replaces .git/hooks, so move any personal hooks into .githooks/ if
you have them. git commit --no-verify bypasses it.
Repo hygiene CI proves the generators run. A markdown change that breaks the renderer or a
path change that breaks the graph scan fails the PR with the command to run locally. It also fails
if a machinery doc has no references in or out — link it (usually a CLAUDE.md Reference Map row,
or its directory’s README) rather than leaving it floating. Payload — discovery exports,
screenshots, the vendored prototype — is exempt, so dropping in a screenshot can never break the
build. The hosted site is built from main by the Publish dashboard workflow, which runs
.claude/lib/pages-build.sh on every push to main and pushes the result to the live branch
that Cloudflare Pages serves — the dashboard at /, the reference graph beside it, the doc site at
/docs/ — so it follows main without anyone committing generated output.
After a git pull, your local views include everyone’s new files the next time anything
regenerates them — the generators read the whole tree, not a delta.
Remotes (GitHub org altrium-io):
- Harness:
https://github.com/altrium-io/forge-et-harness - Backend:
https://github.com/altrium-io/forge-et-be - Frontend:
https://github.com/altrium-io/forge-et-fe - Capture app:
https://github.com/altrium-io/forge-et-pwa - Capture POC (read-only):
https://github.com/altrium-io/forge-et-pwa-poc - Infrastructure (trunk
dev):https://github.com/altrium-io/forge-et-iaac
Cross-Repo Commands
# Start both dev servers inside a feature worktree
cd worktrees/<ticket>
(cd forge-et-be && ./gradlew bootRun) &
(cd forge-et-fe && pnpm dev)
Mobilisation Week Agenda (24–28 Aug)
The agenda the team worked through before kickoff (1 Sep) is in .forge/engagement-log.md § 2026-10-05 — the mobilisation-week agenda, moved from the team guide.
Ceremonies
Agreed by the team 2026-08-19, ahead of mobilisation week.
- Standup: async, each working morning, in the team chat — yesterday / today / blocked.
- Sync call: twice weekly (Mon + Thu) during the build window — plan, dependency check against the timeline §4 register, tracker walk.
- Retro: one per delivery phase, folded into the phase-demo debrief, plus the UAT-round debriefs.
- Demo: end of each phase, to the Empire Teas signatory — the client-facing cadence in
client/project-timeline.md §2.
Communication
Agreed 2026-08-19.
- Day-to-day: Slack — the private
et-teamchannel. - Blockers / escalation: Tharinda (lead) first; Altrium management for anything client-facing or commercial.
- Client contact: the lead only — one contact toward the client.
Branching & Releases
Full rules in .claude/rules/git-conventions.md; AD #24 locks the shape. The short version:
mainis the trunk. Branch from it, PR back to it, branch deleted on merge. Dev deploys every merge. Never push tomaindirectly — protection blocks it, and so does the review rule.- Merge commits only — original history always preserved. Squash and rebase are disabled at the repo level, so the merge button has exactly one behaviour.
- Commit locally as often as you like; push in meaningful batches. Every push to a PR runs the validation pipeline, so pushing per-commit burns Actions minutes for no signal — push when you want CI’s verdict, when a review round’s fixes are complete (one re-review, not five pings), and always before stepping away: an unpushed branch exists on exactly one laptop, and the end-of-sitting push is also the backup.
- Name the branch after the ticket:
feature/F2-kanban-board,fix/BUG-000-quote-rounding. Commits and PR titles carry it too —feat(F2): add drag-and-drop to the kanban board. Housekeeping with no ticket just drops the segment:chore: add CODEOWNERS. - Releases are annotated tags —
v0.1.0at Phase 1,v1.0.0at V1 sign-off, patch bumps for fixes to a live release and for each fix release in a UAT round. UAT and production always deploy a tag, never a branch. - A
release/vX.Y.Zbranch appears only once that release is live in production, cut from its tag. Fixes for what is live go there ashotfix/<TICKET>-…, get a patch tag, and are then merged back intomain— that merge-back is the one step you must not skip. Release branches are never deleted. - Until something is live there is no release branch: UAT defects are fixed on
main, and each fix release bumps the patch in both app repos before it is tagged (.claude/rules/release-and-branch-protection.md § Release Process).
Environments
Two cloud environments plus local (coding-standards.md §5; a separate staging tier is an unpurchased +$45/mo add-on — see OQ-49).
| Environment | URL | Deploys from | Notes |
|---|---|---|---|
| Local | — | — | ./gradlew bootRun (BE) + pnpm dev (FE); Docker Postgres; local profile stubs the provider seams (coding-standards.md) |
| Dev | dev.crm.empire.lk (app) and api.dev.crm.empire.lk (API, AD #33) — live: the API since 2026-10-09, the app since 2026-10-13, and sign-in as CRM01 works; the capture app has been deployed at capture.dev.crm.empire.lk since 2026-10-25; the first upload succeeded on 2026-10-26 (F38-d WI-6.1), and the mailbox is configured but not yet proved by use (.forge/design/environments-and-identity.md §4) |
auto-deploy on merge to main |
The build environment — never hosts a UAT round |
| UAT | one instance for both acceptance rounds | a release tag | Temporary — terraform apply of the uat instance, kept from Phase 1’s round to the end of Phase 2’s, then destroyed by hand when the lead decides it is no longer needed, never on a schedule (AD #23; .claude/rules/tracker.md § Release & UAT Lifecycle); or pre-go-live production with test data cleared |
| Prod | crm.empire.lk and api.crm.empire.lk (AD #33) — set up by F38-i (production and go-live; tracked in Phase 1) |
a release tag (vX.Y.Z) |
Promotion is deliberate — deploying a tag, not a branch. A delivery phase may go live here ahead of V1 sign-off |
A forge-et-be branch deployed to dev by hand must contain the code for every schedule dev runs (merge main into it first). Otherwise every firing is refused as an unknown job kind and dead-lettered until main is deployed again. This means:
- F20-g wave 1, once the
scheduled-email-sendschedule is on dev (register §B F20-g row (a)); - F37-a wave 1 as well, once the
price-broadcast-sendschedule is on dev (register §B F37-a row (a)); - F37-b wave 1 as well, once the
bulk-email-sendschedule is on dev (register §B F37-b row (a)); - F36-c as well, since the hourly
capture-research-sweepschedule went on dev (forge-et-iaac#25,6fca402, 2026-11-20; register §B F36-c item (b)); - F22 wave 1 as well, once the hourly
contact-sync-sweepschedule is on dev (register §B F22 row (b)).
After a dev deploy — the smoke run
The smoke run is a short, read-only check that dev works after a deploy (F38-g FR-2, FR-3). It runs on your machine, not in CI, so it costs no GitHub Actions minutes.
- The command:
pnpm e2e:smoke, from aforge-et-fecheckout onmainwithpnpm installdone, Chromium installed (pnpm exec playwright install chromium) andghsigned in. A Chromium window opens athttps://dev.crm.empire.lk; choose Sign in with Microsoft and sign in ascrm05@empire.lk, the reserved smoke account, with the password you hold out-of-band. The window closes by itself, and the run prints nine checks by name with their results, the account’s role and keys, and the time taken. It never types or stores a password, writes nothing on dev, and deletes its session file when it ends, interrupted runs included. - Who runs it, and when: the delivery-team member whose merge to
main, or manual dispatch of the workflow, started adeploy-devrun inforge-et-beorforge-et-feruns it once that deploy run has finished. - A deploy the DevOps team starts by a direct push to
mainis covered by the next smoke run a delivery-team member makes. - A failing run is raised as a
BUG-NNNthrough the bug flow (.claude/rules/tracker.md § Bug Tracking), and dev is fixed before new work merges, as a failed nightly run is. A passing run is not recorded. - From when: the rule has applied since 2026-10-21, when the smoke account was set up on dev (F38-g-WI-2.1,
.forge/design/environments-and-identity.md§5).
forge-et-fe’s e2e/README.md § The smoke suite describes the checks, the session file and the reserved SMOKE records.
How We Use the Forge Workflow on This Project
- Tracker cadence: walked at the twice-weekly sync; updated by whoever moves a feature’s state (see
.claude/rules/tracker.md). - Spec/plan approval: the author may approve their own through the review skill (§ Review Pairings above); a teammate’s look is optional.
- Project-specific gates:
- Every harness PR runs
Repo hygieneCI: a secret scan (gitleaks), front matter, the tracker parse, shellcheck, and the doc-site and reference-graph generators running clean. - Each app repo’s
mainrequiresFast lane,Slow lane,Test recordandForge review(.claude/rules/git-conventions.md § Branch Protection; re-check withgh api repos/altrium-io/<repo>/rules/branches/main). - The Trivy dependency scan reports HIGH and CRITICAL findings (CVSS ≥ 7.0) on every ready app-repo PR without failing it. Only a UAT or production release stops on an open finding that has no exception (AD #9, AD #27, AD #38).
- New interactive elements need a
data-testid(coding-standards.md §4).
- Every harness PR runs
Choosing a Claude model and effort
This section is the one place in the harness documentation that names the Claude models we develop with; the guides under .forge/guides/ point here rather than repeating it. Two other places must name them, and change with this section when the team adopts a model:
- the project settings (
.claude/settings.json, below); - the usage dashboard’s price table (
.forge/dashboard/usage.html, with a copy inindex.html). Add the new model’s rates to both pages, or the dashboard prices it at a fallback rate and shows an “Unknown model rate” warning.
This section covers the development tooling only. The models the CRM itself calls at runtime are AD #19’s decision, and nothing below affects them. For current model facts (names, prices, effort behaviour), consult the claude-api skill rather than this section. Working defaults as of 2026-09-23.
One model for everything: Claude Opus 5.5. The /forge-deliver driver, spec and plan authoring, every sub-agent (implementers, test implementers, reviewers) and every background task run on Opus 5.5. There is no cheaper model for implementation and no premium model for hard problems.
| Situation | Effort |
|---|---|
Default for all work — driving /forge-deliver, authoring, reviews, implementation |
high |
| A hard problem the default did not solve — a difficult wave-decompose, a cross-cutting plan, a failing test that resists diagnosis | xhigh for that session, then back to high |
| Not used | max, which overthinks structured harness artifacts and spends the weekly cap for little gain; ultracode for /forge-deliver, which adds Claude Code’s own workflow orchestration on top of the orchestrator we already run |
Why high and not xhigh as the default. Anthropic’s default for Opus 5.5 is medium. It reports that medium already matches Opus 5 at high on coding work, and advises keeping xhigh and max for tasks where a quality gain has been measured, because Opus 5.5 thinks more at each level than earlier models did. We run one level above Anthropic’s default because a gate or rule missed during a long run costs a review cycle. With implementation also on Opus, xhigh everywhere is the setting most likely to use up the weekly cap before the week ends.
Setup: none — the project settings carry the default. The shared .claude/settings.json sets "model": "claude-opus-5-5" and, under modelSettings, "effortLevel": "high" for that model. Project settings take precedence over each person’s ~/.claude/settings.json, which is where /model and /effort save a default, so every session started in this repo opens on Opus 5.5 at high. The effort sits under modelSettings rather than as a top-level effortLevel because Claude Code resolves effort one model at a time: a per-model entry in the project file outranks a level someone saved for Opus 5.5 in their user file. The model is the exact id rather than the opus alias so that a new Opus release is adopted by a change here, not by the alias moving. It covers sessions started in this repo only; a session started inside an app repo uses that person’s own defaults.
/modeland/effortinside a session still change that session — that is how to go toxhighfor a hard problem. The next session in this repo starts on the project default again.- A standing personal override (for example the Opus 4.8 fallback below) goes in
.claude/settings.local.json, which overrides the shared file; set the model and itsmodelSettingseffort there. The repo’s.gitignorekeeps that file out of git. - Do not set
CLAUDE_CODE_SUBAGENT_MODELorCLAUDE_CODE_SUBAGENT_MODEL_FORCE. Without them, Claude Code’s built-in sub-agents (Explore, Plan, general-purpose) also run on the session’s model.
How sub-agents follow the driver. Every agent definition in .claude/agents/ declares model: inherit and has no effort: field. So each one runs on the driver session’s model, at the driver session’s effort. model: inherit wins over a personal CLAUDE_CODE_SUBAGENT_MODEL. Only a model parameter passed when dispatching overrides it, so do not pass one. A session at xhigh therefore dispatches its implementers at xhigh too — return to high before a long implementation wave.
Weekly cap. A Team seat has one weekly usage cap across all models, and it does not roll over. Implementation runs on Opus too, so watch the cap during the week’s first large implementation wave. If it runs short, lower the effort for light work (/effort medium for tracker edits, small doc fixes and questions) rather than changing the model.
Settled (lead’s decision, 2026-10-04). Opus 5.5 at high, with xhigh for a hard problem, is the setup for all work; the trial begun on 2026-09-23 is closed. If Opus 5.5 regresses on our work or is unavailable, move the default to xhigh first; if that does not fix it, use Opus 4.8 at xhigh as the fallback. Switch at the start of a session, not partway through a run: switching re-reads the whole context without the prompt cache and drops the earlier model’s reasoning.
What to watch on Opus 5.5. The load-bearing gates are deterministic hooks, so no model can bypass spec/plan approval, protected paths or the PRD shape. The differences to watch are the Opus 5 family’s documented tendencies (Anthropic’s “Prompting Claude Opus 5.5” and “Prompting Claude Opus 5”):
| What you observe | What to do |
|---|---|
| Adds work nobody asked for — extra steps, a nearby fix, a broader change | This lands on the soft ASK-FIRST items (plan deviation, new dependency, schema change, opening a locked phase), which hooks do not catch and reviewers do. Point it back at the approved plan’s scope |
| Re-verifies its own work, or dispatches extra sub-agents for checks the plan did not call for | Tell it to stop: the harness’s own verification steps (/forge-test-verify, the reviewers) are the verification, and unrequested sub-agents spend the weekly cap |
| Ends a long run with a summary that announces the next step instead of taking it | Reply “continue”. For background agents, /forge-deliver’s integration barrier waits for every work item to reach pr-open, so an agent that stopped early shows up there |
| Turns run long and slow on routine work | Check /effort — the session is probably still on xhigh from an earlier hard problem |
Does the harness suit the Claude 5 models?
Assessed on 2026-09-23 when the team adopted Opus 5.5, against Anthropic’s “Prompting Claude Opus 5.5” guide, its audit guidance for prompts written for older models, and Claude Code’s guidance on CLAUDE.md files. In short: the enforcement layer suits the newer models; the guidance layer carried too much text, and some of it was out of date or wrong.
-
What already fits. The load-bearing gates are hooks, which is what Claude Code’s documentation recommends for anything that must hold whatever the model decides. The instruction text uses a normal register; capitalised MUST/NEVER is rare. It has none of the patterns Anthropic identifies as harmful on current models: no “think step by step”, no request to write out reasoning in the reply (Opus 5.5 can decline those), and almost no “double-check your work” instructions, which make the Opus 5 family over-verify. Skill descriptions are short.
-
What the length question is really about. Anthropic’s guidance is that the harm comes from specific outdated or contradictory instructions, which newer models follow more literally, more than from length alone. Claude Code’s documentation still recommends keeping each CLAUDE.md short (under about 200 lines of normal length), because a longer file costs context and lowers adherence. Both applied here.
-
Fixed with the Opus 5.5 adoption. The rules in
.claude/rules/had never been path-scoped: they used aglobs:key that Claude Code does not read, so every rule loaded in every session. They now usepaths:. Sub-agent model routing existed only as advice; every agent definition now declaresmodel: inherit. Model names were repeated in four documents; they now live only in this section. Measurements and detail:.forge/lessons.mdL-064. -
Oversized: CLAUDE.md. On 2026-09-23 it was several times the size of the upstream template. Most of the excess was in three places:
- the Architecture Decisions table, whose rows kept their rationale and superseded text inline (AD #30 still described the role templates AD #32 had removed);
- the Reference Map, whose rows had grown into status reports (one called a decided memo “nothing decided”);
- Active Context.
A separate harness PR reduces each AD row to the rule in force and each Reference Map row to one clause, archiving the prior text verbatim in
.forge/engagement-log.md. It is separate because it rewrites the wording of the DO-NOT-REVERSE table. That removes roughly a fifth of the file; most of what remains is rules the team builds against. The next reduction is§ Boundaries, which upstream’s context-rightsizing spec already plans to trim after a live-engagement trial. -
Left to upstream: the long command, skill and agent bodies. They load only when invoked,
/forge-deliverbeing the largest. Anthropic warns that step-by-step prompts written for older models can lower quality on current ones, but the ordered git, branch and PR steps are exactly the fragile sequences that should stay scripted. Upstreamforge-harnessalready has the cuts drafted behind a live-engagement trial (its context-rightsizing spec), so take them through a harness sync rather than hand-editing upstream-derived files here. -
Not a harness change: model-specific prompting. Claude Code adjusts its own system prompt for each model, so none belongs in the harness.
Do not refactor the shared CLAUDE.md prompts for a model. Handle any remaining quirk by observation, then a targeted rule in the specific skill or agent prompt, phrased for all models (Compounding Engineering). Reasoning: .forge/lessons.md L-053 and L-064.
Framework Reference
For everything not covered above (workflow phases, gates, session management, compounding engineering, quality gates, troubleshooting):
- Forge framework reference — model and rationale, synced into this repo (read on demand for why questions)
- Upstream forge-harness repo — source of template/CHANGELOG syncs; the tracker’s
harness_versionpins the last synced version