diff --git a/.github/REPOSITORY_SETTINGS.md b/.github/REPOSITORY_SETTINGS.md index 7b847ac..44584d7 100644 --- a/.github/REPOSITORY_SETTINGS.md +++ b/.github/REPOSITORY_SETTINGS.md @@ -54,4 +54,5 @@ GitHub Pages is published from the `/docs` folder on `main`. - Review Issues, PRs, and Actions logs. - Confirm About description, Website, topics, and social preview. - Confirm GitHub Actions checks and Pages deployment are green. -- Create release `v1.2`. +- Confirm citation metadata and release notes match the active standard version. +- Create a tagged GitHub release when a tag is part of the publication plan. 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 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. diff --git a/AGENT_HANDOFF_STANDARD.md b/AGENT_HANDOFF_STANDARD.md index 9eea63e..0654bd2 100644 --- a/AGENT_HANDOFF_STANDARD.md +++ b/AGENT_HANDOFF_STANDARD.md @@ -1,8 +1,8 @@ --- standard: Agent Handoff -version: "1.2" +version: "1.3" status: active -updated: 2026-07-07 +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,47 @@ 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. + +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; @@ -95,7 +139,10 @@ Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates. - 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index f5394cb..eafab4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,23 @@ All notable changes to Agent Handoff are documented here. +## 1.3 - 2026-07-18 + +### 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. +- 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 ### Added 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" diff --git a/README.md b/README.md index d525c70..56303a3 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-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) @@ -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,10 +78,12 @@ 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) | | Examples | [examples/](examples/) | +| Release notes | [docs/releases/v1.3.md](docs/releases/v1.3.md) | ## Comparison @@ -90,7 +97,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 +105,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 diff --git a/ai/CONTAINERIZATION.md b/ai/CONTAINERIZATION.md new file mode 100644 index 0000000..ee51283 --- /dev/null +++ b/ai/CONTAINERIZATION.md @@ -0,0 +1,292 @@ +--- +type: containerization_protocol +version: 1 +status: active +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. diff --git a/ai/DECISIONS.md b/ai/DECISIONS.md index ae1b76c..9619f35 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,69 @@ 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 in Standard 1.3 + +### 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 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` 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. diff --git a/ai/PROJECT_STATE.md b/ai/PROJECT_STATE.md index da27509..2aa2623 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 the active published standard. The repository is maintained as an English-only canonical version. @@ -27,6 +27,11 @@ The repository is maintained as an English-only canonical version. - FAQ and examples. - GitHub Actions checks workflow. - Citation metadata. +- 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 @@ -39,10 +44,29 @@ 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` +- `docs/releases/v1.3.md` + +## Active decisions + +- Container layout is selected by the user, not inferred by an agent. +- 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. Confirm checks are green. -2. Publish release `v1.2` after final review. +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. 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. diff --git a/ai/handoffs/2026-07-18_issue-12_pr-13_run-publish-standard-1-3-20260718.md b/ai/handoffs/2026-07-18_issue-12_pr-13_run-publish-standard-1-3-20260718.md new file mode 100644 index 0000000..72c96da --- /dev/null +++ b/ai/handoffs/2026-07-18_issue-12_pr-13_run-publish-standard-1-3-20260718.md @@ -0,0 +1,75 @@ +--- +type: handoff +version: 1 +date: 2026-07-18 +updated: 2026-07-18 +run: publish-standard-1-3-20260718 +agent: GPT-5.6 Thinking +agent_id: chatgpt-gpt-5-6-thinking +project: Agent_Handoff +branch: standard-1.3 +issue: 12 +pr: 13 +base_commit: 727e83aab342ac68de4849318e6ac162a6db8153 +final_reviewed_commit: 140b721de61aaf98c9e8006c6c9cee3e2114c8da +status: completed +relevance: active +supersedes: +--- + +# Handoff: publish-standard-1-3-20260718 + +## Task + +Finalize and publish Agent Handoff Standard 1.3. + +## What changed + +- Activated Standard 1.3. +- Added the rule against brittle position-dependent automated GUI tests. +- Added the complete containerization protocol. +- Required a separate explicit user decision about containerization during both new-repository initialization and adoption into an existing repository. +- Documented all supported container layouts, migration rules, Compose path rules, verification, project-memory, and handoff requirements. +- Synchronized README, changelog, citation metadata, release notes, project state, decisions, public documentation, Pull Request checks, and repository validation. + +## Files changed + +- `AGENT_HANDOFF_STANDARD.md` — active Standard 1.3. +- `ai/CONTAINERIZATION.md` — containerization decision and operating protocol. +- `ai/HANDOFF_PROTOCOL.md` — container workflow and verification procedure. +- `AGENTS.md` — mandatory containerization decision gate. +- `README.md` and `docs/en/README.md` — public usage instructions. +- `CHANGELOG.md` and `docs/releases/v1.3.md` — release history and notes. +- `CITATION.cff` — version 1.3 citation metadata. +- `ai/PROJECT_STATE.md` and `ai/DECISIONS.md` — active state and durable decisions. +- `.github/pull_request_template.md` — Standard 1.3 checks. +- `scripts/check_agent_handoff.py` — metadata, release-note, containerization, and PR checklist validation. +- `docs/index.html` — Standard 1.3 landing page. + +## Smoke tests + +- GitHub Actions workflow `Agent Handoff checks` is required to pass on Pull Request #13 before merge. +- The validation script checks required files, YAML, PR checklist items, active version metadata, matching README and citation versions, release notes, English-only active files, and social preview dimensions. + +## What was tested + +- Repository file and link consistency was reviewed through the GitHub diff. +- No application runtime or Docker configuration is present in this standards repository, so Compose runtime tests are not applicable. +- GUI runtime tests are not applicable to this documentation repository. + +## What failed / risks + +- A tagged GitHub Release is a separate optional publication artifact and is not required for the standard to become active on `main`. +- Downstream agents must implement the mandatory user decision gate rather than silently selecting the recommended hybrid layout. +- The merge commit and post-merge workflow run remain authoritative after Pull Request #13 is merged. + +## Next recommended step + +Merge Pull Request #13 only after the final GitHub Actions check is green, then verify the `main` workflow and GitHub Pages publication. + +## Links + +- Issue: https://github.com/artyomboyko/Agent_Handoff/issues/12 +- PR: https://github.com/artyomboyko/Agent_Handoff/pull/13 +- Release notes: `docs/releases/v1.3.md` +- Actions: Pull Request #13 checks diff --git a/ai/handoffs/INDEX.md b/ai/handoffs/INDEX.md index 4170976..6459c4d 100644 --- a/ai/handoffs/INDEX.md +++ b/ai/handoffs/INDEX.md @@ -2,7 +2,7 @@ type: handoff_index version: 1 status: active -updated: 2026-07-07 +updated: 2026-07-18 project: Agent_Handoff --- @@ -12,7 +12,8 @@ Read this index first. | Date | Updated | Run | Issue | PR | Branch | Status | Relevance | Summary | File | Supersedes | |---|---|---|---|---|---|---|---|---|---|---| -| 2026-07-07 | 2026-07-07 | english-only-cleanup | none | none | main | in-progress | active | Simplified active repository files to English-only documentation | | repository-presentation | +| 2026-07-18 | 2026-07-18 | publish-standard-1-3-20260718 | #12 | #13 | standard-1.3 | completed | active | Published Standard 1.3 with containerization decision gate and safe GUI testing rules | 2026-07-18_issue-12_pr-13_run-publish-standard-1-3-20260718.md | english-only-cleanup | +| 2026-07-07 | 2026-07-07 | english-only-cleanup | none | none | main | completed | historical | Simplified active repository files to English-only documentation | | repository-presentation | | 2026-07-02 | 2026-07-02 | repository-presentation | none | none | main | completed | historical | Added public presentation docs and assets | | consistency-pass | | 2026-07-02 | 2026-07-02 | consistency-pass | none | none | main | completed | historical | Synchronized standard docs and templates | | bilingual-docs | | 2026-07-02 | 2026-07-02 | bilingual-docs | none | none | main | completed | historical | Added bilingual docs and issue templates | | | diff --git a/docs/PROMOTION_CHECKLIST.md b/docs/PROMOTION_CHECKLIST.md index b614c0c..8e3054d 100644 --- a/docs/PROMOTION_CHECKLIST.md +++ b/docs/PROMOTION_CHECKLIST.md @@ -1,26 +1,26 @@ -# Promotion checklist / Checklist продвижения +# Promotion checklist -Current promotion state before release `v1.2`. -Текущее состояние продвижения перед release `v1.2`. +Reusable checklist for publishing Agent Handoff releases. -## Done / Сделано +## Current release -- Landing README. -- Natural search terms in README. -- FAQ. -- Examples. -- Contributing, Security, Code of Conduct, and Changelog. -- Social preview asset and uploaded social preview image. -- Public repository. -- About description. -- Website pointing to GitHub Pages. -- Topics. -- GitHub Pages site. -- Citation metadata. -- GitHub Actions checks. +- Standard 1.3 is active in `AGENT_HANDOFF_STANDARD.md`. +- README, citation metadata, changelog, release notes, project state, and public documentation identify version 1.3. +- Repository checks validate active standard metadata and release-note presence. -## Remaining / Осталось +## Public repository checks -- Review repository history. -- Review generated files. -- Create release `v1.2`. +- Landing README is current. +- Natural search terms are current. +- FAQ and examples are available. +- Contributing, Security, Code of Conduct, and Changelog are available. +- Social preview asset and uploaded social preview image are current. +- About description, Website, and topics are current. +- GitHub Pages is published from `/docs` on `main`. +- Citation metadata matches the active standard version. +- GitHub Actions checks are green. +- Repository history, generated files, Issues, Pull Requests, and Actions logs were reviewed. + +## Tagged release + +When a tagged GitHub release is planned, create it from the verified merge commit and use the matching file from `docs/releases/` as the release notes source. diff --git a/docs/en/PROMOTION_CHECKLIST_EN.md b/docs/en/PROMOTION_CHECKLIST_EN.md index 01be807..84b29da 100644 --- a/docs/en/PROMOTION_CHECKLIST_EN.md +++ b/docs/en/PROMOTION_CHECKLIST_EN.md @@ -2,23 +2,25 @@ This page mirrors `docs/PROMOTION_CHECKLIST.md` for English documentation readers. -## Done +## Current release -- Landing README. -- Natural search terms in README. -- FAQ. -- Examples. -- Contributing, Security, Code of Conduct, and Changelog. -- Social preview asset and uploaded social preview image. -- Public repository. -- About description. -- Website pointing to GitHub Pages. -- Topics. -- GitHub Pages site. -- Citation metadata. -- GitHub Actions checks. +- Standard 1.3 is active in `AGENT_HANDOFF_STANDARD.md`. +- README, citation metadata, changelog, release notes, project state, and public documentation identify version 1.3. +- Repository checks validate active standard metadata and release-note presence. -## Remaining +## Public repository checks -- Final repository review. -- Create release `v1.2`. +- Landing README is current. +- Natural search terms are current. +- FAQ and examples are available. +- Contributing, Security, Code of Conduct, and Changelog are available. +- Social preview asset and uploaded social preview image are current. +- About description, Website, and topics are current. +- GitHub Pages is published from `/docs` on `main`. +- Citation metadata matches the active standard version. +- GitHub Actions checks are green. +- Repository history, generated files, Issues, Pull Requests, and Actions logs were reviewed. + +## Tagged release + +When a tagged GitHub release is planned, create it from the verified merge commit and use the matching file from `docs/releases/` as the release notes source. diff --git a/docs/en/README.md b/docs/en/README.md index ec5e1f1..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) @@ -17,6 +18,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 +30,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 +44,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 +58,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. ``` diff --git a/docs/en/REPOSITORY_SETTINGS_EN.md b/docs/en/REPOSITORY_SETTINGS_EN.md index beb6d3c..b98b3d4 100644 --- a/docs/en/REPOSITORY_SETTINGS_EN.md +++ b/docs/en/REPOSITORY_SETTINGS_EN.md @@ -67,4 +67,5 @@ GitHub Pages is published from the `/docs` folder on `main`. - Review Issues, PRs, and Actions logs. - Confirm About description, Website, topics, and social preview. - Confirm GitHub Actions checks and Pages deployment are green. -- Create release `v1.2`. +- Confirm citation metadata and release notes match the active standard version. +- Create a tagged GitHub release when a tag is part of the publication plan. 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 + - - + +