jira-cloud-configuration.md
1 # Jira Cloud Configuration Plan 2 3 **Generated:** 2026-02-15 4 **Status:** Planning Document 5 **Purpose:** Configure Jira Cloud instance aligned with 333Method agent system architecture 6 7 --- 8 9 ## Table of Contents 10 11 - [Executive Summary](#executive-summary) 12 - [Research Findings](#research-findings) 13 - [Configuration Approach](#configuration-approach) 14 - [Workflow Design](#workflow-design) 15 - [Issue Types & Custom Fields](#issue-types--custom-fields) 16 - [Automation Rules](#automation-rules) 17 - [Boards & Filters](#boards--filters) 18 - [Notifications & Integrations](#notifications--integrations) 19 - [Implementation Plan](#implementation-plan) 20 - [Deliverables](#deliverables) 21 - [Time Estimates](#time-estimates) 22 - [References](#references) 23 24 --- 25 26 ## Executive Summary 27 28 This plan outlines the configuration of a Jira Cloud instance to integrate with the 333Method multi-agent development system. The configuration implements: 29 30 1. **TOGAF-aligned workflows** with approval gates (Architect → PO → Developer → QA) 31 2. **ITIL service management** practices for incident triage and resolution 32 3. **SRE principles** for monitoring, SLOs, and capacity planning 33 4. **Bidirectional sync** between Jira Cloud and agent_tasks database via webhooks 34 35 **Key Benefits:** 36 37 - Human oversight via familiar Jira UI 38 - Automated agent execution tracked in Jira 39 - Approval workflows enforced in both systems 40 - Real-time visibility into agent work 41 42 **Implementation Strategy:** 43 44 - **Primary**: Jira REST API + automation rules (70% automated) 45 - **Secondary**: Manual configuration checklist (30% manual) 46 - **Fallback**: OpenClaw/Playwright automation script (if API insufficient) 47 48 --- 49 50 ## Research Findings 51 52 ### Jira Cloud REST API Capabilities (2026) 53 54 Based on research, Jira Cloud provides: 55 56 ✅ **Available:** 57 58 - Bulk workflow creation API (team and company-managed scopes) 59 - Bulk issue operations (up to 1000 issues, 200 fields per request) 60 - Webhook-triggered automation rules (incoming and outgoing) 61 - Bidirectional sync between Jira instances via automation 62 - Custom field creation via API 63 - Project template export/import (limited) 64 65 ❌ **Not Available:** 66 67 - Complete project configuration import from JSON/YAML 68 - Workflow scheme bulk import (must create workflows individually) 69 - Approval workflow templates (TOGAF/ITIL-specific) 70 71 **Conclusion:** Hybrid approach needed - API for bulk data, manual for workflows, automation for sync. 72 73 ### Available Templates 74 75 **ITIL/ITSM Template** (Built-in): 76 77 - Pre-configured for incident, change, problem management 78 - Service catalog and request portal 79 - SLA tracking 80 - Queues for triage 81 82 **No TOGAF or SRE templates found** - must create custom workflows. 83 84 **Marketplace Alternative:** 85 86 - "Project Templates for Jira" app (300+ blueprints including Lean, CI/CD, XP) 87 - May require purchase/evaluation 88 89 --- 90 91 ## Configuration Approach 92 93 ### Phase 1: API-Driven Configuration (Automated) 94 95 **What:** Project creation, issue types, custom fields, basic workflows 96 **How:** Jira REST API via Node.js script 97 **Time:** 2 hours (Claude), 6 hours (Human) 98 99 ### Phase 2: Manual Configuration (Guided) 100 101 **What:** Complex workflows with approval gates, automation rules, board layouts 102 **How:** Step-by-step guide with screenshots 103 **Time:** 1 hour (Claude assists), 3 hours (Human) 104 105 ### Phase 3: Automation & Sync (Scripted) 106 107 **What:** Webhook automation rules, bidirectional sync with agent_tasks 108 **How:** Jira automation rules + Node.js sync service 109 **Time:** 2 hours (Claude), 8 hours (Human) 110 111 ### Fallback: OpenClaw Automation 112 113 If manual configuration is too time-consuming: 114 **What:** Automated browser clicks via Playwright 115 **How:** Script navigates Jira UI and replicates manual steps 116 **Time:** 3 hours to develop (Claude), 30 minutes to run 117 118 --- 119 120 ## Workflow Design 121 122 Based on `architectural-workflow.md` and `agent-job-roles-gaps.md`: 123 124 ### Workflow 1: Feature Implementation (Significant) 125 126 ``` 127 Backlog → Architect (Design Proposal) → PO Approval → Developer (Plan) → 128 Architect Review → Developer (Implement) → QA Test → Done 129 ``` 130 131 **Jira Statuses:** 132 133 1. `To Do` - Backlog item 134 2. `In Design` - Architect creating design proposal 135 3. `Awaiting PO` - Design complete, needs PO approval 136 4. `In Planning` - Developer creating implementation plan 137 5. `Awaiting Architect` - Plan complete, needs Architect review 138 6. `In Progress` - Developer implementing 139 7. `In Review` - Code review (optional) 140 8. `In QA` - QA testing 141 9. `Done` - Completed 142 10. `Rejected` - PO or Architect rejected 143 144 **Transitions:** 145 146 - `To Do` → `In Design` (Architect assigns to self) 147 - `In Design` → `Awaiting PO` (Architect submits proposal) 148 - `Awaiting PO` → `In Planning` (PO approves) OR `Rejected` (PO rejects) 149 - `In Planning` → `Awaiting Architect` (Developer submits plan) 150 - `Awaiting Architect` → `In Progress` (Architect approves) OR `Rejected` (Architect rejects) 151 - `In Progress` → `In QA` (Developer marks done) 152 - `In QA` → `Done` (QA passes) OR `In Progress` (QA fails) 153 154 **Automation Rules:** 155 156 1. **Auto-assign to Architect** when status → `In Design` 157 2. **Email PO** when status → `Awaiting PO` 158 3. **Auto-assign to Developer** when status → `In Planning` 159 4. **Email Architect** when status → `Awaiting Architect` 160 5. **Create agent task** via webhook when status changes 161 162 ### Workflow 2: Bug Fix (Architectural) 163 164 ``` 165 Triage → Architect (Design) → PO Approval → Developer (Fix) → QA Verify → Done 166 ``` 167 168 **Jira Statuses:** (Reuses Feature statuses) 169 170 - `To Do` → `In Design` → `Awaiting PO` → `In Progress` → `In QA` → `Done` 171 172 **Automation:** 173 174 - Auto-assign to Triage when bug created 175 - Triage sets "Architectural" flag → routes to Architect 176 - Otherwise routes to Developer directly 177 178 ### Workflow 3: Bug Fix (Standard) 179 180 ``` 181 Triage → Developer → QA → Done 182 ``` 183 184 **Jira Statuses:** 185 186 - `To Do` → `In Progress` → `In QA` → `Done` 187 188 **Automation:** 189 190 - Auto-assign to Triage 191 - Triage routes to Developer (if not architectural) 192 193 ### Workflow 4: Incident Management (SRE) 194 195 ``` 196 Monitor → Triage → Investigate → Resolved → Postmortem 197 ``` 198 199 **Jira Statuses:** 200 201 1. `Open` - New incident 202 2. `Triaging` - Triage agent classifying 203 3. `Investigating` - Developer/SRE investigating 204 4. `Escalated` - High priority, needs human 205 5. `Resolved` - Fix deployed 206 6. `Postmortem Required` - Critical incident 207 7. `Closed` - Complete 208 209 **Automation:** 210 211 - SLA tracking (P1: 1 hour, P2: 4 hours, P3: 24 hours) 212 - Auto-escalate if SLA breach 213 - Auto-create postmortem task for P1 incidents 214 215 --- 216 217 ## Issue Types & Custom Fields 218 219 ### Issue Types 220 221 1. **Epic** - Large features (multi-sprint) 222 2. **Story** - User-facing features 223 3. **Task** - Technical work (no user impact) 224 4. **Bug** - Defects 225 5. **Incident** - Production issues (SRE) 226 6. **Sub-task** - Breakdown of Stories/Tasks 227 7. **Design Proposal** - Architect design documents 228 8. **Implementation Plan** - Developer plan documents 229 230 ### Custom Fields 231 232 #### Agent Integration Fields 233 234 | Field Name | Type | Options/Description | 235 | --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ | 236 | **Agent Role** | Dropdown | Monitor, Triage, Developer, QA, Security, Architect | 237 | **Task Type** | Dropdown | scan_logs, classify_error, fix_bug, verify_fix, design_proposal, implementation_plan, technical_review, etc. | 238 | **Agent Task ID** | Number | ID from agent_tasks table (for bidirectional sync) | 239 | **Priority (1-10)** | Number | Maps to agent_tasks.priority | 240 | **Approval Metadata** | Text (JSON) | Stores approval_json data | 241 | **Reviewed By** | Text | Who approved (maps to agent_tasks.reviewed_by) | 242 | **Context JSON** | Text (Multi-line) | Task context from agent_tasks.context_json | 243 | **Result JSON** | Text (Multi-line) | Task result from agent_tasks.result_json | 244 245 #### SRE/ITIL Fields 246 247 | Field Name | Type | Options/Description | 248 | ------------------- | -------- | ------------------------------------------------------------------------------ | 249 | **Severity** | Dropdown | P1 (Critical), P2 (High), P3 (Medium), P4 (Low) | 250 | **Impact** | Dropdown | High, Medium, Low (# users affected) | 251 | **Error Type** | Dropdown | null_pointer, network, database_constraint, api_error, security, configuration | 252 | **SLO Target** | Text | e.g., "95% of sites score within 1 hour" | 253 | **Architectural** | Checkbox | Requires design proposal? | 254 | **Breaking Change** | Checkbox | Requires PO approval? | 255 256 #### Architecture Fields 257 258 | Field Name | Type | Options/Description | 259 | ---------------------------- | ----------------- | ------------------------- | 260 | **Files Affected** | Text (Multi-line) | List of files to modify | 261 | **Estimated Effort (hours)** | Number | For PO approval trigger | 262 | **Requires Migration** | Checkbox | Database schema change? | 263 | **Alternatives Considered** | Text (Multi-line) | Design alternatives | 264 | **Test Coverage Target** | Number | Percentage (default: 85%) | 265 266 --- 267 268 ## Automation Rules 269 270 ### Rule 1: Auto-Assign Based on Issue Type 271 272 **Trigger:** Issue created or status changed to `To Do` 273 **Conditions:** 274 275 - Issue type = Bug → Assign to Triage agent 276 - Issue type = Story → Assign to Architect agent 277 - Issue type = Incident → Assign to Monitor agent 278 279 **Actions:** 280 281 - Set assignee 282 - Add comment: "Auto-assigned to {Agent Role}" 283 - Send webhook to agent system 284 285 ### Rule 2: PO Approval Notification 286 287 **Trigger:** Status changed to `Awaiting PO` 288 **Actions:** 289 290 - Email Product Owner (jason@example.com) 291 - Add to "PO Approval Queue" board 292 - Set SLA (respond within 24 hours) 293 294 ### Rule 3: Architect Approval Notification 295 296 **Trigger:** Status changed to `Awaiting Architect` 297 **Actions:** 298 299 - Email Architect agent (or human architect) 300 - Add to "Architect Review Queue" board 301 - Create "Technical Review" sub-task 302 303 ### Rule 4: SLA Escalation 304 305 **Trigger:** SLA breached 306 **Conditions:** 307 308 - Priority = P1 and time in status > 1 hour 309 - Priority = P2 and time in status > 4 hours 310 - Priority = P3 and time in status > 24 hours 311 312 **Actions:** 313 314 - Change status to `Escalated` 315 - Email human operator 316 - Add to `human_review_queue` table via webhook 317 318 ### Rule 5: Bidirectional Sync to Agent System 319 320 **Trigger:** Issue created, updated, or status changed 321 **Actions:** 322 323 - Send webhook to `https://333method.com/api/jira-webhook` 324 - Payload includes: Issue key, status, assignee, custom fields 325 - Webhook creates/updates agent_tasks row 326 327 ### Rule 6: Coverage Gate Enforcement 328 329 **Trigger:** Status changed to `In QA` 330 **Conditions:** 331 332 - Custom field "Test Coverage Target" is set 333 - Coverage < target 334 335 **Actions:** 336 337 - Transition back to `In Progress` 338 - Add comment: "Coverage {actual}% below target {target}%" 339 - Create sub-task: "Write missing tests" 340 341 ### Rule 7: Postmortem Creation (SRE) 342 343 **Trigger:** Incident status changed to `Resolved` 344 **Conditions:** 345 346 - Severity = P1 347 348 **Actions:** 349 350 - Create new issue: "Postmortem: {Incident Title}" 351 - Link to original incident 352 - Add template for blameless postmortem 353 - Assign to Architect 354 355 ### Rule 8: Auto-Close Stale Tasks 356 357 **Trigger:** Scheduled (daily at 2am) 358 **Conditions:** 359 360 - Status = `To Do` 361 - No activity for 30 days 362 - Priority ≤ 5 363 364 **Actions:** 365 366 - Add comment: "Auto-closing due to inactivity" 367 - Change status to `Closed` 368 369 --- 370 371 ## Boards & Filters 372 373 ### Board 1: Agent Workflow Board (Kanban) 374 375 **Columns:** To Do | In Design | Awaiting PO | In Planning | Awaiting Architect | In Progress | In QA | Done 376 377 **Filter:** 378 379 ```jql 380 project = AGENT AND ( 381 type IN (Story, Task, Bug) 382 OR "Agent Role" IS NOT EMPTY 383 ) 384 ORDER BY priority DESC, created ASC 385 ``` 386 387 **Swimlanes:** 388 389 - By Agent Role (Monitor, Triage, Developer, QA, Security, Architect) 390 391 ### Board 2: Approval Queue Board (Kanban) 392 393 **Columns:** Awaiting PO | Awaiting Architect | Approved | Rejected 394 395 **Filter:** 396 397 ```jql 398 project = AGENT AND status IN ("Awaiting PO", "Awaiting Architect", "Approved", "Rejected") 399 ORDER BY priority DESC, created ASC 400 ``` 401 402 **Purpose:** Quick view for approvals 403 404 ### Board 3: Incident Board (Scrum) 405 406 **Columns:** Open | Triaging | Investigating | Escalated | Resolved | Postmortem Required | Closed 407 408 **Filter:** 409 410 ```jql 411 project = AGENT AND type = Incident 412 ORDER BY Severity ASC, created ASC 413 ``` 414 415 **Swimlanes:** 416 417 - By Severity (P1, P2, P3, P4) 418 419 ### Board 4: Sprint Planning Board (Scrum) 420 421 **Columns:** Backlog | Selected for Sprint | In Progress | Done 422 423 **Filter:** 424 425 ```jql 426 project = AGENT AND type IN (Story, Task) AND sprint IS NOT EMPTY 427 ORDER BY rank ASC 428 ``` 429 430 **Purpose:** Human-driven sprint planning 431 432 ### Saved Filters 433 434 1. **My Approvals** - `status IN ("Awaiting PO", "Awaiting Architect") AND (assignee = currentUser() OR watcher = currentUser())` 435 2. **Agent Tasks** - `"Agent Task ID" IS NOT EMPTY` 436 3. **High Priority Bugs** - `type = Bug AND priority >= 7` 437 4. **Overdue SLA** - `SLA breached` 438 5. **Architectural Changes** - `"Architectural" = true OR "Breaking Change" = true` 439 440 --- 441 442 ## Notifications & Integrations 443 444 ### Email Notifications 445 446 **Enabled for:** 447 448 - PO when design awaiting approval 449 - Architect when implementation plan awaiting review 450 - Assignee when task assigned 451 - Watchers when task status changes 452 - Human operator when SLA breached 453 454 **Template Example (PO Approval):** 455 456 ``` 457 Subject: [AGENT-123] Design proposal needs your approval 458 459 Hi Jason, 460 461 A design proposal is awaiting your approval: 462 463 Title: {Issue Summary} 464 Proposed by: {Architect Name} 465 Estimated Effort: {Custom Field: Estimated Effort (hours)} hours 466 Breaking Changes: {Custom Field: Breaking Change} 467 468 Design Summary: 469 {Custom Field: Context JSON} 470 471 Approve: {Link to Jira} 472 Reject: {Link to Jira} 473 474 Thanks, 475 333Method Agent System 476 ``` 477 478 ### Webhook Integration (Bidirectional Sync) 479 480 #### Jira → Agent System 481 482 **Endpoint:** `https://333method.com/api/jira-webhook` 483 484 **Triggers:** 485 486 - Issue created 487 - Issue updated 488 - Issue status changed 489 - Comment added 490 491 **Payload:** 492 493 ```json 494 { 495 "event": "issue_created", 496 "issue": { 497 "key": "AGENT-123", 498 "summary": "Fix scoring null pointer bug", 499 "status": "To Do", 500 "priority": 7, 501 "assignee": "developer", 502 "custom_fields": { 503 "agent_role": "developer", 504 "task_type": "fix_bug", 505 "agent_task_id": null, 506 "context_json": "{...}", 507 "severity": "P2" 508 } 509 } 510 } 511 ``` 512 513 **Handler Logic:** 514 515 1. Check if `agent_task_id` exists 516 - If exists: Update `agent_tasks` row 517 - If null: Create new `agent_tasks` row 518 2. Map Jira status to agent_tasks status: 519 - `To Do` → `pending` 520 - `In Progress` → `running` 521 - `Done` → `completed` 522 - `Awaiting PO` → `awaiting_po_approval` 523 - `Awaiting Architect` → `awaiting_architect_approval` 524 3. Populate `agent_tasks` fields from custom fields 525 4. Trigger agent polling if high priority 526 527 #### Agent System → Jira 528 529 **Endpoint:** Jira REST API `/rest/api/3/issue/{issueKey}` 530 531 **Triggers (from agent system):** 532 533 - Task status changed in `agent_tasks` 534 - Task completed with results 535 - Approval granted/rejected 536 - Agent log entry (comment in Jira) 537 538 **Sync Logic:** 539 540 ```javascript 541 async function syncAgentTaskToJira(taskId) { 542 const task = getAgentTaskById(taskId); 543 const jiraKey = getJiraKeyByAgentTaskId(taskId); // Lookup in mapping table 544 545 if (!jiraKey) { 546 // Create new Jira issue 547 const issue = await jira.createIssue({ 548 project: 'AGENT', 549 issueType: mapTaskTypeToIssueType(task.task_type), 550 summary: generateSummary(task), 551 customFields: { 552 agent_task_id: task.id, 553 agent_role: task.assigned_to, 554 task_type: task.task_type, 555 priority_1_10: task.priority, 556 context_json: task.context_json, 557 result_json: task.result_json, 558 }, 559 }); 560 561 // Store mapping 562 saveJiraMapping(task.id, issue.key); 563 } else { 564 // Update existing Jira issue 565 await jira.updateIssue(jiraKey, { 566 status: mapAgentStatusToJiraStatus(task.status), 567 customFields: { 568 result_json: task.result_json, 569 reviewed_by: task.reviewed_by, 570 approval_metadata: task.approval_json, 571 }, 572 }); 573 } 574 575 // Add comment with agent logs 576 if (task.status === 'completed' || task.status === 'failed') { 577 const logs = getAgentLogs(taskId); 578 await jira.addComment(jiraKey, formatLogsAsComment(logs)); 579 } 580 } 581 ``` 582 583 ### Slack Integration (Optional) 584 585 **Channels:** 586 587 - `#agent-approvals` - PO and Architect approvals needed 588 - `#agent-incidents` - P1/P2 incidents 589 - `#agent-escalations` - SLA breaches, circuit breaker trips 590 591 **Messages:** 592 593 - "🚨 P1 Incident: {Title} - Assigned to {Agent}" 594 - "⏰ Approval needed: {Title} - Awaiting PO" 595 - "✅ Approved: {Title} - Moving to implementation" 596 597 --- 598 599 ## Implementation Plan 600 601 ### Prerequisites 602 603 1. **Jira Cloud Instance** 604 - Free plan (up to 10 users) or paid 605 - Project created: "AGENT" (or "333Method Agents") 606 - Admin access for configuration 607 608 2. **API Credentials** 609 - Generate API token: https://id.atlassian.com/manage-profile/security/api-tokens 610 - Store in .env: `JIRA_API_TOKEN`, `JIRA_EMAIL`, `JIRA_DOMAIN` 611 612 3. **Webhook Endpoint** 613 - Public URL for Jira to send webhooks (e.g., ngrok for testing) 614 - Or deploy to production: `https://333method.com/api/jira-webhook` 615 616 ### Step 1: API-Driven Setup (Automated) 617 618 **Script:** `scripts/setup-jira.js` 619 620 **Actions:** 621 622 1. Create project "AGENT" (if not exists) 623 2. Create custom fields (Agent Role, Task Type, etc.) 624 3. Create issue types (Design Proposal, Implementation Plan, Incident) 625 4. Create basic workflows (simplified versions) 626 5. Create boards (Agent Workflow Board, Approval Queue Board) 627 6. Create filters (My Approvals, High Priority Bugs) 628 629 **Run:** 630 631 ```bash 632 npm run jira:setup 633 ``` 634 635 **Output:** 636 637 ``` 638 ✅ Project created: AGENT (key: AGENT) 639 ✅ Custom fields created: 12 640 ✅ Issue types created: 8 641 ✅ Workflows created: 4 642 ✅ Boards created: 4 643 ✅ Filters created: 5 644 645 ⚠️ Manual steps required: 646 1. Configure workflow transitions in Jira UI 647 2. Set up automation rules (15 rules) 648 3. Configure email notifications 649 4. Test bidirectional sync 650 651 See docs/JIRA-SETUP.md for details. 652 ``` 653 654 ### Step 2: Manual Configuration (Guided) 655 656 **Document:** `docs/JIRA-SETUP.md` 657 658 **Steps:** 659 660 1. Configure workflow transitions (approval gates) 661 2. Create automation rules (15 rules from plan) 662 3. Configure email templates 663 4. Set up webhooks (incoming and outgoing) 664 5. Configure permissions (who can approve) 665 6. Test workflows end-to-end 666 667 **Estimated Time:** 1-2 hours 668 669 ### Step 3: Bidirectional Sync Service 670 671 **File:** `src/integrations/jira-sync.js` 672 673 **Features:** 674 675 - Express webhook handler for Jira events 676 - Polling service to sync agent_tasks → Jira (every 1 minute) 677 - Mapping table: `jira_sync_map` (agent_task_id ↔ jira_issue_key) 678 - Retry logic for failed syncs 679 - Conflict resolution (last-write-wins or human review) 680 681 **Run:** 682 683 ```bash 684 npm run jira:sync 685 # Starts webhook server on :3001 686 # Polls agent_tasks every 60 seconds 687 ``` 688 689 ### Step 4: Testing & Validation 690 691 **Test Cases:** 692 693 1. **Create bug in Jira** → Verify agent_tasks row created → Verify Triage agent picks it up 694 2. **Agent completes task** → Verify Jira status updated → Verify comment added 695 3. **PO approves design** → Verify agent_tasks status changes → Verify next task created 696 4. **SLA breach** → Verify escalation to human_review_queue → Verify email sent 697 5. **Coverage gate fails** → Verify Jira transitions back to In Progress → Verify sub-task created 698 699 **Validation Script:** 700 701 ```bash 702 npm run jira:test 703 ``` 704 705 ### Step 5: Documentation & Training 706 707 **Create:** 708 709 1. `docs/JIRA-SETUP.md` - Setup guide for humans 710 2. `docs/JIRA-WORKFLOWS.md` - Workflow diagrams and explanations 711 3. `docs/JIRA-INTEGRATION.md` - API integration technical details 712 4. Video walkthrough (5-10 minutes) 713 714 --- 715 716 ## Deliverables 717 718 ### 1. Configuration Files 719 720 #### `jira-config.json` 721 722 ```json 723 { 724 "project": { 725 "key": "AGENT", 726 "name": "333Method Agents", 727 "projectTypeKey": "software", 728 "lead": "jason@example.com" 729 }, 730 "issueTypes": [ 731 { "name": "Epic", "description": "Large features" }, 732 { "name": "Story", "description": "User-facing features" }, 733 { "name": "Task", "description": "Technical work" }, 734 { "name": "Bug", "description": "Defects" }, 735 { "name": "Incident", "description": "Production issues" }, 736 { "name": "Design Proposal", "description": "Architect design documents" }, 737 { "name": "Implementation Plan", "description": "Developer plan documents" } 738 ], 739 "customFields": [ 740 { 741 "name": "Agent Role", 742 "type": "select", 743 "options": ["Monitor", "Triage", "Developer", "QA", "Security", "Architect"] 744 }, 745 { 746 "name": "Task Type", 747 "type": "select", 748 "options": [ 749 "scan_logs", 750 "classify_error", 751 "fix_bug", 752 "verify_fix", 753 "design_proposal", 754 "implementation_plan", 755 "technical_review" 756 ] 757 }, 758 { "name": "Agent Task ID", "type": "number" }, 759 { "name": "Priority (1-10)", "type": "number" }, 760 { "name": "Approval Metadata", "type": "textarea" }, 761 { "name": "Reviewed By", "type": "text" }, 762 { "name": "Context JSON", "type": "textarea" }, 763 { "name": "Result JSON", "type": "textarea" }, 764 { "name": "Severity", "type": "select", "options": ["P1", "P2", "P3", "P4"] }, 765 { "name": "Architectural", "type": "checkbox" }, 766 { "name": "Breaking Change", "type": "checkbox" }, 767 { "name": "Files Affected", "type": "textarea" }, 768 { "name": "Estimated Effort (hours)", "type": "number" }, 769 { "name": "Test Coverage Target", "type": "number" } 770 ], 771 "workflows": [ 772 { 773 "name": "Feature Workflow", 774 "statuses": [ 775 "To Do", 776 "In Design", 777 "Awaiting PO", 778 "In Planning", 779 "Awaiting Architect", 780 "In Progress", 781 "In QA", 782 "Done", 783 "Rejected" 784 ] 785 }, 786 { 787 "name": "Bug Workflow", 788 "statuses": ["To Do", "In Design", "Awaiting PO", "In Progress", "In QA", "Done"] 789 }, 790 { 791 "name": "Incident Workflow", 792 "statuses": [ 793 "Open", 794 "Triaging", 795 "Investigating", 796 "Escalated", 797 "Resolved", 798 "Postmortem Required", 799 "Closed" 800 ] 801 } 802 ] 803 } 804 ``` 805 806 ### 2. Setup Script 807 808 **File:** `scripts/setup-jira.js` 809 810 ```javascript 811 #!/usr/bin/env node 812 import { JiraClient } from '../src/integrations/jira-client.js'; 813 import config from './jira-config.json' assert { type: 'json' }; 814 815 const jira = new JiraClient({ 816 domain: process.env.JIRA_DOMAIN, 817 email: process.env.JIRA_EMAIL, 818 apiToken: process.env.JIRA_API_TOKEN, 819 }); 820 821 async function setupJira() { 822 console.log('🚀 Setting up Jira Cloud instance...\n'); 823 824 // 1. Create project 825 console.log('Creating project...'); 826 const project = await jira.createProject(config.project); 827 console.log(`✅ Project created: ${project.key}\n`); 828 829 // 2. Create custom fields 830 console.log('Creating custom fields...'); 831 for (const field of config.customFields) { 832 await jira.createCustomField(field); 833 console.log(` ✅ ${field.name}`); 834 } 835 console.log(''); 836 837 // 3. Create issue types 838 console.log('Creating issue types...'); 839 for (const issueType of config.issueTypes) { 840 await jira.createIssueType(issueType); 841 console.log(` ✅ ${issueType.name}`); 842 } 843 console.log(''); 844 845 // 4. Create workflows (simplified) 846 console.log('Creating workflows...'); 847 for (const workflow of config.workflows) { 848 await jira.createWorkflow(workflow); 849 console.log(` ✅ ${workflow.name}`); 850 } 851 console.log(''); 852 853 // 5. Create boards 854 console.log('Creating boards...'); 855 await jira.createBoard({ 856 name: 'Agent Workflow Board', 857 type: 'kanban', 858 filter: `project = ${project.key} AND type IN (Story, Task, Bug)`, 859 }); 860 console.log(' ✅ Agent Workflow Board'); 861 862 await jira.createBoard({ 863 name: 'Approval Queue Board', 864 type: 'kanban', 865 filter: `project = ${project.key} AND status IN ("Awaiting PO", "Awaiting Architect")`, 866 }); 867 console.log(' ✅ Approval Queue Board'); 868 console.log(''); 869 870 console.log('✅ Jira setup complete!\n'); 871 console.log('⚠️ Manual steps required:'); 872 console.log('1. Configure workflow transitions in Jira UI'); 873 console.log('2. Set up automation rules (see docs/JIRA-SETUP.md)'); 874 console.log('3. Configure webhooks'); 875 console.log('4. Test bidirectional sync\n'); 876 } 877 878 setupJira().catch(console.error); 879 ``` 880 881 ### 3. Sync Service 882 883 **File:** `src/integrations/jira-sync.js` 884 885 ```javascript 886 import express from 'express'; 887 import { JiraClient } from './jira-client.js'; 888 import { 889 getAgentTasksPendingSync, 890 markTaskSynced, 891 updateTaskFromJira, 892 } from '../agents/utils/task-manager.js'; 893 import Database from 'better-sqlite3'; 894 895 const db = new Database(process.env.DATABASE_PATH || './db/sites.db'); 896 const jira = new JiraClient({ 897 domain: process.env.JIRA_DOMAIN, 898 email: process.env.JIRA_EMAIL, 899 apiToken: process.env.JIRA_API_TOKEN, 900 }); 901 902 const app = express(); 903 app.use(express.json()); 904 905 // Jira → Agent System webhook 906 app.post('/api/jira-webhook', async (req, res) => { 907 try { 908 const { event, issue } = req.body; 909 910 console.log(`[Jira Webhook] Received event: ${event} for ${issue.key}`); 911 912 // Get agent_task_id from custom field 913 const agentTaskId = issue.fields.customfield_10001; // Agent Task ID field 914 915 if (agentTaskId) { 916 // Update existing agent task 917 await updateTaskFromJira(agentTaskId, { 918 status: mapJiraStatusToAgent(issue.fields.status.name), 919 result_json: issue.fields.customfield_10007, // Result JSON field 920 reviewed_by: issue.fields.customfield_10006, // Reviewed By field 921 approval_json: issue.fields.customfield_10005, // Approval Metadata field 922 }); 923 } else { 924 // Create new agent task from Jira issue 925 const taskId = await createAgentTask({ 926 task_type: issue.fields.customfield_10002, // Task Type field 927 assigned_to: issue.fields.customfield_10001, // Agent Role field 928 priority: issue.fields.customfield_10004 || 5, // Priority (1-10) field 929 context_json: issue.fields.customfield_10007, // Context JSON field 930 created_by: 'jira', 931 }); 932 933 // Update Jira with agent_task_id 934 await jira.updateCustomField(issue.key, 'Agent Task ID', taskId); 935 936 // Store mapping 937 db.prepare( 938 ` 939 INSERT INTO jira_sync_map (agent_task_id, jira_issue_key) 940 VALUES (?, ?) 941 ` 942 ).run(taskId, issue.key); 943 } 944 945 res.json({ success: true }); 946 } catch (error) { 947 console.error('[Jira Webhook] Error:', error); 948 res.status(500).json({ error: error.message }); 949 } 950 }); 951 952 // Agent System → Jira polling 953 async function syncAgentTasksToJira() { 954 const tasks = getAgentTasksPendingSync(); // Tasks updated since last sync 955 956 for (const task of tasks) { 957 try { 958 const mapping = db 959 .prepare( 960 ` 961 SELECT jira_issue_key FROM jira_sync_map WHERE agent_task_id = ? 962 ` 963 ) 964 .get(task.id); 965 966 if (mapping) { 967 // Update existing Jira issue 968 await jira.updateIssue(mapping.jira_issue_key, { 969 status: mapAgentStatusToJira(task.status), 970 customFields: { 971 result_json: task.result_json, 972 reviewed_by: task.reviewed_by, 973 approval_metadata: task.approval_json, 974 }, 975 }); 976 977 // Add comment with logs 978 if (task.status === 'completed' || task.status === 'failed') { 979 const logs = db 980 .prepare( 981 ` 982 SELECT message, log_level, created_at FROM agent_logs 983 WHERE task_id = ? ORDER BY created_at ASC 984 ` 985 ) 986 .all(task.id); 987 988 const comment = formatLogsAsComment(logs); 989 await jira.addComment(mapping.jira_issue_key, comment); 990 } 991 } else { 992 // Create new Jira issue 993 const issue = await jira.createIssue({ 994 project: 'AGENT', 995 issueType: mapTaskTypeToIssueType(task.task_type), 996 summary: generateSummary(task), 997 customFields: { 998 agent_task_id: task.id, 999 agent_role: task.assigned_to, 1000 task_type: task.task_type, 1001 priority_1_10: task.priority, 1002 context_json: task.context_json, 1003 }, 1004 }); 1005 1006 // Store mapping 1007 db.prepare( 1008 ` 1009 INSERT INTO jira_sync_map (agent_task_id, jira_issue_key) 1010 VALUES (?, ?) 1011 ` 1012 ).run(task.id, issue.key); 1013 } 1014 1015 markTaskSynced(task.id); 1016 } catch (error) { 1017 console.error(`[Jira Sync] Failed to sync task ${task.id}:`, error); 1018 } 1019 } 1020 } 1021 1022 // Helper functions 1023 function mapJiraStatusToAgent(jiraStatus) { 1024 const mapping = { 1025 'To Do': 'pending', 1026 'In Progress': 'running', 1027 Done: 'completed', 1028 'Awaiting PO': 'awaiting_po_approval', 1029 'Awaiting Architect': 'awaiting_architect_approval', 1030 Rejected: 'failed', 1031 }; 1032 return mapping[jiraStatus] || 'pending'; 1033 } 1034 1035 function mapAgentStatusToJira(agentStatus) { 1036 const mapping = { 1037 pending: 'To Do', 1038 running: 'In Progress', 1039 completed: 'Done', 1040 failed: 'Rejected', 1041 awaiting_po_approval: 'Awaiting PO', 1042 awaiting_architect_approval: 'Awaiting Architect', 1043 }; 1044 return mapping[agentStatus] || 'To Do'; 1045 } 1046 1047 function mapTaskTypeToIssueType(taskType) { 1048 const mapping = { 1049 fix_bug: 'Bug', 1050 implement_feature: 'Story', 1051 design_proposal: 'Design Proposal', 1052 implementation_plan: 'Implementation Plan', 1053 scan_logs: 'Task', 1054 classify_error: 'Task', 1055 verify_fix: 'Task', 1056 technical_review: 'Task', 1057 }; 1058 return mapping[taskType] || 'Task'; 1059 } 1060 1061 function generateSummary(task) { 1062 const context = JSON.parse(task.context_json || '{}'); 1063 const summaries = { 1064 fix_bug: `Fix bug: ${context.error_message || 'Unknown error'}`, 1065 implement_feature: `Implement: ${context.feature_description || 'New feature'}`, 1066 design_proposal: `Design: ${context.feature_description || 'Proposal'}`, 1067 scan_logs: 'Monitor: Scan logs for errors', 1068 classify_error: `Triage: Classify error in ${context.stage || 'system'}`, 1069 }; 1070 return summaries[task.task_type] || `Task: ${task.task_type}`; 1071 } 1072 1073 function formatLogsAsComment(logs) { 1074 let comment = '**Agent Execution Logs:**\n\n'; 1075 for (const log of logs) { 1076 const emoji = { error: '❌', warn: '⚠️', info: 'ℹ️', debug: '🔍' }[log.log_level] || ''; 1077 comment += `${emoji} [${log.created_at}] ${log.message}\n`; 1078 } 1079 return comment; 1080 } 1081 1082 // Start webhook server 1083 const PORT = process.env.JIRA_WEBHOOK_PORT || 3001; 1084 app.listen(PORT, () => { 1085 console.log(`[Jira Sync] Webhook server listening on :${PORT}`); 1086 }); 1087 1088 // Start polling service 1089 setInterval(syncAgentTasksToJira, 60000); // Every 1 minute 1090 console.log('[Jira Sync] Polling service started (60s interval)'); 1091 ``` 1092 1093 ### 4. Documentation 1094 1095 **File:** `docs/JIRA-SETUP.md` 1096 1097 ````markdown 1098 # Jira Cloud Setup Guide 1099 1100 Step-by-step instructions for configuring Jira Cloud for 333Method agent system. 1101 1102 ## Prerequisites 1103 1104 1. Jira Cloud instance (free or paid) 1105 2. Admin access 1106 3. API token generated 1107 4. .env configured with: 1108 - JIRA_DOMAIN=yourcompany.atlassian.net 1109 - JIRA_EMAIL=your@email.com 1110 - JIRA_API_TOKEN=your_token_here 1111 1112 ## Step 1: Run Automated Setup 1113 1114 ```bash 1115 npm run jira:setup 1116 ``` 1117 ```` 1118 1119 This creates: 1120 1121 - Project "AGENT" 1122 - Custom fields (14) 1123 - Issue types (8) 1124 - Basic workflows (4) 1125 - Boards (4) 1126 - Filters (5) 1127 1128 ## Step 2: Configure Workflows (Manual) 1129 1130 1. Go to Project Settings → Workflows 1131 2. Edit "Feature Workflow" 1132 3. Add transitions: 1133 - [Screenshot: Add transition from In Design to Awaiting PO] 1134 - Condition: "Only Architect can transition" 1135 - Validation: "Design Proposal custom field is required" 1136 4. Repeat for all workflows (see diagrams below) 1137 1138 [Workflow diagrams...] 1139 1140 ## Step 3: Create Automation Rules (15 rules) 1141 1142 ### Rule 1: Auto-Assign to Triage 1143 1144 [Screenshot + step-by-step...] 1145 1146 [Continue for all 15 rules...] 1147 1148 ## Step 4: Configure Webhooks 1149 1150 1. Go to Settings → System → Webhooks 1151 2. Create webhook: 1152 - URL: https://333method.com/api/jira-webhook 1153 - Events: Issue created, updated, transitioned 1154 - JQL filter: project = AGENT 1155 3. Test webhook with sample issue 1156 1157 ## Step 5: Test End-to-End 1158 1159 1. Create test bug in Jira 1160 2. Verify agent_tasks row created 1161 3. Let Triage agent classify 1162 4. Verify Jira status updated 1163 5. Complete workflow and verify sync 1164 1165 [Detailed test cases...] 1166 1167 ## Troubleshooting 1168 1169 **Webhook not firing:** 1170 1171 - Check webhook logs in Jira 1172 - Verify URL is publicly accessible 1173 - Check firewall rules 1174 1175 **Sync not working:** 1176 1177 - Check jira-sync.js logs 1178 - Verify API token is valid 1179 - Check jira_sync_map table for mappings 1180 1181 ```` 1182 1183 ### 5. Migration Plan 1184 1185 **File:** `db/migrations/052-create-jira-sync-map.sql` 1186 1187 ```sql 1188 -- Migration 052: Create Jira Sync Mapping Table 1189 -- Maps agent_tasks to Jira issues for bidirectional sync 1190 1191 CREATE TABLE IF NOT EXISTS jira_sync_map ( 1192 id INTEGER PRIMARY KEY AUTOINCREMENT, 1193 agent_task_id INTEGER NOT NULL UNIQUE REFERENCES agent_tasks(id), 1194 jira_issue_key TEXT NOT NULL UNIQUE, 1195 created_at DATETIME DEFAULT CURRENT_TIMESTAMP, 1196 last_synced_at DATETIME DEFAULT CURRENT_TIMESTAMP 1197 ); 1198 1199 CREATE INDEX IF NOT EXISTS idx_jira_sync_task ON jira_sync_map(agent_task_id); 1200 CREATE INDEX IF NOT EXISTS idx_jira_sync_issue ON jira_sync_map(jira_issue_key); 1201 1202 -- Add sync tracking to agent_tasks 1203 ALTER TABLE agent_tasks ADD COLUMN last_synced_to_jira DATETIME; 1204 ```` 1205 1206 --- 1207 1208 ## Time Estimates 1209 1210 ### Claude Code Time (with AI assistance) 1211 1212 | Task | Time | 1213 | ------------------------------------ | ------------ | 1214 | Research Jira API and best practices | 45 minutes | 1215 | Create jira-config.json | 15 minutes | 1216 | Write scripts/setup-jira.js | 30 minutes | 1217 | Write src/integrations/jira-sync.js | 1 hour | 1218 | Write docs/JIRA-SETUP.md | 30 minutes | 1219 | Create migration 052 | 10 minutes | 1220 | Test and debug | 1 hour | 1221 | **Total** | **~4 hours** | 1222 1223 ### Human Developer Time (manual, no AI) 1224 1225 | Task | Time | 1226 | ------------------------------------ | ------------- | 1227 | Research Jira API and best practices | 2 hours | 1228 | Manual Jira configuration | 3 hours | 1229 | Write integration code | 4 hours | 1230 | Write documentation with screenshots | 2 hours | 1231 | Test and debug | 2 hours | 1232 | **Total** | **~13 hours** | 1233 1234 ### Speedup Factor 1235 1236 **Claude Code: 3.25x faster** (4 hours vs 13 hours) 1237 1238 --- 1239 1240 ## References 1241 1242 **Jira Cloud REST API:** 1243 1244 - [Jira Cloud platform REST API - Workflows](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-workflows/) 1245 - [Bulk Move work items with the Jira cloud REST API](https://support.atlassian.com/atlassian-cloud/kb/bulk-move-work-items-with-the-jira-cloud-rest-api/) 1246 1247 **Jira Templates:** 1248 1249 - [Jira templates | Atlassian](https://www.atlassian.com/software/jira/templates) 1250 - [IT service management template | Jira Service Management](https://support.atlassian.com/jira-service-management-cloud/docs/learn-about-the-it-service-management-template/) 1251 - [How is ITIL used in Jira Service Management?](https://support.atlassian.com/jira-service-management-cloud/docs/how-is-itil-used-in-jira-service-management/) 1252 1253 **Jira Automation & Webhooks:** 1254 1255 - [Automation webhooks](https://developer.atlassian.com/cloud/jira/service-desk/automation-webhooks/) 1256 - [Configure the incoming webhook trigger in Atlassian Automation](https://support.atlassian.com/cloud-automation/docs/configure-the-incoming-webhook-trigger-in-atlassian-automation/) 1257 - [Master Jira Webhooks: A Comprehensive Integration Guide](https://www.salto.io/blog-posts/jira-webhooks-deeper-dive) 1258 1259 **Architecture References:** 1260 1261 - `docs/plans/agent-job-roles-gaps.md` - Industry standard agent responsibilities 1262 - `docs/plans/implemented/architectural-workflow.md` - Approval workflow implementation 1263 - `docs/06-automation/agent-system.md` - Multi-agent system documentation 1264 - `db/migrations/051-add-workflow-approval.sql` - Approval gates schema 1265 1266 --- 1267 1268 ## Next Steps 1269 1270 1. **Review this plan** with Product Owner (Jason) 1271 2. **Decide on approach:** 1272 - Option A: API-driven setup (70% automated) 1273 - Option B: Full manual configuration (with guide) 1274 - Option C: OpenClaw/Playwright automation (90% automated) 1275 3. **Set up Jira Cloud instance** (free trial if needed) 1276 4. **Run `npm run jira:setup`** to automate initial configuration 1277 5. **Complete manual steps** per `docs/JIRA-SETUP.md` 1278 6. **Deploy webhook service** to production 1279 7. **Test end-to-end** with sample workflows 1280 8. **Train team** on Jira + agent system integration 1281 1282 --- 1283 1284 **Status:** Ready for review and implementation 1285 **Estimated Implementation Time:** 4 hours (Claude) | 13 hours (Human) 1286 **Blockers:** None - ready to proceed