# AI Template Tooling Reusable AI-assisted development framework for VS Code Copilot, Claude Code, Gemini CLI, and compatible agents. This repository contains universal instructions, agent skills, and documentation templates designed to enhance AI-assisted software development workflows. ![Its Dangerous Out There! screenshot](docs/imgs/image.png) --- ## Purpose Provides standardized, reusable AI development patterns: - **Security-first git workflows** with upstream push protection - **Architectural decision tracking** (ADR) - **Code quality and security validation** - **Emergency incident response procedures** - **Structured PR creation and reviews** - **Jira integration** — sync, write, and implement tickets end-to-end - **MCP server management** — install, configure, and repair tool servers --- ## Contents ### `.github/copilot-instructions.md` Universal guidelines for: - Git fork-based development - Security principles - Decision tracking system - Code quality standards - Communication standards for senior engineers - Skill chaining and concurrent invocation rules ### `AGENTS.md` / `GEMINI.md` Entry-point stubs for Claude Code and Gemini CLI agents. Both redirect to `.github/copilot-instructions.md` for full instructions. ### `.github/skills/` 22 specialized agent skills (auto-loaded by VS Code Copilot when context matches): | Skill | Purpose | | --- | --- | | **code-quality-check** | Validate code quality before PRs | | **compress-skills** | Compress skill/instruction files into symbolic DSL; backs up originals | | **decision-logging** | Create architectural decision records (ADR) | | **emergency-procedures** | Handle git emergencies and security incidents | | **git-fork-setup** | Configure fork-based workflow with upstream push protection | | **git-workflow** | Enforce safe git practices: feature branches, atomic commits, draft PRs | | **implement-ticket** | Interactively select and implement a Jira ticket end-to-end | | **jira-ticket-sync** | Fetch tickets assigned to the current user and sync to `.github/tickets/` | | **jira-ticket-writing** | Format and generate ticket Markdown files to the team standard | | **local-project-knowledge** | Persist/recall project knowledge, reasoning traces, and ADRs across sessions | | **mcp-setup** | Install, configure, and repair MCP servers (GitHub, Atlassian, Snowflake, Tavily, Playwright) | | **pre-commit-check** | Quick safety checklist before staging — catches `.env`, credentials, `os.environ` misuse | | **project-instructions-setup** | Create per-ticket or per-project instruction files | | **pull-request-creation** | Generate comprehensive draft PR descriptions | | **security-review** | Security checks before commits and pushes | | **snowflake-query** | Translate natural-language questions into Snowflake SQL and execute them | | **template-sync** | Deploy or sync the boilerplate to/from any target project folder | | **tf-ticket-implement** | Fetch a Jira ticket, discover Terraform repos, research patterns, and implement changes | | **ticket-workspace-prep** | Clone a repo and create a feature branch when starting a ticket | | **ui-guided-operator** | Drive a web UI headlessly via Playwright with staged user-confirmation flows | | **workspace-bootstrap** | Bootstrap a new workspace with the boilerplate, adapted to the actual stack | | **workspace-bulk-prep** | Bulk-clone all repos referenced by open tickets and create one branch per ticket | ### `.github/instructions/` Templates for project-specific context: - `example-ticket.instructions.md` — Annotated per-ticket documentation template - `ticket-template.instructions.md` — Blank per-ticket template ### `.github/rules/` Runtime agent directives: - `immediate.md` — Directives applied immediately on load - `README.md` — Rules index ### `.github/prompts/` Reusable prompt files: - `compress-instructions.prompt.md` — DSL compression prompt used by the `compress-skills` skill ### `.mcp/` MCP server configuration and local SQLite data store (used by `local-project-knowledge`). ### `.vscode/` VS Code workspace configuration: - `settings.json` — Instruction/skill locations, AI request limits - `mcp.json` — MCP server definitions - `AI-collab.code-workspace` — Multi-root workspace file ### `docs/` Reference documentation: - `DEVELOPMENT_WORKFLOW.md` — End-to-end development workflow guide - `python_style_pep8_pep257.md` — Python style conventions (PEP 8 / PEP 257) - `uv.md` — `uv` package manager usage guide --- ## Quick Start ### For New Projects 1. **Deploy the template:** ```bash # Ask Copilot: "Bootstrap this workspace with the AI template tooling" # Or run template-sync manually: cp -r /path/to/ai_template_tooling/.github your-project/ cp -r /path/to/ai_template_tooling/.vscode your-project/ cp -r /path/to/ai_template_tooling/docs your-project/ cp /path/to/ai_template_tooling/AGENTS.md your-project/ cp /path/to/ai_template_tooling/GEMINI.md your-project/ ``` 2. **Customize project-specific instructions:** - Copy `.github/instructions/ticket-template.instructions.md` - Rename to `.instructions.md` - Fill in project-specific details 3. **Verify VS Code detects skills:** - Open project in VS Code - Skills auto-load when relevant to your requests - Check `.vscode/settings.json` for skill location config ### For Per-Ticket Work 1. **Create ticket-specific instructions:** ```bash cp .github/instructions/ticket-template.instructions.md \ .github/instructions/.instructions.md ``` 2. **Document as you work:** - Repository configuration - Implementation details - Critical findings - Quick command references --- ## Git Safety Pattern Always configure upstream push protection after cloning: ```bash git remote rename origin upstream git remote add git@github.com:/.git git remote set-url --push upstream NO_PUSH # prevents accidental upstream pushes # Verify git remote -v # Expected: upstream NO_PUSH (push) ``` --- ## Skills Usage Skills activate automatically when VS Code Copilot detects matching context: | When You Say... | Skill Activated | | --- | --- | | "Set up fork remotes" | git-fork-setup | | "Document this decision" | decision-logging | | "Check for secrets" | security-review | | "Create a PR" | pull-request-creation | | "Validate code quality" | code-quality-check | | "I committed a secret" | emergency-procedures | | "Create ticket instructions" | project-instructions-setup | | "Implement a ticket" | implement-ticket | | "Sync my Jira tickets" | jira-ticket-sync | | "Query Snowflake" | snowflake-query | | "Bootstrap this workspace" | workspace-bootstrap | **Progressive Disclosure:** skills are discovered via YAML frontmatter `name`/`description`; full instructions load only when matched; additional resources load only if referenced. --- ## Communication Standards Optimized for senior engineers: - ✅ **Fullsome yet concise** — comprehensive, minimal verbosity - ✅ **Technical precision** — use domain terms (ADR, idempotent, atomic) - ✅ **Scannable format** — bullets, tables, status indicators - ✅ **Actionable outputs** — clear next steps always provided Status indicators: - ✅ Complete/Passed - ❌ Failed/Blocked - ⏳ In Progress/Pending - ⚠️ Warning/Non-blocking Issue --- ## File Structure ```text .github/ ├── copilot-instructions.md ├── instructions/ │ ├── example-ticket.instructions.md │ └── ticket-template.instructions.md ├── prompts/ │ └── compress-instructions.prompt.md ├── rules/ │ ├── README.md │ └── immediate.md └── skills/ ├── README.md ├── code-quality-check/ ├── compress-skills/ ├── decision-logging/ ├── emergency-procedures/ ├── git-fork-setup/ ├── git-workflow/ ├── implement-ticket/ ├── jira-ticket-sync/ ├── jira-ticket-writing/ ├── local-project-knowledge/ ├── mcp-setup/ ├── pre-commit-check/ ├── project-instructions-setup/ ├── pull-request-creation/ ├── security-review/ ├── snowflake-query/ ├── template-sync/ ├── tf-ticket-implement/ ├── ticket-workspace-prep/ ├── ui-guided-operator/ ├── workspace-bootstrap/ └── workspace-bulk-prep/ .mcp/ └── sqlite/ .vscode/ ├── AI-collab.code-workspace ├── mcp.json └── settings.json docs/ ├── DEVELOPMENT_WORKFLOW.md ├── python_style_pep8_pep257.md ├── uv.md └── imgs/ AGENTS.md # Claude Code / OpenCode entry point GEMINI.md # Gemini CLI entry point ``` --- ## Requirements - **VS Code** with GitHub Copilot - **Git** 2.x+ - **GitHub CLI** (`gh`) — optional, for PR creation - **MCP servers** — optional; see `.vscode/mcp.json` and the `mcp-setup` skill --- ## Best Practices ### Security 1. **Always** set `git remote set-url --push upstream NO_PUSH` 2. **Never** commit credentials, API keys, or secrets 3. **Use** `pre-commit-check` skill before every commit 4. **Verify** remote configuration before any push ### Documentation 1. **Log decisions** as they're made — use the `decision-logging` skill 2. **Create ticket instructions** at the start of work 3. **Update regularly** as discoveries are made 4. **Be specific** — include actual values, commands, links ### Code Quality 1. **Self-review** all changes before commit 2. **Run linters and tests** locally 3. **Security review** before any push 4. **Keep PRs focused** — < 400 lines preferred ### Team Collaboration 1. **Request explicit approval** before pushing 2. **Tag reviewers** with relevant expertise 3. **Communicate blockers** immediately 4. **Update tickets** with progress regularly --- ## Customization ### Adding New Skills 1. Create the skill directory: ```bash mkdir .github/skills/your-skill-name ``` 2. Create `SKILL.md` with YAML frontmatter (no backtick fences wrapping the file): ```markdown --- name: your-skill-name description: When to use this skill and what it does --- # Skill Instructions Your detailed instructions here... ``` 3. Register the skill in `.github/copilot-instructions.md` under `@SKILLS:` and the chain table. 4. Redeploy to consumer projects via the `template-sync` skill. ### Project-Specific Instructions Universal instructions (`.github/copilot-instructions.md`) should remain generic. Project-specific details go in: - `.github/instructions/.instructions.md` — Per-ticket context - `.github/instructions/.instructions.md` — Project-wide guidelines --- ## Examples ### Scenario 1: Starting a New Ticket ```bash cp .github/instructions/ticket-template.instructions.md \ .github/instructions/int-2614.instructions.md # Fill in: project context, repo config, implementation approach, findings ``` ### Scenario 2: Setting Up a Fork Ask Copilot: "Set up my fork with upstream protection" `git-fork-setup` skill activates and guides through: 1. Renaming origin → upstream 2. Adding your fork remote 3. Setting `NO_PUSH` on upstream 4. Verifying configuration ### Scenario 3: Pre-Commit Check Ask Copilot: "Check for security issues before I commit" `security-review` skill activates and validates: - ✅ No credentials/secrets - ✅ Linters pass - ✅ Tests pass - ✅ No hardcoded config --- ## Maintenance ### Keep Current - Update skills as new patterns emerge - Refine communication standards based on team feedback - Archive/remove obsolete patterns ### Share Improvements - Document lessons learned using the `decision-logging` skill - Update templates with better examples - Redeploy to consumer projects via `template-sync` --- ## License Internal use within organization. Adapt as needed for your team's workflows. --- ## Support Questions or improvements? Document in: - Decision log for architectural choices - README updates for process changes - Skill enhancements for new capabilities --- ## Related Repositories These repos live alongside this one in the [`theorchard/collab`](https://github.com/theorchard/collab) monorepo: - **[lvona/snowflake-mcp](https://github.com/theorchard/collab/tree/master/lvona/snowflake-mcp)** — Custom Snowflake MCP server used by the `snowflake-query` skill --- **Created:** February 10, 2026 **Updated:** April 8, 2026 **Purpose:** Standardized AI-assisted development framework