Update agents.rb with deliverable parts guidance

Home Epics Update agents.rb with deliverable parts guidanceEdit

Cancel

Title *

Project *

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