chore: integrate AI development platform into HLL Vietnam project

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