@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/commands/pf-standalone.md

@@ -41,6 +41,8 @@ Fast path for shipping completed work that deserves tracking but doesn't need st
 8. Create PR with summary
 9. Merge PR (squash) and delete branch
 10. Return to develop
+11. Add done story to `current-sprint.yaml` standalone_stories section
+12. Write retroactive session file to `sprint/archive/{JIRA_KEY}-session.md`
 </workflow>
 
 ## Execution
@@ -176,6 +178,64 @@ echo "   Jira: https://1898andco.atlassian.net/browse/$JIRA_KEY"
 echo "   PR: $PR_URL"
 ```
 
+### Step 7: Sprint Tracking & Session Archive
+
+After merge, register the story in sprint YAML and write an archived session file.
+
+**Add to `current-sprint.yaml` standalone_stories section:**
+
+Append a new entry under `standalone_stories:` in `sprint/current-sprint.yaml` (create the section if it doesn't exist). Use the same field structure as `stories:` entries:
+
+```yaml
+standalone_stories:
+  - id: ${JIRA_KEY}
+    jira: ${JIRA_KEY}
+    title: ${TITLE}
+    points: ${POINTS}
+    status: done
+    repos: ${REPO}        # pennyfarthing or orchestrator (whichever has the changes)
+    pr: ${PR_NUMBER}
+    branch: ${BRANCH}
+```
+
+**Write retroactive session file** to `sprint/archive/${JIRA_KEY}-session.md`:
+
+```markdown
+# Standalone: ${TITLE}
+
+**Jira:** ${JIRA_KEY}
+**Points:** ${POINTS}
+**Priority:** P2
+**Workflow:** standalone
+**Status:** done
+**Repos:** ${REPO}
+**Branch:** ${BRANCH}
+**PR:** ${PR_NUMBER}
+**Started:** ${TODAY}
+**Completed:** ${TODAY}
+
+---
+
+## Description
+
+${DESCRIPTION}
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+${FILE_TABLE}
+```
+
+**Commit both tracking files** in the orchestrator repo:
+
+```bash
+# Return to orchestrator root
+cd ${PROJECT_ROOT}
+git add sprint/current-sprint.yaml sprint/archive/${JIRA_KEY}-session.md
+git commit -m "chore(sprint): add standalone ${JIRA_KEY} to sprint tracking"
+```
+
 ## Safety
 
 - **NEVER commit directly to develop**

package/pennyfarthing-dist/commands/pf-tea.md

@@ -5,7 +5,7 @@ description: Test Engineer/Architect - Test strategy and TDD
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "tea"
+pf agent start "tea"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/commands/pf-tech-writer.md

@@ -5,7 +5,7 @@ description: Technical Writer - Documentation creation and maintenance
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "tech-writer"
+pf agent start "tech-writer"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/commands/pf-ux-designer.md

@@ -5,7 +5,7 @@ description: UX Designer - User experience design and UI patterns
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "ux-designer"
+pf agent start "ux-designer"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/commands/pf-work.md

@@ -7,7 +7,7 @@ description: Resume work or start new - smart entry point that picks up where yo
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "sm"
+pf agent start "sm"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -3,22 +3,22 @@
 
 **Tests:** Use `testing-runner` subagent, never run directly.
 
-**Handoff:** Run pf.sh `handoff resolve-gate` → gate check → pf.sh `handoff complete-phase` → pf.sh `handoff marker` → EXIT. See `<agent-exit-protocol>`.
+**Handoff:** Run `pf handoff resolve-gate` → gate check → `pf handoff complete-phase` → `pf handoff marker` → EXIT. See `<agent-exit-protocol>`.
 
 **Sidecars:** Write learnings BEFORE starting exit protocol.
 
 **Scripts:** Pennyfarthing scripts are Python-based (`pf/`), not shell—check before assuming `.sh`.
 
-**pf CLI:** Never call bare `pf` — it is not globally installed. Always use the wrapper:
+**pf CLI:** Call `pf` directly — it is globally installed:
 ```bash
-"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh <command> [args...]
+pf <command> [args...]
 ```
 </critical>
 
 <critical>
 **Story completion is MANDATORY.** A story is NOT done until:
 1. Reviewer approves and merges the PR
-2. SM runs pf.sh `sprint story finish` (archive session, update Jira, clean up)
+2. SM runs `pf sprint story finish` (archive session, update Jira, clean up)
 
 **Never** start new work while stories have open PRs. The merge gate blocks `/pf-sprint work` if open PRs exist.
 
@@ -32,7 +32,7 @@
 ## Reference
 
 <info>
-**Workflow:** SM → TEA → Dev → Reviewer → SM. Trivial skips TEA.
+**Workflow:** Read the active workflow YAML at `pennyfarthing-dist/workflows/` for phase order, agents, and tandem/team pairings. Session file `**Workflow:**` line tells you which one is active. `pf workflow show <name>` for details.
 
 **Skills:** `/pf-sprint`, `/pf-testing`, `/pf-jira`, `/pf-just`
 
@@ -54,7 +54,7 @@ On activation, check session file for a `**Tandem:**` line (e.g., `**Tandem:** a
 
 **If tandem is configured:**
 
-1. **Resolve backseat persona** from theme using the `pf.sh theme`
+1. **Resolve backseat persona** from theme using `pf theme`
    ```bash
    THEME=$(yq '.theme' .pennyfarthing/config.local.yaml)
    PARTNER_CHARACTER=$(yq ".agents.{PARTNER}.character" .pennyfarthing/personas/themes/${THEME}.yaml)
@@ -227,14 +227,14 @@ When spawned as a teammate (you receive a task via spawn prompt, not a phase han
 1. Write assessment to session
 2. **If team mode active:** Shut down all teammates via `SendMessage`, then `TeamDelete`. Wait for cleanup before proceeding.
 3. Terminate tandem backseat (if active)
-4. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff resolve-gate {story-id} {workflow} {phase}` → RESOLVE_RESULT
+4. `pf handoff resolve-gate {story-id} {workflow} {phase}` → RESOLVE_RESULT
 5. If blocked → report error, STOP
 6. If skip → jump to step 8
 7. If ready → spawn gate subagent with gate file → GATE_RESULT
    - If fail → fix issues, retry from step 4 (max 3 retries)
    - If pass → continue
-8. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}`
-9. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff marker {next_agent}` → AGENT_COMMAND block
+8. `pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}`
+9. `pf handoff marker {next_agent}` → AGENT_COMMAND block
 10. **Act on AGENT_COMMAND:**
     - Has `marker:` field → emit the CYCLIST marker (Cyclist path)
     - `action: "inline_handoff"` → run `activation_command` via Bash, output result, adopt new agent identity
@@ -250,12 +250,12 @@ When spawned as a teammate (you receive a task via spawn prompt, not a phase han
 On activation, check if story phase belongs to you:
 
 ```bash
-"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff phase-check {your_agent_name}
+pf handoff phase-check {your_agent_name}
 ```
 
 If result has `action: "redirect"`:
 
 - **Cyclist:** Emit `<!-- CYCLIST:HANDOFF:/{phase_owner} -->` and EXIT
-- **CLI + relay ON:** Run `source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start {phase_owner} --tier handoff --quiet` via Bash, adopt new identity
+- **CLI + relay ON:** Run `pf agent start {phase_owner} --tier handoff --quiet` via Bash, adopt new identity
 - **CLI + relay OFF:** Output `Run /pf-{phase_owner} to continue` and EXIT
 </wrong-phase-detection>

package/pennyfarthing-dist/guides/agent-tag-taxonomy.md

@@ -175,10 +175,10 @@ Logic for checking if this agent owns the current phase.
 
 Read `**Workflow:**` and `**Phase:**` from session. Query:
 ```bash
-OWNER=$("$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh workflow phase-check {workflow} {phase})
+OWNER=$(pf workflow phase-check {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `pf.sh handoff marker $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 

package/pennyfarthing-dist/guides/bikelane.md

@@ -8,14 +8,7 @@ Workflow orchestration engine. Coordinates multi-agent development through three
 
 ### Phased — Agent-driven with automatic handoffs
 
-| Workflow | Flow |
-|----------|------|
-| `tdd` | SM → TEA (RED) → Dev (GREEN) → Reviewer → SM |
-| `tdd-tandem` | SM → TEA+Architect (RED) → Dev+TEA (GREEN) → Reviewer+PM → SM |
-| `bdd` | SM → UX → TEA → Dev → Reviewer → SM |
-| `bdd-tandem` | SM → UX+Architect → TEA → Dev+UX (GREEN) → Reviewer+PM → SM |
-| `trivial` | SM → Dev → Reviewer → SM |
-| `agent-docs` | SM → Orchestrator → Tech Writer → SM |
+Workflow definitions live in `pennyfarthing-dist/workflows/*.yaml`. Each YAML defines phases, agents, tandem/team pairings, and gates. Use `pf workflow list` to see all available workflows, `pf workflow show <name>` for phase details. **Read the YAML — don't rely on summaries.**
 
 ### Stepped — Progressive disclosure with user gates
 

package/pennyfarthing-dist/guides/bikerack.md

@@ -26,6 +26,25 @@ Cyclist bundles the conversation UI and dashboard panels into one Electron app.
 
 ## Quick Start
 
+There are two approaches to running BikeRack.
+@arcaven currently uses:
+
+```bash
+# hint - cd ($repo)
+just wheelhub stop # in case it's running, clears left over pid and port files
+just wheelhub start # open browser w/ the URL for GUI
+just claude # handles some env setup
+
+# in another terminal
+# hint - cd ($repo)
+just tui
+
+# or
+just bikerack # your mileage may vary
+```
+
+RoseSecurity has been using:
+
 ```bash
 # Launch BikeRack + Claude CLI together
 pf.sh bikerack start
@@ -117,6 +136,81 @@ pf.sh bc list                 # List saved layouts
 | `packages/core/src/public/components/StandalonePanel.tsx` | `?panel=X` routing + `PANEL_REGISTRY` |
 | `pf/bikerack/cli.py` | `pf.sh bikerack` launcher CLI |
 
+## TUI Mode (Terminal Dashboard)
+
+BikeRack also ships a Textual-based TUI that runs entirely in the terminal — no browser needed.
+
+### Prerequisites
+
+- **Python** >= 3.11
+- **uv** (recommended) or pip
+- **just** >= 1.0
+
+### Setup
+
+```bash
+# From the pennyfarthing repo root — create venv and install TUI deps
+python3 -m venv .venv
+uv pip install --python .venv/bin/python3 -e "pennyfarthing-dist[tui]"
+```
+
+This installs the required packages into `.venv/`:
+
+| Package | Purpose |
+|---------|---------|
+| `textual` >= 1.0 | Terminal UI framework |
+| `websockets` >= 12.0 | WheelHub WebSocket client |
+| `rich` | Terminal rendering (textual dependency) |
+| `click` >= 8.0 | CLI framework (base dependency) |
+| `pyyaml` >= 6.0 | YAML parsing (base dependency) |
+| `textual-image` >= 0.7.0 | Agent portrait images (optional, graceful fallback) |
+
+The justfile automatically uses `.venv/bin/python3` when `.venv/` exists.
+
+### Launch
+
+```bash
+# Default — connects to WheelHub on localhost:1898
+just tui
+
+# Point at a specific project directory
+just tui dir=/path/to/project
+
+# Custom WheelHub port
+just tui port=2898
+```
+
+### Panels
+
+The TUI provides tabbed panels navigable via keyboard:
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `]` | Next panel |
+| `[` | Previous panel |
+| `Shift+S` | Split view |
+| `Ctrl+P` | Command palette |
+| `q` | Quit |
+
+Available panels: Sprint, Git, Diffs, Audit Log, Debug, Progress.
+
+### Troubleshooting
+
+**`ModuleNotFoundError: No module named 'textual'`**
+```bash
+# Deps not installed in venv — re-run setup
+uv pip install --python .venv/bin/python3 -e "pennyfarthing-dist[tui]"
+```
+
+**`No module named 'pf'`**
+The justfile sets `PYTHONPATH` automatically. If running manually:
+```bash
+PYTHONPATH=pennyfarthing-dist:$PYTHONPATH .venv/bin/python3 -m pf.bikerack.tui
+```
+
+**Portrait images not rendering**
+Install `textual-image` (included in the `[tui]` extra). Requires a terminal with Sixel or Kitty graphics protocol support (iTerm2, WezTerm, Kitty). Falls back to text-only in unsupported terminals.
+
 ## Constraints
 
 - **No MessagePanel** — Claude conversation stays in your terminal. This is intentional.

package/pennyfarthing-dist/guides/hooks.md

@@ -308,5 +308,5 @@ If a hook fails or behaves unexpectedly:
 | Managed hooks | `.pennyfarthing/scripts/hooks/` | No (symlinked — edit in `pennyfarthing-dist/`) |
 | Project hooks | `.claude/project/hooks/` | Yes |
 | Settings | `.claude/settings.local.json` | Yes |
-| Git hook dispatchers | `.git/hooks/{name}` | No (installed by `pennyfarthing init`) |
+| Git hook dispatchers | `.git/hooks/{name}` | No (installed by `pf setup`) |
 | Git hook scripts | `.git/hooks/{name}.d/` | Yes (add scripts to `.d/` directories) |

package/pennyfarthing-dist/guides/what-is-pennyfarthing.md

@@ -0,0 +1,91 @@
+# What Is Pennyfarthing?
+
+A Claude Code agent orchestration framework. It coordinates multiple AI agents through BikeLane workflows — structured phase sequences with quality gates and automatic handoffs.
+
+## Three Pillars
+
+| Pillar | What It Does |
+|--------|-------------|
+| **Development Platform** | 11 agents hand off work through BikeLane workflows. Phased workflows (TDD, BDD, trivial, agent-docs, patch) drive agents through phases automatically. Stepped workflows (architecture, research, PRD) guide users through gated steps. |
+| **Personality Research** | 102 themed persona sets (Discworld, Star Trek, Breaking Bad, etc.) studied for how character traits affect agent behavior. OCEAN profiling, TRAIL error taxonomy, benchmarking. |
+| **Integration & Tooling** | Visual dashboards (Cyclist desktop app, BikeRack browser/TUI panels), Jira sync, sprint tracking, codebase health analysis. |
+
+## How BikeLane Workflows Work
+
+A BikeLane workflow defines a sequence of **phases**, each owned by an **agent**, separated by **gates**.
+
+```
+Phase 1 → [gate] → Phase 2 → [gate] → Phase 3 → ...
+```
+
+Each agent does its job, writes an assessment, passes the gate, and hands off to the next agent. The workflow YAML defines the order — you can create custom workflows or use built-in ones.
+
+**Phased workflows** (agent-driven): SM sets up the story, agents hand off to each other automatically.
+
+| Workflow | Phases | Use For |
+|----------|--------|---------|
+| `tdd` | SM → TEA → Dev → Reviewer → SM | Features with test-first design |
+| `bdd` | SM → UX → TEA → Dev → Reviewer → SM | User-facing features |
+| `trivial` | SM → Dev → Reviewer → SM | Quick fixes, 1-2 point chores |
+| `agent-docs` | SM → Orchestrator → Tech Writer → SM | Documentation updates |
+| `patch` | Dev → Reviewer → SM | Interrupt-driven bug fixes |
+
+**Stepped workflows** (user-guided): BikeLane walks you through gated steps with prompts.
+
+| Workflow | Use For |
+|----------|---------|
+| `architecture` | System design documents |
+| `research` | Technical or domain research |
+| `prd` | Product requirements |
+
+## Key Concepts
+
+| Term | What It Is |
+|------|-----------|
+| **BikeLane** | Workflow engine — the core of Pennyfarthing. Defines phase order, agents, gates, tandem pairings, and team composition. Every structured task runs through a BikeLane. |
+| **BikeRack** | Dashboard panel viewer — browser or terminal, alongside your Claude Code session |
+| **Cyclist** | Full desktop app with embedded terminal and panels |
+| **WheelHub** | Local server powering dashboard panels via API |
+| **Prime** | Context loader — assembles agent definition, persona, session state, and sidecar memory |
+| **TirePump** | Context clearing — resets conversation when approaching limits |
+| **Handoff** | Agent transition — assessment → gate check → phase complete → next agent activates |
+| **Tandem** | Background observer — a second agent watches and comments as you work |
+| **Sidecar** | Persistent learning file — agents record patterns, gotchas, and decisions across stories |
+| **Gates** | Quality checks between phases — tests must pass, reviews must approve |
+
+## Entry Points
+
+| Want to... | Command |
+|------------|---------|
+| Start or resume work | `/pf-work` |
+| See sprint backlog | `/pf-sprint backlog` |
+| Check installation health | `/pf-health-check` |
+| See all commands | `/pf-help` |
+
+## Display Modes
+
+| Mode | How | For |
+|------|-----|-----|
+| **CLI only** | `claude` | Agents in your terminal, no dashboard |
+| **BikeRack GUI** | `just gui` + `just claude` | Dashboard in browser, Claude in terminal |
+| **BikeRack TUI** | `just tui` + `just claude` | Dashboard in terminal alongside Claude |
+| **Cyclist** | `pf cyclist` | Desktop app with everything |
+
+## What Pennyfarthing Is NOT
+
+- **Not a code generator.** Agents coordinate work; they use Claude Code for the actual coding.
+- **Not an IDE replacement.** It wraps Claude Code's CLI with structured workflows. Use your editor as usual.
+- **Not mandatory ceremony.** The `trivial` workflow skips TEA entirely for quick fixes. Scale to fit.
+- **Not locked to one theme.** Personas are swappable. Run `/pf-theme set shakespeare` and your SM becomes a different character.
+
+## File Layout
+
+| Path | Purpose |
+|------|---------|
+| `.pennyfarthing/` | Runtime config and symlinks (don't edit directly) |
+| `pennyfarthing-dist/agents/` | Agent behavior definitions |
+| `pennyfarthing-dist/guides/` | Component documentation (you are here) |
+| `pennyfarthing-dist/workflows/` | BikeLane workflow definitions |
+| `pennyfarthing-dist/personas/` | Theme and character files |
+| `.session/` | Active work sessions |
+| `sprint/` | Sprint tracking YAML |

package/pennyfarthing-dist/guides/xml-tags.md

@@ -132,10 +132,10 @@ Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Revie
 
 Read `**Workflow:**` and `**Phase:**` from session. Query:
 ```bash
-OWNER=$("$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh workflow phase-check {workflow} {phase})
+OWNER=$(pf workflow phase-check {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `pf.sh handoff marker $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 

package/pennyfarthing-dist/personas/themes/discworld.yaml

@@ -13,7 +13,9 @@ theme:
   default_humor: enabled
   character_immersion: high
   user_title: Citizen of Ankh-Morpork
-  portrait_style: ", ink and wash illustration, satirical fantasy, whimsical yet serious"
+  portrait_prefix: "Watercolor painting on rough paper:"
+  portrait_style: ", soft washes, visible paper texture, warm muted palette"
+  negative_prompt: "photorealistic, glossy, 3d render, digital art, smooth skin, airbrushed, photograph, sharp focus"
   tier: A
   dimensions:
     tone: satirical
@@ -27,7 +29,7 @@ zeitgeist:
 agents:
   orchestrator:
     character: DEATH
-    visual: "A seven-foot skeleton in flowing black robes,  holding an hourglass in one hand and a scythe in the other"
+    visual: "A tall skeleton in flowing black robes, blue lights in eye sockets, holding a golden hourglass and scythe, dark library with glowing books behind"
     ocean:
       O: 5
       C: 5
@@ -56,7 +58,7 @@ agents:
     shortName: DEATH
   sm:
     character: Captain Carrot Ironfoundersson
-    visual: "A six-foot-tall man with honest blue eyes and red-gold hair, wearing the ua copper breastplate polished to perfection with two hippos on it in relief"
+    visual: "A tall muscular man with honest blue eyes and red-gold hair, polished copper breastplate over chainmail, earnest open face, cobblestone street at dusk"
     ocean:
       O: 2
       C: 5
@@ -85,7 +87,7 @@ agents:
     shortName: Carrot
   tea:
     character: Igor
-    visual: "A hunched figure with mismatched eyes, visible stitching across the face, lank black hair, wearing a stained apron over traditional Igor attire, holding surgical implements with surprising delicacy, lisp included in the kindly expression"
+    visual: "A hunched man with mismatched eyes, crude stitching across face and neck, lank black hair, blood-stained leather apron, holding surgical implements, kindly lopsided smile, specimen jars behind"
     ocean:
       O: 3
       C: 5
@@ -115,7 +117,7 @@ agents:
     shortName: Igor
   dev:
     character: Ponder Stibbons
-    visual: "A bespectacled young wizard with perpetually worried expression, robes covered in chalk dust and arcane calculations, standing before Hex the thinking engine (complete with ants and ram skull), surrounded by senior wizards who don't understand"
+    visual: "A thin bespectacled young man in dark academic robes covered in chalk dust, worried expression, standing before a brass mechanical computing engine with glass tubes, papers pinned everywhere"
     ocean:
       O: 5
       C: 5
@@ -145,7 +147,7 @@ agents:
     shortName: Ponder
   reviewer:
     character: Granny Weatherwax
-    visual: "The most formidable witch on the Disc, iron-grey hair in a tight bun beneath a pointed black hat, piercing blue eyes that see through all pretense, standing arms-crossed in Lancre cottage doorway, 'I ATEN'T DEAD' sign ready nearby"
+    visual: "A thin formidable elderly witch, bony and gaunt, iron-grey hair in tight bun beneath tall pointed black witch hat, piercing blue eyes, sharp angular face, plain black dress, arms crossed in stone cottage doorway"
     ocean:
       O: 3
       C: 5
@@ -175,7 +177,7 @@ agents:
     shortName: Granny
   architect:
     character: Leonard of Quirm
-    visual: "A gentle genius in paint-stained smock with wild grey hair and kind distracted eyes, surrounded by incredible sketches and impossible inventions, mirror-writing covering every surface, accidentally designing weapons while trying to make things beautiful"
+    visual: "A gentle genius in paint-stained smock, wild grey hair, kind distracted eyes, charcoal smudges on hands, surrounded by sketches of flying machines, candlelit Renaissance workshop"
     ocean:
       O: 5
       C: 3
@@ -205,7 +207,7 @@ agents:
     shortName: Leonard
   pm:
     character: Lord Havelock Vetinari
-    visual: "The Patrician of Ankh-Morpork in severe black robes, thin face with cold calculating eyes, long fingers steepled, sitting perfectly still at his desk completing the Times crossword, the hint of a scorpion pit somewhere below"
+    visual: "A tall thin aristocrat in austere black robes, gaunt face, cold calculating grey eyes, long pale fingers steepled, sitting at a dark wood desk, single candle casting sharp shadows"
     ocean:
       O: 5
       C: 5
@@ -235,7 +237,7 @@ agents:
     shortName: Vetinari
   tech-writer:
     character: Sacharissa Cripslock
-    visual: "A determined young journalist with ink-stained fingers and practical clothing, notepad clutched tight, standing in the chaotic offices of the Ankh-Morpork Times beneath 'THE TRUTH SHALL MAKE YE FRET' banner, refusing to accept 'no comment'"
+    visual: "A determined young woman with sharp eyes and brown hair pinned up, ink-stained fingers gripping notepad and pencil, high-collared blouse, chaotic newspaper office with printing press behind"
     ocean:
       O: 4
       C: 5
@@ -265,7 +267,7 @@ agents:
     shortName: Sacharissa
   ux-designer:
     character: Adora Belle Dearheart
-    visual: "A sharp-featured woman in severe black dress, permanent cigarette trailing smoke, cold grey eyes that have seen too much, surrounded by loyal golems in the Golem Trust office, 'Spike' nickname earned through attitude not appearance"
+    visual: "A sharp-featured woman in severe black dress, angular cheekbones, cold grey eyes, cigarette trailing smoke from elegant fingers, dark hair pulled back, tall clay figures looming behind"
     ocean:
       O: 4
       C: 5
@@ -295,7 +297,7 @@ agents:
     shortName: Adora
   devops:
     character: Lu-Tze
-    visual: "A small, wrinkly, bald old man in simple sweeper's robes, carrying a broom with serene smile, 'RULE ONE' tattooed on his scalp, the most dangerous man in any room disguised as the least important, time itself bending around him"
+    visual: "A small wrinkly bald old man in faded saffron robes, carrying a bamboo broom, serene knowing smile, sharp eyes, bare feet on stone monastery steps"
     ocean:
       O: 5
       C: 5
@@ -327,7 +329,7 @@ agents:
 
   ba:
     character: Moist von Lipwig
-    visual: "A charming con artist with easy smile and sharp eyes, wearing golden suit and winged hat of the Postmaster General, surrounded by letters, the man who discovered honesty is the best con"
+    visual: "A charming man with easy confident smile and sharp eyes, extravagant golden suit, dramatic winged hat, leaning against marble counter piled with letters, gaslit postal hall"
     ocean:
       O: 4  # High openness - creative schemes, adaptable
       C: 4  # High conscientiousness - reformed, keeps promises now