Governed Agent Methodology (GAM)

At KomITi we follow what we call Governed Agent Methodology (GAM) — where we prefer a native VS Code approach where rules are delivered to the AI agent automatically, through built-in agent customization (global instructions, glob-scoped instructions, on-demand skills).

A GAM-compliant workspace is built from four building blocks — foundational concepts (§1), custom agents (§2), instructions (§3), and skills (§4). The sections that follow cover each one, then dive into KomITi's concrete setup (§8).

1) What are Agents, LLM Models, and MCP Servers

Before building your own agents, you need to understand the three components that make AI-assisted development possible:

• LLM (Large Language Model) is the AI brain — a neural network trained on vast amounts of text and code that can understand natural language, generate code, reason about problems, and hold a conversation. Examples: OpenAI GPT, Anthropic Claude, Google Gemini.
  • How it thinks: an LLM does not look things up in a database and has no access to your files or ability to run commands — it only processes text in and text out. During training, it read billions of pages of text — documentation, source code, books, forums — and compressed the patterns into numerical weights. When you ask it a question, it predicts the most likely next words based on those patterns. It has no understanding in the human sense — it is sophisticated pattern matching. This is why it can write fluent code one moment and confidently state something incorrect the next. Treat it as a very fast, very well-read junior colleague who always needs verification.
  • Context window — the LLM's only memory: the model itself stores nothing. Every time you send a message, the agent re-sends the entire conversation history plus instructions plus file contents to the LLM from scratch — and all of it must fit into a fixed number of tokens (units of text, roughly ¾ of a word). When the context window fills up, the model starts losing earlier parts of the conversation. When you close the chat panel or start a new conversation, even that is gone — the model starts with a blank slate. The entire GAM architecture — scoped instructions, on-demand skills, concise .agent.md files — exists precisely for this reason: spend context window budget only on what is relevant to the current task.

    Note: you can see the context window in real time. In VS Code, open the Chat panel and click the token counter at the top — it shows a breakdown of what is consuming your budget:

    

    System Instructions (your copilot-instructions.md, scoped .instructions.md, active .agent.md) are loaded into every single prompt — the longer they are, the less room remains for messages, file contents, and tool results. This is why concise instructions are not a style preference but a direct context window trade-off.

• Agent is the orchestration layer that connects the LLM with tools and context. In VS Code, an agent receives your prompt, loads relevant instructions and skills into the LLM's context window, decides which tools to call (file search, terminal, MCP servers), interprets the results, and iterates until the task is done. A custom agent (.agent.md) adds identity, scope constraints, and guardrails on top of this loop.
• MCP Server (Model Context Protocol Server) is a bridge between the LLM and external systems. MCP is an open standard (created by Anthropic in 2024) that defines how an AI agent can call external tools — query a database, read a Jira ticket, trigger a CI pipeline, fetch live data from an API. Each MCP server exposes a set of tools (functions the agent can call) and resources (data the agent can read). Without MCP servers, the agent is limited to what VS Code provides natively — file reads, edits, terminal commands, and search.

1.1) How Agent, LLM, and MCP work together

GitHub Copilot is the agent runtime embedded in VS Code. When you open the Chat panel and switch to Agent mode, VS Code activates a loop that connects all three components:

1. You type a request in the VS Code Chat panel — e.g. "add a num_pages field to the Book model".
   Data stays local — nothing leaves your machine yet.
2. The agent (GitHub Copilot, running inside VS Code) packages your request together with automatically loaded instructions (copilot-instructions.md, scoped .instructions.md files, and any active .agent.md identity). This combined package is sent to the LLM.
   🌐 Leaves KomITi — your prompt text and all loaded instruction content travel through GitHub's API to the LLM provider's cloud (Anthropic, OpenAI, or Google, depending on the model you selected).
3. The LLM (e.g. Claude or GPT, running on a remote Anthropic or OpenAI server) reasons about the task. It does not touch your files directly — it returns a structured response telling the agent what to do next: "read file models/library_book.py".
   🌐 The LLM's response travels back from the provider's cloud through GitHub to your VS Code.
4. The agent executes the tool call — reads the file using VS Code's built-in file tool.
   Local — the agent reads the file from your disk. Nothing leaves your machine in this step.
5. The LLM sees the file content, decides what to change, and returns an edit instruction: "insert num_pages = fields.Integer(...) after line 12".
   🌐 Leaves KomITi — the file content from step 4 is sent to the LLM provider's cloud as part of the next reasoning call. The LLM's edit instruction returns the same way.
6. The agent applies the edit to the file on disk and shows you the diff.
   Local — the edit is written to your disk. Nothing leaves your machine.
7. If the task requires external data — say, checking a production database schema — the agent calls an MCP server instead of a built-in tool. The MCP server queries the database and returns the result to the LLM for the next reasoning step.
   The MCP call itself can be local (localhost DB) or within KomITi infra (AWS RDS). But the result the MCP server returns is then sent to the LLM provider's cloud 🌐 as part of the next reasoning call — same as step 5.

This agent → LLM → tool → LLM loop repeats until the task is complete. Every cycle consumes context window tokens, which is why efficient instructions and targeted skills matter.

1.2) How to connect VS Code with a GitHub Copilot agent

GitHub Copilot is the agent runtime built into VS Code. To set it up:

1. Install the extension: open VS Code → Extensions (Ctrl+Shift+X) → search for "GitHub Copilot" → install both GitHub Copilot and GitHub Copilot Chat.
2. Sign in: click the Copilot icon in the bottom-right status bar → sign in with your GitHub account. You need an active Copilot Individual, Copilot Business, or Copilot Enterprise subscription.
3. Choose a model: in the Chat panel, click the model selector dropdown (top of the chat input). Select the LLM you want — e.g. Claude Sonnet 4, GPT-4.1, or Claude Opus 4. Different models have different strengths; you can switch between them at any time.
4. Switch to Agent mode: in the Chat panel, change the mode selector from "Ask" to "Agent". In Agent mode, Copilot can read/write files, run terminal commands, and call MCP servers — not just answer questions.
5. Test it: type a request in the chat input — e.g. list all Python files in this project. The agent should use the file search tool and return results. If it works, your setup is complete.

2) Start with Custom agents

Custom agents are the capstone of GAM — they bring together instructions, skills, tool restrictions, and identity into a single file that gives the agent a name, scope, and personality.

2.1) What is a custom agent?

A custom agent is a .agent.md file placed in the .github/agents/ folder of your repository. It defines a named persona that you invoke by typing @AgentName in the VS Code chat. When invoked, the agent receives the full body of the .agent.md file as system-level context — on top of the global and scoped instructions that already load from the workspace.

Think of it this way: instructions define rules for the workspace; a custom agent defines who is working in that workspace. Two agents can share the same instructions but have different scopes, different tool access, and different ownership boundaries.

Real examples from KomITi:

• @odoo4komiti — the owner-agent for the odoo4komiti repo. It is the only agent allowed to push to staging and main, run deploys, and execute runbooks.
• @Academy — the content-agent for the komiti_academy repo. It owns tutorial HTML, follows the pedagogy skill, and hands off to @odoo4komiti for promotion and deploy.

2.2) How to create one

Creating a custom agent takes three steps:

1. Create the folder: .github/agents/ in your repository root (if it does not exist yet).
2. Create the file: .github/agents/YourAgent.agent.md. The filename (without extension) becomes the default agent name.
3. Write frontmatter + body:

---
name: MyAgent
description: "Short sentence — when to invoke this agent."
tools: [read, edit, search, todo, agent]
user-invocable: true
---

You are **MyAgent** — the designated agent for [scope].

## Identity
- Always identify yourself as `MyAgent`.
- Respond in Serbian Cyrillic by default.

## Scope
- What this agent works on.

## Constraints
- What rules it must follow.
- What it must NOT do.

The YAML frontmatter (between --- markers) has four fields:

The body (everything after the frontmatter) is free-form Markdown. VS Code injects the entire body as system-level context when the agent is invoked. Structure it with clear sections: Identity, Scope, Constraints, Approach — and any domain-specific reference material (file maps, conventions, terminology).

3) Define instructions

Think of instructions as a permanent briefing document the agent reads before it starts working. They replace the need to repeat the same rules in every prompt. Instructions are .md files — saved at a specific location and/or with a specific filename convention — that automatically load into the AI agent's context when it works in your workspace.

Instruction .md files, introduced with the .github/copilot-instructions.md convention in 2024, are a GitHub Copilot feature. Other tools have equivalents: Amazon Kiro uses .kiro/steering/ documents, Anthropic's Claude Code uses CLAUDE.md, Cursor uses .cursor/rules/, and Cline uses .clinerules.

There are two kinds:

3.1) Global instructions — copilot-instructions.md

Place a file at .github/copilot-instructions.md in the root of your repository. VS Code loads this file automatically in every conversation, regardless of which files the agent is working on.

Use it for rules that apply everywhere:

• Language preference (e.g. respond in Serbian Cyrillic).
• Git workflow (branch promotion, commit discipline).
• Definition of Done.
• Agent ownership (who may push to which branches).
• Navigation index (pointers to scoped files).

3.2) Scoped instructions — *.instructions.md

Any file ending with .instructions.md can contain a YAML frontmatter block with an applyTo glob pattern. VS Code loads this file only when the agent opens or edits files matching that pattern.

---
applyTo: "custom-addons/**"
---

# Odoo Development Discipline
- Module upgrade mandatory for every changed module.
- View inheritance must use stable inherit_id references.
...

3.3) How VS Code decides which instructions to load

4) Add skills as you grow

Skills are folders of instructions, scripts, and resources that the agent can load on demand. Unlike instructions (which are policy/constraints that load automatically), skills are step-by-step playbooks the agent reads when it recognizes a matching task. A skill folder can also contain scripts, templates, examples, and other assets alongside the main instruction file.

A skill is defined by a SKILL.md file inside a named folder — for example .github/skills/deploy-prod/SKILL.md. In VS Code (GitHub Copilot), project skills live in .github/skills/. Personal skills (not shared with the team) live in ~/.copilot/skills/. The SKILL.md file has a description in its frontmatter. The agent sees all skill descriptions in every conversation (~100 tokens each), but only reads the full skill body when the task matches.

Skills are also available as slash commands — type / in the chat input to see a list of available skills and invoke one directly (e.g. /deploy-prod).

Think of it this way:

• Instructions = "always follow these rules" (loaded automatically).
• Skills = "here is how to do X step by step" (loaded on demand, with bundled assets).

Example: a skill for creating VS Code customization files knows the exact YAML syntax, file naming conventions, and validation steps — but the agent only reads that procedure when you actually ask it to create or debug an instruction file.

A real example from this project: komiti_academy/.github/skills/pedagogy/SKILL.md is a pedagogy skill that defines how to write and review tutorial content — voice and tone, section structure, observation blocks, analogies, and numbering conventions. When you ask the agent to "review section 3 of tutorial 04", it matches the skill description, loads the full body, and applies those rules. When you ask it to fix a Terraform config, the skill stays unloaded.

Agent Skills are an open standard — they work across GitHub Copilot in VS Code, Copilot CLI, and the Copilot coding agent. Claude Code also supports SKILL.md files (stored in .claude/skills/). Amazon Kiro does not have an on-demand procedure equivalent; in Kiro, everything goes into the steering documents.

5) Global vs Scoped instructions vs Skills — when to use which

6) Guardrailing agents: two approaches

6.1) Always-on agent customization in VS Code

In the chapters above we covered custom agents, instructions (global and scoped) and skills — three of the most important customisation mechanisms. However, VS Code offers many other ways to shape how your AI agent behaves: prompt files, MCP servers, tool restrictions, and more. The following video gives you a broad overview of all available options:

6.2) On-demand agent customization with SDD

Another approach to agent customisation is Spec-Driven Development (SDD), an open-source methodology by GitHub (github/spec-kit, 83 k ⭐). SDD drives development through a structured pipeline: constitution → specify → plan → tasks → implement.

In this approach the agent reads its governing instructions only on demand, when the user explicitly invokes a slash command.

The table below compares our GAM mechanisms with their SDD equivalents:

7) Multi-root workspaces

In a multi-root workspace (covered in Git & VS Code Basics), Copilot loads .github/copilot-instructions.md from every repository folder in the workspace, not just the one you are editing.

Practical example: if your workspace contains odoo4komiti/ and komiti_academy/, the agent sees instructions from both repos simultaneously.

Scoped *.instructions.md files still activate by applyTo glob — but the glob is evaluated relative to the repo root, not the workspace root. This means an applyTo: "custom-addons/**" in odoo4komiti/ will only match files inside odoo4komiti/custom-addons/, never files in komiti_academy/.

Skills are also discovered across all repos: VS Code scans .github/skills/ in every repo folder. Skills have no applyTo — the agent sees all skill descriptions globally (like copilot-instructions.md), but only loads the full SKILL.md body on demand when the task matches the description.

8) Governed Agent Methodology (GAM) at KomITi

This section shows how GAM works in practice — the concrete instruction files, custom agents, and skills that the odoo4komiti repository uses. The repository has a three-level instruction hierarchy that mirrors the old CODEX file structure but now works natively with VS Code's automatic loading.

8.1) Visual overview — file tree

8.2) Every KomITi developer needs a custom agent

GAM prescribes that every developer must create a custom agent for each repository they own or actively develop in. The rationale:

• Clear ownership. The .agent.md file declares who may push where. When multiple agents exist in a multi-root workspace, each one knows its boundaries — no accidental cross-repo pushes or unauthorized promotions.
• Consistent team identity. Every team member's agent speaks the same language (Serbian Cyrillic), follows the same commit discipline, and applies the same Definition of Done.
• Predictable handoffs. When @Academy finishes a tutorial edit, it knows to hand off to @odoo4komiti — not to push directly to production. This boundary is documented in each agent's Constraints section.
• Tool safety. A content agent does not need terminal access. A deploy agent does not need notebook tools. The tools array enforces the principle of least privilege.

To be GAM-compliant, every KomITi custom agent must include at least these elements:

A minimal KomITi-compliant agent file looks like this:

---
name: MyProjectAgent
description: "Use for development work in the my-project repository."
tools: [read, edit, search, todo]
user-invocable: true
---

You are **MyProjectAgent** — the designated agent for the `my-project` repository.

## Identity
- Always identify yourself as `MyProjectAgent`.
- Respond in Serbian Cyrillic by default.
- You may push to feature branches only. Hand off to the
  repo owner for promotion to `staging` and `main`.

## Scope
- Python module development in `src/`.
- Unit tests in `tests/`.
- Documentation updates in `docs/`.

## Constraints
- Follow `.github/copilot-instructions.md` for all repo-level rules.
- One commit = one logical unit.
- Update the relevant instruction file when workflow rules change.
- Do not deploy — prepare a HANDOFF block instead.

8.3) .github/copilot-instructions.md — global rules

This file loads in every conversation. It is the single source of truth for company-level engineering policy. Contents:

8.4) odoo.instructions.md — Odoo development discipline

Scope: applyTo: "custom-addons/**" — loads whenever the agent works on any Odoo addon.

Key sections:

• Change type matrix — what verification is required for each type of change (docs-only, XML, JS, Python, DB restore, multi-module).
• Localhost vs remote runtime diff — a 5-step diagnostic order when behavior differs between environments.
• Post-change discipline — the exact sequence after model/view changes: pull → upgrade → restart → hard refresh → confirm.
• Readable URL — how to set ir.actions.act_window.path for human-friendly Odoo URLs.

8.5) terraform.instructions.md — Terraform / AWS discipline

Scope: applyTo: "infra/**" — loads whenever the agent touches infrastructure code.

Key sections:

• Policy — terraform plan before every apply; state and secrets never in git.
• DEV workflow — prerequisites (AWS CLI, Terraform install, SSO login), tfvars setup, init/validate/plan/apply sequence.
• PROD workflow — same structure but with the explicit rule: do not put DB/Odoo passwords in Terraform to avoid them ending up in tfstate.
• Inventory / scaling / pause-resume — PowerShell scripts for operational tasks.

8.6) komiti_timesheet.instructions.md — timesheet module

Scope: applyTo: "custom-addons/komiti_timesheet/**" — loads only when working on this specific addon.

Key sections:

• Purpose — From/To time entry, auto-calculated Hours, Timesheet Lock Date.
• File map — table of every file in the module and what it does.
• Design decisions — defensive logic (checks if line is "timesheet-like"), lock-date consistency through UI and server-side write path.
• Upgrade command — exact Docker Compose command to run.
• UI smoke test — 2-step manual verification procedure.

8.7) komiti_gantt.instructions.md — Gantt module

Scope: applyTo: "custom-addons/komiti_gantt/**" — loads only when working on this specific addon.

Key sections:

• Purpose — native Gantt view in Dispatching → Orders, bar resize, no 3rd-party dependency.
• File map — table covering Python models, OWL JS controller, QWeb templates, SCSS styles.
• Behavior rules — no hardcoded hiding of done/cancelled in JS; default search filter via action context.
• UI smoke test — 4-step verification (switcher, search bar, navigation, bar interactions).
• Cross-module alignment — when adding state colors, keep komiti_gantt.scss, dispatching styles, and search defaults in sync.

8.8) INTER_AGENT_HANDOFF.instructions.md — inter-agent communication

Scope: applyTo: "crewai_orchestration/**" + description (also loads on-demand when agent detects a handoff task).

Key sections:

• Handoff format — mandatory block format: FROM, TO, BRANCH, COMMIT, FILES, DELTA, ACTION.
• ACTION field rules — ACTION must be a complete, ordered checklist covering git ops, file sync, runtime verification, promotion/deploy, and downstream notification.
• Direction matrix — who hands off to whom and what the typical ACTION steps are (komiti_academy → odoo4komiti, odoo4komiti → komiti_academy, either → user).
• Rules — agents do not push to each other's repos; handoffs go through the user; receiving agent confirms each step.

99) Task on the komiti_academy project for the candidate

In this task you will set up your personal AI coding assistant so it can help you throughout the rest of the KomITi Academy tutorials. You will activate GitHub Copilot, create a custom Mentor agent, and configure it through the VS Code settings UI.

99.1) Activate GitHub Copilot

1. Open VS Code and click the Copilot icon (sparkle ✦) in the top-right area of the title bar, or press Ctrl+Shift+I.
2. If you do not see the icon, install the extension: go to Extensions (Ctrl+Shift+X), search for GitHub Copilot, and install it. It includes both Copilot and Copilot Chat.
3. Sign in with your GitHub account when prompted. If you do not have a Copilot subscription yet, GitHub offers a free tier — activate it at github.com/settings/copilot.
4. Verify: open the Copilot Chat panel (Ctrl+Shift+I) and type Hello. If Copilot responds, you are ready.

99.2) Create your Mentor agent

You will create a custom agent called Mentor in your komiti_library repository. This agent will be your personal tutor — whenever you get stuck while following a tutorial, you can ask @Mentor in the Copilot Chat panel and it will help you in context.

1. Create the agents folder in your komiti_library repo:

   PS C:\dev\komiti_library> mkdir .github\agents

2. Create the file .github/agents/Mentor.agent.md with the following content:

   ---
   name: Mentor
   description: "Personal tutor for KomITi Academy tutorials. Ask @Mentor when you are stuck."
   tools: [read, search, execute]
   ---
   
   You are **Mentor** — a patient, knowledgeable tutor for the KomITi Academy onboarding course.
   
   ## Identity
   
   - Always identify yourself as Mentor.
   - Respond in the candidate's native language and script.
   
   ## Scope
   
   - Answer questions about KomITi Academy tutorials.
   - Explain Odoo, Git, Docker, Terraform, and VS Code concepts covered in the tutorials.
   - Help debug errors the candidate encounters while following hands-on steps.
   - Point the candidate to the relevant tutorial section when the answer is already documented.
   
   ## Constraints
   
   - Do not write code for the candidate — guide them to write it themselves.
   - Do not skip steps. If the candidate asks to jump ahead, explain why the current step matters.
   - When the candidate makes a terminology mistake, correct it constructively so they learn.
   - Keep answers short: 1–3 paragraphs unless the candidate asks for more detail.

3. Verify: open the Copilot Chat panel, type @Mentor and press Enter. You should see the Mentor agent respond with its identity. Try asking: @Mentor What is a window action in Odoo?

99.3) Configure custom agent settings

VS Code has a dedicated settings page for customizing how Copilot agents behave globally across all your projects. Open it via the gear icon ⚙ in the Copilot Chat panel header → Configure Code Generation, or through File → Preferences → Settings and search for copilot.

Configure the following settings:

1. Response language — In the Copilot Chat settings, find github.copilot.chat.localeOverride and set it to the locale code of your native language (e.g. sr for Serbian, de for German, fr for French). This tells Copilot Chat to respond in your native language by default, regardless of the language you type in.
   Note: this setting affects Copilot Chat responses globally. It does not change the language of code, variable names, or comments — only the natural-language explanations and answers.
2. Instructions files discovery — Search for github.copilot.chat.codeGeneration.useInstructionFiles and make sure it is set to true (the default). This ensures Copilot reads your .github/copilot-instructions.md and *.instructions.md files automatically. If this is off, all the instruction files discussed in this tutorial would be ignored. Reference: 2) Define instructions.
3. Inline suggestions toggle — Search for github.copilot.enable and confirm it is enabled for the languages you work with (Python, XML, JavaScript, Markdown). Inline suggestions are the grey "ghost text" completions that appear as you type. They are separate from Chat — you want both active.

99.4) Self-check

Key concepts — explain in your own words:

• What is a custom agent and how does it differ from a plain Copilot Chat conversation?
• What is the difference between .agent.md, copilot-instructions.md, and *.instructions.md?
• What does the tools field in the agent frontmatter control?
• What is the purpose of localeOverride?

You must be able to answer:

• Where does the Mentor.agent.md file live in the repository file tree?
• How do you invoke the Mentor agent in the Copilot Chat panel?
• If you set useInstructionFiles to false, what happens to all the instruction files you create?
• After changing a VS Code Copilot setting, what must you do for it to take effect?