@pennyfarthing/core 11.1.1 → 11.2.0

package/pennyfarthing-dist/skills/pf-workflow/skill.md

@@ -11,25 +11,22 @@ Pennyfarthing uses YAML-defined workflows to control agent sequences. The defaul
 
 ## Quick Reference
 
-### Shell Script Commands
-
-| Command | Script | Purpose |
-|---------|--------|---------|
-| `/pf-workflow` or `/pf-workflow list` | `.pennyfarthing/scripts/workflow/list-workflows.sh` | List all workflows |
-| `/pf-workflow show [name]` | `.pennyfarthing/scripts/workflow/show-workflow.sh [name]` | Show workflow details |
-| `/pf-workflow set <name>` | Edit session file `**Workflow:**` line | Switch workflow mid-session |
-| `/pf-workflow start <name>` | `.pennyfarthing/scripts/workflow/start-workflow.sh <name> [--mode M]` | Start stepped workflow |
-| `/pf-workflow resume [name]` | `.pennyfarthing/scripts/workflow/resume-workflow.sh [name]` | Resume interrupted workflow |
-| `/pf-workflow status` | `.pennyfarthing/scripts/workflow/workflow-status.sh` | Show stepped workflow progress |
-| `/pf-workflow fix-phase <id> <phase>` | `.pennyfarthing/scripts/workflow/fix-session-phase.sh <id> <phase> [--dry-run]` | Repair session phase |
-
 ### Python CLI Commands
 
 | Command | CLI | Purpose |
 |---------|-----|---------|
+| `/pf-workflow` or `/pf-workflow list` | `pf workflow list` | List all workflows |
+| `/pf-workflow show [name]` | `pf workflow show [name]` | Show workflow details |
+| `/pf-workflow set <name>` | Edit session file `**Workflow:**` line | Switch workflow mid-session |
+| `/pf-workflow start <name>` | `pf workflow start <name> [--mode M]` | Start stepped workflow |
+| `/pf-workflow resume [name]` | `pf workflow resume [name]` | Resume interrupted workflow |
+| `/pf-workflow status` | `pf workflow status` | Show stepped workflow progress |
+| `/pf-workflow fix-phase <id> <phase>` | `pf workflow fix-phase <id> <phase> [--dry-run]` | Repair session phase |
 | Check workflow state | `pf workflow check [--json]` | Current story, phase, state |
 | Check phase owner | `pf workflow phase-check <workflow> <phase>` | Which agent owns a phase |
+| Get workflow type | `pf workflow type <workflow>` | phased/stepped/procedural |
 | Emit handoff marker | `pf workflow handoff <next-agent>` | CYCLIST handoff marker |
+| Complete step | `pf workflow complete-step [name] [--step N]` | Advance stepped workflow |
 
 ### Built-in Workflows
 

package/pennyfarthing-dist/skills/pf-workflow/usage.md

@@ -1,11 +1,11 @@
 # Workflow — Detailed Usage
 
-## Shell Script Commands
+## Commands
 
 ### List Workflows
 
 ```bash
-.pennyfarthing/scripts/workflow/list-workflows.sh
+pf workflow list
 ```
 
 No arguments. Returns table of workflows with type, phases/steps count, modes, default flag, description.
@@ -13,7 +13,7 @@ No arguments. Returns table of workflows with type, phases/steps count, modes, d
 ### Show Workflow
 
 ```bash
-.pennyfarthing/scripts/workflow/show-workflow.sh [NAME]
+pf workflow show [NAME]
 ```
 
 | Arg | Required | Description |
@@ -31,7 +31,7 @@ Warning: Only do this when story requirements have fundamentally changed. Switch
 ### Start Stepped Workflow
 
 ```bash
-.pennyfarthing/scripts/workflow/start-workflow.sh <NAME> [--mode <MODE>]
+pf workflow start <NAME> [--mode <MODE>]
 ```
 
 | Arg/Option | Required | Description |
@@ -44,7 +44,7 @@ Creates a new session and begins at step 1.
 ### Resume Stepped Workflow
 
 ```bash
-.pennyfarthing/scripts/workflow/resume-workflow.sh [NAME]
+pf workflow resume [NAME]
 ```
 
 | Arg | Required | Description |
@@ -54,7 +54,7 @@ Creates a new session and begins at step 1.
 ### Workflow Status
 
 ```bash
-.pennyfarthing/scripts/workflow/workflow-status.sh
+pf workflow status
 ```
 
 No arguments. Shows current step, progress percentage, mode.
@@ -62,7 +62,7 @@ No arguments. Shows current step, progress percentage, mode.
 ### Fix Session Phase
 
 ```bash
-.pennyfarthing/scripts/workflow/fix-session-phase.sh <STORY_ID> <TARGET_PHASE> [--dry-run]
+pf workflow fix-phase <STORY_ID> <TARGET_PHASE> [--dry-run]
 ```
 
 | Arg/Option | Required | Description |
@@ -80,9 +80,22 @@ Valid phases by workflow:
 
 Updates `**Phase:**` field, `**Phase Started:**` timestamp, and handoff history table.
 
+### Complete Step
+
+```bash
+pf workflow complete-step [NAME] [--step N]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (auto-detects from session) |
+| `--step N` | No | Complete specific step number instead of current |
+
+Advances session: increments step, updates completed list, recalculates percentage.
+
 ---
 
-## Python CLI Commands
+## State & Phase Commands
 
 ### Check Workflow State
 
@@ -109,6 +122,18 @@ pf workflow phase-check <WORKFLOW_NAME> <PHASE>
 
 Returns the agent name that owns the phase.
 
+### Get Workflow Type
+
+```bash
+pf workflow type <WORKFLOW_NAME>
+```
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `WORKFLOW_NAME` | Yes | Workflow name (e.g., `tdd`, `architecture`) |
+
+Returns `phased`, `stepped`, or `procedural`.
+
 ### Emit Handoff Marker
 
 ```bash

package/pennyfarthing-dist/workflows/bdd-tandem.yaml

@@ -1,14 +1,23 @@
 # BDD Tandem Workflow - BDD with Full Tandem Chain
-# Extends standard BDD with tandem observers:
-#   - Architect backseats UX-Designer during design
-#   - UX-Designer backseats Dev during implementation
-#   - PM backseats Reviewer during review
 #
-# Flow: SM → UX-Designer (+Architect) → TEA → Dev (+UX-Designer) → Reviewer (+PM) → SM
+# When to use: Best for UI/UX-heavy stories where designer-architect pairing
+# shapes implementation. Use this instead of base bdd when the story involves
+# complex user flows, new component patterns, or cross-domain UI integration.
+#
+# Tandem pairings:
+#   - DESIGN phase: UX-Designer + Architect (file-watch) — Architect validates technical feasibility
+#   - RED phase: TEA + Dev (file-watch) — Dev provides implementation context for test strategy
+#   - GREEN phase: Dev + UX-Designer (file-watch) — UX-Designer ensures design fidelity
+#   - REVIEW phase: Reviewer + PM (file-watch) — PM validates business requirements
+#
+# Compared to base bdd: Adds tandem observers on every working phase.
+# Designer-developer pairing ensures UX intent survives implementation.
+#
+# Flow: SM → UX-Designer (+Architect) → TEA (+Dev) → Dev (+UX-Designer) → Reviewer (+PM) → SM
 
 workflow:
   name: bdd-tandem
-  description: BDD with full tandem chain across design, implementation, and review
+  description: BDD with full tandem chain — designer and architect consultation across phases
   version: "1.0.0"
 
   phases:
@@ -36,6 +45,9 @@ workflow:
         file: gates/tests-fail
         type: tests_fail
         condition: Behavior scenarios have test coverage
+      tandem:
+        partner: dev
+        scope: file-watch
 
     - name: green
       agent: dev

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-01-analyze.md

@@ -32,7 +32,7 @@ Build a complete picture of uncommitted changes across ALL repos defined in `.cl
 **CRITICAL: Use the multi-repo script, not plain `git status`.**
 
 ```bash
-.pennyfarthing/scripts/git/git-status-all.sh
+pf git status
 ```
 
 This shows branch, staged/unstaged changes, and unpushed commits for **all repos** defined in the project configuration.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-04-verify.md

@@ -34,7 +34,7 @@ Git cleanup summary report including:
 ### 4.1 Final Git Status (All Repos)
 
 ```bash
-.pennyfarthing/scripts/git/git-status-all.sh
+pf git status
 ```
 
 Expected: Clean working directory in all repos, or only intentionally skipped files.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-05-complete.md

@@ -68,7 +68,7 @@ To run git-cleanup again:
 Or for a quick status check across all repos:
 
 ```bash
-.pennyfarthing/scripts/git/git-status-all.sh
+pf git status
 ```
 
 ---

package/pennyfarthing-dist/workflows/review-tandem.yaml

@@ -0,0 +1,65 @@
+# Review Tandem Workflow - TDD with Focused Architectural Review
+#
+# When to use: Best for stories that primarily need architectural review during
+# the review phase. Use this for large refactors (10+ pts), cross-cutting
+# infrastructure changes, or stories where an architect audit catches issues
+# that a standard code review might miss.
+#
+# Tandem pairings:
+#   - REVIEW phase: Reviewer + Architect (file-watch) — Architect provides
+#     focused architectural audit alongside standard code review
+#
+# Compared to base tdd: Same phase flow, but adds architect consultation
+# during review only. Lighter than tdd-tandem (no tandem on red/green phases).
+#
+# Flow: SM → TEA → Dev → Reviewer (+Architect) → SM
+
+workflow:
+  name: review-tandem
+  description: TDD with tandem architect consultation on review phase
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        file: gates/tests-fail
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        file: gates/tests-pass
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, architecture validated
+      tandem:
+        partner: architect
+        scope: file-watch
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [review-tandem, tandem]
+    points:
+      min: 8

package/pennyfarthing-dist/workflows/tdd-tandem.yaml

@@ -1,14 +1,22 @@
 # TDD Tandem Workflow - TDD with Full Tandem Chain
-# Extends standard TDD with tandem observers on every phase:
-#   - Architect backseats TEA during red phase
-#   - TEA backseats Dev during green phase
-#   - PM backseats Reviewer during review phase
 #
-# Flow: SM → TEA (+Architect) → Dev (+TEA) → Reviewer (+PM) → SM
+# When to use: Best for 5+ point feature stories where architectural alignment
+# during implementation provides high value. Use this instead of base tdd when
+# the story involves cross-cutting concerns, new patterns, or complex integrations.
+#
+# Tandem pairings:
+#   - RED phase: TEA + Architect (file-watch) — Architect reviews test strategy
+#   - GREEN phase: Dev + Architect (file-watch) — Architect guides implementation patterns
+#   - REVIEW phase: Reviewer + PM (file-watch) — PM validates business requirements
+#
+# Compared to base tdd: Adds tandem observers on every working phase.
+# The extra context from partner agents helps catch architectural drift early.
+#
+# Flow: SM → TEA (+Architect) → Dev (+Architect) → Reviewer (+PM) → SM
 
 workflow:
   name: tdd-tandem
-  description: TDD with full tandem chain across all phases
+  description: TDD with full tandem chain — architect and PM consultation across phases
   version: "2.0.0"
 
   phases:
@@ -37,7 +45,7 @@ workflow:
         type: tests_pass
         condition: All tests passing, no skipped tests
       tandem:
-        partner: tea
+        partner: architect
         scope: file-watch
 
     - name: review
@@ -60,5 +68,5 @@ workflow:
   triggers:
     tags: [tandem]
     points:
-      min: 3
+      min: 5
     default: false

package/pennyfarthing_scripts/CLAUDE.md

@@ -12,8 +12,9 @@ Python Click CLI for Pennyfarthing. Entry point: `pennyfarthing_scripts/cli.py`.
 | `pf bc` | Panel focus and layout management | `bc/cli.py` |
 | `pf validate` | Project validators | `validate/cli.py` |
 | `pf agent` | Agent session management | `cli.py` (inline) |
-| `pf workflow` | Workflow state and phase management | `cli.py` (inline) |
+| `pf workflow` | Workflow state and phase management | `workflow/cli.py` |
 | `pf bikerack` | BikeRack dashboard launcher | `bikerack/cli.py` |
+| `pf git` | Repository operations (status, branches, worktree, hooks) | `git_group/cli.py` |
 | `pf debug` | Analysis tools (hotspots, deadcode, healthscore) | `cli.py` (inline group) |
 
 ### Sugar Shortcuts
@@ -139,9 +140,17 @@ Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--qui
 
 | Command | Description | Source |
 |---------|-------------|--------|
-| `pf workflow check` | Current workflow state | `workflow.py` |
-| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow.py` |
-| `pf workflow handoff AGENT` | Emit handoff marker | `cli.py` (inline) |
+| `pf workflow check [--json]` | Current workflow state | `workflow/cli.py` |
+| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow/cli.py` |
+| `pf workflow handoff AGENT` | Emit handoff marker | `workflow/cli.py` |
+| `pf workflow type WORKFLOW` | Get workflow type (phased/stepped/procedural) | `workflow/cli.py` |
+| `pf workflow list` | List all available workflows | `workflow/cli.py` |
+| `pf workflow show [NAME]` | Show workflow details | `workflow/cli.py` |
+| `pf workflow start NAME [--mode M]` | Start stepped workflow | `workflow/cli.py` |
+| `pf workflow resume [NAME]` | Resume interrupted workflow | `workflow/cli.py` |
+| `pf workflow status [NAME]` | Show stepped workflow progress | `workflow/cli.py` |
+| `pf workflow fix-phase ID PHASE [--dry-run]` | Repair session phase | `workflow/cli.py` |
+| `pf workflow complete-step [NAME] [--step N]` | Complete current step | `workflow/cli.py` |
 
 ## pf bikerack
 
@@ -151,6 +160,19 @@ Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--qui
 | `pf bikerack stop` | Stop running instance | `bikerack/cli.py` |
 | `pf bikerack status` | Show running state | `bikerack/cli.py` |
 
+## pf git
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf git status [--brief]` | Check git status of all repos | `git/status_all.py` |
+| `pf git branches BRANCH [--repos all\|api\|ui]` | Create feature branches | `git/create_branches.py` |
+| `pf git cleanup` | Start git-cleanup workflow | `git_group/cli.py` |
+| `pf git worktree create NAME BRANCH` | Create worktree(s) | `git/worktree.py` |
+| `pf git worktree remove NAME` | Remove worktree | `git/worktree.py` |
+| `pf git worktree list` | List active worktrees | `git/worktree.py` |
+| `pf git worktree status` | Show worktree status | `git/worktree.py` |
+| `pf git install-hooks` | Install git hooks with .d/ dispatcher | `git/hooks_installer.py` |
+
 ## pf debug
 
 | Command | Description | Source |

package/pennyfarthing_scripts/bc/cli.py

@@ -34,8 +34,8 @@ from pennyfarthing_scripts.bc.focus import (
 def _get_current_layout() -> dict | None:
     """Fetch the current layout from a running Cyclist or BikeRack server.
 
-    Checks .bikerack-port first, then .cyclist-port, and fetches the
-    appropriate layout endpoint.
+    Reads .wheelhub-port (shared by both Cyclist and BikeRack) and fetches
+    the layout endpoint.
 
     Returns:
         Layout dict, or None if no server is running or fetch fails.
@@ -44,10 +44,8 @@ def _get_current_layout() -> dict | None:
 
     root = _get_root()
 
-    # Try BikeRack first (bikerack-layout), then Cyclist (layout)
     candidates = [
-        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
-        (root / ".cyclist-port", "/api/settings/bikerack-layout"),
+        (root / ".wheelhub-port", "/api/settings/bikerack-layout"),
     ]
 
     for port_file, endpoint in candidates:

package/pennyfarthing_scripts/bikerack/background_panel.py

@@ -6,12 +6,13 @@ list with status indicators (running, completed, failed).
 
 from __future__ import annotations
 
+import time
 from typing import Any
 
 from rich.console import Group
 from rich.text import Text
 
-from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel, format_duration
 
 
 class BackgroundPanel(BasePanel):
@@ -25,12 +26,62 @@ class BackgroundPanel(BasePanel):
     panel_name: str = "Background"
     icon: str = PANEL_ICONS["background"][0]
 
+    def __init__(self, client=None, **kwargs):
+        super().__init__(client=client, **kwargs)
+        self._timer = None
+
+    def on_mount(self) -> None:
+        """Subscribe to channel and start elapsed timer."""
+        super().on_mount()
+        self._timer = self.set_interval(1, self._tick)
+
+    def on_unmount(self) -> None:
+        """Stop timer and cleanup."""
+        if self._timer is not None:
+            self._timer.stop()
+        super().on_unmount()
+
+    def _tick(self) -> None:
+        """Re-render every second to update elapsed times."""
+        if self._last_payload is not None:
+            rendered = self.render_panel(self._last_payload)
+            try:
+                self.update(rendered)
+            except Exception:
+                pass
+
     def render_panel(self, payload: dict[str, Any]) -> Any:
         """Render background task data from WebSocket payload."""
         tasks = payload.get("tasks", [])
         if not isinstance(tasks, list) or not tasks:
             return Text("No background tasks", style="dim italic")
 
+        running = 0
+        done = 0
+        failed = 0
+        for task in tasks:
+            if not isinstance(task, dict):
+                continue
+            if task.get("completedAt") is not None:
+                if task.get("success"):
+                    done += 1
+                else:
+                    failed += 1
+            else:
+                running += 1
+
+        # Summary header
+        summary = Text()
+        summary.append(f"{running} running", style="yellow")
+        summary.append("  ")
+        summary.append(f"{done} done", style="green")
+        if failed > 0:
+            summary.append("  ")
+            summary.append(f"{failed} failed", style="red")
+
+        separator = Text("─" * 30, style="dim")
+
+        # Task list
         parts: list[Any] = []
         for task in tasks:
             if not isinstance(task, dict):
@@ -40,7 +91,7 @@ class BackgroundPanel(BasePanel):
         if not parts:
             return Text("No background tasks", style="dim italic")
 
-        return Group(*parts)
+        return Group(summary, separator, *parts)
 
 
 def _render_task(task: dict[str, Any]) -> Text:
@@ -48,6 +99,7 @@ def _render_task(task: dict[str, Any]) -> Text:
     description = task.get("description", "Unknown task")
     subagent_type = task.get("subagentType", "")
     completed_at = task.get("completedAt")
+    started_at = task.get("startedAt")
     success = task.get("success")
     result = task.get("result", "")
     error = task.get("error", "")
@@ -60,7 +112,12 @@ def _render_task(task: dict[str, Any]) -> Text:
             line.append(description)
             if subagent_type:
                 line.append(f" [{subagent_type}]", style="dim")
-            line.append(" — done", style="green")
+            # Show duration if timestamps available
+            duration = _calc_duration(started_at, completed_at)
+            if duration:
+                line.append(f" — {duration}", style="green")
+            else:
+                line.append(" — done", style="green")
             if result:
                 line.append(f" ({result})", style="dim green")
         else:
@@ -68,7 +125,11 @@ def _render_task(task: dict[str, Any]) -> Text:
             line.append(description)
             if subagent_type:
                 line.append(f" [{subagent_type}]", style="dim")
-            line.append(" — failed", style="red")
+            duration = _calc_duration(started_at, completed_at)
+            if duration:
+                line.append(f" — {duration}", style="red")
+            else:
+                line.append(" — failed", style="red")
             if error:
                 line.append(f"\n  {error}", style="red")
     else:
@@ -76,6 +137,26 @@ def _render_task(task: dict[str, Any]) -> Text:
         line.append(description)
         if subagent_type:
             line.append(f" [{subagent_type}]", style="dim")
-        line.append(" — running", style="yellow")
+        # Live elapsed time for running tasks
+        if started_at:
+            try:
+                elapsed = time.time() - float(started_at) / 1000  # startedAt is typically ms
+                line.append(f" — {format_duration(elapsed)}", style="yellow")
+            except (ValueError, TypeError):
+                line.append(" — running", style="yellow")
+        else:
+            line.append(" — running", style="yellow")
 
     return line
+
+
+def _calc_duration(started_at, completed_at) -> str:
+    """Calculate duration string from timestamps."""
+    if started_at is None or completed_at is None:
+        return ""
+    try:
+        start = float(started_at) / 1000  # ms to seconds
+        end = float(completed_at) / 1000
+        return format_duration(end - start)
+    except (ValueError, TypeError):
+        return ""

package/pennyfarthing_scripts/bikerack/base_panel.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from typing import Any
 
+from rich.text import Text
 from textual.widgets import Static
 
 # Nerd Font icon registry: panel_name → (nerd_font_icon, ascii_fallback)
@@ -25,6 +26,7 @@ PANEL_ICONS: dict[str, tuple[str, str]] = {
     "debug": ("\uf188", "d"),        # nf-fa-bug
     "settings": ("\uf013", "S"),     # nf-fa-gear
     "tty": ("\uf120", ">"),          # nf-fa-terminal
+    "progress": ("\uf200", "P"),     # nf-fa-pie_chart
 }
 
 
@@ -44,6 +46,66 @@ def get_panel_icon(panel_name: str, use_nerd_font: bool = True) -> str:
     return entry[0] if use_nerd_font else entry[1]
 
 
+def render_progress_bar(percent: int | float, width: int = 20, warn_high: bool = False) -> Text:
+    """Render a Unicode progress bar with color based on percentage.
+
+    Args:
+        percent: Value 0-100.
+        width: Number of bar characters (default 20).
+        warn_high: If True, use red at high values (for resource usage).
+                   If False (default), use blue at 100% (for completion).
+
+    Returns:
+        Rich Text like ``[████████░░░░░░░░░░░░] 22%``
+    """
+    percent = max(0, min(100, int(percent)))
+    filled = round(width * percent / 100)
+    empty = width - filled
+
+    if warn_high:
+        if percent < 50:
+            style = "green"
+        elif percent <= 80:
+            style = "yellow"
+        else:
+            style = "red"
+    else:
+        style = "blue"
+
+    bar = Text()
+    bar.append("[")
+    bar.append("█" * filled, style=style)
+    bar.append("░" * empty, style="dim")
+    bar.append(f"] {percent}%")
+    return bar
+
+
+def format_duration(seconds: int | float) -> str:
+    """Format seconds into human-friendly duration string.
+
+    Returns:
+        ``47s``, ``2m 14s``, ``1h 5m``.
+    """
+    seconds = max(0, int(seconds))
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes, secs = divmod(seconds, 60)
+    if minutes < 60:
+        return f"{minutes}m {secs}s"
+    hours, mins = divmod(minutes, 60)
+    return f"{hours}h {mins}m"
+
+
+def humanize_theme(slug: str) -> str:
+    """Convert a theme slug to a display name.
+
+    ``princess-bride`` → ``Princess Bride``
+    """
+    if not slug:
+        return ""
+    return slug.replace("-", " ").replace("_", " ").title()
+
+
 class BasePanel(Static):
     """Base class for BikeRack TUI panels.