Skip to content

Commit 363cc76

Browse files
2-Coatl2-Coatl
authored
Merge pull request #1 from 2-Coatl/copilot/update-copilot-instructions-md
Add copilot-instructions.md for AI agent onboarding
2 parents 536485a + c45f39c commit 363cc76

1 file changed

Lines changed: 229 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# Copilot Instructions for IACT Project
2+
3+
## Repository Overview
4+
5+
This is the IACT (Intelligent Autonomous Coding Toolkit) project repository. Currently in its initial stages, this repository serves as the foundation for building intelligent coding automation tools and workflows.
6+
7+
## Big Picture Architecture
8+
9+
### Current State
10+
The repository is in its early stages with a minimal structure:
11+
- **Repository Root**: Contains core documentation and configuration files
12+
- **Documentation**: README.md provides the project overview
13+
14+
### Architectural Vision
15+
As this project evolves, it is expected to follow these architectural principles:
16+
17+
1. **Modularity**: Components should be loosely coupled and highly cohesive
18+
2. **Extensibility**: New features and tools should be easy to add without modifying existing code
19+
3. **Automation-First**: All repetitive tasks should be automated where possible
20+
4. **Documentation-Driven**: Changes should be documented before or alongside implementation
21+
22+
## Project Structure
23+
24+
```
25+
IACT---project/
26+
├── .github/ # GitHub-specific configurations
27+
│ ├── copilot-instructions.md # This file - AI agent guidance
28+
│ ├── workflows/ # (Future) CI/CD workflows
29+
│ └── CODEOWNERS # (Future) Code ownership definitions
30+
├── README.md # Project documentation
31+
└── (Additional directories as project grows)
32+
```
33+
34+
### Expected Future Structure
35+
As the project develops, expect these directories:
36+
37+
- **src/** or **lib/**: Core application/library code
38+
- **tests/** or **test/**: Test suites
39+
- **docs/**: Detailed documentation
40+
- **scripts/**: Utility and automation scripts
41+
- **config/**: Configuration files
42+
- **examples/**: Usage examples and demonstrations
43+
44+
## Development Guidelines
45+
46+
### Code Organization
47+
- Keep related functionality together
48+
- Use clear, descriptive naming conventions
49+
- Maintain separation of concerns
50+
- Document complex logic with comments
51+
- Follow the DRY (Don't Repeat Yourself) principle
52+
53+
### File Naming Conventions
54+
- Use kebab-case for file names (e.g., `my-component.js`)
55+
- Use descriptive names that reflect the file's purpose
56+
- Group related files in appropriate directories
57+
58+
### Documentation Standards
59+
- Update README.md when adding new features or changing architecture
60+
- Add inline comments for complex algorithms or non-obvious code
61+
- Document all public APIs and interfaces
62+
- Keep documentation in sync with code changes
63+
64+
### Git Workflow
65+
- Use descriptive commit messages following conventional commits format
66+
- Create feature branches for new work
67+
- Keep commits atomic and focused
68+
- Write meaningful PR descriptions
69+
70+
### Testing Philosophy
71+
- Write tests for all new functionality
72+
- Aim for high test coverage, especially for critical paths
73+
- Use descriptive test names that explain what is being tested
74+
- Follow the Arrange-Act-Assert pattern in tests
75+
76+
## Key Patterns and Conventions
77+
78+
### When Adding New Features
79+
1. **Plan First**: Understand the requirement fully before coding
80+
2. **Start Small**: Begin with a minimal implementation
81+
3. **Test Early**: Write tests as you develop
82+
4. **Document**: Add relevant documentation
83+
5. **Review**: Self-review your changes before submitting
84+
85+
### When Refactoring
86+
1. **Understand Existing Code**: Read and comprehend before changing
87+
2. **Preserve Behavior**: Ensure refactoring doesn't change functionality
88+
3. **Test Coverage**: Ensure tests exist before refactoring
89+
4. **Incremental Changes**: Make small, reviewable changes
90+
5. **Verify**: Run all tests after refactoring
91+
92+
### When Fixing Bugs
93+
1. **Reproduce**: Understand and reproduce the bug first
94+
2. **Write Test**: Create a failing test that captures the bug
95+
3. **Fix**: Implement the minimal fix
96+
4. **Verify**: Ensure the test passes and no regressions occur
97+
5. **Document**: Add comments explaining the fix if non-obvious
98+
99+
## AI Agent Best Practices
100+
101+
### Understanding the Codebase
102+
- Always start by exploring the repository structure
103+
- Read README.md and any existing documentation first
104+
- Check for configuration files (package.json, requirements.txt, etc.)
105+
- Look for existing patterns in the codebase before implementing new features
106+
- Review recent commit history to understand development patterns
107+
108+
### Making Changes
109+
- **Minimal Changes**: Make the smallest possible changes to achieve the goal
110+
- **Consistency**: Follow existing code style and patterns
111+
- **Testing**: Run existing tests before and after changes
112+
- **Documentation**: Update docs when changing functionality
113+
- **Verification**: Manually verify changes work as expected
114+
115+
### Problem-Solving Approach
116+
1. **Analyze**: Understand the problem and its context
117+
2. **Research**: Check existing code for similar solutions
118+
3. **Plan**: Outline the approach before implementing
119+
4. **Implement**: Write clean, well-structured code
120+
5. **Test**: Verify the solution works correctly
121+
6. **Document**: Explain what was done and why
122+
123+
### Common Pitfalls to Avoid
124+
- Don't assume the project structure without exploring first
125+
- Don't add dependencies without checking existing ones
126+
- Don't remove or modify code you don't understand
127+
- Don't skip testing after making changes
128+
- Don't leave debug code or commented-out code in commits
129+
- Don't make unrelated changes in the same commit
130+
131+
### Security Considerations
132+
- Never commit secrets, API keys, or credentials
133+
- Validate all inputs
134+
- Follow security best practices for the technology stack
135+
- Keep dependencies up to date
136+
- Review security implications of changes
137+
138+
## Technology Stack
139+
140+
### Current
141+
- Git for version control
142+
- GitHub for repository hosting and collaboration
143+
- Markdown for documentation
144+
145+
### Future Considerations
146+
When adding new technologies:
147+
- Choose well-maintained, popular libraries
148+
- Consider the learning curve for contributors
149+
- Ensure compatibility with existing stack
150+
- Document setup and usage clearly
151+
- Add to this instructions file
152+
153+
## Communication and Collaboration
154+
155+
### For AI Agents
156+
- Be explicit about what you're doing and why
157+
- Report progress frequently
158+
- Ask for clarification when requirements are unclear
159+
- Provide context in commit messages and PR descriptions
160+
- Highlight any assumptions made during implementation
161+
162+
### Code Review Expectations
163+
- Explain the reasoning behind your approach
164+
- Highlight any trade-offs or limitations
165+
- Call out areas where you need feedback
166+
- Respond to review comments constructively
167+
- Be open to alternative solutions
168+
169+
## Maintenance and Evolution
170+
171+
### As the Project Grows
172+
This instructions file should be updated when:
173+
- New architectural patterns are introduced
174+
- Technology stack changes
175+
- New conventions are established
176+
- Common issues are identified
177+
- Best practices evolve
178+
179+
### Keeping This Document Useful
180+
- Keep it concise but comprehensive
181+
- Focus on what's unique to this project
182+
- Remove outdated information promptly
183+
- Organize information logically
184+
- Use examples where helpful
185+
186+
## Quick Reference
187+
188+
### First Time Setup
189+
```bash
190+
# Clone the repository
191+
git clone https://github.com/2-Coatl/IACT---project.git
192+
cd IACT---project
193+
194+
# (Future) Install dependencies
195+
# npm install or pip install -r requirements.txt or similar
196+
```
197+
198+
### Common Commands
199+
```bash
200+
# Check repository status
201+
git status
202+
203+
# Create a new branch
204+
git checkout -b feature/my-feature
205+
206+
# (Future) Run tests
207+
# npm test or pytest or similar
208+
209+
# (Future) Build the project
210+
# npm run build or make or similar
211+
```
212+
213+
## Resources
214+
215+
### Internal Documentation
216+
- README.md - Project overview and getting started
217+
- (Future) Architecture diagrams and detailed design docs
218+
219+
### External Resources
220+
- GitHub Docs: https://docs.github.com
221+
- Git Best Practices: https://git-scm.com/doc
222+
- Conventional Commits: https://www.conventionalcommits.org
223+
224+
---
225+
226+
**Last Updated**: 2025-10-27
227+
**Maintainers**: IACT Project Team
228+
229+
This document is a living guide - update it as the project evolves to keep it relevant and useful for all contributors, human and AI alike.

0 commit comments

Comments
 (0)