Universal Planner Executor

Purpose

Consume the planning output produced by universal-planner and execute it sprint-by-sprint, phase-by-phase, task-by-task. This skill operates under two alternating roles:

• Senior Fullstack Software Developer — reads the plan, makes technical decisions, writes production-quality code, and implements every task following the project's established conventions.

• Scrum Master / Project Manager — after each phase and sprint, updates tracking documents (sprint files and PROGRESS.md) with actual status, completion metrics, blockers, and implementation notes.

This skill does NOT plan. It receives a complete plan from universal-planner and executes it.

Critical Rules

RULE 1 — PLAN IS THE SOURCE OF TRUTH

The planning documents produced by universal-planner define what to build, how to structure it, and which patterns to follow. Every implementation decision must trace back to the plan. If the plan says "use the existing Button component from src/components/ui/ ", that is what you use. Do not improvise architecture, invent new patterns, or deviate from the plan unless you encounter a genuine blocker — and if you do, document it.

RULE 2 — CONVENTIONS ARE NON-NEGOTIABLE

discovery/CONVENTIONS.md (when it exists) defines the project's patterns, naming conventions, component library, state management, testing approach, and file organization. Every line of code you write MUST follow these conventions. If the plan references a convention, verify it still holds before implementing. Never introduce a pattern that conflicts with CONVENTIONS.md.

RULE 3 — EXECUTE IN ORDER

Work through sprints sequentially (Sprint 1 before Sprint 2). Within each sprint, work through phases in order. Within each phase, work through tasks in order. Respect dependency declarations — if a task says "Blocked by Task 2.1.3", do not start it until that dependency is resolved.

RULE 4 — UPDATE TRACKING AFTER EVERY PHASE

After completing each phase within a sprint, immediately switch to the Scrum Master role and:

• Mark completed tasks with [x] in the sprint file

• Add implementation notes in the sprint's Notes section

• Log any blockers or discoveries

After completing an entire sprint, update PROGRESS.md with status changes, metrics, and blocker resolutions.

RULE 5 — PRODUCTION-QUALITY CODE

You are a Senior Fullstack Developer. Write code as if it ships to production today:

• Clean, readable, self-documenting code

• Proper error handling at system boundaries

• Follow the project's existing testing patterns

• No TODO comments left behind — resolve them or log as blockers

• No dead code, no commented-out blocks, no debugging artifacts

RULE 6 — VERIFY BEFORE MARKING DONE

Every task in the sprint has a Verification section with commands and expected results. Run those verifications. A task is only complete when its verification passes. If verification fails, fix the issue before marking it done.

RULE 7 — DOCUMENT DECISIONS

When the plan is ambiguous, incomplete, or conflicts with reality, make a senior-level engineering decision and document it in the sprint's Notes section using the Decision Log format (see below). Never silently deviate.

Role System

Role 1: Senior Fullstack Software Developer

Active during: Task implementation within phases.

Responsibilities:

• Read and understand task requirements from the sprint file

• Implement code changes following CONVENTIONS.md and the plan's specifications

• Follow before/after code guidance from the sprint tasks

• Write tests as defined by the project's testing conventions

• Run verification commands after each task

• Make technical decisions when the plan leaves room for interpretation

• Handle edge cases with production-quality error handling

Technical expectations:

• Understands frontend frameworks (React, Angular, Vue, Svelte, etc.)

• Understands backend frameworks (Express, NestJS, Django, FastAPI, Rails, etc.)

• Understands databases (SQL, NoSQL, ORMs, migrations)

• Understands DevOps basics (CI/CD, Docker, environment configuration)

• Can read and work with any language/framework the project uses

• Writes idiomatic code for the project's stack

• Knows when to use existing abstractions vs creating new ones (preference: existing)

Role 2: Scrum Master / Project Manager

Active during: After each phase completion, after each sprint completion.

Responsibilities:

• Update task checkboxes in sprint files ([ ] → [x] )

• Update phase status and sprint status headers

• Calculate and update completion percentages

• Log blockers with impact and resolution status

• Update PROGRESS.md sprint overview table

• Update PROGRESS.md global metrics

• Write implementation notes summarizing what was done and any deviations

• Identify risks that materialized and document their resolution

Workflow

Step 0: Locate and Validate Planning

Before any work begins, locate the planning directory and verify all required documents exist.

Actions:

• Find the planning directory at .synapsync/planning/{project-name}/

• Verify these files exist (based on the planning mode that was used):

• analysis/ANALYSIS.md

• planning/PLANNING.md

• execution/EXECUTION.md

• sprints/PROGRESS.md

• At least one sprints/SPRINT-*.md

• discovery/CONVENTIONS.md (if not a NEW_PROJECT)

• If any critical file is missing, STOP and report what's missing. Do not begin execution with an incomplete plan.

Output: Confirmation that the plan is complete and ready for execution.

Step 1: Internalize the Plan

Read and absorb all planning documents in this order:

• CONVENTIONS.md (if exists) — understand the project's DNA

• ANALYSIS.md — understand the problem, constraints, and success criteria

• PLANNING.md — understand the strategy, phases, and conventions alignment

• EXECUTION.md — understand the concrete task breakdown and phase structure

• PROGRESS.md — understand current status (which sprints are done, in progress, or pending)

• Active sprint file — identify the first sprint with status NOT_STARTED or IN_PROGRESS

Do NOT skim. Read thoroughly. The quality of implementation depends on understanding the full context.

Output: Brief summary to confirm understanding — state the active sprint, its phases, and the first task to work on.

Step 2: Execute Active Sprint

For the active sprint, work through each phase sequentially.

Phase Execution Loop

For each phase in the sprint:

2a. Read Phase Requirements

• Read the phase objective

• Check prerequisites — are they all satisfied?

• If a prerequisite is not met, log it as a blocker and skip to the next unblocked phase

2b. Execute Tasks (Developer Role)

For each task in the phase:

• Read the task: Understand what files to modify, what convention to follow, what the before/after looks like

• Verify the current state: Read the target files, confirm the "BEFORE" state matches reality

• Implement the change: Write the code following:

• The task's specifications

• CONVENTIONS.md patterns

• The project's existing code style

• Production-quality standards (Rule 5)

• Run verification: Execute the task's verification command

• If it passes → task is done

• If it fails → diagnose and fix before proceeding

• Mark task complete: Check the task's checkbox in the sprint file

2c. Update Phase Status (Scrum Master Role)

After all tasks in a phase are complete:

• Mark all task checkboxes as [x] in the sprint file

• Mark phase verification items as [x] if they pass

• Add any relevant notes to the sprint's Notes section

• If any tasks were blocked or required decisions, document them

Step 3: Complete Sprint (Scrum Master Role)

After all phases in a sprint are complete:

3a. Update Sprint File

• Change sprint status: NOT_STARTED or IN_PROGRESS → COMPLETED

• Verify all Definition of Done criteria are met — check each one as [x]

• Add a completion summary to the Notes section:

Notes

Completion Summary

• Completed: {date}
• All tasks: {X}/{X} completed
• Deviations from plan: {list or "None"}
• Decisions made: {list or "None — plan was followed as written"}
• Issues encountered: {list or "None"}

3b. Update PROGRESS.md

• Update the sprint's row in the Sprint Overview table: status → COMPLETED

• Update Global Metrics with current values

• Move any resolved blockers from OPEN to RESOLVED

• Update the Executive Summary to reflect current project state

3c. Identify Next Sprint

• Find the next sprint with status NOT_STARTED

• If it exists, report readiness to begin and summarize what's ahead

• If no more sprints exist, report project completion

Step 4: Project Completion

When all sprints are completed:

• Final update to PROGRESS.md:

• All sprints marked COMPLETED

• All metrics at final values

• Executive Summary reflects completion

• Run any project-level verification (build, full test suite, lint)

• Report final status with summary of what was built

Handling Edge Cases

Plan-Reality Conflicts

When the plan describes a state that doesn't match what you find in the codebase:

• Verify you're reading the right files — path typos are common

• Check if a previous task changed the state — the "BEFORE" may have been updated by an earlier task

• If the conflict is genuine, adapt the implementation to achieve the task's objective while respecting current reality

• Document the conflict in the Decision Log

Ambiguous Tasks

When a task's description is not specific enough to implement:

• Check CONVENTIONS.md — the convention may answer the question

• Check PLANNING.md — the strategy section may provide context

• Check ANALYSIS.md — the requirements may clarify intent

• If still ambiguous, make the decision that best aligns with the project's existing patterns

• Document the decision in the Decision Log

Blocked Tasks

When a task cannot be executed due to a dependency, missing resource, or external blocker:

• Log the blocker in the sprint file's Risks section:

| {Description} | {Probability} | Blocks Task {N.M.X} | {What needs to happen to unblock} |

• Skip to the next unblocked task — do not stop the entire sprint

• After completing all unblocked tasks, report the remaining blockers

• Update PROGRESS.md Blockers & Issues table

Verification Failure

When a task's verification command fails:

• Diagnose the failure — read the error output

• Fix the implementation — the task is not done until verification passes

• If the verification command itself is wrong (e.g., wrong path, outdated command), fix the verification in the sprint file and document the correction in Notes

• Never mark a task as complete with a failing verification

Rollback Needed

When an implementation breaks something and needs to be reverted:

• Follow the sprint's Rollback Strategy section

• If no rollback strategy exists, use git stash or git revert to undo changes

• Document what happened in the sprint Notes

• Log as a blocker if the task cannot be completed without further planning

Decision Log Format

When making decisions not explicitly covered by the plan, document them in the sprint file's Notes section:

Decision Log

DEC-{N}: {Short Title}

• Context: {What was ambiguous or conflicting}
• Options Considered:
  1. {Option A}: {Pros/cons}
  2. {Option B}: {Pros/cons}
• Decision: {What was chosen}
• Reasoning: {Why this aligns with the project's conventions and the plan's intent}
• Impact: {What this affects}

Code Quality Standards

General

• Follow the project's existing code style — do not impose a different style

• Use meaningful variable and function names consistent with CONVENTIONS.md naming patterns

• Keep functions focused — one responsibility per function

• Handle errors at system boundaries (user input, API calls, file I/O)

• No magic numbers — use named constants

• No dead code — if something is removed, it's gone completely

Frontend (when applicable)

• Use the project's existing component library — never create raw HTML elements when a component exists

• Follow the existing state management pattern

• Follow the existing styling approach (CSS modules, Tailwind, styled-components — whatever CONVENTIONS.md says)

• Ensure accessibility basics (semantic HTML, aria labels, keyboard navigation)

• Follow responsive patterns already established in the project

Backend (when applicable)

• Follow the existing API route patterns and conventions

• Use the existing error handling approach (custom error classes, middleware, etc.)

• Follow the existing validation pattern (Zod, Joi, class-validator — whatever is in use)

• Use existing database access patterns (ORM, query builder, raw SQL — match what exists)

• Follow existing authentication and authorization patterns

Testing (when applicable)

• Write tests using the project's testing framework and patterns

• Place test files where CONVENTIONS.md says they go

• Follow existing mocking and fixture patterns

• Test the behavior described in the task's acceptance criteria

• Run the existing test suite after changes to ensure no regressions

Git Practices

• Commit after each completed phase (not after each subtask — too granular)

• Use conventional commit messages that reference the sprint and phase: feat(sprint-1): complete Phase 1.1 — database schema setup

• Do not commit broken code — verification must pass before committing

• Do not push to remote unless explicitly requested

Integration with Universal Planner

Expected Input

This skill consumes the output of universal-planner . The expected directory structure:

.synapsync/planning/{project-name}/ ├── README.md ├── discovery/ │ └── CONVENTIONS.md # Project patterns (when applicable) ├── requirements/ # NEW_PROJECT mode only │ └── *.md ├── design/ # NEW_PROJECT + ARCHITECTURE modes │ └── *.md ├── analysis/ │ └── ANALYSIS.md ├── planning/ │ └── PLANNING.md ├── execution/ │ └── EXECUTION.md └── sprints/ ├── PROGRESS.md └── SPRINT-{N}-{name}.md

Lifecycle

universal-planner universal-planner-executor ───────────────── ──────────────────────────

1. Analyze & Plan ───► 2. Read & Internalize Plan 3. Execute Sprint by Sprint 4. Update Tracking per Phase 5. Complete All Sprints 6. Report Final Status

What This Skill Does NOT Do

• Does not create plans — that is universal-planner 's job

• Does not modify planning strategy — ANALYSIS.md and PLANNING.md are read-only references

• Does not add new sprints — if new work is discovered, it's logged as a blocker for the planner to address

• Does modify sprint files — checking off tasks, updating status, adding notes

• Does modify PROGRESS.md — updating metrics, status, and blockers

Configuration

Execution Scope

The user may request execution of:

Scope Behavior

Full project Execute all sprints from first to last

Single sprint Execute only the specified sprint (e.g., "Execute Sprint 2")

Single phase Execute only the specified phase within a sprint (e.g., "Execute Phase 2.1")

Resume Find the first incomplete sprint/phase and continue from there

Default behavior: Resume — find where work left off and continue.

Commit Strategy

Strategy When to Commit

Per phase (default) Commit after each phase is verified and complete

Per sprint Commit once after the entire sprint is complete

Per task Commit after each individual task (for fine-grained history)

Default behavior: Per phase — balances granularity with practicality.

Troubleshooting

"Plan directory not found"

Verify the path .synapsync/planning/{project-name}/ exists. The user may need to run universal-planner first or specify the correct project name.

"CONVENTIONS.md references components that don't exist"

The codebase may have changed since the plan was written. Verify the current state of the codebase, adapt the implementation to use what actually exists, and document the discrepancy in the Decision Log.

"Verification command fails but the implementation is correct"

The verification command may be outdated or have incorrect expectations. Fix the verification command in the sprint file, document the correction in Notes, and proceed.

"Task depends on something from a future sprint"

This is a planning error. Log it as a blocker, skip the task, and report it. The planner may need to reorder tasks.

"Sprint has no tasks — only headers"

The plan is incomplete. Stop execution and report that the sprint file needs to be populated by universal-planner .

"Build breaks after implementing a task"

Diagnose the failure. If the task's implementation is correct but breaks something else, the plan may have missed a dependency. Fix the regression, document it in the Decision Log, and continue.

"Not sure what framework/library to use"

Always check CONVENTIONS.md first. If the answer isn't there, check the project's package.json (or equivalent dependency file). Match what the project already uses. Never introduce a new library when the plan doesn't call for it.

Limitations

• Requires a complete plan: Cannot execute without universal-planner output

• Sequential execution: Processes one sprint at a time, in order

• No planning modifications: Does not restructure or improve the plan — only executes it

• Discovery is read-only: CONVENTIONS.md is consumed, not created — that is the planner's job

• External blockers: Cannot resolve dependencies on external teams, services, or decisions — logs them and moves on

• Single agent: Executes all tasks itself — does not delegate to specialized sub-agents

Version History

Version Date Changes

1.0 2026-02-04 Initial release — companion executor for universal-planner