From a82a90a1b43715467d6819194d1ec0f385ff1c03 Mon Sep 17 00:00:00 2001 From: devRaGonSa Date: Thu, 19 Mar 2026 10:57:24 +0100 Subject: [PATCH] chore: integrate AI development platform into HLL Vietnam project --- .github/workflows/codex-worker.yml | 33 ++++++ AGENTS.md | 104 ++++++++++++++++-- ai/README.md | 23 +++- ai/architecture-index.md | 58 ++++++++++ ai/orchestrator/README.md | 21 +++- ai/orchestrator/analyst.md | 30 +++++ ai/orchestrator/backend-senior.md | 30 +++++ ai/orchestrator/component-discovery.md | 20 ++++ ai/orchestrator/database-architect.md | 30 +++++ ai/orchestrator/di-analysis.md | 11 ++ ai/orchestrator/feature-planner.md | 20 ++++ ai/orchestrator/frontend-senior.md | 30 +++++ ai/orchestrator/graphic-designer.md | 30 +++++ ai/orchestrator/planning-memory.md | 12 ++ ai/orchestrator/pm.md | 30 +++++ ai/orchestrator/python-architect.md | 30 +++++ ai/orchestrator/repo-reviewer.md | 12 ++ ai/orchestrator/ui-expert.md | 30 +++++ ai/prompts/plan-feature.md | 26 +++++ ai/repo-context.md | 84 ++++++++++++++ ai/system-metrics.md | 15 +++ ai/task-template.md | 65 +++++++++++ .../TASK-001-platform-readiness-check.md | 48 ++++++++ docs/decisions.md | 4 + docs/project-overview.md | 1 + install-ai-platform.ps1 | 8 ++ scripts/codex-runner.ps1 | 83 ++++++++++++++ scripts/run-integration-tests.ps1 | 3 + 28 files changed, 874 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/codex-worker.yml create mode 100644 ai/architecture-index.md create mode 100644 ai/orchestrator/analyst.md create mode 100644 ai/orchestrator/backend-senior.md create mode 100644 ai/orchestrator/component-discovery.md create mode 100644 ai/orchestrator/database-architect.md create mode 100644 ai/orchestrator/di-analysis.md create mode 100644 ai/orchestrator/feature-planner.md create mode 100644 ai/orchestrator/frontend-senior.md create mode 100644 ai/orchestrator/graphic-designer.md create mode 100644 ai/orchestrator/planning-memory.md create mode 100644 ai/orchestrator/pm.md create mode 100644 ai/orchestrator/python-architect.md create mode 100644 ai/orchestrator/repo-reviewer.md create mode 100644 ai/orchestrator/ui-expert.md create mode 100644 ai/prompts/plan-feature.md create mode 100644 ai/repo-context.md create mode 100644 ai/system-metrics.md create mode 100644 ai/task-template.md create mode 100644 ai/tasks/pending/TASK-001-platform-readiness-check.md create mode 100644 install-ai-platform.ps1 create mode 100644 scripts/codex-runner.ps1 create mode 100644 scripts/run-integration-tests.ps1 diff --git a/.github/workflows/codex-worker.yml b/.github/workflows/codex-worker.yml new file mode 100644 index 0000000..2767fb5 --- /dev/null +++ b/.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." diff --git a/AGENTS.md b/AGENTS.md index 02f6cc0..3af7f2b 100644 --- a/AGENTS.md +++ b/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 -- Diseñador gráfico +- Arquitecto Python +- 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. -- Documentar las decisiones importantes en `docs/decisions.md`. -- Hacer cambios pequeños, verificables y fáciles de revisar. -- Mantener coherencia visual con una identidad militar, Vietnam y táctica. -- Considerar Python como backend principal previsto del proyecto. -- No introducir frameworks o complejidad innecesaria en esta fase inicial. +- `ai/orchestrator/` + +## Rules + +- Do not break repository structure without explicit technical justification. +- 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. diff --git a/ai/README.md b/ai/README.md index 00b1b39..ac37239 100644 --- a/ai/README.md +++ b/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. diff --git a/ai/architecture-index.md b/ai/architecture-index.md new file mode 100644 index 0000000..899e252 --- /dev/null +++ b/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. diff --git a/ai/orchestrator/README.md b/ai/orchestrator/README.md index dd37a75..ec07318 100644 --- a/ai/orchestrator/README.md +++ b/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. diff --git a/ai/orchestrator/analyst.md b/ai/orchestrator/analyst.md new file mode 100644 index 0000000..9815452 --- /dev/null +++ b/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 diff --git a/ai/orchestrator/backend-senior.md b/ai/orchestrator/backend-senior.md new file mode 100644 index 0000000..4d51301 --- /dev/null +++ b/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 diff --git a/ai/orchestrator/component-discovery.md b/ai/orchestrator/component-discovery.md new file mode 100644 index 0000000..dd56905 --- /dev/null +++ b/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. diff --git a/ai/orchestrator/database-architect.md b/ai/orchestrator/database-architect.md new file mode 100644 index 0000000..b0745ec --- /dev/null +++ b/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 diff --git a/ai/orchestrator/di-analysis.md b/ai/orchestrator/di-analysis.md new file mode 100644 index 0000000..5770c31 --- /dev/null +++ b/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. diff --git a/ai/orchestrator/feature-planner.md b/ai/orchestrator/feature-planner.md new file mode 100644 index 0000000..576a25e --- /dev/null +++ b/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. diff --git a/ai/orchestrator/frontend-senior.md b/ai/orchestrator/frontend-senior.md new file mode 100644 index 0000000..3f4ce0c --- /dev/null +++ b/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 diff --git a/ai/orchestrator/graphic-designer.md b/ai/orchestrator/graphic-designer.md new file mode 100644 index 0000000..878fbfd --- /dev/null +++ b/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 diff --git a/ai/orchestrator/planning-memory.md b/ai/orchestrator/planning-memory.md new file mode 100644 index 0000000..c36659f --- /dev/null +++ b/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. diff --git a/ai/orchestrator/pm.md b/ai/orchestrator/pm.md new file mode 100644 index 0000000..bb72f33 --- /dev/null +++ b/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 diff --git a/ai/orchestrator/python-architect.md b/ai/orchestrator/python-architect.md new file mode 100644 index 0000000..0bf5936 --- /dev/null +++ b/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 diff --git a/ai/orchestrator/repo-reviewer.md b/ai/orchestrator/repo-reviewer.md new file mode 100644 index 0000000..291b2a5 --- /dev/null +++ b/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. diff --git a/ai/orchestrator/ui-expert.md b/ai/orchestrator/ui-expert.md new file mode 100644 index 0000000..d1df4f5 --- /dev/null +++ b/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 diff --git a/ai/prompts/plan-feature.md b/ai/prompts/plan-feature.md new file mode 100644 index 0000000..c50e301 --- /dev/null +++ b/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. diff --git a/ai/repo-context.md b/ai/repo-context.md new file mode 100644 index 0000000..98a0687 --- /dev/null +++ b/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` diff --git a/ai/system-metrics.md b/ai/system-metrics.md new file mode 100644 index 0000000..7e8fe59 --- /dev/null +++ b/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 diff --git a/ai/task-template.md b/ai/task-template.md new file mode 100644 index 0000000..a472e8f --- /dev/null +++ b/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. diff --git a/ai/tasks/pending/TASK-001-platform-readiness-check.md b/ai/tasks/pending/TASK-001-platform-readiness-check.md new file mode 100644 index 0000000..3c72b6a --- /dev/null +++ b/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. diff --git a/docs/decisions.md b/docs/decisions.md index bfbec68..e0b6dbf 100644 --- a/docs/decisions.md +++ b/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. diff --git a/docs/project-overview.md b/docs/project-overview.md index 42726cc..43fd3ce 100644 --- a/docs/project-overview.md +++ b/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 diff --git a/install-ai-platform.ps1 b/install-ai-platform.ps1 new file mode 100644 index 0000000..2e6e26d --- /dev/null +++ b/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." diff --git a/scripts/codex-runner.ps1 b/scripts/codex-runner.ps1 new file mode 100644 index 0000000..81f046e --- /dev/null +++ b/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 +} diff --git a/scripts/run-integration-tests.ps1 b/scripts/run-integration-tests.ps1 new file mode 100644 index 0000000..0097111 --- /dev/null +++ b/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