feat(shell): open and complete project_open projects anywhere under ~/Code

[codepuncher]

Summary

Generalize project_open/po to open and tab-complete projects discovered anywhere under ~/Code (not just ~/Code/wordpress), backed by an on-disk cache, with Bash and Zsh autocompletion.

Changes

• Discover projects under ~/Code at <category>/<project> depth: any such directory holding a .git is a project (nested submodules sit deeper and are excluded). Resolve a project by basename.
• Back discovery with an on-disk cache under $XDG_CACHE_HOME/project_open/ (the filename is keyed by root, so a different PROJECT_OPEN_ROOT never reads a stale cache), built asynchronously on interactive shell startup when absent and then kept until po_refresh rebuilds it. Root is overridable via PROJECT_OPEN_ROOT.
• project_open <name> opens a project found anywhere under ~/Code. With no second argument it keeps the existing WordPress bedrock/site descent; with a second argument it cds into that literal <subdir> of the project root (no descent), matching the prior behaviour. The two were never combined; the old theme special-case is removed.
• Add a Bash completion adapter/registration and register Zsh completion the canonical way via an autoloaded #compdef function on $fpath (shell/completions/_project_open) for project_open and po. First-argument (project name) completion reads the cache; second-argument completion lists the resolved project's immediate subdirectories via a shallow find.

Testing

• tests/project_open.bats (BATS) covers discovery, cache build/refresh, name resolution, completion helpers, and runtime navigation. Run with ./tests/bats/bin/bats tests/*.bats; now wired into CI alongside ShellCheck and stylua.
• shellcheck shell/aliases and zsh -n shell/aliases.

[Copilot]

Pull request overview

Adds interactive shell autocompletion for the project_open function (and its po alias) across Bash and Zsh, using shared helper functions to discover WordPress projects and their immediate subdirectories under ~/Code/wordpress.

Changes:

• Add shared discovery helpers (_project_open_projects, _project_open_targets) in shell/aliases.
• Register Bash completion via complete -F ... for project_open and po.
• Add Zsh completion function (via deferred eval) and register it with compdef when available.
• Add a design/spec document describing goals, architecture, and manual testing steps.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
shell/aliases	Implements project/target discovery and wires up Bash + Zsh completion handlers for project_open/po.
docs/superpowers/specs/2026-06-19-project-open-autocomplete-design.md	Documents design goals, behavior, and manual testing approach for the new completions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

shell/aliases:371

• project_open <name> theme used to be handled as a special case (jumping to the first Composer theme). With the new early return on any second argument, theme is now treated as a literal subdirectory and will try to cd "${NEW_PATH}/theme", which is likely wrong and a behavior regression.

	if [ -n "${2}" ]; then
		# shellcheck disable=SC2164
		cd "${NEW_PATH}/${2}"
		return
	fi

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

shell/aliases:369

• project_open previously special-cased a second argument of theme (skipping the generic cd "${NEW_PATH}/${2}" and instead resolving a composer-based theme directory). With the new unconditional [ -n "${2}" ] early-return, project_open <wp-project> theme will now try to cd into a literal theme/ subdirectory and never reaches any theme lookup. If theme is still a supported subcommand, reintroduce the special-case and theme resolution after the bedrock/site descent.

	if [ -n "${2}" ]; then
		# shellcheck disable=SC2164
		cd "${NEW_PATH}/${2}"
		return
	fi

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.