open-agent-ready-typescript

open-agent-ready-typescript is a robust TypeScript codebase designed to enhance the productivity and reliability of AI agents in software development. This project introduces an innovative architectural approach where rules are implemented as actionable tools rather than mere documentation.

Key Features

This codebase exemplifies a small but functional invoicing API that includes essential features such as drafting, sending, and paying invoices with strict adherence to integer cents, supported by a well-defined state machine. The foundational thesis articulated here is:

Every rule that matters must be enforced by a tool the agent cannot argue with.

Five Architectural Guardrails

1. Dependency Management:
   Utilizing dependency-cruiser, this system enforces strict dependency rules, failing builds on illegal imports, ensuring that no domain code imports external modules, which solidifies architecture compliance.

2. Mutation Testing:
   The integration of mutation testing, powered by Stryker, ensures that code is genuinely tested. The CI will fail if mutation scores drop below 75%, promoting a relentless focus on test quality.

3. Protected Tests and Specs:
   With a PreToolUse hook, modifications to tests/** and specs/** files by AI agents are restricted, preserving the integrity of tests without risking their deletion, thus enforcing a more rigorous development approach.

4. Commit Verification:
   Every commit initiates a comprehensive verification suite, including type checks, linting, dependency verification, and tests, providing immediate feedback and maintaining high code quality.

5. Spec-Driven Development:
   Each use case is documented in a markdown spec with corresponding acceptance criteria. A rigorous check ensures that tests reflect all specifications, failing the build if discrepancies are found.

Structure and Documentation

• The repository contains an AGENTS.md file, encapsulating the open standard with intricate commands for the development process, along with nested AGENTS.md files that dictate local invariants across the code structure.
• Documentation for architectural decisions is maintained in the docs/adr/ directory to prevent the need for agents to revisit previous choices.

Benchmark Exercise

The repository includes a benchmark task (cancel-invoice) that serves as an evaluative framework for coding agents, ensuring that any agent can interact appropriately with the codebase by following the entire lifecycle from specs to implementation successfully.

Project Templates

This repository serves as a template for new projects and includes a Claude Code skill which allows users to easily set up a reinforced code structure for backend services, frontend applications, or monorepos. Developers can initiate their projects by executing commands that uphold the guardrails specified and foster a spec-first workflow.

Running the Project

Run the following commands to set up and test the API:

npm install
npm run verify        # Type check + lint + dependency rules + tests
npm run dev           # Start API on port 3000
npm run mutation      # Execute mutation tests

To create an invoice, use:

curl -s -X POST :3000/invoices -H 'content-type: application/json' \
  -d '{"customerName":"ACME Ltda","currency":"BRL"}'

Limitations

• While the test protection feature is specific to Claude Code, other agents can apply comparable strategies. Mutation testing in CI stands as a universal backstop for maintaining code quality.
• The sample database implementation relies on a basic JSON file which may not support concurrent processes, though replacing it with a more robust database solution is straightforward.
• Persistent mutation survivors might include redundant error message strings; the focus remains on consistent error codes rather than prose.

This repository stands as a critical resource for developers looking to leverage AI in their coding practices while ensuring robust software architecture.