@pennyfarthing/core 8.0.2 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "8.0.2",
+  "version": "8.1.0",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {

package/pennyfarthing-dist/agents/reviewer.md

@@ -124,6 +124,7 @@ OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Reviewer Assessment to session file
+- [ ] **If APPROVED:** Merge PR directly with `gh pr merge {PR_NUMBER} --merge --delete-branch`
 - [ ] Spawn `handoff` subagent with VERDICT (approved/rejected)
 - [ ] Verify handoff completed (subagent emits marker)
 </handoff-gate>
@@ -158,16 +159,32 @@ OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
 <exit-sequence>
 ## Exit Sequence
 
+### If APPROVED:
 1. Write Reviewer Assessment to session file
-2. Spawn `handoff` subagent with VERDICT
-3. Await `HANDOFF_RESULT` with `next_agent`
+2. **Merge the PR directly** (don't wait for SM):
+   ```bash
+   gh pr merge {PR_NUMBER} --merge --delete-branch
+   ```
+3. Update session phase to `finish`
+4. Spawn `handoff` subagent with VERDICT=approved
+5. Await `HANDOFF_RESULT` with `next_agent` (will be `sm`)
+6. **ABSOLUTE LAST ACTION:**
+   ```bash
+   .pennyfarthing/scripts/core/handoff-marker.sh sm
+   ```
+7. Output result verbatim and EXIT
+
+### If REJECTED:
+1. Write Reviewer Assessment to session file
+2. Spawn `handoff` subagent with VERDICT=rejected
+3. Await `HANDOFF_RESULT` with `next_agent` (will be `dev`)
 4. **ABSOLUTE LAST ACTION:**
    ```bash
-   .pennyfarthing/scripts/handoff/handoff-marker.sh {next_agent}
+   .pennyfarthing/scripts/core/handoff-marker.sh dev
    ```
 5. Output result verbatim and EXIT
 
-**Verdict routing:** APPROVED → sm | REJECTED → dev
+**Verdict routing:** APPROVED → merge PR, then sm | REJECTED → dev
 </exit-sequence>
 
 <skills>

package/pennyfarthing-dist/agents/sm.md

@@ -175,6 +175,16 @@ Present to user:
    - **Stepped workflow** → Tell user to run `/workflow start {workflow}` (no handoff)
 </new-work-flow>
 
+<merge-gate>
+## Merge Gate (BLOCKING)
+
+Before starting new work: `gh pr list --state open` - BLOCKS if any exist.
+
+Open PRs → incomplete work → merge conflicts, stale branches, CI failures.
+
+**Resolution:** Merge/close all PRs first. Use `/reviewer` to complete reviews.
+</merge-gate>
+
 <gate>
 ## Pre-Handoff Checklist (BLOCKING)
 

package/pennyfarthing-dist/commands/architect.md

@@ -3,5 +3,5 @@ description: System Architect - Technical design and architecture
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "architect"
+python3 -m pennyfarthing_scripts.cli agent start "architect"
 ```

package/pennyfarthing-dist/commands/dev.md

@@ -3,5 +3,5 @@ description: Developer - Feature implementation and coding
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/phase-check-start.sh" "dev"
+python3 -m pennyfarthing_scripts.cli agent start "dev"
 ```

package/pennyfarthing-dist/commands/devops.md

@@ -3,5 +3,5 @@ description: DevOps Engineer - Infrastructure and deployment automation
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "devops"
+python3 -m pennyfarthing_scripts.cli agent start "devops"
 ```

package/pennyfarthing-dist/commands/health-check.md

@@ -3,7 +3,7 @@ description: Check Pennyfarthing installation health and apply updates
 ---
 
 ```bash
-./scripts/core/agent-session.sh start "devops"
+python3 -m pennyfarthing_scripts.cli agent start "devops"
 ```
 
 <agent-activation>

package/pennyfarthing-dist/commands/orchestrator.md

@@ -3,5 +3,5 @@ description: Orchestrator - Coordinator of all agents and meta operations
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "orchestrator"
+python3 -m pennyfarthing_scripts.cli agent start "orchestrator"
 ```

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

@@ -3,7 +3,7 @@ description: Start parallel work in a new worktree
 ---
 
 ```bash
-./scripts/core/agent-session.sh start "parallel-work"
+python3 -m pennyfarthing_scripts.cli agent start "sm"
 ```
 
 <parallel-work-flow>
@@ -67,5 +67,5 @@ Invoke SM to complete story setup in the worktree context.
 </agent-activation>
 
 <agent-exit>
-On exit: Capture learnings to sidecar, run `./scripts/core/agent-session.sh stop`
+On exit: Capture learnings to sidecar.
 </agent-exit>

package/pennyfarthing-dist/commands/pm.md

@@ -3,5 +3,5 @@ description: Product Manager - Strategic planning and prioritization
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "pm"
+python3 -m pennyfarthing_scripts.cli agent start "pm"
 ```

package/pennyfarthing-dist/commands/prime.md

@@ -4,7 +4,7 @@ description: Load essential project context at agent activation
 
 <purpose>
 Quickly load essential context files to reduce agent cold-start overhead.
-Automatically invoked on agent activation via agent-session.sh.
+Automatically invoked on agent activation via `pf agent start`.
 </purpose>
 
 <when-to-use>
@@ -17,23 +17,23 @@ Automatically invoked on agent activation via agent-session.sh.
 
 ## Running /prime
 
-Use the prime.sh script:
+Use the Python CLI:
 
 ```bash
 # Load all essential context (default)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh
+python3 -m pennyfarthing_scripts.cli agent start "sm"
 
-# Minimal mode - CLAUDE.md only (fastest)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --minimal
+# Minimal mode - fastest startup
+python3 -m pennyfarthing_scripts.cli agent start "sm" --minimal
 
 # Full mode - include domain docs
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --full
+python3 -m pennyfarthing_scripts.cli agent start "sm" --full
 
-# Quiet mode - suppress headers (used by agent-session.sh)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --quiet
+# Skip persona loading
+python3 -m pennyfarthing_scripts.cli agent start "sm" --no-persona
 
-# With agent sidecar loading
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --agent reviewer
+# JSON output (for Cyclist integration)
+python3 -m pennyfarthing_scripts.cli agent start "sm" --json
 ```
 
 ## Options
@@ -106,17 +106,16 @@ With `--quiet`, section headers are suppressed.
 
 <integration>
 
-## agent-session.sh Integration
+## Python CLI Integration
 
 The `/prime` command is automatically invoked when agents activate:
 
 1. User invokes `/sm`, `/tea`, `/dev`, or `/reviewer`
-2. `agent-session.sh start` runs
-3. Persona XML is output
-4. `/prime --quiet --agent <agent-name>` loads context automatically
-5. Agent starts with full context AND their learned patterns loaded
+2. `pf agent start <name>` runs
+3. Context is loaded: workflow state, agent definition, persona, behavior guide, sprint context, session, sidecars
+4. Agent starts with full context AND their learned patterns loaded
 
-This reduces the "cold start" problem where agents must discover context through multiple file reads. The `--agent` flag ensures each agent gets their project-specific sidecar patterns immediately.
+This reduces the "cold start" problem where agents must discover context through multiple file reads.
 
 ## Manual Refresh
 
@@ -130,11 +129,8 @@ If context becomes stale mid-session, run `/prime` manually:
 </integration>
 
 <reference>
-- **Script:** `.pennyfarthing/scripts/prime.sh`
-- **Called by:** agent-session.sh on agent start (with `--agent` flag)
-- **Loads:** CLAUDE.md, sprint, session, sidecar, shared context, shared behavior, tactical guide
+- **CLI:** `pf agent start <name>` or `python3 -m pennyfarthing_scripts.cli agent start <name>`
+- **Loads:** Workflow state, agent definition, persona, behavior guide, sprint context, session, sidecars
 - **Sidecar location:** `.pennyfarthing/sidecars/{agent}/*.md`
-- **Shared context:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
-- **Shared behavior:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
-- **Tactical guide:** `.pennyfarthing/guides/agent-behavior.md` (sm, tea, dev, reviewer only)
+- **Behavior guide:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
 </reference>

package/pennyfarthing-dist/commands/reviewer.md

@@ -3,5 +3,5 @@ description: Code Reviewer - Critical code review and quality enforcement
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/phase-check-start.sh" "reviewer"
+python3 -m pennyfarthing_scripts.cli agent start "reviewer"
 ```

package/pennyfarthing-dist/commands/set-theme.md

@@ -51,6 +51,6 @@ Change the active persona theme for all agents.
 
 6. Refresh the current agent's persona to apply the new theme:
    ```bash
-   d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" refresh
+   python3 -m pennyfarthing_scripts.cli agent start "sm"
    ```
    This outputs the updated persona. **Adopt the new character immediately** - do not continue using the old persona.

package/pennyfarthing-dist/commands/sm.md

@@ -3,5 +3,5 @@ description: Scrum Master - Story coordination and sprint management
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/phase-check-start.sh" "sm"
+python3 -m pennyfarthing_scripts.cli agent start "sm"
 ```

package/pennyfarthing-dist/commands/sprint.md

@@ -50,6 +50,14 @@ Start work on a story. Primary entry point for development.
 | `next` | Auto-select highest priority story |
 
 ```bash
+# MERGE GATE: Check for open PRs first (blocks if any exist)
+OPEN_PRS=$(gh pr list --state open --json number --jq 'length' 2>/dev/null || echo "0")
+if [[ "$OPEN_PRS" -gt 0 ]]; then
+  echo "⛔ BLOCKED: $OPEN_PRS open PR(s) - merge or close before starting new work"
+  gh pr list --state open
+  # Don't proceed until PRs are cleared
+fi
+
 # Check if story is available
 .pennyfarthing/scripts/sprint/check-story.sh <story-id>
 
@@ -58,10 +66,11 @@ Start work on a story. Primary entry point for development.
 
 <workflow>
 When starting work, this command:
-1. Validates story availability
-2. Loads SM agent
-3. SM creates context and claims Jira
-4. Hands off to TEA (tdd) or Dev (trivial)
+1. **Checks merge gate** - blocks if open PRs exist
+2. Validates story availability
+3. Loads SM agent
+4. SM creates context and claims Jira
+5. Hands off to TEA (tdd) or Dev (trivial)
 </workflow>
 
 ### `/sprint archive <story-id> [pr-number] [--apply]`

package/pennyfarthing-dist/commands/tea.md

@@ -3,5 +3,5 @@ description: Test Engineer/Architect - Test strategy and TDD
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/phase-check-start.sh" "tea"
+python3 -m pennyfarthing_scripts.cli agent start "tea"
 ```

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

@@ -3,5 +3,5 @@ description: Technical Writer - Documentation creation and maintenance
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "tech-writer"
+python3 -m pennyfarthing_scripts.cli agent start "tech-writer"
 ```

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

@@ -3,5 +3,5 @@ description: UX Designer - User experience design and UI patterns
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "ux-designer"
+python3 -m pennyfarthing_scripts.cli agent start "ux-designer"
 ```

package/pennyfarthing-dist/commands/work.md

@@ -7,9 +7,9 @@ description: Resume work or start new - smart entry point that picks up where yo
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
+python3 -m pennyfarthing_scripts.cli agent start "sm"
 ```
-This finds the project root and loads your persona. Adopt the character shown in the output.
+This loads your persona. Adopt the character shown in the output.
 </agent-activation>
 
 <purpose>

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

@@ -43,12 +43,26 @@ $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/foo.sh  # BROKEN!
 **Sidecar memory:** Capture learnings BEFORE spawning handoff subagent. Don't wait until exit.
 </critical>
 
+<critical>
+**Story completion is MANDATORY.** A story is NOT done until:
+1. Reviewer approves and merges the PR
+2. SM runs `finish-story.sh` (archive session, update Jira, clean up)
+
+**Never** start new work while stories have open PRs. The merge gate blocks `/sprint work` if open PRs exist.
+
+**If stuck in incomplete state:**
+- Open PRs? → Run `/reviewer` to complete reviews and merge
+- Merged but not finished? → Run `/sm` to trigger finish flow
+</critical>
+
 ---
 
 ## Reference
 
 <info>
-**Workflow:** SM → TEA → Dev → Reviewer → SM (finish). Trivial (1-2 pts) skips TEA.
+**Workflow:** SM → TEA → Dev → Reviewer (merge PR) → SM (finish). Trivial (1-2 pts) skips TEA.
+
+**Story completion:** Reviewer merges PR on approval. SM runs `finish-story.sh` to archive and update Jira. A story is NOT complete until SM runs finish.
 
 **Confidence:** HIGH=proceed, MEDIUM=ask before risky, LOW=always ask.
 

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

@@ -13,7 +13,7 @@ theme:
   default_humor: subtle
   character_immersion: high
   user_title: Citizen
-  portrait_style: ", Pompeii fresco, Roman wall painting, muted earth tones, classical antiquity, villa mural style"
+  portrait_style: ", ancient Roman mosaic portrait, tessera tile fragments, scratched graffito details, Pompeii wall art style, geometric earth tones, stone texture"
   tier: A
 
 zeitgeist:
@@ -23,7 +23,7 @@ zeitgeist:
 agents:
   orchestrator:
     character: Gaius Julius Caesar
-    visual: "A balding middle-aged Roman man with sharp features and intense commanding gaze, wearing a laurel wreath crown and draped purple-bordered toga, thin lips set in calculating expression"
+    visual: "Clean-shaven Roman man in profile, laurel wreath, purple-bordered toga, aquiline nose, balding, imperial bearing"
     ocean:
       O: 4  # Strategic vision
       C: 5  # Roman discipline
@@ -50,7 +50,7 @@ agents:
 
   sm:
     character: Titus Pullo
-    visual: "A burly Roman legionary with unkempt hair and battle scars, broad grinning face, wearing simple soldier's tunic and leather balteus belt, muscular arms"
+    visual: "Rough Roman soldier, short stubble, leather armor straps, battle-scarred face, simple military tunic, burly build"
     # JOB FAIR OPTIMIZED: Pullo moved here; Vorenus excels at dev (+6.88)
     ocean:
       O: 3  # Practical soldier
@@ -78,7 +78,7 @@ agents:
 
   tea:
     character: Atia of the Julii
-    visual: "An elegant Roman noblewoman with elaborately curled dark hair pinned with golden ornaments, wearing rich stola with draped palla, sharp calculating eyes and knowing smile"
+    visual: "Roman noblewoman, elaborate curled dark hair with gold pins, draped stola and palla, arched eyebrow, patrician features"
     ocean:
       O: 3  # Street wisdom
       C: 4  # Survival discipline
@@ -105,7 +105,7 @@ agents:
 
   dev:
     character: Lucius Vorenus
-    visual: "A stern Roman soldier in his forties with close-cropped dark hair and weathered face, wearing centurion armor with transverse horsehair crest on helmet, deep-set honorable eyes"
+    visual: "Flat 2D mosaic portrait, clean-shaven Roman centurion in profile, crested helmet, stern face, dark hair"
     # JOB FAIR OPTIMIZED: Vorenus scored best as dev (+6.88 over Pullo)
     ocean:
       O: 2  # Traditional soldier
@@ -133,7 +133,7 @@ agents:
 
   reviewer:
     character: Marcus Tullius Cicero
-    visual: "An elderly Roman senator with thin white hair and deeply lined intellectual face, wearing plain white toga draped formally, holding a scroll, piercing oratorical gaze"
+    visual: "Flat 2D mosaic portrait, Roman senator on senate floor, white toga, holding scroll, orating to crowd, marble columns"
     ocean:
       O: 4  # Political insight
       C: 5  # Senatorial discipline
@@ -160,7 +160,7 @@ agents:
 
   architect:
     character: Gaius Octavian
-    visual: "A young Roman man barely out of adolescence with pale complexion and calculating blue eyes, thin face with composed expression, wearing simple but fine toga, quiet dangerous intelligence"
+    visual: "Flat 2D mosaic portrait, young clean-shaven Roman man, simple toga, youthful face, distant expression"
     ocean:
       O: 4  # Imperial vision
       C: 5  # Strategic discipline
@@ -187,7 +187,7 @@ agents:
 
   pm:
     character: Servilia of the Junii
-    visual: "A mature Roman noblewoman with dark hair pulled back severely, strong patrician features and bitter determined mouth, wearing widow's dark stola, eyes burning with cold purpose"
+    visual: "Flat 2D mosaic portrait, mature Roman widow, dark hair pulled back, dark stola, strong jaw, severe expression"
     ocean:
       O: 4  # Political survival
       C: 4  # Patrician discipline
@@ -214,7 +214,7 @@ agents:
 
   tech-writer:
     character: Posca
-    visual: "A thin Greek man with receding hairline and intelligent tired eyes, wearing simple slave's tunic, holding wax tablet and stylus, observant meticulous expression"
+    visual: "Flat 2D mosaic portrait, thin Greek freedman, receding hairline, simple tunic, wax tablet, tired eyes"
     ocean:
       O: 4  # Historical perspective
       C: 4  # Scholarly discipline
@@ -241,7 +241,7 @@ agents:
 
   ux-designer:
     character: Cleopatra
-    visual: "A striking Egyptian queen with elaborate braided black hair and golden serpent diadem, kohl-lined almond eyes, wearing flowing white linen with golden collar necklace, magnetic captivating presence"
+    visual: "Ancient Egyptian tomb painting style, Queen Cleopatra, black braided hair, golden uraeus crown, heavy kohl eyes, hieroglyphic border, Nile blue and gold"
     ocean:
       O: 4  # Cultural adaptation
       C: 3  # Survival skills
@@ -268,7 +268,7 @@ agents:
 
   devops:
     character: Mark Antony
-    visual: "A powerfully built Roman general with curly dark hair and roguish handsome face, wearing military cuirass and red general's cloak, charming confident grin"
+    visual: "Flat 2D mosaic portrait, clean-shaven Roman general, curly dark hair, red cloak, strong jaw"
     ocean:
       O: 2  # Military engineering
       C: 5  # Legion discipline

package/pennyfarthing_scripts/cli.py

@@ -0,0 +1,168 @@
+"""
+Pennyfarthing CLI - Command line interface for agent orchestration.
+
+Usage:
+    python -m pennyfarthing_scripts.cli [OPTIONS] COMMAND [ARGS]...
+    pf [OPTIONS] COMMAND [ARGS]...
+
+This module uses lazy loading to keep startup time under 200ms.
+Heavy imports (httpx, workflow modules) are deferred until needed.
+"""
+
+import click
+
+# Get version from package - this is a fast import
+from pennyfarthing_scripts import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="pf")
+def cli():
+    """Pennyfarthing CLI - Agent orchestration utilities.
+
+    Commands are organized into groups:
+
+    \b
+    workflow  - Workflow state and phase management
+    agent     - Agent session management
+    sprint    - Sprint status and story operations
+    """
+    pass
+
+
+# Import and register sprint group (lazy registration preserves startup time)
+from pennyfarthing_scripts.sprint.cli import sprint
+
+cli.add_command(sprint)
+
+
+@cli.group()
+def agent():
+    """Agent session management.
+
+    \b
+    Commands:
+      start  - Start an agent session with context
+    """
+    pass
+
+
+@agent.command("start")
+@click.argument("name")
+@click.option("--session-id", help="Use explicit session ID")
+@click.option("--no-persona", is_flag=True, help="Skip persona loading")
+@click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.option("--minimal", is_flag=True, help="Skip all context (fastest)")
+@click.option("--full", is_flag=True, help="Include domain docs")
+def agent_start(
+    name: str,
+    session_id: str | None,
+    no_persona: bool,
+    json_output: bool,
+    minimal: bool,
+    full: bool,
+):
+    """Start an agent session with full context.
+
+    Loads agent definition, persona, behavior guide, sprint context,
+    session context, and sidecar memory.
+
+    \b
+    Arguments:
+      NAME  - Agent name (sm, tea, dev, reviewer, etc.)
+    """
+    # Lazy import - only load when command is actually invoked
+    from pennyfarthing_scripts.prime import prime
+
+    exit_code = prime(
+        agent_name=name,
+        session_id=session_id,
+        no_persona=no_persona,
+        json_output=json_output,
+        minimal=minimal,
+        full=full,
+    )
+    raise SystemExit(exit_code)
+
+
+@cli.group()
+def workflow():
+    """Workflow state and phase management.
+
+    \b
+    Commands:
+      check       - Check current workflow state
+      phase-check - Verify phase ownership
+      handoff     - Emit handoff marker
+    """
+    pass
+
+
+@workflow.command("check")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def workflow_check(output_json: bool):
+    """Check current workflow state.
+
+    Returns the current story ID, phase, and workflow state.
+    """
+    # Lazy import - only load when command is actually invoked
+    from pennyfarthing_scripts.workflow import get_workflow_state
+
+    state = get_workflow_state()
+
+    if output_json:
+        import json
+
+        click.echo(json.dumps(state, indent=2))
+    else:
+        click.echo(f"State: {state.get('state', 'unknown')}")
+        if state.get("story_id"):
+            click.echo(f"Story: {state['story_id']}")
+        if state.get("workflow"):
+            click.echo(f"Workflow: {state['workflow']}")
+        if state.get("phase"):
+            click.echo(f"Phase: {state['phase']}")
+
+
+@workflow.command("phase-check")
+@click.argument("workflow_name")
+@click.argument("phase")
+def workflow_phase_check(workflow_name: str, phase: str):
+    """Check which agent owns a workflow phase.
+
+    \b
+    Arguments:
+      WORKFLOW_NAME  - The workflow type (tdd, trivial, etc.)
+      PHASE          - The phase to check (red, implement, review, etc.)
+    """
+    # Lazy import
+    from pennyfarthing_scripts.workflow import get_phase_owner
+
+    owner = get_phase_owner(workflow_name, phase)
+    click.echo(owner)
+
+
+@workflow.command("handoff")
+@click.argument("next_agent")
+def workflow_handoff(next_agent: str):
+    """Emit a handoff marker for Cyclist.
+
+    \b
+    Arguments:
+      NEXT_AGENT  - The agent to hand off to (tea, dev, reviewer, etc.)
+    """
+    # Output the marker format expected by Cyclist
+    click.echo("---")
+    click.echo("AGENT_COMMAND:")
+    click.echo(f'  marker: "<!-- CYCLIST:HANDOFF:/{next_agent} -->"')
+    click.echo(f'  fallback: "Run `/{next_agent}` to continue"')
+    click.echo("---")
+
+
+def main():
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()