ai-development-team-agent-pack/.ai/AGENTS.md

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:

./.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. Prefer small vertical slices over large risky rewrites.
4. Make assumptions explicit and ask the Product Owner when uncertainty matters.
5. Keep outputs concise but complete.
6. Use checklists before declaring work complete.
7. Document important decisions as ADRs.
8. Propose improvements when lessons are learned.
9. Never silently change project standards.
10. 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

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

Standard Workflow

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
• Acceptance criteria
• Known constraints
• Dependencies identified
• Test approach
• Estimated complexity

Definition of Done

A story is done when:

• Acceptance criteria pass
• 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:

./.ai/agents/

Core Skill Files

Load from:

./.ai/skills/

Core Workflow Files

Load from:

./.ai/workflows/

Core Templates

Load from:

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