# Agents

## Purpose
This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable.

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

- Be specific and explicit. Avoid shorthand.
- Explain terms in plain language.
- Provide an example whenever possible.
- 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 and README 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.

### Example Request
"Read Agents.md and PRD.md first. Propose a plan, then update docs/ai/ios.md with step-by-step guidance and examples. If you add new files, update docs/ai/index.md."

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

1. Review skills.yaml for required skills.
2. Run ./scripts/sync-skills.sh to sync skills locally.
3. Restart your editor if needed.

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

## Example
Goal: Add a troubleshooting section to the AI docs.
Inputs: docs/ai/troubleshooting.md, docs/planning/AI-Docs-Plan.md
Output: Updated troubleshooting section with 5 common issues.
Verification: Manual review.