Historian
Turn long sessions into a usable record.
Incremental historian artifacts preserve what changed, why it changed and which evidence closed the work. Later agents can recover the decision without reconstructing thousands of turns.
The method behind the system
How AI agents become an engineering environment.
BlueShop tests whether agents can understand, change and validate one persistent distributed system when durable context, narrow authority, executable specifications, observable failures and hard evidence gates surround the model.
1. The Experiment
The research object is not the storefront. It is the engineering environment that allows different models and agents to understand, change and validate one persistent distributed system.
Can autonomous AI agents build, debug and evolve a complex software system when intent is explicit, authority is constrained and every important claim must survive executable evidence?
E-commerce supplies realistic pressure: money, identity, inventory races, state machines, event delivery, search, analytics, privacy and cross-service change.
- 01Persistent systemAgents return to the same code, infrastructure, defects and decisions instead of solving disposable toy prompts.
- 02Multiple abstractionsBusiness rules must remain coherent across domain models, APIs, events, data, UI, infrastructure and operations.
- 03Executable criticismA plausible answer is insufficient. Tests, traces, pipelines and visible behavior can contradict it.
- 04Accumulated learningDurable context records architecture, constraints, root causes and rejected approaches so later work can start from evidence.
Not a commercial claim: BlueShop has synthetic
development data, not real customers or product-market evidence.
Commerce is the experimental domain.
2. What Autonomy Means
Autonomy means an agent can carry a bounded engineering objective through investigation, implementation and verification. It does not mean removing human intent or pretending generated work is correct by default.
Agents are expected to
- inspect current code before proposing a change;
- trace callers, contracts and cross-service impact;
- write regression and acceptance criteria;
- make the smallest root-cause correction;
- run the relevant quality gates;
- read failure evidence and iterate;
- leave source, tests and documentation coherent.
Human governance remains
- defining the objective and useful outcome;
- rejecting weak design, misleading claims or poor storytelling;
- setting security and delivery constraints;
- deciding trade-offs when business ownership is ambiguous;
- accepting or redirecting the final result.
Authority follows the task
Engineering agent
Local user identity→Repository and worktree→GitLab token and API→K3s CI compute
Business persona
Keycloak identity→Role-specific OAuth scopes→MCP capability allowlist→Business API
Runtime workload
Service identity→Vault lease or workload token→Database, Kafka and service boundary
Useful distinction: autonomous execution operates
inside human-directed purpose. The experiment tests delegated
engineering agency, not an unsupervised organization.
3. Agent Orchestration
The primary agent coordinates the objective and retains the whole-system context. Specialists receive narrow, non-overlapping work and return evidence rather than independent product direction.
Coordinated engineering work
Human intentGoal, constraints, feedback and acceptance
→
CoordinatorScopes work, owns integration and reconciles evidence
→
SpecialistsExplore, implement, review, test, observe or act as a business
persona
→
HarnessesCode intelligence, tests, security, CI and runtime
observation
→
Verified changeOr a concrete failure that drives the next correction
Explore agentsLocate code, explain flows and identify impact without editing.
Exploration is delegated when the question spans several modules or naming conventions. Exact file and symbol work stays in the coordinator when delegation would add more context transfer than value.
Implementation agentsOwn a bounded change with tests and verification.
Independent workstreams use separate repository worktrees when they could collide. A specialist does not silently broaden scope into adjacent systems.
Review agentsChallenge correctness, architecture, security, evidence or unnecessary complexity.
Review is intentionally separated from authorship for large changes. Findings are resolved against source rather than accepted by authority.
Watcher and operational agentsWait for terminal system evidence and return actionable failures.
Long-running waits are moved out of the main reasoning loop. Watchers report terminal status, failed gates and relevant logs instead of encouraging manual polling.
4. Models, Context and Token Efficiency
The experiment is not “how many models appeared in telemetry.” It is whether the engineering environment can route work: deep reasoning where uncertainty is broad, fast variants where the task is narrow, and independent review where risk is high—while spending context on decisions rather than repetition.
| Role in the environment | When it is used | What must still constrain it |
|---|---|---|
| Coordination and implementation | Cross-service change, long diagnosis and delivery loops | Ownership, acceptance criteria and CI/deploy evidence |
| Exploration and specialist review | Ambiguous boundaries, security, architecture and evidence challenges | Findings resolved against source, not model authority |
| Alternative providers under the same harness | Compatibility checks and real project exposure beyond one vendor | Identical tools, rules and gates—not a separate process |
| Fast or lightweight variants | Focused reads, classification, simple checks and watcher-style waits | No skipping of the evidence path for “small” tasks |
Measured BlueShop token activity
| Value | Metric | Meaning |
|---|---|---|
| 273,673 / 275,914 | Metered assistant messages (99.2%) | Messages with non-zero local token telemetry |
| 1,588,401,797 | Uncached input tokens | Prompt input processed outside provider cache reads |
| 35,470,031,235 | Cache-read tokens | Stable prompt content reused from provider caches |
| 247,004,119 | Cache-write tokens | Prompt content written into provider caches |
| 74,475,565 | Model-output tokens | Generated output, including delegated work |
| 20,121,640 | Reasoning-output tokens | Separately reported internal reasoning tokens |
| 95.7% | Prompt-token cache-read share | cache reads / (cache reads + uncached input) |
| ~50,862 | Estimated unretained input tokens | Uncached prompt input extrapolated from a comparable period |
| ~5,138,760,832 | Estimated unretained cache-read tokens | Reused prompt content in the estimated period |
| ~226,579,700 | Estimated unretained cache-write tokens | Prompt content cached during the estimated period |
| ~17,032,794 | Estimated unretained output tokens | Generated output in the estimated period |
Source: local OpenCode telemetry for BlueShop project worktrees, 2026-04-09 through 2026-07-22. The 95.7% figure is a reuse ratio, not a claim that caching reduced cost or work by 95.7%. Earlier local history is unavailable; its activity is an approximate extrapolation from a comparable retained month, not a measured total.
No fabricated ROI: local telemetry records $80.51 of
provider cost, but subscription-backed and zero-cost records make that
total incomplete. No financial return or productivity percentage is
claimed without complete cost and human-effort baselines.
Spend context on uncertainty, not repetition.
A token-efficient working set
Retrieve by intentSemantic search finds the likely boundary
→
Inspect exact symbolsRead the implementation, callers and tests
→
Reuse stable contextProvider caches avoid reprocessing stable prefixes
→
Prune spent outputDiscard large reads after extracting the decision
→
Preserve the learningMemory keeps the rule without keeping every log line
Semantic retrieval is a locator, not proof:
embedding-based similarity can find likely code even when the task and
source use different words. Exact symbols, callers, contracts and
tests still establish how the system actually behaves.
- 01Deep reasoning where uncertainty is broadCross-repository design, ambiguous ownership and distributed failures justify larger reasoning contexts.
- 02Fast variants where the task is narrowFocused search, classification, terminal watching and simple verification do not need the most expensive model.
- 03Independent perspective where risk is highA separate reviewer can challenge security, architecture, evidence or unnecessary complexity without duplicating the whole implementation.
- 04Prompt with boundaries and proofA useful task prompt names the owner, constraints, acceptance behavior and required evidence instead of loading the model with undirected prose.
THE ENGINEERING ENVIRONMENT
Models become useful through tools, constraints and feedback.
The remaining sections explain the current harness around the model rather than treating the model as the whole system.
5. Tools, Context and Memory
The agent is given structured ways to understand and modify the project. Raw shell access is not the default answer to every question.
- 01AFT code intelligenceSemantic and exact search, structure outlines, symbol-level reads, call context, diagnostics, conflict inspection and safe edits.
- 02Persistent project contextArchitecture snapshots, repository maps, project rules, durable memories and recoverable conversation history.
- 03Safety mechanismsCheckpoints, undo history, explicit worktrees and non-destructive Git rules bound the blast radius.
- 04Specialized operational toolsPipeline watchers and trace queries turn long waits or distributed failures into concise evidence.
- 05Context7 and Exa researchCurrent library documentation comes from Context7, while Exa supports broader web research.
- 06MCP business surfacesBusiness personas can act through role-specific tools without receiving shell, filesystem or database access.
Memory without carrying every token forever
Active context
System constraints+Project architecture+User preferences+Current task evidence
Durable context
Compacted session history→Project memories and notes→Source-backed documentation
Targeted recall
Search prior decisions→Expand only the relevant exchange→Return the learning to active work
Dreamer roles
Reflect deliberately, not on every coding turn.
Review, retrospective, documentation and memory-mapping roles can revisit accumulated work when deeper synthesis is useful. They are deliberate reflection tools, not an invented always-running agent platform.
Design principle: powerful tools are separated by
purpose. Code navigation, editing, business actions, runtime diagnosis
and recovery do not share one unconstrained interface.
6. Fast Feedback Without Tool Tax
Feedback must arrive early enough to change the work, but every check has a cost. BlueShop widens evidence with risk instead of running every tool after every edit.
Use the cheapest feedback that can disprove the change
While editing
AFT diagnostics→Focused unit or behavior check→Correct immediately
At a coherent checkpoint
Types and architecture→Wider affected tests→Review the complete diff
On cluster compute
Parallel GitLab jobs→SonarQube, security and integration gates→Build and deploy
Against the running system
Browser and API behavior→SigNoz, data and event evidence→Visible acceptance proof
Proportional feedback
Let risk decide the width.
Fast checks stay close to the edit. Expensive integration, mutation, load and live acceptance checks are reserved for the boundaries they can actually protect.
Batch and parallelize
Do not alternate between coding and every linter.
Coherent changes are checked together, heavy work runs in parallel on K3s runners and watchers return only terminal failures. The foreground agent keeps reasoning instead of polling or thrashing.
Tooling rule: every tool must answer a distinct
question. A redundant gate that adds latency without reducing a real
risk is engineering drag, not rigor.
7. Methodologies as Agent Constraints
| Method | How it constrains agent behavior | Failure it reduces |
|---|---|---|
| Domain-Driven Design | Use business language, explicit ownership, aggregates and state transitions | Editing the wrong service or flattening domain decisions into data plumbing |
| TDD | Make the defect executable before changing production behavior | Symptom patches and regressions without a durable check |
| BDD | Express acceptance as visible Given/When/Then behavior | Implementation passing while the stakeholder journey is still wrong |
| Root-cause-first diagnosis | Trace every shared caller and collect runtime evidence | Retries, longer waits or local guards hiding a distributed defect |
| Minimal solution discipline | Reuse existing patterns and write the smallest correct diff | Speculative abstractions and AI-generated boilerplate |
| Architecture fitness functions | Make package, reactive and dependency rules executable | Slow architectural drift invisible in one review |
8. Role-Scoped Business Personas
Five current personas exercise BlueShop as business actors through the MCP Gateway. They demonstrate constrained agency rather than unrestricted automation.
Observe, decide, act once, verify
ObserveUse only role-specific read tools
→
DecideChoose one useful business action or stop
→
Mutate onceRespect risk and action budgets
→
VerifyRead after write; report exact result or gap
| Persona | Useful autonomy | Boundary |
|---|---|---|
| Customer | Browse, manage cart, place orders and interact with owned commerce state | Customer identity and customer-safe MCP capabilities |
| Catalog manager | Inspect and govern products, categories and merchandising relations | Catalog-manager OAuth scope and role |
| Marketing manager | Observe campaigns and perform bounded campaign actions | Marketing capability allowlist and mutation budget |
| Logistician | Observe shipment work and advance legal delivery transitions | Logistics lifecycle and role scope |
| Support manager | Inspect queues, claim work and progress support cases | Support role, customer privacy and ticket state machine |
9. The Autonomous Feedback Loop
BlueShop combines fast local development with cluster and live-system validation. Each layer can reject the current hypothesis and return better evidence to the same agent context.
Hybrid local, cluster and live feedback
Intent and specificationWhat behavior matters and why
→
Fast local loopInspect, change and run focused checks
→
Cluster challengeParallel CI, SonarQube, integration and security
→
Live proofDeployment, browser, API, traces, events and data
→
Compounded learningRegression, architecture rule and durable memory
Local speed
Disprove cheap mistakes immediately.
Semantic code search, diagnostics and focused behavior checks keep the edit loop short. The agent does not wait for a remote pipeline to discover a type error or a broken invariant it could prove locally.
Cluster truth
Use the real environment for integration risk.
K3s runners provide parallel compute for wider gates. The deployed system then exposes identity, event, persistence, scheduling and observability behavior that a local test cannot reproduce.
10. Foundations Create Velocity
Models extend a codebase faster when the codebase teaches them how it works. Repeated architectural building blocks reduce entropy, shrink the search space and provide trustworthy examples for the next change.
Make the right path discoverable, not merely documented.
DDD and ubiquitous language remove competing names. Repeated structure, typed contracts, semantic search and architecture checks reveal the current path directly. Documentation keeps the map, rationale and non-discoverable constraints; it does not duplicate the implementation in a giant agent prompt.
The architectural compounding loop
Repeat a clear patternOne recognizable shape per concern
→
Retrieve an equivalentSemantic search finds a proven example
→
Adapt the building blockLess invention and less context
→
Enforce the boundaryTests and architecture rules reject drift
→
Strengthen the next exampleThe corrected pattern compounds
Low entropy
Patterns make extension predictable.
The agent can compare several existing implementations, identify the stable shape and spend its reasoning budget on the new domain behavior instead of rediscovering project conventions.
High entropy
Unique code creates repair work.
When every module solves the same concern differently, retrieval returns contradictory examples. Work slows down until the shared pattern is recovered and the exceptional code is refactored.
Engineering learning: velocity is built, not
prompted. Strong foundations reduce uncertainty and defect risk.
Defects will still appear; the goal is to bound their impact and turn
each correction into a stronger reusable building block.
11. AI-Friendly and AI-Resilient
An AI-friendly system is easy to understand. An AI-resilient system remains safe when the agent misunderstands it.
AI-friendly
- stable repository ownership and naming;
- concise architecture and structure maps;
- explicit domain state transitions;
- typed API and event contracts;
- repeatable package patterns;
- searchable logs, traces and correlation IDs;
- small commands with machine-readable output.
AI-resilient
- least privilege and role-scoped tools;
- default-deny security boundaries;
- database constraints and RLS;
- idempotent events and transactional outbox/inbox;
- immutable migrations and Git history;
- tests and architecture rules that reject drift;
- reconciliation and recovery paths after failure.
Risk objective: autonomy does not promise zero
defects. It reduces the chance of a defect, limits its blast radius,
shortens the time to evidence and makes the same failure harder to
repeat.
12. What the Laboratory Has Exposed
Five failures changed the engineering system. Open a case to see the signal, the evidence that contradicted the first explanation and the correction that remained afterward.
From flaky E2E to controlled shared stateConcurrent journeys exposed campaign bleed, unsafe cleanup and shared identities.
Evidence. Traces, artifacts and database timestamps showed active products and customer profiles being changed or deleted by another run.
Durable correction. Active-run protection, owned fixtures and serialization only around truly global campaign mutations kept the remaining suites parallel.
From free RAM to schedulable capacityJobs waited even though the machine still showed 28 GiB free.
Evidence. Kubernetes had already reserved nearly all allocatable memory and CPU through requests, while actual usage remained much lower.
Durable correction. Requests and quota were right-sized while burst limits remained available; concurrent pipelines then used the reclaimed capacity without becoming unschedulable.
From Vault corruption to a safe shutdownA host power-off left an all-NUL lease file on persistent storage.
Evidence. The shutdown script stopped containers before Kubernetes could terminate stateful workloads in order, interrupting a Vault file write.
Durable correction. Vault, PostgreSQL, Kafka, ClickHouse, Elasticsearch and their volumes now drain before K3s stops. Two complete power cycles proved recovery.
From ClickHouse OOM to a bounded queryOne product-performance card exceeded the 3 GiB query limit.
Evidence. The exact dashboard SQL scanned the deduplicated stream twice, joined served and clicked tuples and aggregated the result again.
Durable correction. Raw-fact aggregation reduced the same query to 394 ms and 68.97 MiB while preserving the product-level answer.
From invented architecture to source-backed docsAn abandoned agent-platform idea had drifted into the current story.
Evidence. Source validation found no current Argo Workflows/Events agent platform or matching manifests.
Durable correction. The false canonical and presentation references were deleted. Current AI documentation now describes only the local agent, MCP, context and engineering systems that actually exist.
13. Honest Limits
- 01No real customersDevelopment activity and BI figures are synthetic system data, not commercial traction.
- 02Human direction mattersAutonomy operates within human goals, corrections, constraints and acceptance.
- 03Evidence can driftDocumentation, tests and dashboards require continuous reconciliation with current source and runtime behavior.
- 04Tokens are activityThey measure processing scale, not correctness, usefulness or engineering quality.
- 05The system remains unfinishedKnown gaps and transitional boundaries are retained explicitly rather than hidden behind a showcase narrative.
Result
The model is one component. The engineering environment is the experiment.
BlueShop demonstrates a practical direction for autonomous software engineering: models with durable context, constrained authority, composable tools, explicit methods and a feedback loop strong enough to expose their mistakes.
Continue to the technical architecture · See the applied commerce result · Return to the site map