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: