home / skills / bdambrosio / cognitive_workbench / nav-advance

nav-advance skill

This skill advances forward up to a specified number of blocks, handling alignment and safety to maintain nav invariants.

npx playbooks add skill bdambrosio/cognitive_workbench --skill nav-advance

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

Files (2)

Skill.md

1.9 KB

---
name: nav-advance
type: python
description: "Advance forward up to N blocks using nav conventions. Stops early on collision, fall, or ambiguous support."
---

# nav-advance

Planner-friendly multi-step forward motion. Reduces fragile planner loops while preserving nav invariants (verification, snap-to-grid, nav history).

## Input

- `blocks`: Integer number of blocks to advance (required)
- `step_duration`: Float seconds per move (default: `0.2`)
- `max_abs_delta_y`: Float tolerance for Y noise (default: `0.2`)

## Output

Success (`status: "success"`):
- `value`: Summary text (e.g., "Advance completed: TARGET_REACHED (3/3)")

Failure (`status: "failed"`):
- `value`: Summary with steps completed
- `reason`: One of `"INVALID_TARGET"`, `"STATUS_FAILED"`, `"MOVE_FAILED"`, `"COLLISION"`, `"FELL"`, `"OBSERVATION_FAILED"`, `"UNEXPECTED_VERTICAL_CHANGE"`, `"SUPPORT_AMBIGUOUS"`

## Behavior

- Automatically aligns agent to block center and cardinal yaw before movement
- Moves forward in the direction of current yaw (use `nav-turn` first if yaw isn't in desired direction)
- Internally performs up to `blocks` single moves with verification
- Snaps to block center after each landed move and updates nav history
- Stops immediately when unsafe conditions are detected

## Alignment

Before each movement, agent is automatically aligned:
- Position: Block center (x+0.5, y, z+0.5) - eliminates fractional offsets
- Yaw: Nearest cardinal (0°=South, 90°=West, 180°=North, 270°=East)
- Pitch: 0°

This prevents collisions from fractional offsets and ensures predictable movement direction.

## Planning Notes

- Ensure agent yaw points in desired direction before calling (use `nav-turn` if needed)
- Use instead of planner loops over `nav-move`
- If `reason` is `FELL`, treat as safety event and consider `nav-backtrack`

## Example

```json
{"type":"nav-advance","blocks":3,"out":"$adv"}
```

Overview

This skill advances the agent forward up to N blocks using navigation conventions that preserve verification and history. It performs single-step moves with automatic alignment and stops early on collisions, falls, or ambiguous support. The result includes a clear success or failure status and a brief summary of steps completed.

How this skill works

Before moving, the agent is snapped to the nearest block center and cardinal yaw to ensure predictable direction and avoid fractional-offset collisions. The skill performs up to the requested number of single-block moves, verifying landing, snapping to center after each move, and updating navigation history. It halts immediately on unsafe conditions such as collisions, unexpected vertical changes, loss of support, observation failures, or falls and returns a failure reason.

When to use it

Advance multiple blocks reliably without writing planner loops.
Execute forward motion when you need verification after each step.
Move while preserving nav history and grid alignment for later recovery.
Stop on safety events (collision or fall) without continuing blind motion.
When you require consistent cardinal-directed movement after using nav-turn.

Best practices

Ensure agent yaw points in the desired direction before calling (use nav-turn).
Request a modest step_duration to balance speed and observation reliability.
Treat a FELL failure as a safety event and consider calling nav-backtrack.
Check returned reason and value to decide recovery or replanning actions.
Avoid relying on this skill for diagonal or non-cardinal movement.

Example use cases

Move forward three blocks along a hallway after aligning yaw with nav-turn.
Cross a sequence of predictable, flat blocks while ensuring each step is verified.
Advance toward an object while stopping immediately on unexpected collisions.
Perform grid-aligned traversal prior to a perception or manipulation action.
Use as a robust building block inside higher-level planners instead of looping nav-move.

FAQ

What happens if the agent isn't facing a cardinal direction?

The skill expects cardinal yaw. Call nav-turn first or it will align to the nearest cardinal before moving.

How does the skill report partial progress?

On success or failure the returned value summarizes steps completed (e.g., "TARGET_REACHED (3/3)").

Which failure reason indicates a safety event to recover from?

FELL indicates a safety event; use nav-backtrack or other recovery behavior.