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:

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

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, and acceptance criteria before coding.
4. Implement work in small vertical slices.
5. Review results against 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

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

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

Product definition

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

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

Story refinement

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

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

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

Implement this story as a small vertical slice. Update code, tests, and documentation. If you are unsure about behavior or requirements, stop and ask me instead of guessing.

Review

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

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

Evolution and upstream learning

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

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