chore: integrate AI development platform into HLL Vietnam project

.github/workflows/codex-worker.yml

@@ -0,0 +1,33 @@
+name: Codex Worker
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'ai/tasks/pending/**'
+      - 'AGENTS.md'
+      - 'ai/**'
+      - 'scripts/codex-runner.ps1'
+
+jobs:
+  run-codex-worker:
+    runs-on: ubuntu-latest
+    if: ${{ secrets.OPENAI_API_KEY != '' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Codex CLI
+        run: npm install -g @openai/codex
+
+      - name: Run Codex Worker
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          codex --auto "Follow AGENTS.md, read the AI platform files in ai/, and process only the pending tasks within scoped repository rules."

AGENTS.md

@@ -1,23 +1,103 @@
-# AGENTS
+# HLL Vietnam Agent Operating Rules
 
-Este repositorio está preparado para ser orquestado mediante roles especializados. La coordinación debe priorizar claridad, cambios pequeños y documentación técnica suficiente para sostener el crecimiento del proyecto.
+This repository uses an AI-driven task workflow adapted to HLL Vietnam.
 
-## Roles previstos
+## Project Context
+
+- Product: HLL Vietnam
+- Product type: community website
+- Current frontend: HTML, CSS and vanilla JavaScript
+- Planned backend: Python
+- Current product scope: simple landing page and repository foundation
+- Visual identity: military, Vietnam, tactical, sober
+
+## Task System
+
+Task locations:
+
+- Pending: `ai/tasks/pending`
+- In progress: `ai/tasks/in-progress`
+- Done: `ai/tasks/done`
+
+Every new task must follow:
+
+- `ai/task-template.md`
+
+## Core Workflow
+
+1. The orchestrator reviews repository context and relevant code.
+2. The orchestrator writes or refines a task in `ai/tasks/pending`.
+3. A worker moves the selected task to `ai/tasks/in-progress`.
+4. The worker reads the files listed in `Files to Read First`.
+5. The worker performs only the scoped change defined by the task.
+6. The worker validates the change with the documented checks.
+7. The worker moves the completed task to `ai/tasks/done`.
+8. The worker documents any relevant architectural or process decision.
+
+Codex must not act freely outside tasks except for repository inspection, platform maintenance, or explicitly requested integration work like this one.
+
+## Roles Used In This Repository
 
 - PM
 - Analista
 - Backend Senior
 - Frontend Senior
 - Arquitecto de Base de Datos
-- Arquitecto .NET
+- Arquitecto Python
-- Diseñador gráfico
+- Disenador grafico
 - Experto en interfaz
 
-## Reglas de trabajo
+Role guidance is stored in:
 
-- No romper la estructura del repositorio sin una justificación técnica clara.
+- `ai/orchestrator/`
-- Documentar las decisiones importantes en `docs/decisions.md`.
+
-- Hacer cambios pequeños, verificables y fáciles de revisar.
+## Rules
-- Mantener coherencia visual con una identidad militar, Vietnam y táctica.
+
-- Considerar Python como backend principal previsto del proyecto.
+- Do not break repository structure without explicit technical justification.
-- No introducir frameworks o complejidad innecesaria en esta fase inicial.
+- Do not make destructive changes without explicit justification.
+- Keep changes small, verifiable and documented.
+- Do not overwrite existing project context with generic template content.
+- Preserve HLL Vietnam branding and product identity.
+- Do not introduce unnecessary frameworks in the current phase.
+- Do not build backend functionality until a task explicitly requires it.
+- Do not modify unrelated files.
+
+## Technical Constraints
+
+- Frontend changes must remain compatible with direct browser opening when applicable.
+- Backend architecture decisions must assume Python as the primary backend language.
+- AI platform files are support infrastructure, not product features.
+- If a template utility is copied from the platform template, it must remain clearly identified as platform infrastructure.
+
+## Planning Rules
+
+Before drafting or executing a task:
+
+1. Read `ai/architecture-index.md`.
+2. Read `ai/repo-context.md`.
+3. Read the relevant role file in `ai/orchestrator/`.
+4. Read the small set of project files directly related to the requested change.
+
+When no pending product task exists:
+
+1. Do not invent a large backlog.
+2. Only create a minimal technical validation task if needed to verify platform readiness.
+3. Avoid feature planning that changes product scope without instruction.
+
+## Change Budget
+
+- Prefer fewer than 5 modified files per task.
+- Prefer changes under 200 lines when feasible.
+- Split work into follow-up tasks if the scope grows.
+
+## Validation
+
+Before marking a task as done:
+
+1. Run the validation listed in the task.
+2. Review `git diff --name-only`.
+3. Confirm that changed files match the expected scope.
+4. Update documentation if the task changed workflow or architecture assumptions.
+
+If integration tests are relevant and `scripts/run-integration-tests.ps1` exists, use it.
+If no integration tests are configured for the affected scope, document that explicitly in the task outcome.

ai/README.md

@@ -1,5 +1,22 @@
-# AI Workspace
+# AI Platform Workspace
 
-Esta carpeta queda preparada para incorporar más adelante el sistema de tareas, la orquestación y los flujos de trabajo asistidos por agentes.
+This directory contains the AI Development Platform support layer integrated into HLL Vietnam.
 
-La estructura actual separa el espacio de tareas por estado y reserva un área específica para el orquestador.
+Its purpose is operational, not product-facing. It exists to help the project plan work through tasks, preserve repository context, coordinate specialist roles and keep changes small, reviewable and documented.
+
+## Included areas
+
+- `task-template.md`: standard structure for every task
+- `repo-context.md`: repository and product context for planners and workers
+- `architecture-index.md`: quick map of the repository structure
+- `system-metrics.md`: lightweight log for platform execution metrics
+- `prompts/`: reusable planning prompts
+- `orchestrator/`: role guidance and orchestration documents
+- `tasks/`: task queue split by status
+
+## HLL Vietnam usage rules
+
+- The platform must reflect the real state of HLL Vietnam, not generic sample content.
+- Tasks should be created only when there is a justified change to perform.
+- This integration does not add product features by itself.
+- The current product stack remains HTML, CSS and JavaScript on the frontend, with Python reserved for the future backend.

ai/architecture-index.md

@@ -0,0 +1,58 @@
+# Architecture Index
+
+This file gives AI agents a fast overview of HLL Vietnam before they inspect the repository in detail.
+
+## Application Type
+
+Community website repository with a static landing in the current phase and a planned Python backend in later phases.
+
+## Top-Level Structure
+
+### Documentation
+
+- `README.md`
+- `AGENTS.md`
+- `docs/`
+
+### Frontend
+
+- `frontend/index.html`
+- `frontend/assets/css/`
+- `frontend/assets/js/`
+- `frontend/assets/img/`
+
+### Backend
+
+- `backend/`
+- `backend/app/`
+
+### AI Platform
+
+- `ai/`
+- `ai/orchestrator/`
+- `ai/prompts/`
+- `ai/tasks/`
+
+### Automation And Support
+
+- `scripts/`
+- `.github/workflows/`
+
+## Current Technical Baseline
+
+- Frontend runtime is plain browser-loaded HTML, CSS and JavaScript.
+- There is no active backend runtime yet.
+- Python is the expected backend language for future development.
+- GitHub Actions and local PowerShell scripts may support the AI task workflow.
+
+## Editing Priorities
+
+- Product-facing changes usually start in `frontend/`.
+- Process and coordination changes usually start in `ai/`, `AGENTS.md` and `scripts/`.
+- Backend changes must remain preparatory unless a task explicitly changes that scope.
+
+## Validation Expectations
+
+- Frontend changes should remain compatible with local browser opening where applicable.
+- AI platform changes should keep task paths and documentation aligned.
+- Script changes should fail safely when optional tools or tests are not configured.

ai/orchestrator/README.md

@@ -1,5 +1,22 @@
 # Orchestrator
 
-El orquestador coordinará en fases posteriores la ejecución de tareas, la asignación de roles y la trazabilidad del trabajo entre agentes del proyecto.
+The orchestrator is responsible for turning repository context into safe, scoped and verifiable tasks for HLL Vietnam.
 
-Los agentes actuarán sobre responsabilidades acotadas, con decisiones documentadas y cambios verificables.
+## What it does
+
+- Reviews repository structure and current documentation
+- Identifies the smallest useful unit of work
+- Assigns the most suitable role guidance for the task
+- Keeps tasks aligned with HLL Vietnam constraints and branding
+- Prevents uncontrolled work outside the task system
+
+## How it collaborates
+
+- Reads `ai/architecture-index.md` and `ai/repo-context.md` first
+- Uses `ai/task-template.md` to draft tasks
+- Sends execution to the appropriate role document in this folder
+- Keeps completed work traceable through `ai/tasks/` and `ai/system-metrics.md`
+
+## Current scope
+
+At this stage the orchestrator supports repository setup, documentation alignment, planning hygiene and future implementation flow. It does not define product roadmap beyond explicit project instructions.

ai/orchestrator/analyst.md

@@ -0,0 +1,30 @@
+# Analista
+
+## Mission
+
+Convert requests into concrete repository context, dependencies and risks before implementation starts.
+
+## When This Role Intervenes
+
+- When requirements need clarification through code and docs review
+- When impact analysis is needed before editing
+- When validation criteria must be derived from repository state
+
+## Review First
+
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `docs/decisions.md`
+- Files directly affected by the request
+
+## Restrictions
+
+- Do not implement product features from analysis alone.
+- Do not generate a backlog beyond the immediate validated need.
+- Keep analysis focused on the current request.
+
+## Collaboration With The Orchestrator
+
+- Provides the factual basis for task creation
+- Identifies the smallest safe change set
+- Documents assumptions the worker must preserve

ai/orchestrator/backend-senior.md

@@ -0,0 +1,30 @@
+# Backend Senior
+
+## Mission
+
+Guard backend readiness and future service design without introducing premature implementation.
+
+## When This Role Intervenes
+
+- When a task touches `backend/`
+- When integration points with the future backend must be documented
+- When validation needs to preserve Python readiness
+
+## Review First
+
+- `backend/README.md`
+- `backend/requirements.txt`
+- `docs/project-overview.md`
+- `docs/decisions.md`
+
+## Restrictions
+
+- Do not create functional backend services unless explicitly required by task.
+- Keep the future backend baseline in Python.
+- Avoid placeholder complexity that creates false architecture commitments.
+
+## Collaboration With The Orchestrator
+
+- Reviews backend-facing tasks for future compatibility
+- Suggests minimal preparatory structure only when justified
+- Prevents accidental drift toward non-Python backend assumptions

ai/orchestrator/component-discovery.md

@@ -0,0 +1,20 @@
+# Component Discovery
+
+## Purpose
+
+Identify the real repository areas affected by a request before any task is executed.
+
+## Repository Areas
+
+- Root docs: repository purpose and rules
+- `docs/`: scope, roadmap and decisions
+- `frontend/`: current live product surface
+- `backend/`: future Python backend foundation
+- `ai/`: orchestration and task workflow
+- `scripts/`: local platform automation
+
+## Rules
+
+- Read the smallest relevant set of files first.
+- Prefer extending existing documents and scripts instead of duplicating them.
+- Do not assume framework layers that do not exist in this repository.

ai/orchestrator/database-architect.md

@@ -0,0 +1,30 @@
+# Arquitecto de Base de Datos
+
+## Mission
+
+Protect long-term data modeling decisions while the repository is still in foundation stage.
+
+## When This Role Intervenes
+
+- When a task discusses future persistence
+- When backend planning introduces data structure assumptions
+- When architecture documents mention storage or schema strategy
+
+## Review First
+
+- `docs/project-overview.md`
+- `docs/roadmap.md`
+- `docs/decisions.md`
+- `backend/README.md`
+
+## Restrictions
+
+- Do not introduce concrete database implementations in this phase.
+- Do not force schema decisions without a real product task.
+- Keep guidance abstract and aligned with the future Python backend.
+
+## Collaboration With The Orchestrator
+
+- Reviews planning assumptions for data persistence
+- Helps avoid premature database commitments
+- Documents open questions instead of inventing structures

ai/orchestrator/di-analysis.md

@@ -0,0 +1,11 @@
+# Dependency Analysis
+
+## Purpose
+
+Analyze dependencies and execution assumptions before changing scripts, automation or future backend design notes.
+
+## Rules
+
+- Identify whether the task affects frontend-only, documentation-only or platform-only areas.
+- Avoid importing template assumptions from unrelated stacks.
+- When in doubt, preserve the current lightweight structure and document the dependency instead of implementing it.

ai/orchestrator/feature-planner.md

@@ -0,0 +1,20 @@
+# Feature Planner
+
+## Purpose
+
+Turn explicit repository requests into implementation-ready tasks without expanding product scope.
+
+## Workflow
+
+1. Read `AGENTS.md`.
+2. Read `ai/repo-context.md`.
+3. Read `ai/architecture-index.md`.
+4. Inspect only the files directly related to the request.
+5. Create the smallest useful task set in `ai/tasks/pending`.
+
+## Rules
+
+- Use `ai/task-template.md`.
+- Keep tasks small, focused and verifiable.
+- Do not invent product work beyond the request.
+- Keep HLL Vietnam branding and stack constraints intact.

ai/orchestrator/frontend-senior.md

@@ -0,0 +1,30 @@
+# Frontend Senior
+
+## Mission
+
+Maintain and evolve the frontend foundation with minimal, high-signal changes that preserve local-browser compatibility.
+
+## When This Role Intervenes
+
+- When a task touches `frontend/`
+- When landing integration must remain stable after platform changes
+- When markup, styles or script loading need review
+
+## Review First
+
+- `frontend/index.html`
+- `frontend/assets/css/styles.css`
+- `frontend/assets/js/main.js`
+- `docs/decisions.md`
+
+## Restrictions
+
+- Do not introduce heavy frontend frameworks in this phase.
+- Do not redesign the landing unless the task explicitly requires it.
+- Preserve the HLL Vietnam military and tactical tone.
+
+## Collaboration With The Orchestrator
+
+- Confirms whether a task really needs product-facing frontend edits
+- Keeps frontend changes scoped and reversible
+- Reports any integration effect on direct browser usage

ai/orchestrator/graphic-designer.md

@@ -0,0 +1,30 @@
+# Disenador Grafico
+
+## Mission
+
+Protect the visual identity of HLL Vietnam so that future assets, layouts and presentations remain coherent with the intended military and Vietnam-inspired branding.
+
+## When This Role Intervenes
+
+- When a task affects visual assets or art direction
+- When design documentation needs alignment
+- When branding consistency is at risk
+
+## Review First
+
+- `frontend/index.html`
+- `frontend/assets/css/styles.css`
+- `docs/project-overview.md`
+- `docs/decisions.md`
+
+## Restrictions
+
+- Do not introduce off-brand visuals or generic styles.
+- Do not add asset-heavy redesign work unless explicitly requested.
+- Preserve a sober tactical tone.
+
+## Collaboration With The Orchestrator
+
+- Validates visual consistency before design-oriented tasks are executed
+- Helps frame asset and branding work into scoped tasks
+- Keeps platform-generated work aligned with project identity

ai/orchestrator/planning-memory.md

@@ -0,0 +1,12 @@
+# Planning Memory
+
+## Purpose
+
+Store short planning lessons that help future tasks stay aligned with the repository.
+
+## Current Notes
+
+- HLL Vietnam is in foundation stage.
+- Product work must not be invented from generic platform templates.
+- Backend assumptions must remain Python-oriented.
+- Frontend remains static and lightweight until explicitly expanded.

ai/orchestrator/pm.md

@@ -0,0 +1,30 @@
+# PM
+
+## Mission
+
+Translate stakeholder intent into the smallest useful task scope without changing project goals on your own.
+
+## When This Role Intervenes
+
+- When a request needs scope framing
+- When work must be split into smaller tasks
+- When priorities or sequencing need clarification
+
+## Review First
+
+- `README.md`
+- `docs/project-overview.md`
+- `docs/roadmap.md`
+- `AGENTS.md`
+
+## Restrictions
+
+- Do not invent new product features without instruction.
+- Do not expand scope beyond what the request justifies.
+- Do not bypass the task system.
+
+## Collaboration With The Orchestrator
+
+- Helps the orchestrator define task boundaries
+- Suggests execution order
+- Flags scope creep early

ai/orchestrator/python-architect.md

@@ -0,0 +1,30 @@
+# Arquitecto Python
+
+## Mission
+
+Ensure all backend-oriented planning remains coherent with a future Python implementation.
+
+## When This Role Intervenes
+
+- When backend architecture is discussed
+- When automation or support scripts reference backend assumptions
+- When tasks might accidentally introduce a conflicting stack
+
+## Review First
+
+- `AGENTS.md`
+- `docs/decisions.md`
+- `backend/README.md`
+- `ai/repo-context.md`
+
+## Restrictions
+
+- Do not add Python services, frameworks or runtime code unless explicitly requested.
+- Do not accept template defaults that assume .NET or another backend stack.
+- Keep platform docs aligned with Python as the intended backend.
+
+## Collaboration With The Orchestrator
+
+- Reviews tasks for backend stack consistency
+- Rewrites generic template assumptions into Python-compatible guidance
+- Flags any drift away from the intended backend baseline

ai/orchestrator/repo-reviewer.md

@@ -0,0 +1,12 @@
+# Repository Reviewer
+
+## Purpose
+
+Review repository health and identify only the most relevant technical follow-ups.
+
+## Rules
+
+- Start from `ai/architecture-index.md` and `ai/repo-context.md`.
+- Prefer documentation, consistency and workflow issues over speculative product work.
+- Do not create a large backlog by default.
+- If needed, create only minimal technical readiness tasks.

ai/orchestrator/ui-expert.md

@@ -0,0 +1,30 @@
+# Experto en Interfaz
+
+## Mission
+
+Safeguard usability, clarity and responsive behavior of the HLL Vietnam frontend without introducing unnecessary complexity.
+
+## When This Role Intervenes
+
+- When a task changes user-facing flows or layout
+- When responsiveness or readability must be reviewed
+- When an integration could degrade the landing experience
+
+## Review First
+
+- `frontend/index.html`
+- `frontend/assets/css/styles.css`
+- `frontend/assets/js/main.js`
+- `docs/project-overview.md`
+
+## Restrictions
+
+- Do not add new interface flows without task scope.
+- Do not sacrifice simplicity for novelty.
+- Keep interactions lightweight and compatible with the current static frontend approach.
+
+## Collaboration With The Orchestrator
+
+- Reviews impact on usability before execution
+- Recommends minimal UI-safe changes
+- Helps keep frontend tasks grounded in real interface needs

ai/prompts/plan-feature.md

@@ -0,0 +1,26 @@
+# Plan Feature Prompt
+
+Use this prompt when the orchestrator needs to transform a repository request into implementation-ready tasks.
+
+## Prompt
+
+Analyze the HLL Vietnam repository before proposing any implementation work.
+
+Required behavior:
+
+1. Read `AGENTS.md`.
+2. Read `ai/repo-context.md`.
+3. Read `ai/architecture-index.md`.
+4. Review only the files directly related to the request.
+5. Produce a small, safe task breakdown.
+6. Do not invent product features outside the request.
+7. Keep branding, frontend stack and planned Python backend consistent with the repository rules.
+
+Task output rules:
+
+- Use `ai/task-template.md`.
+- Keep tasks small and verifiable.
+- Prefer one task when the work is very small.
+- Add clear `Files to Read First`.
+- Add clear `Expected Files to Modify`.
+- Include explicit validation steps.

ai/repo-context.md

@@ -0,0 +1,84 @@
+# Repository Context
+
+## Project Overview
+
+HLL Vietnam is a community website repository for a Spanish-speaking Discord community centered on the future game HLL Vietnam.
+
+The current implementation is intentionally small:
+
+- a static landing page in `frontend/`
+- a reserved Python backend space in `backend/`
+- documentation in `docs/`
+- an AI task orchestration layer in `ai/`
+
+This repository is in foundation stage. The objective is to grow in a controlled way without losing clarity or overwriting project identity with generic template content.
+
+## Current Product State
+
+- Frontend: static HTML, CSS and vanilla JavaScript
+- Backend: not implemented yet, but planned in Python
+- AI Platform: integrated to coordinate planning and task execution
+- Product goal in current phase: maintain a clean landing and repository structure
+
+## Repository Areas
+
+### Root documentation
+
+- `README.md`
+- `AGENTS.md`
+
+These files define the repository purpose and operating rules.
+
+### Docs
+
+- `docs/project-overview.md`
+- `docs/roadmap.md`
+- `docs/decisions.md`
+
+These files describe scope, phased evolution and technical decisions.
+
+### Frontend
+
+- `frontend/index.html`
+- `frontend/assets/css/styles.css`
+- `frontend/assets/js/main.js`
+
+This is the live product surface in the current phase. Keep changes conservative unless a task explicitly targets the landing.
+
+### Backend
+
+- `backend/README.md`
+- `backend/requirements.txt`
+- `backend/app/__init__.py`
+
+This area is a reserved foundation for the future Python backend. Do not add functional services unless explicitly requested by task.
+
+### AI Platform
+
+- `ai/task-template.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `ai/system-metrics.md`
+- `ai/prompts/`
+- `ai/orchestrator/`
+- `ai/tasks/`
+
+This area supports planning, orchestration and execution discipline.
+
+## Working Rules For Agents
+
+- Always work from tasks, except for repository inspection or explicitly requested platform integration.
+- Prefer small, focused, reviewable changes.
+- Preserve the military and Vietnam-inspired visual tone.
+- Avoid introducing new technologies without clear reason.
+- Treat Python as the planned backend baseline.
+
+## AI Workflow
+
+`Request -> Orchestrator review -> Scoped task -> Execution -> Validation -> Documentation -> Commit`
+
+Tasks move through:
+
+- `ai/tasks/pending`
+- `ai/tasks/in-progress`
+- `ai/tasks/done`

ai/system-metrics.md

@@ -0,0 +1,15 @@
+# System Metrics
+
+This file tracks lightweight execution history for the HLL Vietnam AI development workflow.
+
+## Metrics
+
+- Total task cycles executed
+- Successful task cycles
+- Failed task cycles
+- Average cycle duration
+- Notes about skipped validation steps
+
+## Task History
+
+Date | Task | Duration | Result | Notes

ai/task-template.md

@@ -0,0 +1,65 @@
+# TASK-XXX
+
+## Goal
+
+Describe the smallest useful objective for this task.
+
+## Context
+
+Explain where the change happens in HLL Vietnam and why it is needed now.
+
+## Steps
+
+1. Inspect the listed files first.
+2. Apply only the scoped change.
+3. Validate the result and document relevant findings.
+
+## Files to Read First
+
+List 3 to 6 files that must be reviewed before changing anything.
+
+Examples for this repository:
+
+- `AGENTS.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `frontend/index.html`
+- `frontend/assets/css/styles.css`
+- `backend/README.md`
+
+Rules:
+
+- Read these files before implementation.
+- Keep the list small and directly relevant.
+- Prefer existing docs and code that already define the area being changed.
+
+## Expected Files to Modify
+
+List the files that should change during the task.
+
+Rules:
+
+- Prefer modifying only these files.
+- If additional files become necessary, explain why in the task outcome or commit message.
+- Do not modify unrelated files.
+
+## Constraints
+
+- Keep the change minimal.
+- Preserve HLL Vietnam project identity.
+- Do not introduce unnecessary frameworks or dependencies.
+- Do not implement backend functionality unless the task explicitly requires it.
+
+## Validation
+
+Before completing the task ensure:
+
+- scoped checks pass
+- no unrelated files were modified
+- documentation remains consistent with the repository state
+
+## Change Budget
+
+- Prefer fewer than 5 modified files.
+- Prefer changes under 200 lines when feasible.
+- Split the work into follow-up tasks if limits are exceeded.

ai/tasks/pending/TASK-001-platform-readiness-check.md

@@ -0,0 +1,48 @@
+# TASK-001-platform-readiness-check
+
+## Goal
+
+Validate that the AI development platform is integrated into HLL Vietnam with the required documentation, task structure and automation entry points.
+
+## Context
+
+This task exists only as a technical readiness reference. It is not a product feature task and should not change the landing or add backend behavior.
+
+## Steps
+
+1. Verify that `AGENTS.md` points to the task workflow.
+2. Verify that `ai/` contains context, architecture, prompts and orchestrator role docs.
+3. Verify that `scripts/` contains the expected platform scripts.
+4. Verify that the repository remains consistent after integration.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/README.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `ai/orchestrator/README.md`
+
+## Expected Files to Modify
+
+- None unless a platform consistency issue is found
+
+## Constraints
+
+- Do not modify product-facing files unless a platform integration issue requires it.
+- Do not add new product tasks.
+- Keep this task as a platform validation reference only.
+
+## Validation
+
+Before completing the task ensure:
+
+- required platform files exist
+- task paths are present
+- scripts are present
+- repository documentation is coherent
+
+## Change Budget
+
+- Prefer zero code changes.
+- If any correction is needed, keep it minimal and platform-scoped.

docs/decisions.md

@@ -15,3 +15,7 @@ Se incluye una carpeta `ai/` y un documento `AGENTS.md` para facilitar una futur
 ## Decision 004: branding militar Vietnam
 
 La dirección visual inicial se alinea con una estética sobria, táctica y militar inspirada en el contexto Vietnam para mantener coherencia temática desde la primera iteración.
+
+## Decision 005: AI Development Platform integrada de forma adaptada
+
+Se integra una capa de orquestación por tasks inspirada en la plantilla de AI Development Platform, pero adaptada al contexto real de HLL Vietnam y sin arrastrar supuestos genéricos de otros stacks. La plataforma se usa como soporte operativo del repositorio, no como funcionalidad del producto.

docs/project-overview.md

@@ -14,6 +14,7 @@ Publicar una landing simple que permita presentar la comunidad, mostrar el trail
 - Landing estática en HTML, CSS y JavaScript.
 - Documentación base para organizar el crecimiento del proyecto.
 - Preparación de carpetas para backend y orquestación futura.
+- Plataforma de tasks y orquestación integrada para coordinar trabajo técnico.
 
 ## Stack actual
 

install-ai-platform.ps1

@@ -0,0 +1,8 @@
+param(
+    [string]$RepositoryRoot = (Get-Location).Path
+)
+
+Write-Host "HLL Vietnam AI platform is already integrated in this repository."
+Write-Host "This script is kept as a platform utility placeholder inherited from the template approach."
+Write-Host "Repository root: $RepositoryRoot"
+Write-Host "If platform files drift, compare them against the project task workflow before replacing anything."

scripts/codex-runner.ps1

@@ -0,0 +1,83 @@
+param(
+    [int]$PollIntervalSeconds = 30
+)
+
+Write-Host "HLL Vietnam Codex worker started..."
+
+$lockFile = "ai/worker.lock"
+
+function Test-WorkerProcessActive {
+    param(
+        [string]$LockFilePath
+    )
+
+    if (-not (Test-Path $LockFilePath)) {
+        return $false
+    }
+
+    $lockContent = Get-Content $LockFilePath -ErrorAction SilentlyContinue | Select-Object -First 1
+    $workerPid = 0
+
+    if ([int]::TryParse(($lockContent -as [string]), [ref]$workerPid) -and $workerPid -gt 0) {
+        try {
+            Get-Process -Id $workerPid -ErrorAction Stop | Out-Null
+            return $true
+        }
+        catch {
+            return $false
+        }
+    }
+
+    return $false
+}
+
+while ($true) {
+    if (Test-Path $lockFile) {
+        if (Test-WorkerProcessActive -LockFilePath $lockFile) {
+            Write-Host "Worker already running. Waiting..."
+            Start-Sleep -Seconds $PollIntervalSeconds
+            continue
+        }
+
+        Write-Host "Stale worker lock detected. Removing it."
+        Remove-Item $lockFile -Force -ErrorAction SilentlyContinue
+    }
+
+    $pendingTasks = Get-ChildItem "ai/tasks/pending" -Filter *.md -ErrorAction SilentlyContinue
+
+    if (-not $pendingTasks) {
+        Write-Host "No pending tasks found."
+        Start-Sleep -Seconds $PollIntervalSeconds
+        continue
+    }
+
+    if (-not (Get-Command codex -ErrorAction SilentlyContinue)) {
+        Write-Host "Codex CLI not found. Install and authenticate Codex before running the worker."
+        exit 1
+    }
+
+    Set-Content -Path $lockFile -Value "$PID" -NoNewline
+
+    try {
+        $startTime = Get-Date
+        codex "Follow AGENTS.md, read the platform context in ai/, and process the pending tasks without acting outside task scope."
+        $codexExitCode = $LASTEXITCODE
+        $duration = [math]::Round(((Get-Date) - $startTime).TotalSeconds, 2)
+
+        if ($codexExitCode -eq 0) {
+            Add-Content "ai/system-metrics.md" "$(Get-Date -Format s) | worker-cycle | $duration sec | success | codex-runner"
+
+            if (Test-Path "scripts/run-integration-tests.ps1") {
+                powershell -ExecutionPolicy Bypass -File "scripts/run-integration-tests.ps1"
+            }
+        }
+        else {
+            Add-Content "ai/system-metrics.md" "$(Get-Date -Format s) | worker-cycle | $duration sec | failed($codexExitCode) | codex-runner"
+        }
+    }
+    finally {
+        Remove-Item $lockFile -Force -ErrorAction SilentlyContinue
+    }
+
+    Start-Sleep -Seconds $PollIntervalSeconds
+}

scripts/run-integration-tests.ps1

@@ -0,0 +1,3 @@
+Write-Host "HLL Vietnam integration validation"
+Write-Host "No integration tests are configured for the current repository scope."
+exit 0