Operating notes · Note 01
April 16, 2026 · 9 min read
Agentic practice
Agentic

What belongs
in AGENTS.md

The file an agent reads before code is a router, a set of hard rules, and a list of locks. It is not a diary, and it is not a second copy of every doc in the repo.

↓ The file that collapsed orientation
01
The first file

The first file
is not code.

In Built From the Rubble I wrote that a good AGENTS.md cuts orientation from about twenty minutes to about two. Before the pivot, a session opened with fifteen to twenty minutes of “which service handles this?” After it, orientation was about two minutes: read AGENTS.md, open the controller, start the work. Qwen Coder, the operator named in that essay, reads AGENTS.md at the start of a session, runs tests before calling the work done, and logs what it changed.

“The unit of architecture for agentic development is not the service boundary — it’s the context window.”
Built From the Rubble · March 2026

AGENTS.md is architecture for that window. If the first file the agent loads is long, vague, or full of secrets, the rest of the session inherits the waste.

02
Router and rules

A short router.
A longer lock file.

The root file titles itself “Steller Workspace Agent Router.” It is 63 lines. Its opening instruction is: “Read this file first to choose the correct instruction source.” Backend tasks follow backend/AGENTS.md. The root file says to use itself as routing guidance and not to duplicate backend hard rules here. The backend file is 121 lines and opens with its own order: “Read this file before every task. These rules are non-negotiable.” steller-backend/AGENTS.md is a symlink to ../backend/AGENTS.md, so there are not two backend policies. The root file states the split in one place: this file is workspace routing and precedence; backend/AGENTS.md is hard rules and execution constraints. If rules appear to conflict on a backend task, backend/AGENTS.md wins.

Unless someone says otherwise, “Read AGENTS.md” means both steps the root file lists. First, a policy-readiness check from the authoritative AGENTS file for that task scope. Second, a runtime-status verification using environment and runbook docs. It is not an invitation to redesign the platform before those checks.

Branch discipline is a chain. The default branch is main. Never push directly to main. The root file’s path is feature branch, then tests pass, then a pull request, then merge, then auto staging deploy. Production deploy and rollback are manual GitHub Actions operations with human approval. The backend file repeats the ban in a command: never run git push origin main. Feature work uses feat/... or fix/.... Backend is pushed first, then the root submodule ref is updated. Build and tests are run locally until they pass, and only then is the branch pushed.

03
Scope map

Point at docs.
Do not paste them.

The root router’s scope map names an authoritative file for each kind of task. The phrases in the left column are the file’s own labels. This essay quotes that map. It does not quote the documents the map points at.

Task scope, as the router labels it
Authoritative file
Transferable engineering knowledge — outcome-based testing, resilience, skills playbook, single file
docs/STELLER_TRANSFERABLE_KNOWLEDGE.md
Product leadership coach — PM, interview, and strategy persona, separate from engineering
docs/PRODUCT_LEADERSHIP_COACH_OS.md
Backend code, API, jobs, migrations, onboarding flow, Bamboo integration
backend/AGENTS.md
Copilot global behavior and repo-wide non-code policy
.github/copilot-instructions.md
Environment model and runtime identity
docs/ENVIRONMENTS.md
DB isolation and staging DB boundaries
docs/ONE_DB_PER_ENVIRONMENT.md
Staging runbooks and scripts index
docs/STAGING_INDEX.md
Open issues and tracked follow-up work
docs/BACKLOG.md
GitHub CI/CD operator flow and environment setup
docs/GITHUB_CICD_OPERATOR_GUIDE.md
Release process and branch discipline
docs/CHANGES_AND_RELEASES_BEST_PRACTICES.md
Developer docs site, developers.steler.org
docs/DEVELOPER_HUB_DEPLOY.md
This blog, muhanad.steler.org
docs/MUHANAD_BLOG_PUBLISHING_RUNBOOK.md

The router also says the product-leadership file is separate from engineering, and points at section 11 of the transferable-knowledge doc. That is a cross-reference, not a quotation of section 11. A scope map belongs here because an agent will otherwise guess which document is current. The rubble essay’s scorecard already named the failure: when each service has its own docs, the agent cannot tell which are current.

The developer-hub boundary is its own rule. developer-hub/ in the workspace is ignored in steller-v3, so edits there are not commits of that repo. The portal’s source of truth is the separate repository the file names, git@github.com:manni17/developer-hub.git. Partner-facing docs UI changes are committed there first. On the deploy host, git pull runs inside developer-hub/ because the Dockerfile copies that folder and does not clone GitHub at build time. Then only the developer-hub Docker service is rebuilt. The backend file repeats the same boundary as rule 1b: do not implement partner portal UI from the backend repo workflow.

04
The locks

Non-negotiables
are remediation locks.

The backend file is where Steller’s real AGENTS.md practice gets specific. These are not preferences. They are written as locks: an agent that “improves” them is breaking the file. The rubble essay called the same idea confirmation gates and remediation locks — make the wrong move unambiguously wrong.

Lock
Backend AGENTS.md
CORS
Only explicit origins. Never a wildcard in production.
Hangfire workers
WorkerCount must be 2 for Bamboo. Never increase it.
PlaceBambooOrderJob
No retry. Refund on failure. Swallow a refund throw.
Bamboo calls
Always send an Idempotency-Key on vendor calls.
JWT_KEY
Never hardcode it in source. Always read it from the environment.
Catalog validation
Never coalesce nulls. Keep a strict schema.
Business claims
Never bypass RequireBusinessClaimsMiddleware.

Around that table, the same file names moves that look helpful and are forbidden. Never delete or recreate existing model, migration, or context files. If a build error involves Order.cs, Brand.cs, ApplicationDbContext.cs, or any migration file, stop and report. Do not fix it by deleting or recreating those files. After every file change, run dotnet build Steller.sln. If errors increase from the baseline, revert the last change before going on. The build must stay at zero errors.

Environment variables use a double underscore for hierarchy. The file’s own correct example is PartnerOnboarding__TrialCreditAmount=500. The form it marks wrong is a single-underscore name. That 500 is the file’s syntax example. This essay does not turn it into a published price. Before setting any variable, grep docker-compose.yml for the existing section name. After setting it, confirm the container sees it with printenv.

Success is a business outcome, not HTTP 200 or exit 0. The file lists the checks. A created wallet’s AvailableBalance must equal the expected amount. A trial credit must equal the configured amount, not 0. An order counts as placed when a poll reaches Completed and the cards array is non-empty. Config counts as loaded when the running container’s environment shows the value. Warning signs mean stop, before any retry: balance 0 when trial credit is configured; the same unexpected result across test partners; HTTP 200 with business data wrong or missing; an environment variable visible while behaviour is unchanged; a log entry missing that should be present. Repeating the same action and expecting a different result is not investigation. The motive for a worker count of 2 is not written next to the lock.

05
Closed loop

Done means a run,
not a reassurance.

When the ask is to run until green, the root file requires a closed loop instead of waiting for pasted logs. Trigger the relevant GitHub Actions workflow. Poll until it completes. Pull the failed-step logs and classify the failure as an infra artifact, a readiness or timing problem, an endpoint or contract problem, an auth or secret problem, or an app regression. Apply the smallest fix in code, docs, or scripts. Re-run the same workflow. Stop only when the run is green, or when missing access genuinely blocks it. The default tooling is gh workflow run, gh run list, gh run view --log-failed, and edits that travel through a pull request. If that loop is repetitive — trigger, poll, fetch logs, patch, re-run — the root file says to make it automation, not another request that a person paste the log.

The backend file states the same loop for a deploy that must go green, and it separates smoke from “the process is up.” After an environment change, a config update, or a service restart, run ./scripts/smoke-staging.sh. For partner onboarding the file names four calls: POST /api/public/signup must return a partnerId; GET /api/wallet/me must show available balance equal to the trial credit, not 0; POST /api/orders must return 202; GET /api/orders/{id} is polled until Completed. Do not start that smoke when compose returns. Wait for API readiness first. The file’s example probe is http://127.0.0.1:6091/api/health, with a bounded wait, and on timeout print recent API logs and fail fast. Its sentence is the one to keep: do not treat docker compose up -d success as application readiness. Smoke scripts must follow routes verified from current controllers, not inferred legacy paths. When a smoke run rotates a partner API key, do not reuse a cached .env key from the prior run; generate a fresh key if generation revokes the old one.

Integration failures are fixed only in test files: Tests.Integration/CustomWebApplicationFactory.cs, Tests.Integration/TestDataFactory.cs, and the failing test class. Never modify Program.cs, services, or controllers to make a test pass. Before adding a configuration, endpoint, variable, or service, search docker-compose.yml and Program.cs and copy the existing format. The file also says where to look, which is an index, not a second copy of the code: Steller.Api/Program.cs for the API entry, OrderService.cs for order financial logic, BambooApiClient.cs for the vendor, and Steller.Infrastructure/Jobs/ for background jobs. The rubble essay’s orientation line remains “read AGENTS.md, open the controller.” The file itself names these paths.

What still does not belong is a transcript of the last run, a production secret, or a protocol body this record does not have. JWT_KEY is named only as a value from the environment. QWEN_PROTOCOL.md, HANDOVER_TO_QWEN.md, and CHANGELOG_AI.md stay names. Their text is not in either AGENTS file, and it is not invented here.

06
Two minutes

Orientation collapsed
because the file was short.

15–20m
Orientation before, asking which service
~2m
Read AGENTS.md, open the controller
63
Lines in the workspace router
121
Lines in the backend hard rules

I am not a developer. I build Steller with agents, from Mississauga, with no engineering team. The file works for that arrangement only if a new session can obey it without me re-explaining the locks. That is what belongs in AGENTS.md: the choice of source, the map of names, the commands that close the loop, and the rules that must not be improved.

Next in the series
Note 02 · Operating notes
The Agent Handover Protocol
What the hardening week named, and what can still be quoted.
Read the essay →