A Specification-, Role-, and Gate-Driven Agentic Development Process for the Basic Next Compiler

Document status: description of a process being deployed (bucket process-adjustments). The results in Section IX are expected, not measured.

Abstract — Programming agents based on language models already perform multi-step engineering tasks, but their adoption in projects with a normative specification, such as a compiler, runs into three problems: the agent invents rules by analogy, evaluates its own work, and loses context between sessions. This paper describes the agentic development process adopted in Basic Next, an object-oriented language with an interpreter (bni) and a native compiler (bnc) that share a validated intermediate representation. The process combines five mechanisms: (i) precedence of the specification over the implementation, with a guardian that classifies each change as a fix, a complement, or an extension; (ii) separation of roles — planner, tester, implementer, reviewer, and auditor — assigned to different models by a single configuration file, which allows the assignment to be inverted according to each model's availability; (iii) small units of work (buckets, sprints, and activities) with acceptance criteria that must fail before the change; (iv) rules converted into executable gates, from the edit hook to continuous integration; and (v) project memory in versioned files in a private repository, instead of each tool's internal memory. The paper presents the objectives, the components, the operation, and the metrics by which the process will be evaluated.

Index Terms — software agents, language models, compiler engineering, test-driven development, independent review, continuous integration.

I. Introduction

The current generation of programming tools has moved from suggesting code snippets to performing entire tasks: reading a repository, planning, editing several files, running tests, and iterating until done. Tools such as Claude Code and Antigravity CLI operate in this mode, with access to the terminal and the file system.

In a programming-language project, this autonomy has a specific cost. The language is defined by a normative specification (grammar, semantics, reserved words), and a change that seems reasonable — accepting syntax from another dialect, "fixing" a defect by changing what a valid program does — is an alteration of the language, not a fix. The agent does not distinguish these situations on its own.

In Basic Next, the continuous use of agents across versions 0.4 to 0.6.12 exposed recurring failures:

1. Invented rule. Proposals that introduced constructs from other BASIC dialects or filled normative gaps by analogy.
2. Self-assessment. The same agent implemented, tested, and audited, and defects survived all three stages.
3. Loss of context. Buckets of 31 to 35 KB, with dozens of items, caused sessions to compact before closing.
4. False green. Tests run against stale binaries, and checks that passed locally and failed only in continuous integration.
5. Divergent instructions. The agent's brief and the skills repeated commands and numbers that, over time, came to contradict one another.

This paper describes the process that addresses these failures. The contribution is not a new algorithm but a composition of well-known practices — normative specification, test-driven development [3], independent review, continuous integration — adapted to agents that change session, model, and tool.

II. Context: the Basic Next project

Basic Next is an explicitly typed, object-oriented language. The toolchain, written in Rust, has a single shared frontend that produces the BN IR intermediate representation; this IR is validated once and consumed both by the bni interpreter, which is the executable reference, and by the bnc compiler, which generates native code via LLVM.

The order of authority is fixed: the specification; then the observable behavior of bni where the specification is silent; then the architecture documentation. A divergence between the toolchain and the specification is fixed in the toolchain, never in the specification. Language extensions are admitted only by a recorded decision of the maintainer (BDFL model).

The project keeps sibling repositories inside a common folder, bn/, which is not itself a repository: the code (basicnext, public), the textbook (basicnext-book, public), the editor extensions and, starting with this process, the private process repository (workflow).

III. Objectives

The process pursues six objectives, each tied to a failure from Section I:

• O1 — Specification above the agent. No change to the language surface without explicit classification and, for extensions, a maintainer decision.
• O2 — No model evaluates its own code. Whoever implements is never the one who tests, reviews, or audits.
• O3 — Work that fits in one session. Units small enough to be completed without context compaction and reviewed by a human.
• O4 — Rules that matter are executable. Every critical rule becomes an automatic gate; the brief's text merely points to it.
• O5 — Shared, auditable memory. State, decisions, and defects live in versioned files that any agent reads.
• O6 — Private process, public product. No public file cites private material, and no process file goes into the public repository.

IV. Environment architecture

Fig. 1 shows the organization. Agents always open in bn/, so that code, book, and process are in the same workspace: a language change and the corresponding book chapter are made in the same session.

The separation has two consequences. First, a git add -A in the public repository never publishes a process file, because there is none there. Second, the checks split into two sets: the code gates, which live in the public repository and read only it, and the process gates, which live in workflow and read the sibling repositories.

V. Components

A. Brief and skills

AGENTS.md contains the project's stable rules and is loaded in every session. Skills are folders with a SKILL.md describing a procedure; the agent sees only the name and description at the start and loads the content when the task matches. The process imposes a rule of authority: the brief defines, the skills only detail, and no skill repeats a number, path, package list, or command that the brief or a script already owns. Antigravity CLI truncates rule files above 24,000 bytes and limits the set of always-on rules to 20,000 tokens [6], which makes this trimming a technical necessity, not merely an aesthetic one.

B. Language guardian

The language-guardian skill applies a procedure to every change that touches the language surface: name the surface, cite the norm, check the vocabulary against the grammar and the reserved words, classify the change, and require evidence. Only fixes and complements proceed; extensions are blocked until a maintainer decision, and conflicts between normative sources are reported with options, never resolved by the agent.

C. Units of work

A bucket is a markdown file whose list of activities is the plan. Only files executed by an agent carry the bucket- prefix; design notes, plans, and reports live in separate files. Each activity has fields with a defined owner: Kind (the guardian's classification), Touches, Acceptance (written before the work and required to fail on the current tree), Test, and Evidence.

D. Roles and the roles file

The process defines five roles. The default assignment is in Table II, but it lives in a single file, roles.conf, and can be inverted by editing one line — for example, when one of the models runs out of quota.

Fig. 2 shows how an agent decides what it may do in a session.

Three rules hold for any assignment: the implementer is never the tester, reviewer, or auditor; the implementer never edits a test of its own activity; and the bucket is the only hand-off channel between agents. Each commit carries the Role: and Agent: trailers, and a gate checks that the declared role owns every changed path.

E. Gates

A gate is an automatic check that blocks progress. The process organizes gates in layers, from the fastest to the most complete (Fig. 3).

Some gates deserve mention:

• Prerequisites stamp. After building, the prerequisites script records a hash of the tree state (the current commit, the diff including what is staged, and the contents of untracked files). The test helper recomputes the hash and fails with an explicit message if it diverges. Comparing file timestamps does not work: Cargo relinks a binary only when one of its dependencies changes, and an edit to a crate the binary does not use would leave it "stale" forever.
• Pre-commit on the index. The hook formats and checks only what is in the commit (git show :<path>), never the working tree, so as not to block or alter other people's uncommitted work.
• Private-reference ratchet. The gate that forbids citations of private material in public files starts from a list of files and counts that can only decrease, like the existing file-size gate. This allows the rule to be introduced before cleaning up the roughly 300 existing lines.

F. Memory in files

Each tool's internal memory is invisible to the other when roles are inverted, has no history, and may hold a wrong conclusion without anyone noticing. The process replaces it with files in workflow (Fig. 4).

Memory is written at fixed points: the evidence when an activity is marked done, a hand-off line at the end of each session, and STATUS.md at sprint close. A lesson learned first becomes a test or a gate; only when that is not possible does it become a dated line in a skill. At the close of each bucket, the planner prunes the session notes.

VI. Operation

A. Life cycle of a bucket

B. Cycle of an activity across agents

Fig. 6 shows a complete activity with the default assignment. The central point is that the red test exists before the code, written by a different model from the one that will implement it.

Each activity produces commits identified by the ID (P3: …, P3 test: …, AUDIT-2: …) on a bucket branch. Every commit must build; only the test commit may fail its own new tests, and the binary search for regressions (git bisect) skips them. When the activity changes the language, it also produces a commit in the book repository, with the same ID.

C. Role inversion

To invert the assignment — for example, Claude implementing and Gemini testing — the maintainer edits roles.conf and commits it. No other file changes, because the brief and the skills speak of roles, not models. The review script reads the reviewer role and invokes the corresponding agent's command, with the model already pinned. If quota is exhausted in both directions, solo mode allows a single agent, with a mandatory reason and review in new sessions.

VII. Guarantees and how they are verified

A cross-cutting rule underpins the table: every acceptance criterion must be able to fail. It fails on the current tree, or on a planted defect, and passes after the activity. A criterion such as "CI is green" only shows that nothing broke. This rule was applied to the deployment bucket itself: a review before the first sprint found a criterion that already passed (the prerequisites script existed, although CI did not use it) and a count of private citations about five times lower than the real one, and the bucket was rebuilt before any code was written.

VIII. Deployment

The process is deployed by its own bucket, executed by Claude Code in solo mode, because Antigravity CLI is only verified in the last sprint. Fig. 7 shows the order.

The last sprint is an acceptance test of the tool switch: workspace root, single loading of the brief without truncation, loading of skills by description, permissions on the Windows test host, behavior of non-interactive mode when facing a rule that requires approval, and an end-to-end activity crossing the roles.

IX. Expected results

Results will be measured on bucket 0.6.14, the first one executed entirely under the process, against the baseline of buckets 0.6.11 and 0.6.12.

Calibration of the independent review uses real defects already fixed — a deadlock in the FIFO copy in 0.6.12 and a string-buffer leak in bnc — reintroduced on a throwaway branch. A reviewer is considered fit only if it finds the planted defect. The token cost of each review is recorded per sprint in order to later set a spending cap.

X. Limitations and risks

• Tester and auditor from the same model. In the default assignment, Claude writes the tests and also reviews and audits. A misreading of a criterion may survive in both the test and the audit. The mitigation is to run the audit in a session that did not write the tests, to check each test against the text of the specification rather than against the bucket's evidence, and to leave disputed findings to the maintainer.
• Hand-off cost. Two agents read the same bucket and the same specification, and each hand-off is a session boundary. The process trades speed for independence.
• Reliance on undocumented behavior. The Antigravity CLI workspace root in a folder containing several repositories, and the handling of rules that require approval in non-interactive mode, are not documented [6] and are verified empirically.
• Single point of storage. The process repository has no remote, and the formal documentation lives outside any repository; backup depends on the maintainer's machine.
• Rule overload. The process itself accumulates rules. The defense is the hierarchy (the brief defines, the skills detail), the conversion of rules into gates, and pruning at the close of each bucket.

XI. Future work

Three directions follow naturally: measuring the metrics of Table IV across several buckets rather than just one; studying whether role inversion changes the rate of defects found, which says something about the complementarity of the models; and relating the process to the research question of validating the alignment between agents and specification, for which Basic Next serves as an artifact.

XII. Conclusion

The process described does not depend on a more capable model, but on structure around the model: a specification that rules, roles that prevent self-assessment, units of work that fit in a session, rules that execute, and a memory that any agent reads. In terms of the classical taxonomy of agents [1], each programming agent is a goal-based agent that does not learn between sessions; the system's learning resides in the environment — the tests and the reviewer play the role of critic, and the decision and defect logs play the role of memory.

Acknowledgments

The text of this paper and the design of the process were developed with the assistance of Claude, Anthropic's assistant, under the direction of the author, who made all the recorded decisions.

References

1. S. Russell and P. Norvig, Artificial Intelligence: A Modern Approach, 4th ed. Hoboken, NJ, USA: Pearson, 2020.
2. C. E. Jimenez et al., "SWE-bench: Can language models resolve real-world GitHub issues?", in Proc. Int. Conf. Learn. Represent. (ICLR), 2024.
3. K. Beck, Test-Driven Development: By Example. Boston, MA, USA: Addison-Wesley, 2002.
4. R. C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship. Upper Saddle River, NJ, USA: Prentice Hall, 2008.
5. Software and Systems Engineering — Software Testing, ISO/IEC/IEEE 29119, 2013–2022.
6. Google, "Antigravity documentation: Rules, Skills, Hooks, Permissions, CLI reference". Accessed: Oct. 29, 2026. [Online]. Available: https://antigravity.google/docs
7. Anthropic, "Claude Code documentation". Accessed: Oct. 29, 2026. [Online]. Available: https://docs.claude.com
8. "AGENTS.md: a simple, open format for guiding coding agents". Accessed: Oct. 29, 2026. [Online]. Available: https://agents.md