Claude Agent Team

Clarity Gate (5 criteria, ALL must pass):

1. What needs to change is described
2. Where in the codebase is identifiable
3. Expected behavior is described or inferable
4. No unanswered questions in comments
5. No conflicting instructions between description and comments

Branch naming: Auto-maps issue type to prefix:

Sprint mode: /jira sprint --autonomous processes all tickets sequentially, skips unclear ones, and generates a summary table showing completed vs skipped with reasons.

Output: reports/{timestamp}_autonomous_{KEY}.md per ticket with branch info, all changes, testing instructions.

1. Fetch & Analyze — fetches ticket via REST API, downloads/resizes image attachments, auto-detects JAM links and analyzes them via MCP, reads all comments for additional requirements and unanswered questions, classifies scope (UI/Backend/Full-stack)
2. Design (if UI changes) — captures BEFORE screenshots with Playwright, creates mockups in Paper via MCP, presents to user for approval
3. Implementation — creates Git branches for all affected projects, launches Frontend + Backend agents in parallel, Code Analyst reviews the diff
4. Report & Jira Update — generates HTML report, uploads to Jira as attachment, posts summary comment, transitions ticket status
5. Summary & Time Logging — presents results, logs time via Tempo

• Comment analysis — reads ALL comments chronologically, extracts additional requirements added after the description, identifies unanswered questions, notes latest context that may override the description
• Automatic @mention + watch loop — if the agent determines it doesn’t have enough info to implement, it recommends asking the reporter, posts a question @mentioning them on Jira, then automatically enters a watch loop (polls every 2 min). When the reporter replies, the agent detects it, analyzes the answer, and auto-resumes the pipeline. If it still needs more info, it posts another question and watches again. This back-and-forth continues until the ticket has enough info.
• JAM auto-detection — scans description and comments for jam.dev links, analyzes each via MCP (video, console logs, network requests, user events)
• Git branch setup — after plan approval, asks to create branches. Lists available branches from each project, user picks base branch and names the new one (hotfix/FO-xxx, feature/FO-xxx, custom)
• Image auto-resize — resizes downloaded attachments to max 1600px before analysis (prevents multi-image dimension errors)
• State persistence — saves full pipeline state to reports/jira-state-{KEY}.json when paused. Resume from a new session with /jira resume {KEY} — no need to re-enter project paths, branches, or approvals

1. Agent analyzes ticket → determines it needs more information
2. Agent recommends asking the reporter (“I recommend asking — the ticket doesn’t specify X and Y”)
3. Posts @mention comment on Jira with specific questions
4. Automatically enters watch loop (no user prompt needed)
5. Polls every 2 minutes for new comments
6. Reporter replies on Jira → agent detects reply → analyzes if it answers the question
7. If answered: auto-resumes pipeline from where it paused
8. If reporter asks a counter-question: presents to user, can draft AI response
9. If agent still needs more info after resuming: posts another question → watches again
10. Loop continues until ticket is fully resolved

In sprint mode: asks whether to watch this ticket or move to the next one (since watching blocks the batch).

Interrupt: Ctrl+C saves state. Resume later with /jira resume {KEY}.

When a ticket comes back from review with issues, use: /jira FO-2847 "Description of what needs fixing"

1. Fetches ticket + latest comments (the review feedback)
2. Checks for JAM recordings in review comments
3. Parses feedback into actionable items: bugs found, missing requirements, design changes, code quality issues
4. Loads previous context (project paths, branches) from saved state — avoids re-asking
5. Plans fixes, presents to user for approval
6. Implements the minimum changes needed
7. Verifies with Playwright (if app running)
8. Generates jira-{KEY}-review-fix-report.html
9. Offers to post a comment on Jira listing what was fixed + attach the report

1. Fetches all Scrum teams from Jira (dynamically, not hardcoded)
2. User picks a team or "All teams"
3. Fetches current sprint tickets (assigned to user or unassigned)
4. Presents prioritized table with ticket details
5. User selects: all / specific / only mine / only unassigned
6. Processes each ticket through the full 5-phase /jira pipeline
7. Continue / Skip / Stop controls between tickets
8. Sprint summary at the end

Automatic (most common): When /jira FO-2847 determines it needs more info, it posts a question @mentioning the reporter and immediately enters the watch loop. No user action needed.

Manual: Run /jira watch FO-2847 to start watching a ticket you previously paused or where you’re expecting a response.

1. Pipeline posts a question on Jira (@mentions reporter)
2. Automatically enters watch loop — polls every 2 minutes
3. Ignores its own comments (from the authenticated user)
4. When reply detected: analyzes if it answers the question
5. If answered: auto-resumes pipeline from where it paused
6. If counter-question: presents to user, can draft AI response or let user type, posts it, continues watching
7. If pipeline needs more info after resuming: posts another question → watches again
8. Loop continues until ticket is fully resolved

Interrupt: Ctrl+C or type stop to save state and exit. Resume later with /jira resume {KEY}.

1. Analyze — reads 3-5 existing files first to understand conventions. Identifies files to create/modify, detects if UI changes needed
2. Design mockups (if UI) — create artboards in Paper via MCP, capture screenshots
3. Generate HTML plan — reports/feature-plan.html with embedded Paper screenshots, technical plan, API contracts, testing plan. Auto-opens in browser for review.
4. User approval gate — Accept / Adjust / Redesign / Cancel
5. BEFORE screenshots (if app running) — captures current state with Playwright before any changes
6. Implement — follows the HTML plan. For large features, can spawn parallel Frontend + Backend agents. All agents match existing code style.
7. Code analysis — reviews the diff for security issues, logic errors, dead code. Auto-fixes critical issues.
8. Verify (if app running) — auto-offers Playwright E2E verification. Takes AFTER screenshots, generates before/after comparison.
9. Master HTML report — optional: compile everything into a comprehensive report (like /new-feature)

Before writing any code, /create reads existing files in the area it’s working on. It identifies naming conventions, code style, architecture patterns, and existing utilities to reuse. Generated code matches the existing codebase — same indentation, bracket style, naming convention, error handling pattern, and import structure. Sub-agents receive the same instruction.

After fixing the bug, if the app is running, the agent auto-offers to verify the fix with Playwright. It logs in using the project profile, reproduces the original bug steps, confirms the bug no longer occurs, and takes screenshots as evidence. Results are attached to the report.

The changelog visual design adapts to the project type:

Design is detected from: 1) .claude/project-profile.json design section, 2) project CSS/theme files, 3) auto-generated from ProjectType. Saved to profile for all future reports.

1. Questions — asks about stack preference, features for v1, auth needs, design style, where to create the project
2. Architecture — designs directory structure, database schema, API endpoints, component architecture
3. UI Design in Paper — creates 3-5+ screens in Paper via MCP (login, dashboard, feature pages, mobile). Takes screenshots.
4. HTML Plan — generates reports/project-plan.html with ALL Paper screenshots embedded, architecture docs, API spec, DB schema. Auto-opens in browser.
5. User Approval — Build / Adjust / Redesign / Change stack / Cancel
6. Build — scaffolds project, launches Backend Dev + Frontend Dev agents, Code Analyst reviews
7. Quality Loop — Security Auditor + Quality Engineer scan, Backend Dev fixes, Test Engineer tests, re-scan until clean
8. Verify — builds, starts the app, runs Playwright E2E verification with screenshots
9. Docker (if requested) — creates Dockerfiles, docker-compose.yml, builds and verifies
10. Delivery Report — generates reports/project-delivery-report.html with all screenshots, auto-opens

1. Planning — ask for project paths, analyze codebase, draft feature plan, user approval gate
2. Visual Capture — screenshot existing app with Playwright (if running)
3. Design in Paper — UI Designer agent creates mockups via MCP, user reviews and approves
4. Implementation — Frontend + Backend agents work in parallel, Code Analyst reviews diff
5. Report — Documentation Lead compiles master HTML report
6. Testing — optional handoff to /full-pipeline

1. Parallel Scan — Security Auditor + Quality Engineer run simultaneously
2. Fix — Backend Developer fixes all findings (Critical → Warning → Info)
3. Test — Test Engineer writes tests for every fix, runs until green
4. Verify — Re-run both scans. New issues? Loop back. Zero findings? Done.
5. Report — Documentation Lead compiles master report

On first run, /verify interactively builds a .claude/project-profile.json with:

• Frontend URL — where the app runs (localhost:3000, etc.)
• Auth config — login page URL, form selectors, test user credentials
• Auth types supported: form login, OAuth/SSO (saved session), API key, basic auth, no auth
• Viewport and timing — screenshot size, wait times

Credentials go in .claude/.env (gitignored), not the profile JSON. The profile is reused for all future verifications.

1. Reads the “How to Verify” section from the report (/create, /bug, or /jira output)
2. Translates each step into Playwright actions (navigate, click, fill, assert)
3. Logs in using the project profile auth config
4. Takes BEFORE screenshots
5. Performs each verification step
6. Takes AFTER screenshots
7. Visually analyzes screenshots for confirmation
8. Reports pass/fail per step with screenshot evidence

/create and /bug automatically offer to run /verify after implementation if the app is running. The verification results and screenshots are attached to the report.

/jira includes verification screenshots in the Jira ticket attachments and comment.

1. Executive Summary — what the branch does, scope, risk assessment
2. Changes by Category — new features (green), bug fixes (amber), refactoring (blue), config (gray), database (purple), styling (cyan), tests (teal)
3. Files Changed — table with file, change type, category, summary
4. Screenshots — if app is running, captures affected pages with Playwright
5. Testing Instructions for QA — step-by-step test cases with: preconditions, exact steps, expected results, test data, priority (must/should/nice to test). Checkboxes for testers.
6. Commit History — all commits with hash, author, date, message
7. Technical Details — dependencies, migrations, env var changes

After generating, asks if you want to upload to Jira:

• Uploads HTML report as attachment
• Uploads screenshots as attachments
• Posts summary comment on the ticket
• Auto-detects ticket key from branch name (e.g., feature/FO-2847)

With --fix-merge-errors, for each conflicting file a specialized agent:

1. Reads both versions (HEAD and incoming)
2. Analyzes what each side is doing
3. Resolves: both needed (merge both), incoming preferred, current preferred, or needs human review
4. Removes all conflict markers
5. Regenerates lock files (package-lock.json, yarn.lock, etc.)

If the AI isn't confident, it flags the file as NEEDS_HUMAN_REVIEW instead of guessing.

• Fetches all repos via GitHub API
• Maps inter-repo relationships: depends-on, frontend-for, shares-data, shared-library, gateway
• Calculates correct startup order from dependency graph
• Generates CSS architecture diagram with color-coded repo boxes and connection lines
• GitHub account switching: lists all authenticated gh accounts, user picks one

1. Resolve repos — fetch from GitHub org, scan local disk, or use specified repos
2. Extract keywords — parse the description into entities, actions, layers, search patterns
3. Deep scan each repo — search for models, DTOs, controllers, endpoints, serializers, tests. Read matching files to understand what they do.
4. Classify impact per file — change type (add/modify/create), priority (must/should/consider), complexity (simple/medium/complex)
5. Map dependencies — determine implementation order (shared libs first, then backends, then frontends)
6. Generate HTML report — impact diagram, per-repo tables with exact files and change descriptions, code snippets

• Executive summary with complexity estimate
• CSS impact diagram showing affected vs unaffected repos
• Implementation order with dependency reasoning
• Per-repo detail: file, change type, what to do, priority, complexity, code snippets
• Repos NOT affected (with reasoning)
• Risk assessment and rollback plan
• Suggested PR strategy

After scanning, use --apply to implement ALL changes from a report locally:

1. Reads the scan report HTML to extract repos, files, changes
2. Clones/pulls all affected repos
3. Creates identical feature branches in each repo (LOCAL ONLY)
4. Installs dependencies
5. Implements changes in dependency order (spawns agents per repo)
6. Builds all repos, runs tests
7. Starts all services locally
8. Generates delivery report with testing instructions

Safety: NEVER pushes to remote. All changes stay on local branches. Includes rollback instructions.

• Apply locally — --apply report.html implements everything on local branches
• Start implementing — uses /create for each repo in dependency order
• Create Jira tickets — one ticket per affected repo with change details + blocked-by links
• Just the report — for planning purposes only

Every scan generates both an HTML and a JSON file (same filename, different extension). The JSON uses a structured schema with: title, changeRequest, date, reposScanned, reposAffected, complexity, executiveSummary, architectureFlow, implementationOrder, affectedRepos (with per-file changes + currentCode/newCode snippets), unaffectedRepos, riskAssessment, and suggestedApproach.

The JSON can be consumed by --apply mode, CI pipelines, or external tools. Use --convert-json to retroactively generate JSON from older HTML-only reports.

1. Code Quality Loop — /dev-team iterative scan/fix/test
2. Playwright E2E — browser tests, failure triage, coverage gaps
3. Docker Pipeline — build, deploy, integration tests against live container
4. Master Report — compiles everything into one HTML document