Shell functions, aliases, and executable boundaries: practice drills

Eight exercises classify commands, inspect helper definitions and sources, practice discoverability tools, choose aliases/functions/executables, preserve arguments across zsh handoffs, build a webhook replay wrapper, and map orchestration responsibilities.

These exercises practice command diagnosis and wrapper design.

The goal is not to memorize every helper. The goal is to prove what a command name is and choose the right integration pattern.

Exercise 1: Classify Command Names

Run:

for name in alias cd git l rm x xi xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain; do
  printf "%-14s " "$name"
  whence -w "$name" 2>/dev/null || echo MISSING
done

Fill out:

# Command Classification

| Name | alias / function / builtin / command / missing | Notes |
| --- | --- | --- |
| alias | | |
| cd | | |
| git | | |
| xfl | | |
| xfc | | |
| xport | | |
| fix | | |
| muxai | | |
| agent_chain | | |

Questions:

  • Which names are portable executables?
  • Which names only exist inside zsh?
  • Which names are workflow wrappers?

Exercise 2: Function Versus Executable

Pick three helpers:

xfl
xfc
xport
p-f
p-c
fix
agent_chain
muxai
ghost-save
pksk

Run:

for name in xfl xfc xport; do
  echo "== $name =="
  whence -w "$name" 2>/dev/null || true
  type "$name" 2>/dev/null || true
  command -v "$name" 2>/dev/null || true
  whence -p "$name" 2>/dev/null || true
done

Fill out:

# Function Versus Executable

| Helper | `whence -w` result | `command -v` result | `whence -p` result | Needs executable fallback? |
| --- | --- | --- | --- | --- |
| | | | | |

Exercise 3: Find The Source

Pick one helper:

xfl
xfc
xport
p-f
p-c
fix
ghost-save
pksk
muxai
agent_chain

Run:

whence -w <name>
funcwhere <name>
functions <name> | sed -n '1,120p'

Fill out:

# Function Reading Notes

- helper:
- kind:
- source file:
- purpose:
- arguments:
- external tools called:
- files or git state it may change:
- why this is a function instead of an alias:
- one way to confirm it worked:
- one failure mode:

Exercise 4: Use funclist, funcwhere, And funced

Run:

funclist
funclist ai
funclist git
funclist -v x

Then pick a helper and run:

funcwhere <name>
funced <name>

Fill out:

# Discoverability Notes

- topic searched:
- helper found:
- source file:
- what `funclist` showed:
- what `funcwhere` showed:
- whether `funced` opened the expected source:
- one improvement you would make to the helper comment or description:

Exercise 5: Alias Or Function?

For each proposed helper, decide alias, function, executable wrapper, or no helper.

Desired Helper Your Choice Why
l runs ls -lah
rm routes to trash only when installed
replay-webhook <fixture> runs a command, captures logs, and prints pass/fail
xport exports the latest Codex transcript and optionally saves markdown
pksk terminates process groups and cleans matching app processes
agent_chain runs gated explore-plan-implement phases
ci-smoke must run from GitHub Actions

Exercise 6: Write A Safe Handoff

Scenario: Prompt Builder or another tool needs to call xfc, but xfc is a zsh function.

Diagnose:

whence -w xfc
funcwhere xfc
whence -p xfc || true

Write a safe handoff:

zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' xfc "continue the failing billing webhook investigation"

Adapt the pattern for:

xfl
xport
p-f
p-c

Exercise 7: Design An Executable Fallback

Scenario: the project has a repeated workflow for replaying billing webhooks. It must work from zsh, scripts, CI, and agents.

Create a wrapper shape:

mkdir -p bin
cat > bin/replay-webhook <<'EOF'
#!/usr/bin/env zsh
set -euo pipefail
fixture="${1:?Usage: replay-webhook <fixture>}"
pnpm test:billing-webhook -- "$fixture"
EOF
chmod +x bin/replay-webhook

Confirm it:

zsh -lc 'PATH="$PWD/bin:$PATH"; p="$(command -v replay-webhook)"; print -r -- "$p"; test -x "$p"'
zsh -lc 'PATH="$PWD/bin:$PATH"; replay-webhook sample-fixture'

Fill out:

# Executable Fallback Design

- wrapper path:
- shebang:
- required arguments:
- underlying command:
- confirmation command:
- why executable instead of function:

Exercise 8: Section 4 Bridge

Run:

whence -w muxai agent_chain xfl xfc xport p-f p-c
funcwhere muxai
funcwhere agent_chain

Fill out:

# Section 4 Bridge Notes

- helpers that create or manage workspace shape:
- helpers that fork or compact Codex threads:
- helpers that export context:
- helpers that run multi-agent phases:
- what needs a pane/thread/layout confirmation:
- what another agent would need to resume:

Source references