ReddRadar
Agent skill
plan-phase
Generate execution-ready implementation plans from research docs - planning ONLY, no fixing or verifying. North Star is whether a JR developer can execute the plan with zero additional context.
Install this agent skill to your Project
npx add-skill https://github.com/alchemiststudiosDOTai/harness-engineering/tree/main/skills/plan-phase
SKILL.md
Plan Phase
Overview
Generate execution-ready, coding-only implementation plans from research documents. The goal is to produce plans that any JR developer can execute immediately with zero ambiguity.
North Star Rule
If a JR developer picked this up, could they start coding immediately?
If the answer is "no" or "they'd need to ask clarifying questions," the plan is incomplete.
When to Use
- User asks to "create a plan from research"
- User references a research doc in
.artifacts/research/ - User wants "implementation steps" from findings
- User asks to "break down into tasks" a researched topic
What This Skill Does NOT Do
| ❌ DON'T | ✅ DO INSTEAD |
|---|---|
| Fix code issues | Document them as tasks to fix |
| Verify implementations | Plan verification steps |
| Run tests | Plan what tests to write |
| Deploy anything | Plan deployment as a task |
| Make code changes | Document exactly what changes to make |
Planning Workflow
1. Read Research Doc
Read from: .artifacts/research/<topic>.md
Extract: scope, constraints, target files, unresolved questions, proposed solutions
2. Verify Git Freshness
# Capture current state
git rev-parse HEAD # Commit SHA
git status --short # Working tree status
3. Generate Plan File
Save as: .artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>.md
4. Plan Structure
---
title: "<topic> implementation plan"
link: "<topic>-plan"
type: implementation_plan
ontological_relations:
- relates_to: [[<research-link>]]
tags: [plan, <topic>, coding]
uuid: "<uuid>"
created_at: "<ISO-8601 timestamp>"
parent_research: ".artifacts/research/<file>.md"
git_commit_at_plan: "<short_sha>"
---
## Goal
- ONE singular coding-focused outcome
- Explicitly state what is OUT of scope (ops, deploy, excessive testing)
## Scope & Assumptions
- IN scope: (technical items only)
- OUT of scope: (what we're NOT doing)
- Assumptions: (frameworks, environments, libraries)
## Deliverables
- Source code modules, functions, or APIs
- Documentation limited to developer-level notes (not user docs)
## Readiness
- Preconditions: repos, libs, data schemas, sample inputs
- What must exist before starting
## Milestones
- M1: Skeleton & architecture setup
- M2: Core logic & data flow
- M3: Feature completion & refinement
- M4: Basic test(s) & integration hooks
## Work Breakdown (Tasks)
For EACH task, specify:
- **Task ID**: T001, T002, etc.
- **Summary**: What to do (present tense, actionable)
- **Owner**: who does it
- **Estimate**: time/complexity
- **Dependencies**: other task IDs
- **Target milestone**: M1-M4
- **Acceptance test**: Exactly ONE test that proves it works
- **Files/modules touched**: List exact paths
## Risks & Mitigations
Keep technical:
- Library stability issues
- API version drift
- Schema mismatch risks
- Breaking changes in dependencies
## Test Strategy
At most ONE new test per task, only for validating main coding work.
Focus on proving correctness, not coverage.
## References
- Research doc sections
- Key code references (file:line format)
## Final Gate
- **Output summary**: plan path, milestone count, tasks ready
- **Next step**: proceed to execute-phase with the generated plan path
Task Writing Guidelines
✅ Good Task
T003: Add user authentication middleware
- Create src/middleware/auth.ts with verifyToken() function
- Import in src/app.ts and apply to /api/* routes
- Acceptance: curl /api/users returns 401 without header, 200 with valid token
- Files: src/middleware/auth.ts, src/app.ts
- Milestone: M2
❌ Bad Task
T003: Fix auth
- Handle the auth stuff properly
- Make sure it works
Rules for Tasks
- Present tense, actionable: "Add function X" not "Function X should be added"
- File paths explicit: No "find the right place to put it"
- One acceptance test per task: Single proof of correctness
- No hand-waving: "Implement caching" → "Add Redis caching to src/cache.ts with get/set methods"
- Depend on tasks, not people: "Depends on T001" not "Wait for backend team"
Git Freshness Check
Always capture and include:
COMMIT_SHA=$(git rev-parse --short HEAD)
STATUS=$(git status --short)
If research doc mentions specific commits/branches and they've changed:
- Mark affected tasks for re-verification
- Note the discrepancy in plan frontmatter
Issue Opening (When Available)
If planning reveals blockers or prerequisites that need tracking:
- Check for Gitea/GitHub availability
- Open issues ONLY for:
- External dependencies
- Prerequisites that aren't in scope
- Decisions needed before execution
- Link issue IDs to relevant tasks
Validation Questions
Before finalizing, ask:
- Ambiguity check: Could a JR developer understand every task without questions?
- Completeness: Are all prerequisites and dependencies listed?
- Executability: Does each task specify exact files and acceptance criteria?
- Scope creep: Is ops/deploy work leaking into the plan?
Output Format
After plan generation, output:
✓ Plan written to: .artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>.md
✓ Milestones: 4
✓ Tasks: 12
✓ Git state: <short_sha>
Next step: Execute phase using the generated plan path
Examples
Example Plan Entry
## Task T004: Add rate limiting to API endpoints
**Summary**: Implement token-bucket rate limiting for public API endpoints
**Files**:
- src/middleware/rateLimit.ts (new)
- src/app.ts (modify)
**Changes**:
1. Create src/middleware/rateLimit.ts with TokenBucket class
- Constructor takes capacity and refillRate
- consume(tokens) method returns true if allowed
2. Add rateLimit instance to src/app.ts
3. Apply to /api/public/* routes only
**Acceptance Test**:
- Send 100 requests in 1 second to /api/public/data
- First 60 succeed (200)
- Next 40 fail (429)
- Headers include X-RateLimit-Remaining
**Dependencies**: T001 (Express app setup)
**Milestone**: M2
**Estimate**: 2 hours
Subagent Usage (Sparingly)
Only spawn subagents if:
- Research doc is large (>500 lines)
- Need to map tasks to existing codebase structure
- Need parallel analysis of multiple subsystems
Typical subagents:
codebase-analyzer: Find where new code fitscontext-synthesis: Extract structured tasks from prose research
Default: Don't use subagents. Trust the research doc.
Handoff
After writing the plan document to .artifacts/plan/, proceed to execute-phase if the next step is the Execute phase.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
alchemiststudiosDOTai/harness-engineering
differential-session-runner
Run or continue a differential debugging session between two implementations, traces, captures, or outputs. Record artifact identity, exact commands, first mismatch progression, findings, validation, and next probe in a durable session log.
alchemiststudiosDOTai/harness-engineering
agents-md-mapper
This skill should be used when creating, refreshing, or validating a repository `AGENTS.md` so it stays concise, current, and grounded in repository evidence. Use when `AGENTS.md` is missing or stale, after refactors or tooling changes, when new docs become the system of record, or when adding lightweight drift checks.
alchemiststudiosDOTai/harness-engineering
ast-grep-setup
Set up ast-grep for a codebase with common TypeScript rules for detecting anti-patterns, enforcing best practices, and preventing bugs. Creates sgconfig.yml, rule files, and rule tests. Use when adding structural linting, banning legacy patterns, or implementing ratchet gates.
alchemiststudiosDOTai/harness-engineering
research-phase
This skill should be used when mapping or researching a codebase to understand its structure, patterns, and architecture. Use when the user asks to "map the codebase", "research how X works", "find all Y patterns", or needs to understand code organization. Produces factual structural maps in .artifacts/research/—no suggestions, no recommendations, just what exists. Uses ast-grep for structural pattern matching.
alchemiststudiosDOTai/harness-engineering
execute-phase
Execute implementation plans from .artifacts/plan/. Focus on EXECUTING ONLY - no planning, no fixes outside plan scope. Uses gated checks, atomic commits, and maintains a single execution log in .artifacts/execute/. Use when the user says "execute this plan" or provides a plan path.
alchemiststudiosDOTai/harness-engineering
qa-from-execute
Perform quality assurance on code changes after the research-phase -> plan-phase -> execute-phase workflow. STRICTLY QA only—no coding, no fixes, no source-code changes. Focus on changed areas only, emphasizing control/data flow correctness.
Didn't find tool you were looking for?