agent-setup

Comment ça marche

agent-setup tient en deux commandes. bootstrap.sh installe une fois pour toutes les skills et les templates dans ~/.claude/ et ~/.codex/. Ensuite, dans un dépôt, /init-project ./vision.md génère l’espace de travail : agents, workflows, sprints, standards d’ingénierie et un state.json. Côté Codex, la même skill s’appelle $init-project.

Le travail se lance ensuite par sprint. /sprint 001 US-001 lit la tâche dans sprint-001.md, en déduit le workflow à partir de son champ Workflow: et enchaîne les agents. Chaque étape écrit un artefact dans .project/workflows/<run-id>/. La case de la tâche n’est cochée qu’après une vérification explicite des critères d’acceptation.

Les rôles sont des fichiers Markdown : product-owner, analyst, designer, test-writer, developer, qa-reviewer, tech-lead. Chacun a sa définition et sa mémoire. On peut en ajouter dans agent-setup/agents/specialized/ et les composer à la volée, par exemple /run-workflow analyst-tech-lead.

Dernière brique, ajoutée en mai : le mode vault. Le skill migrate déplace la vision, les sprints, les agents et les workflows dans un vault Obsidian partagé, avec une sauvegarde avant de toucher au dépôt.

Sous le capot

Depuis la v1.11, le développement est découpé en red-green-refactor entre deux rôles. Le test-writer écrit les tests et doit les voir échouer pour la bonne raison. Le developer écrit ensuite le code minimal pour les faire passer. Le qa-reviewer rend PASS ou FAIL, et le tech-lead écrit la synthèse finale. Cette séparation est le point de départ de la règle de shipyard selon laquelle le reviewer vérifie que les tests n’ont pas été affaiblis.

## Stage 3a - Red (write the failing test)
Agent: [[agents/test-writer/agent|test-writer]]
Inputs:
- `.project/workflows/<run-id>/01-analyze.md`
- `.project/workflows/<run-id>/02-design.md`
- `agent-setup/spec/engineering-standards.md` §11
Outputs:
- `.project/workflows/<run-id>/03a-red.md`
Pass:
- At least one test exists per acceptance criterion
- Every new test was run via `run-tests` (`expect-fail` mode) and observed to fail for the right reason
- Verbatim failure output is captured in the artifact
- No production code was written or modified
- Test committed alone with a `test:` Conventional Commit
OnFailure:
- Stop and document which acceptance criterion could not be expressed as a failing test

Les conditions Pass sont écrites pour un agent, pas pour un humain : une sortie d’échec copiée mot pour mot, aucun code de production touché, un commit test: isolé. Les liens [[…]] servent au vault Obsidian.

L’installation se vérifie sans rien écrire, ici vers un dossier de démonstration :

Ce que j’en retiens

• Deux CLI, c’était un coût fixe. Même avec des skills unifiées en un seul fichier, il fallait deux installations, deux syntaxes d’appel (/sprint et $sprint) et la config MCP en double, dans .mcp.json et .codex/config.toml. shipyard a choisi Claude Code seul pour pouvoir aller plus loin sur l’autonomie.
• Le Markdown structuré tient la route. Des champs Agent / Inputs / Outputs / Pass / OnFailure suffisent à rendre un workflow vérifiable. shipyard a repris tel quel le renderer, les templates, les rôles et state.json.
• Il restait un humain dans la boucle. C’était moi qui lançais chaque sprint et chaque workflow, et l’enchaînement des étapes reposait sur le modèle qui lisait la skill. C’est précisément ce que shipyard remplace par un script déterministe.