agentleFS
LucfaceLucface/claude-skills/skills/executing-plans/SKILL.md

executing-plans

Skill1 starsChanged 3 days agoMITView on GitHub

Implements written plans through batched execution with review checkpoints. Stops on blockers and asks for clarification rather than guessing.

189 other projects use a version of this.

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

  • obraSkill

    diagnosing-superpowers

    Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.

    Also in 20 projects that use this

  • allanninalSkill

    algorand-vulnerability-scanner

    Scans Algorand smart contracts for 11 common vulnerabilities including rekeying attacks, unchecked transaction fees, missing field validations, and access control issues. Use when auditing Algorand projects (TEAL/PyTeal). (project, gitignored)

    Also in 4 projects that use this

  • allanninalSkill

    cairo-vulnerability-scanner

    Scans Cairo/StarkNet smart contracts for 6 critical vulnerabilities including felt252 arithmetic overflow, L1-L2 messaging issues, address conversion problems, and signature replay. Use when auditing StarkNet projects. (project, gitignored)

    Also in 4 projects that use this

  • farslabSkill

    aws-agentic-ai

    AWS Bedrock AgentCore comprehensive expert for deploying and managing AI agents at scale. Use when working with any AgentCore service including Gateway, Runtime, Memory, Identity, Code Interpreter, Browser, Observability, Agent Registry, or Evaluations. Covers agent deployment, MCP tool integration, credential management, agent discovery, governance workflows, and automated quality assessment. Essential when user mentions AgentCore, agent runtime, agent registry, agent evaluation, MCP gateway, deploy agent, register MCP server, discover agents, evaluate agent quality, agent credentials, or wants to build, deploy, catalog, or monitor AI agents on AWS.

    Also in 3 projects that use this

  • +3 more from Leodorareluctant259
  • +1 more from allanninal

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 13 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 177 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Default batch size: 3 tasks

    line 26
  2. Distinctive:

    Only when ALL criteria pass → commit

    line 34
  3. Distinctive:

    Every task MUST have verifiable success criteria before execution starts.

    line 39
  4. Distinctive:

    After completing a batch:

    line 72
  5. Distinctive:

    Do not proceed to next batch until:

    line 92
  6. Distinctive:

    When all tasks done:

    line 99
  7. Distinctive:

    Critical: Ask for clarification rather than guessing.

    line 115
  8. Distinctive:

    If plan requires modification:

    line 151
  9. Distinctive:

    Before marking batch complete:

    line 166
  10. Distinctive:

    When a task fails after 2+ attempts, don't just mark it BLOCKED.

    line 180
  11. Very specific:

    When using ACCEPT_WITH_DEBT, append to the plan file or batch report:

    line 194
  12. Very specific:

    Integration: Before /ship, scan the plan file for open DEBT entries.

    line 213
  13. Distinctive:

    When a task succeeds via a non-obvious approach, record the pattern so parallel or downstream tasks can reuse it without rediscovery:

    line 217
  14. Distinctive:

    Before executing each task, classify it.

    line 238
  15. Distinctive:

    When in doubt, classify up, not down.

    line 246

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

Executing Implementation Plans

Systematic implementation of written plans through batched execution with review checkpoints.

Process

1. Load and Review

# Read the plan
cat docs/plans/YYYY-MM-DD-feature-name.md

Before starting:

  • Review the entire plan
  • Raise concerns about unclear or risky steps
  • Confirm understanding
  • Identify success criteria for each task (see Goal-Driven Execution below)

2. Execute in Batches (Goal-Driven)

Default batch size: 3 tasks

For each task:

  1. Mark as in-progress (TodoWrite)
  2. Define success criteria — what proves this task is done?
  3. Execute test-first (RED)
  4. Implement (GREEN)
  5. Loop: verify ALL success criteria are met
  6. Only when ALL criteria pass → commit
  7. Mark complete

Goal-Driven Execution

Every task MUST have verifiable success criteria before execution starts.

Template for each task:

## Task N: [description]
**Success criteria (ALL must pass):**
- [ ] `bun test [relevant test file]` passes
- [ ] `bun run typecheck` clean
- [ ] [Specific behavioral verification]
- [ ] No `any` types in new code

**Loop until ALL criteria are met.**

The loop:

while (not all criteria met) {
  attempt implementation/fix
  run ALL verification commands
  check each criterion
  if (all pass) → done
  if (3+ failed attempts on same criterion) → STOP, report blocker
}

Key difference from step-based execution:

  • Step-based: "Do A, then B, then C" → done when steps complete
  • Goal-driven: "Achieve state X" → done when state X is verified true

This prevents the "I did all the steps but it still doesn't work" problem.

3. Report After Each Batch

After completing a batch:

## Batch Complete

### Completed:
- Task 1: [status]
- Task 2: [status]
- Task 3: [status]

### Verification:
All tests passing: YES/NO

### Issues Encountered:
[Any problems or deviations]

Ready for feedback.

4. Wait for Review

Do not proceed to next batch until:

  • User acknowledges completion
  • User provides feedback
  • User approves continuation

5. Complete

When all tasks done:

  • Use finishing-development-branch skill
  • Merge or create PR

Stop Conditions

STOP IMMEDIATELY when encountering:

BlockerAction
Missing dependenciesReport and wait
Test failuresReport with error details
Plan gapsAsk for clarification
Unclear instructionsAsk before guessing
Repeated verification failuresStop after 3 attempts

Critical: Ask for clarification rather than guessing.

Batch Execution Example

## Starting Batch 1 (Tasks 1-3)

### Task 1: Add user validation
[in_progress]

Writing test...
```typescript
test('validates user email', () => {
  expect(() => validateUser({ email: 'invalid' })).toThrow();
});

Running test... ❌ FAIL (expected - no implementation)

Implementing... [code]

Running test... ✅ PASS

Committing... ✅ Committed: abc123

[completed]

Task 2: ...


## Handling Deviations

If plan requires modification:

1. **Stop execution**
2. **Document the issue**

Plan deviation detected:

  • Task 4 assumes X exists
  • Actually, Y is the pattern here
  • Proposed adjustment: [change]
3. **Wait for approval**
4. **Continue with adjusted plan**

## Quality Checks

Before marking batch complete:
- All tests pass
- No linting errors
- No type errors
- Code matches plan intent

```bash
bun test
bun run lint
bun run typecheck

Partial Failure & Typed Debt

When a task fails after 2+ attempts, don't just mark it BLOCKED. Classify the failure and record typed debt.

Failure Classification

Pick exactly one before stopping or retrying:

  • RETRY_MODIFIED — Relax acceptance criteria and retry. Record what was relaxed as debt.
  • RETRY_APPROACH — Same success criteria, completely different implementation strategy. Never retry the exact same approach.
  • SPLIT — Decompose the failing task into 2-4 smaller sub-tasks. Each must be independently verifiable. Depth Limit: Max 2 levels of decomposition. If a sub-task also needs splitting, ESCALATE_TO_REPLAN instead.
  • ACCEPT_WITH_DEBT — Close the task but record a structured debt entry (see format below). Use when the gap is non-blocking and the cost of perfection exceeds the risk. Debt Accumulation Threshold: If a plan accumulates 3+ debts touching the same subsystem, pause and consider ESCALATE_TO_REPLAN. Localized debt compounds into systemic risk.
  • ESCALATE_TO_REPLAN — The plan itself needs restructuring. Stop execution, surface findings, wait for approval before continuing.

Debt Record Format

When using ACCEPT_WITH_DEBT, append to the plan file or batch report:

DEBT: {task name/number} — {severity: low | medium | high | critical}
Missing: {what specifically was not completed}
Impact: {which downstream tasks or systems are affected}
Accepted because: {justification — time, risk, scope, dependency}
Resolution: {what would fully fix it, estimated effort}

Example:

DEBT: Task 3 (Auth middleware) — medium
Missing: Rate limiting not implemented
Impact: Task 7 (API endpoints) will need to add it before ship
Accepted because: Rate limiting is out of scope for this plan; auth logic itself is correct
Resolution: Add express-rate-limit in a follow-up task, ~30 min

Integration: Before /ship, scan the plan file for open DEBT entries. Surface them in the pre-merge review. Debts that should persist across sessions should be promoted to the Runbook (<your-runbook, e.g. docs/RUNBOOK.md>).

Cross-Task Convention Capture

When a task succeeds via a non-obvious approach, record the pattern so parallel or downstream tasks can reuse it without rediscovery:

CONVENTION: {pattern name}
Applied in: {task name/number}
Pattern: {what worked — be specific enough to copy}
Reuse when: {trigger condition}

Example:

CONVENTION: Drizzle insert with conflict ignore
Applied in: Task 2 (seed baseline data)
Pattern: db.insert(table).values(rows).onConflictDoNothing()
Reuse when: Any seeding or idempotent insert operation

Conventions accumulate in the batch report and are referenced at the start of each new batch.

Hardness-Aware Routing

Before executing each task, classify it. This prevents wasting review cycles on trivial changes and ensures complex ones get proper scrutiny.

HardnessCriteriaExecution mode
Simple< 5 min, single file, no architecture impactExecute directly, no review gate
Medium5–30 min, multi-file, localized changeExecute with self-review before marking done
Complex30+ min, architecture change, cross-system impactExecute with full review checkpoint — pause for user approval

When in doubt, classify up, not down. A wrong complexity estimate on the low side is how "quick fixes" become 2-hour detours.


Integration Points

SkillWhen
test-driven-developmentEach task implementation
verification-before-completionAfter each verification step
finishing-development-branchAfter all tasks complete

Guardrails

See agent-guardrails.md for time budgets, retry limits, and fast verification patterns.

Related Context

  • agent-guardrails.md - Time budgets, retry limits
  • validation-oracles.md - Baseline validation
  • output-markers.md - Standard output format

Source

Adapted from https://github.com/obra/superpowers (MIT, Copyright (c) 2025 Jesse Vincent). Changed for this repo by Lucas Cooper-Bey in 2026: wording rewritten, and goal-driven success criteria added.

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.