# 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, 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.

## 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.

### 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.