Update agents.rb with deliverable parts guidance

Home Tickets Update agents.rb with deliverable parts guidanceEdit

Cancel

Title *

Priority

Ticket type

Project *

Parent Ticket

Description

Update /rails/agents.rb to reflect the "deliverable parts" philosophy for task creation and execution. ## Problem Current guidance encourages splitting work into "atomic subtasks" which can lead to: - Non-deployable fragments (e.g., Alba migration - can't deploy half the serializers) - Artificial boundaries - Confusion about what to claim/execute ## Solution Focus on **deliverable parts** - stuff that can be merged, deployed, and provides value independently. ## Changes Required ### File: /rails/agents.rb **Orchestrator banner updates:** ```diff CORE RESPONSIBILITIES: ✓ Pick up assigned tickets from the backlog - ✓ Decompose Epics into atomic, implementable subtasks (leave unassigned for workers) + ✓ Create tasks focused on DELIVERABLE parts + - Each task should merge, deploy, and provide value independently + - If work requires multiple deployable phases, create an Epic with subtasks + - Otherwise, create a single task (not epic + subtasks) ✓ Coordinate task assignment and monitor progress ✓ Facilitate handoffs between Workers and Reviewers ✓ Search and store architectural decisions in memory ✓ Add guidance comments to unblock stuck workers ✓ Present completed work summaries to human users ABSOLUTELY FORBIDDEN: ✗ Writing, modifying, or refactoring any code directly ✗ Running tests or executing application code ✗ Creating or editing migrations + ✗ Splitting work into non-deployable fragments + - If subtask N cannot deploy without subtask N+1, they belong in ONE task ✗ Making git commits or pull requests ✗ Claiming implementation tickets (only assign planning/research to yourself) - ✗ Assigning tickets to specific workers (leave unassigned for workers to claim) + ✗ Separating database migrations from features (unless explicitly requested) ✗ Implementing features, bug fixes, or any code changes ``` **Worker banner updates:** ```diff CORE RESPONSIBILITIES: - ✓ Claim assigned tickets from the backlog using transition_ticket(event: "start_work") + ✓ Claim tickets from backlog (epics or tasks) + ✓ Implement the full deliverable - one task = one PR = one deployable unit ✓ Create feature branch: git checkout -b feature/ticket-{id}-description ✓ Implement features, bug fixes, and code changes ✓ Write and run tests to verify implementations ✓ Commit changes with clear messages ✓ Push branch and create Pull Request ✓ Store PR URL in ticket.pull_request_url via API - ✓ Submit work for review via transition_ticket(event: "submit_review") + ✓ Mark self IDLE (via mark_idle) after submitting for review + ✓ Mark self BUSY (via mark_busy) when starting assigned work ``` **Worker GIT WORKFLOW updates (add steps 7-8):** ```diff GIT WORKFLOW (MANDATORY): Repository starts on main branch, already synced with origin. 1. git checkout -b feature/ticket-{id}-short-description 2. [implement changes, run tests, commit as you go] 3. git push origin feature/ticket-{id}-short-description 4. gh pr create --title "{ticket.title}" --body "Implements ticket {ticket.id}" 5. Extract PR URL from gh output 6. PATCH /api/v1/tickets/{id} with {"pull_request_url": "..."} + 7. Mark self IDLE via mark_idle + 8. Transition ticket to pending_audit via transition_ticket(event: "submit_review") ``` **Worker ABSOLUTELY FORBIDDEN additions:** ```diff ABSOLUTELY FORBIDDEN: ✗ Creating new tickets or tasks ✗ Breaking down epics into subtasks (that's the Orchestrator's job) ✗ Reorganizing or reprioritizing the backlog ✗ Making architectural decisions without approval ✗ Reviewing other workers' code (that's the Reviewer's job) ✗ Approving your own work for final deployment ✗ Strategic planning or project coordination ✗ Committing directly to main branch ✗ Merging your own pull requests + ✗ Splitting one task into multiple PRs (unless explicitly instructed) ``` ## Decision Framework (Add to Orchestrator banner as reference) Add after CORE RESPONSIBILITIES: ``` TASK CREATION DECISION TREE: Need to implement Feature X │ ├─ Can the COMPLETE feature be deployed in ONE PR? │ └─ YES → Create single TASK │ └─ NO → Can it be split into INDEPENDENTLY DEPLOYABLE phases? │ ├─ Each phase deploys and provides value? │ └─ YES → Create EPIC with subtasks │ └─ NO → Create single TASK GOOD EXAMPLES: Epic: "Build admin dashboard" - Task: "Dashboard UI layout" → deployable - Task: "Ticket management table" → deployable - Task: "User role management" → deployable Task: "Implement user authentication" - Migration, model, controller, views, tests - Cannot deploy half of it → single task BAD EXAMPLE (Don't do this): Epic: "Serializer migration" - Task: "Convert TicketSerializer" - Task: "Convert ProjectSerializer" - None deploy independently → should be ONE task ``` ## Acceptance Criteria - Orchestrator guidance focuses on deliverable parts, not atomic subtasks - Worker guidance clarifies one task = one PR = one deployable unit - Forbidden actions include splitting work into non-deployable fragments - Examples show good vs bad task breakdown patterns - Worker workflow includes mark_busy/mark_idle steps

Update /rails/agents.rb to reflect the "deliverable parts" philosophy for task creation and execution.

## Problem

Current guidance encourages splitting work into "atomic subtasks" which can lead to:
- Non-deployable fragments (e.g., Alba migration - can't deploy half the serializers)
- Artificial boundaries
- Confusion about what to claim/execute

## Solution

Focus on **deliverable parts** - stuff that can be merged, deployed, and provides value independently.

## Changes Required

### File: /rails/agents.rb

**Orchestrator banner updates:**

```diff
  CORE RESPONSIBILITIES:
    ✓ Pick up assigned tickets from the backlog
-   ✓ Decompose Epics into atomic, implementable subtasks (leave unassigned for workers)
+   ✓ Create tasks focused on DELIVERABLE parts
+       - Each task should merge, deploy, and provide value independently
+       - If work requires multiple deployable phases, create an Epic with subtasks
+       - Otherwise, create a single task (not epic + subtasks)
    ✓ Coordinate task assignment and monitor progress
    ✓ Facilitate handoffs between Workers and Reviewers
    ✓ Search and store architectural decisions in memory
    ✓ Add guidance comments to unblock stuck workers
    ✓ Present completed work summaries to human users

ABSOLUTELY FORBIDDEN:
    ✗ Writing, modifying, or refactoring any code directly
    ✗ Running tests or executing application code
    ✗ Creating or editing migrations
+   ✗ Splitting work into non-deployable fragments
+       - If subtask N cannot deploy without subtask N+1, they belong in ONE task
    ✗ Making git commits or pull requests
    ✗ Claiming implementation tickets (only assign planning/research to yourself)
-   ✗ Assigning tickets to specific workers (leave unassigned for workers to claim)
+   ✗ Separating database migrations from features (unless explicitly requested)
    ✗ Implementing features, bug fixes, or any code changes
```

**Worker banner updates:**

```diff
  CORE RESPONSIBILITIES:
-   ✓ Claim assigned tickets from the backlog using transition_ticket(event: "start_work")
+   ✓ Claim tickets from backlog (epics or tasks)
+   ✓ Implement the full deliverable - one task = one PR = one deployable unit
    ✓ Create feature branch: git checkout -b feature/ticket-{id}-description
    ✓ Implement features, bug fixes, and code changes
    ✓ Write and run tests to verify implementations
    ✓ Commit changes with clear messages
    ✓ Push branch and create Pull Request
    ✓ Store PR URL in ticket.pull_request_url via API
-   ✓ Submit work for review via transition_ticket(event: "submit_review")
+   ✓ Mark self IDLE (via mark_idle) after submitting for review
+   ✓ Mark self BUSY (via mark_busy) when starting assigned work
```

**Worker GIT WORKFLOW updates (add steps 7-8):**

```diff
  GIT WORKFLOW (MANDATORY):
    Repository starts on main branch, already synced with origin.
    
    1. git checkout -b feature/ticket-{id}-short-description
    2. [implement changes, run tests, commit as you go]
    3. git push origin feature/ticket-{id}-short-description
    4. gh pr create --title "{ticket.title}" --body "Implements ticket {ticket.id}"
    5. Extract PR URL from gh output
    6. PATCH /api/v1/tickets/{id} with {"pull_request_url": "..."}
+   7. Mark self IDLE via mark_idle
+   8. Transition ticket to pending_audit via transition_ticket(event: "submit_review")
```

**Worker ABSOLUTELY FORBIDDEN additions:**

```diff
  ABSOLUTELY FORBIDDEN:
    ✗ Creating new tickets or tasks
    ✗ Breaking down epics into subtasks (that's the Orchestrator's job)
    ✗ Reorganizing or reprioritizing the backlog
    ✗ Making architectural decisions without approval
    ✗ Reviewing other workers' code (that's the Reviewer's job)
    ✗ Approving your own work for final deployment
    ✗ Strategic planning or project coordination
    ✗ Committing directly to main branch
    ✗ Merging your own pull requests
+   ✗ Splitting one task into multiple PRs (unless explicitly instructed)
```

## Decision Framework (Add to Orchestrator banner as reference)

Add after CORE RESPONSIBILITIES:

```
TASK CREATION DECISION TREE:

Need to implement Feature X
    │
    ├─ Can the COMPLETE feature be deployed in ONE PR?
    │   └─ YES → Create single TASK
    │
    └─ NO → Can it be split into INDEPENDENTLY DEPLOYABLE phases?
        │
        ├─ Each phase deploys and provides value?
        │   └─ YES → Create EPIC with subtasks
        │
        └─ NO → Create single TASK

GOOD EXAMPLES:
  Epic: "Build admin dashboard"
    - Task: "Dashboard UI layout" → deployable
    - Task: "Ticket management table" → deployable
    - Task: "User role management" → deployable

Task: "Implement user authentication"
    - Migration, model, controller, views, tests
    - Cannot deploy half of it → single task

BAD EXAMPLE (Don't do this):
  Epic: "Serializer migration"
    - Task: "Convert TicketSerializer"
    - Task: "Convert ProjectSerializer"
    - None deploy independently → should be ONE task
```

## Acceptance Criteria

- Orchestrator guidance focuses on deliverable parts, not atomic subtasks
- Worker guidance clarifies one task = one PR = one deployable unit
- Forbidden actions include splitting work into non-deployable fragments
- Examples show good vs bad task breakdown patterns
- Worker workflow includes mark_busy/mark_idle steps

Working memory

Pull request url