A comprehensive AI agent workflow system with specialized roles, skills, and instructions for building complex software systems using AI-assisted development.
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.
- 🤖 Specialized Agent Roles: 8 workflow agents (Planner, Architect, Designer, DBA, Developer, Reviewer, Tester, Documenter) plus 5 council personas used by the pressure-test skill
- 📋 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 Code, OpenAI Codex, and Google Antigravity
All platforms share the same content via the sync script. .github/ is the single source of truth.
| Concept | Source of Truth | GitHub Copilot | OpenAI Codex | Google Antigravity | Claude Code |
|---|---|---|---|---|---|
| Auto-loaded rules | .github/instructions/ |
(native) | — | .agents/rules/ → + plugin rules/ → |
.claude/rules/ → |
| Slash commands | .github/prompts/ |
(native) | (via skills) | .agents/workflows/ → |
.claude/commands/ → + plugin commands/ → |
| Reusable skills | .github/skills/ |
(native) | plugin skills/ → |
plugin skills/ → |
plugin skills/ → |
| Agent personas | .github/agents/ |
(native) | — | — | .claude/agents/ → + plugin agents/ → |
| Orchestration | .github/copilot-instructions.md |
(native) | AGENTS.md → |
AGENTS.md → |
CLAUDE.md → |
| Standards | .github/CONTRIBUTING.md |
(native) | — | — | — |
| Plugin packaging | plugins/ai-toolkit/ |
.claude-plugin/plugin.json (CLI) |
.codex-plugin/plugin.json |
plugin.json |
.claude-plugin/plugin.json |
| Config | (platform-specific) | .vscode/settings.json |
.codex/config.toml |
.agents/mcp_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. "plugin" =plugins/ai-toolkit/— the single generated bundle that Claude Code, Codex, and Antigravity install via their own manifests. Skills are copied verbatim: SKILL.md is the cross-platform Agent Skills standard, consumed unmodified by all four platforms.AGENTS.md/CLAUDE.mdare thin committed pointers to.github/copilot-instructions.md. That orchestration file is the one thing a consuming repo copies rather than symlinks — it describes that repo's own layout and workflow, so each repo owns its copy outright.Outside the plugin, the repo-level outputs are
.claude/{rules,commands,agents}/and.agents/{rules,workflows}/. Two of them exist because plugins cannot carry them at all:.claude/rules/(Claude has no rules component) and.agents/workflows/(Antigravity has no workflows component). The rest —.claude/commands/,.claude/agents/,.agents/rules/— are project-scope twins of the plugin build, so a repo that vendors this one works with or without the plugin installed.
—cells: the platform has no native equivalent. Codex has no path-scoped rules (fold must-have rules intoAGENTS.mdor a nestedAGENTS.md) and no persona files (its subagents use TOML in.codex/agents/, not generated today). Skills double as explicit slash-style invocations ($skill-namein Codex,/skill-namein the Antigravity CLI and VS Code chat).Copilot needs no generated output at all: it reads the
.github/sources natively on every surface (Copilot code review reads skills only from.github/skills/, which is why.github/stays the source of truth).
The plugins/ai-toolkit/ folder carries a manifest for each platform's plugin system, so the same content installs everywhere:
# Claude Code (also delivers agent personas)
/plugin marketplace add cilerler/lillian
/plugin install ai-toolkit@cilerler
# OpenAI Codex (delivers skills)
codex plugin marketplace add cilerler/lillian
codex plugin install ai-toolkit
# Google Antigravity (also delivers rules)
git clone https://github.com/cilerler/lillian.git
agy plugin install ./lillian/plugins/ai-toolkitGitHub Copilot CLI plugins (public preview) resolve
.claude-plugin/plugin.jsonas a manifest location, so the Claude manifest doubles for Copilot CLI.Plugins deliver skills everywhere, plus commands and agents on Claude Code and rules on Antigravity. Claude Code path-scoped rules (
.claude/rules/), Copilot instructions, and Antigravity workflows cannot ride in a plugin.Installing is optional. Vendoring this repo (below) covers every assistant at project scope with nothing installed — the plugin is for using the toolkit in repos that don't vendor it, or for installing once across many.
This repository is designed as a shared AI instructions base. Add it into your repo, create the symlinks, then copy the two files your repo owns. There is no build step — every generated output is committed here and arrives with the checkout.
In the examples below,
.aiis the local directory you choose for the submodule or clone (e.g..ai,vendor/ai-templates).
Two setups. The choice is whether the wiring is committed, which is about contributors — not about whether the repository is public or private.
| Committed setup | Local-only setup | |
|---|---|---|
| Vendoring | git submodule | plain clone |
| Committed to your repo | .gitmodules, the .ai gitlink, all symlinks |
nothing |
.gitignore AI block |
must not be present — it would block the commit | required — it is what keeps them local |
| Contributors | get the wiring on clone | run the setup themselves |
| Pins a version | yes — the gitlink records a commit | no — .ai tracks itself |
| Use when | several people work in the repo | you work alone, or people should opt in |
Symlinks are committed and shared with all contributors.
Important
Do not add the AI Files ignore block — it belongs to the local-only setup, and the two are opposites. Here .ai/, CLAUDE.md, AGENTS.md, .claude/, .agents/ and the four .github/* symlinks are all supposed to be committed.
If your repo already carries that block (from a template, or from a previous local-only setup), remove it before running the command below. git submodule add refuses an ignored path outright — "The following path is ignored by one of your .gitignore files: .ai" — and even forced through with -f, every symlink you create afterwards would be silently unstageable.
Two entries are worth keeping either way, because they are per-developer rather than shared wiring:
CLAUDE.local.md
.mcp.jsongit submodule add -b main https://github.com/cilerler/lillian.git ".ai";Because the symlinks are committed, cloning the repository requires two additional steps. Document them in that repository's own README:
# 1. Fetch the submodule. A plain `git clone` leaves .ai/ empty and every symlink dangles.
git clone --recurse-submodules <your-repo>; # or, after cloning: git submodule update --init
# 2. Windows only — confirm symlinks materialise rather than checking out as text files.
git config --get core.symlinks; # must be trueGit only creates real symlinks on checkout when core.symlinks=true and the OS permits it (Developer Mode or an elevated shell). Otherwise each one lands as a small text file containing its target path, which every tool then reads as a malformed config rather than a missing one. On locked-down machines, have contributors use the local-clone setup below instead.
Pull updates:
git submodule update --remote ".ai";Nothing is committed. Each developer runs the setup themselves.
git clone https://github.com/cilerler/lillian.git ".ai";Then keep the vendored content out of git. Add this block to your .gitignore:
# =========================
# AI Files
# =========================
CLAUDE.local.md
CLAUDE.md
AGENTS.md
GEMINI.md
.mcp.json
.github/agents
.github/instructions
.github/prompts
.github/skills
.copilotignore
.claudeignore
.aiexclude
.geminiignore
.claude/
.agents/
.ai/Important
A trailing slash matches directories only. Git records a symlink as a file entry, even when it points at a directory — so .github/skills/ silently fails to match the symlink .github/skills, and it lands in your next commit.
That is why the list above is split:
- No trailing slash —
.github/agents,.github/instructions,.github/prompts,.github/skills, and the root.mdentries. These are symlinks. - Trailing slash kept —
.claude/,.agents/,.ai/. These are real directories; only their contents are linked.
.agent/ covers Antigravity's legacy folder name alongside the current .agents/.
Two entries are deliberately absent: .github/copilot-instructions.md and .github/CONTRIBUTING.md. Both are copies your repository owns and commits — see Copy the Repo-Owned Files.
Alternative: .git/info/exclude instead of .gitignore
Use this only when the repository must show no trace of the setup — a shared repo where teammates shouldn't see AI entries in a tracked file.
The cost is real: .git/info/exclude lives inside .git/, so it is per-clone and invisible. Re-clone the repository and it is gone, silently, and the next commit sweeps up every symlink.
# Idempotent: wrapped in a marker block so re-running replaces instead of duplicating.
$excludePath = ".\.git\info\exclude";
$block = @"
# >>> lillian >>>
# AI instructions base (managed block — safe to re-run)
CLAUDE.local.md
CLAUDE.md
AGENTS.md
GEMINI.md
.mcp.json
.github/agents
.github/instructions
.github/prompts
.github/skills
.copilotignore
.claudeignore
.aiexclude
.geminiignore
.claude/
.agents/
.agent/
.ai/
# <<< lillian <<<
"@;
$existing = if (Test-Path $excludePath) { Get-Content -Path $excludePath -Raw } else { "" };
$pattern = "(?ms)# >>> lillian >>>.*?# <<< lillian <<<\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 ..;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 SymbolicLinkwithCopy-Item -Recurseand re-copy after eachgit submodule update/git pullin.ai/.
Important
Targets must be relative, and each link must be created from the folder it will live in.
New-Item -ItemType SymbolicLink -Target resolves a relative target against your current directory, but Windows later resolves the stored target against the link's own directory. Create a link in .github\ while standing at the repo root and the two disagree — the link is written as .ai\..., then read as .github\.ai\..., and it dead-ends. That mismatch is why relative targets look broken; the Push-Location calls below remove it.
Do not use (Resolve-Path …).Path. It bakes an absolute machine-specific path (C:\Users\you\…) into the link. In a private-repo setup those links are committed, so every other clone — and your own repo after a rename or move — gets a target that resolves to nothing.
# Real directories — sub-symlinks go inside them
New-Item -ItemType Directory -Force -Path ".\.github";
New-Item -ItemType Directory -Force -Path ".\.claude";
New-Item -ItemType Directory -Force -Path ".\.agents";
# Root entry points
New-Item -ItemType SymbolicLink -Path ".\CLAUDE.md" -Target ".ai\CLAUDE.md";
New-Item -ItemType SymbolicLink -Path ".\AGENTS.md" -Target ".ai\AGENTS.md";
# .github — GitHub Copilot reads these natively
# Created from INSIDE .github, so targets climb out with `..\` first
Push-Location ".\.github";
New-Item -ItemType SymbolicLink -Path "skills" -Target "..\.ai\.github\skills";
New-Item -ItemType SymbolicLink -Path "agents" -Target "..\.ai\.github\agents";
New-Item -ItemType SymbolicLink -Path "instructions" -Target "..\.ai\.github\instructions";
New-Item -ItemType SymbolicLink -Path "prompts" -Target "..\.ai\.github\prompts";
Pop-Location;
# .claude — Claude Code project scope (works with no plugin installed)
Push-Location ".\.claude";
New-Item -ItemType SymbolicLink -Path "skills" -Target "..\.ai\.github\skills";
New-Item -ItemType SymbolicLink -Path "agents" -Target "..\.ai\.claude\agents";
New-Item -ItemType SymbolicLink -Path "rules" -Target "..\.ai\.claude\rules";
New-Item -ItemType SymbolicLink -Path "commands" -Target "..\.ai\.claude\commands";
Pop-Location;
# .agents — Codex AND Antigravity project scope (works with no plugin installed)
Push-Location ".\.agents";
New-Item -ItemType SymbolicLink -Path "skills" -Target "..\.ai\.github\skills";
New-Item -ItemType SymbolicLink -Path "workflows" -Target "..\.ai\.agents\workflows";
New-Item -ItemType SymbolicLink -Path "rules" -Target "..\.ai\.agents\rules";
Pop-Location;Note
.claude/ and .agents/ are real directories, not symlinks. Linking them wholesale would mean any file you create inside — .claude/settings.local.json, for instance — lands in your lillian checkout instead of your repo. Linking one level deeper keeps those directories yours. If you want lillian's permission defaults, copy .ai/.claude/settings.json in and edit from there; don't symlink it, you will want to diverge.
.agents/rules points at the plugin folder rather than .github/instructions because the sync script transforms instructions into Antigravity's rule format; the plugin copy is the usable one.
Note
.claude/commands and .claude/agents point at generated output, not at .github/ sources. The sync script emits two builds of each: the plugin one uses ${CLAUDE_PLUGIN_ROOT} paths, which resolve only under an installed plugin, while the .claude/ one uses repo-level paths that work at project scope. Linking the raw sources instead would register /code-review.prompt rather than /code-review and leave Copilot's mode: and tool names untranslated.
skills is the exception — it links straight to .github/skills, because skills are copied verbatim as the Agent Skills standard and need no transform at all.
Verify — every Target should be short and relative, with no drive letter anywhere:
Get-ChildItem -Recurse -Force | Where-Object LinkType | Select-Object FullName, Target;Git normalises the backslashes to forward slashes when it stores a symlink, so links created this way stay valid on macOS and Linux too.
Content reaches an assistant through two independent channels, and knowing which is which explains why the same skill appears in more than one place.
Channel 1 — the plugin, installed once per user. Not in your repo at all; it lives under the assistant's own plugin directory. This is what /plugin install ai-toolkit@cilerler sets up.
Channel 2 — project scope, read straight out of the repo. No install required. The symlinks above put lillian's content where each assistant already looks:
| Assistant | Project-scope paths | Still needs the plugin for |
|---|---|---|
| GitHub Copilot | .github/skills, .github/instructions, .github/prompts, .github/agents, .github/copilot-instructions.md |
nothing — reads .github/ natively |
| Claude Code | .claude/skills, .claude/rules, .claude/commands, .claude/agents, CLAUDE.md |
nothing |
| OpenAI Codex | .agents/skills (scanned from cwd up to repo root), AGENTS.md |
nothing |
| Google Antigravity | .agents/skills, .agents/rules, .agents/workflows, AGENTS.md |
nothing |
Project scope now covers every assistant. The plugin remains useful for installing across many repos at once, or for repos that don't vendor this one — but nothing requires it.
.agents/skills is shared: Codex and Antigravity both read it, so one symlink serves both. Codex follows symlinked skill folders when it scans.
Expect duplicates if you also install the plugin. Claude Code namespaces plugin skills as
/ai-toolkit:skill-nameand project skills as/skill-name, so each skill shows up twice under two names. Harmless — VS Code Copilot behaves the same way. Pick one channel if it bothers you; project scope is the one that needs no setup on a new machine.
The two channels update separately. They are different clones of this repository, so pulling one does nothing to the other and they drift silently:
git -C .ai pull; # refreshes project scope # in a Claude Code session: /plugin marketplace update cilerler # refreshes the installed pluginCompare
git -C .ai rev-parse --short HEADagainst the marketplace clone's HEAD. "I updated the toolkit but my skills didn't change" is almost always this. If you use project scope only, the second command is unnecessary.
Two files are copied, not symlinked — they belong to your repository, are committed with it, and are read by people as well as agents:
Copy-Item ".\.ai\.github\CONTRIBUTING.md" ".\.github\CONTRIBUTING.md";
Copy-Item ".\.ai\.github\copilot-instructions.md" ".\.github\copilot-instructions.md";They are then maintained differently, and both by hand — there is deliberately no hook:
| File | Yours to edit? | Updating it later |
|---|---|---|
CONTRIBUTING.md |
no — kept verbatim | re-copy with -Force |
copilot-instructions.md |
yes — you own it | never overwrite; diff and port what you want |
# see whether anything moved upstream before you touch either file
Compare-Object (Get-Content ".\.ai\.github\CONTRIBUTING.md") (Get-Content ".\.github\CONTRIBUTING.md");
git diff --no-index ".\.github\copilot-instructions.md" ".\.ai\.github\copilot-instructions.md";copilot-instructions.md is written to be portable — copy it in and nothing needs deleting. It carries no lillian-specific layout section; the "don't edit generated or vendored output" guardrail lives in .github/instructions/generated-output.instructions.md instead, path-scoped so it fires only when an agent touches those folders, and worded to be correct in either repository.
One thing may still need adjusting: the tasks/todo.md and tasks/lessons.md paths under Task Management and Self-Improvement Loop assume a tasks/ folder. Repoint or drop them if your repo has no such convention. Everything else — plan-mode defaults, verification rules, core principles — is portable as-is. From there the file is yours: add repo-specific orchestration as your project grows.
Why these are copies. Both describe your repository, not lillian. Symlinking them would impose lillian's layout and standards on every consumer with no way to state your own — and would leave contributors reading a
CONTRIBUTING.mdthat isn't in the repo they cloned. Skills, instructions, prompts and agents stay symlinked because they genuinely are shared.
Why no automation. A refresh hook would have to live inside
.ai/.git/hooks/, with vendor-specific scripts behind it sitting in your repository — the one category of file this setup keeps out. It would also overwrite a file your repository owns during an ordinarygit pull, discarding local edits with no prompt. The payoff would be a notification you already have: you control this content, so when it changes it is because you changed it.
Caution
This hook belongs to this repository only. Do not enable it in a repository that vendors this one: its paths assume the repo root is here, and it would rewrite generated output that is already committed and arrives with the checkout. See Setup Notes — consuming repos never run the sync.
Git does not use the hook until you point it at the committed hooks directory. This is per-clone local config — it lives in .git/config and is never committed — so run it once after cloning:
git config core.hooksPath tools/git/hooks;After that, any commit that changes an AI source file automatically runs tools/sync-ai-platforms.ps1, bumps the plugin's patch version (tools/bump-plugin-version.ps1), and stages the regenerated files and folders. Commits that don't touch .github/ sources are skipped, so it adds no overhead to unrelated work. Minor and major bumps stay manual.
- If your repo already has its own
CONTRIBUTING.mdorcopilot-instructions.md, keep yours and cherry-pick from lillian's rather than overwriting. - Do not create a
.codex/folder for skills. Codex reads project skills from.agents/skills, which the setup above already provides..codex/config.tomlis machine configuration, not shared content, and nothing here belongs there. - Do not run
tools/sync-ai-platforms.ps1. It is a contributor step for this repository. Everything it generates —plugins/ai-toolkit/,.claude/{rules,commands,agents}/,.agents/{rules,workflows}/— is committed and arrives with the clone. Running it from a consuming repo writes into.ai/, dirtying vendored content and setting up a conflict on the next pull there. - Do not edit anything under the symlinked paths. They resolve into
.ai/, so a change there modifies your vendored checkout rather than your repo: it never shows in your diff and is lost on the next update. Thegenerated-outputrule below enforces this for agents; the same applies to you.
.github/instructions/generated-output.instructions.md is the one instruction file that exists purely to protect this setup. It is path-scoped to .agents/**, .claude/**, plugins/** and .ai/**, so it costs no context until an agent actually touches one of those folders — then it tells the agent to stop and find the real source.
It is written to be correct in both directions, detecting which repository it is in by whether tools/sync-ai-platforms.ps1 exists at the root:
| Where | What it says |
|---|---|
| This repository | Those folders are build artifacts. Edit the .github/ source and let the hook regenerate. |
| A consuming repository | Those paths are symlinks into .ai/. Change shared behavior upstream; put repo-specific behavior in a real file outside them. |
It reaches Copilot natively, Claude Code through .claude/rules, and Antigravity through .agents/rules. Codex has no path-scoped rule mechanism, so it does not get this guardrail — fold it into AGENTS.md if that matters to you.
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();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.
| 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 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 |
Outside the workflow, five council personas (council-contrarian, council-expansionist, council-logician, council-researcher, council-buyer) serve the pressure-test skill — they are convened by that skill, not invoked directly.
- ✅ 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/workflow-<role>.agent.md - ✅ After 3 consecutive FAIL verdicts from Reviewer, escalate to user
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
│
├── plugins/ai-toolkit/ # GENERATED bundle + committed manifests — the single distribution unit
│ ├── .claude-plugin/plugin.json # Claude manifest (Copilot CLI reads it too)
│ ├── .codex-plugin/plugin.json # Codex manifest
│ ├── plugin.json # Antigravity manifest
│ ├── skills/ # ← .github/skills/ (verbatim — shared standard, all platforms)
│ ├── commands/ # ← .github/prompts/ (transformed; Claude)
│ ├── agents/ # ← .github/agents/ (transformed; Claude)
│ └── rules/ # ← .github/instructions/ (transformed; Antigravity)
│
├── .claude/ # repo-level Claude Code scope (no plugin needed)
│ ├── rules/ # ← .github/instructions/ (transformed) — GENERATED
│ ├── commands/ # ← .github/prompts/ (transformed) — GENERATED
│ ├── agents/ # ← .github/agents/ (transformed) — GENERATED
│ └── settings.json # permissions config (committed)
│
├── .agents/ # repo-level Codex + Antigravity scope (no plugin needed)
│ ├── rules/ # ← .github/instructions/ (transformed) — GENERATED
│ ├── workflows/ # ← .github/prompts/ (transformed) — GENERATED
│ └── plugins/marketplace.json # Codex plugin marketplace (committed)
│
├── .claude-plugin/marketplace.json # Claude plugin marketplace
│
├── tools/
│ ├── sync-ai-platforms.ps1 # generates plugins/, .claude/rules/, .agents/workflows/ from .github/
│ ├── bump-plugin-version.ps1 # patch-bumps the plugin version (run by the pre-commit hook)
│ └── git/ # opt-in pre-commit hook — runs sync + bump on commit
│ ├── hooks/pre-commit # shell shim → pre-commit.ps1
│ └── pre-commit.ps1 # gate + pointer: runs each generator, stages outputs
│
├── AGENTS.md # Codex & Antigravity entry point (pointer)
├── CLAUDE.md # Claude entry point (pointer)
└── LICENSE
The repository includes production-ready skills for engineering, documentation, and decision-making tasks. The list below is generated by the sync script from each skill's summary: frontmatter:
- documentation-generator: Document templates for ADRs, RFCs, design docs, runbooks, post incident reviews, SOPs, handovers, business cases, test plans, test cases, role briefs, and more.
- dotnet-service-generator: Interactive scaffolder for .NET service modules with observability and DI conventions.
- excalidraw-diagram-generator: Excalidraw diagram JSON files that make visual arguments, with automatic PNG rendering via a bundled renderer.
- infrastructure: Docker and Kubernetes patterns for .NET 10 services including health probes, resource limits, and graceful shutdown.
- mssql-bulk-data-operations: Generates production-ready batched T-SQL for large-scale UPDATE/DELETE on MSSQL, plus tracking-table staging, with progress tracking, checkpointing, and transaction safety.
- mssql-table-scaffolder: Scaffolds production-ready MSSQL tables or generates migration scripts following enterprise conventions.
- observability: Standard SLIs, dashboard templates, alert conventions, and OpenTelemetry patterns for .NET services.
- plantuml-sequence-diagram-generator: Generate professional PlantUML sequence diagrams with consistent styling, colors, and standardized interaction patterns.
- pressure-test: Adversarial 5-persona council that attacks an idea from every angle, then a Judge returns one GO / RESHAPE / KILL verdict with the cheapest 48-hour test to de-risk it. Optional anonymized peer-review round.
- session-handoff: Structured end-of-session summary so a fresh agent can continue seamlessly after the context is cleared. Chat-only output.
- solution-structure: Source of truth for the opinionated .NET solution folder structure (root scaffolding, /docs, /src/Modules/Component/Service hierarchy, /tools/Kubernetes, /tests) and the documentation placement rules that govern items inside it.
- storm-research: Multi-perspective, citation-verified HTML research briefing — five expert lenses, contradiction map, synthesized report, adversarial peer review with primary-source verification.
- work-item-generator: Interactive generator for work items (initiatives, epics, features, stories, bugs, spikes, enhancements, tasks) that gathers context through targeted questions and produces structured documents.
- workspace-productivity: Initializes folders and documents, syncs tasks, triages stale items, and maintains a two-tier memory system for decoding workplace shorthand.
See .github/skills/INDEX.md for detailed skill documentation.
- GitHub Copilot: Automatically reads
.github/copilot-instructions.md(andAGENTS.md) - Claude Code: Reads
CLAUDE.md, which points to the main instructions - OpenAI Codex: Reads
AGENTS.md, which points to the main instructions - Google Antigravity: Reads
AGENTS.md, which points to the main instructions
- Add this repository to your project (see Usage in Your Repositories)
- Review
.github/CONTRIBUTING.mdfor engineering standards - Customize agent roles in
.github/agents/as needed - Add project-specific skills to
.github/skills/ - Update technology instructions in
.github/instructions/for your stack
- Start with a request: Describe what you need to build
- Invoke Planner: Get a structured plan with acceptance criteria
- Invoke Architect: Receive technical design and architecture
- Invoke specialized agents: Designer for UI, DBA for database changes
- Invoke Developer: Implement the solution
- Invoke Reviewer: Get quality feedback and validation
- Invoke Tester (if needed): Add comprehensive test coverage
- Invoke Documenter (if needed): Produce documentation
| 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.
- 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
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/
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.