You are preparing this repository for long-term collaboration between human developers and AI agents.

Your objective is to establish a consistent repository structure that clearly separates:

- permanent project knowledge
    
- reusable AI guidance
    
- temporary working artifacts
    

The repository should remain fully backward compatible.

Do not modify application behavior.

Do not move existing source files.

Do not change build or CI/CD behavior.

---

### Repository Structure

Ensure the repository contains:

```text
/
├── AGENTS.md
├── docs/
├── .ai/
│   ├── prompts/
│   ├── standards/
│   ├── workflows/
│   ├── scratch/
│   ├── cache/
│   └── logs/
├── .work/
```

Create directories only if they do not already exist.

---

### Git Ignore

Update `.gitignore` without removing existing entries.

Ensure the following are ignored:

```text
.ai/scratch/
.ai/cache/
.ai/logs/
.work/
```

---

### Preserve Existing Documentation

If the repository already contains a `docs/` directory, preserve it.

Do not move or rewrite existing documentation unless necessary to improve organization.

---

### Explain the Difference Between `docs/` and `.ai`

Ensure repository documentation clearly explains this distinction.

`docs/` is the canonical documentation describing the software itself.

Examples include:

- architecture
    
- APIs
    
- coding standards
    
- deployment
    
- security
    
- operations
    
- ADRs
    

It answers:

> How does the software work?

`.ai/` is documentation for AI contributors.

It should contain:

- reusable prompts
    
- implementation workflows
    
- agent standards
    
- contributor guidance
    

It answers:

> How should an AI agent work in this repository?

`.ai/` should reference `docs/` rather than duplicate it.

---

### AGENTS.md

Create or update `AGENTS.md`.

Keep it concise.

It should:

- describe repository conventions
    
- direct agents to the appropriate documentation
    
- explain where temporary work belongs
    
- explain how permanent knowledge should be documented
    
- explain multi-agent collaboration
    

Avoid placing detailed project documentation inside `AGENTS.md`.

Use it as an entry point into the repository.

---

### Multi-Agent Collaboration

Document that:

- each agent should use its own directory beneath `.work`
    
- temporary files should never become dependencies
    
- permanent knowledge belongs in committed documentation
    
- implementation notes belong in temporary workspaces
    
- reusable prompts belong in `.ai/prompts`
    
- reusable workflows belong in `.ai/workflows`
    

---

### Documentation Philosophy

Document the following principle:

> If future developers or future AI agents will benefit from the information, commit it.

> If the information is only useful while solving the current task, place it in the temporary workspace.

---

### Quality Checks

Before finishing, verify:

- repository structure exists
    
- ignored directories are ignored
    
- documentation clearly distinguishes `docs` from `.ai`
    
- AGENTS.md is concise
    
- no temporary directories are referenced as project dependencies
    
- no existing project behavior changed
    

Finally, summarize every change you made.