Skip to content

Commit c070992

Browse files
potatoqualiteepotatoqualitee
committed
Add AI agent instruction modules and guidelines
Introduces AGENTS.md and a comprehensive set of instruction files for AI agent workflows, coding standards, git and GitHub CLI usage, markdown formatting, testing, release management, and repository-specific conventions. These files provide structured guidance for AI agents and contributors working in the repository.
1 parent 1265716 commit c070992

13 files changed

+1846
-0
lines changed

‎AGENTS.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# AI Agent Instructions
2+
3+
AI agents working in this repository must follow these instructions.
4+
5+
Template Version: 0.6.0
6+
7+
Last sync: 2025-12-28 (Update this date when syncing from the centralized repository)
8+
9+
## Instructions for AI Agents
10+
11+
AI agents **must**:
12+
13+
1. **When deploying or updating this template, follow `instructions/update.instructions.md` and update the Last sync date above.**
14+
15+
2. **Read `instructions/agent-workflow.instructions.md` FIRST to determine which other instruction files apply to your task.** Follow all applicable instructions before proceeding with work.
16+
17+
## Instruction Applicability Matrix
18+
19+
Use this matrix to determine which instruction files to read based on your task:
20+
21+
| Task Type | Required Instructions |
22+
|-----------|----------------------|
23+
| Any task | `agent-workflow.instructions.md` |
24+
| Any code or documentation | `shorthand.instructions.md` |
25+
| Git operations | `git-workflow.instructions.md` |
26+
| Writing tests | `testing.instructions.md` |
27+
| PowerShell code | `powershell.instructions.md` |
28+
| Documentation | `markdown.instructions.md` |
29+
| README files | `readme.instructions.md` |
30+
| GitHub CLI usage | `github-cli.instructions.md` |
31+
| Creating releases | `releases.instructions.md` |
32+
| Repository-specific work | `repository-specific.instructions.md` |
33+
| Updating instructions | `update.instructions.md` |
34+
| Contributing to upstream | `contributing.instructions.md` |
35+
36+
## Available Instruction Files
37+
38+
- `agent-workflow.instructions.md` - Pre-flight protocol and task workflow
39+
- `shorthand.instructions.md` - Avoid shorthand and abbreviations
40+
- `git-workflow.instructions.md` - Git branching, commits, and PR conventions
41+
- `testing.instructions.md` - Test writing best practices
42+
- `powershell.instructions.md` - PowerShell coding standards
43+
- `markdown.instructions.md` - Markdown formatting standards
44+
- `readme.instructions.md` - README maintenance guidelines
45+
- `github-cli.instructions.md` - GitHub CLI usage guidelines
46+
- `releases.instructions.md` - Release management guidelines
47+
- `repository-specific.instructions.md` - Repository-specific customizations
48+
- `update.instructions.md` - Procedures for updating instructions
49+
- `contributing.instructions.md` - Contributing improvements to upstream
50+
51+
## Quick Reference
52+
53+
### Before Starting Any Task
54+
55+
1. Identify the task type from the matrix above
56+
2. Read all applicable instruction files
57+
3. Follow the guidelines when implementing
58+
59+
### Best Practices
60+
61+
- Follow existing patterns in the codebase
62+
- Keep solutions simple and focused
63+
- Only make changes that are directly requested
64+
- Follow language-specific guidelines
65+
66+
## Repository-Specific Instructions
67+
68+
See `instructions/repository-specific.instructions.md` for customizations specific to this repository.

‎instructions/agent-workflow.instructions.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
applyTo: '**/*'
3+
description: 'Mandatory pre-flight protocol for AI agents'
4+
---
5+
6+
# Agent Workflow Instructions
7+
8+
## Purpose
9+
10+
This file defines the recommended workflow that AI agents should follow when working in repositories using AIM. It ensures agents understand the context and guidelines before starting work.
11+
12+
## Pre-Flight Protocol
13+
14+
**Before starting any task, AI agents should:**
15+
16+
### 1. Identify Task Type
17+
18+
Analyze the user's request and identify all areas it touches. Common patterns:
19+
20+
- Code development (specific languages or frameworks)
21+
- Documentation (Markdown files, README files)
22+
- Git operations (commits, branches, PRs)
23+
- Testing and quality assurance
24+
- Security considerations
25+
- Repository-specific customizations
26+
27+
### 2. Consider Applicable Instructions
28+
29+
Review the instruction files listed in the repository's `AGENTS.md` to understand:
30+
31+
- Language-specific coding standards
32+
- Framework conventions
33+
- Documentation requirements
34+
- Git workflow expectations
35+
- Security best practices
36+
37+
### 3. Implement with Compliance
38+
39+
Execute your task following the guidelines from the applicable instruction sections.
40+
41+
## Best Practices
42+
43+
### Read Before Writing
44+
45+
- Always read existing code before modifying it
46+
- Understand the project's patterns and conventions
47+
- Check for existing implementations before creating new ones
48+
49+
### Confirm Understanding
50+
51+
When starting complex tasks, briefly confirm your understanding:
52+
53+
> "Based on the instructions, I'll follow [specific guidelines]. Here's my approach..."
54+
55+
This builds trust and catches misunderstandings early.
56+
57+
### Avoid Over-Engineering
58+
59+
- Only make changes that are directly requested
60+
- Keep solutions simple and focused
61+
- Don't add features, refactoring, or improvements beyond what was asked
62+
63+
### Security First
64+
65+
- Never introduce security vulnerabilities
66+
- Be careful with user input validation
67+
- Avoid hardcoding secrets or credentials
68+
- Follow the security guidelines in this document
69+
70+
## When in Doubt
71+
72+
1. **Ask for clarification** - Better to ask than implement incorrectly
73+
2. **Check existing code** - Follow established patterns in the codebase
74+
3. **Keep it simple** - The simplest solution that works is usually best
75+
76+
## Custom Instructions
77+
78+
If this repository has a custom instructions section, those guidelines take precedence for repository-specific conventions and may override or supplement the general instructions above.

‎instructions/contributing.instructions.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
applyTo: '**/*'
3+
description: 'Guidelines for contributing improvements back to the upstream AIM repository'
4+
---
5+
6+
# Contributing Instructions for AI Agents
7+
8+
When users want to improve, fix, or extend the AI agent instructions, this guide helps agents facilitate contributions back to the upstream AIM repository.
9+
10+
## When to Contribute Upstream vs. Modify Locally
11+
12+
### Contribute Upstream (Submit a PR)
13+
14+
- Fixing errors or typos in instruction files
15+
- Clarifying confusing or ambiguous instructions
16+
- Adding missing best practices that benefit all users
17+
- Creating new instruction modules for languages, frameworks, or tools
18+
- Improving examples or adding helpful code snippets
19+
20+
### Modify Locally Only
21+
22+
- Organization-specific conventions or standards
23+
- Project-specific customizations
24+
- Internal tooling or proprietary workflows
25+
- Content that references internal systems or URLs
26+
27+
**Local changes belong in `repository-specific.instructions.md`** - this file is never synced from upstream.
28+
29+
## Agent-Assisted Contribution Workflow
30+
31+
When a user wants to contribute to upstream, guide them through these steps:
32+
33+
### 1. Fork the Repository
34+
35+
```bash
36+
gh repo fork tablackburn/ai-agent-instruction-modules --clone
37+
cd ai-agent-instruction-modules
38+
```
39+
40+
### 2. Create a Feature Branch
41+
42+
```bash
43+
git checkout -b feature/descriptive-branch-name
44+
```
45+
46+
Use descriptive branch names:
47+
- `feature/add-python-module` - New module
48+
- `fix/powershell-typo` - Bug fix
49+
- `docs/clarify-update-procedure` - Documentation improvement
50+
51+
### 3. Make Changes
52+
53+
Follow existing patterns in the repository:
54+
55+
**For new instruction files:**
56+
- Place in `instructions/` folder
57+
- Use `.instructions.md` extension
58+
- Include required YAML frontmatter
59+
60+
**For existing files:**
61+
- Preserve the file's structure and style
62+
- Make minimal, focused changes
63+
- Don't introduce unrelated modifications
64+
65+
### 4. Validate Changes
66+
67+
```powershell
68+
Invoke-Pester -Path .\tests\
69+
```
70+
71+
Ensure all tests pass before committing.
72+
73+
### 5. Commit with Conventional Commits
74+
75+
```bash
76+
git commit -m "feat: Add Python type hints module"
77+
```
78+
79+
Prefixes:
80+
- `feat:` - New feature or module
81+
- `fix:` - Bug fix or correction
82+
- `docs:` - Documentation only
83+
- `refactor:` - Code restructuring without behavior change
84+
85+
### 6. Push and Create Pull Request
86+
87+
```bash
88+
git push origin feature/descriptive-branch-name
89+
gh pr create --title "feat: Add Python type hints module" --body "Description of changes"
90+
```
91+
92+
## Module Requirements
93+
94+
All instruction files must include YAML frontmatter:
95+
96+
```yaml
97+
---
98+
applyTo: '**/*.py'
99+
description: 'Brief description of what this module covers'
100+
---
101+
```
102+
103+
**Frontmatter fields:**
104+
- `applyTo` - Glob pattern for applicable files (e.g., `'**/*'`, `'**/*.py'`, `'**/README.md'`)
105+
- `description` - One-line description of the module's purpose
106+
107+
**Content guidelines:**
108+
- Keep instructions generic and universally applicable
109+
- Use placeholder examples (`<owner>`, `<repo>`, `example.com`)
110+
- Avoid organization-specific references
111+
- Include practical code examples where helpful
112+
- Follow markdown conventions from `markdown.instructions.md`
113+
114+
## Pull Request Guidelines
115+
116+
**Title:** Use conventional commit format (e.g., `feat: Add Python module`)
117+
118+
**Description should include:**
119+
- Summary of changes (1-3 bullet points)
120+
- Motivation or problem being solved
121+
- Any breaking changes or migration notes
122+
123+
**Example PR body:**
124+
125+
```markdown
126+
## Summary
127+
128+
- Add Python type hints and docstring guidelines
129+
- Include examples for common patterns
130+
- Reference PEP 484 and PEP 257 standards
131+
132+
## Motivation
133+
134+
Python developers need consistent guidance on type annotations and documentation strings.
135+
```
136+
137+
## After Submission
138+
139+
- Respond to review feedback promptly
140+
- Make requested changes in additional commits
141+
- Once merged, downstream repositories can sync using `update.instructions.md`
142+
143+
## Questions or Discussion
144+
145+
For questions about contributing, open an issue on the upstream repository:
146+
147+
```bash
148+
gh issue create --repo tablackburn/ai-agent-instruction-modules --title "Question: Your topic" --body "Your question here"
149+
```

0 commit comments

Comments
 (0)