# Agents

## Purpose
This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable.
It is internal guidance for the assistant, not reader-facing documentation.

## Audience And Tone Rules
Assume the reader is new to AI and needs detailed, step-by-step guidance.

- Read the PRD.md and README.md to understand this project.
- On the first response in a new chat, read this file and summarize the repo purpose in 1-2 sentences before proceeding.
- Be specific and explicit. Avoid shorthand.
- Explain terms in plain language.
- Provide an example whenever possible.
- Format chat or code examples consistently: use "Example prompt:" with a fenced ```text``` block for chat prompts, and "Example code:" with the right language for code.
- Prefer checklists, short steps, and concrete outcomes.
- Assume the reader is an expert engineer but a beginner at AI.

## Sync Expectation
Keep this file aligned with PRD, README, and docs/planning/AI-Docs-Plan.md when workflows, scope, or structure change.

## When to Use Agents
- Multi-step changes across files.
- Refactors with clear acceptance criteria.
- Audits or documentation updates.

## Common Agent Use Cases
- Create or expand documentation sections.
- Plan a refactor before making edits.
- Summarize and assess risks across files.

## How to Use Agents
1. Define the outcome in one sentence.
2. List inputs (files, context, constraints).
3. Ask for a plan, then approve before edits.
4. Ask for focused changes and verification steps.

## Contribution Workflow (Required)
When using AI to add or change docs in this repo:

1. Point the AI to this file and PRD.md first.
2. Ask for a short plan before edits.
3. Require explicit examples and step-by-step language in outputs.
4. Update the index when adding new markdown files.
5. Verify formatting (bullets, code blocks, and links) before commit.

## Doc Navigation Pattern (Required)
If you add, remove, or rename any file under docs/ai:

1. Update [docs/ai/index.md](docs/ai/index.md) with the new or removed entry.
2. Add or update the page breadcrumb ("You are here") on the page.
3. Add or update the page "Contents" block.
4. Add or update the "Next Steps" block so readers can navigate forward.
5. Verify all links still resolve.

### Example Checklist
- [ ] Index updated in docs/ai/index.md
- [ ] Breadcrumb updated on the page
- [ ] Contents block updated
- [ ] Next Steps block updated
- [ ] Links verified

## When A New Chat Starts
If you had to restart a chat and re-explain the goal, add a short reminder so the assistant places content in the reader-facing docs instead of workflow files.

Also, the first response in a new chat must confirm it read Agents.md and briefly state what this repo is about at a high level.

### What To Say (Plain English)
- "Treat this repo like a book for developers. Put reader-facing guidance in docs/ai, not in Agents.md."
- "If placement is unclear, ask where the content should live before editing."

## Commit And Push After Repo Updates
If you update any file in this repo, commit and push right away so other developers do not lose their local changes. If you are unsure, ask and confirm before pushing.

## Skills Sync
This repo uses a skills manifest to standardize skills across developers.

1. Review the curated list under assets/.
2. Run `./assets/setup.sh skills` (or `skills ios`, `skills android`).
3. Run `./assets/setup.sh agents` to install agents.
4. Run `./assets/setup.sh instructions` to install instructions.
5. Or run `./assets/setup.sh all ios` to install everything at once.
6. Restart your editor if needed.

## Suggested Agent Request Template
- Goal: (one sentence)
- Inputs: (files, context, constraints)
- Output: (expected deliverable)
- Verification: (tests or checks)