workflow

name	workflow
description	Complete development workflow from planning to GitHub PR using PARA methodology and RLM for large codebases. Use when implementing a feature, fixing a bug, refactoring, or taking work from plan to GitHub PR.
triggers	["/workflow","implement a feature","fix bug end to end","refactor code","add functionality","architecture change","large codebase work","complex task","start development","plan to github"]

Workflow Skill

Core Philosophy

"Structure + Execution = Reproducible Results."

This workflow is a pure orchestrator that coordinates specialized skills through phases. It does not implement functionality directly—it delegates to the appropriate skill for each task.

Orchestration Model:

Plan (para) → Branch → Execute (developer) → Test (testing) → Validate (reviewers) → Commit (git-commits) → PR → Monitor

Each phase invokes one or more specialized skills. The workflow ensures proper sequencing, gates, and parallel execution.

⚠️ ENFORCEMENT: Phase gates are MANDATORY. See GATES.md for all gate checklists and enforcement mechanisms.

---

When to Use This Workflow

Use the workflow skill when you need to:

• Implement a feature end-to-end (plan → code → test → PR)
• Fix a bug with full TDD cycle
• Refactor code with complete validation
• Take work from concept to merged PR
• Ensure quality gates are enforced (tests, code review, security)

Skip this workflow for:

• Read-only queries or explanations
• Quick fixes without tests
• Simple documentation updates

---

The 8 Phases (Overview)

Phase	Goal	Skill Used	Details
1. Plan	Create implementation plan with Design Ownership + Readiness checklists	para, architect	PHASES.md
2. Worktree	Set up isolated workspace	-	PHASES.md
3. Execute	Implement using TDD	developer	PHASES.md
4. Test	Validate all tests pass	phase-testing-agent	PHASES.md
5. Validate	Quality + security review	phase-validation-agent	PHASES.md
5.5 Diff Review	Human approval of diff before commit	-	PHASES.md
6. Commit	Stage work for PR	git-commits	PHASES.md
7. PR	Create GitHub pull request	phase-pr-agent	PHASES.md
8. Monitor	Document and clean up	para, documentation	PHASES.md

Detailed phase protocols: See PHASES.md for complete phase-by-phase instructions.

---

Required Skills

This workflow coordinates these specialized skills:

• para - Planning, execution, summarization (/plan, /execute, /summarize)
• developer - TDD implementation (MANDATORY for all code)
• architect - Technical specifications and design documents
• testing - Test design and execution (unit, integration, e2e)
• code-reviewer - Code quality review
• security-reviewer - Security audit and vulnerability detection
• git-commits - Commit message conventions
• documentation - README, API docs, ADRs
• rlm - Large codebase processing (100+ files)
• refactoring - Safe structural changes
• debugging - Bug reproduction and fixing
• dependencies - Dependency management
• performance - Profiling and optimization
• ci-cd - Pipeline configuration

Skills are invoked by reading their SKILL.md files. Example: Read skills/developer/SKILL.md for TDD implementation protocol.

---

Reference Documents

For detailed information, see these reference files:

• PHASES.md - Detailed protocol for all 8 phases
• PRODUCT_PROPOSALS.md - Product proposal validation protocol (user stories + E2E tests)
• GATES.md - Gate checklists and retry loops (MANDATORY enforcement)
• MCP.md - MCP integration (Atlassian, Datadog, Playwright)
• TOOLS.md - Tool usage for file modifications (Edit/Write/Read)
• AGENTS.md - Phase agent specifications (testing, validation, PR)
• PARALLEL.md - Parallel execution patterns
• ENFORCEMENT.md - Gate enforcement mechanisms and scripts
• context/data/DRIVERS_SEAT.md - Design ownership protocol (deep plans, readiness requirements, diff review gate)

---

Quick Start

1. Plan Your Work

/plan <task-description>

Creates detailed plan in context/plans/YYYY-MM-DD-<task>.md. For technical designs, also use architect skill and tech_proposal_template.md.

Jira Epic/Initiative input: When given a Jira Epic or Initiative, Phase 1 breaks it down into Stories and Tasks (Epic → Stories + Tasks; Initiative → Backend Epic + Frontend Epic → Stories + Tasks). Dependencies are explicitly identified with parallel-work patterns (backend API contract + mocks first). See PHASES.md for full breakdown rules.

⛔ MANDATORY APPROVAL GATE: After creating the plan, you MUST:

• Present the plan to the user clearly
• STOP and WAIT for explicit user approval
• Do NOT proceed to Phase 2 without approval

Post-Approval Actions: After user approves:

• Add FULL plan as comment to Jira ticket (if Jira key provided) - includes all sections verbatim, not a summary
• Create Jira tickets from plan (if Epic/Initiative breakdown performed)

See GATES.md for complete approval gate protocol.

2. Execute All Phases

After plan approval, phases 2-8 execute autonomously:

• No stopping between phases
• Automatic gate enforcement
• Progress tracking with TodoWrite
• Only escalate if gate fails or critical blocker

3. Monitor Gates

Watch for these critical gates:

• Phase 4: All tests must pass
• Phase 5: Code review + security review (MANDATORY)
• Phase 5.5: Diff Review Gate — human approval of diff before commit (BLOCKING)
• Phase 7: PR created successfully

See GATES.md for complete gate checklists.

---

Tool Usage (CRITICAL)

⛔ NEVER create temporary bash scripts for file modifications

• ✅ ALWAYS use Edit tool for modifying existing files
• ✅ ALWAYS use Write tool for creating new files
• ❌ NEVER create temporary scripts (fix.sh, replace.sh, etc.)
• ❌ NEVER use sed/awk/perl for source code modifications

See TOOLS.md for complete tool usage guidelines and examples.

---

MCP Integration

After running /setup, use these MCP servers:

• Atlassian (atlassian, atlassian-tech) - Jira tickets, Confluence docs
  • Phase 1: Get ticket context
  • Phase 2: Transition to "In Progress"
  • Phase 7: Link PR, transition to "In Code Review"
• Datadog - Logs, metrics, monitors, traces
  • Phase 8: Monitor deployment, check for errors
  • debugging/ci-cd: Observability
• Playwright - Browser automation (MANDATORY for UI)
  • Phase 4: E2E testing for frontend work

See MCP.md for detailed integration instructions and examples.

---

Feedback Loops (MANDATORY)

The workflow enforces retry loops at each gate:

1. TDD Loop (Phase 3): Write test → Run (FAIL) → Write code → Run (PASS) → Refactor
2. Testing Loop (Phase 4): Run tests → If fail, fix code → Re-run tests
3. Validation Loop (Phase 5): Run 6 checks → If fail, fix issues → Re-run checks

Escalation Rules:

• Test fails 3+ times: Ask user for guidance
• Security vulnerability: STOP workflow, require user decision
• Conflicting requirements: Ask user to clarify

See GATES.md for complete feedback loop protocols.

---

Parallel Execution

Launch independent subagents in parallel for efficiency:

Phase 1 (Exploration):

Task(Explore, "Find affected files...")
Task(Explore, "Check existing patterns...")
Task(Bash, "Review git history...")

Phase 5 (Validation):

# phase-validation-agent runs all checks internally in parallel
Task(general-purpose, "Read skills/agents/phase-validation-agent/AGENT.md...")

See PARALLEL.md for complete parallel execution patterns.

---

Workflow Checklist

• Phase 1: Plan created (para skill) with Design Ownership Checklist and Readiness Checklist
• ⛔ APPROVAL GATE: User explicitly approved the plan (BLOCKING - do not proceed without this)
• Post-approval: FULL plan added as comment to Jira ticket (complete contents, not summary) - if Jira key provided
• Post-approval: Jira tickets created from plan (if Epic/Initiative breakdown performed)
• Phase 2: Git worktree created and initialized
• Phase 3: Implementation complete (developer skill, TDD)
• Phase 4: Test validation complete (all tests pass, build succeeds)
• Phase 5: Validation complete (formatter, linter, build, tests, code review, security review)
• ⛔ DIFF REVIEW GATE: User explicitly approved the diff (BLOCKING - do not commit without this)
• Phase 6: Changes committed and pushed
• Phase 7: PR created as draft; marked ready after all commits
• Phase 8: CI/bot monitoring complete (one-pass), summary documented, worktree cleaned up

---

Output

At the end of Phase 1 (BEFORE proceeding to Phase 2):

• Display complete plan in conversation
• Wait for explicit user approval
• Do NOT proceed without approval

When complete (ONLY after all phases and gates pass):

• Display complete summary in conversation (read from context/summaries/YYYY-MM-DD-<task>.md)
• Merged PR URL
• Confirmation that all tests pass
• Confirmation that build succeeds
• Worktree path for cleanup
• Link to summary document in context/summaries/

---

Cross-Skill Integration

Situation	Skill to invoke	How
Phase 1 needs technical architecture	architect skill	Read skills/architect/SKILL.md
Phase 3 implementation uses TDD	developer skill	Read skills/developer/SKILL.md
Phase 4 testing details	testing skill	Read skills/testing/SKILL.md
Phase 5 code review	code-reviewer skill	Read skills/code-reviewer/SKILL.md
Phase 5 security review	security-reviewer skill	Read skills/security-reviewer/SKILL.md
Phase 6 commit messages	git-commits skill	Read skills/git-commits/SKILL.md
Phase 8 documentation	documentation skill	Read skills/documentation/SKILL.md
Large codebase in any phase	rlm skill	Read skills/rlm/SKILL.md