agentleFS
LucasDuysLucasDuys/forge/skills/planning/SKILL.md

planning

Skill56 starsChanged 8 months agoMITView on GitHub

Decompose approved specs into ordered task frontiers with dependency DAGs, token estimates, and repo tags

74 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use Problem-Solving Techniques, ads-management and 9 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.
  • truongtv22Skill

    Problem-Solving Techniques

    Apply systematic problem-solving techniques for complexity spirals (simplification cascades), innovation blocks (collision-zone thinking), recurring patterns (meta-pattern recognition), assumption constraints (inversion exercise), scale uncertainty (scale game), and dispatch when stuck. Techniques derived from Microsoft Amplifier project patterns adapted for immediate application.

    Also in 6 projects that use this

  • OpenAnalystIncSkill

    ads-management

    Activate for paid advertising campaigns on Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads. Includes ad copywriting, audience targeting, budget optimization, A/B testing, and ROAS tracking. Used by ads-specialist and campaign-manager agents.

    Also in 3 projects that use this

  • OpenAnalystIncSkill

    ai-artist

    Write and optimize prompts for AI-generated outcomes across text and image models. Use when crafting prompts for LLMs (Claude, GPT, Gemini), image generators (Midjourney, DALL-E, Stable Diffusion, Imagen, Flux), or video generators (Veo, Runway). Covers prompt structure, style keywords, negative prompts, chain-of-thought, few-shot examples, iterative refinement, and domain-specific patterns for marketing, code, and creative writing.

    Also in 3 projects that use this

  • mrgoonieSkill

    web-frameworks

    Build modern full-stack web applications with Next.js (App Router, Server Components, RSC, PPR, SSR, SSG, ISR), Turborepo (monorepo management, task pipelines, remote caching, parallel execution), and RemixIcon (3100+ SVG icons in outlined/filled styles). Use when creating React applications, implementing server-side rendering, setting up monorepos with multiple packages, optimizing build performance and caching strategies, adding icon libraries, managing shared dependencies, or working with TypeScript full-stack projects.

    Also in 6 projects that use this

  • mrgoonieSkill

    mcp-management

    Manage Model Context Protocol (MCP) servers - discover, analyze, and execute tools/prompts/resources from configured MCP servers. Use when working with MCP integrations, need to discover available MCP capabilities, filter MCP tools for specific tasks, execute MCP tools programmatically, access MCP prompts/resources, or implement MCP client functionality. Supports intelligent tool selection, multi-server management, and context-efficient capability discovery.

    Also in 6 projects that use this

  • +4 more from OpenAnalystInc
  • +2 more from mrgoonie

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 8 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 66 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the file and parse its YAML frontmatter

    line 25
  2. Very specific:

    Verify status: approved — skip any spec that is not approved

    line 26
  3. Very specific:

    Knowledge Graph: If graphify-out/graph.json exists, load it and extract:

    line 45
  4. Very specific:

    Design System: If the spec has a design: field or DESIGN.md exists in the project root, load it.

    line 52
  5. Distinctive:

    After receiving each frontier from the planner agent:

    line 70
  6. Distinctive:

    Requirement coverage: Verify every R-number from the spec maps to at least one task.

    line 72
  7. Very specific:

    Dependency validity: Verify all depends: references point to real task IDs.

    line 73
  8. Very specific:

    Repo ordering: If cross_repo_rules.api_first is true, API tasks in the same tier must be listed before frontend tasks.

    line 75
  9. Distinctive:

    Task count: Verify the task count falls within the depth range (e.g., 6-12 for standard).

    line 76
  10. Distinctive:

    Token estimates: Verify per-task estimates are reasonable for the depth level.

    line 77
  11. Very specific:

    Write initial estimates to .forge/token-ledger.json:

    line 108
  12. Very specific:

    Write .forge/state.md with the first spec queued:

    line 127
  13. Distinctive:

    After all frontiers are written, present a summary showing:

    line 157
  14. Very specific:

    When designing tasks (enforced by the forge-planner agent):

    line 168
  15. Distinctive:

    Dependency-minimal: Prefer fewer dependencies.

    line 172
  16. Distinctive:

    Requirement-traced: Every task should trace back to one or more R-numbers from the spec.

    line 176

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

Planning Skill

This skill guides the decomposition of approved specifications into executable task frontiers. Each frontier is a dependency-ordered list of tasks grouped into parallelizable tiers.

Inputs

You will receive:

  • Spec files: One or more approved spec files from .forge/specs/
  • Depth: quick, standard, or thorough
  • Repo config: From .forge/config.json (may include multiple repos with ordering)
  • Capabilities: From .forge/capabilities.json (optional, informs task design)
  • Knowledge graph: graphify-out/graph.json (optional, enables architecture-aware decomposition)
  • Design system: DESIGN.md (optional, enables design-tagged UI tasks)

Procedure

Step 1: Read and Validate Specs

For each spec file in .forge/specs/ (or the filtered subset):

  1. Read the file and parse its YAML frontmatter
  2. Verify status: approved — skip any spec that is not approved
  3. Extract all R-numbered requirements and their acceptance criteria
  4. Note the linked_repos field — this determines which repos tasks will target
  5. Note the complexity field — this informs task sizing

Step 2: Determine Depth Parameters

Reference references/token-profiles.md for depth-specific settings:

ParameterQuickStandardThorough
Tasks per spec3-56-1212-20
Tokens per task~3k~6k~12k
Review stepsNoneAfter critical tasksAfter every task
TDD enforcementNoIf skill availableAlways
Phase verificationSkipQuick checkFull goal-backward

Step 2.5: Load Architecture Context (optional)

Knowledge Graph: If graphify-out/graph.json exists, load it and extract:

  • God nodes (highest-connectivity concepts) for task prioritization
  • Community structure for aligning task boundaries with module boundaries
  • Cross-module dependencies for implicit dependency edges in the DAG

See skills/graphify-integration/SKILL.md for details.

Design System: If the spec has a design: field or DESIGN.md exists in the project root, load it. UI tasks will be tagged with design: DESIGN.md in the frontier, and a design verification task will be added for depth >= standard.

See skills/design-system/SKILL.md for details.

Step 3: Dispatch Planner Agent Per Spec

For each approved spec, dispatch a forge-planner agent (via the Agent tool) with:

  • The full spec content (requirements + acceptance criteria)
  • The resolved depth level
  • The repo configuration (which repos are available, their roles and ordering)
  • The capabilities map (which MCP servers and skills are available)
  • The knowledge graph summary (if available: god nodes, communities, key dependencies)
  • The design system reference (if available: DESIGN.md path)

The agent returns a frontier file in the template format. See templates/plan.md.

Step 4: Validate and Refine Frontiers

After receiving each frontier from the planner agent:

  1. Requirement coverage: Verify every R-number from the spec maps to at least one task. If any requirement is missing, add tasks to cover it.
  2. Dependency validity: Verify all depends: references point to real task IDs. No circular dependencies.
  3. Tier correctness: Tier 1 tasks must have zero dependencies. Tier N tasks must depend only on tasks in Tiers 1 through N-1.
  4. Repo ordering: If cross_repo_rules.api_first is true, API tasks in the same tier must be listed before frontend tasks.
  5. Task count: Verify the task count falls within the depth range (e.g., 6-12 for standard). Adjust if needed.
  6. Token estimates: Verify per-task estimates are reasonable for the depth level. Total should be sum of all tasks.

Step 5: Write Frontier Files

For each spec, write the frontier to .forge/plans/{spec-domain}-frontier.md.

The frontier file format (matching templates/plan.md):

---
spec: {domain}
total_tasks: {N}
estimated_tokens: {total}
depth: {quick|standard|thorough}
---

# {Domain} Frontier

## Tier 1 (parallel -- no dependencies)
- [T001] Task name | est: ~Nk tokens | repo: REPO
- [T002] Task name | est: ~Nk tokens | repo: REPO

## Tier 2 (depends on Tier 1)
- [T003] Task name | est: ~Nk tokens | repo: REPO | depends: T001, T002

## Tier 3 (depends on Tier 2)
- [T004] Task name | est: ~Nk tokens | repo: REPO | depends: T003

Step 6: Write Token Ledger

Write initial estimates to .forge/token-ledger.json:

{
  "total": 0,
  "iterations": 0,
  "per_spec": {
    "auth": { "estimated": 45000, "actual": 0 },
    "ui": { "estimated": 32000, "actual": 0 }
  },
  "estimated_total": 77000,
  "last_transcript_tokens": 0
}

The estimated_total is the sum of all frontier estimated tokens. The total (actual usage) starts at 0 and is updated during execution by the stop hook.

Step 7: Initialize State

Write .forge/state.md with the first spec queued:

---
phase: idle
spec: {first-spec-domain}
current_task: null
task_status: null
iteration: 0
tokens_used: 0
tokens_budget: {from config, default 500000}
depth: {resolved depth}
autonomy: {from config, default gated}
handoff_requested: false
---

## What's Done

## In-Flight Work

## What's Next
{List all specs and their task counts}

## Key Decisions
- Depth: {depth} ({reason -- auto-detected or user-specified})
- Planning generated {N} total tasks across {M} specs

Step 8: Present Summary

After all frontiers are written, present a summary showing:

  • Number of specs planned
  • Total tasks across all frontiers
  • Estimated total tokens
  • Depth level used
  • List of frontier files with task counts

Then instruct the user to run /forge execute to begin implementation.

Task Design Principles

When designing tasks (enforced by the forge-planner agent):

  1. Atomic: Each task has one clear deliverable. "Implement user model + migration" is one task, not "implement entire auth system."
  2. Testable: Each task's completion can be verified by running tests or checking observable output.
  3. Dependency-minimal: Prefer fewer dependencies. Tasks should be as parallelizable as possible.
  4. API-first: For multi-repo projects, API/backend tasks come before frontend tasks that depend on them.
  5. Scaffolding first: Structural tasks (models, controllers, routes) in early tiers, logic tasks (business logic, validation) in later tiers.
  6. Cross-repo boundary: Tasks that cross repo boundaries should be split into separate tasks per repo.
  7. Requirement-traced: Every task should trace back to one or more R-numbers from the spec. Every R-number must be covered by at least one task.

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.