87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# 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/sync-skills.sh (uses the `npx skills` CLI).
|
|
3. Restart your editor if needed.
|
|
|
|
## Suggested Agent Request Template
|
|
- Goal: (one sentence)
|
|
- Inputs: (files, context, constraints)
|
|
- Output: (expected deliverable)
|
|
- Verification: (tests or checks)
|