agentleFS
wxxb789wxxb789/hoa/skills/writing-plans/SKILL.md

writing-plans

Skill3 starsChanged 53 days agoMITView on GitHub

Write an implementation plan that an agent with zero context for the codebase can execute without guessing: exact file paths, complete code, test commands with expected output, and bite-sized tasks of 2–5 minutes each. Use before any multi-step feature, complex requirement breakdown, or hand-off to a task-per-subagent executor. Not for setting outcomes and ambition (that is goal definition) and not for exploring whether the work should happen at all.

188 other projects use a version of this, 106 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use chinese-code-review, chinese-commit-conventions and 10 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.
  • Leodorareluctant259Skill

    chinese-code-review

    中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈

    Also in 8 projects that use this

  • Leodorareluctant259Skill

    chinese-commit-conventions

    中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化

    Also in 8 projects that use this

  • ryanportfolioSkill

    addskill

    Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.

    Also in 6 projects that use this

  • ryanportfolioSkill

    apply-firmware

    Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.

    Also in 6 projects that use this

  • +2 more from Leodorareluctant259
  • +6 more from ryanportfolio

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 14 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 170 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste.

    line 24
  2. Very specific:

    Start from the spec, not from scratch: When spec-convergence produced a spec, the plan consumes it: implement its Scope, Acceptance and …

    line 45
  3. Distinctive:

    Every step is one action:

    line 61
  4. Distinctive:

    Every plan MUST start with:

    line 93
  5. Distinctive:

    Use the harness's search, read and shell capabilities to understand the project:

    line 170
  6. Distinctive:

    Read the entry point and the configuration that the feature will touch.

    line 174
  7. Distinctive:

    Create tasks in order:

    line 188
  8. Very specific:

    Write the plan wherever this project records plans — PLAN_DIR (default docs/plans), file name pattern PLAN_FILE_PATTERN (default …

    line 219
  9. Distinctive:

    If the plan is tracked somewhere else (an issue, a board card, a task file), record it there and treat that surface as authoritative — the …

    line 230
  10. Distinctive:

    Bad: Add "flexibility" for future requirements

    line 242
  11. Distinctive:

    Every task that produces code should include the full TDD cycle:

    line 263
  12. Distinctive:

    Run to verify failure

    line 266
  13. Distinctive:

    Run to verify pass

    line 268
  14. Distinctive:

    If the project has no test-first rule, still require a regression test at the seam the task touches.

    line 270
  15. Distinctive:

    Commit after every task:

    line 274
  16. Distinctive:

    After saving the plan, offer the execution approach:

    line 305
  17. Very specific:

    When executing, use the subagent-driven-development skill:

    line 310

“Common” is measured: kept by at least 6 in 10 of the 170 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

Writing Implementation Plans

Overview

Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well.

Core principle: A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.

Method adapted from the public superpowers planning flow (MIT); the plan-shape sections and hand-off are this port's.

When to Use

Always use before:

  • Implementing multi-step features
  • Breaking down complex requirements
  • Delegating to subagents via subagent-driven-development

Start from the spec, not from scratch. When spec-convergence produced a spec, the plan consumes it: implement its Scope, Acceptance and Testing seam; do not re-decide a settled boundary. If a task would need a decision the spec never made, stop and return to spec-convergence — widening the plan is how an unagreed boundary becomes code.

Don't skip when:

  • Feature seems simple (assumptions cause bugs)
  • You plan to implement it yourself (future you needs guidance)
  • Working alone (documentation matters)

Bite-Sized Task Granularity

Each task = 2–5 minutes of focused work by default (PLAN_TASK_MINUTES_MIN, PLAN_TASK_MINUTES_MAX).

Every step is one action:

  • "Write the failing test" — step
  • "Run it to make sure it fails" — step
  • "Implement the minimal code to make the test pass" — step
  • "Run the tests and make sure they pass" — step
  • "Commit" — step

Too big:

### Task 1: Build authentication system
[50 lines of code across 5 files]

Right size:

### Task 1: Create User model with email field
[10 lines, 1 file]

### Task 2: Add password hash field to User
[8 lines, 1 file]

### Task 3: Create password hashing utility
[15 lines, 1 file]

Plan Document Structure

Header (Required)

Every plan MUST start with:

# [Feature Name] Implementation Plan

> **For the executing agent:** implement this plan task by task using the project's
> task-per-subagent method, if it has one.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

Each task follows this format:

### Task N: [Descriptive Name]

**Objective:** What this task accomplishes (one sentence)

**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`

**Step 1: Write failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify failure**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"

**Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

**Step 4: Run test to verify pass**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

Writing Process

Step 1: Understand Requirements

Read and understand:

  • Feature requirements
  • Design documents or user description
  • Acceptance criteria
  • Constraints

Step 2: Explore the Codebase

Use the harness's search, read and shell capabilities to understand the project:

  • List the project's source and test layout, and find the file that owns the area you will change.
  • Find a similar, already-working feature and read its implementation and tests completely.
  • Read the entry point and the configuration that the feature will touch.
  • Record the exact test/build commands from the project's own instructions, not from memory.

Step 3: Design Approach

Decide:

  • Architecture pattern
  • File organization
  • Dependencies needed
  • Testing strategy

Step 4: Write Tasks

Create tasks in order:

  1. Setup/infrastructure
  2. Core functionality (TDD for each)
  3. Edge cases
  4. Integration
  5. Cleanup/documentation

Step 5: Add Complete Details

For each task, include:

  • Exact file paths (not "the config file" but src/config/settings.py)
  • Complete code examples (not "add validation" but the actual code)
  • Exact commands with expected output
  • Verification steps that prove the task works

Step 6: Review the Plan

Check:

  • Tasks are sequential and logical
  • Each task is bite-sized (2–5 min by default)
  • File paths are exact
  • Code examples are complete (copy-pasteable)
  • Commands are exact with expected output
  • No missing context
  • DRY, YAGNI, TDD principles applied

Step 7: Save the Plan

Write the plan wherever this project records plans — PLAN_DIR (default docs/plans), file name pattern PLAN_FILE_PATTERN (default YYYY-MM-DD-<feature>.md) — then commit it with the project's commit convention:

mkdir -p "${PLAN_DIR:-docs/plans}"
# save as "${PLAN_DIR:-docs/plans}/$(date +%Y-%m-%d)-<feature>.md"
git add "${PLAN_DIR:-docs/plans}/"
git commit -m "docs: add implementation plan for <feature>"

If the plan is tracked somewhere else (an issue, a board card, a task file), record it there and treat that surface as authoritative — the plan does not exist twice.

Principles

DRY (Don't Repeat Yourself)

Bad: Copy-paste validation in 3 places Good: Extract validation function, use everywhere

YAGNI (You Aren't Gonna Need It)

Bad: Add "flexibility" for future requirements Good: Implement only what's needed now

# Bad — YAGNI violation
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Not needed yet!
        self.metadata = {}     # Not needed yet!

# Good — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (Test-Driven Development)

Every task that produces code should include the full TDD cycle:

  1. Write failing test
  2. Run to verify failure
  3. Write minimal code
  4. Run to verify pass

If the project has no test-first rule, still require a regression test at the seam the task touches.

Frequent Commits

Commit after every task:

git add [explicit paths]
git commit -m "type: description"

Common Mistakes

Vague Tasks

Bad: "Add authentication" Good: "Create User model with email and password_hash fields"

Incomplete Code

Bad: "Step 1: Add validation function" Good: "Step 1: Add validation function" followed by the complete function code

Missing Verification

Bad: "Step 3: Test it works" Good: "Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed"

Missing File Paths

Bad: "Create the model file" Good: "Create: src/models/user.py"

Execution Handoff

After saving the plan, offer the execution approach:

"Plan complete and saved. Ready to execute using subagent-driven-development — a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"

When executing, use the subagent-driven-development skill:

  • Fresh subagent per task with full context
  • Spec compliance review after each task
  • Code quality review after spec passes
  • Proceed only when both reviews approve

Configuration

KeyEnvDefault
plan_dirPLAN_DIRdocs/plans
plan_file_patternPLAN_FILE_PATTERNYYYY-MM-DD-<feature>.md
task_minutes_minPLAN_TASK_MINUTES_MIN2
task_minutes_maxPLAN_TASK_MINUTES_MAX5
test_commandPLAN_TEST_CMDthe project's documented test command
commit_stylePLAN_COMMIT_STYLEthe repo's own commit convention

Resolution order and the config-file path are defined once in skill-porting-and-publishing § Configuration; this skill does not restate them. A plan recorded outside the filesystem (issue, board, task file) is a project profile choice, not a second source of truth.

Remember

Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits

A good plan makes implementation obvious.

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.