AGENTS.md git:20260422.2462a00A

Immutable. This exact content never changes and is served at /api/v1/blob/89fbaf5071adf0c7.

# ExStruct AI Agents Guide

## 0. Overview

This repository is organized around the following top-level directories:

```text
exstruct/
|- src/           # Main library and implementation code
|- tests/         # Automated tests
|- sample/        # Sample workbooks and example inputs
|- schemas/       # JSON schemas and validation-related assets
|- scripts/       # Utility and maintenance scripts
|- benchmark/     # Benchmark code and performance measurements
|- docs/          # User-facing documentation
|- dev-docs/      # All developer-facing documentation
|- tasks/         # Temporary task notes and working files
|- drafts/        # Draft documents and work-in-progress materials
|- dist/          # Build artifacts and packaged outputs
`- site/          # Generated documentation site output
```

For internal development guidance, architecture notes, ADRs, specifications, and testing references, use `dev-docs/` as the canonical location. Developer-facing documentation should be written there rather than scattered across the repository.

## 1. Workflow Design

### 1. Use Plan mode by default

- Always start tasks with 3 or more steps, or tasks that affect architecture, in Plan mode
- If things stop going well partway through, do not force it; stop immediately and replan
- Use Plan mode not only for implementation, but also for verification steps
- Write detailed specifications before implementation to reduce ambiguity

### 2. Multi-Agent Strategy

- Actively use sub-agents to keep the main context window clean
- Delegate research, investigation, and parallel analysis to sub-agents
- For complex problems, use sub-agents to apply more compute resources
- To keep execution focused, assign one task per sub-agent
- Use explorer for read-heavy codebase exploration
- Use worker for implementation and fixes
- Use reviewer for reviews

### 3. Self-Improvement Loop

- Whenever you receive a correction from the user, record that pattern in `tasks/lessons.md`
- Write rules for yourself so you do not repeat the same mistake
- Keep improving those rules thoroughly until the error rate goes down
- At the start of each session, review the lessons relevant to the project

### 4. Always verify before completion

- Do not mark a task as complete until you can prove that it works
- Compare the main branch and your changes when necessary
- Ask yourself, "Would a staff engineer approve this?"
- Run tests, review logs, and show that it works correctly

### 5. Pursue elegance (with balance)

- Before making an important change, pause and ask, "Is there a more elegant way to do this?"
- If a fix feels hacky, think, "Based on everything I know now, implement an elegant solution"
- Skip this process for simple and obvious fixes (do not over-engineer)
- Question your own work before presenting it

### 6. Autonomous bug fixing

- When you receive a bug report, fix it directly without needing step-by-step guidance
- Use logs, errors, and failing tests to solve it yourself
- Eliminate context switching for the user
- Even without being asked, go fix failing CI tests

---

## 2. Areas Outside the AI's Responsibility (Handled by Humans)

The AI does not own the following areas. Humans make these decisions.

- Specification decisions (the direction of ExStruct's evolution)
- Public API design (deciding whether something is a breaking change)
- Large-scale reorganization of the directory structure
- Security and licensing decisions

However, the AI **may make proposals**.

---

## 3. Required Work Procedure

The AI must always follow the steps below before generating code.

1. **Understand requirements**: Read specifications and design materials, and fully understand the requirements
2. **Consider the design**: Consider function decomposition and model design as needed.
3. **Define the specification**: Based on the requirements, define function argument and return types in `tasks/feature_spec.md`.
4. **Assign tasks**: Clearly define each task and determine the implementation order.
5. **Implement code**: Implement the code while following the standards above.
6. **Review code**: Self-review generated code and confirm that it meets the quality standards.
7. **Generate tests**: Generate test code as needed.
8. **Run tests**: Run the generated test code and confirm that it behaves as expected.
9. **Static analysis**: Run `uv run task precommit-run` and confirm that there are no mypy / Ruff errors.
10. **Update documentation**: If there are changes, update the related documentation as well.

---

## 4. Task Management

1. **Plan first**: Write the plan in `tasks/todo.md` as checkable items
2. **Review the plan**: Review it before starting implementation
3. **Track progress**: Mark completed items as you go
4. **Explain changes**: Provide a high-level summary at each step
5. **Document results**: Add a Review section to `tasks/todo.md`
6. **Record lessons**: Update `tasks/lessons.md` after receiving corrections

---

## 5. Documentation Retention Policy

### Separation of Roles

- `tasks/todo.md` may temporarily hold not only session-specific progress tracking, but also verification results, unresolved items, and summaries of decision rationale.
- `tasks/feature_spec.md` may be used as a pre-implementation working spec draft, but do not treat it as disposable if it contains specifications, constraints, or validation conditions that will be referenced in the future.
- `tasks/lessons.md` is where recurrence-prevention rules are stored, and should not be used to store design decisions or the specification itself.
- Permanent internal documentation belongs under `dev-docs/`.
- Move design decisions and trade-offs to `dev-docs/adr/`, current internal specifications and constraints to `dev-docs/specs/`, and implementation structure and extension guidance to `dev-docs/architecture/`.
- Only user-facing contracts such as public API, CLI, and MCP should be reflected in the corresponding documents under `docs/`.

### Using skills

- If you are unsure where to store a document, where to move it, or how to verify it, prefer using available skills over relying on manual judgment alone.
- Use `adr-suggester` to determine whether an ADR is needed, `adr-drafter` for ADR drafts or update proposals, `adr-linter` to lint drafts, `adr-reviewer` for design review, `adr-reconciler` for drift audits, and `adr-indexer` for index synchronization.
- Do not leave skill results trapped in temporary notes under `tasks/`; reflect them in the appropriate `dev-docs/` or `docs/` location as needed.

### Information to Keep

- Decision rationale that future implementers may encounter again on the same issue
- Chosen policies adopted after comparing multiple options
- Permanent rules established through review, CI, Codacy, or incident response
- Contracts related to public API, CLI, MCP, output formats, validation, and compatibility
- Specification context behind added regression tests where forgetting the reason could cause the issue to recur

### Information You May Discard

- One-off notes about work order
- Rejected hypotheses or interim notes that ended midway
- Progress logs with no reference value after completion
- Simple lists of steps with no decision rationale

### Required Steps at Completion

- At task completion, review the relevant sections of `tasks/feature_spec.md` and `tasks/todo.md`, and classify each item as either "temporary notes that can be discarded", "content that should remain in a permanent spec", or "content that should remain as an ADR".
- The AI must not blank out all of `tasks/feature_spec.md` or `tasks/todo.md` based on its own judgment. Cleanup must be limited to the relevant sections of the completed task.
- If there is content that will be referenced in the future, move it into permanent documentation before deleting anything.
- Do not discard decision rationale, specifications, or validation conditions before migration is complete.
- Only sections confirmed to contain no permanent information may be summarized, deleted, or archived.
- If ADR creation, spec creation, index synchronization, or design review is involved, and a corresponding skill exists, run it first and use its verdict and findings to decide the permanent document destination and what to reflect there.
- Choose the destination according to the role split defined in `dev-docs/README.md`.
- Prefer `dev-docs/adr/` for "why", `dev-docs/specs/` for "what is guaranteed", and `dev-docs/architecture/` for "how the structure works".
- Only when the change affects a public contract should you update the corresponding page under `docs/` in addition to moving the information into internal documentation.

### When to Create an ADR

- If you are unsure whether an ADR is needed, first use `adr-suggester` to determine `required` / `recommended` / `not-needed` and record the rationale.
- If any of the following apply, the AI must record the decision under `dev-docs/adr/`:
  - There are trade-offs or a comparison between multiple options.
  - The same question may recur in the future.
  - The design intent cannot be understood from the implementation diff alone.
  - A permanent policy was established through review, CI, Codacy, or incident investigation.
  - It is highly likely to be referenced by later implementation or review.

### End-of-Session Checklist

- Confirm that conclusions in the Review section of `tasks/todo.md` have been moved, as needed, into `dev-docs/adr/`, `dev-docs/specs/`, `dev-docs/architecture/`, or `docs/`.
- Confirm that contracts, constraints, and validation conditions in `tasks/feature_spec.md` have been reflected, as needed, in permanent documents under `dev-docs/`.
- If an ADR was added / updated / superseded, confirm as needed that the results of `adr-linter`, `adr-reviewer`, `adr-reconciler`, and `adr-indexer` do not conflict with the permanent documents.
- Only after the information has been moved into permanent documentation may the relevant sections be shortened.

---

## 6. Core Principles

- **Simplicity first**: Keep every change as simple as possible. Minimize the code affected.
- **No cutting corners**: Find the root cause. Avoid temporary fixes. Maintain senior engineer standards.
- **Minimize impact**: Limit changes to only what is necessary. Do not introduce new bugs.