aiskillstore/devflow

DEVFLOW: Agent Development

5-phase workflow for coordinated multi-agent development.

⚠️ MANDATORY: 100% Issue/Task Coverage

Every phase must verify that 100% of original issue/task requirements are being addressed.

• Phase 1: Extract ALL requirements from original issue
• Phase 2: Dispatch agents with complete requirement lists
• Phase 3: Review must verify 100% coverage before quality check
• Phase 5: Cannot merge until 100% of original requirements implemented

Incomplete implementations = SEND BACK, do not proceed.

Phase 1: Oracle Assessment

• Assess codebase state with Oracle
• Identify completed work, remaining work, dependencies
• Extract ALL requirements from original issue/task (gh issue view <number>)
• Break down into parallelizable tasks ensuring ALL requirements are covered

Phase 2: Parallel Implementation

Dispatch Docker agents:

• Clone repo, format locally (cargo +nightly fmt)
• Branch as feat/name or fix/name
• Open PR to correct base branch with Closes #X in body
• Never push to existing branches

PR MUST include issue links:

• Closes #X or Fixes #X for issues being addressed
• "Related Issues" section in PR body
• Verify: gh pr view --json closingIssuesReferences

Phase 3: Ultra-Critical Review

After CI passes, run 6-pass review:

| Pass | Focus | |------|-------| | 0.5 | 100% issue/task coverage verification (MANDATORY FIRST) | | 1 | Runtime/compile failures | | 2 | Patterns, imports, dead code | | 3 | Abstractions, hard-coded values | | 4 | Environment compatibility | | 5 | Verification commands | | 6 | Context synthesis |

CRITICAL: Pass 0.5 (issue coverage) MUST pass before proceeding. If coverage < 100%, send agent back immediately.

Review Escalation

1. Escalate to coordinator first — Architecture/tradeoff questions
2. Coordinator applies good judgment — Based on codebase patterns
3. Escalate to human when needed — Significant risk or uncertainty

Review Timing

• Pre-PR review: After agent work, before PR creation
• Post-PR review: After PR creation, before merge

Phase 4: Human Approval

Pause for: PR approval, complex decisions requiring human judgment.

Continue through: workstream setup, agent dispatch, CI fixes, review feedback.

Phase 4.5: FINAL COVERAGE GATE

MANDATORY: Before any merge, perform LINE-BY-LINE requirement verification.

# Extract ALL requirements from issue
gh issue view <number> --json body --jq '.body' | grep -E "^\- \["
gh issue view <number>

Create verification table:

| Requirement | Status | Evidence |
|-------------|--------|----------|
| [from issue] | ✅ | `file:line` |
| [from issue] | ❌ MISSING | Not in PR |
| [from issue] | ⚠️ PARTIAL | [what's missing] |

**Honest Assessment**: X% (Y of Z requirements)

| Coverage | Action | |----------|--------| | 100% | ✅ Proceed to merge | | < 100% | ❌ Return to Phase 2 with line-by-line gap list |

Phase 5: Merge & Continue

Before merge, verify issue linking:

gh pr view <NUMBER> --json closingIssuesReferences
# Must show linked issues - if empty, send back to fix

Merge PRs in dependency order. Only after Final Coverage Gate passes AND issues are linked. Issues auto-close on merge.

---

Mermaid Diagrams in Reviews and PRs

Reviews and PRs SHOULD include Mermaid diagrams when changes involve flows, states, or architecture.

| Change Type | Diagram | |-------------|---------| | Flow change | flowchart before/after | | API modification | sequenceDiagram | | State handling | stateDiagram-v2 | | Architecture change | flowchart with subgraphs |

Example in review:

### New Token Flow
```mermaid
sequenceDiagram
    Client->>Server: Request (expired token)
    Server-->>Client: 401 + refresh
    Client->>Server: New request
```

---

Anti-Patterns

| Wrong | Right | |-------|-------| | Merge with incomplete coverage | 100% of issue requirements implemented first | | PR without issue links | Every PR has Closes #X for related issues | | Push to branch | Feature branch + PR | | Checkbox review | 6-pass analysis (starting with coverage check) | | Coordinator implements | Dispatch agents | | Pause every step | Pause for PR decisions | | Skip CI | Wait for CI | | "Core requirements done" | ALL requirements done, no exceptions | | Merge then close issue manually | Use Closes #X for auto-close on merge | | Text-only complex changes | Mermaid diagrams for flows/states |