git:20260315.b5e9049 to git:20260315.bd53ef2

# ExStruct AI Agents Guide

## 0. Overview

## 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.