KomITi Engineering Handbook

1) Purpose and scope

This handbook is the single source of truth for how KomITi engineering work is organised — branches, worktrees, promotion path, deploy responsibility, and inter-agent communication. It binds every contributor, human or AI agent, who touches any KomITi repository.

The handbook does not teach Git or VS Code from zero — that is the job of tutorial 02: Git & VS Code Basics. It also does not document any single Odoo module, infrastructure stack, or product feature. Instead, it codifies the operating rules that all of those activities follow.

The handbook draws on three on-repo sources, each of which remains authoritative for its own scope:

• .github/copilot-instructions.md — global rules per repository (agent ownership, branch model, working-tree convention, Definition of Done).
• .github/instructions/INTER_AGENT_HANDOFF.instructions.md — the unified handoff block format.
• .github/skills/delivery-workflow/SKILL.md — the operational commands (branch creation, localhost runtime prep, promotion, deploy, smoke-test).

2) Repository topology and ownership

2.1) The four KomITi repositories

The KomITi engineering workspace contains four repositories, each with a distinct role:

2.2) Agent ownership and authority

Each repository has a designated owner agent. The owner is the only agent allowed to promote into staging or main, or to run deploy workflows on the corresponding environments.

2.3) Every repository needs a custom agent

KomITi prescribes that every repository that holds engineering work must have a custom agent declared in .github/agents/*.agent.md. The rationale:

• Clear ownership. The .agent.md file declares who may push where. When multiple agents share a multi-root workspace, each one knows its boundaries — no accidental cross-repo pushes or unauthorized promotions.
• Consistent team identity. Every agent speaks the same language (Serbian Cyrillic by default), follows the same commit discipline, and applies the same Definition of Done.
• Predictable handoffs. When @Academy finishes a tutorial edit, it hands off to @odoo4komiti instead of pushing 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 least privilege.

To be KomITi-compliant, every 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.

3) Branch model — feature → staging → main

3.1) The three permanent branches

Every KomITi repository follows the same three-branch model, taken from Vincent Driessen’s Git Flow (2010) and adapted to a single integration branch:

• main — the protected production branch. Reflects what runs in production. Direct commits are forbidden. Only the owner agent may merge here, and only via the promotion path.
• staging — the canonical integration branch. All feature branches are merged here first; staging is what the local runtime, the DEV server, and the smoke tests verify before anything reaches main.
• feature/… — short-lived working branches. One feature branch = one logical change. Created from the current origin/main, merged into staging, then promoted to main.

3.2) Feature branch naming rule

Feature branches use the rule:

YYYY-MM-DD-<agent-or-developer>-feature_name

• YYYY-MM-DD — today’s date (the date the branch was created from origin/main).
• <agent-or-developer> — agent slug (Academy, odoo4komiti, Etn, Designer) or human developer name (e.g. Marko, Sara).
• feature_name — short underscore-separated label for the change.

Examples:

• 2026-05-17-Academy-07_engineering_handbook — Academy agent authoring tutorial 07 on 17 May 2026.
• 2026-05-14-Sara-fix_login_css — developer Sara fixing the login CSS.
• 2026-05-15-Marko-add_invoicing_report — developer Marko adding a new invoicing report.

4) Worktree-per-Branch (WTPB) convention

On the real KomITi repositories (odoo4komiti, odoo4komiti4etn, komiti_academy) a feature branch is not started with git checkout -b inside the protected main worktree. Instead, each branch lives in its own folder on disk, side by side with main. The folder name equals the branch name exactly.

Why WTPB — two concrete benefits:

• The active branch is unambiguous from Windows Explorer alone. The folder name is the branch name — no need to run git branch --show-current to know what you are editing.
• Multiple agents or developers work in parallel without disturbing the protected worktrees. The main\ and staging\ folders are reserved for promotion, deploy, and reference builds; they must always sit cleanly on their respective branches. Side-by-side feature folders mean nobody has to git checkout in main\ or staging\ to look at someone else’s work.

The full hands-on walk-through — worktree commands, VS Code multi-root setup, what you should notice in Source Control and the Status Bar — lives in tutorial 02, section 4.6.4. This handbook only fixes the rule; the tutorial teaches the mechanics.

Worktree commands you will use most often:

PS C:\dev\KomITi\odoo4komiti\main> git fetch origin
PS C:\dev\KomITi\odoo4komiti\main> git worktree add -b 2026-05-14-Sara-fix_login_css C:\dev\KomITi\odoo4komiti\2026-05-14-Sara-fix_login_css origin/main
PS C:\dev\KomITi\odoo4komiti\main> git worktree list
PS C:\dev\KomITi\odoo4komiti\main> git worktree remove --force C:\dev\KomITi\odoo4komiti\2026-05-14-Sara-fix_login_css

5) Promotion workflow — owner-controlled

5.1) The promotion path

Every change reaches production along the same path:

1. Work in a feature branch + worktree — commit and push freely.
2. Verify the change locally at the appropriate level (file render, module install/upgrade, runtime smoke).
3. Send a handoff (section 6) to the owner agent.
4. Owner fetches the feature branch, reviews the diff, reruns the narrowest relevant validation.
5. Owner promotes feature → staging, deploys to DEV if applicable, smoke-tests.
6. Owner promotes staging → main, deploys to PROD if applicable, smoke-tests.
7. Owner confirms close-out (echoing the HANDOFF ID). Only then may the feature worktree and branch be cleaned up.

5.2) What a non-owner agent may and may not do

5.3) Pull requests vs handoff

Pull requests are optional review artifacts. They are useful when a human reviewer wants a GitHub-side diff with comments. They do not replace:

• the handoff block,
• the owner’s review of the diff in their own worktree,
• the owner’s control over when promotion actually happens,
• or the runtime verification on the target environment.

A merged PR does not mean “done”. Done is defined in section 10.

6) Inter-agent handoff protocol

Agents do not push to each other’s repos directly. They do not assume the other agent has context from a previous conversation. The only mechanism for cross-agent coordination is the unified HANDOFF block, relayed through the user.

6.1) The unified HANDOFF block

Every handoff between agents MUST use this single fenced block (one-click-copy):

HANDOFF ID: <from-agent>-YYYYMMDD-NN
FROM:      <agent or repo that produced the change>
TO:        <agent or repo that consumes it>
BRANCH:    <branch name>
COMMIT:    <short SHA or "uncommitted">
SOURCE:    <canonical source file or "no direct source">
FILES:     <list of changed files, one per line>
DELTA:     <1-2 sentence summary of what changed>
STYLING:   yes | no | n/a
ALIGN OK:  verified | not checked | n/a
ODOO CSS:  not needed | needed (<reason>) | n/a
ACTION:    <numbered list - every step the receiving side must execute>

Field notes:

• SOURCE — the canonical source file the change derives from, or no direct source if content was created in-session. For non-tutorial work use n/a.
• STYLING / ALIGN OK / ODOO CSS — tutorial QA fields. Set all three to n/a when the change is not an HTML tutorial.
• All other fields are always required.

6.2) HANDOFF ID rules

• Format: <from-agent>-YYYYMMDD-NN — e.g. komiti_academy-20260517-02.
• NN is a 2-digit counter for that sender on that date, starting at 01.
• Every new handoff gets a new HANDOFF ID. Revisions to the same work item create a new handoff with a new ID — never silently reuse an older ID for changed content.
• The receiver MUST echo the HANDOFF ID in status updates, verification notes, and close-out messages, so both sides can track exactly which handoff was executed.
• Do not use a bare counter like docs_agent-7; the date is mandatory.

6.3) ACTION field rules

ACTION must be a complete, ordered checklist — not a vague hint. Include every step required to close the loop:

1. Git operations — commit, push, submodule update, merge.
2. File sync — copy artifacts to their deploy-side location (e.g. custom-addons/komiti_web/static/tutorials/en/).
3. Runtime verification — restart containers, clear assets, confirm UI.
4. Promotion / deploy — if the change is ready for staging or prod, state the promotion path explicitly (e.g. merge to staging → merge to main → deploy prod).
5. Downstream notification — if another agent or repo is affected, state who and what they need to do.

If a step is not needed, omit it. Never write “deploy if needed” — either include the concrete deploy steps or leave them out.

7) komiti_academy submodule lifecycle

Tutorial HTML lives in two places, and the relationship between them is the most common source of confusion for new contributors:

• Active working copy — C:\dev\KomITi\komiti_academy\main (standalone clone of KomITidoo/komiti_academy). Academy agent edits here.
• Deployment-side reference — C:\dev\KomITi\odoo4komiti\staging\komiti_academy (Git submodule, pinned to a specific commit). The Odoo runtime reads through this.

The two are not magically in sync. After a push to KomITidoo/komiti_academy, the submodule needs an explicit update:

PS C:\dev\KomITi\odoo4komiti\staging> git submodule update --remote komiti_academy

End-to-end flow for an Academy tutorial change:

1. Academy edits in C:\dev\KomITi\komiti_academy\<feature-branch>\tutorials\.
2. Academy commits, pushes feature branch, merges into main, pushes main.
3. Academy sends HANDOFF block with commit SHA + file list to odoo4komiti agent.
4. odoo4komiti runs git submodule update --remote komiti_academy.
5. odoo4komiti copies the changed HTML file(s) into custom-addons/komiti_web/static/tutorials/en/.
6. odoo4komiti commits the submodule pointer + copied artifacts in odoo4komiti.
7. odoo4komiti promotes through staging → main, deploys, restarts Odoo, smoke-tests the tutorial in the browser.
8. odoo4komiti echoes the HANDOFF ID as close-out; only then does Academy clean up its feature worktree.

8) Code change discipline

8.1) One commit, one logical unit

• Fix the root cause, not the symptom. A patch that hides the symptom but leaves the underlying bug in place is not finished work.
• One commit = one logical unit. No unrelated changes piggy-backing on the same commit (no “while I was there I also reformatted X”).
• If a failed attempt needs retry, roll back the agent’s changes first. Restore the last known good state before trying again. Do not pile fixes on top of broken state.

8.2) Retry / rollback matrix

Rollback scope must match failure scope. Do not revert unrelated user changes when the failure was narrow.

9) Testing and rollout

• Functional test of the affected flow is mandatory before merge or deploy. “It builds” is not a test.
• Post-deploy smoke test is mandatory. A merged PR or a green CI run is not proof that the change works on the target environment.
• Merge does not equal deploy. Odoo runtime verification on the relevant environment (localhost, DEV server, or PROD server) is a separate step and is mandatory.

10) Definition of Done

A task is finished only when all of these are true:

1. Root cause is addressed, not just the symptom.
2. The affected flow has been locally verified at the appropriate level.
3. If there is a runtime effect, runtime state has been confirmed (module upgrade, container restart, assets cleared, health checks green, UI flow walked end-to-end).
4. Documentation has been updated in the relevant instruction file whenever the workflow or operational rules changed.
5. The final report includes outcome, delta, and next step.
6. No leftover agent artifacts in the workspace (stale worktrees, stale branches, temp files, half-applied patches).

11) Where the rules live

This handbook is the canonical narrative. The machine-readable rules live in the repositories themselves — that is what each agent loads at the start of every session. A KomITi repository organises them under .github/ as follows:

The table below summarises what each of these files contains. applyTo is the glob pattern that triggers automatic loading; on-demand files are loaded when their description matches the current task.

For terminology and per-command reference see tutorial 99: Cheat Sheet & Glossary. For the hands-on Git and VS Code mechanics that this handbook assumes, see tutorial 02: Git & VS Code Basics.