api/.ai-workflow/workflow.md

Developer AI Workflow

This directory is the canonical source of truth for the repository's developer-facing AI workflow.

Goals

• Keep Codex, AI Assistant, Junie, and Copilot aligned from one maintained source.
• Make assistant metadata deterministic so the generated files can be rewritten safely and checked in CI.
• Preserve the current mirror-repo workflow for backend-php and front-end-vue.
• Keep all changes in this workflow scoped to developer tooling and documentation. Runtime OpenAI features stay out of scope.

Supported Assistants

• Codex: local environments and actions under .codex/environments.
• AI Assistant: generated guidance under .aiassistant/rules.
• Junie: generated project guidance under .junie/guidelines.md.
• Copilot: standardized issue-dispatch workflow content under .github/workflows/copilot.yml.

Global Rules

1. Change only .ai-workflow/workflow.md and .ai-workflow/manifest.json when updating the developer AI workflow.
2. Regenerate all derived files with node scripts/sync-ai-workflow.mjs --write.
3. Validate drift with node scripts/sync-ai-workflow.mjs --check.
4. Generated assistant files are not hand-edited.
5. Unsupported surfaces stay unsupported until they have a real owner and a real config.
6. front-end-vue/.ai/mcp/mcp.json is intentionally unsupported and should not be recreated until there is an actual MCP integration to maintain.

Command Matrix

backend-php

• Setup: use the existing setup scripts in backend-php/scripts.
• Run: start the API stack with traefik, redis, mysql-debug, php1, and caddy.
• Debug: tail php1 logs.
• PHP verification: always run backend validation in the php1 container.
• Unit tests: docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:unit".
• Integration tests: docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:integration".
• API tests: docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:api".

front-end-vue

• Setup: npm ci and npx playwright install.
• Run: npm run dev.
• Unit tests: npm run test:unit with Vitest.
• Browser smoke: npm run test:e2e:smoke.
• Browser full suite: npm run test:e2e:ci.
• Debug: npx playwright test --debug.
• Browser validation is Playwright-first. WebdriverIO and Appium are not part of the supported workflow.

automation

• Setup: npm ci and npx playwright install.
• Run: npx playwright test --ui.
• Browser tests: npx playwright test.
• Debug: npx playwright test --debug.

Mirror Repos And Sync

• backend-php mirrors to C:\Users\2jepp\PhpstormProjects\api.
• front-end-vue mirrors to C:\Users\2jepp\WebstormProjects\pleno-vue.
• Supported metadata directories that must stay mirrored are .codex, .aiassistant, .junie, .github, generated .ai-workflow, and scripts/sync-ai-workflow.mjs.
• Cache and build directories remain excluded from the watcher.
• The mirror repos receive generated snapshots of .ai-workflow and scripts/sync-ai-workflow.mjs so their local CI can run --check without depending on the combined workspace root.

Generated Outputs

• Root Codex environment for combined backend and frontend entrypoints.
• Backend and frontend Codex environments.
• Backend and frontend AI Assistant guidance.
• Backend and frontend Junie guidance.
• Backend Copilot dispatcher workflow.
• Backend and frontend snapshot copies of .ai-workflow plus scripts/sync-ai-workflow.mjs for mirrored repositories.