adaptive-agent-workflow 0.1.13

Deterministic repository intelligence and measurable Codex workflows

Adaptive Agent Workflow

Système agentique réutilisable pour Codex : intelligence incrémentale du dépôt, contexte borné par tâche, workflows sous forme de skills, télémétrie objective, replay et dashboard local. Le cœur est indépendant du langage et ne dépend que de la bibliothèque standard Python.

Capacités

• Repository Brain SQLite incrémental : seuls les fichiers nouveaux, modifiés ou supprimés sont retraités.
• Analyse déterministe Python (AST), JavaScript/TypeScript (lexicale) et fallback texte générique.
• Contexte classé par chemin, symbole, résumé et graphe d’imports, sous plafonds stricts.
• Serveur MCP local stdio : repository_sync, repository_status, repository_context, repository_symbols.
• Épisodes, événements, mémoire positive/négative et redaction défensive des secrets.
• Cycle GitHub de ticket : détection d’issue, branche depuis develop, publication validée, PR idempotente, lien réciproque et métriques dédiées.
• Routage Luna/Terra/Sol selon une complexité mesurée; model: none pour les opérations mécaniques.
• Budgets de tokens, temps, outils, retries et stagnation avec raisons d’arrêt explicites.
• Métriques JSON/CSV, rapport quotidien HTML/Markdown et comparaison J-1, 7 jours et 30 jours.
• GitHub Action quotidienne ou manuelle produisant un artefact public expurgé, sans appel modèle.
• Replay déterministe, benchmark de référence multi-risques, rapports JSON/CSV/Markdown et gates bloquants.
• Mining hebdomadaire déterministe des épisodes vers des skills candidates inactives, avec routage vers des mécanismes plus simples, détection de chevauchement et validation humaine des effets de bord.
• Scheduler parallèle déterministe : DAG d’issues, états READY/BLOCKED, risque de conflit explicable, lanes réservées et contrôle pré-intégration.
• Sept skills Codex validées, avec approbation manuelle obligatoire pour toute skill modifiant le code.
• Mode cloud auto-détecté pour les clones éphémères, avec reconstruction sans modèle et snapshots d’index portables facultatifs.

Les index, caches, épisodes, snapshots de skills, métriques et dashboards restent hors dépôt par défaut. Le chemin est AGENT_WORKFLOW_HOME s’il est défini, sinon le répertoire d’état utilisateur de la plateforme.

Installation

Prérequis : Python 3.11+ et Git.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/awf bootstrap /chemin/du/depot

Pour imposer un stockage externe :

export AGENT_WORKFLOW_HOME=/chemin/absolu/vers/agent-workflow-state

awf bootstrap <repo> --dry-run analyse sans modifier le dépôt ni l’état. --install génère un AGENTS.md spécifique et une politique non secrète .agent-workflow.json; il est idempotent, complète la configuration existante et refuse d’écraser des instructions locales. L’ancien --write-config reste disponible pour la configuration seule.

L’analyse détecte les langages, manifests, dépendances, CI, commandes canoniques et chemins générés, vendoriés ou potentiellement secrets. Elle référence uniquement les skills nécessaires et ne modifie aucun comportement produit.

La politique créée utilise base_branch: develop et auto_merge: false. awf bootstrap . --update-config propage les nouveaux champs manquants sans remplacer les personnalisations locales. Pour une tâche issue d’une issue GitHub, $adaptive-software-change publie la branche et ouvre la PR après un quality gate vert; il ne merge pas en contournant la CI, les reviews ou les protections.

Le bootstrap installe aussi les workflows non bloquants Control Tower .github/workflows/awf-episode-completed.yml et .github/workflows/awf-pr-lifecycle.yml, avec leur helper géré. La configuration additive utilise telemetry_enabled, control_tower_repository et dashboard_enabled; ce dernier prépare le dashboard sans installer de workflow Pages. Quand la télémétrie est activée, configurer manuellement dans GitHub Settings → Secrets and variables → Actions → AWF_CONTROL_TOWER_TOKEN, puis les variables AWF_CONTROL_TOWER_REPOSITORY et AWF_TELEMETRY_ENABLED. Le bootstrap ne lit ni n’écrit la valeur du secret. Une désactivation conserve les artefacts existants, n’altère pas la quality gate et ne supprime rien implicitement.

Quand dashboard_enabled vaut true, le bootstrap installe aussi .github/workflows/awf-dashboard-pages.yml. Ce workflow construit un GitHub Pages propre au repository consommateur avec le frontend versionné de Control Tower et un filtre strict sur ${{ github.repository }}. Il ne publie ni les données brutes ni celles d’un autre repository. Le token Control Tower reste limité aux checkouts privés pendant le build. Voir docs/project-dashboard.md pour la configuration, la migration et la désactivation non destructive.

Codex Web et environnements éphémères

Une fresh clone fonctionne sans installation globale, configuration utilisateur ou service externe :

PYTHONPATH=src python3 -m agentic_workflow --mode cloud runtime .
PYTHONPATH=src python3 -m agentic_workflow --mode cloud bootstrap .
PYTHONPATH=src python3 -m agentic_workflow --mode cloud context "<tâche>" --repository . --max-tokens 4000

Le mode cloud place l’état sous le répertoire temporaire de la plateforme et signale explicitement qu’il ne persistera pas. Les skills nécessaires sont versionnées dans .agents/skills. Voir le guide Codex Web pour le parcours complet et l’accélération facultative par snapshot.

Connexion à Codex

Codex prend en charge les serveurs MCP locaux stdio et partage leur configuration entre le CLI, l’extension IDE et l’application. Ajouter le serveur avec un exécutable absolu :

codex mcp add repository-brain \
  --env AGENT_WORKFLOW_HOME=/chemin/absolu/vers/agent-workflow-state \
  -- /chemin/absolu/vers/.venv/bin/awf mcp
codex mcp list

La configuration peut aussi être placée dans .codex/config.toml d’un dépôt approuvé :

[mcp_servers.repository-brain]
command = "/chemin/absolu/vers/.venv/bin/awf"
args = ["mcp"]
required = true
enabled_tools = ["repository_sync", "repository_status", "repository_context", "repository_symbols"]

[mcp_servers.repository-brain.env]
AGENT_WORKFLOW_HOME = "/chemin/absolu/vers/agent-workflow-state"

Cette syntaxe suit la documentation officielle Model Context Protocol de Codex. Codex découvre les skills de dépôt sous .agents/skills et les skills utilisateur sous ~/.agents/skills; voir Build skills.

Pour installer une version passée par le cycle de vie :

awf skill stage .agents/skills/repository-context --version 1.0.0
awf replay benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0 --output replay.json
awf skill evaluate repository-context --version 1.0.0 --replay-result replay.json
awf skill promote repository-context --version 1.0.0
awf skill activate repository-context --version 1.0.0
awf skill install repository-context

Pour adaptive-software-change, ajouter --changes-code au staging et --manual-approval à la promotion. Il n’existe aucun chemin d’auto-promotion pour une skill marquée comme modifiant le code.

Commandes principales

awf bootstrap <repo> [--dry-run | --install | --write-config | --update-config]
awf --mode cloud bootstrap <repo> [--snapshot-in index.awf-index.json.gz] [--snapshot-out index.awf-index.json.gz]
awf --mode auto runtime <repo>
awf sync <repo>
awf status <repo>
awf maintenance [--repository <repo>]
awf context "<tâche>" --repository <repo> --max-tokens 4000 --max-files 12 --seed src/app.py
awf route "<tâche>" --files 4 --languages 2 --failing-tests 1
awf budget-check --tokens 12000 --tool-calls 20
awf episode start "<tâche>" --repository <repo> --workflow-version 0.2.0 --model gpt-5.6-terra
awf episode finish <id> --outcome success --tests-passed 12 --duration-ms 42000
awf episode telemetry <id> --model-calls 2 --files-read 8 --first-test-green-ms 4200
awf episode payload <id>
awf memory add positive "<pratique vérifiée>" --repository <repo> --episode-id <id>
awf memory recall "<tâche>" --repository <repo>
awf metrics export --format json --output metrics.json --repository <repo>
awf metrics export --format csv --output episodes.csv --repository <repo>
awf daily-report --repository <repo>
awf daily-report --repository <repo> --public --output-dir <répertoire>
awf replay benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf evaluate benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf benchmark benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf benchmark benchmarks/reference_workflow.json --baseline 0.2.0 --candidate 0.3.0 --output-dir benchmark-report
awf skill --help
awf skill mine episodes.json --output-dir /etat/candidates --benchmark benchmarks/reference_workflow.json --baseline 0.2.0 --candidate 0.3.0
awf scheduler plan --repository . --input backlog.json
awf scheduler ready --repository .
awf scheduler next --repository . --lanes 4 --format json
awf scheduler integration-check 24 --repository . --develop-ref develop
awf snapshot export <fichier.awf-index.json.gz> <repo>
awf snapshot import <fichier.awf-index.json.gz> <repo>

Développement et vérification

PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python scripts/validate_skills.py
python -m compileall -q src

Les fixtures couvrent Python, TypeScript et le fallback générique. Aucun test ne requiert de réseau ni de modèle.

Documentation

• Architecture
• Exploitation, Git et automatisation
• Métriques et replay
• Codex Web et mode cloud
• Schéma JSON des datasets de replay
• Parallel Work Scheduler
• Schéma JSON des plans scheduler
• Schéma JSON du benchmark de référence

Principes de sécurité

• Ne jamais indexer les fichiers ignorés par Git, les dépendances, binaires, répertoires générés ou fichiers de plus de 1 Mo.
• Ne jamais stocker volontairement de secrets; les patterns usuels sont expurgés des épisodes et mémoires en défense supplémentaire.
• Ne jamais injecter le dépôt entier dans un contexte.
• Ne jamais invoquer un modèle pour une opération mécanique détectable.
• Ne jamais publier, pousser, promouvoir ou écraser une skill sans commande explicite.