mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f2005386d8
ai-docs/Agents.md
Matt Bruce f2005386d8 docs: formalize contribution workflow
2026-02-10 15:06:18 -06:00

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