home / skills / bdambrosio / cognitive_workbench / nav-move

nav-move skill

safe

This skill executes exactly one forward move relative to facing direction and reports outcome to enable reliable step-by-step navigation.

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

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-move
type: python
description: "Attempt exactly ONE adjacent navigation move forward and report the outcome. Atomic navigation operation suitable for composition."
---

# nav-move

Attempt exactly one adjacent forward move (relative to current facing direction) and report the outcome. Atomic forward navigation primitive.

## Input

- `step_duration`: Float seconds for the move (default: `0.2`)
- `max_abs_delta_y`: Float tolerance for Y noise (default: `0.2`)

## Output

Success (`status: "success"`):
- `value`: Summary text
- `extra.from`: Starting position `{x, y, z}`
- `extra.to`: Ending position `{x, y, z}`
- `extra.delta_y`: Vertical displacement
- `extra.support_here`: Support type at destination

Failure (`status: "failed"`):
- `reason`: One of `"status_failed"`, `"move_failed"`, `"collision"`, `"fell"`, `"observation_failed"`, `"support_ambiguous"`, `"unexpected_vertical_change"`
- `extra.from`, `extra.to`: Positions (if available)

## Behavior

- Automatically aligns agent to block center and cardinal yaw before movement
- Calls bridge `/act/move` once (forward) with collision checking
- Moves forward relative to current facing direction
- Validates landing via `mc-status` + `mc-observe`
- Snaps to block center after any position change
- Updates `world_state("nav")` history

## Alignment

Before 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

- Use for single-step movement with verification
- For multi-step forward motion, prefer `nav-advance`
- If `fell` occurs, treat as safety event and consider `nav-backtrack`

## Examples

```json
{"type":"nav-move","out":"$m1"}
{"type":"nav-move","step_duration":0.25,"out":"$m2"}
```

Overview

This skill attempts exactly one adjacent forward move relative to the agent's current facing direction and reports a precise outcome. It is an atomic navigation primitive designed to be composed into larger motion plans. The operation aligns the agent, executes a single forward action, verifies landing, and returns structured success or failure details.

How this skill works

Before moving, the agent snaps to the center of the current block and sets yaw to the nearest cardinal direction and pitch to zero to avoid fractional-offset collisions. The skill calls a single forward move action with collision checking, then validates the result using status and observation checks. It returns structured output describing start/end positions, vertical change, support at the destination, or a specific failure reason.

When to use it

You need one guaranteed forward step with verification before composing further moves.
Testing or debugging low-level navigation behavior step-by-step.
Performing safety-checked movement where a single failed step should abort higher-level plans.
Situations where precise alignment and predictable cardinal movement are required.
Before invoking multi-step primitives to validate single-step feasibility.

Best practices

Allow the skill to realign the agent; do not mix pre-move offsets as it snaps to block center and cardinal yaw.
Use this as an atomic primitive inside higher-level planners rather than for long-distance motion.
Inspect failure reasons to decide recovery: e.g., treat "fell" as a safety event and trigger backtrack or stop.
Set step_duration for smoother simulation if needed, but keep it minimal for responsiveness.
Check extra fields (from/to/delta_y/support_here) to validate environmental assumptions before next action.

Example use cases

Move one block forward down a corridor, verify support and proceed if successful.
Step onto a new block to inspect support type (solid, air, etc.) before placing blocks or interacting.
Use in a recovery loop: attempt move, on collision adjust facing or clear obstacle, retry.
Combine multiple nav-move calls inside a planner to build stepwise, verifiable paths with immediate fall/collision detection.

FAQ

What exactly does success include?

Success includes a summary text plus extra fields: starting and ending positions, vertical displacement, and detected support at the destination.

What failure reasons should I handle specially?

Treat "fell" as a safety-critical event requiring backtrack or emergency stop. "collision" indicates blocked path; consider clearing or re-planning. "unexpected_vertical_change" and "support_ambiguous" indicate sensing or environment anomalies.

Should I use nav-move for long movements?

No. Use this for single-step atomic moves. For multi-step forward motion, prefer a higher-level primitive designed for advancement and path planning.