From 558c928e1d34d9bb302f0380375280e516fabfb0 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Tue, 14 Jul 2026 01:02:30 +0300 Subject: [PATCH 01/29] docs: start standard 1.3 with GUI testing rule --- AGENT_HANDOFF_STANDARD.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/AGENT_HANDOFF_STANDARD.md b/AGENT_HANDOFF_STANDARD.md index 9eea63e..d10b4ec 100644 --- a/AGENT_HANDOFF_STANDARD.md +++ b/AGENT_HANDOFF_STANDARD.md @@ -1,8 +1,8 @@ --- standard: Agent Handoff -version: "1.2" -status: active -updated: 2026-07-07 +version: "1.3" +status: draft +updated: 2026-07-14 --- # Agent Handoff Standard @@ -84,6 +84,14 @@ Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates. 11. Update PR description. 12. Leave a handoff when work is completed or interrupted. +## GUI testing + +Do not create brittle automated GUI tests that locate, interact with, or validate interface elements through absolute coordinates, screen position, pixel offsets, or incidental layout order. + +Position-dependent GUI checks must be performed manually or as supervised exploratory checks with Codex. They must not be committed as part of the routine automated test suite. + +Automated GUI tests should use stable semantic selectors such as roles, accessible names, labels, documented component identifiers, or dedicated test IDs. + ## Definition of Done - related Issue or PR is linked; From 16fea3127285fd5bca5608935ffe37132a00c8fb Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:21:39 +0300 Subject: [PATCH 02/29] docs: add containerization layout protocol --- ai/CONTAINERIZATION.md | 292 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 ai/CONTAINERIZATION.md diff --git a/ai/CONTAINERIZATION.md b/ai/CONTAINERIZATION.md new file mode 100644 index 0000000..c97ea0d --- /dev/null +++ b/ai/CONTAINERIZATION.md @@ -0,0 +1,292 @@ +--- +type: containerization_protocol +version: 1 +status: draft +updated: 2026-07-18 +project: Agent_Handoff +--- + +# Containerization Protocol + +## Purpose + +This protocol defines how Agent Handoff projects choose, document, change, and verify Docker and Docker Compose organization. + +Agent Handoff does not impose one universal container file layout. The layout is a project decision controlled by the user or maintainer. + +## Mandatory user decision gate + +This decision gate applies in both cases: + +1. initializing Agent Handoff in a new repository; +2. adding Agent Handoff to an existing repository. + +The agent MUST ask the user a separate, explicit containerization question before creating, moving, renaming, deleting, or consolidating Dockerfiles, Compose files, container scripts, build contexts, environment-file references, or container configuration. + +The agent MUST NOT infer approval from the presence or absence of existing Docker files, from general best practices, or from the recommended default in this document. + +### Required questions + +Ask the user to confirm: + +1. whether Docker or Docker Compose is used now or planned; +2. which supported layout should be used; +3. for an existing repository, whether the current layout must be preserved or may be migrated; +4. which development, test, and production entry commands are canonical; +5. whether production deployment configuration belongs in this repository or in a separate deployment repository. + +A concise question is acceptable, but the containerization decision must not be hidden inside a broader initialization or migration question. + +### When the user has not answered + +For a new repository, do not create container infrastructure and record the choice as unresolved. + +For an existing repository, preserve the current layout and do not relocate or consolidate container files. Non-container Agent Handoff files may still be added when that work is otherwise safe. + +## Supported approaches + +### 0. No repository-managed containerization + +Use this when Docker is not required or container execution is managed entirely outside the repository. + +Do not create placeholder Dockerfiles or Compose files without an approved use case. + +### 1. Colocated service files + +Store each Dockerfile next to the source code and keep the primary Compose entry point at the repository root. + +```text +repository/ +├── compose.yaml +├── compose.dev.yaml +├── service-a/ +│ ├── Dockerfile +│ └── src/ +└── service-b/ + ├── Dockerfile + └── src/ +``` + +Use this for small repositories and services whose image definition changes together with application dependencies and source layout. + +Strengths: + +- short and predictable build paths; +- Dockerfile ownership is close to service ownership; +- simple root-level Compose commands. + +Trade-off: + +- container-related files are distributed across service directories. + +### 2. Centralized `docker/` directory + +Store Compose files, Dockerfiles, container scripts, initialization assets, and shared configuration under `docker/`. + +```text +repository/ +├── application/ +│ └── src/ +├── docker/ +│ ├── compose.yaml +│ ├── compose.dev.yaml +│ ├── compose.prod.yaml +│ ├── application/ +│ │ └── Dockerfile +│ ├── postgres/ +│ │ └── init/ +│ └── scripts/ +└── .env.example +``` + +Use this when container infrastructure is substantial and centralized discoverability is more valuable than proximity to service code. + +Strengths: + +- one discoverable location for container infrastructure; +- a cleaner repository root; +- convenient for shared scripts and configuration. + +Trade-offs: + +- more relative paths; +- commands often require `-f docker/compose.yaml` or a wrapper command; +- a parent build context may expose more of the repository to the build than required. + +### 3. Hybrid layout + +Keep primary Compose entry points at the repository root, service Dockerfiles next to their source, and shared container infrastructure under `docker/`. + +```text +repository/ +├── compose.yaml +├── compose.dev.yaml +├── compose.prod.yaml +├── service-a/ +│ ├── Dockerfile +│ └── src/ +└── docker/ + ├── configs/ + ├── postgres/init/ + └── scripts/ +``` + +This is the recommended default to present to users for small and medium multi-service repositories. It MUST NOT be selected without user confirmation. + +Strengths: + +- simple root-level Compose commands; +- Dockerfiles remain close to service code; +- shared infrastructure has a dedicated location. + +Trade-off: + +- container infrastructure is intentionally split between the root, services, and `docker/`. + +### 4. Modular monorepo layout + +Keep Dockerfiles and optional service-level Compose modules inside each service, with a documented top-level orchestration entry point. + +```text +repository/ +├── compose.yaml +├── services/ +│ ├── api/ +│ │ ├── Dockerfile +│ │ └── compose.yaml +│ └── worker/ +│ ├── Dockerfile +│ └── compose.yaml +└── docker/ + └── shared/ +``` + +Use this when services have independent ownership, release cycles, or local development workflows. + +The repository must document whether top-level orchestration uses Compose `include`, multiple `-f` files, generated configuration, or another explicit mechanism. + +Strengths: + +- service autonomy; +- smaller service-specific contexts; +- easier ownership in a growing monorepo. + +Trade-offs: + +- orchestration and path resolution become more complex; +- duplicate configuration can appear without clear shared conventions. + +### 5. Separate deployment repository + +Keep application image definitions with application code while storing production deployment orchestration in a separate repository. + +Use this when application and operations ownership are separated, deployment configuration has a different release lifecycle, or production access boundaries require repository separation. + +The application repository must link to the deployment repository without copying secrets or environment-specific private values. + +Strengths: + +- clear application and deployment ownership boundaries; +- independent release and access controls. + +Trade-offs: + +- cross-repository coordination is required; +- a clone of one repository may not contain the complete production deployment state. + +### 6. Preserve an existing or custom layout + +An established repository may retain a layout not listed above. + +Preservation is preferred over unnecessary migration when the current structure is understandable, documented, and testable. + +A custom layout must document: + +- the reason for the layout; +- canonical entry commands; +- build contexts and Dockerfile locations; +- ownership of shared scripts and configuration; +- known path-resolution constraints. + +## Selection guidance + +| Project condition | Typical choice | +|---|---| +| Docker is not used | No repository-managed containerization | +| One or a few services | Colocated or hybrid | +| Substantial shared Docker infrastructure | Centralized or hybrid | +| Growing monorepo with service ownership | Modular monorepo | +| Separate application and operations ownership | Separate deployment repository | +| Mature existing repository | Preserve existing unless migration is explicitly approved | + +This table guides the user conversation. It does not authorize the agent to choose on the user's behalf. + +## Common requirements + +For every repository-managed containerization approach: + +- build contexts and Dockerfile paths must be explicit; +- build contexts should be no broader than required; +- each build context must have an appropriate `.dockerignore` or Dockerfile-specific ignore file; +- primary development, test, production, build, stop, and log commands must be documented when applicable; +- real secrets and production environment files must not be committed; +- `.env.example` or equivalent documentation should describe required non-secret variables; +- ports, volumes, networks, profiles, dependencies, and health checks must be understandable from repository documentation; +- generated Compose configuration should not become an undocumented source of truth; +- wrapper commands such as Make, Task, Just, or repository scripts may be used, but their underlying Compose files and order must remain discoverable. + +## Compose path and override rules + +The project must document: + +- the primary Compose file; +- the project directory used for relative paths; +- the order of multiple `-f` files; +- whether `include`, profiles, or overrides are used; +- the location and purpose of each `env_file`; +- the method used to provide variables for Compose interpolation; +- any paths that intentionally reference files outside the Compose directory. + +Agents must inspect these rules before changing relative paths, volumes, build contexts, or environment-file references. + +## Migration rules + +Migration between layouts requires explicit user approval. + +Before migration: + +1. inventory Dockerfiles, Compose files, ignore files, scripts, configuration, volumes, environment references, CI commands, and documentation; +2. identify consumers outside the repository, including deployment automation and developer scripts; +3. define the target layout and canonical commands; +4. keep the migration in a focused Issue, branch, and Pull Request; +5. avoid unrelated application refactoring in the same migration; +6. provide compatibility wrappers when removing them immediately would break documented workflows. + +## Verification + +When Docker or Compose configuration changes, run the applicable checks: + +1. render and validate the effective Compose model with `docker compose config`; +2. build the affected images or document why building was not possible; +3. start the affected services or run a focused container smoke test; +4. verify health checks, required ports, volumes, and service dependencies; +5. verify that ignored and secret files are not unintentionally included in build contexts or commits; +6. verify canonical commands from the documented repository entry point. + +If a check cannot be run, record the reason, risk, and next action in the Issue, Pull Request, or handoff. + +## Project memory + +Record the confirmed current layout and canonical commands in `ai/PROJECT_STATE.md`. + +Record a new layout choice or approved migration in `ai/DECISIONS.md` when it is a durable project decision. + +A handoff for container work should state: + +- selected layout; +- files and paths changed; +- commands run; +- effective Compose files and order; +- images or services tested; +- changed ports, volumes, networks, health checks, or environment variables; +- unresolved risks and rollback or compatibility notes. From 73f5da435c2228440093896bea6f92a7958c2131 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:22:14 +0300 Subject: [PATCH 03/29] docs: require explicit containerization decision during adoption --- AGENT_HANDOFF_STANDARD.md | 47 +++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/AGENT_HANDOFF_STANDARD.md b/AGENT_HANDOFF_STANDARD.md index d10b4ec..f9793a2 100644 --- a/AGENT_HANDOFF_STANDARD.md +++ b/AGENT_HANDOFF_STANDARD.md @@ -2,7 +2,7 @@ standard: Agent Handoff version: "1.3" status: draft -updated: 2026-07-14 +updated: 2026-07-18 --- # Agent Handoff Standard @@ -42,6 +42,8 @@ ai/handoffs/INDEX.md docs/en/ ``` +For projects that use or plan Docker or Docker Compose, `ai/CONTAINERIZATION.md` is also required. + ## Start order Before meaningful work, read: @@ -56,8 +58,9 @@ Before meaningful work, read: 8. `ai/TASK_REPORT_PROTOCOL.md` 9. `ai/PROJECT_STATE.md` 10. `ai/DECISIONS.md` -11. related GitHub Issue or Pull Request -12. relevant handoffs through `ai/handoffs/INDEX.md` +11. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, or being discussed +12. related GitHub Issue or Pull Request +13. relevant handoffs through `ai/handoffs/INDEX.md` ## Task result reports @@ -84,6 +87,39 @@ Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates. 11. Update PR description. 12. Leave a handoff when work is completed or interrupted. +## Repository initialization and adoption decision gate + +When Agent Handoff is initialized in a new repository or added to an existing repository, the agent MUST inspect the repository and ask the user a separate, explicit question about containerization before changing any Docker or Compose structure. + +The question must confirm: + +- whether Docker or Docker Compose is used now or planned; +- which container file layout the user wants; +- for an existing repository, whether the current layout must be preserved or may be migrated; +- whether production deployment configuration belongs in the same repository or a separate deployment repository. + +The agent MUST NOT infer this decision from existing files, an empty repository, general best practices, or the recommended default. + +Until the user answers, the agent must not create, move, rename, delete, or consolidate Dockerfiles, Compose files, build contexts, ignore files, container scripts, environment-file references, or container configuration. + +For an unanswered new-repository decision, create no container infrastructure. For an unanswered existing-repository decision, preserve the current layout. + +## Containerized project organization + +Agent Handoff supports these approaches: + +1. no repository-managed containerization; +2. Dockerfiles colocated with service code and primary Compose files at the root; +3. centralized Docker and Compose infrastructure under `docker/`; +4. a hybrid layout with root Compose files, service-local Dockerfiles, and shared infrastructure under `docker/`; +5. a modular monorepo layout with service-level container modules and explicit top-level orchestration; +6. a separate deployment repository for production orchestration; +7. preservation of an established or custom layout. + +The hybrid layout is the recommended option to present for many small and medium multi-service repositories, but it must never be selected without explicit user confirmation. + +The selected approach, canonical commands, build contexts, Compose file order, environment handling, and migration decision must be documented. Use `ai/CONTAINERIZATION.md` for the complete decision gate, layouts, migration rules, and verification requirements. + ## GUI testing Do not create brittle automated GUI tests that locate, interact with, or validate interface elements through absolute coordinates, screen position, pixel offsets, or incidental layout order. @@ -103,7 +139,10 @@ Automated GUI tests should use stable semantic selectors such as roles, accessib - PR description is updated; - risks are listed; - handoff exists for meaningful work; -- `ai/handoffs/INDEX.md` is updated when needed. +- `ai/handoffs/INDEX.md` is updated when needed; +- mandatory initialization or adoption questions were answered when relevant; +- container layout and canonical commands are recorded when Docker or Compose is used; +- changed Compose configuration was rendered and checked, or the reason and risk are documented. ## Final rule From f3b4a5413c8311deeabef8bb6f6c21d321a75d5e Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:22:37 +0300 Subject: [PATCH 04/29] docs: add containerization decision gate to handoff protocol --- ai/HANDOFF_PROTOCOL.md | 48 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/ai/HANDOFF_PROTOCOL.md b/ai/HANDOFF_PROTOCOL.md index c76b390..d85c5c7 100644 --- a/ai/HANDOFF_PROTOCOL.md +++ b/ai/HANDOFF_PROTOCOL.md @@ -2,7 +2,7 @@ type: handoff_protocol version: 1 status: active -updated: 2026-07-07 +updated: 2026-07-18 project: Agent_Handoff --- @@ -12,6 +12,8 @@ project: Agent_Handoff Read the required Agent Handoff files, the related Issue or PR, current branch, recent commits, and relevant handoffs. +Read `ai/CONTAINERIZATION.md` when Docker or Docker Compose is used, planned, present in the repository, or part of the requested work. + Choose `agent_name`, `agent_id`, and `run_id` before taking work. ## Work claim @@ -36,12 +38,53 @@ Use meaningful branch names without `/`, Issue numbers, or random identifiers by Open a Draft PR early. +## Initialization and adoption decision gate + +When initializing Agent Handoff in a new repository or adding it to an existing repository, ask the user a separate, explicit question about Docker and Compose organization. + +The user must confirm: + +- whether containerization is used or planned; +- which supported layout should be used; +- whether an existing layout must be preserved or may be migrated; +- whether production deployment configuration belongs in the same repository or a separate repository. + +Do not infer the answer from repository contents or choose the recommended layout automatically. + +Until the user answers, do not create, move, rename, delete, or consolidate Dockerfiles, Compose files, build contexts, ignore files, container scripts, environment-file references, or container configuration. + +For a new repository, leave containerization unresolved and create no container infrastructure. For an existing repository, preserve the current layout. + +## Docker and Compose + +Before changing container infrastructure: + +1. identify the user-confirmed layout in `ai/PROJECT_STATE.md` or the related Issue; +2. inspect the primary Compose file, project directory, override order, build contexts, Dockerfile paths, ignore files, environment references, scripts, and CI commands; +3. check whether production orchestration is stored in this repository or elsewhere; +4. keep layout migration separate from unrelated application refactoring; +5. validate the effective Compose model with `docker compose config` when Compose is used; +6. build and start the affected scope, or document why this was not possible; +7. record changed commands, paths, images, services, ports, volumes, networks, health checks, environment variables, risks, and compatibility notes. + +Migration between container layouts requires explicit user approval even when another approach appears cleaner. + +## GUI testing + +Do not commit automated GUI tests that depend on absolute coordinates, screen position, pixel offsets, or incidental layout order. + +Perform position-dependent GUI checks manually or as supervised exploratory checks with Codex. + +Automated GUI tests should use stable semantic selectors. + ## Smoke tests Run smoke tests before marking work ready or setting a handoff to `completed`. Current checks cover required files, YAML, PR template checklist, social preview size, and English-only active files. +For container changes, also run the applicable Compose rendering, image build, service startup, health, and focused smoke checks defined in `ai/CONTAINERIZATION.md`. + ## Done checklist - Related Issue or PR is linked. @@ -53,3 +96,6 @@ Current checks cover required files, YAML, PR template checklist, social preview - Risks are listed. - Handoff file is created when needed. - `ai/handoffs/INDEX.md` is updated when needed. +- Mandatory initialization or adoption questions were answered when relevant. +- User-confirmed container layout is recorded when Docker or Compose is used. +- Container migration has explicit user approval when applicable. From c341a7e983025c34496e3b7dc5c94e198826994d Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:22:48 +0300 Subject: [PATCH 05/29] docs: add containerization protocol to memory map --- ai/README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/ai/README.md b/ai/README.md index 084e920..539e90e 100644 --- a/ai/README.md +++ b/ai/README.md @@ -2,7 +2,7 @@ type: ai_readme version: 1 status: active -updated: 2026-07-07 +updated: 2026-07-18 project: Agent_Handoff --- @@ -23,10 +23,11 @@ It does not replace GitHub Issues, Pull Requests, checks, or Git history. 7. `ai/TASK_REPORT_PROTOCOL.md` 8. `ai/PROJECT_STATE.md` 9. `ai/DECISIONS.md` -10. related Issue or PR -11. `ai/REFACTORING.md` when relevant -12. `ai/handoffs/INDEX.md` -13. relevant handoff files only +10. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, present, or being discussed +11. related Issue or PR +12. `ai/REFACTORING.md` when relevant +13. `ai/handoffs/INDEX.md` +14. relevant handoff files only ## Files @@ -38,8 +39,11 @@ It does not replace GitHub Issues, Pull Requests, checks, or Git history. - `WORK_CLAIM_PROTOCOL.md` — work claim protocol. - `TASK_REPORT_PROTOCOL.md` — required result comments. - `REFACTORING.md` — refactoring workflow. +- `CONTAINERIZATION.md` — user-controlled Docker and Compose layout decisions, supported approaches, migration rules, and checks. - `handoffs/INDEX.md` — handoff index. ## Rules Keep files compact. + +Do not choose or migrate a container layout without explicit user confirmation during new-repository initialization or existing-repository adoption. From b83250eda3c90fb83d4ff555ec20479fe46524cf Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:23:09 +0300 Subject: [PATCH 06/29] docs: require separate containerization question in adoption prompts --- docs/en/README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/en/README.md b/docs/en/README.md index ec5e1f1..8b3d91d 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -17,6 +17,7 @@ This page is the documentation index for Agent Handoff. - [Project state](../../ai/PROJECT_STATE.md) - [Decisions](../../ai/DECISIONS.md) - [Refactoring workflow](../../ai/REFACTORING.md) +- [Containerization protocol](../../ai/CONTAINERIZATION.md) - [FAQ](FAQ_EN.md) - [Examples](../../examples/README.md) - [Promotion checklist](PROMOTION_CHECKLIST_EN.md) @@ -28,6 +29,12 @@ This page is the documentation index for Agent Handoff. - [Promotion changelog appendix](../CHANGELOG_PROMOTION_APPENDIX.md) - [Repository discovery settings](REPOSITORY_SETTINGS_EN.md) +## Mandatory containerization question + +For both a new repository and an existing repository, the coding agent must ask a separate, explicit question about Docker and Docker Compose organization before changing any container files or paths. + +The agent must not choose the recommended layout automatically. Read `ai/CONTAINERIZATION.md` for the supported choices and decision rules. + ## Scenario 1: new repository ```text @@ -36,6 +43,11 @@ Use the latest standard from https://github.com/artyomboyko/Agent_Handoff. Create the Agent Handoff files, GitHub issue templates, and pull request template. Fill PROJECT_STATE.md with the initial project snapshot. Configure HANDOFF_PROTOCOL.md with smoke tests for this project. + +Before creating any Docker or Docker Compose files, ask me a separate explicit question about containerization. +Ask whether Docker or Compose is needed, which supported layout I want, and whether production deployment configuration belongs in this repository or a separate deployment repository. +Do not infer the answer or create container infrastructure until I answer. + Create the first short handoff and update the handoff index. ``` @@ -45,9 +57,14 @@ Create the first short handoff and update the handoff index. Add Agent Handoff to this existing repository. Use the latest standard from https://github.com/artyomboyko/Agent_Handoff. Inspect the current repository first. -Merge similar files carefully. +Merge similar Agent Handoff files carefully. Compress current state into ai/PROJECT_STATE.md. Put durable decisions into ai/DECISIONS.md. Configure smoke tests in ai/HANDOFF_PROTOCOL.md. + +Inspect existing Dockerfiles, Compose files, scripts, build contexts, ignore files, environment references, and documented commands. +Then ask me a separate explicit question whether the existing container layout must be preserved or may be migrated, which supported target layout I want, and whether production deployment configuration belongs here or in a separate repository. +Do not move, rename, delete, consolidate, or create container infrastructure until I answer. + Open a pull request and leave a short handoff. ``` From c5d2ce91843d87f642a2f142dcb0a37b9a020952 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:23:34 +0300 Subject: [PATCH 07/29] docs: update quick start for mandatory container layout choice --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d525c70..24f49c0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Agent Handoff -[![Standard](https://img.shields.io/badge/standard-1.2-blue)](AGENT_HANDOFF_STANDARD.md) +[![Standard](https://img.shields.io/badge/standard-1.3--draft-orange)](AGENT_HANDOFF_STANDARD.md) [![Language](https://img.shields.io/badge/language-English-blue)](docs/en/README.md) [![GitHub native](https://img.shields.io/badge/GitHub-native-black)](ai/GITHUB_WORKFLOW.md) [![AI agent ready](https://img.shields.io/badge/AI%20agent-ready-purple)](ai/AGENT_IDENTITY.md) @@ -50,6 +50,11 @@ Use the latest standard from https://github.com/artyomboyko/Agent_Handoff. Inspect the current repository first. Create or update the Agent Handoff files, GitHub Issue Forms, and Pull Request template. Keep the repository language English unless the downstream project explicitly chooses another language. + +Ask me a separate explicit question about Docker and Docker Compose organization before creating, moving, renaming, deleting, or consolidating any container files or paths. +Ask whether containerization is used or planned, which supported layout I want, whether an existing layout must be preserved or may be migrated, and whether production deployment configuration belongs in this repository or a separate deployment repository. +Do not infer the answer or choose the recommended layout automatically. + Open a Pull Request and leave a compact handoff. ``` @@ -59,7 +64,7 @@ Open a Pull Request and leave a compact handoff. 2. Git is the source of code truth. 3. `ai/` is compact durable memory. 4. Handoffs are short, structured, and reviewable. -5. Humans stay in control. +5. Humans stay in control of structural and migration decisions. ## What is included @@ -73,6 +78,7 @@ Open a Pull Request and leave a compact handoff. | Task reports | [ai/TASK_REPORT_PROTOCOL.md](ai/TASK_REPORT_PROTOCOL.md) | | Agent identity | [ai/AGENT_IDENTITY.md](ai/AGENT_IDENTITY.md) | | Refactoring workflow | [ai/REFACTORING.md](ai/REFACTORING.md) | +| Containerization | [ai/CONTAINERIZATION.md](ai/CONTAINERIZATION.md) | | Issue labels | [ISSUE_LABELS.md](ISSUE_LABELS.md) | | Issue status | [ISSUE_STATUS.md](ISSUE_STATUS.md) | | FAQ | [FAQ.md](FAQ.md) | @@ -90,7 +96,7 @@ Open a Pull Request and leave a compact handoff. ## Natural search terms -Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, and human-agent collaboration. +Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, containerization decisions, Docker Compose organization, and human-agent collaboration. ## For humans @@ -98,7 +104,7 @@ Use Agent Handoff to see who owns work, what changed, what was tested, what rema ## For agents -Start from `AGENTS.md`, read the required files, claim work in GitHub, open a Draft PR early, keep `ai/` compact, and leave a handoff when work is completed, paused, blocked, or transferred. +Start from `AGENTS.md`, read the required files, claim work in GitHub, ask for required user decisions, open a Draft PR early, keep `ai/` compact, and leave a handoff when work is completed, paused, blocked, or transferred. ## Repository visibility From 5b63c012fbdb1e585639f833a3330c84dfa370f8 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:23:47 +0300 Subject: [PATCH 08/29] docs: record standard 1.3 draft changes --- CHANGELOG.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5394cb..b7ab4cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,21 @@ All notable changes to Agent Handoff are documented here. +## 1.3 - Draft + +### Added + +- GUI testing rule that prohibits brittle automated tests based on absolute coordinates, screen position, pixel offsets, or incidental layout order. +- `ai/CONTAINERIZATION.md` with supported Docker and Docker Compose organization approaches. +- Supported containerization choices for no repository-managed containers, colocated files, centralized `docker/`, hybrid layout, modular monorepos, separate deployment repositories, and established custom layouts. +- Container layout migration inventory, verification, project-memory, and handoff requirements. + +### Changed + +- New-repository initialization and existing-repository adoption now require a separate, explicit user decision about containerization and file layout. +- Agents may not infer, create, relocate, consolidate, or migrate container infrastructure before the user answers the mandatory question. +- The hybrid layout is a recommended option to present, not an automatic default. + ## 1.2 - 2026-07-07 ### Added From de5b3bcd0faa90c1c85367ddfc46cf9a953f5343 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:24:01 +0300 Subject: [PATCH 09/29] docs: update project state for standard 1.3 draft --- ai/PROJECT_STATE.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/ai/PROJECT_STATE.md b/ai/PROJECT_STATE.md index da27509..0d2a684 100644 --- a/ai/PROJECT_STATE.md +++ b/ai/PROJECT_STATE.md @@ -2,7 +2,7 @@ type: project_state version: 1 status: active -updated: 2026-07-07 +updated: 2026-07-18 project: Agent_Handoff --- @@ -10,7 +10,7 @@ project: Agent_Handoff ## Current phase -Agent Handoff Standard 1.2 is ready for final publication review. +Agent Handoff Standard 1.3 is in draft development on branch `standard-1.3`. The repository is maintained as an English-only canonical version. @@ -27,6 +27,9 @@ The repository is maintained as an English-only canonical version. - FAQ and examples. - GitHub Actions checks workflow. - Citation metadata. +- Standard 1.3 draft GUI testing rule against position-dependent automated tests. +- Standard 1.3 draft containerization protocol with explicit user-controlled layout selection. +- Mandatory separate containerization question for new-repository initialization and existing-repository adoption. ## Main files @@ -39,10 +42,20 @@ The repository is maintained as an English-only canonical version. - `ai/WORK_CLAIM_PROTOCOL.md` - `ai/TASK_REPORT_PROTOCOL.md` - `ai/REFACTORING.md` +- `ai/CONTAINERIZATION.md` - `.github/pull_request_template.md` - `scripts/check_agent_handoff.py` +## Current draft decisions + +- Container layout is selected by the user, not inferred by an agent. +- Supported approaches include no containerization, colocated, centralized, hybrid, modular monorepo, separate deployment repository, and preserved custom layouts. +- The hybrid layout may be recommended to the user but cannot be selected automatically. +- Existing container infrastructure cannot be migrated without explicit approval. + ## Next -1. Confirm checks are green. -2. Publish release `v1.2` after final review. +1. Review Standard 1.3 wording and examples. +2. Decide whether repository checks should require or validate the new containerization protocol. +3. Add a focused Issue and Draft Pull Request before publication. +4. Complete a release handoff and publish `v1.3` only after review and green checks. From da2e400a9c44deb5355acffdb777de590e893dcb Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:24:18 +0300 Subject: [PATCH 10/29] docs: record user-controlled container layout decision --- ai/DECISIONS.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/ai/DECISIONS.md b/ai/DECISIONS.md index ae1b76c..c0df658 100644 --- a/ai/DECISIONS.md +++ b/ai/DECISIONS.md @@ -2,7 +2,7 @@ type: architecture_record version: 1 status: active -updated: 2026-07-07 +updated: 2026-07-18 project: Agent_Handoff --- @@ -56,3 +56,41 @@ Maintain this repository in English only. Downstream projects may adapt Agent Ha - `AGENT_HANDOFF_STANDARD.md` - `docs/en/README.md` + +## 2026-07-18 — User-controlled containerization layout + +Status: accepted for Standard 1.3 draft + +### Background + +Docker and Docker Compose files can be organized in several valid ways. Automatically applying one preferred structure during repository initialization or Agent Handoff adoption could create unnecessary migrations, break paths and commands, or override established project ownership boundaries. + +### Decision + +Document all supported containerization approaches in `ai/CONTAINERIZATION.md`. + +During both new-repository initialization and adoption into an existing repository, require the agent to ask the user a separate, explicit question about whether containerization is used or planned, which layout should be used, whether an existing layout may be migrated, and whether production deployment belongs in the same repository. + +Do not allow the agent to infer approval or automatically apply the recommended hybrid layout. + +### Rejected alternatives + +- Require one universal Docker layout for all repositories. +- Automatically migrate existing repositories to the hybrid layout. +- Treat the container layout as an implementation detail that the agent may decide silently. +- Create placeholder Docker infrastructure before a confirmed requirement exists. + +### Consequences + +- Container layout remains a human-controlled architecture decision. +- Existing repositories are preserved until migration is explicitly approved. +- New repositories do not receive speculative Docker infrastructure. +- Agents have a complete catalog of supported layouts and shared verification requirements. +- Initialization prompts and handoff procedures must expose the decision gate explicitly. + +### Related + +- `AGENT_HANDOFF_STANDARD.md` +- `ai/CONTAINERIZATION.md` +- `ai/HANDOFF_PROTOCOL.md` +- `docs/en/README.md` From 76c03489075afca09f4554f730ca5f50ac7ae98d Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:24:33 +0300 Subject: [PATCH 11/29] docs: surface containerization decision gate in agent guide --- AGENTS.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2eaaea8..fa6a332 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,11 +12,14 @@ Before meaningful work, read these files: 8. `ai/TASK_REPORT_PROTOCOL.md` 9. `ai/PROJECT_STATE.md` 10. `ai/DECISIONS.md` -11. related Issue or PR -12. relevant handoffs through `ai/handoffs/INDEX.md` +11. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, present, or being discussed +12. related Issue or PR +13. relevant handoffs through `ai/handoffs/INDEX.md` Use GitHub Issues and Pull Requests as the primary workflow system. Report each meaningful Issue with a required stage or final result comment. +When initializing Agent Handoff in a new repository or adding it to an existing repository, ask the user a separate explicit question about containerization and file layout before changing any Docker or Compose structure. Do not infer or automatically select the recommended approach. + Keep `ai/` files compact. From 866a2364e5d97dd7bf88b67faf833cf8dc6d2779 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:41:43 +0300 Subject: [PATCH 12/29] release: activate Agent Handoff Standard 1.3 --- AGENT_HANDOFF_STANDARD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENT_HANDOFF_STANDARD.md b/AGENT_HANDOFF_STANDARD.md index f9793a2..0654bd2 100644 --- a/AGENT_HANDOFF_STANDARD.md +++ b/AGENT_HANDOFF_STANDARD.md @@ -1,7 +1,7 @@ --- standard: Agent Handoff version: "1.3" -status: draft +status: active updated: 2026-07-18 --- From 5f7f847064ee6c2213d4ab392ecbc01815684b78 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:42:17 +0300 Subject: [PATCH 13/29] release: activate containerization protocol --- ai/CONTAINERIZATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/CONTAINERIZATION.md b/ai/CONTAINERIZATION.md index c97ea0d..ee51283 100644 --- a/ai/CONTAINERIZATION.md +++ b/ai/CONTAINERIZATION.md @@ -1,7 +1,7 @@ --- type: containerization_protocol version: 1 -status: draft +status: active updated: 2026-07-18 project: Agent_Handoff --- From ebe2efadb82803934cbf53fc6bfd37bdee99ca58 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:42:37 +0300 Subject: [PATCH 14/29] release: publish Standard 1.3 in README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 24f49c0..56303a3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Agent Handoff -[![Standard](https://img.shields.io/badge/standard-1.3--draft-orange)](AGENT_HANDOFF_STANDARD.md) +[![Standard](https://img.shields.io/badge/standard-1.3-blue)](AGENT_HANDOFF_STANDARD.md) [![Language](https://img.shields.io/badge/language-English-blue)](docs/en/README.md) [![GitHub native](https://img.shields.io/badge/GitHub-native-black)](ai/GITHUB_WORKFLOW.md) [![AI agent ready](https://img.shields.io/badge/AI%20agent-ready-purple)](ai/AGENT_IDENTITY.md) @@ -83,6 +83,7 @@ Open a Pull Request and leave a compact handoff. | Issue status | [ISSUE_STATUS.md](ISSUE_STATUS.md) | | FAQ | [FAQ.md](FAQ.md) | | Examples | [examples/](examples/) | +| Release notes | [docs/releases/v1.3.md](docs/releases/v1.3.md) | ## Comparison From 3444c3c845acf469dedb0a2ccd362f1b4c9224db Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:42:48 +0300 Subject: [PATCH 15/29] release: date Standard 1.3 changelog --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b7ab4cf..eafab4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to Agent Handoff are documented here. -## 1.3 - Draft +## 1.3 - 2026-07-18 ### Added @@ -10,12 +10,14 @@ All notable changes to Agent Handoff are documented here. - `ai/CONTAINERIZATION.md` with supported Docker and Docker Compose organization approaches. - Supported containerization choices for no repository-managed containers, colocated files, centralized `docker/`, hybrid layout, modular monorepos, separate deployment repositories, and established custom layouts. - Container layout migration inventory, verification, project-memory, and handoff requirements. +- Release notes in `docs/releases/v1.3.md`. ### Changed - New-repository initialization and existing-repository adoption now require a separate, explicit user decision about containerization and file layout. - Agents may not infer, create, relocate, consolidate, or migrate container infrastructure before the user answers the mandatory question. - The hybrid layout is a recommended option to present, not an automatic default. +- Repository checks and the Pull Request checklist now cover the containerization protocol and decision gate. ## 1.2 - 2026-07-07 From b86a3808bb988f050de004fee5cae321000cbbd1 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:42:56 +0300 Subject: [PATCH 16/29] release: update citation metadata for 1.3 --- CITATION.cff | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 5d13274..45acc2e 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,7 +4,8 @@ title: "Agent Handoff: GitHub-native context handoff for AI coding agents" authors: - family-names: "Boyko" given-names: "Artyom" -version: "1.2" +version: "1.3" +date-released: 2026-07-18 url: "https://github.com/artyomboyko/Agent_Handoff" repository-code: "https://github.com/artyomboyko/Agent_Handoff" license: "GPL-3.0-only" @@ -16,3 +17,5 @@ keywords: - "agent-memory" - "multi-agent-system" - "handoff-protocol" + - "docker-compose" + - "containerization" From d969f50ead5d5b51c0bebbfd98a35f0647364fce Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:43:08 +0300 Subject: [PATCH 17/29] docs: add Standard 1.3 release notes --- docs/releases/v1.3.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/releases/v1.3.md diff --git a/docs/releases/v1.3.md b/docs/releases/v1.3.md new file mode 100644 index 0000000..7de42e1 --- /dev/null +++ b/docs/releases/v1.3.md @@ -0,0 +1,43 @@ +# Agent Handoff 1.3 + +Agent Handoff 1.3 adds explicit human control over containerization decisions and strengthens testing guidance for GUI-based projects. + +## Highlights + +- Mandatory separate containerization question during both new-repository initialization and adoption into an existing repository. +- Agents cannot infer, create, relocate, consolidate, or migrate Docker and Docker Compose infrastructure before the user confirms the approach. +- Complete containerization protocol in `ai/CONTAINERIZATION.md`. +- Supported layouts for no repository-managed containerization, colocated files, centralized `docker/`, hybrid projects, modular monorepos, separate deployment repositories, and established custom layouts. +- Existing container layouts are preserved unless migration is explicitly approved. +- The hybrid layout may be recommended for many small and medium multi-service repositories, but it is never selected automatically. +- Compose path, override, environment, migration, verification, project-memory, and handoff requirements. +- Prohibition on brittle automated GUI tests based on absolute coordinates, screen position, pixel offsets, or incidental layout order. +- Position-dependent GUI checks are performed manually or as supervised exploratory checks with Codex. +- Automated GUI tests should use semantic roles, accessible names, labels, stable component identifiers, or dedicated test IDs. + +## Compatibility + +Standard 1.3 does not require existing projects to reorganize Docker or Compose files. + +When Agent Handoff is added to an established repository, the current container layout remains unchanged until the user explicitly authorizes a migration. + +Projects that do not use Docker or Docker Compose do not need to create container files or `ai/CONTAINERIZATION.md`. + +## Main files + +- `AGENT_HANDOFF_STANDARD.md` +- `ai/CONTAINERIZATION.md` +- `ai/HANDOFF_PROTOCOL.md` +- `AGENTS.md` +- `README.md` +- `docs/en/README.md` +- `.github/pull_request_template.md` +- `scripts/check_agent_handoff.py` + +## Publication + +- Issue: https://github.com/artyomboyko/Agent_Handoff/issues/12 +- Pull Request: https://github.com/artyomboyko/Agent_Handoff/pull/13 +- Repository: https://github.com/artyomboyko/Agent_Handoff +- Website: https://artyomboyko.github.io/Agent_Handoff/ +- Standard: https://github.com/artyomboyko/Agent_Handoff/blob/main/AGENT_HANDOFF_STANDARD.md From 99243fb32f99608bd81472d0f4a12f2d3bd1209b Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:43:21 +0300 Subject: [PATCH 18/29] release: mark Standard 1.3 active in project state --- ai/PROJECT_STATE.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/ai/PROJECT_STATE.md b/ai/PROJECT_STATE.md index 0d2a684..2aa2623 100644 --- a/ai/PROJECT_STATE.md +++ b/ai/PROJECT_STATE.md @@ -10,7 +10,7 @@ project: Agent_Handoff ## Current phase -Agent Handoff Standard 1.3 is in draft development on branch `standard-1.3`. +Agent Handoff Standard 1.3 is the active published standard. The repository is maintained as an English-only canonical version. @@ -27,9 +27,11 @@ The repository is maintained as an English-only canonical version. - FAQ and examples. - GitHub Actions checks workflow. - Citation metadata. -- Standard 1.3 draft GUI testing rule against position-dependent automated tests. -- Standard 1.3 draft containerization protocol with explicit user-controlled layout selection. +- GUI testing rule against position-dependent automated tests. +- Containerization protocol with explicit user-controlled layout selection. - Mandatory separate containerization question for new-repository initialization and existing-repository adoption. +- Supported no-containerization, colocated, centralized, hybrid, modular monorepo, separate deployment repository, and preserved custom layouts. +- Container migration, Compose path, verification, project-memory, and handoff requirements. ## Main files @@ -45,17 +47,26 @@ The repository is maintained as an English-only canonical version. - `ai/CONTAINERIZATION.md` - `.github/pull_request_template.md` - `scripts/check_agent_handoff.py` +- `docs/releases/v1.3.md` -## Current draft decisions +## Active decisions - Container layout is selected by the user, not inferred by an agent. -- Supported approaches include no containerization, colocated, centralized, hybrid, modular monorepo, separate deployment repository, and preserved custom layouts. -- The hybrid layout may be recommended to the user but cannot be selected automatically. +- The hybrid layout may be recommended but cannot be selected automatically. - Existing container infrastructure cannot be migrated without explicit approval. +- Position-dependent GUI tests stay outside the routine automated test suite. +- Automated GUI tests use stable semantic selectors. + +## Current publication + +- Standard version: `1.3` +- Status: active +- Publication date: 2026-07-18 +- Issue: #12 +- Pull Request: #13 ## Next -1. Review Standard 1.3 wording and examples. -2. Decide whether repository checks should require or validate the new containerization protocol. -3. Add a focused Issue and Draft Pull Request before publication. -4. Complete a release handoff and publish `v1.3` only after review and green checks. +1. Keep repository checks and public documentation synchronized with future standard changes. +2. Collect feedback from projects adopting the containerization decision gate. +3. Prepare a future version only through a focused Issue, branch, Pull Request, checks, and release handoff. From f6070ca899aa15a3ba2d153c3cf1d89ebbd5f5bc Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:43:40 +0300 Subject: [PATCH 19/29] docs: finalize Standard 1.3 decisions --- ai/DECISIONS.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/ai/DECISIONS.md b/ai/DECISIONS.md index c0df658..9619f35 100644 --- a/ai/DECISIONS.md +++ b/ai/DECISIONS.md @@ -59,7 +59,7 @@ Maintain this repository in English only. Downstream projects may adapt Agent Ha ## 2026-07-18 — User-controlled containerization layout -Status: accepted for Standard 1.3 draft +Status: accepted in Standard 1.3 ### Background @@ -86,11 +86,39 @@ Do not allow the agent to infer approval or automatically apply the recommended - Existing repositories are preserved until migration is explicitly approved. - New repositories do not receive speculative Docker infrastructure. - Agents have a complete catalog of supported layouts and shared verification requirements. -- Initialization prompts and handoff procedures must expose the decision gate explicitly. +- Initialization prompts and handoff procedures expose the decision gate explicitly. ### Related +- Issue: #12 +- Pull Request: #13 - `AGENT_HANDOFF_STANDARD.md` - `ai/CONTAINERIZATION.md` - `ai/HANDOFF_PROTOCOL.md` - `docs/en/README.md` + +## 2026-07-18 — Stable GUI automation over position-dependent tests + +Status: accepted in Standard 1.3 + +### Background + +GUI tests that depend on absolute coordinates, screen positions, pixel offsets, or incidental layout order are fragile and frequently fail after harmless interface changes. + +### Decision + +Do not include position-dependent GUI checks in the routine automated test suite. Perform those checks manually or as supervised exploratory checks with Codex. + +Automated GUI tests use stable semantic roles, accessible names, labels, documented component identifiers, or dedicated test IDs. + +### Consequences + +- Routine GUI automation is more resilient to layout changes. +- Visual and position-dependent behavior remains explicitly testable through manual or supervised exploratory checks. +- Handoffs and Pull Requests must state when such checks were performed manually. + +### Related + +- Issue: #12 +- Pull Request: #13 +- `AGENT_HANDOFF_STANDARD.md` From 059215c5819c6ef56aaa02fc2d2e18cbeed5f157 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:44:02 +0300 Subject: [PATCH 20/29] docs: link Standard 1.3 release notes --- docs/en/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/README.md b/docs/en/README.md index 8b3d91d..1c19f6e 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -1,10 +1,11 @@ # English documentation -This page is the documentation index for Agent Handoff. +This page is the documentation index for Agent Handoff Standard 1.3. ## Documents - [Standard](../../AGENT_HANDOFF_STANDARD.md) +- [Release notes 1.3](../releases/v1.3.md) - [Issue labels](../../ISSUE_LABELS.md) - [Issue status](../../ISSUE_STATUS.md) - [Guide](../../AGENTS.md) From 4f35bcffe2c2b74731c8875b7ae8201abec20837 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:44:13 +0300 Subject: [PATCH 21/29] template: add Standard 1.3 release checks --- .github/pull_request_template.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1b7292c..1183c9d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -29,6 +29,9 @@ Closes # - [ ] Forms are valid when changed. - [ ] Required stage or final result comment exists. - [ ] Smoke tests were run or reason is documented. +- [ ] Mandatory containerization decision was confirmed when relevant, or not applicable. +- [ ] Changed Compose configuration was rendered and checked, or reason and risk are documented. +- [ ] Automated GUI tests avoid position-dependent selectors, or manual/supervised checks are documented. ## State updates From 814840727c35bdb701cdc83276225aaff5ce1edf Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:44:48 +0300 Subject: [PATCH 22/29] ci: validate Standard 1.3 metadata and protocols --- scripts/check_agent_handoff.py | 56 +++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 4 deletions(-) diff --git a/scripts/check_agent_handoff.py b/scripts/check_agent_handoff.py index c4ea0da..bcf0657 100644 --- a/scripts/check_agent_handoff.py +++ b/scripts/check_agent_handoff.py @@ -13,8 +13,9 @@ 'ai/README.md', 'ai/PROJECT_STATE.md', 'ai/DECISIONS.md', 'ai/GITHUB_WORKFLOW.md', 'ai/HANDOFF_PROTOCOL.md', 'ai/AGENT_IDENTITY.md', 'ai/WORK_CLAIM_PROTOCOL.md', 'ai/TASK_REPORT_PROTOCOL.md', 'ai/REFACTORING.md', - 'ai/handoffs/INDEX.md', '.github/ISSUE_TEMPLATE', '.github/pull_request_template.md', - '.github/workflows/standard-check.yml', 'docs/en', + 'ai/CONTAINERIZATION.md', 'ai/handoffs/INDEX.md', + '.github/ISSUE_TEMPLATE', '.github/pull_request_template.md', + '.github/workflows/standard-check.yml', 'docs/en', 'docs/releases', 'docs/index.html', 'docs/404.html', 'docs/robots.txt', 'docs/sitemap.xml', 'examples/README.md', 'assets/social-preview.svg', ] @@ -26,16 +27,32 @@ 'Forms are valid when changed.', 'Required stage or final result comment exists.', 'Smoke tests were run or reason is documented.', + 'Mandatory containerization decision was confirmed when relevant, or not applicable.', + 'Changed Compose configuration was rendered and checked, or reason and risk are documented.', + 'Automated GUI tests avoid position-dependent selectors, or manual/supervised checks are documented.', ] ENGLISH_ONLY_PATHS = [ 'README.md', 'AGENTS.md', 'AGENT_HANDOFF_STANDARD.md', 'CONTRIBUTING.md', 'CODE_OF_CONDUCT.md', 'SECURITY.md', 'ISSUE_LABELS.md', 'ISSUE_STATUS.md', - 'FAQ.md', 'CHANGELOG.md', 'ai', 'docs/en', '.github/ISSUE_TEMPLATE', - '.github/pull_request_template.md', 'docs/index.html', 'examples/README.md', + 'FAQ.md', 'CHANGELOG.md', 'ai', 'docs/en', 'docs/releases', + '.github/ISSUE_TEMPLATE', '.github/pull_request_template.md', + 'docs/index.html', 'examples/README.md', ] CYRILLIC_RE = re.compile(r'[А-Яа-яЁё]') +FRONT_MATTER_RE = re.compile(r'^---\n(.*?)\n---\n', re.DOTALL) + + +def read_front_matter(path: Path): + text = path.read_text(encoding='utf-8') + match = FRONT_MATTER_RE.match(text) + if not match: + raise ValueError('missing YAML front matter') + data = yaml.safe_load(match.group(1)) + if not isinstance(data, dict): + raise ValueError('front matter root must be a map') + return data def main(): @@ -69,6 +86,37 @@ def main(): if item not in text: errors.append(f'TASK_REPORT_PROTOCOL.md missing: {item}') + standard = ROOT / 'AGENT_HANDOFF_STANDARD.md' + if standard.exists(): + try: + metadata = read_front_matter(standard) + version = str(metadata.get('version', '')).strip() + if not version: + errors.append('standard metadata missing version') + if metadata.get('status') != 'active': + errors.append('standard status must be active') + if version: + release_notes = ROOT / 'docs' / 'releases' / f'v{version}.md' + if not release_notes.exists(): + errors.append(f'missing release notes: {release_notes.relative_to(ROOT)}') + readme = (ROOT / 'README.md').read_text(encoding='utf-8') + if f'standard-{version}-blue' not in readme: + errors.append('README standard badge does not match active standard version') + citation = yaml.safe_load((ROOT / 'CITATION.cff').read_text(encoding='utf-8')) + if str(citation.get('version', '')).strip() != version: + errors.append('CITATION.cff version does not match active standard version') + except Exception as exc: + errors.append(f'invalid standard metadata: {exc}') + + containerization = ROOT / 'ai' / 'CONTAINERIZATION.md' + if containerization.exists(): + try: + metadata = read_front_matter(containerization) + if metadata.get('status') != 'active': + errors.append('containerization protocol status must be active') + except Exception as exc: + errors.append(f'invalid containerization metadata: {exc}') + for item in ENGLISH_ONLY_PATHS: path = ROOT / item if path.is_file(): From b9ad9e7e70ed9cab38463f966e6549f020c043c3 Mon Sep 17 00:00:00 2001 From: Artyom Boyko Date: Sat, 18 Jul 2026 13:45:17 +0300 Subject: [PATCH 23/29] site: publish Standard 1.3 landing page --- docs/index.html | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/index.html b/docs/index.html index f329896..bd8eed5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -3,11 +3,11 @@ - Agent Handoff — GitHub-native context handoff for AI coding agents - + Agent Handoff 1.3 — GitHub-native context handoff for AI coding agents + - - + +