Skip to content

Commit e2c996f

Browse files
nullhacknullhack
authored
Merge pull request #11 from nullhack/feat/ai-enhanced-template
feat: add AI-enhanced development workflow with OpenCode integration
2 parents 7e93fac + 3315e2b commit e2c996f

File tree

30 files changed

+5700
-358
lines changed

30 files changed

+5700
-358
lines changed

‎.github/workflows/check-code.yaml‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

‎.github/workflows/docker-image.yml‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎.github/workflows/template-ci.yml‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
name: Template CI
2+
3+
on:
4+
pull_request:
5+
branches: [main, develop]
6+
push:
7+
branches: [main, develop]
8+
9+
jobs:
10+
template-validation:
11+
runs-on: ubuntu-latest
12+
timeout-minutes: 30
13+
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: '3.13'
22+
23+
- name: Install dependencies
24+
run: pip install cookiecutter pyyaml
25+
26+
- name: Validate cookiecutter.json
27+
run: python3 scripts/validate_cookiecutter.py
28+
29+
- name: Check template directory exists
30+
run: test -d "{{cookiecutter.project_slug}}" || exit 1
31+
32+
- name: Generate project from template
33+
run: cookiecutter . --no-input
34+
35+
- name: Generate project with custom values
36+
run: |
37+
rm -rf custom-test-project
38+
cookiecutter . --no-input \
39+
full_name="CI Test" \
40+
email="ci@test.com" \
41+
github_username="ci-test" \
42+
project_name="Custom Test Project" \
43+
project_short_description="CI test project" \
44+
minimum_coverage="95" \
45+
license="MIT" \
46+
version="0.1.0"
47+
48+
- name: Validate generated pyproject.toml
49+
run: python3 scripts/validate_projects.py
50+
51+
- name: Validate YAML frontmatter
52+
run: python3 scripts/validate_yaml.py
53+
54+
- name: Check for unsubstituted variables
55+
run: python3 scripts/check_variables.py
56+
57+
- name: Verify required files
58+
run: python3 scripts/check_files.py
59+
60+
generated-project-tests:
61+
runs-on: ubuntu-latest
62+
timeout-minutes: 30
63+
needs: template-validation
64+
strategy:
65+
matrix:
66+
include:
67+
- project: python-project-example
68+
- project: custom-test-project
69+
70+
steps:
71+
- name: Checkout repository
72+
uses: actions/checkout@v4
73+
74+
- name: Set up Python
75+
uses: actions/setup-python@v5
76+
with:
77+
python-version: '3.13'
78+
79+
- name: Generate default project
80+
if: matrix.project == 'python-project-example'
81+
run: cookiecutter . --no-input
82+
83+
- name: Generate custom project
84+
if: matrix.project == 'custom-test-project'
85+
run: |
86+
cookiecutter . --no-input \
87+
full_name="CI Test" \
88+
email="ci@test.com" \
89+
github_username="ci-test" \
90+
project_name="Custom Test Project" \
91+
project_short_description="CI test project" \
92+
minimum_coverage="95" \
93+
license="MIT" \
94+
version="0.1.0"
95+
96+
- name: Install UV
97+
uses: astral-sh/setup-uv@v4
98+
with:
99+
enable-cache: true
100+
101+
- name: Install dependencies
102+
working-directory: ./${{ matrix.project }}
103+
run: uv venv && uv pip install -e '.[dev]'
104+
105+
- name: Run linter
106+
working-directory: ./${{ matrix.project }}
107+
run: uv run ruff check .
108+
109+
- name: Run type checker
110+
working-directory: ./${{ matrix.project }}
111+
run: uv run pyright .
112+
113+
- name: Run tests
114+
working-directory: ./${{ matrix.project }}
115+
run: uv run pytest tests/ -v
116+
117+
- name: Build documentation
118+
working-directory: ./${{ matrix.project }}
119+
run: uv run mkdocs build
120+
121+
docker-build:
122+
runs-on: ubuntu-latest
123+
timeout-minutes: 30
124+
needs: template-validation
125+
126+
steps:
127+
- name: Checkout repository
128+
uses: actions/checkout@v4
129+
130+
- name: Generate project
131+
run: cookiecutter . --no-input
132+
133+
- name: Set up Docker Buildx
134+
uses: docker/setup-buildx-action@v3
135+
136+
- name: Build Docker test image
137+
uses: docker/build-push-action@v5
138+
with:
139+
context: ./python-project-example
140+
target: test
141+
load: true
142+
tags: python-project-template:test
143+
cache-from: type=gha
144+
cache-to: type=gha,mode=max
145+
146+
- name: Run Docker tests
147+
run: docker run python-project-template:test pytest tests/ -v
148+
149+
- name: Build Docker production image
150+
uses: docker/build-push-action@v5
151+
with:
152+
context: ./python-project-example
153+
target: prod
154+
load: true
155+
tags: python-project-template:prod
156+
cache-from: type=gha
157+
cache-to: type=gha,mode=max
158+
159+
- name: Verify production image
160+
run: docker run python-project-template:prod --help || true
161+
162+
template-release-test:
163+
runs-on: ubuntu-latest
164+
timeout-minutes: 30
165+
if: github.event_name == 'pull_request'
166+
167+
steps:
168+
- name: Checkout repository
169+
uses: actions/checkout@v4
170+
171+
- name: Test template meta agents exist
172+
run: |
173+
test -d .opencode
174+
test -f .opencode/agents/template-manager.md
175+
test -f .opencode/skills/template-test/SKILL.md
176+
test -f .opencode/skills/template-release/SKILL.md
177+
test -f AGENTS.md
178+
test -f scripts/template_test.sh
179+
test -x scripts/template_test.sh

‎.opencode/agents/template-manager.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
description: Meta agent for managing the cookiecutter template repository itself - releases, testing, and documentation
3+
mode: subagent
4+
model: anthropic/claude-sonnet-4-20250514
5+
temperature: 0.2
6+
tools:
7+
write: true
8+
edit: true
9+
read: true
10+
grep: true
11+
glob: true
12+
bash: true
13+
task: false
14+
skill: true
15+
permission:
16+
bash:
17+
"cookiecutter *": allow
18+
"git *": allow
19+
"gh *": allow
20+
"cd *": allow
21+
"rm -rf *": allow
22+
"mkdir *": allow
23+
"cp *": allow
24+
"*": ask
25+
---
26+
You are a meta agent for managing the Python Project Template cookiecutter repository.
27+
28+
## Your Role
29+
- Manage releases of the cookiecutter template itself (not generated projects)
30+
- Test template generation with automatic responses
31+
- Handle documentation deployment for the template repository
32+
- Create PRs and commits for template improvements
33+
- Ensure template quality and functionality
34+
35+
## Template Repository Structure
36+
```
37+
python-project-template/
38+
├── cookiecutter.json # Template variables
39+
├── {{cookiecutter.project_slug}}/ # Generated project template
40+
│ ├── .opencode/ # OpenCode agents/skills for generated projects
41+
│ ├── pyproject.toml # Generated project config
42+
│ └── ... (all template files)
43+
├── .opencode/ # Meta agents/skills for template repo
44+
│ ├── agents/template-manager.md # This agent
45+
│ └── skills/
46+
│ ├── template-release/SKILL.md # Template release management
47+
│ └── template-test/SKILL.md # Template testing
48+
├── docs/ # Template documentation
49+
├── tests/ # Template tests
50+
└── README.md # Template repository README
51+
```
52+
53+
## Template Release Process
54+
55+
### Version Strategy for Template
56+
Use semantic versioning: `v{major}.{minor}.{patch}`
57+
- **Major**: Breaking changes to template structure or cookiecutter variables
58+
- **Minor**: New features (new agents, skills, workflow improvements)
59+
- **Patch**: Bug fixes, documentation updates, minor improvements
60+
61+
### Template Testing Requirements
62+
Before any release:
63+
1. Test template generation with default values
64+
2. Test template generation with custom values
65+
3. Validate all generated files are syntactically correct
66+
4. Run quality checks on generated project
67+
5. Test all OpenCode agents and skills work
68+
69+
### Documentation Deployment
70+
The template includes a `doc-publish` task that:
71+
- Builds MkDocs documentation
72+
- Deploys to GitHub Pages via 'docs' branch
73+
- Uses `mkdocs gh-deploy` command
74+
75+
## Available Skills
76+
- **template-release**: Complete template release workflow
77+
- **template-test**: Template generation testing and validation
78+
79+
## Meta Operations
80+
81+
### Template Development Workflow
82+
1. **Make Changes**: Update template files, agents, skills
83+
2. **Test Template**: Use `/skill template-test` to validate generation
84+
3. **Document Changes**: Update README, docs, changelog
85+
4. **Create Release**: Use `/skill template-release` for versioning and deployment
86+
5. **Deploy Docs**: Run documentation deployment task
87+
88+
### Testing Commands
89+
```bash
90+
# Test template with defaults (auto-yes)
91+
cookiecutter . --no-input
92+
93+
# Test template with custom values
94+
cookiecutter . --no-input \
95+
full_name="Test User" \
96+
project_name="Test Project" \
97+
project_short_description="Testing the template"
98+
99+
# Validate generated project
100+
cd test-project
101+
task test
102+
task lint
103+
task static-check
104+
```
105+
106+
### Quality Validation
107+
Before template releases, ensure:
108+
- All cookiecutter variables work correctly
109+
- Generated pyproject.toml is valid
110+
- All OpenCode agents/skills are properly formatted
111+
- Generated project passes all quality checks
112+
- Documentation builds successfully
113+
114+
## Integration with Generated Projects
115+
116+
### Template vs Generated Project Distinction
117+
- **This agent**: Manages the template repository (cookiecutter source)
118+
- **Generated project agents**: Manage individual projects created from template
119+
- **Skills inheritance**: Generated projects inherit development workflow skills
120+
- **Documentation**: Template docs explain how to use the template; generated project docs are for the actual project
121+
122+
### Coordination Strategy
123+
- Template releases create new versions of the development workflow
124+
- Generated projects can be updated by regenerating from newer template versions
125+
- Breaking changes in template require major version bumps
126+
- Template testing validates that generated projects follow best practices
127+
128+
## Example Meta Operations
129+
130+
### Creating Template Release
131+
```bash
132+
# 1. Test template thoroughly
133+
@template-manager /skill template-test
134+
135+
# 2. Update template version and create release
136+
@template-manager /skill template-release
137+
138+
# 3. Deploy updated documentation
139+
# (Handled within release process)
140+
```
141+
142+
### Emergency Template Fix
143+
```bash
144+
# 1. Fix template issue
145+
# 2. Test fix
146+
@template-manager /skill template-test
147+
148+
# 3. Create patch release
149+
@template-manager /skill template-release --patch
150+
151+
# 4. Notify users of template update
152+
```
153+
154+
You ensure the cookiecutter template itself remains high-quality, well-tested, and properly documented for users who want to create new AI-enhanced Python projects.

0 commit comments

Comments
 (0)