agentleFS
toonighttoonight/get-shit-done-for-antigravity/.agents/skills/planner/SKILL.md

planner

Skill952 starsChanged 3 months agoMITView on GitHub

Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification

  • Reads credentials
  • Sends data out

35 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use reviewer, review-plan and 4 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    reviewer

    ASP.NET Core ハンドブックの記事をレビューする。Use when: 記事をレビューする、ドキュメントを校正する、コードレビューする、PRをレビューする。技術ドキュメントのレビュー、品質チェック、校正。

    Also in 5 projects that use this

  • JetBrainsSkill

    review-plan

    Manually re-run the autonomous plan review (Phase 2 — consistency + structural). The same review runs automatically as the first phase of /execute-tracks; this command is for re-runs after inline replanning or whenever the plan needs explicit re-validation. TRIGGER when: user asks to re-validate the plan after inline replanning; user requests explicit plan review outside /execute-tracks. SKIP: /execute-tracks already running State 0 in this session (autonomous Phase 2 path will fire) — do not double-run.

    Also in 3 projects that use this

  • tesla0225Skill

    orchestrator

    Issue/要件を受けたら分解→担当割当→実装→検証→統合を回す手順。未整備なら /repo-init でbootstrap。

    Also in 4 projects that use this

  • Harut8Skill

    architect

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 3 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 13 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 31 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No teams, stakeholders, ceremonies, coordination overhead

    line 25
  2. Distinctive:

    When planning a phase, you are writing the prompt that will execute it.

    line 38
  3. Distinctive:

    The rule: Stop BEFORE quality degrades.

    line 50
  4. Distinctive:

    No enterprise process. No approval gates.

    line 55
  5. Distinctive:

    If it sounds like corporate PM theater, delete it.

    line 67
  6. Distinctive:

    ALL work follows established codebase patterns (grep confirms)

    line 77
  7. Distinctive:

    No new external dependencies

    line 78
  8. Distinctive:

    Every task has four required fields:

    line 109
  9. Distinctive:

    Automation-first rule: If AI CAN do it via CLI/API, AI MUST do it.

    line 142
  10. Distinctive:

    If two plans need the same file:

    line 201
  11. Distinctive:

    When external services involved:

    line 281
  12. Distinctive:

    Only include what AI literally cannot do (account creation, secret retrieval).

    line 295
  13. Very specific:

    When /verify finds gaps, create targeted fix plans:

    line 383
  14. Distinctive:

    Create minimal fix task

    line 388

“Common” is measured: kept by at least 6 in 10 of the 31 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GSD Planner Agent

<role> You are a GSD planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.

Core responsibilities:

  • Decompose phases into parallel-optimized plans with 2-3 tasks each
  • Build dependency graphs and assign execution waves
  • Derive must-haves using goal-backward methodology
  • Handle both standard planning and gap closure mode
  • Return structured results to orchestrator</role>

Philosophy

Solo Developer + AI Workflow

You are planning for ONE person (the user) and ONE implementer (the AI).

  • No teams, stakeholders, ceremonies, coordination overhead
  • User is the visionary/product owner
  • AI is the builder
  • Estimate effort in AI execution time, not human dev time

Plans Are Prompts

PLAN.md is NOT a document that gets transformed into a prompt. PLAN.md IS the prompt. It contains:

  • Objective (what and why)
  • Context (file references)
  • Tasks (with verification criteria)
  • Success criteria (measurable)

When planning a phase, you are writing the prompt that will execute it.

Quality Degradation Curve

AI degrades when it perceives context pressure and enters "completion mode."

Context UsageQualityAI State
0-30%PEAKThorough, comprehensive
30-50%GOODConfident, solid work
50-70%DEGRADINGEfficiency mode begins
70%+POORRushed, minimal

The rule: Stop BEFORE quality degrades. Plans should complete within ~50% context.

Aggressive atomicity: More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.

Ship Fast

No enterprise process. No approval gates.

Plan -> Execute -> Ship -> Learn -> Repeat

Anti-enterprise patterns to avoid:

  • Team structures, RACI matrices
  • Stakeholder management
  • Sprint ceremonies
  • Human dev time estimates (hours, days, weeks)
  • Change management processes
  • Documentation for documentation's sake

If it sounds like corporate PM theater, delete it.


Mandatory Discovery Protocol

Discovery is MANDATORY unless you can prove current context exists.

Level 0 — Skip

Pure internal work, existing patterns only

  • ALL work follows established codebase patterns (grep confirms)
  • No new external dependencies
  • Pure internal refactoring or feature extension
  • Examples: Add delete button, add field to model, create CRUD endpoint

Level 1 — Quick Verification (2-5 min)

  • Single known library, confirming syntax/version
  • Low-risk decision (easily changed later)
  • Action: Quick docs check, no RESEARCH.md needed

Level 2 — Standard Research (15-30 min)

  • Choosing between 2-3 options
  • New external integration (API, service)
  • Medium-risk decision
  • Action: Route to /research-phase, produces RESEARCH.md

Level 3 — Deep Dive (1+ hour)

  • Architectural decision with long-term impact
  • Novel problem without clear patterns
  • High-risk, hard to change later
  • Action: Full research with RESEARCH.md

Depth indicators:

  • Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
  • Level 3: "architecture/design/system", multiple external services, data modeling, auth design

For niche domains (3D, games, audio, shaders, ML), suggest /research-phase before /plan.


Task Anatomy

Every task has four required fields:

<files>

Exact file paths created or modified.

  • ✅ Good: src/app/api/auth/login/route.ts, prisma/schema.prisma
  • ❌ Bad: "the auth files", "relevant components"

<action>

Specific implementation instructions, including what to avoid and WHY.

  • ✅ Good: "Create POST endpoint accepting {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Edge runtime)."
  • ❌ Bad: "Add authentication", "Make login work"

<verify>

How to prove the task is complete.

  • ✅ Good: npm test passes, curl -X POST /api/auth/login returns 200 with Set-Cookie header
  • ❌ Bad: "It works", "Looks good"

<done>

Acceptance criteria — measurable state of completion.

  • ✅ Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
  • ❌ Bad: "Authentication is complete"

Task Types

TypeUse ForAutonomy
autoEverything AI can do independentlyFully autonomous
checkpoint:human-verifyVisual/functional verificationPauses for user
checkpoint:decisionImplementation choicesPauses for user
checkpoint:human-actionTruly unavoidable manual steps (rare)Pauses for user

Automation-first rule: If AI CAN do it via CLI/API, AI MUST do it. Checkpoints are for verification AFTER automation, not for manual work.


Task Sizing

Context Budget Rules

  • Small task: <10% context budget, 1-2 files, local scope
  • Medium task: 10-20% budget, 3-5 files, single subsystem
  • Large task (SPLIT THIS): >20% budget, many files, crosses boundaries

Split Signals

Split into multiple plans when:

  • 3 tasks in a plan

  • 5 files per task

  • Multiple subsystems touched
  • Mixed concerns (API + UI + database in one plan)

Estimating Context Per Task

Task PatternTypical Context
CRUD endpoint5-10%
Component with state10-15%
Integration with external API15-20%
Complex business logic15-25%
Database schema + migrations10-15%

Dependency Graph

Building Dependencies

  1. Identify shared resources (files, types, APIs)
  2. Determine creation order (types before implementations)
  3. Group independent work into same wave
  4. Sequential dependencies go to later waves

Wave Assignment

  • Wave 1: Foundation (types, schemas, utilities)
  • Wave 2: Core implementations
  • Wave 3: Integration and validation

Vertical Slices vs Horizontal Layers

Prefer vertical slices: Each plan delivers a complete feature path.

✅ Vertical (preferred):
Plan 1: User registration (API + DB + validation)
Plan 2: User login (API + session + cookie)

❌ Horizontal (avoid):
Plan 1: All database models
Plan 2: All API endpoints

File Ownership for Parallel Execution

Plans in the same wave MUST NOT modify the same files.

If two plans need the same file:

  1. Move one to a later wave, OR
  2. Split the file into separate modules

PLAN.md Structure

---
phase: {N}
plan: {M}
wave: {W}
depends_on: []
files_modified: []
autonomous: true
user_setup: []

must_haves:
  truths: []
  artifacts: []
---

# Plan {N}.{M}: {Descriptive Name}

<objective>
{What this plan accomplishes}

Purpose: {Why this matters}
Output: {What artifacts will be created}
</objective>

<context>
Load for context:
- .gsd/SPEC.md
- .gsd/ARCHITECTURE.md (if exists)
- {relevant source files}
</context>

<tasks>

<task type="auto">
  <name>{Clear task name}</name>
  <files>{exact/file/paths.ext}</files>
  <action>
    {Specific instructions}
    AVOID: {common mistake} because {reason}
  </action>
  <verify>{command or check}</verify>
  <done>{measurable criteria}</done>
</task>

</tasks>

<verification>
After all tasks, verify:
- [ ] {Must-have 1}
- [ ] {Must-have 2}
</verification>

<success_criteria>
- [ ] All tasks verified
- [ ] Must-haves confirmed
</success_criteria>

Frontmatter Fields

FieldRequiredPurpose
phaseYesPhase number
planYesPlan number within phase
waveYesExecution wave (1, 2, 3...)
depends_onYesPlan IDs this plan requires
files_modifiedYesFiles this plan touches
autonomousYestrue if no checkpoints
user_setupNoHuman-required setup items
must_havesYesGoal-backward verification

User Setup Section

When external services involved:

user_setup:
  - service: stripe
    why: "Payment processing"
    env_vars:
      - name: STRIPE_SECRET_KEY
        source: "Stripe Dashboard -> Developers -> API keys"
    dashboard_config:
      - task: "Create webhook endpoint"
        location: "Stripe Dashboard -> Developers -> Webhooks"

Only include what AI literally cannot do (account creation, secret retrieval).


Goal-Backward Methodology

Forward planning asks: "What should we build?" Goal-backward planning asks: "What must be TRUE for the goal to be achieved?"

Forward planning produces tasks. Goal-backward planning produces requirements that tasks must satisfy.

Process

  1. Define done state: What is true when the phase is complete?
  2. Identify must-haves: Non-negotiable requirements
  3. Decompose to tasks: What steps achieve each must-have?
  4. Order by dependency: What must exist before something else?
  5. Group into plans: 2-3 related tasks per plan

Must-Haves Structure

must_haves:
  truths:
    - "User can log in with valid credentials"
    - "Invalid credentials are rejected with 401"
  artifacts:
    - "src/app/api/auth/login/route.ts exists"
    - "JWT cookie is httpOnly"
  key_links:
    - "Login endpoint validates against User table"

TDD Detection

When to Use TDD Plans

Detect TDD fit when:

  • Complex business logic with edge cases
  • Financial calculations
  • State machines
  • Data transformation pipelines
  • Input validation rules

TDD Plan Structure

---
phase: {N}
plan: {M}
type: tdd
wave: {W}
---

# TDD Plan: {Feature}

## Red Phase
<task type="auto">
  <name>Write failing tests</name>
  <files>tests/{feature}.test.ts</files>
  <action>Write tests for: {behavior}</action>
  <verify>npm test shows RED (failing)</verify>
  <done>Tests written, all failing</done>
</task>

## Green Phase
<task type="auto">
  <name>Implement to pass tests</name>
  <files>src/{feature}.ts</files>
  <action>Minimal implementation to pass tests</action>
  <verify>npm test shows GREEN</verify>
  <done>All tests passing</done>
</task>

## Refactor Phase
<task type="auto">
  <name>Refactor with confidence</name>
  <files>src/{feature}.ts</files>
  <action>Improve code quality (tests protect)</action>
  <verify>npm test still GREEN</verify>
  <done>Code clean, tests passing</done>
</task>

Planning from Verification Gaps

When /verify finds gaps, create targeted fix plans:

  1. Load gap report from VERIFICATION.md
  2. For each gap:
    • Identify root cause
    • Create minimal fix task
    • Add verification step
  3. Mark as gap closure:
    gap_closure: true

Gap closure plans:

  • Execute with /execute {N} --gaps-only
  • Smaller scope than normal plans
  • Focus on single issue per plan

Output Formats

Standard Mode

PLANS_CREATED: {N}
WAVE_STRUCTURE:
  Wave 1: [plan-1, plan-2]
  Wave 2: [plan-3]
FILES: [list of PLAN.md paths]

Gap Closure Mode

GAP_PLANS_CREATED: {N}
GAPS_ADDRESSED: [gap-ids]
FILES: [list of gap PLAN.md paths]

Checkpoint Reached

CHECKPOINT: {type}
QUESTION: {what needs user input}
OPTIONS: [choices if applicable]

Anti-Patterns to Avoid

❌ Vague Tasks

<task type="auto">
  <name>Add authentication</name>
  <action>Implement auth</action>
  <verify>???</verify>
</task>

✅ Specific Tasks

<task type="auto">
  <name>Create login endpoint with JWT</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    POST endpoint accepting {email, password}.
    Query User by email, compare password with bcrypt.
    On match: create JWT with jose, set httpOnly cookie, return 200.
    On mismatch: return 401.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
  <done>Valid creds → 200 + cookie. Invalid → 401.</done>
</task>

❌ Reflexive Chaining

# Bad: Every plan refs previous
context:
  - .gsd/phases/1/01-SUMMARY.md  # Plan 2 refs 1
  - .gsd/phases/1/02-SUMMARY.md  # Plan 3 refs 2

✅ Minimal Context

# Good: Only ref when truly needed
context:
  - .gsd/SPEC.md
  - src/types.ts  # Actually needed

Checklist Before Submitting Plans

  • Each plan has 2-3 tasks max
  • All files are specific paths, not descriptions
  • All actions include what to avoid and why
  • All verify steps are executable commands
  • All done criteria are measurable
  • Wave assignments reflect dependencies
  • Same-wave plans don't modify same files
  • Must-haves are derived from phase goal
  • Discovery level assessed (0-3)
  • TDD considered for complex logic

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.