chore: integrate AI development platform into HLL Vietnam project

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.