Skip to content

Commit c9ce827

Browse files
christopherpaquinchristopherpaquin
committed
Add initial AI standards, requirements, and GitHub templates
1 parent 7ccf2ed commit c9ce827

9 files changed

Lines changed: 399 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Bug Report
2+
description: Report a defect with repro steps and expected behavior
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: textarea
7+
id: summary
8+
attributes:
9+
label: Summary
10+
validations:
11+
required: true
12+
13+
- type: textarea
14+
id: repro
15+
attributes:
16+
label: Reproduction Steps
17+
placeholder: |
18+
1. ...
19+
2. ...
20+
3. ...
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: expected
26+
attributes:
27+
label: Expected Behavior
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: actual
33+
attributes:
34+
label: Actual Behavior
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: env
40+
attributes:
41+
label: Environment
42+
placeholder: |
43+
- OS:
44+
- Version/commit:
45+
- Python:
46+
- Shell:
47+
validations:
48+
required: true
49+

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Feature / Enhancement
2+
description: Propose new functionality with acceptance criteria
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: Problem Statement
10+
validations:
11+
required: true
12+
13+
- type: textarea
14+
id: outcome
15+
attributes:
16+
label: Desired Outcome
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: acceptance
22+
attributes:
23+
label: Acceptance Criteria
24+
placeholder: |
25+
- AC-1:
26+
- AC-2:
27+
validations:
28+
required: true
29+
30+
- type: textarea
31+
id: constraints
32+
attributes:
33+
label: Constraints / Environment
34+
validations:
35+
required: false
36+

‎.github/pull_request_template.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
## Summary
2+
What does this change do and why?
3+
4+
---
5+
6+
## Related Issues
7+
Closes #
8+
9+
---
10+
11+
## Requirements Coverage
12+
- [ ] Reviewed docs/requirements.md
13+
- [ ] No undocumented behavior introduced
14+
15+
### Acceptance Criteria
16+
- [ ] AC-1:
17+
- [ ] AC-2:
18+
- [ ] AC-3:
19+
20+
---
21+
22+
## Implementation Notes
23+
Design decisions, tradeoffs, and known limitations.
24+
25+
---
26+
27+
## Testing Evidence
28+
- [ ] pre-commit passed
29+
- [ ] CI passed
30+
- [ ] Manual validation performed (describe steps)
31+
32+
---
33+
34+
## Security and Safety
35+
- [ ] No secrets logged
36+
- [ ] Inputs validated
37+
- [ ] Idempotency verified
38+
39+
---
40+
41+
## Documentation
42+
- [ ] README updated
43+
- [ ] Runbook updated (if applicable)
44+

‎.github/workflows/ci.yml‎

Whitespace-only changes.

‎.pre-commit-config.yaml‎

Whitespace-only changes.

‎README.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,23 @@
1-
# ai-automation-template
2-
Template repo for AI-assisted Python/Bash automation with governance and CI.
1+
# AI Automation Template
2+
3+
This repository is a GitHub Template used to create
4+
AI-assisted automation projects with consistent standards.
5+
6+
## How to Use This Template
7+
1. Click **Use this template**
8+
2. Create a new repository
9+
3. Populate `docs/requirements.md`
10+
4. Use AI tools (Cursor, ChatGPT) anchored to `docs/ai/CONTEXT.md`
11+
12+
## Key Files
13+
- `docs/ai/CONTEXT.md` – AI behavior standards
14+
- `docs/requirements.md` – Behavioral contract
15+
- `.github/*` – Workflow and governance enforcement
16+
17+
## AI Usage Pattern
18+
Always instruct AI tools to:
19+
- Follow `docs/ai/CONTEXT.md`
20+
- Implement `docs/requirements.md`
21+
- Update documentation
22+
- Ensure CI passes
23+

‎bootstrap-template-structure.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
ROOT_DIR="."
5+
6+
# Directories to create
7+
DIRS=(
8+
"docs"
9+
"docs/ai"
10+
"docs/governance"
11+
".github"
12+
".github/workflows"
13+
".github/ISSUE_TEMPLATE"
14+
)
15+
16+
# Files to create (empty placeholders only)
17+
FILES=(
18+
"README.md"
19+
".pre-commit-config.yaml"
20+
"docs/ai/CONTEXT.md"
21+
"docs/requirements.md"
22+
".github/workflows/ci.yml"
23+
".github/pull_request_template.md"
24+
".github/ISSUE_TEMPLATE/feature_request.yml"
25+
".github/ISSUE_TEMPLATE/bug_report.yml"
26+
)
27+
28+
echo "==> Creating directory structure (no overwrite)"
29+
30+
for dir in "${DIRS[@]}"; do
31+
if [[ -d "${ROOT_DIR}/${dir}" ]]; then
32+
echo "SKIP dir exists: ${dir}"
33+
else
34+
mkdir -p "${ROOT_DIR}/${dir}"
35+
echo "CREATED dir: ${dir}"
36+
fi
37+
done
38+
39+
echo
40+
echo "==> Creating files if missing (no overwrite)"
41+
42+
for file in "${FILES[@]}"; do
43+
if [[ -f "${ROOT_DIR}/${file}" ]]; then
44+
echo "SKIP file exists: ${file}"
45+
else
46+
mkdir -p "$(dirname "${ROOT_DIR}/${file}")"
47+
touch "${ROOT_DIR}/${file}"
48+
echo "CREATED file: ${file}"
49+
fi
50+
done
51+
52+
echo
53+
echo "==> Bootstrap complete"
54+

‎docs/ai/CONTEXT.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# AI Engineering Context and Standards
2+
3+
This repository uses AI-assisted development.
4+
All AI tools (Cursor, ChatGPT, Copilot, etc.) must follow this document.
5+
6+
If behavior is not explicitly allowed here or in docs/requirements.md,
7+
it must not be implemented without clarification.
8+
9+
---
10+
11+
## 1. Design Principles
12+
- Correctness over cleverness
13+
- Explicit behavior over implicit assumptions
14+
- Idempotent and safe by default
15+
- Fail loudly, clearly, and early
16+
- Prefer boring, maintainable solutions
17+
- All code should be easily installed and uninstalled
18+
- Adhere to Security best practices
19+
- Adhere to SELinux best practices (semanage over chcon)
20+
21+
---
22+
23+
## 2. Supported Environments
24+
- Primary OS: RHEL 9 / RHEL 10
25+
- Secondary OS: Ubuntu 22.04 (best-effort)
26+
- Shell: bash
27+
- Python: 3.11+
28+
29+
Do not assume additional tools are installed unless explicitly documented.
30+
31+
---
32+
33+
## 3. Bash Standards
34+
- Use `#!/usr/bin/env bash`
35+
- Scripts must start with:
36+
- `set -euo pipefail`
37+
- Quote all variables
38+
- Never use `eval`
39+
- Validate all inputs early
40+
- Use functions; avoid large monolithic scripts
41+
- Use `trap` for cleanup when modifying system state
42+
43+
---
44+
45+
## 4. Python Standards
46+
- Prefer standard library
47+
- Use type hints for public functions
48+
- Avoid global mutable state
49+
- Use structured logging
50+
- External calls must have timeouts
51+
- Avoid `shell=True`
52+
- CLI tools must support `--help`
53+
54+
---
55+
56+
## 5. Idempotency and Safety
57+
- Scripts must be safe to re-run
58+
- Existing state must be detected, not overwritten blindly
59+
- Partial failures must be handled
60+
- Destructive actions must be explicit and documented
61+
- Provide `--dry-run` where reasonable
62+
63+
---
64+
65+
## 6. Security
66+
- Never log secrets
67+
- credentails and IP addresses should never be hardcoded into scripts, should exist in vars.txt file
68+
- vars.txt file should not be checked into any repo (.gitignore), however an example vars.txt should be created and checked in via git
69+
- Treat all inputs as untrusted
70+
- Document required permissions
71+
- Use least privilege
72+
- Sanitize file paths and user input
73+
74+
---
75+
76+
## 7. Logging and Exit Codes
77+
- Logs must be actionable and informative
78+
- Logs should exist in /var/log
79+
- Errors must explain what failed and why
80+
- Exit codes:
81+
- 0: success
82+
- 1: general failure
83+
- 2: invalid usage or input
84+
- 3: missing dependency
85+
86+
---
87+
88+
## 8. Documentation Requirements
89+
README must include:
90+
- Overview
91+
- Include "tested on" shields (from https://img.shields.io/)
92+
- Requirements / dependencies
93+
- Include high level architecture overview
94+
- Installation
95+
- Uninstall steps
96+
- Usage examples
97+
- Configuration
98+
- Troubleshooting
99+
- Security notes
100+
- License (Apache 2.0)
101+
102+
Operational tools must include docs/runbook.md.
103+
104+
---
105+
106+
## 9. Change Discipline
107+
- Do not invent requirements
108+
- If requirements are unclear, update docs/requirements.md first
109+
- Implementation must map to acceptance criteria
110+

0 commit comments

Comments
 (0)