skill-planner
- Repo stars 435
- Author updated Live
- Author repo nvim
- Domain
- Engineering
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @benbrastmckie · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-planner
description: Create phased implementation plans from research findings. Invoke when a task needs an implement…
category: engineering
runtime: no special runtime
---
# skill-planner output preview
## PART A: Task fit
- Use case: Create phased implementation plans from research findings. Invoke when a task needs an implementation plan. Thin wrapper that delegates plan creation to planner-agent subagent. runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Context References / Execution Flow / Stage 1: Input Validation” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Create phased implementation plans from research findings. Invoke when a task needs an implementation plan. Thin wrapper that delegates plan creation to planner-agent subagent. runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Context References / Execution Flow / Stage 1: Input Validation” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Context References / Execution Flow / Stage 1: Input Validation”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-planner
description: Create phased implementation plans from research findings. Invoke when a task needs an implement…
category: engineering
source: benbrastmckie/nvim
---
# skill-planner
## When to use
- Create phased implementation plans from research findings. Invoke when a task needs an implementation plan. Thin wrapp…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Context References / Execution Flow / Stage 1: Input Validation” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-planner" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Context References / Execution Flow / Stage 1: Input Validation
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Planner Skill
Thin wrapper that delegates plan creation to planner-agent subagent.
IMPORTANT: Skill-internal postflight pattern — this skill handles all postflight operations after the subagent returns, eliminating the "continue" prompt issue.
Context References
Reference (do not load eagerly):
.claude/context/formats/return-metadata-file.md- Metadata file schema.claude/context/patterns/postflight-control.md- Marker file protocol.claude/context/patterns/jq-escaping-workarounds.md- jq escaping patterns (Issue #1132)
Execution Flow
Stage 1: Input Validation
source .claude/scripts/skill-base.sh
skill_validate_input "$task_number"
# Exports: TASK_TYPE, TASK_STATUS, PROJECT_NAME, DESCRIPTION, PADDED_NUM, TASK_DIR
Stage 2: Preflight Status Update
skill_preflight_update "$task_number" "plan" "$session_id"
If the script exits non-zero, stop execution. Exit code 2 = state.json failure; exit code 3 = TODO.md failure.
Stage 3: Create Postflight Marker
skill_create_postflight_marker "$PADDED_NUM" "$PROJECT_NAME" "$session_id" "skill-planner" "plan"
Stage 3a: Calculate Artifact Number
Planner uses "prev" mode — shares the same round as the preceding research.
skill_read_artifact_number "$task_number" "$PADDED_NUM" "$PROJECT_NAME" "plans/" "prev"
# Exports: ARTIFACT_NUMBER, ARTIFACT_PADDED
Note: Plan does NOT increment next_artifact_number. Only research advances the sequence.
Stage 4a: Memory Retrieval (Auto)
Skip if clean_flag is true.
memory_context=""
if [ "$clean_flag" != "true" ]; then
memory_context=$(bash .claude/scripts/memory-retrieve.sh "$DESCRIPTION" "$TASK_TYPE" "" 2>/dev/null) || memory_context=""
fi
Stage 4: Prepare Delegation Context
Extract orchestrator_mode early:
orchestrator_mode=$(echo "$delegation_context" | jq -r '.orchestrator_mode // "false"' 2>/dev/null || echo "false")
Prior plan discovery: Find the latest existing plan file (if any) to pass as reference context.
prior_plan_path=$(ls -1 "specs/${PADDED_NUM}_${PROJECT_NAME}/plans/"*.md 2>/dev/null | sort -V | tail -1)
# prior_plan_path will be empty if no prior plans exist
Prepare delegation context for the subagent:
{
"session_id": "sess_{timestamp}_{random}",
"delegation_depth": 1,
"delegation_path": ["orchestrator", "plan", "skill-planner"],
"timeout": 1800,
"task_context": {
"task_number": N,
"task_name": "{PROJECT_NAME}",
"description": "{DESCRIPTION}",
"task_type": "{TASK_TYPE}"
},
"artifact_number": "{ARTIFACT_PADDED}",
"effort_flag": "{effort_flag or null}",
"model_flag": "{model_flag or null}",
"orchestrator_mode": false,
"roadmap_flag": "{roadmap_flag or false}",
"research_path": "{path to research report if exists}",
"prior_plan_path": "{prior_plan_path or empty}",
"roadmap_path": "specs/ROADMAP.md",
"metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}
Model/Effort Flags: Pass model_flag as model parameter on the Agent tool if set. Include effort_flag as prompt context for reasoning depth if set.
Stage 4b: Read and Inject Format Specification
format_content=$(cat .claude/context/formats/plan-format.md)
Stage 5: Invoke Subagent
CRITICAL: Use the Agent tool (subagent_type: "planner-agent").
Build the prompt with these blocks in order:
- Delegation context JSON
<artifact-format-specification>block with{format_content}(Plan Format Requirements){memory_context}block (only if non-empty; already wrapped in<memory-context>tags)- Task-specific instructions
DO NOT use Skill(planner-agent) or Agent(subagent_type: "Plan") — Plan is a built-in read-only subagent that CANNOT write files.
Stage 5b: Self-Execution Fallback
If you performed work WITHOUT using the Agent tool, write .return-meta.json with status "planned" before proceeding to postflight. If you used the Agent tool, skip this stage.
Postflight (ALWAYS EXECUTE)
Stage 6: Read Metadata File
source .claude/scripts/skill-base.sh
skill_read_metadata "$PADDED_NUM" "$PROJECT_NAME"
# Exports: SUBAGENT_STATUS, ARTIFACT_PATH, ARTIFACT_TYPE, ARTIFACT_SUMMARY, MEMORY_CANDIDATES
Stage 6a: Validate Artifact Content
skill_validate_artifact "$SUBAGENT_STATUS" "$ARTIFACT_PATH" "plan"
Stage 7: Update Task Status (Postflight)
# Step 1: Update status
skill_postflight_update "$task_number" "plan" "$session_id" "$SUBAGENT_STATUS"
# Step 2: Write orchestrator handoff (only if orchestrator_mode=true)
skill_write_orchestrator_handoff "$orchestrator_mode" "$PADDED_NUM" "$PROJECT_NAME" \
"plan" "$SUBAGENT_STATUS" "$ARTIFACT_SUMMARY" "$ARTIFACT_PATH" "$ARTIFACT_TYPE" "implement"
On partial/failed: skill_postflight_update skips non-success statuses — status remains "planning" for resume.
Stage 8: Link Artifacts
skill_link_artifacts "$task_number" "$ARTIFACT_PATH" "$ARTIFACT_TYPE" "$ARTIFACT_SUMMARY" '**Plan**' '**Description**'
Stage 9: Git Commit
git add -A
git commit -m "task ${task_number}: create implementation plan
Session: ${session_id}"
Stage 10: Cleanup
skill_cleanup "$PADDED_NUM" "$PROJECT_NAME"
Stage 11: Return Brief Summary
Return a brief text summary (NOT JSON):
Plan created for task {N}:
- {phase_count} phases defined, {estimated_hours} hours estimated
- Created plan at specs/{NNN}_{SLUG}/plans/MM_{short-slug}.md
- Status updated to [PLANNED]
- Changes committed
Error Handling
- Task not found or terminal state: Exit immediately with error
- Metadata missing: Keep status "planning", do not cleanup marker, report error
- Git commit failure: Non-blocking (log and continue)
- jq parse failure (Issue #1132): Log to errors.json, retry with two-step pattern (already in skill_link_artifacts)
- Subagent timeout: Return partial; keep status "planning" for resume
MUST NOT (Postflight Boundary)
After the agent returns, MUST NOT: edit source files, run build/test, use research tools, analyze task requirements, or write plan files.
Postflight is LIMITED TO: reading metadata, calling update-task-status.sh, linking artifacts, git commit, cleanup.
Reference: @.claude/context/standards/postflight-tool-restrictions.md
Decide Fit First
Design Intent
How To Use It
Boundaries And Review