Skip to content

cilerler/melis

BranchesTags

Repository files navigation

AI Agent Templates

A comprehensive AI agent workflow system with specialized roles, skills, and instructions for building complex software systems using AI-assisted development.

Overview

This repository provides a structured framework for AI-assisted software development through specialized agent roles. It defines a workflow where different AI agents handle specific phases of development, from planning to implementation to documentation.

Features

  • 🤖 Specialized Agent Roles: 8 distinct agents (Planner, Architect, Designer, DBA, Developer, Reviewer, Tester, Documenter)
  • 📋 Structured Workflow: Clear transitions and responsibilities between agents
  • 🎯 Domain-Specific Skills: Reusable skills for common engineering tasks
  • 📚 Technology-Specific Instructions: Guidelines for Blazor, C#, SQL, Infrastructure, and Testing
  • 🔄 Multi-AI Support: Compatible with GitHub Copilot, Claude, and Gemini

AI Assistant Compatibility Matrix

All platforms share the same content via the sync script. .github/ is the single source of truth.

Concept Source of Truth GitHub Copilot Google Antigravity Claude Code
Auto-loaded rules .github/instructions/ (native) .agent/rules/ → .claude/rules/ →
Slash commands .github/prompts/ (native) .agent/prompts/ → .claude/commands/ →
Reusable skills .github/skills/ (native) .agent/skills/ → .claude/skills/ →
Agent personas .github/agents/ (native) — .claude/agents/ →
Orchestration .github/copilot-instructions.md (native) GEMINI.md → CLAUDE.md →
Standards .github/CONTRIBUTING.md (native) — —
Config (platform-specific) .vscode/settings.json .agent/config.json .claude/settings.json

→ = generated by sync script with platform-native frontmatter, filenames, and paths. Edit once in .github/, run the script, all platforms get the correct format.

— cells: these surfaces are not generated for Google Antigravity today — either because the platform has no native equivalent, or because the mapping hasn't been implemented in tools/sync-ai-platforms.ps1. If you need them for Antigravity, extend the sync script to emit the missing outputs.

Usage in Your Repositories

This repository is designed as a shared AI instructions base. Add it to your code repositories as a submodule (private) or local clone (public), then create symlinks and run the sync script.

In the examples below, .ai is the local directory you choose for the submodule or clone (e.g. .ai, vendor/ai-templates).

Private Repositories (Git Submodule)

Symlinks are committed and shared with all contributors.

git submodule add -b main https://github.com/cilerler/melis.git ".ai";

Pull updates:

git submodule update --remote ".ai";

Public Repositories (Local Clone)

Nothing is committed. Each developer runs the setup locally.

git clone https://github.com/cilerler/melis.git ".ai";

# Exclude from git tracking (local-only, never committed)
# Idempotent: wrapped in a marker block so re-running replaces instead of duplicating.
$excludePath = ".\.git\info\exclude";
$block = @"
# >>> melis >>>
# AI instructions base (managed block — safe to re-run)
.ai/
CLAUDE.md
AGENTS.md
GEMINI.md
.claude
.agent
.github/agents
.github/instructions
.github/skills
.github/prompts
.github/copilot-instructions.md
.github/CONTRIBUTING.md
# <<< melis <<<
"@;

$existing = if (Test-Path $excludePath) { Get-Content -Path $excludePath -Raw } else { "" };
$pattern  = "(?ms)# >>> melis >>>.*?# <<< melis <<<\s*";
if ($existing -match $pattern) {
    ($existing -replace $pattern, $block) | Set-Content -Path $excludePath -NoNewline;
} else {
    Add-Content -Path $excludePath -Value "`n$block";
}

Pull updates:

cd .ai; git pull; cd ..;

Create Symlinks

Run once after either setup above.

Windows symlink requirements: symlink creation needs one of:

  • An elevated PowerShell session (Run as Administrator), or
  • Developer Mode enabled (Windows 10/11: Settings → Privacy & security → For developers → Developer Mode On), which allows non-admin symlink creation.

On locked-down corporate machines where neither is available, replace New-Item -ItemType SymbolicLink with Copy-Item -Recurse and re-copy after each git submodule update / git pull in .ai/.

# Create required directories
New-Item -ItemType Directory -Force -Path ".\.github";

# Symlink root-level AI entry points
New-Item -ItemType SymbolicLink -Path ".\CLAUDE.md" -Target (Resolve-Path ".\.ai\CLAUDE.md").Path;
New-Item -ItemType SymbolicLink -Path ".\AGENTS.md" -Target (Resolve-Path ".\.ai\AGENTS.md").Path;
New-Item -ItemType SymbolicLink -Path ".\GEMINI.md" -Target (Resolve-Path ".\.ai\GEMINI.md").Path;

# Symlink .github content (GitHub Copilot reads these natively)
New-Item -ItemType SymbolicLink -Path ".\.github\skills" -Target (Resolve-Path ".\.ai\.github\skills").Path;
New-Item -ItemType SymbolicLink -Path ".\.github\agents" -Target (Resolve-Path ".\.ai\.github\agents").Path;
New-Item -ItemType SymbolicLink -Path ".\.github\instructions" -Target (Resolve-Path ".\.ai\.github\instructions").Path;
New-Item -ItemType SymbolicLink -Path ".\.github\prompts" -Target (Resolve-Path ".\.ai\.github\prompts").Path;
New-Item -ItemType SymbolicLink -Path ".\.github\copilot-instructions.md" -Target (Resolve-Path ".\.ai\.github\copilot-instructions.md").Path;
New-Item -ItemType SymbolicLink -Path ".\.github\CONTRIBUTING.md" -Target (Resolve-Path ".\.ai\.github\CONTRIBUTING.md").Path;

# Symlink platform directories (sync script generates content inside these)
New-Item -ItemType SymbolicLink -Path ".\.claude" -Target (Resolve-Path ".\.ai\.claude").Path;
New-Item -ItemType SymbolicLink -Path ".\.agent" -Target (Resolve-Path ".\.ai\.agent").Path;

Sync AI Platforms

Run once after setup, and again after pulling updates:

& ".\.ai\tools\sync-ai-platforms.ps1";

This generates platform-specific files inside .claude/ and .agent/ with transformed frontmatter, filenames, and paths. Since those directories are symlinked, the consumer repo sees them automatically.

Setup Notes

  • If your repo already has .github/CONTRIBUTING.md or .github/copilot-instructions.md, skip those symlinks and keep your project-specific files
  • .claude/settings.local.json is project-specific — copy and customize per project rather than syncing

Managing Symlinks

List all symlinks (recursively, including hidden items):

Get-ChildItem -Recurse -Force | Where-Object { $_.LinkType };

Remove a symlink (does not delete the target):

# File symlink
(Get-Item ".\CLAUDE.md").Delete();

# Directory symlink
(Get-Item ".\.claude").Delete();

Agent Workflow

The system follows a sequential workflow where each agent performs specific tasks and hands off to the next:

User Request → Planner → Architect → [Designer/DBA (optional)] →
[Documenter → RFC (optional)] → [Documenter → Design Doc (optional)] →
[Tester → Test Cases (contract for Developer, optional)] →
Developer → Reviewer →
[Tester → implements tests → Reviewer re-review (optional)] →
[Documenter → ADR(s) / runbook / SOP (optional)] → Complete

Where each document type fits:

Artifact Produced by Timing Purpose
RFC Documenter After Architect, before Developer Proposes the change; captures alternatives and trade-offs while the decision is still open
Design Doc (DD) Documenter (or Architect) After RFC approval, before Developer Details how to build it — components, APIs, data flow, edge cases
ADR(s) Documenter Anywhere a load-bearing decision is made — post-RFC, during DD, or post-implementation Crisp standalone record of one decision so it stays discoverable
Test Cases (TC) Tester After Planner/Architect, BEFORE Developer — updated during Reviewer iterations Enumerated, verifiable scenarios derived 1:1 from acceptance criteria; serves as the build contract so Developer knows what "done" means
Runbook / SOP Documenter (from Developer's draft) Post-implementation Operational procedures — living documents updated as the system evolves

Documenter runs at up to three distinct points:

  • Pre-implementation — proposal (after Architect): drafts RFC to capture the architectural decision.
  • Pre-implementation — design (after RFC approval): drafts the Design Doc spelling out the build plan.
  • Post-implementation — record (after Reviewer/Tester): produces ADRs, runbooks, SOPs, and README updates reflecting what was actually built.

Tester runs at two distinct points:

  • Pre-implementation — contract (after Planner/Architect, before Developer): drafts Test Cases mapped 1:1 to the Planner's acceptance criteria. Developer builds against them. Missing or ambiguous acceptance criteria surface here, when they're cheap to fix.
  • Post-implementation — verify (after Developer passes Reviewer): implements the Test Cases as executable unit/integration tests, iterates with Reviewer until green.

See .github/skills/documentation-generator/SKILL.md for the RFC/ADR/DD lifecycle, subset-selection rules, and anti-patterns.

Available Agents

Agent Purpose Output
Planner Analyzes requests and creates actionable plans Plan with acceptance criteria
Architect Designs system architecture and technical specifications Technical design, observability requirements
Designer Creates UI/UX mockups and component designs HTML/Tailwind mockups
DBA Designs database schemas and migration strategies Schema design, migrations, indexes
Developer Implements code, infrastructure, and observability Code, Docker, K8s, dashboards, runbooks
Reviewer Reviews implementation against standards PASS/FAIL verdict with feedback
Tester Creates test cases and implements tests Test cases, unit/integration tests
Documenter Produces technical documentation RFCs, ADRs, runbooks, SOPs

Workflow Rules

  • ✅ All agent transitions require explicit human approval
  • ✅ Each agent outputs and stops - user decides when to proceed
  • ✅ Agents must read their specific definition from .github/agents/<role>.agent.md
  • ✅ After 3 consecutive FAIL verdicts from Reviewer, escalate to user

Repository Structure

root/
├── .github/                         # SOURCE OF TRUTH — edit here
│   ├── agents/                      #   agent role definitions
│   ├── instructions/                #   technology-specific guidelines
│   ├── prompts/                     #   slash command definitions
│   ├── skills/                      #   reusable domain skills
│   ├── CONTRIBUTING.md              #   engineering standards (authoritative)
│   └── copilot-instructions.md      #   workflow orchestration
│
├── .claude/                         # GENERATED — do not edit directly
│   ├── agents/                      #   ← .github/agents/ (transformed)
│   ├── commands/                    #   ← .github/prompts/ (transformed)
│   ├── rules/                       #   ← .github/instructions/ (transformed)
│   ├── skills/                      #   ← .github/skills/ (copied)
│   └── settings.json                #   permissions config (committed)
│
├── .agent/                          # GENERATED — do not edit directly
│   ├── prompts/                     #   ← .github/prompts/ (transformed)
│   ├── rules/                       #   ← .github/instructions/ (transformed)
│   └── skills/                      #   ← .github/skills/ (copied)
│
├── tools/
│   └── sync-ai-platforms.ps1        # generates .claude/ and .agent/ from .github/
│
├── AGENTS.md                        # Gemini entry point
├── CLAUDE.md                        # Claude entry point
├── GEMINI.md                        # Gemini entry point
└── LICENSE

Available Skills

The repository includes production-ready skills for common engineering tasks:

  • documentation-generator: Templates for ADRs, RFCs, design docs, runbooks, postmortems, SOPs, and more
  • dotnet-service-generator: Scaffolds .NET service modules with observability and DI conventions
  • infrastructure: Docker and Kubernetes patterns for .NET services
  • mssql-table-scaffolder: Generates MSSQL tables or migration scripts following enterprise conventions
  • observability: SLIs, dashboard templates, alert conventions, and OpenTelemetry patterns
  • plantuml-sequence-diagram-generator: Generates professional PlantUML sequence diagrams

See .github/skills/INDEX.md for detailed skill documentation.

Getting Started

For AI Assistants

  1. GitHub Copilot: Automatically reads .github/copilot-instructions.md
  2. Claude: Reference CLAUDE.md which points to the main instructions
  3. Gemini: Reference GEMINI.md which points to the main instructions

For Developers

  1. Add this repository to your project (see Usage in Your Repositories)
  2. Review .github/CONTRIBUTING.md for engineering standards
  3. Customize agent roles in .github/agents/ as needed
  4. Add project-specific skills to .github/skills/
  5. Update technology instructions in .github/instructions/ for your stack

Using the Workflow

  1. Start with a request: Describe what you need to build
  2. Invoke Planner: Get a structured plan with acceptance criteria
  3. Invoke Architect: Receive technical design and architecture
  4. Invoke specialized agents: Designer for UI, DBA for database changes
  5. Invoke Developer: Implement the solution
  6. Invoke Reviewer: Get quality feedback and validation
  7. Invoke Tester (if needed): Add comprehensive test coverage
  8. Invoke Documenter (if needed): Produce documentation

Source of Truth

Document Purpose
.github/CONTRIBUTING.md Engineering standards (authoritative)
.github/skills/INDEX.md Skill routing and library references
.github/agents/*.agent.md Role definitions and behaviors

In case of conflict, .github/CONTRIBUTING.md takes precedence.

Key Principles

  • No automatic handoffs: Every agent transition requires human interaction
  • Output and stop: Agents complete their work and wait for user direction
  • Quality gates: Reviewer enforces standards at multiple checkpoints
  • Separation of concerns: Each agent has a single, well-defined responsibility
  • Observability first: Developer handles both code and operational concerns
  • Documentation as code: Technical documentation is version-controlled and reviewed

Contributing

This is a template repository. Fork it and customize for your organization's needs. Update:

  • Engineering standards in .github/CONTRIBUTING.md
  • Agent behaviors in .github/agents/
  • Technology-specific instructions in .github/instructions/
  • Skills library in .github/skills/

License

MIT License - see LICENSE for details.

Note: This repository provides the framework and templates. The actual agent behavior depends on the AI assistant being used and how it interprets the provided instructions.

About

AI agent workflows, custom skills, and coding standards template for bootstrapping Copilot-powered projects

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages