| name | template-guide |
| description | Navigate template conventions, audit compliance, and guide upgrades for ai-project-template repos |
| category | project-management |
| tags | ["template","conventions","compliance","upgrade"] |
| version | 1.0.0 |
| template-version | 0.3.7-beta |
Template Guide
A skill for navigating ai-project-template conventions, auditing compliance, and guiding upgrades.
When to Use
Invoke this skill when:
- You are new to a project scaffolded from
ai-project-template
- You are reviewing a PR against a project using this template
- You need to check whether a project follows template conventions
- A user asks how to update their project to a newer template version
- You encounter a file you don't recognize and need to understand its purpose
Conventions Reference
Core Files
| File | Purpose | Key sections |
|---|
AGENTS.md | Project-level context for AI coding agents | Project Overview, Build & Run, Code Style, CI/CD, Agent Behavior |
README.md | Human-facing project documentation | Features, Quick Start, What's Included, Documentation |
CONTRIBUTING.md | Development guidelines | Commits, Branches, Changelog, Code Review |
CHANGELOG.md | Version history (Keep a Changelog format) | [Unreleased], [0.x.0] headers with Added/Changed/Fixed/Removed |
ARCHITECTURE.md | System design documentation | Components, data flow, dependencies |
UPGRADING.md | Re-sync guide for template upgrades | Version check, diff, merge, verify |
ADOPTING.md | First-time adoption guide for existing repos | Pre-flight audit, incremental adoption phases |
SETUP_GUIDE.md | Greenfield setup instructions | Required info, setup checklist, quality gates |
CI/CD Files
| File | Purpose | Trigger |
|---|
.github/workflows/ci.yml | Lint, typecheck, test | push + PR to main |
.github/workflows/commit-lint.yml | Enforces Conventional Commits | PR + push |
.github/workflows/changelog-check.yml | Requires CHANGELOG.md updates | PR only |
.github/workflows/blob-size-policy.yml | Rejects oversized files | PR only |
docs/ci.md | CI architecture guide | Reference |
Agent Configuration
| File/Directory | Purpose |
|---|
.omp/agents/ | Agent definitions (code-reviewer, adr-writer, changelog-updater) |
.omp/skills/ | Agent skills (e.g., template-guide) |
.omp/settings.json | OMP configuration |
.omp/rules/ | Agent rules |
.omp/hooks/ | Pre/post hooks |
.omp/tools/ | Agent tools |
Code Quality
| File | Purpose |
|---|
.architecture.yml | Code quality thresholds (max file lines, function lines, exports, nesting) |
.editorconfig | Editor settings |
docs/agent-files-guide.md | Guide for writing AGENTS.md, ARCHITECTURE.md, SKILL.md |
Compliance Checklist
Run .omp/skills/template-guide/scripts/audit.sh to check all items, or verify manually:
Required Files
CI Workflows
Versioning
Agent Configuration
Markdown Links
What "Passing" Looks Like
$ .omp/skills/template-guide/scripts/audit.sh
Checking AGENTS.md for placeholders... PASS: no placeholders found
Checking required files... PASS: all required files present
Checking CI workflows... PASS: all workflow files present
Checking .template-version... PASS: version matches known release (0.5.0)
Checking markdown internal links... PASS: all links resolve
What "Failing" Looks Like
$ .omp/skills/template-guide/scripts/audit.sh
Checking AGENTS.md for placeholders... FAIL: 3 placeholders remaining at lines 10, 14, 47
Checking .template-version... PASS: version matches known release (0.5.0)
Checking markdown internal links... FAIL: docs/ci.md links to missing ./docs/nonexistent.md
Run the audit after any significant change to confirm the project remains compliant.
Upgrade Procedure
When a user wants to update their project to a newer template version:
- Check current version: Read
.template-version in the project and compare against TheSmuks/ai-project-template's latest version
- Read the changelog: Show them the CHANGELOG.md entries between their version and the latest
- Diff the files: Identify which files changed and categorize by merge strategy (safe-to-copy, merge-carefully, never-overwrite)
- Walk through the merge: Guide them through UPGRADING.md's merge process
- Verify: Run
audit.sh after merging to confirm compliance
For the full upgrade guide, see UPGRADING.md.
Audit Script Usage
.omp/skills/template-guide/scripts/audit.sh
cd /path/to/project
/path/to/.omp/skills/template-guide/scripts/audit.sh
The script checks:
- No HTML comment placeholders in AGENTS.md
- Required files exist (CHANGELOG.md, CONTRIBUTING.md, AGENTS.md, README.md)
- CI workflow files present and not empty
.template-version exists and matches a known release
- Internal markdown links resolve (relative links in
.md files)
For AI Agents
When working in a project scaffolded from this template:
- Read
AGENTS.md first — it defines the conventions, commands, and project structure
- Before editing any file, read it fully — context determines correct changes
- Before renaming a symbol, find all references (
lsp references or grep)
- Every PR must go through CI:
commit-lint, changelog-check, blob-size-policy
- Always create PRs for changes — never push directly to
main
- Use the audit script to verify compliance after major changes