AI Agent Development Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The AI agent development workflow defines the strict rules and procedures that LLM coding agents (Codex and Claude Code) must follow when contributing to the cyrus project. Cyrus is a rebuild of The Elder Scrolls Adventures: Redguard written entirely by AI agents under human direction.
This workflow ensures fidelity to the original game, maintains legal compliance regarding copyrighted assets, and enforces technical quality through automated gates and specific verification methods.
Sources: AGENTS.md:1-12, README.md:144-146, CONTRIBUTING.md:4-7
Core Development Rules
Agents follow seven "Hard Rules" to ensure the project remains a clean-room implementation that requires an original game install to function.
| Rule | Description |
|---|---|
| No Tracked Assets | No game assets or research artifacts from the magic/ folder enter the Git history. |
| Read-Only Install | Cyrus never writes to the original game directory. |
| Faithful by Default | Behavior matches the original game's player experience by default. |
| Do Not Guess | All constants and logic must derive from documented preservation evidence. |
| Facts, Not Traces | Documentation states engine facts directly without memory addresses or offsets. |
| No Piracy | The repository contains no links to installers, keys, or copyrighted files. |
| Preservation Feedback | New engine discoveries are contributed back to the redguard-preservation project. |
Sources: AGENTS.md:14-63
Technical Verification Gates
Agents must validate changes using a hierarchy of local scripts and Cargo commands before committing. The "gates" ensure that the codebase remains stable and that documentation, such as the repository map, stays in sync with the source code.
Verification Levels
The following diagram illustrates the workflow for matching verification to the type of change:
The diagram shows the branching logic agents use to select the narrowest sufficient verification gate.
Sources: AGENTS.md:104-124
Automated Scripts
dev/scripts/publish-check.sh: Greps the tree for prohibited patterns like memory addresses or decompiler placeholders.dev/scripts/genmap.sh: Regeneratesdocs/MAP.mdfrom the first//!doc line of every module.dev/scripts/native-audit.py: Maps the native catalogue to installed scripts to identify unimplemented or unused handlers.
Sources: dev/scripts/genmap.sh:1-10, dev/scripts/native-audit.py:1-15, AGENTS.md:65-68
Handoff and Research Process
Research documentation and decompiler output are strictly separated from the implementation repository. Agents use a private research archive for intermediate artifacts.
- Work in
magic/: Agents keep untracked working memory, investigation plans, and raw research in the git-ignoredmagic/directory. - Private Archive: Before handing over a research task, agents push text observations and analysis to the private
redguard-decomprepository. - Durable Facts: Durable engine and format facts are moved to the public
redguard-preservationproject. - Implementation: Agents implement code in
cyrusbased only on the documented facts, never by copying decompiled code directly.
Sources: AGENTS.md:71-86, AGENTS.md:129-130
Contribution Standards
Agents use Conventional Commits and document all public APIs with invariants and units.
- Commits: Format is
type(scope): description. Scopes represent the crate (e.g.,game,web) or module. - Claims: Every claim about game behavior must be labeled as Verified (observed in game/preservation docs), Inferred (logically follows), or Unknown.
- Boundaries: Core logic must remain independent of rendering or networking. This is checked via
dev/scripts/check-core-boundaries.sh.
Sources: AGENTS.md:99-102, AGENTS.md:126-128, AGENTS.md:154-159
Conclusion
The AI agent development workflow prioritizes project longevity and legal safety over development speed. By enforcing a clean-room approach and rigorous automated verification, the project maintains a high standard of technical quality while successfully rebuilding a complex legacy engine using LLM assistance.
Sources: AGENTS.md:1-12, README.md:150-155