Agent Skills: Develop

Develop

PM orchestration playbook for the full PR-based development lifecycle.

Phase Flow

intake → research → design → branch → [test_writing → implement → test] → review → merge → acceptance → complete
                                        └──────── TDD loop ────────┘
Kickbacks:
  test ──────────→ implement        (tests fail)
  review ────────→ implement        (code issues)
  review ────────→ test_writing     (test gaps)
  merge ─────────→ implement        (conflicts)
  acceptance ────→ implement        (requirements)
  acceptance ────→ test_writing     (test gaps)

Agent Lifecycle

| Role | Spawn At | Shut Down After | |------|----------|-----------------| | PM | Workflow start (team lead) | complete | | Researcher | research | research complete | | Architect | design | design approved | | Implementer | test_writing | complete | | Reviewer | review | complete | | Git-agent | branch | complete | | Debugger | On demand | Issue resolved |

Phases

1. Startup

Create team and start workflow. PM is team lead.

TeamCreate(team_name="develop-<feature>")
workflow__workflow_start(workflow_id="develop", task="<feature description>")
mkdir -p .develop/  # artifact directory for stories, research, design

2. Intake

Gather requirements from user. Write user stories with acceptance criteria.

Actions:

• Elicit requirements via conversation
• Write user stories (As a..., I want..., So that...) with acceptance criteria
• Optionally create feature ticket: gh issue create --title "<feature>" --body "<stories>"
• Store stories in workflow state: workflow__set_value(wf_id, "stories", stories)
• Write to .develop/stories.md
• Advance: workflow__advance_phase(wf_id, "research")

3. Research

Spawn Researcher to gather codebase context.

Actions:

• Register + spawn Researcher teammate

  reg = router__register_agent(agent_id="researcher", agent_type="researcher", workflow_id="develop")
  Task(team_name=<team>, name="researcher", prompt=reg.briefing + "\n\n" + context_request)
  

• Send context request via SendMessage(recipient="researcher", content=<stories + questions>)
• Wait for context document
• Researcher writes findings to .develop/research.md
• Shut down Researcher: SendMessage(type="shutdown_request", recipient="researcher")
• Advance: workflow__advance_phase(wf_id, "design")

4. Design

Spawn Architect to produce design spec with subtask dependency graph.

Actions:

• Register + spawn Architect teammate

  reg = router__register_agent(agent_id="architect", agent_type="architect", workflow_id="develop")
  Task(team_name=<team>, name="architect", prompt=reg.briefing + "\n\n" + design_request)
  

• Send stories + research context via SendMessage
• Wait for design spec with:
  • Architecture decisions
  • Subtask breakdown with dependency graph
  • Interface contracts between subtasks
• Architect writes to .develop/design.md
• Checkpoint: PM reviews and approves design
• Optionally create subtask tickets: gh issue create per subtask
• Shut down Architect: SendMessage(type="shutdown_request", recipient="architect")
• Advance: workflow__advance_phase(wf_id, "branch")

5. Branch

Spawn Git-agent to create feature branch from main.

Actions:

• Register + spawn Git-agent teammate

  reg = router__register_agent(agent_id="git-agent", agent_type="git-agent", workflow_id="develop")
  Task(team_name=<team>, name="git-agent", prompt=reg.briefing + "\n\n" + branch_request)
  

• Request branch creation via SendMessage

  SendMessage(recipient="git-agent", content="Create feature branch 'feat/<name>' from main")
  

• Git-agent creates branch, reports name
• Advance: workflow__advance_phase(wf_id, "test_writing")

6. TDD Loop (test_writing -> implement -> test)

For each eligible subtask (respecting dependency graph):

Actions:

• Build subtask queue from design spec. Store in workflow state:

  workflow__set_value(wf_id, "subtask_queue", subtask_list)
  

• Dequeue unblocked subtasks (all dependencies complete)
• For each unblocked subtask:

  # Implementers use iterate sub-workflow (TDD loop) for their individual work.
  # The develop workflow governs the PM's outer lifecycle.
  reg = router__register_agent(agent_id=<subtask-id>, agent_type="implementer", workflow_id="iterate")
  Task(
    team_name=<team>,
    name=<subtask-id>,
    prompt=reg.briefing + "\n\n" + subtask_description + working_dir,
    subagent_type="implementer",
    isolation="worktree"  # parallel subtasks get isolated worktrees
  )
  

• Independent subtasks run in parallel via isolated worktrees
• Each Implementer follows iterate sub-workflow: test_writing -> implement -> test
• Monitor via messages and task list
• When subtask tests pass, mark complete, check for newly eligible subtasks
• Re-assign idle Implementers to next unblocked subtask
• When all subtasks complete: workflow__advance_phase(wf_id, "review")

7. Review

Spawn Reviewer for adversarial code review.

Actions:

• Register + spawn Reviewer teammate

  reg = router__register_agent(agent_id="reviewer", agent_type="reviewer", workflow_id="develop")
  Task(team_name=<team>, name="reviewer", prompt=reg.briefing + "\n\n" + review_request)
  

• Send design spec + full diff via SendMessage
• Reviewer performs adversarial review against:
  • Design spec compliance
  • Code quality and conventions
  • Test coverage adequacy
  • Edge cases and error handling

Outcomes:

| Result | Action | |--------|--------| | Approve | workflow__advance_phase(wf_id, "merge") | | Code issues | Record kickback, workflow__advance_phase(wf_id, "implement") | | Test gaps | Record kickback, workflow__advance_phase(wf_id, "test_writing") |

8. Merge

Message Git-agent to create PR and merge.

Actions:

• Send merge request via SendMessage(recipient="git-agent")
• Git-agent pushes branch, creates PR: gh pr create --base main --head <branch>
• Attempt merge

Outcomes:

| Result | Action | |--------|--------| | Clean merge | workflow__advance_phase(wf_id, "acceptance") | | Conflicts | Record conflict files, workflow__advance_phase(wf_id, "implement") |

9. Acceptance

PM validates implementation against user stories.

Actions:

• Check each acceptance criterion from stories
• Run acceptance tests if applicable
• Validate against original requirements

Outcomes:

| Result | Action | |--------|--------| | Accept | workflow__advance_phase(wf_id, "complete") | | Code issue | Record issue, workflow__advance_phase(wf_id, "implement") | | Test gap | Record gap, workflow__advance_phase(wf_id, "test_writing") |

10. Complete

Shut down all teammates and summarize.

Actions:

• Shut down all remaining teammates:

  SendMessage(type="shutdown_request", recipient="<each-agent>")
  

• Output summary:
  • What was done (stories satisfied)
  • PR link
  • Ticket links (if tickets enabled)
  • Kickback history
• Workflow done

Kickback Routing

| From | Target | Reason | |------|--------|--------| | test | implement | Tests fail | | review | implement | Code quality issues | | review | test_writing | Insufficient test coverage | | merge | implement | Merge conflicts | | acceptance | implement | Doesn't meet requirements | | acceptance | test_writing | Tests don't validate requirements |

Kickback loops (3+ same-issue kickbacks) trigger PM intervention — escalate to user.

Subtask Parallelism

• Independent subtasks (no shared dependencies) run in parallel via isolated worktrees
• Dependent subtasks wait until their dependencies complete
• PM re-assigns idle Implementers when dependencies resolve
• Max concurrent agents governed by max_agents in workflow config (default: 8)

Artifacts

| Artifact | Location | Purpose | |----------|----------|---------| | User stories | .develop/stories.md | Requirements + acceptance criteria | | Research | .develop/research.md | Codebase context and findings | | Design spec | .develop/design.md | Architecture, subtasks, dependency graph | | Workflow state | Router state store | Phase, kickbacks, subtask status |

Error Handling

• Agent crash: Re-spawn up to max_agent_respawns (default: 3). If exceeded, mark subtask failed and alert PM.
• Kickback loops: PM intervenes after 3+ same-issue kickbacks. Escalate to user if unresolvable.
• Merge conflicts: Kickback to implement with conflict file list.
• Stale agents: Monitor via messages/task list. Dead/stuck agent -> re-register and re-spawn.
• Debugger escalation: For persistent test failures, spawn a debugger on demand:

  reg = router__register_agent(agent_id="debugger-<issue>", agent_type="debugger", workflow_id="develop")
  Task(team_name=<team>, name="debugger-<issue>", prompt=reg.briefing + "\n\n" + error_context)
  

  Shut down debugger after issue is resolved.

Configuration

Settings in config/workflows/develop.yaml:

| Setting | Default | Purpose | |---------|---------|---------| | max_agents | 8 | Max concurrent agents | | max_review_retries | 0 | Auto-retry limit for review kickbacks (0 = unlimited) | | max_agent_respawns | 3 | Max re-spawns per crashed agent | | tickets.enabled | true | Create GitHub issues | | tickets.provider | github | Issue provider (gh CLI) | | tickets.feature_ticket | true | Create parent feature ticket | | tickets.subtask_tickets | true | Create per-subtask tickets | | tickets.followup_tickets | true | Reviewer/PM create at review/acceptance |