marsai-writing-plans

name	marsai:writing-plans
description	Creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps for engineers with zero codebase context.
trigger	- Design phase complete (brainstorming/PRD/TRD validated) - Need to create executable task breakdown - Creating work for other engineers or AI agents
skip_when	- Design not validated → use brainstorming first - Requirements still unclear → use marsai:pre-dev-prd-creation first - Already have a plan → use marsai:executing-plans
sequence	{"after":["brainstorming","marsai:pre-dev-trd-creation"],"before":["marsai:executing-plans","marsai:subagent-driven-development"]}
related	{"similar":["brainstorming"]}

Writing Plans

Overview

This skill dispatches a specialized agent to write comprehensive implementation plans for engineers with zero codebase context.

Announce at start: "I'm using the marsai:writing-plans skill to create the implementation plan."

Context: This should be run in a dedicated worktree (created by marsai:brainstorming skill).

The Process

Step 1: Dispatch Write-Plan Agent

Dispatch via Task(subagent_type: "marsai:write-plan") with:

• Instructions to create bite-sized tasks (2-5 min each)
• Include exact file paths, complete code, verification steps
• Save to docs/plans/YYYY-MM-DD-<feature-name>.md

Step 2: Ask User About Execution

Ask via AskUserQuestion: "Execute now?" Options:

1. Execute now → marsai:subagent-driven-development
2. Parallel session → user opens new session with marsai:executing-plans
3. Save for later → report location and end

Why Use an Agent?

Context preservation (reading many files keeps supervisor clean) | Model power (comprehensive planning) | Separation of concerns (supervisor orchestrates, agent plans)

What the Agent Does

Explore codebase → identify files → break into bite-sized tasks (2-5 min) → write complete code → include exact commands → add review checkpoints → verify Zero-Context Test → save to docs/plans/YYYY-MM-DD-<feature>.md → report back

Requirements for Plans

Every plan: Header (goal, architecture, tech stack) | Verification commands with expected output | Exact file paths (never "somewhere in src") | Complete code (never "add validation here") | Bite-sized steps with verification | Failure recovery | Review checkpoints | Zero-Context Test | Recommended agents per task

Multi-Module Task Requirements

If TopologyConfig exists (from pre-dev research.md frontmatter or user input):

Each task MUST include:

• Target: backend | frontend | shared
• Working Directory: Resolved path from topology configuration
• Agent: Recommended agent matching the target

Task Format with Target:

## Task 3: Create User Login API

**Target:** backend
**Working Directory:** packages/api
**Agent:** marsai:backend-engineer-typescript

**Files to Create/Modify:**
- `packages/api/src/handlers/auth.ts`
- `packages/api/src/services/auth-service.ts`

...rest of task...

Target Assignment Rules:

Target	When	Agent
backend	API endpoints, services, data layer, CLI	marsai:backend-engineer-typescript
frontend	UI components, pages, BFF routes	See Frontend Tasks (api_pattern aware)
shared	CI/CD, configs, docs, cross-module	marsai:devops-engineer or marsai:general-purpose

Working Directory Resolution:

Topology Structure	Backend Path	Frontend Path
single-repo	.	.
monorepo	topology.modules.backend.path	topology.modules.frontend.path
multi-repo	topology.modules.backend.path (absolute)	topology.modules.frontend.path (absolute)

Agent Selection

Backend Tasks

Task Type	Agent
TypeScript backend API/services	marsai:backend-engineer-typescript

Frontend Tasks (api_pattern aware)

Read api_pattern from topology configuration to determine correct agent:

API Pattern	Task Type	Agent
direct	UI components, pages, forms	marsai:frontend-engineer
direct	Server Actions, data fetching	marsai:frontend-engineer
direct	Server Components with data loading	marsai:frontend-engineer
bff	API routes (/api/*)	marsai:frontend-bff-engineer-typescript
bff	Data aggregation, transformation	marsai:frontend-bff-engineer-typescript
bff	External service integration	marsai:frontend-bff-engineer-typescript
bff	UI components, pages, forms	marsai:frontend-engineer
other	Depends on pattern	Ask user or use marsai:frontend-engineer default

Decision Logic for Frontend Tasks

def get_frontend_agent(task, topology):
    api_pattern = topology.get('api_pattern', 'direct')

    if api_pattern == 'direct':
        return 'marsai:frontend-engineer'

    if api_pattern == 'bff':
        if is_bff_task(task):  # API routes, aggregation, transformation
            return 'marsai:frontend-bff-engineer-typescript'
        else:  # UI components, pages
            return 'marsai:frontend-engineer'

    return 'marsai:frontend-engineer'  # Default for 'other'

def is_bff_task(task):
    bff_indicators = [
        'API route', 'api route', '/api/',
        'aggregat', 'transform', 'BFF',
        'external service', 'backend service',
        'data layer', 'HTTP client'
    ]
    return any(ind in task.description for ind in bff_indicators)

Infrastructure and Other Tasks

Task Type	Agent
Infra/CI/CD	marsai:devops-engineer
Testing	marsai:qa-analyst
Reliability	marsai:sre
Fallback	marsai:general-purpose

Task Format with api_pattern

When TopologyConfig includes api_pattern, include it in task metadata:

## Task 3: Aggregate Dashboard Data

**Target:** frontend
**Working Directory:** packages/web
**API Pattern:** bff
**Agent:** marsai:frontend-bff-engineer-typescript

**Files to Create/Modify:**
- `packages/web/app/api/dashboard/route.ts`
- `packages/web/lib/services/dashboard-aggregator.ts`

...rest of task...

Execution Options Reference

Option	Description
Execute now	Fresh subagent per task, code review between tasks → marsai:subagent-driven-development
Parallel session	User opens new session, batch execution with human review → marsai:executing-plans
Save for later	Plan at docs/plans/YYYY-MM-DD-<feature>.md, manual review before execution

Required Patterns

This skill uses these universal patterns:

• State Tracking: See skills/shared-patterns/state-tracking.md
• Failure Recovery: See skills/shared-patterns/failure-recovery.md
• Exit Criteria: See skills/shared-patterns/exit-criteria.md
• TodoWrite: See skills/shared-patterns/todowrite-integration.md

Apply ALL patterns when using this skill.

Blocker Criteria

STOP and report if:

Decision Type	Blocker Condition	Required Action
Design Validation	Design phase not complete (brainstorming/PRD/TRD not validated)	STOP and report
Zero-Context Test	Plan contains vague instructions ("add validation here")	STOP and report
Agent Assignment	Tasks missing recommended agent specification	STOP and report

Cannot Be Overridden

The following requirements CANNOT be waived:

• Design phase MUST be complete before creating implementation plan
• All tasks MUST include exact file paths, never "somewhere in src"
• All tasks MUST include complete code examples, never placeholders
• Each task MUST specify recommended agent

Severity Calibration

Severity	Condition	Required Action
CRITICAL	Plan created without validated design	MUST complete design phase first
CRITICAL	Tasks contain placeholder code ("add logic here")	MUST write complete code examples
HIGH	Missing exact file paths in tasks	MUST specify complete paths
MEDIUM	Missing verification commands in tasks	Should add expected output verification
LOW	Missing review checkpoints between tasks	Fix in next iteration

Pressure Resistance

User Says	Your Response
"Skip design validation, we know what to build"	"CANNOT skip design validation. Plans without validated design lead to rework. Design phase MUST be complete first."
"Add the code later, just outline the tasks"	"CANNOT use placeholder code. Zero-Context Test requires complete code so engineers can execute without codebase knowledge."
"Approximate file paths are fine"	"CANNOT use vague paths. Tasks MUST include exact file paths - never 'somewhere in src'."
"Skip Zero-Context Test, we're in a hurry"	"CANNOT skip validation. Zero-Context Test catches issues before they become implementation blockers."

Anti-Rationalization Table

Rationalization	Why It's WRONG	Required Action
"Design is obvious, skip to planning"	Obvious ≠ validated. Unvalidated designs cause plan rework.	MUST complete design phase first
"Engineer will figure out the details"	Zero-Context Test: engineer has NO codebase context. Plan must be complete.	MUST include complete code and paths
"Validation is overkill for this plan"	Unvalidated plans fail Zero-Context Test during execution.	MUST verify plan completeness
"Agent assignment is flexible"	Wrong agent = wrong standards applied. Each task needs correct specialist.	MUST specify recommended agent
"Plan is good enough, skip review"	"Good enough" plans fail Zero-Context Test. Completeness must be verified.	MUST verify Zero-Context Test criteria