From “smart cd” idea to a tested command foundation

Most people already have several ways to jump between directories: shell history, project checkouts, bookmarks, desktop mounts, and network shares. The friction is remembering which tool handles each location. goto is being shaped as one small Go command that accepts an entity and resolves it to a directory. Existing programs such as zoxide, ghq, udisks, sshfs, and gio are intended to do the specialized work; goto coordinates them rather than replacing their engines.

There is an important distinction in the design: the command prints a path, while a shell function changes the current shell's directory. A child process cannot change its parent's working directory. The intended interaction is therefore eval "$(goto init zsh)", which defines a short function (by default g) that calls the binary and then runs cd with its result. The separation keeps the executable useful to scripts and agents, where printing a path is more reliable than trying to manipulate an interactive shell.

The first implementation milestone arrived on October 2, 2026. Commit 8e79b81 added the Go module, a Cobra command, embedded YAML specifications, JSON schemas, command completion, and man-page generation. The specs describe command text, resolver ordering, and external tools; the loader rejects unknown fields, and tests check both schema validity and relationships between tool and resolver declarations. Ticket 001 was then closed with the stated acceptance that make check and make install passed. The present implementation remains deliberately small: entity resolution is still a placeholder, and the project issues track the larger resolver features as future work.

One revealing design episode was settling the output and interaction contract. A shell function captures the binary's standard output so it can pass the path to cd; any hint or warning on that stream would turn a valid directory into an invalid command argument. The architecture therefore assigns the resolved directory to stdout and hints, warnings, and prompts to stderr. The design notes go a step further: “interactive” depends on stdin and stderr being terminals, not stdout, because the shell function captures stdout even while a person is using a terminal. In non-interactive use, actions that need confirmation should fail with a specific exit code unless --yes is supplied, and --dry-run should avoid side effects. These choices make the same interface legible to both people and automation.

The October 2 documentation commits record the reasoning as well as the command shape. The feature list explains why fuzzy history is delegated to zoxide instead of building another frecency database. The architecture document records the resolver precedence mechanism, the spec layout, and pitfalls such as command names shadowing project names. Commits 536d618 and b6271f2 refined the binary-versus-shell distinction and the terminal/confirmation behavior; ticket 014 captures a later proposed goto spec [name] --open interaction. The issue tracker currently has one closed foundation ticket and thirteen open tickets, making the boundary between completed work and intended behavior visible.

This repository is evidence of disciplined groundwork for agentic development, but not yet evidence that agents delivered a large body of functionality. Its Harnez use is visible in the issue workflow, repository rules, shared development conventions, and explicit ticket references in the spec. The inspected commits do not establish that advisors, reverse-sprints, parallel agents, or feedback ratings produced the implementation, so those should not be claimed as accomplishments. At 16 commits, 525 tracked Go lines, two Go test files, and one closed ticket, it is also too early to claim that a single developer could not plausibly build and maintain the current code. The ambitious part is the planned breadth: projects and XDG directories, source trees, processes, local and remote mounts, archives, and bookmarks. Those are useful future challenges, not shipped features today.

The instructive lesson is smaller and more concrete: agent-ready software benefits from a stable contract before adding many integrations. A predictable stdout channel, explicit confirmation rules, schemas for configuration, and tickets for unfinished work give later contributors a shared map. Whether those foundations enable a broader agent workflow will be clear only as the open features are implemented and maintained.

Facts