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. Read skills/workflow/ENFORCEMENT.md for validation enforcement mechanisms, scripts, and pre-commit hooks to prevent skipping critical phases (especially Phase 5: code review + security review).

Required Skills

This workflow must use the para, developer, rlm, architect, testing, code-reviewer, security-reviewer, documentation, git-commits, refactoring, debugging, dependencies, performance, ci-cd, and setup skills. Invoke them by reading and following their skill files: e.g. read skills/para/SKILL.md for plan/execute/summarize/archive, read skills/developer/SKILL.md for TDD implementation, and read skills/architect/SKILL.md plus skills/architect/tech_proposal_template.md when writing plans that need technical design. Details below.

Setup skill (MCP: Atlassian, Atlassian Tech, Datadog, Playwright)

Run /setup before using Jira, Confluence, Datadog, or Playwright in the workflow. After setup, use Atlassian MCP (atlassian or atlassian-tech) for tickets and Confluence, Datadog MCP for logs, metrics, and monitors, and Playwright MCP for UI testing (see MCP integration below).

PARA skill (planning and execution phases)

RLM skill (large codebase exploration and analysis)

Architect skill (tech spec and design)

Developer skill (TDD implementation) - MANDATORY

MANDATORY: All implementation uses TDD. Read skills/developer/SKILL.md for the full protocol. The developer skill handles:

• •Feature implementation (tests define behavior first)
• •Bug fixes (reproduction test first)
• •Refactoring (tests as safety net)

Testing skill (test design and execution) - MANDATORY

MANDATORY: Testing is required before any PR. For UI/frontend work, Playwright MCP must be used for E2E testing.

Code reviewer skill (review before merge)

Security reviewer skill (security audit)

Documentation skill (docs and ADRs)

Git / commits skill (commit messages and changelog)

Refactoring skill (safe structure changes)

Debugging skill (repro and fix)

Dependencies skill (upgrade and lockfile)

Performance skill (profile and optimize)

CI/CD skill (pipeline and deploy)

Use PARA for plan → execute → summarize → archive. Use developer (MANDATORY) for all implementation—enforces TDD (tests before code) for features, bug fixes, and refactoring. Use RLM when the codebase is large (>100 files) or when you need to find usage/patterns across many files. Use architect when writing a tech spec or design document before implementation. Use testing (MANDATORY) when adding or running tests—all tests must pass before PR; use Playwright MCP for UI/E2E testing. Use code-reviewer when reviewing PRs or diffs. Use security-reviewer when auditing for vulnerabilities or before release. Use documentation when writing or updating docs. Use git-commits when writing commit messages or changelogs. Use refactoring when changing structure without behavior. Use debugging when investigating or fixing bugs (with TDD reproduction test). Use dependencies when upgrading or resolving deps. Use performance when profiling or optimizing. Use ci-cd when configuring or fixing pipelines and deploy. Use setup when the user wants to add or reconfigure Atlassian, Datadog, or Playwright MCP for Claude or Cursor.

MCP Integration (Atlassian, Atlassian Tech, Datadog, Playwright)

After /setup has been run and MCPs are configured, use these tools when relevant:

Skills that should use these MCPs when the task involves tickets or observability: workflow (Jira/Confluence in plan and PR; Jira transitions: In Progress at Phase 2, In Code Review at Phase 7), ci-cd (Datadog for monitoring/observability), debugging (Datadog logs/traces), documentation (Confluence for docs), testing (Playwright for UI tests). Use atlassian or atlassian-tech as appropriate for the context.

Parallel Execution Groups (Subagents)

CRITICAL: The following skill groups can and SHOULD run as parallel subagents to maximize efficiency. Launch all subagents in a single message using multiple Task tool calls.

Group 1: Validation (Phase 5)

These skills are independent and should run as parallel subagents:

Example parallel launch:

Task(subagent_type="general-purpose", prompt="Run code-reviewer skill on changed files...")
Task(subagent_type="general-purpose", prompt="Run security-reviewer skill on changed files...")
Task(subagent_type="Bash", prompt="Run test suite: npm test")
Task(subagent_type="Bash", prompt="Run formatter and linter and build: npm run format && npm run lint && npm run build")

Group 2: Exploration (Phase 1)

When exploring the codebase, launch parallel Explore subagents:

Group 3: Test Writing (Phase 4)

When writing tests for multiple components:

Group 4: Documentation (Phase 8)

After implementation, documentation tasks can parallelize:

Sequential Skills (Do NOT Parallelize)

These skills depend on previous results and must run sequentially:

• •debugging → requires investigation results before fix
• •refactoring → requires understanding before changing
• •dependencies → requires conflict analysis before resolution
• •performance → requires profiling before optimization
• •git-commits → requires all changes complete before commit

Feedback Loops (MANDATORY)

⚠️ CRITICAL: The workflow enforces retry loops at each gate. You MUST NOT proceed until all checks pass.

Loop 1: TDD Cycle (Phase 3)

┌─────────────────────────────────────────────────────────────┐
│                    TDD FEEDBACK LOOP                        │
│                                                             │
│   Write Test ──► Run Test ──► FAIL? ──► Write Code ──┐     │
│       ▲                                              │     │
│       │                                              ▼     │
│       │                                         Run Test   │
│       │                                              │     │
│       │                        ┌─────────────────────┤     │
│       │                        │                     │     │
│       │                     PASS?                 FAIL?    │
│       │                        │                     │     │
│       │                        ▼                     ▼     │
│       │                   Refactor            Fix Code     │
│       │                        │                     │     │
│       │                        ▼                     │     │
│       └──── More behaviors? ◄──┴─────────────────────┘     │
│                    │                                        │
│                   Done                                      │
└─────────────────────────────────────────────────────────────┘

Retry until: All tests pass for current behavior before moving to next.

Loop 2: Testing Gate (Phase 4)

┌─────────────────────────────────────────────────────────────┐
│                  TESTING FEEDBACK LOOP                      │
│                                                             │
│   Run All Tests ──► All Pass? ──► YES ──► Proceed          │
│        ▲                │                                   │
│        │               NO                                   │
│        │                │                                   │
│        │                ▼                                   │
│        │         Identify Failures                          │
│        │                │                                   │
│        │                ▼                                   │
│        │           Fix Issues                               │
│        │                │                                   │
│        └────────────────┘                                   │
│                                                             │
│   Max retries: Until all pass (no limit)                    │
│   Escalate: If stuck after 3 attempts, ask user            │
└─────────────────────────────────────────────────────────────┘

Checks (ALL must pass):

• • Unit tests pass
• • Integration tests pass
• • E2E tests pass (if UI)
• • Build succeeds

On failure:

1. •Identify which test(s) failed
2. •Analyze failure reason
3. •Fix the code (not the test, unless test is wrong)
4. •Re-run ALL tests
5. •Repeat until all pass

Loop 3: Validation Gate (Phase 5)

┌─────────────────────────────────────────────────────────────┐
│                 VALIDATION FEEDBACK LOOP                    │
│                                                             │
│   Run Validations ──► All Pass? ──► YES ──► Proceed        │
│        ▲                  │                                 │
│        │                 NO                                 │
│        │                  │                                 │
│        │                  ▼                                 │
│        │         ┌────────┴────────┐                       │
│        │         │                 │                       │
│        │   Linter/Format?       Review?                    │
│        │         │                 │                       │
│        │         ▼                 ▼                       │
│        │    Run format,       Address                     │
│        │    auto-fix lint,    feedback                    │
│        │         │                 │                       │
│        └─────────┴─────────────────┘                       │
│                                                             │
│   Max retries: Until all pass (no limit)                    │
│   Escalate: If security issue can't be resolved, STOP      │
└─────────────────────────────────────────────────────────────┘

Checks (ALL must pass):

• • Formatter run and code formatted (project style)
• • Linter passes (auto-fix allowed)
• • Build succeeds
• • Code review passed
• • Security review passed

On failure:

1. •Formatting/Linter fails: Run formatter (e.g. npm run format), then linter with auto-fix, then manual fix remaining
2. •Build fails: Fix compilation/bundling errors
3. •Code review fails: Address feedback, improve code
4. •Security review fails: Fix vulnerability (NEVER skip)
5. •Re-run ALL validations
6. •Repeat until all pass

Escalation Rules

Loop Enforcement

The workflow MUST:

1. •Track retry count for each gate
2. •Log each failure and fix attempt
3. •Never proceed with failing checks
4. •Ask user if stuck (after reasonable attempts)
5. •Document all retries in commit message or summary

Protocol: PARA-Driven Development Workflow

BLOCKING REQUIREMENT: Follow phases in order. Do NOT skip phases or make assumptions about what needs to be done.

⛔ MANDATORY TESTING: Testing is NOT optional. The workflow MUST include:

• •Writing and passing tests (Phase 4)
• •Build verification (Phase 4/5)
• •For UI: E2E tests via Playwright MCP
• •NEVER suggest tests as "optional" or "next steps"
• •STOP and write tests before proceeding to commit

⛔ MANDATORY VALIDATION: Phase 5 validation is NOT optional. The workflow MUST include:

• •Code review via code-reviewer subagent (Phase 5)
• •Security review via security-reviewer subagent (Phase 5)
• •NEVER skip or suggest reviews as "optional" or "next steps"
• •STOP and run ALL 5 validations before proceeding to commit
• •Use validation script to verify: python3 skills/workflow/scripts/validate_phase.py --phase 5

OUTCOME FOCUS: Work continues until PR is merged or explicitly stopped by user. Track progress visibly at each phase.

PARALLEL EXECUTION: Launch multiple subagents simultaneously for independent tasks within the same phase. Track all parallel work with TodoWrite tool.

PARA SKILL INVOCATION: This workflow must use the para skill. At the start of any workflow run, read skills/para/SKILL.md and follow it for:

• •Plan phase: Use PARA's /plan semantics: create context/plans/YYYY-MM-DD-<task-name>.md, document objectives/approach/steps, and follow PARA's Plan and Review phases.
• •Execute phase: Use PARA's /execute semantics: track progress, reference the plan, document deviations.
• •Summarize phase: Use PARA's /summarize semantics: create context/summaries/YYYY-MM-DD-<task-name>.md with outcomes and learnings.
• •Archive phase: Use PARA's /archive when work is complete to move plans/summaries to context/archives/.

Do not implement a custom plan/execute/summarize flow; use the para skill's structure and commands.

Multi-Subagent Coordination

This workflow uses multiple specialized subagents working in parallel:

1. •Launch parallel subagents when tasks are independent
2. •Use TodoWrite to track all parallel tasks
3. •Wait for completion before moving to next phase
4. •Consolidate results from all subagents
5. •Proceed to next phase only after all subagents complete

Key Rules:

• •All subagents must complete Phase N before any start Phase N+1
• •Independent tasks within a phase can run in parallel
• •Dependent tasks must run sequentially
• •Use terminal/shell with background execution for long-running tasks (builds, tests)

Phase 1: Plan

Goal: Create detailed implementation plan before writing code.

PARA command: Use /plan <task> to create the plan. Follow the para skill (skills/para/SKILL.md) for plan creation, file location (context/plans/YYYY-MM-DD-<task-name>.md), and Review phase (present plan for approval).

Plan skills and tech proposal: When the plan involves technical design, architecture, new features, or system changes:

• •Read and follow the architect skill (skills/architect/SKILL.md).
• •Use the tech proposal template (skills/architect/tech_proposal_template.md): read it first, then structure the plan (or a separate tech spec) using its sections (Metadata, Architecture Considerations, API Changes, Data Models, Domain Architecture, Additional Considerations, Estimation & Implementation Plan). Output a tech spec to docs/tech-specs/YYYY-MM-DD-<feature>.md or context/tech-specs/ when appropriate, and reference it from the plan.

Skills: Use para skill for planning; use architect skill and tech_proposal_template.md when the plan requires technical design or a tech spec.

Actions:

1. •Understand the requirements and task scope
2. •Explore affected code sections using parallel subagents
3. •Identify implementation approach and files to modify
4. •If tech design is needed: read architect skill and tech_proposal_template.md; produce structured plan or tech spec using the template
5. •Create plan via PARA /plan: document in context/plans/YYYY-MM-DD-<task-name>.md

⚡ PARALLEL SUBAGENTS for exploration (launch in single message):

Task(subagent_type="Explore", prompt="Find all files related to [feature area]. Identify components, patterns, and dependencies.")
Task(subagent_type="Explore", prompt="Search for existing patterns for [similar functionality] in codebase.")
Task(subagent_type="Bash", prompt="Check git history for recent changes to [affected area]: git log --oneline -20 -- path/")
Task(subagent_type="Explore", prompt="Find test files and patterns for [feature area] to understand testing approach.")

For large codebases (100+ files), use RLM skill instead of multiple Explore agents.

Plan Document Contents:

• •Objective (1-2 sentences)
• •Approach (how you'll solve it)
• •Affected files and components
• •Implementation steps (numbered)
• •Edge cases and risks
• •Testing strategy

When the plan involves architecture or tech design, also structure content using tech_proposal_template.md (Metadata, Architecture Considerations, API Changes, Data Models, Domain Architecture, Additional Considerations, Estimation & Implementation Plan)—either inline in the plan or in a separate tech spec file referenced from the plan.

Approval Gate:

• •Present plan to user for review
• •User can approve, request changes, or provide clarification
• •Do NOT proceed to execution without approval

Commit Plan to Git:

After plan approval, commit it to git:

git add context/plans/<plan-file>.md
git commit -m "docs: add plan for <task>"

Phase 2: Create Feature Branch

Goal: Set up isolated work environment.

Actions:

1. •If a Jira ticket key is provided: Use Atlassian MCP to transition the issue to In Progress. Call jira_get_transitions with the issue key, find the transition whose name matches "In Progress" (or "In progress"; names vary by project), then call jira_transition_issue with that transition ID. This marks the ticket as in progress before implementation starts.
2. •Create feature branch: git checkout -b feature/<description> or fix/<description>
3. •Confirm branch creation with git status

Phase 3: Execute Implementation

Goal: Implement according to approved plan.

PARA command: Use /execute to implement with tracking and context.

Skill: Use the developer skill (skills/developer/SKILL.md) for all implementation. The developer skill enforces TDD (Test-Driven Development).

Actions:

1. •Start execution with /execute; track progress with TodoWrite tool
2. •Read and follow the developer skill for implementation:
   • •Features: Red-Green-Refactor cycle (tests first)
   • •Bug fixes: Write reproduction test first, then fix
   • •Refactoring: Tests as safety net
3. •Use parallel subagents for efficient execution:
   • •Bash agent: Git operations, command execution, builds
   • •Explore agent: Code navigation, pattern discovery
   • •General-purpose agent: Research, complex analysis, test writing
   • •RLM skill: Parallel implementation on multiple independent files/components
4. •Reference plan document during execution
5. •Commit changes atomically with clear messages
6. •Document deviations from plan in commit messages

Parallel Execution Strategy:

• •Break independent tasks into subtasks for parallel processing
• •Use RLM for map-reduce style implementation across many files
• •Different agents can work on different components simultaneously
• •Merge results after all subtasks complete

Quality Gates (from developer skill):

• • TDD followed (tests before code)
• • All tests pass
• • Code follows project conventions
• • No security vulnerabilities
• • Changes are minimal and focused

Phase 4: Testing Validation (MANDATORY)

Goal: Verify all tests pass and coverage is adequate.

⚠️ BLOCKING REQUIREMENT: Testing is MANDATORY. Do NOT proceed to Phase 5 until all tests pass.

Skills: Use the testing skill for test execution and the developer skill for TDD validation. For UI/frontend work, Playwright MCP is MANDATORY.

NOTE: If following the developer skill (TDD) correctly, tests should already exist from Phase 3. This phase validates and extends coverage.

Language-Specific Requirements:

Actions:

1. •Verify tests from Phase 3 (developer skill TDD) are passing
2. •Add additional test coverage using parallel subagents:
   • •Bash agent: Run test suite, execute build commands
   • •General-purpose agent: Write additional edge case tests
   • •Explore agent: Find existing test patterns and files to emulate
   • •Playwright MCP: For UI testing (mandatory if frontend)
3. •Test coverage requirements:
   • •Happy path (primary use case)
   • •Edge cases (boundary conditions, empty data)
   • •Error handling (invalid inputs)
   • •Regression tests (existing scenarios still work)
4. •Parallel test execution:
   • •Run unit tests
   • •Run integration tests (if applicable)
   • •Run E2E tests via Playwright MCP (if UI exists)
5. •For frontend/UI projects: Verify build succeeds
6. •Fix any test failures or regressions
7. •Validate test coverage is reasonable

Required Coverage (ALL must pass to proceed):

• • New code is tested
• • Edge cases covered
• • No regressions in existing tests
• • Tests are deterministic (not flaky)
• • Frontend: Build succeeds (mandatory for JS/TS/Node projects)

⚠️ RETRY LOOP (MANDATORY):

WHILE any test fails:
    1. Identify failed test(s)
    2. Analyze failure reason
    3. Fix code (or test if test is wrong)
    4. Re-run ALL tests
    5. IF same failure 3+ times: Ask user for guidance
END WHILE
→ Only proceed when ALL tests pass

DO NOT proceed to Phase 5 until this loop completes successfully.

• • UI: E2E tests via Playwright MCP (mandatory if UI exists)

⚡ PARALLEL SUBAGENTS (launch in single message):

Task(subagent_type="Bash", prompt="Run existing test suite to establish baseline")
Task(subagent_type="Bash", prompt="Run build to verify compilation: npm run build (or equivalent)")
Task(subagent_type="general-purpose", prompt="Write unit tests for [component A] following testing skill")
Task(subagent_type="general-purpose", prompt="Write unit tests for [component B] following testing skill")
Task(subagent_type="Explore", prompt="Find existing test patterns in codebase to emulate")

For UI projects, also use Playwright MCP:

Use Playwright MCP tools (browser_navigate, browser_click, browser_type, browser_screenshot) for E2E testing

Wait for all subagents to complete, then consolidate and fix any failures. Do NOT proceed until ALL tests pass and build succeeds.

Phase 5: Validation (MANDATORY)

Goal: Ensure quality and security.

⚠️ BLOCKING REQUIREMENT: All validation checks are MANDATORY. Do NOT proceed to Phase 6 until all checks pass.

Skills: Use code-reviewer, security-reviewer, and ci-cd skills.

Language-Specific Validation:

Actions:

1. •Run formatter: npm run format or equivalent (Prettier, Black, gofmt, cargo fmt, etc.)
2. •Run linter: npm run lint or equivalent (ESLint, ruff, golangci-lint, etc.)
3. •Run build: npm run build or equivalent (MANDATORY for compiled languages and frontend)
4. •Run tests: Verify all tests still pass after any fixes
5. •Security review (security-reviewer skill):
   • •No hardcoded secrets or credentials
   • •No expanded data access
   • •No common vulnerabilities (injection, XSS, etc.)
6. •Code review (code-reviewer skill):
   • •Clear variable names
   • •Logical flow is obvious
   • •Tests are meaningful
7. •Performance check (if applicable):
   • •No N+1 queries
   • •No significant performance degradation

Required Validation (ALL must pass to proceed):

• • Formatter run and code formatted (no style-only diffs left)
• • Linter passes with no errors
• • Build succeeds (mandatory for frontend, compiled languages)
• • All tests pass
• • Security review complete (no vulnerabilities)
• • Code review complete (acceptable quality)

⚠️ RETRY LOOP (MANDATORY):

WHILE any validation fails:
    1. Identify which check(s) failed
    2. FOR format/linter errors:
       - Run formatter (e.g., npm run format, black ., gofmt -w .)
       - Run linter with auto-fix (e.g., npm run lint --fix)
       - Manually fix remaining issues
    3. FOR build errors:
       - Fix compilation/type errors
    4. FOR security issues:
       - Fix vulnerability (NEVER skip or ignore)
       - If unfixable, STOP and escalate to user
    5. FOR code review issues:
       - Address feedback
       - Improve code quality
    6. Re-run ALL validations
    7. IF same failure 3+ times: Ask user for guidance
END WHILE
→ Only proceed when ALL validations pass

DO NOT proceed to Phase 6 until this loop completes successfully.

⚡ PARALLEL SUBAGENTS (launch ALL in single message):

⛔ CRITICAL ENFORCEMENT: You MUST launch ALL 5 subagents below. DO NOT skip code-reviewer or security-reviewer. They are NOT optional.

Task(subagent_type="Bash", prompt="Run formatter and linter: npm run format && npm run lint (or project equivalent: black . && ruff check ., gofmt -s -w . && golangci-lint run, etc.)")
Task(subagent_type="Bash", prompt="Run build: npm run build (or project equivalent)")
Task(subagent_type="Bash", prompt="Run tests: npm test (or project equivalent)")
Task(subagent_type="general-purpose", prompt="Read skills/code-reviewer/SKILL.md and run code review on all changed files. Review for correctness, readability, maintainability, accessibility, i18n.")
Task(subagent_type="general-purpose", prompt="Read skills/security-reviewer/SKILL.md and run security review on all changed files. Check for injection, XSS, auth issues, sensitive data exposure, crypto vulnerabilities.")

VERIFICATION CHECKLIST (Complete BEFORE proceeding to Phase 6):

Before moving to Phase 6 (Commit), you MUST verify completion of ALL 5 tasks:

1. • Formatter and linter subagent completed - Result: PASS/FAIL
2. • Build subagent completed - Result: PASS/FAIL
3. • Tests subagent completed - Result: PASS/FAIL
4. • Code review subagent completed - Result: PASS/FAIL (with findings documented)
5. • Security review subagent completed - Result: PASS/FAIL (with findings documented)

IF any subagent was not launched: STOP. Go back and launch it now. This is a blocking requirement.

IF any check failed: Fix issues and re-run ALL validations until all pass.

Wait for all 5 subagents to complete, then consolidate findings and fix any issues before proceeding. Do NOT proceed until ALL validation checks pass.

Phase 6: Commit & Push

Goal: Stage work for PR creation.

⛔ PHASE 5 GATE ENFORCEMENT:

Before executing ANY action in Phase 6, you MUST verify Phase 5 completion:

PHASE 5 COMPLETION CHECKLIST:
✓ [ ] Formatter executed and code formatted
✓ [ ] Linter executed and passed
✓ [ ] Build executed and passed
✓ [ ] Tests executed and passed
✓ [ ] Code review subagent launched AND completed
✓ [ ] Security review subagent launched AND completed
✓ [ ] All findings from reviews addressed
✓ [ ] Re-validation completed after fixes

IF ANY item above is unchecked:
  → STOP immediately
  → Go back to Phase 5
  → Complete missing steps
  → Do NOT commit until ALL checks pass

Skill: Use git-commits skill for commit message conventions.

Actions:

1. •FIRST: Verify Phase 5 gate (checklist above) is complete
2. •Stage all relevant files: git add <files>
3. •Create commit with clear message (follow git-commits skill / project conventions)
4. •Push to remote: git push -u origin <branch-name>

Commit Message Format (Conventional Commits):

• •First line: <type>(<scope>): <summary> (50 chars max)
• •Blank line
• •Detailed explanation of why change was made
• •Reference issue/ticket if applicable

Note: This phase is sequential - must complete after validation passes.

Phase 7: Create GitHub PR

Goal: Submit work for team review.

Actions:

1. •Create PR as draft with gh pr create --draft so the PR is not ready for review until all work is pushed.
2. •Include in the PR:
   • •Clear title summarizing change
   • •Description with context and reasoning
   • •Link to related issue/ticket
   • •Test plan or validation steps
   • •Any breaking changes or migration notes
3. •Mark PR ready for review only after all commits are pushed: run gh pr ready (or gh pr ready <number>) when the branch is complete and no further commits are expected for this round.
4. •If a Jira ticket key was provided: After the PR is created (and optionally after marking it ready), use Atlassian MCP to transition the issue to In Code Review. Call jira_get_transitions for the issue, find the transition whose name matches "In Code Review" or "Code Review" (names vary by project), then call jira_transition_issue with that transition ID.

PR Description Template:

## Summary
[1-3 bullet points of what changed and why]

## Changes
[List of files modified and what changed]

## Test Plan
[Steps to verify the changes work]

## Risks/Notes
[Any concerns or things reviewers should know]

Phase 8: Monitor & Summarize

Goal: Document outcomes and capture learnings.

PARA command: Use /summarize once work is complete (e.g. after PR merge).

Skills: Use para skill for summary, documentation skill if docs need updating.

Actions:

1. •Monitor PR feedback and CI checks
2. •Address review comments
3. •Once merged, run /summarize to document in context/summaries/YYYY-MM-DD-<task-name>.md
4. •Update documentation if needed (README, API docs, ADRs)

Summary Document Contents:

• •What was built/fixed
• •Files modified (with impact)
• •Key decisions made
• •Lessons learned
• •Known limitations
• •Future improvements
• •Link to merged PR and commits

Commit Summary to Git:

After creating the summary, commit it to git:

git add context/summaries/<summary-file>.md
git commit -m "docs: add summary for <task>"

⚡ PARALLEL SUBAGENTS for documentation (if docs need updating):

Task(subagent_type="general-purpose", prompt="Update README.md with new feature/change following documentation skill")
Task(subagent_type="general-purpose", prompt="Update API docs for new/changed endpoints following documentation skill")
Task(subagent_type="general-purpose", prompt="Write ADR for architectural decision made, following documentation skill ADR format")

Only launch doc subagents if documentation updates are needed for this change.

Subagent Types & Parallel Execution

Use multiple subagents simultaneously to parallelize work across different task types:

Subagent Capabilities

Parallel Execution Patterns

Pattern 1: Explore + Write in Parallel

- Explore agent: Scan for existing test patterns
- General-purpose agent: Write new tests
- Results: Consolidate findings and update tests

Pattern 2: Build + Test + Validation Parallel

- Bash agent: Run build command
- Bash agent: Run test suite
- General-purpose agent: Code review
- Results: Consolidate status and fix failures

Pattern 3: RLM Map-Reduce

- RLM: Parallel analysis of 100+ files
- Multiple agents: Process different subsystems
- Consolidate: Merge results and implement

When to Use Multiple Subagents

Launch multiple subagents in parallel when:

• •Tasks are independent (one doesn't depend on another's result)
• •Same overall phase (e.g., multiple Test subtasks in Phase 4)
• •Time savings justify context overhead
• •Tasks are naturally divisible

RLM Integration for Large Codebases

When working with large repositories (100+ files):

1. •Use RLM Skill: Use the RLM skill for parallel exploration when the codebase has 100+ files
2. •Map-Reduce Pattern: Break complex tasks into parallel subtasks:
   • •Map: Parallel file search and analysis by multiple agents
   • •Reduce: Consolidate findings and implement
3. •Context Efficiency: RLM prevents context overflow in large projects
4. •Dependency Analysis: Use RLM to understand file relationships before editing

When to activate RLM:

• •Codebase has 100+ files
• •Task touches multiple subsystems
• •Need to understand cross-file dependencies
• •Search space is too large for sequential exploration

Parallel Agent Strategy with RLM:

• •RLM coordinates parallel subagents for different code sections
• •Each subagent analyzes its assigned portion
• •Results consolidated for coherent implementation
• •Prevents context rot on massive projects

Workflow Checklist

• • Phase 1: Plan created and approved (para skill)
• • Phase 2: Feature branch created
• • Phase 3: Implementation complete (developer skill)
  • • TDD followed (tests before code)
  • • All developer skill quality gates met
• • Phase 4: Test validation complete (testing skill)
  • • All tests pass
  • • Additional edge case tests added
  • • Integration tests pass (if applicable)
  • • E2E tests via Playwright MCP pass (if UI exists)
  • • Build succeeds (mandatory for frontend/compiled languages)
• • Phase 5: Validation complete (MANDATORY)
  • • Formatter run and code formatted
  • • Linter passes
  • • Build succeeds
  • • All tests pass
  • • Security review passed
  • • Code review passed
• • Phase 6: Changes committed and pushed
• • Phase 7: PR created as draft; marked ready with gh pr ready after all commits pushed
• • Phase 8: Summary documented after merge

⛔ BLOCKING GATES (Workflow MUST STOP if not met)

The workflow CANNOT proceed to Phase 6 (Commit) until ALL of these pass:

NEVER output "Optional next steps" for testing. Testing is NOT optional. If tests are missing:

1. •STOP the workflow
2. •Write the required tests
3. •Run tests until they pass
4. •Only then proceed to commit

For frontend projects specifically:

• •npm test (or equivalent) MUST pass
• •npm run build MUST succeed
• •If UI exists, E2E tests via Playwright MCP MUST pass

For backend projects (Go, Python, Ruby, Rust, Java):

• •Test command MUST pass (go test -race ./..., pytest, rspec, cargo test, mvn test)
• •Build command MUST succeed (if applicable)

Output

When complete (ONLY after all gates pass):

• •Merged PR URL
• •Summary of what was accomplished
• •Link to summary document in context/summaries/
• •Confirmation that all tests pass
• •Confirmation that build succeeds