planning

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:

| Parameter | Quick | Standard | Thorough | |-----------|-------|----------|----------| | Tasks per spec | 3-5 | 6-12 | 12-20 | | Tokens per task | ~3k | ~6k | ~12k | | Review steps | None | After critical tasks | After every task | | TDD enforcement | No | If skill available | Always | | Phase verification | Skip | Quick check | Full 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.