update_server/docs/agents/WORKFLOW.md

AI Agent Workflow Runbook

1. Purpose

This document defines how to implement the update server with sequential AI agents.

The workflow is designed for:

• one human operator who launches agents one by one;
• one implementation agent per stage;
• one validation agent after each stage;
• file-based handoff instead of direct agent-to-agent chat.

2. Source Of Truth

Every implementation agent must read these files before starting:

• /Users/delete/projects/update_server/PRODUCT_SPEC.md
• /Users/delete/projects/update_server/IMPLEMENTATION_PLAN.md
• /Users/delete/projects/update_server/DEVELOPMENT_WORKFLOW.md
• /Users/delete/projects/update_server/docs/agents/WORKFLOW.md

Every agent must also read the latest handoff and validation files if they exist.

3. Fixed Technical Decisions

These decisions are considered fixed unless the human operator explicitly changes them.

• Language: Go
• Router: chi
• Database: SQLite
• HTML strategy: server-rendered HTML templates
• Artifact storage: local filesystem
• Deployment shape: app container behind Caddy or Nginx
• Web auth: session-based authentication
• Client auth: Authorization: Bearer <api_key>
• API key access modes:
  • all_projects
  • project_allow_list
  • project_deny_list
  • tag_allow_list
  • tag_deny_list
• One API key must use exactly one scope mode at a time
• Projects support tags from day one
• Security is mandatory, not optional

4. Shared Workspace Rules

All code lives in the main repository.

Agents should use these implementation paths:

• /Users/delete/projects/update_server/cmd/server
• /Users/delete/projects/update_server/internal
• /Users/delete/projects/update_server/web
• /Users/delete/projects/update_server/migrations

Agents must use these coordination paths:

• handoffs: /Users/delete/projects/update_server/docs/agents/handoffs
• validations: /Users/delete/projects/update_server/docs/agents/validation

If an agent needs to communicate something to the next agent, it must do so through:

• code changes;
• a handoff file;
• updates to spec or implementation docs if architecture changed.

Agents should not rely on hidden memory or previous chat state.

5. Handoff Protocol

After finishing work, every implementation agent must create a handoff file:

• naming format: NN-agent-name.md
• example: 01-foundation.md

Each handoff file should be saved in:

• /Users/delete/projects/update_server/docs/agents/handoffs

The handoff file must include:

• scope of work;
• files changed;
• migrations added or changed;
• endpoints added or changed;
• tests or commands run;
• known limitations;
• exact next recommended step.

Use this template:

• /Users/delete/projects/update_server/docs/agents/HANDOFF_TEMPLATE.md

6. Validation Protocol

After each implementation agent finishes, run a validation agent before moving to the next stage.

The validation agent should:

• read the current agent section in this file;
• read the latest handoff file;
• inspect code changes;
• run relevant tests or checks;
• produce a validation report.

Validation files should be saved in:

• /Users/delete/projects/update_server/docs/agents/validation

Use this template:

• /Users/delete/projects/update_server/docs/agents/VALIDATION_TEMPLATE.md

Validation result must end in one of these statuses:

• APPROVED
• CHANGES_REQUIRED

Do not launch the next implementation agent until the previous stage is APPROVED.

7. Agent Count

Recommended sequence:

• 7 implementation agents
• 1 validation agent role used after every stage

The validation agent can be the same AI system reused every time.

8. Agent 01 - Foundation

Mission

Set up the repository skeleton and the minimum runnable Go application.

Ownership

This agent owns:

• Go module initialization
• basic app boot
• config loading
• HTTP router setup
• health endpoint
• base middleware wiring
• template bootstrapping
• initial developer commands

Deliverables

This agent must produce:

• runnable server entrypoint
• config package
• base router with route groups
• health endpoint
• base HTML layout structure
• initial project structure under cmd, internal, and web

Out Of Scope

This agent must not implement:

• business logic
• database schema
• authentication flows
• release upload
• API keys

Acceptance Criteria

• the app starts successfully;
• a health endpoint responds;
• the code structure matches the implementation plan;
• the project is ready for migrations and feature modules.

9. Agent 02 - Database And Migrations

Mission

Create the data model, migrations, and database access foundation.

Ownership

This agent owns:

• migration setup
• database connection layer
• schema design
• repository or query layer foundation

Deliverables

This agent must implement tables for:

• users
• projects
• tags
• project_tags
• releases
• api_keys
• api_key_project_access
• api_key_tag_access
• sessions if needed
• audit_logs if included in the first pass

Out Of Scope

This agent must not implement:

• login UI
• upload endpoints
• full business workflows

Acceptance Criteria

• migrations can be applied cleanly;
• schema matches the spec;
• access tables support project and tag based key scopes;
• database layer is ready for the next agents.

10. Agent 03 - Authentication And Admin Sessions

Mission

Implement admin authentication and session management.

Ownership

This agent owns:

• admin bootstrap user creation
• password hashing
• login and logout flow
• session middleware
• role checks foundation

Deliverables

This agent must produce:

• login form and login handler
• session creation and invalidation
• protected admin route group
• admin bootstrap from environment or setup logic

Out Of Scope

This agent must not implement:

• project management
• release upload
• API key logic

Acceptance Criteria

• admin can log in and log out;
• protected routes are actually protected;
• passwords are hashed securely;
• session handling works reliably.

11. Agent 04 - Projects, Tags, And Releases

Mission

Implement core product data management: projects, project tags, and release upload metadata flow.

Ownership

This agent owns:

• project CRUD
• tag CRUD
• attach or detach tags from projects
• release metadata handling
• artifact storage abstraction
• upload flow and checksum generation

Deliverables

This agent must produce:

• project create, edit, list, archive flow
• tag create, edit, list flow
• project-tag assignment
• release upload service
• artifact persistence on disk
• checksum capture

Out Of Scope

This agent must not implement:

• API key access logic
• external client update endpoints

Acceptance Criteria

• admin can manage projects and tags;
• admin can upload a release to a project;
• release metadata is stored in the database;
• artifact files are stored outside the public web root.

12. Agent 05 - API Keys And Access Control

Mission

Implement API key generation, hashing, permissions, and scope evaluation.

Ownership

This agent owns:

• secure API key generation
• API key hashing and lookup
• permission flags
• access scope evaluation
• project allow or deny list rules
• tag allow or deny list rules

Deliverables

This agent must produce:

• API key creation flow
• one-time key reveal behavior
• key activation and revocation
• permission middleware for API key routes
• project and tag access resolution logic

Out Of Scope

This agent must not implement:

• final UI polish
• deployment hardening

Acceptance Criteria

• API keys are stored hashed;
• only authorized projects are visible to a given key;
• allow-list and deny-list logic works for projects and tags;
• disabled or expired keys are rejected.

13. Agent 06 - Client API And Admin UI

Mission

Implement the usable product experience for admins and client applications.

Ownership

This agent owns:

• admin pages for projects, tags, releases, and API keys
• client-facing update endpoints
• latest-release lookup
• release metadata endpoint
• authenticated download endpoint

Deliverables

This agent must produce:

• admin pages that cover the main flows
• client endpoint to list accessible projects
• client endpoint to get latest release metadata
• client endpoint to download a release

Out Of Scope

This agent must not implement:

• deep security hardening beyond local route protection
• production reverse proxy setup

Acceptance Criteria

• an admin can complete the full product flow from the browser;
• a client can authenticate with a bearer API key;
• a client can discover and download only authorized updates.

14. Agent 07 - Security And Deployment Hardening

Mission

Make the system safe and deployable on an internet-facing server.

Ownership

This agent owns:

• security headers
• rate limiting
• request timeouts
• CSRF finishing pass
• safer cookie settings
• reverse proxy examples
• Docker and deployment finishing pass
• backup and operational notes

Deliverables

This agent must produce:

• hardened HTTP server settings
• production-ready container setup
• Caddy or Nginx example configuration
• deployment notes for Proxmox
• security review fixes that fit the current architecture

Out Of Scope

This agent must not redesign the product or data model unless a critical security issue requires it.

Acceptance Criteria

• the service is ready to run behind HTTPS;
• admin and client traffic have sane security defaults;
• artifacts are not directly exposed;
• deployment instructions are complete enough for first production rollout.

15. Validation Agent Role

Mission

Review each completed stage before the next implementation agent starts.

Required Checks

The validation agent should verify:

• scope completion;
• obvious regressions;
• schema or route mismatches;
• missing tests;
• unsafe behavior;
• contradictions with the spec.

Output

The validation agent must write one validation file per stage and finish with:

• APPROVED
• or CHANGES_REQUIRED

16. Operator Guide For Human User

Этот раздел специально для тебя, на русском.

Общая схема запуска

Запускаешь агентов строго по порядку:

1. Agent 01 - Foundation
2. Validator
3. Agent 02 - Database And Migrations
4. Validator
5. Agent 03 - Authentication And Admin Sessions
6. Validator
7. Agent 04 - Projects, Tags, And Releases
8. Validator
9. Agent 05 - API Keys And Access Control
10. Validator
11. Agent 06 - Client API And Admin UI
12. Validator
13. Agent 07 - Security And Deployment Hardening
14. Final Validator

Как запускать каждый этап

Для каждого нового агента даёшь ему один и тот же базовый контекст:

• прочитать PRODUCT_SPEC.md
• прочитать IMPLEMENTATION_PLAN.md
• прочитать DEVELOPMENT_WORKFLOW.md
• прочитать docs/agents/WORKFLOW.md
• прочитать последний handoff-файл
• прочитать последний validation-файл, если он есть

После этого говоришь агенту работать только в рамках его секции из этого runbook.

Что требовать от каждого агента

После завершения этапа агент обязан:

• внести код;
• если нужно, обновить документацию;
• создать handoff-файл в docs/agents/handoffs;
• перечислить, что сделано;
• перечислить, что не сделано;
• указать, что должен делать следующий агент.

Когда запускать валидатора

Валидатора запускаешь после каждого агента.

Ему даёшь задачу:

• прочитать соответствующую секцию агента из docs/agents/WORKFLOW.md;
• прочитать свежий handoff;
• проверить код;
• проверить, не нарушена ли спецификация;
• выдать APPROVED или CHANGES_REQUIRED;
• сохранить отчёт в docs/agents/validation.

Если валидатор нашёл проблемы

Если статус CHANGES_REQUIRED, то:

1. не переходишь к следующему агенту;
2. запускаешь того же самого агента повторно;
3. даёшь ему его прошлый handoff и validation report;
4. просишь закрыть замечания;
5. снова запускаешь валидатора.

Когда использовать меня как валидатора

Меня лучше использовать:

• после каждого крупного этапа;
• перед миграциями базы;
• перед этапом security hardening;
• перед первым Docker/deploy;
• перед выкладкой на Proxmox.

Практически удобный режим

Самый удобный режим для тебя такой:

1. локально на Mac запускаешь первого агента;
2. проверяешь, что handoff-файл создался;
3. зовёшь меня как валидатора;
4. после APPROVED запускаешь следующего агента;
5. когда дойдёшь до конца, только потом собираешь контейнер и переносишь на Proxmox.

Главный принцип

Следующий агент никогда не стартует без handoff от прошлого и без validation report.

Это защитит тебя от хаоса, повторной работы и скрытых поломок между этапами.