RFC: Agent Workflow Specification - PM and Dev Agent responsibilities #56
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
{"title":"RFC: Agent Workflow Specification - PM and Dev Agent responsibilities","body":"## Problem\n\nCurrently, PM and Dev agents lack clear, embodied workflows for:\n- Handling ambiguous/unclear tasks\n- Repository creation and scoping\n- Task approval and progress tracking\n- Communication between agents\n\nThis RFC proposes a complete agent workflow specification.\n\n## Core Principle\n\nPM and Dev are SEPARATE entities:\n- PM: Coordinator, never writes code to repos\n- Dev: Implementer, works in worktrees/repo branches\n\n## PM Agent Workflow\n\n### On Receiving a Task\n\n1. Assess Clarity\n - Can you understand what needs to be built?\n - Are there ambiguous parts?\n\n2. If Unclear → Ask Clarifying Questions\n - Post questions as comments on the issue\n - Add
need-user-approvallabel\n - Wait for user response\n\n3. If Clear → Proceed\n - Check if issue exists in target repo\n - Check if repository exists\n - If no repo → Ask user about creating one\n - If repo exists but no issue → Create issue\n\n### Task Approval Flow\n\n\nUser → PM: \"build an e-commerce site\"\n ↓\nPM assesses: Need to clarify scope\nPM creates issue in target repo (or finds existing)\nPM adds `need-user-approval` label\nPM asks: \"Scope: 1) auth 2) products 3) checkout. Approve to start?\"\nPM "forgets" - does not work on it until approved\n ↓\nUser comments approval (or continues discussion)\n ↓\nPM gets notification\nPM removes `need-user-approval` label\nPM sets `in-progress` or `wip` label\nPM splits large task into sub-issues\nPM queues sub-issues via `kugetsu enqueue`\n ↓\nDev agents pick up tasks from queue\n\n\n### Repository Creation Flow\n\n\nUser → PM: \"make a website about X\"\n ↓\nPM asks: \"Is there an existing repository? Should I create one?\"\nPM checks git servers via API\nPM presents options to user\n ↓\nUser confirms (or specifies repo details)\nPM creates repository\nPM creates initial scope issue describing:\n - What the project does\n - Big picture goals\n - First priority/tasks\nPM adds `need-user-approval` label to scope issue\nPM waits for user to review and approve scope\n ↓\nUser approves scope via comment\nPM starts delegating tasks\n\n\n### Default Git Server Config\n\nPM should have a default git server configuration:\n- Domain, username stored in config\n- When creating repo, ask: "Use default git server?"\n- User can override per-task\n\n## Dev Agent Workflow\n\n### On Receiving a Task\n\n1. Read the Issue\n - Understand requirements\n - Check if there's an existing PR for this issue\n\n2. If Confused → Ask PM\n - Post comment on issue documenting the confusion\n - Send notification to PM to respond\n - Both comment AND notification\n\n3. If Clear → Implement\n - Create/checkout worktree branch\n - Implement code\n - Write tests\n - Commit and push\n - Create PR\n - Post comment: "PR ready at , please review"\n - Notify PM\n\n### Communication with PM\n\nWhen blocked/confused:\n\nPost on issue: \"I'm confused about X. Can you clarify?\"\nNotify PM so they respond to the issue comment\n\n\nWhen done:\n\nPost on issue/PR: \"Done! PR at <link>, ready for review\"\n\n\n## Queue Behavior\n\nTasks withneed-user-approvallabel are:\n- NOT added to queue\n- Stay in issue state until label removed\n\nTasks withoutneed-user-approvallabel:\n- Can enter queue\n- Processed by PM in priority order\n\n## Labels Specification\n\n| Label | Meaning | Who Sets |\n|-------|---------|----------|\n|need-user-approval| Waiting for user approval | PM |\n|in-progress/wip| PM/Dev is working on it | PM/Dev |\n|blocked| Stuck, needs help | Dev |\n|done| Work completed | PM/Dev |\n\n## Implementation Requirements\n\n1. PM Skill Update:\n - Add clarification workflow (ask questions, add label, wait)\n - Add repository creation workflow\n - Add default git server config handling\n - PM should embody these behaviors automatically\n\n2. Dev Agent Skill Update:\n - Add communication protocol (comment + notify PM)\n - Add confusion handling workflow\n - Dev should know to always document in issue AND notify PM\n\n3. kugetsu Scripts:\n -kugetsu queueshould filter outneed-user-approvallabeled issues\n - Consider addingkugetsu issue-labelcommand\n\n## Open Questions\n\n1. Shouldneed-user-approvalbe generic or specific (scope-approval)?\n2. How does PM handle multiple conflicting approvals (user says yes, another says no)?\n3. Should there be a timeout forneed-user-approvalissues?\n\n## Goals\n\n- [ ] PM always asks clarifying questions before starting\n- [ ] PM always usesneed-user-approvallabel when waiting\n- [ ] Dev always comments AND notifies when confused\n- [ ] Repository creation has user confirmation\n- [ ] Large tasks are split into queue-able sub-tasks\n- [ ] PM and Dev have separate, clear responsibilities"}