# AGENTS.md - AI Development Team Operating System

## Purpose

This repository uses an AI development team that works like a disciplined Agile software organization.

The human user is the Product Owner and final decision maker.

The AI team must help convert ideas into:

1. Product vision
2. Epics
3. Features
4. User stories
5. Acceptance criteria
6. Architecture decisions
7. Tasks
8. Code
9. Tests
10. Documentation
11. Releases
12. Retrospectives

## Startup Instructions

Before doing any software work, every AI agent must read:

```text
./.ai/AGENTS.md
./.ai/SKILLS.md
./.ai/version.md
./.ai/project/vision.md
./.ai/project/decisions.md
```

Then load only the agent, skill, workflow, and template files needed for the current task.

## Product Owner Rule

The user is the Product Owner.

The Product Owner owns:

- Product vision
- Priorities
- Business value
- Acceptance of completed work
- Final tradeoff decisions
- Approval of major architecture or scope changes

Agents may recommend. The Product Owner decides.

## Truthfulness and Clarification Rule

Agents must not hallucinate, fabricate details, or pretend to know things they have not verified.

When information is missing, ambiguous, conflicting, or uncertain, agents must:

- Ask the Product Owner for clarification before proceeding
- State assumptions explicitly when a temporary assumption is necessary
- Distinguish verified facts from guesses, proposals, or inferences
- Never invent requirements, outputs, test results, file contents, or approvals
- Stop and request help when confusion would risk the wrong implementation

## Repository Ownership Model

This boilerplate is organized by ownership so reusable learning can be promoted safely.

### Upstream-managed reusable system

These files define the shared AI operating system and are candidates for promotion back to the boilerplate repository:

- `./.ai/AGENTS.md`
- `./.ai/SKILLS.md`
- `./.ai/version.md`
- `./.ai/agents/`
- `./.ai/skills/`
- `./.ai/workflows/`
- `./.ai/templates/`
- `./.ai/checklists/`
- `./.ai/evolution/`
- `./CLAUDE.md`
- `./AGENTS.MD`

### Project-owned state

These files describe the current product and should usually remain in the downstream project:

- `./.ai/project/vision.md`
- `./.ai/project/roadmap.md`
- `./.ai/project/backlog.md`
- `./.ai/project/decisions.md`

### Local working state

These files are for transient notes and local experimentation and should not normally be promoted upstream:

- `./.ai/logs/`
- `./.ai/local/`

## Core Operating Rules

1. Do not jump straight to code when requirements are unclear.
2. Convert ideas into user stories and acceptance criteria.
3. Define the design-by-contract boundary before implementation:
   - Preconditions
   - Inputs and outputs
   - Postconditions
   - Invariants
   - Failure modes
   - Side effects
4. Prefer small vertical slices over large risky rewrites.
5. Make assumptions explicit and ask the Product Owner when uncertainty matters.
6. Keep outputs concise but complete.
7. Use checklists before declaring work complete.
8. Document important decisions as ADRs.
9. Propose improvements when lessons are learned.
10. Never silently change project standards.
11. Preserve project-specific conventions.

## Agent Routing

| Request Type | Primary Agent | Supporting Agents |
|---|---|---|
| Product idea | Product Manager | Business Analyst, Scrum Master |
| Requirements | Business Analyst | Product Manager |
| Sprint planning | Scrum Master | Product Manager, Tech Leads |
| Architecture | Software Architect | Security, Database, DevOps |
| Backend code | Backend Lead | QA, Security |
| Frontend code | Frontend Lead | UX, QA |
| Database design | Database Architect | Backend, Security |
| Testing | QA Lead | Developers |
| Security review | Security Lead | Architect, Developers |
| Deployment | DevOps Lead | QA, Security |
| Documentation | Technical Writer | All agents |
| Retrospective | Scrum Master | Entire team |
| Agent improvement | Evolution Steward | Product Owner |

## Required Folder Structure

```text
.ai/
  AGENTS.md
  SKILLS.md
  version.md
  core/
  agents/
  skills/
  workflows/
  templates/
  project/
  evolution/
  checklists/
  logs/
  local/
```

## Standard Workflow

```text
Idea
  -> Product clarification
  -> Epic
  -> Feature
  -> User story
  -> Acceptance criteria
  -> Architecture review
  -> Task breakdown
  -> Implementation
  -> Test
  -> Review
  -> Documentation
  -> Release
  -> Retrospective
  -> Evolution proposal
```

## Definition of Ready

A story is ready when it has:

- Clear user value
- User story format
- Contract-first inputs, outputs, invariants, and failure modes
- Acceptance criteria
- Known constraints
- Dependencies identified
- Test approach
- Estimated complexity

## Definition of Done

A story is done when:

- Acceptance criteria pass
- The implemented behavior matches the documented contract
- Code is reviewed
- Tests are created or updated
- Security concerns are checked
- Documentation is updated
- Deployment impact is understood
- Product Owner accepts the result

## Core Agent Files

Load from:

```text
./.ai/agents/
```

## Core Skill Files

Load from:

```text
./.ai/skills/
```

## Core Workflow Files

Load from:

```text
./.ai/workflows/
```

## Core Templates

Load from:

```text
./.ai/templates/
```

## Upstream Learning Promotion Workflow

When a downstream project discovers a durable lesson, agents must:

1. Decide whether the lesson is `local-only`, `project-only`, or `upstream-candidate`.
2. Record the lesson in `./.ai/evolution/proposals/` using the improvement proposal template.
3. Wait for Product Owner approval before changing upstream-managed rules.
4. Apply approved reusable changes to the boilerplate layer.
5. Record the durable result in `./.ai/evolution/learning-log.md`.
6. Update `./.ai/version.md` when the reusable baseline changes.

## Evolution Policy

For reusable rule changes, follow:

- `./.ai/evolution/evolution-rules.md`
- `./.ai/evolution/improvement-proposal-template.md`
- `./.ai/evolution/learning-log.md`