# AI Development Team Agent Pack

This repository is a boilerplate Git repo for running a Markdown-based AI software development team inside software projects.

## Purpose

The repo is organized so downstream projects can learn locally while still promoting durable improvements back into the shared upstream boilerplate.

## Ownership Model

- Reusable system rules live in `.ai/AGENTS.md`, `.ai/SKILLS.md`, and the reusable folders under `.ai/`
- Project-specific state lives in `.ai/project/`
- Local working notes and scratch files live in `.ai/logs/` and `.ai/local/`

## Recommended Sync Model

1. Start new work from this repo as a fork, template, or imported subtree.
2. Keep project-specific changes inside `.ai/project/`.
3. Capture durable lessons in `.ai/evolution/proposals/`.
4. Promote approved `upstream-candidate` changes back to this boilerplate repo.
5. Record released baseline changes in `.ai/version.md` and Git tags.

## Install Into Another Project

Copy the `.ai` folder, `CLAUDE.md`, and `AGENTS.MD` into the root of your software project.

## Start

Tell your AI coding agent:

```text
Read ./.ai/AGENTS.md and help me work as the Product Owner.
```

## How to Use the Contract-First Workflow

When you start a new feature or change:

1. Ask the agent to write the user story.
2. Require a contract before implementation.
3. Review the contract for:
   - Preconditions
   - Inputs and outputs
   - Postconditions
   - Invariants
   - Failure modes
   - Side effects
4. Turn the contract into acceptance criteria and tests.
5. Implement only after the contract is clear.
6. Re-check the result against the contract before accepting it.

### Short Example

```text
As a user, I want to export a territory, so that I can download the generated files.

Contract:
- Preconditions: The territory exists and the user is authorized.
- Inputs: Territory ID.
- Outputs: A downloadable ZIP file.
- Postconditions: The ZIP contains the generated XLSX and PDFs.
- Invariants: The exported files are named consistently.
- Failure modes: Missing territory, file write failure, or export timeout.
- Side effects: Temporary export files may be created and cleaned up after download.
```

## Intended Workflow

Use this repo as the shared AI operating system, then let each downstream project keep its own product state and delivery history.

1. Start the agent with `./.ai/AGENTS.md`.
2. Define or refine the project in `./.ai/project/`.
3. Ask the agent to turn ideas into epics, stories, acceptance criteria, and a design-by-contract boundary before coding.
4. Implement work in small vertical slices.
5. Review results against the contract, acceptance criteria, tests, security, and documentation.
6. Capture durable lessons in `./.ai/evolution/proposals/` before changing reusable rules.
7. Promote approved `upstream-candidate` improvements back into this boilerplate repo.

## Typical Session Flow

### 1. Project setup

Use the agent to establish the project definition:

- Fill in `vision.md`
- Capture important decisions in `decisions.md`
- Build a roadmap in `roadmap.md`
- Turn priorities into epics and stories in `backlog.md`

### 2. Feature planning

Before implementation, ask the agent to clarify the request, identify missing information, and write acceptance criteria.

The agent should ask you for clarification instead of guessing whenever requirements are missing or ambiguous.

### 3. Implementation

Once the story is ready, ask the appropriate agent to implement the smallest useful slice and update tests and docs.

### 4. Review and release

Ask the agent to review the work against Definition of Done, document decisions, and note release impact.

### 5. Learning and promotion

When the agent discovers a durable improvement:

- Put temporary notes in `.ai/logs/` or `.ai/local/`
- Create a proposal in `.ai/evolution/proposals/`
- Mark it `project-only` or `upstream-candidate`
- Promote only reusable lessons back into the boilerplate

## Prompt Examples

Use prompts like these to drive the workflow.

### Startup

```text
Read ./.ai/AGENTS.md and help me work as the Product Owner. Start by reviewing ./.ai/project/vision.md and ./.ai/project/decisions.md.
```

```text
Read ./.ai/AGENTS.md, ask clarifying questions when anything is unclear, and do not make up missing requirements.
```

### Product definition

```text
Help me turn this idea into a project vision, target users, main problems solved, and product principles. Update ./.ai/project/vision.md.
```

```text
Based on the current vision, create a first roadmap and a starter backlog with epics and user stories.
```

### Story refinement

```text
Take this feature idea and convert it into a user story with acceptance criteria, constraints, dependencies, a design-by-contract boundary, and a test approach. Ask me questions before proceeding if anything important is missing.
```

```text
Review ./.ai/project/backlog.md and tell me which stories are not ready for implementation yet, and what clarification you need from me.
```

### Architecture and implementation

```text
Act as the software architect and backend lead. Propose the smallest safe implementation plan for this story, including risks, assumptions, and affected files.
```

```text
Implement this story as a small vertical slice. Update code, tests, and documentation. Define the contract first and stop to ask me if any behavior or requirement is unclear instead of guessing.
```

### Review

```text
Review this change against the acceptance criteria, Definition of Done, and security concerns. Tell me what is missing or risky.
```

```text
Summarize what changed, what still needs Product Owner clarification, and whether this is ready to accept.
```

### Evolution and upstream learning

```text
We learned something reusable from this project. Create an improvement proposal in ./.ai/evolution/proposals/ and classify it as project-only or upstream-candidate.
```

```text
Review this lesson and tell me whether it belongs in project files, local notes, or the reusable boilerplate. Do not promote it upstream unless it clearly generalizes.
```

## Key Features

- Product Owner-centered delivery
- Specialized AI agent roles
- Skill routing
- Workflow templates
- Definition of Ready and Definition of Done
- Controlled self-evolution
- Upstream promotion workflow for durable AI learning