home / skills / bdambrosio / cognitive_workbench / path-frontier

path-frontier skill

safe

/src/world-tools/minecraft/path-frontier

This skill enumerates reachable nearby frontier positions using a bounded BFS simulation, returning offsets and paths for planning without moving.

npx playbooks add skill bdambrosio/cognitive_workbench --skill path-frontier

Review the files below or copy the command above to add this skill to your agents.

Files (3)

Skill.md

2.3 KB

---
name: path-frontier
type: python
description: "Enumerate possible nearby frontier positions within a bounded number of nav actions (over-approx; simulation only)."
situational: false
---

# path-frontier

Reasoning tool that enumerates reachable nearby positions using conservative bounded BFS over nav semantics. Does not execute movement; uses simulation only.

## Input

- `max_actions`: Integer maximum number of nav actions to explore (default: `4`)
- `allow_unknown`: Boolean, if True over-approximates unknown cells as possibly traversable (default: `True`)

## Output

Returns uniform_return format. Access return value via `result["data"]` (not `result["value"]`).

Success (`status: "success"`):
- `data`: Dict containing:
  - `reachable`: List of `{"dx": int, "dz": int, "path": List[str]}` positions reachable within bounds (relative to start)
    - `dx`, `dz`: World-relative offsets from starting position (see coordinate system in jill-minecraft.yaml)
    - `path`: Sequence of action names from start to position (e.g., `["nav-turn-right", "nav-move", "nav-climb"]`)
    - path is a simulation estimate, and may fail in execution
  - `count`: Integer count of reachable positions
- `value`: Formatted/truncated version of data (for display)
- `resource_id`: Note ID if result was persisted

Failure (`status: "failed"`):
- `reason`: One of `"executor_not_available"`, `"status_failed"`
- `data`: Reason string (same as `reason`)

## Behavior

- Performs bounded BFS exploration using `nav_simulation.simulate_nav_step`
- Explores `nav-move`, `nav-descend`, `nav-climb`, and `nav-turn` (left/right only)
- Uses spatial map from `world_state("spatial_map")` for cell queries
- Excludes starting position from results
- Over-approximate by default: unknown cells are treated as possibly traversable unless `allow_unknown=False`
- `nav-turn` changes facing direction without moving position (counts as one action)

## Planning Notes

- Use for reasoning about reachability, not for actual movement
- Requires spatial map to be populated (via `mc-map-update`)
- Small `max_actions` (default 4) keeps exploration bounded
- May return 0 positions. This is NOT an error, and does not require recovery
- Results are relative `dx, dz` offsets from start position (Y coordinate not included)

## Example

```json
{"type":"path-frontier","max_actions":3,"out":"$frontier"}
```

Overview

This skill enumerates nearby frontier positions reachable within a bounded number of navigation actions using a conservative BFS simulation. It returns an over-approximation of positions reachable from the start without executing any real movement, helping planners reason about possible next locations.

How this skill works

The skill runs a bounded breadth-first search over allowed nav actions (move, climb, descend, turn left/right) using nav_simulation.simulate_nav_step and the current spatial_map from world_state("spatial_map"). It treats unknown cells as traversable by default (allow_unknown=True) and reports reachable offsets as dx/dz plus the simulated action path. The starting cell is excluded and nav-turn counts as an action while not changing position.

When to use it

To estimate which nearby positions a robot/agent could reach within a small number of navigation steps.
During high-level planning to identify candidate next goals without committing to movement.
When testing map coverage or exploring possible frontiers after a map update.
To verify reachability constraints before issuing real navigation commands.
When you need a conservative, simulation-only approximation that tolerates unknown cells.

Best practices

Keep max_actions small (default 4) to limit combinatorial explosion and keep results meaningful.
Ensure the spatial_map is populated (use mc-map-update) so the simulation has accurate cell data.
Set allow_unknown=False for stricter, pessimistic reachability when unknowns should be treated as obstacles.
Treat returned paths as estimates; they may fail in real execution and should be validated by an actual navigator.
Expect zero results as a valid outcome; zero reachable positions does not indicate an error.

Example use cases

Compute candidate nearby goals for a short-horizon exploration policy before selecting one to navigate to.
Validate whether a proposed short path is plausible given current map knowledge without moving the agent.
Report possible reachable offsets to a UI to visualize local frontiers around the agent.
Use in planning simulations where actions must be counted (including turns) to estimate action budgets.

FAQ

Does this skill move the agent?

No. It only simulates navigation steps and returns possible reachable positions; no real movement is executed.

What does allow_unknown do?

When true (default), unknown cells are treated as possibly traversable to produce an over-approximation; set to false to treat unknowns as obstacles.