mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9aaa24d6a4
ai-docs/Agents.md
Matt Bruce 8833c282a3 docs: clarify reader doc placement
2026-02-10 15:35:37 -06:00

3.0 KiB
Raw Blame History

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.

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.

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

Example Request

"Read Agents.md and PRD.md first. Propose a plan. Then add chat mode guidance to docs/ai/usage-tokens.md (reader-facing) with hard examples. Do not add reader content to Agents.md."

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.