linkweb-public/linkweb-ai-toolkit
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

PRD: pilotage agentique local et revue générique #1

New issue
Open
opened 2026-06-28 21:00:49 +02:00 by olivier.drieux · 0 comments
olivier.drieux commented 2026-06-28 21:00:49 +02:00
Owner
Copy link

Problem Statement

Le workflow agentique actuel est puissant, mais il demande à l'utilisateur de connaître et d'enchaîner plusieurs briques séparées : cadrage, production d'un dossier, découpage en chantiers, lancement de missions, revue, contrôle visuel, intégration. Cette séquence est trop technique, trop facile à oublier, et expose trop de détails internes à un utilisateur impatient ou non technique.

Le même problème existe côté revue : le plugin actuel de revue s'appelle comme s'il ne savait traiter que plusieurs PR, alors que son rôle réel est plus large : relire une PR, une branche, une plage de commits, un diff, ou un lot assemblé. Le nom actuel rend sa réutilisation par le futur pilotage moins claire.

Le besoin est donc double : renommer et généraliser la brique de revue, puis ajouter une commande unique de pilotage capable de cadrer, découper, déléguer, suivre, assembler, vérifier et intégrer des lots de travail sans exposer le jargon technique.

Solution

Renommer le plugin de revue existant en agent-review, avec la commande publique /review, sans alias de compatibilité. Ce plugin devient la brique générale de revue agentique pour PR, branches, diffs et lots.

Ajouter ensuite un plugin dual-runtime linkweb-pilotage, avec une seule entrée publique /pilotage. Le plugin orchestre le workflow complet en français courant : cadrage, dossier de cadrage, chantiers locaux, missions, lots, revue, contrôle visuel, preuve d'usage quand applicable, intégration finale et nettoyage.

Le pilotage travaille localement pour le cadrage et les chantiers : aucun ticket distant n'est créé. Les dossiers de pilotage sont stockés hors dépôt dans l'espace agent, afin de survivre aux compactages et reprises sans polluer le dépôt. La forge n'est utilisée que pour l'intégration finale du code quand les outils Linkweb existants s'appliquent ; sinon le plugin fournit un résumé prêt à publier manuellement.

User Stories

  1. As a non-technical project owner, I want to launch one command for a new piece of work, so that I do not have to remember the sequence of agent skills.
  2. As a non-technical project owner, I want the assistant to ask one clear framing question at a time, so that I can make decisions without reading a long questionnaire.
  3. As a non-technical project owner, I want every framing question to include a recommendation, so that I can decide quickly instead of designing the workflow myself.
  4. As a non-technical project owner, I want the assistant to use ordinary French words, so that I do not have to understand PRD, issue, thread, merge, or review jargon.
  5. As a non-technical project owner, I want the assistant to keep technical skill names hidden, so that the workflow feels like one coherent pilotage rather than a chain of tools.
  6. As a non-technical project owner, I want the assistant to propose whether the work is simple or complete, so that I understand the expected level of process before it starts.
  7. As a non-technical project owner, I want to validate the simple or complete route before work starts, so that the assistant does not over-process a small task or under-process a complex one.
  8. As a non-technical project owner, I want to grant a clear mandate for a lot of work, so that I do not have to confirm every mechanical integration step.
  9. As a non-technical project owner, I want the assistant to return only when my judgment is needed or when a meaningful milestone is reached, so that I am not overwhelmed by logs.
  10. As a non-technical project owner, I want multiple independent decisions grouped only when useful, so that I am not forced through an unnecessarily long sequence of tiny prompts.
  11. As a non-technical project owner, I want the assistant to write a living framing draft during the questions, so that decisions are not lost if the conversation compacts or stops.
  12. As a non-technical project owner, I want the final framing dossier to mirror decisions already made, so that I am not asked to re-read and re-approve the same content.
  13. As an agent running a mission, I want a stable framing dossier, so that I can implement from validated context instead of relying on the parent conversation memory.
  14. As an agent running a mission, I want each local chantier to include objective, decisions, acceptance criteria, dependencies, and state, so that I can deliver a vertical, verifiable slice.
  15. As an orchestrator, I want chantiers to stay local, so that the pilotage does not depend on Forgejo, GitHub, GitLab, or remote issue tracker configuration.
  16. As an orchestrator, I want pilotage state outside the repository, so that operational notes and mission state do not pollute commits.
  17. As an orchestrator, I want to resume an active pilotage from local state, so that the workflow survives conversation shutdowns and runtime interruptions.
  18. As an orchestrator, I want to use a runtime long-running goal capability after mandate validation, so that I can wait for missions and continue orchestration without stopping prematurely.
  19. As an orchestrator, I want to refuse multi-mission pilotage when the runtime cannot stay alive or resume, so that I do not pretend to supervise work I cannot actually follow.
  20. As an orchestrator, I want each mission on a temporary branch, so that parallel work is isolated and rejected work does not pollute the final lot.
  21. As an orchestrator, I want one final branch per lot, so that the user and reviewers see one coherent integration request instead of many mission-level requests.
  22. As an orchestrator, I want to assemble validated missions by cherry-picking their commits, so that the final lot history stays readable and selective.
  23. As an orchestrator, I want to run a lightweight mission review before assembly, so that obviously unsafe work is rejected before it enters the lot branch.
  24. As an orchestrator, I want to run a complete review on the assembled lot, so that integration is judged on the final code that will actually ship.
  25. As an orchestrator, I want to use the general review plugin for branches, diffs, PRs and lots, so that review behavior is centralized instead of duplicated.
  26. As an orchestrator, I want the review plugin to be named generically, so that its purpose is clear outside multi-PR scenarios.
  27. As a reviewer, I want the review command to be /review, so that the command matches the actual scope of PR, branch, diff, and lot review.
  28. As a maintainer, I want the old multi-pr-review name removed without alias, so that there is one clear public contract after the breaking rename.
  29. As a maintainer, I want generated plugin surfaces to be updated from the TypeScript source, so that Claude, Codex, marketplace entries, and wrappers stay synchronized.
  30. As a maintainer, I want plugin manifests bumped correctly, so that installed plugin versions reflect renamed or added capabilities.
  31. As a project owner, I want UI lots to trigger visual verification at lot level, so that I can judge the assembled result instead of scattered mission fragments.
  32. As a project owner, I want objective interactive proof when acceptance criteria require it, so that behavior like clicking, submitting, or opening a modal can be validated when configured.
  33. As a project owner, I want visible skips for non-testable interactive proof, so that the assistant never silently claims behavior was verified.
  34. As a project owner, I want the assistant to ask for my eye on semantic UI fit, so that the agent does not judge its own visual output.
  35. As a project owner, I want accepted lots integrated automatically within the mandate, so that I am not asked to approve technical steps I cannot evaluate.
  36. As a project owner, I want the assistant to stop for new business decisions, data-risk decisions, authorization decisions, payment decisions, visual judgment, or out-of-scope changes, so that delegation does not become uncontrolled autonomy.
  37. As a project owner, I want unfinished chantiers to be marked delivered, abandoned, or on hold, so that pilotage can end cleanly without hiding unresolved work.
  38. As a project owner, I want abandonment and on-hold decisions to require explicit confirmation, so that the assistant does not silently drop work.
  39. As a project owner, I want on-hold chantiers to resume later from the same pilotage dossier, so that delayed work does not need to be recreated from scratch.
  40. As a project owner, I want local branches cleaned after a validated lot, so that temporary mission branches do not clutter the repository.
  41. As a maintainer, I want linkweb-pilotage to embed stable variants of the existing framing and chantier contracts, so that personal, unversioned skills cannot disappear and break the workflow.
  42. As a maintainer, I want pilotage to depend on versioned review and visual verification plugins where appropriate, so that shared behavior remains canonical.
  43. As a maintainer, I want pilotage to fail closed when a required versioned dependency is missing, so that it does not silently degrade into an unsafe workflow.
  44. As a user, I want /pilotage without subcommands, so that I do not have to learn a mini-CLI.
  45. As a user, I want natural-language follow-ups like status, detail, export, resume, or stop, so that the command surface remains simple.

Implementation Decisions

  • Implement agent-review first, then build linkweb-pilotage on top of the renamed review contract.
  • Rename the existing multi-pr-review plugin to agent-review as a breaking public contract change.
  • Rename the public review command from /review-prs to /review, with no compatibility alias.
  • Rename internal reviewer agents and coordinator names away from the multi-pr prefix to the agent-review vocabulary.
  • Update generated surfaces from the TypeScript generator rather than hand-editing generated manifests or marketplace entries.
  • Bump the renamed review plugin with a major version because command names, skill names, plugin name, and agent names change incompatibly.
  • Create linkweb-pilotage as a dual-runtime plugin for Codex and Claude.
  • Expose exactly one public pilotage command: /pilotage.
  • Do not expose public subcommands for pilotage. Natural-language requests are handled in the conversation.
  • Auto-invocation may start only the intake and framing behavior. Any visible mutation or long-running mandate requires explicit confirmation.
  • Pilotage public language is French, concise, and non-technical. Internal names such as PRD, issue, thread, merge, and skill names are hidden unless the user explicitly asks for technical detail.
  • Pilotage uses public vocabulary such as cadrage, dossier de cadrage, chantier, mission, lot, revue, intégration, contrôle visuel, and preuve d'usage.
  • The plugin embeds stable internal variants of the existing to-prd and to-issues contracts rather than depending on personal unversioned skills.
  • The embedded dossier contract remains a conservative fork of to-prd: problem, solution, user stories, implementation decisions, testing decisions, out of scope, and notes remain available for agents.
  • The embedded chantier contract remains a conservative fork of to-issues: vertical slices, dependencies, acceptance criteria, and ready-for-agent style clarity remain central.
  • The dossier and chantiers are local, not remote tracker issues.
  • Pilotage does not create Forgejo, GitHub, or GitLab tickets for chantiers.
  • Pilotage stores operational state outside the repository under the user's agent workspace, not in the project worktree.
  • The out-of-repo pilotage dossier contains a living draft, final dossier, local chantiers, mission summaries, state, and completion markers.
  • The framing draft is written incrementally from the first framing question to protect against compaction and conversation interruption.
  • The final dossier is a mirror of validated framing, not a document that requires a second full human review.
  • Framing asks one question at a time, always with a recommendation, and searches the codebase instead of asking when the answer is discoverable.
  • During active pilotage, up to three independent decisions may be grouped if that is more concise and does not confuse dependencies.
  • Simple route means one chantier and one mission, but still writes a minimal dossier before launch.
  • Complete route means dossier, local chantiers, dependency-aware lots, and multiple missions over time.
  • The orchestrator proposes simple or complete routing and waits for user confirmation before launching visible or long-running work.
  • Any mission launch, simple or complete, requires the runtime long-running goal capability after mandate validation.
  • The long-running runtime capability is not packaged as a skill dependency; pilotage supplies the mandate/gabarit and uses the runtime mechanism when available.
  • If runtime continuity is unavailable, pilotage refuses true mission orchestration and reports that only framing can be performed.
  • Sub-agents should not interact directly with the human. They record blocks in their summaries and go idle.
  • The orchestrator is the only human-facing channel during pilotage.
  • A blocked mission parks its chantier and descendants but does not stop unrelated lots.
  • Local clarification may be asked inline; wider decision forks recommend targeted framing and keep affected work paused.
  • Work invalidated by a new decision is normally sent back to the relevant mission or lot as findings to correct, not discarded automatically.
  • Mission branches are temporary and follow existing branch-guard naming conventions. No codex, claude, agent, ai, or issue-prefixed branch naming is introduced.
  • The lot branch is the only branch intended for final integration request by default.
  • Missions are assembled into the lot branch through cherry-pick of validated commits in dependency order.
  • Rejected or blocked mission commits are not cherry-picked into the lot branch.
  • After a lot is integrated, temporary local mission branches and unnecessary lot branches are cleaned if all commits are safely integrated or preserved elsewhere.
  • The pilotage dossier remains after delivery and is marked completed rather than deleted automatically.
  • A lot touching UI requires lot-level visual verification before integration.
  • Visual verification remains human-judged for semantic fit and must not become an automatic visual verdict.
  • Interactive proof is a separate layer driven by acceptance criteria; it is objective when configured and visibly skipped when not possible.
  • Interactive proof requires declared project configuration such as dev command or served URL, ready check, base URL, seed/fixture command, and session/cookie auth fixture when needed.
  • Missing interactive capability is reported as a visible skip, not a silent pass.
  • Integration finalization uses existing Linkweb tools when compatible, especially /pr and tea on Forgejo Linkweb projects.
  • For other forges or missing tools, pilotage prepares a manual integration summary and stops before publishing or merging.
  • The review plugin remains the general review brique for lots, including branches and diffs, not just PRs.
  • Publication or merge behavior remains limited by available tooling and explicit mandate boundaries.
  • Final pilotage states visible to the user are delivered, abandoned, and on hold.
  • Abandoned and on-hold states require explicit user confirmation.
  • User-facing progress defaults to a minimal dashboard: what advanced, what is blocked, what needs human judgment, and the next step.

Testing Decisions

  • The highest useful seam for agent-review is the generated plugin surface plus command/skill/agent file layout. A successful change should regenerate Claude and Codex manifests, marketplace entries, and wrappers from the TypeScript source, then pass the surfaces check.
  • The highest useful seam for linkweb-pilotage is the skill contract and generated plugin surface. The test should verify that the plugin installs the expected command, skill, manifests, marketplace entry, and any agent wrappers without requiring real mission execution.
  • Existing surface generation commands are the primary regression checks: surfaces write followed by surfaces check.
  • Manifest version checks must cover both Codex and Claude plugin manifests for any modified plugin tree.
  • Rename verification must search the repository for stale public references to multi-pr-review, /review-prs, and Multi PR Review. Any remaining mention should be intentional and documented only if a changelog or migration note is explicitly added.
  • Pilotage verification must search for accidental public jargon in user-facing command descriptions and README text, especially PRD, issue, thread, merge, multi-pr-review, and internal skill names.
  • Pilotage verification must check that no generated surfaces were hand-edited without corresponding generator changes.
  • Pilotage verification must check that local-state paths point outside the repository and that prompts for mission handoff do not embed absolute repository paths by default.
  • Review workflow verification should cover branch or diff review mode, not only PR review mode, because the renamed plugin is intended to be generic.
  • Integration behavior should be tested at the contract level: compatible Linkweb Forgejo repos may use existing /pr and tea flow; non-compatible repos must stop with a manual summary instead of attempting gh, glab, or raw HTTP.
  • The pilotage skill should include explicit failure paths for missing versioned dependencies and missing runtime continuity.
  • UI verification behavior should be tested by contract: lot-level visual verification is required for UI lots, while semantic visual acceptance remains human-facing.
  • Interactive proof behavior should be tested by contract: acceptance criteria can drive objective interactions when configuration exists, and missing configuration produces a visible skip.

Out of Scope

  • Do not implement the rename and pilotage in the same unreviewable change if the work can be split safely.
  • Do not keep /review-prs as an alias.
  • Do not create remote tracker tickets for pilotage chantiers.
  • Do not add GitHub or GitLab issue adapters for pilotage chantiers.
  • Do not publish, merge, deploy, or send external notifications from auto-invocation alone.
  • Do not expose pilotage subcommands such as /pilotage statut, /pilotage reprendre, or /pilotage nettoyer.
  • Do not put pilotage state inside the project repository by default.
  • Do not ask the user to re-read the full dossier after every framing session.
  • Do not let sub-threads talk directly to the human.
  • Do not create PRs per mission by default.
  • Do not use agent/vendor branch prefixes for mission branches.
  • Do not make visual verification an automatic semantic verdict.
  • Do not make persistent e2e tests the default output of interactive proof.
  • Do not broaden linkweb-workflow or /pr to GitHub or GitLab as part of this PRD.
  • Do not hand-edit generated manifests or marketplaces without updating the generator.

Further Notes

Implementation order is part of the product decision: agent-review first, linkweb-pilotage second. The pilotage plugin should be able to depend on the final generic review naming from the start.

The user-facing product principle is that trust is placed in the mandate and framing, not in repeated low-value confirmations. The assistant should stop for real decisions and risks, not for mechanical steps the user cannot reasonably evaluate.

The design intentionally treats impatient users as the default. Normal output should be a compact dashboard, not execution logs.

The local pilotage dossier is an agent memory artifact, not project documentation. It may be exported only on explicit request.

The current repository is detached HEAD in this worktree during PRD creation. That does not affect issue publication, but implementation work should run branch-guard before edits.

## Problem Statement Le workflow agentique actuel est puissant, mais il demande à l'utilisateur de connaître et d'enchaîner plusieurs briques séparées : cadrage, production d'un dossier, découpage en chantiers, lancement de missions, revue, contrôle visuel, intégration. Cette séquence est trop technique, trop facile à oublier, et expose trop de détails internes à un utilisateur impatient ou non technique. Le même problème existe côté revue : le plugin actuel de revue s'appelle comme s'il ne savait traiter que plusieurs PR, alors que son rôle réel est plus large : relire une PR, une branche, une plage de commits, un diff, ou un lot assemblé. Le nom actuel rend sa réutilisation par le futur pilotage moins claire. Le besoin est donc double : renommer et généraliser la brique de revue, puis ajouter une commande unique de pilotage capable de cadrer, découper, déléguer, suivre, assembler, vérifier et intégrer des lots de travail sans exposer le jargon technique. ## Solution Renommer le plugin de revue existant en agent-review, avec la commande publique /review, sans alias de compatibilité. Ce plugin devient la brique générale de revue agentique pour PR, branches, diffs et lots. Ajouter ensuite un plugin dual-runtime linkweb-pilotage, avec une seule entrée publique /pilotage. Le plugin orchestre le workflow complet en français courant : cadrage, dossier de cadrage, chantiers locaux, missions, lots, revue, contrôle visuel, preuve d'usage quand applicable, intégration finale et nettoyage. Le pilotage travaille localement pour le cadrage et les chantiers : aucun ticket distant n'est créé. Les dossiers de pilotage sont stockés hors dépôt dans l'espace agent, afin de survivre aux compactages et reprises sans polluer le dépôt. La forge n'est utilisée que pour l'intégration finale du code quand les outils Linkweb existants s'appliquent ; sinon le plugin fournit un résumé prêt à publier manuellement. ## User Stories 1. As a non-technical project owner, I want to launch one command for a new piece of work, so that I do not have to remember the sequence of agent skills. 2. As a non-technical project owner, I want the assistant to ask one clear framing question at a time, so that I can make decisions without reading a long questionnaire. 3. As a non-technical project owner, I want every framing question to include a recommendation, so that I can decide quickly instead of designing the workflow myself. 4. As a non-technical project owner, I want the assistant to use ordinary French words, so that I do not have to understand PRD, issue, thread, merge, or review jargon. 5. As a non-technical project owner, I want the assistant to keep technical skill names hidden, so that the workflow feels like one coherent pilotage rather than a chain of tools. 6. As a non-technical project owner, I want the assistant to propose whether the work is simple or complete, so that I understand the expected level of process before it starts. 7. As a non-technical project owner, I want to validate the simple or complete route before work starts, so that the assistant does not over-process a small task or under-process a complex one. 8. As a non-technical project owner, I want to grant a clear mandate for a lot of work, so that I do not have to confirm every mechanical integration step. 9. As a non-technical project owner, I want the assistant to return only when my judgment is needed or when a meaningful milestone is reached, so that I am not overwhelmed by logs. 10. As a non-technical project owner, I want multiple independent decisions grouped only when useful, so that I am not forced through an unnecessarily long sequence of tiny prompts. 11. As a non-technical project owner, I want the assistant to write a living framing draft during the questions, so that decisions are not lost if the conversation compacts or stops. 12. As a non-technical project owner, I want the final framing dossier to mirror decisions already made, so that I am not asked to re-read and re-approve the same content. 13. As an agent running a mission, I want a stable framing dossier, so that I can implement from validated context instead of relying on the parent conversation memory. 14. As an agent running a mission, I want each local chantier to include objective, decisions, acceptance criteria, dependencies, and state, so that I can deliver a vertical, verifiable slice. 15. As an orchestrator, I want chantiers to stay local, so that the pilotage does not depend on Forgejo, GitHub, GitLab, or remote issue tracker configuration. 16. As an orchestrator, I want pilotage state outside the repository, so that operational notes and mission state do not pollute commits. 17. As an orchestrator, I want to resume an active pilotage from local state, so that the workflow survives conversation shutdowns and runtime interruptions. 18. As an orchestrator, I want to use a runtime long-running goal capability after mandate validation, so that I can wait for missions and continue orchestration without stopping prematurely. 19. As an orchestrator, I want to refuse multi-mission pilotage when the runtime cannot stay alive or resume, so that I do not pretend to supervise work I cannot actually follow. 20. As an orchestrator, I want each mission on a temporary branch, so that parallel work is isolated and rejected work does not pollute the final lot. 21. As an orchestrator, I want one final branch per lot, so that the user and reviewers see one coherent integration request instead of many mission-level requests. 22. As an orchestrator, I want to assemble validated missions by cherry-picking their commits, so that the final lot history stays readable and selective. 23. As an orchestrator, I want to run a lightweight mission review before assembly, so that obviously unsafe work is rejected before it enters the lot branch. 24. As an orchestrator, I want to run a complete review on the assembled lot, so that integration is judged on the final code that will actually ship. 25. As an orchestrator, I want to use the general review plugin for branches, diffs, PRs and lots, so that review behavior is centralized instead of duplicated. 26. As an orchestrator, I want the review plugin to be named generically, so that its purpose is clear outside multi-PR scenarios. 27. As a reviewer, I want the review command to be /review, so that the command matches the actual scope of PR, branch, diff, and lot review. 28. As a maintainer, I want the old multi-pr-review name removed without alias, so that there is one clear public contract after the breaking rename. 29. As a maintainer, I want generated plugin surfaces to be updated from the TypeScript source, so that Claude, Codex, marketplace entries, and wrappers stay synchronized. 30. As a maintainer, I want plugin manifests bumped correctly, so that installed plugin versions reflect renamed or added capabilities. 31. As a project owner, I want UI lots to trigger visual verification at lot level, so that I can judge the assembled result instead of scattered mission fragments. 32. As a project owner, I want objective interactive proof when acceptance criteria require it, so that behavior like clicking, submitting, or opening a modal can be validated when configured. 33. As a project owner, I want visible skips for non-testable interactive proof, so that the assistant never silently claims behavior was verified. 34. As a project owner, I want the assistant to ask for my eye on semantic UI fit, so that the agent does not judge its own visual output. 35. As a project owner, I want accepted lots integrated automatically within the mandate, so that I am not asked to approve technical steps I cannot evaluate. 36. As a project owner, I want the assistant to stop for new business decisions, data-risk decisions, authorization decisions, payment decisions, visual judgment, or out-of-scope changes, so that delegation does not become uncontrolled autonomy. 37. As a project owner, I want unfinished chantiers to be marked delivered, abandoned, or on hold, so that pilotage can end cleanly without hiding unresolved work. 38. As a project owner, I want abandonment and on-hold decisions to require explicit confirmation, so that the assistant does not silently drop work. 39. As a project owner, I want on-hold chantiers to resume later from the same pilotage dossier, so that delayed work does not need to be recreated from scratch. 40. As a project owner, I want local branches cleaned after a validated lot, so that temporary mission branches do not clutter the repository. 41. As a maintainer, I want linkweb-pilotage to embed stable variants of the existing framing and chantier contracts, so that personal, unversioned skills cannot disappear and break the workflow. 42. As a maintainer, I want pilotage to depend on versioned review and visual verification plugins where appropriate, so that shared behavior remains canonical. 43. As a maintainer, I want pilotage to fail closed when a required versioned dependency is missing, so that it does not silently degrade into an unsafe workflow. 44. As a user, I want /pilotage without subcommands, so that I do not have to learn a mini-CLI. 45. As a user, I want natural-language follow-ups like status, detail, export, resume, or stop, so that the command surface remains simple. ## Implementation Decisions - Implement agent-review first, then build linkweb-pilotage on top of the renamed review contract. - Rename the existing multi-pr-review plugin to agent-review as a breaking public contract change. - Rename the public review command from /review-prs to /review, with no compatibility alias. - Rename internal reviewer agents and coordinator names away from the multi-pr prefix to the agent-review vocabulary. - Update generated surfaces from the TypeScript generator rather than hand-editing generated manifests or marketplace entries. - Bump the renamed review plugin with a major version because command names, skill names, plugin name, and agent names change incompatibly. - Create linkweb-pilotage as a dual-runtime plugin for Codex and Claude. - Expose exactly one public pilotage command: /pilotage. - Do not expose public subcommands for pilotage. Natural-language requests are handled in the conversation. - Auto-invocation may start only the intake and framing behavior. Any visible mutation or long-running mandate requires explicit confirmation. - Pilotage public language is French, concise, and non-technical. Internal names such as PRD, issue, thread, merge, and skill names are hidden unless the user explicitly asks for technical detail. - Pilotage uses public vocabulary such as cadrage, dossier de cadrage, chantier, mission, lot, revue, intégration, contrôle visuel, and preuve d'usage. - The plugin embeds stable internal variants of the existing to-prd and to-issues contracts rather than depending on personal unversioned skills. - The embedded dossier contract remains a conservative fork of to-prd: problem, solution, user stories, implementation decisions, testing decisions, out of scope, and notes remain available for agents. - The embedded chantier contract remains a conservative fork of to-issues: vertical slices, dependencies, acceptance criteria, and ready-for-agent style clarity remain central. - The dossier and chantiers are local, not remote tracker issues. - Pilotage does not create Forgejo, GitHub, or GitLab tickets for chantiers. - Pilotage stores operational state outside the repository under the user's agent workspace, not in the project worktree. - The out-of-repo pilotage dossier contains a living draft, final dossier, local chantiers, mission summaries, state, and completion markers. - The framing draft is written incrementally from the first framing question to protect against compaction and conversation interruption. - The final dossier is a mirror of validated framing, not a document that requires a second full human review. - Framing asks one question at a time, always with a recommendation, and searches the codebase instead of asking when the answer is discoverable. - During active pilotage, up to three independent decisions may be grouped if that is more concise and does not confuse dependencies. - Simple route means one chantier and one mission, but still writes a minimal dossier before launch. - Complete route means dossier, local chantiers, dependency-aware lots, and multiple missions over time. - The orchestrator proposes simple or complete routing and waits for user confirmation before launching visible or long-running work. - Any mission launch, simple or complete, requires the runtime long-running goal capability after mandate validation. - The long-running runtime capability is not packaged as a skill dependency; pilotage supplies the mandate/gabarit and uses the runtime mechanism when available. - If runtime continuity is unavailable, pilotage refuses true mission orchestration and reports that only framing can be performed. - Sub-agents should not interact directly with the human. They record blocks in their summaries and go idle. - The orchestrator is the only human-facing channel during pilotage. - A blocked mission parks its chantier and descendants but does not stop unrelated lots. - Local clarification may be asked inline; wider decision forks recommend targeted framing and keep affected work paused. - Work invalidated by a new decision is normally sent back to the relevant mission or lot as findings to correct, not discarded automatically. - Mission branches are temporary and follow existing branch-guard naming conventions. No codex, claude, agent, ai, or issue-prefixed branch naming is introduced. - The lot branch is the only branch intended for final integration request by default. - Missions are assembled into the lot branch through cherry-pick of validated commits in dependency order. - Rejected or blocked mission commits are not cherry-picked into the lot branch. - After a lot is integrated, temporary local mission branches and unnecessary lot branches are cleaned if all commits are safely integrated or preserved elsewhere. - The pilotage dossier remains after delivery and is marked completed rather than deleted automatically. - A lot touching UI requires lot-level visual verification before integration. - Visual verification remains human-judged for semantic fit and must not become an automatic visual verdict. - Interactive proof is a separate layer driven by acceptance criteria; it is objective when configured and visibly skipped when not possible. - Interactive proof requires declared project configuration such as dev command or served URL, ready check, base URL, seed/fixture command, and session/cookie auth fixture when needed. - Missing interactive capability is reported as a visible skip, not a silent pass. - Integration finalization uses existing Linkweb tools when compatible, especially /pr and tea on Forgejo Linkweb projects. - For other forges or missing tools, pilotage prepares a manual integration summary and stops before publishing or merging. - The review plugin remains the general review brique for lots, including branches and diffs, not just PRs. - Publication or merge behavior remains limited by available tooling and explicit mandate boundaries. - Final pilotage states visible to the user are delivered, abandoned, and on hold. - Abandoned and on-hold states require explicit user confirmation. - User-facing progress defaults to a minimal dashboard: what advanced, what is blocked, what needs human judgment, and the next step. ## Testing Decisions - The highest useful seam for agent-review is the generated plugin surface plus command/skill/agent file layout. A successful change should regenerate Claude and Codex manifests, marketplace entries, and wrappers from the TypeScript source, then pass the surfaces check. - The highest useful seam for linkweb-pilotage is the skill contract and generated plugin surface. The test should verify that the plugin installs the expected command, skill, manifests, marketplace entry, and any agent wrappers without requiring real mission execution. - Existing surface generation commands are the primary regression checks: surfaces write followed by surfaces check. - Manifest version checks must cover both Codex and Claude plugin manifests for any modified plugin tree. - Rename verification must search the repository for stale public references to multi-pr-review, /review-prs, and Multi PR Review. Any remaining mention should be intentional and documented only if a changelog or migration note is explicitly added. - Pilotage verification must search for accidental public jargon in user-facing command descriptions and README text, especially PRD, issue, thread, merge, multi-pr-review, and internal skill names. - Pilotage verification must check that no generated surfaces were hand-edited without corresponding generator changes. - Pilotage verification must check that local-state paths point outside the repository and that prompts for mission handoff do not embed absolute repository paths by default. - Review workflow verification should cover branch or diff review mode, not only PR review mode, because the renamed plugin is intended to be generic. - Integration behavior should be tested at the contract level: compatible Linkweb Forgejo repos may use existing /pr and tea flow; non-compatible repos must stop with a manual summary instead of attempting gh, glab, or raw HTTP. - The pilotage skill should include explicit failure paths for missing versioned dependencies and missing runtime continuity. - UI verification behavior should be tested by contract: lot-level visual verification is required for UI lots, while semantic visual acceptance remains human-facing. - Interactive proof behavior should be tested by contract: acceptance criteria can drive objective interactions when configuration exists, and missing configuration produces a visible skip. ## Out of Scope - Do not implement the rename and pilotage in the same unreviewable change if the work can be split safely. - Do not keep /review-prs as an alias. - Do not create remote tracker tickets for pilotage chantiers. - Do not add GitHub or GitLab issue adapters for pilotage chantiers. - Do not publish, merge, deploy, or send external notifications from auto-invocation alone. - Do not expose pilotage subcommands such as /pilotage statut, /pilotage reprendre, or /pilotage nettoyer. - Do not put pilotage state inside the project repository by default. - Do not ask the user to re-read the full dossier after every framing session. - Do not let sub-threads talk directly to the human. - Do not create PRs per mission by default. - Do not use agent/vendor branch prefixes for mission branches. - Do not make visual verification an automatic semantic verdict. - Do not make persistent e2e tests the default output of interactive proof. - Do not broaden linkweb-workflow or /pr to GitHub or GitLab as part of this PRD. - Do not hand-edit generated manifests or marketplaces without updating the generator. ## Further Notes Implementation order is part of the product decision: agent-review first, linkweb-pilotage second. The pilotage plugin should be able to depend on the final generic review naming from the start. The user-facing product principle is that trust is placed in the mandate and framing, not in repeated low-value confirmations. The assistant should stop for real decisions and risks, not for mechanical steps the user cannot reasonably evaluate. The design intentionally treats impatient users as the default. Normal output should be a compact dashboard, not execution logs. The local pilotage dossier is an agent memory artifact, not project documentation. It may be exported only on explicit request. The current repository is detached HEAD in this worktree during PRD creation. That does not affect issue publication, but implementation work should run branch-guard before edits.
olivier.drieux changed title from PRD: pilotage agentique local et revue generique to PRD: pilotage agentique local et revue générique 2026-06-28 21:02:21 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
ready-for-agent
Ready for agent implementation

No labels
ready-for-agent
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
linkweb-public/linkweb-ai-toolkit#1
No description provided.