@pennyfarthing/core 10.1.0 → 10.3.0

package/pennyfarthing-dist/workflows/project-context/workflow.yaml

@@ -15,8 +15,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/generate-project-context.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/generate-project-context.md
 
   # Agent assignment (customize as needed)
   agent: architect

package/pennyfarthing-dist/workflows/quick-dev/workflow.yaml

@@ -15,8 +15,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/quick-dev.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/quick-dev.md
 
   # Agent assignment (customize as needed)
   agent: architect

package/pennyfarthing-dist/workflows/research/workflow.yaml

@@ -23,8 +23,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/research.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/research.md
     research_type: ""
     research_topic: ""
     research_goals: ""

package/pennyfarthing-dist/workflows/retrospective/workflow.yaml

@@ -38,7 +38,7 @@ workflow:
   variables:
     project_root: .
     config_source: "./_bmad/bmm/config.yaml"
-    planning_artifacts: ./artifacts/planning
+    planning_artifacts: sprint/planning/
     implementation_artifacts: ./artifacts
     sprint_status_file: ./artifacts/sprint-status.yaml
     story_directory: ./artifacts/stories

package/pennyfarthing-dist/workflows/sprint-planning/workflow.yaml

@@ -15,12 +15,12 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
+    planning_artifacts: sprint/planning/
     implementation_artifacts: ./artifacts
     epics_location: ./artifacts
     epics_pattern: "epic*.md"
-    status_file: artifacts/sprint-status.yaml
-    output_file: artifacts/sprint-status.yaml
+    status_file: sprint/planning/sprint-status.yaml
+    output_file: sprint/planning/sprint-status.yaml
 
   # Agent assignment - SM handles sprint planning
   agent: sm

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

@@ -0,0 +1,61 @@
+# 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
+
+workflow:
+  name: tdd-tandem
+  description: TDD with full tandem chain across all phases
+  version: "2.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:
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+      tandem:
+        partner: architect
+        scope: file-watch
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+      tandem:
+        partner: tea
+        scope: file-watch
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, no blocking issues
+      tandem:
+        partner: pm
+        scope: file-watch
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [tandem]
+    points:
+      min: 3
+    default: false

package/pennyfarthing-dist/workflows/ux-design/workflow.yaml

@@ -29,8 +29,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/ux-design-specification.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/ux-design-specification.md
 
   # Agent assignment - UX Designer for visual design workflow
   agent: ux-designer

package/pennyfarthing_scripts/bellmode_hook.py

@@ -1,30 +1,23 @@
 #!/usr/bin/env python3
 """
-Bell Mode PostToolUse Hook (Python)
+PostToolUse Hook — Bell Mode + Tandem Injection (Python)
 
-This hook is called by Claude Code after each tool execution.
-When bell mode is enabled and there are queued messages, it returns
-the first queued message as additionalContext to be injected into
-Claude's next API call.
+Called by Claude Code after each tool execution. Handles two independent
+injection systems:
 
-Configuration files:
-  .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
-  .pennyfarthing/bell-queue.json - [{"text": "...", "images": [...]}, ...]
+1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
+   is running and bell_mode is enabled. In CLI sessions this is a no-op.
+2. Tandem observations (always active) — injects backseat agent observations
+   when tandem observation files exist. No configuration required.
 
-Output format (when injecting):
-  {
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "User feedback: <message>"
-    }
-  }
-
-Output when disabled or queue empty: (nothing - exit 0)
+Bell queue takes precedence: if a queued message exists, tandem is
+deferred to the next hook invocation.
 
 Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
 """
 
 import json
+import re
 import sys
 from pathlib import Path
 
@@ -32,12 +25,13 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    find_project_root,
-    get_cyclist_port,
-    send_to_cyclist,
-    output_hook_response,
+    CYCLIST_PORT_FILE,
     HookResponse,
+    find_project_root,
     is_bell_mode_enabled,
+    output_hook_response,
+    read_port_file,
+    send_to_cyclist,
 )
 
 
@@ -106,8 +100,170 @@ def notify_cyclist(project_root: Path, message_text: str) -> None:
         pass
 
 
+# =============================================================================
+# Tandem Observation Injection (Story 95-7 / MSSCI-14672)
+# =============================================================================
+# Stubs for tandem observation injection. Dev will implement.
+
+
+def read_tandem_observations(project_root: Path) -> list[Path]:
+    """Find tandem observation files in .session/ directory.
+
+    Looks for files matching .session/*-tandem-*.md pattern.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of Path objects for tandem observation files
+    """
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return []
+    return sorted(session_dir.glob("*-tandem-*.md"))
+
+
+def get_latest_observation(file_content: str) -> dict | None:
+    """Extract the latest observation entry from a tandem observation file.
+
+    Parses the markdown format to extract the most recent ## [HH:MM] Observation
+    block, including the observer persona name from the file header.
+
+    Args:
+        file_content: Full text content of the tandem observation file
+
+    Returns:
+        Dict with 'persona' and 'text' keys, or None if no observations found
+    """
+    # Extract persona from header: **Observer:** agent (Persona Name)
+    persona_match = re.search(r"\*\*Observer:\*\*\s*\w+\s*\(([^)]+)\)", file_content)
+    persona = persona_match.group(1) if persona_match else "Unknown"
+
+    # Split on observation headers: ## [HH:MM] Observation
+    entries = re.split(r"## \[\d{1,2}:\d{2}\] Observation\n", file_content)
+    if len(entries) < 2:
+        return None
+
+    # Last entry is the most recent observation
+    last_entry = entries[-1].strip()
+    # Remove trailing --- separator
+    last_entry = re.sub(r"\n---\s*$", "", last_entry).strip()
+    # Remove the **Trigger:** line
+    lines = last_entry.split("\n")
+    text_lines = [line for line in lines if not line.startswith("**Trigger:**")]
+    text = "\n".join(text_lines).strip()
+
+    if not text:
+        return None
+
+    return {"persona": persona, "text": text}
+
+
+def format_tandem_message(persona_name: str, observation_text: str) -> str:
+    """Format a tandem observation as a bell mode injection message.
+
+    Args:
+        persona_name: The backseat agent's persona name
+        observation_text: The observation summary text
+
+    Returns:
+        Formatted string: [Tandem] {persona_name}: {observation_text}
+    """
+    return f"[Tandem] {persona_name}: {observation_text}"
+
+
+def get_tandem_mtime(project_root: Path, agent: str) -> float:
+    """Read the last-checked mtime for a tandem agent's observation file.
+
+    Args:
+        project_root: Project root directory
+        agent: Agent name (e.g. 'reviewer', 'tea')
+
+    Returns:
+        Last-checked mtime as float, or 0.0 if no sidecar exists
+    """
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    if not sidecar.exists():
+        return 0.0
+    try:
+        return float(sidecar.read_text().strip())
+    except (ValueError, OSError):
+        return 0.0
+
+
+def save_tandem_mtime(project_root: Path, agent: str, mtime: float) -> None:
+    """Save the mtime for a tandem agent's observation file.
+
+    Writes to .session/.tandem-mtime-{agent} sidecar file.
+
+    Args:
+        project_root: Project root directory
+        agent: Agent name (e.g. 'reviewer', 'tea')
+        mtime: The mtime value to save
+    """
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    try:
+        sidecar.write_text(str(mtime))
+    except OSError:
+        pass
+
+
+def check_tandem_files(project_root: Path) -> list[dict]:
+    """Check for new tandem observations and return injection messages.
+
+    Main entry point for tandem injection in the PostToolUse hook.
+    Always active — no configuration required. The presence of tandem
+    observation files in .session/ is the only signal needed.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of dicts with 'agent', 'message' keys for each new observation
+    """
+    tandem_files = read_tandem_observations(project_root)
+    if not tandem_files:
+        return []
+
+    results = []
+    for obs_file in tandem_files:
+        # Extract agent name from filename: *-tandem-{agent}.md
+        agent_match = re.search(r"-tandem-(\w+)\.md$", obs_file.name)
+        if not agent_match:
+            continue
+        agent = agent_match.group(1)
+
+        # Compare mtime
+        try:
+            file_mtime = obs_file.stat().st_mtime
+        except OSError:
+            continue
+        saved_mtime = get_tandem_mtime(project_root, agent)
+        if file_mtime == saved_mtime:
+            continue
+
+        # Read and parse
+        try:
+            content = obs_file.read_text()
+        except OSError:
+            continue
+        obs = get_latest_observation(content)
+        if not obs:
+            # Update mtime even for unparseable files to avoid re-checking
+            save_tandem_mtime(project_root, agent, file_mtime)
+            continue
+
+        message = format_tandem_message(obs["persona"], obs["text"])
+        results.append({"agent": agent, "message": message})
+
+        # Update mtime sidecar
+        save_tandem_mtime(project_root, agent, file_mtime)
+
+    return results
+
+
 def main() -> None:
-    """Main entry point for PostToolUse bell mode hook."""
+    """Main entry point for PostToolUse hook."""
     try:
         # Read and discard stdin (required by hook protocol)
         sys.stdin.read()
@@ -117,35 +273,34 @@ def main() -> None:
         if not project_root:
             sys.exit(0)
 
-        # Check if bell mode is enabled
-        if not is_bell_mode_enabled(project_root):
-            sys.exit(0)
-
-        # Read queue
-        queue = read_bell_queue(project_root)
-        if not queue:
-            sys.exit(0)
-
-        # Get first message
-        first_message = queue[0]
-        message_text = first_message.get("text", "")
-        if not message_text:
-            sys.exit(0)
-
-        # Output hook response with additionalContext
-        output_hook_response(HookResponse(
-            event_name="PostToolUse",
-            additional_context=f"User feedback: {message_text}",
-        ))
-
-        # Dequeue message and notify Cyclist (in background-ish - after output)
-        dequeue_message(project_root)
-        notify_cyclist(project_root, message_text)
+        # --- Bell queue (Cyclist only, requires bell_mode: true) ---
+        # Takes precedence over tandem when active.
+        is_cyclist = read_port_file(CYCLIST_PORT_FILE, project_root) is not None
+        if is_cyclist and is_bell_mode_enabled(project_root):
+            queue = read_bell_queue(project_root)
+            if queue:
+                first_message = queue[0]
+                message_text = first_message.get("text", "")
+                if message_text:
+                    output_hook_response(HookResponse(
+                        event_name="PostToolUse",
+                        additional_context=f"User feedback: {message_text}",
+                    ))
+                    dequeue_message(project_root)
+                    notify_cyclist(project_root, message_text)
+                    sys.exit(0)
+
+        # --- Tandem observations (always active, no config required) ---
+        tandem_results = check_tandem_files(project_root)
+        if tandem_results:
+            output_hook_response(HookResponse(
+                event_name="PostToolUse",
+                additional_context=tandem_results[0]["message"],
+            ))
 
         sys.exit(0)
 
     except Exception as e:
-        # On error, exit silently
         print(f"[bellmode-hook] Error: {e}", file=sys.stderr)
         sys.exit(0)
 

package/pennyfarthing_scripts/bikerack/__init__.py

@@ -0,0 +1,36 @@
+"""BikeRack Mode — Decoupled WheelHub launcher for CLI-first developers.
+
+Story 101-5: BikeRack launcher CLI (pf bikerack start/stop/status)
+"""
+
+from pennyfarthing_scripts.bikerack.launcher import (
+    build_otel_env,
+    cleanup_files,
+    exec_claude,
+    get_status,
+    is_already_running,
+    is_process_alive,
+    poll_for_port_file,
+    read_pid_file,
+    read_port_file,
+    register_cleanup,
+    start_wheelhub,
+    stop_bikerack,
+    write_pid_file,
+)
+
+__all__ = [
+    "build_otel_env",
+    "cleanup_files",
+    "exec_claude",
+    "get_status",
+    "is_already_running",
+    "is_process_alive",
+    "poll_for_port_file",
+    "read_pid_file",
+    "read_port_file",
+    "register_cleanup",
+    "start_wheelhub",
+    "stop_bikerack",
+    "write_pid_file",
+]

package/pennyfarthing_scripts/bikerack/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for python -m pennyfarthing_scripts.bikerack."""
+
+from pennyfarthing_scripts.bikerack.cli import bikerack
+
+bikerack()

package/pennyfarthing_scripts/bikerack/cli.py

@@ -0,0 +1,148 @@
+"""BikeRack CLI — Click-based CLI for bikerack operations.
+
+Usage:
+    pf bikerack [COMMAND]
+
+Commands:
+    start   Start BikeRack mode (default)
+    stop    Stop running BikeRack instance
+    status  Show running state
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def bikerack(ctx):
+    """BikeRack Mode — Decoupled WheelHub dashboard launcher.
+
+    \b
+    Commands:
+      start   - Start WheelHub + Claude CLI (default)
+      stop    - Stop running BikeRack instance
+      status  - Show running state (PID, port, uptime)
+    """
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(start)
+
+
+@bikerack.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory (where .pennyfarthing/ lives). Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def start(project_dir):
+    """Start BikeRack mode.
+
+    Starts WheelHub in background, waits for readiness,
+    sets OTEL env vars, and execs Claude CLI.
+    """
+    from pennyfarthing_scripts.bikerack.launcher import (
+        build_otel_env,
+        exec_claude,
+        is_already_running,
+        poll_for_port_file,
+        register_cleanup,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    if project_dir:
+        project_dir = Path(project_dir)
+    elif os.environ.get("CYCLIST_PROJECT_DIR"):
+        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
+    else:
+        project_dir = Path.cwd()
+
+    running, pid, port = is_already_running(project_dir)
+    if running:
+        click.echo(
+            f"Error: BikeRack is already running (PID {pid}, port {port})",
+            err=True,
+        )
+        click.echo("Use 'pf bikerack stop' to stop it.", err=True)
+        sys.exit(2)
+
+    click.echo("Starting BikeRack mode...")
+    try:
+        proc = start_wheelhub(project_dir)
+        write_pid_file(project_dir, proc.pid)
+
+        port = poll_for_port_file(project_dir)
+        click.echo(f"WheelHub listening on http://localhost:{port}")
+
+        otel_env = build_otel_env(port)
+        click.echo("Setting OTEL environment variables...")
+
+        register_cleanup(project_dir, proc.pid)
+
+        click.echo(f"Dashboard: http://localhost:{port}/bikerack")
+        click.echo("Starting Claude CLI...")
+        exec_claude(otel_env, project_dir)
+    except TimeoutError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@bikerack.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def stop(project_dir):
+    """Stop running BikeRack instance."""
+    from pennyfarthing_scripts.bikerack.launcher import stop_bikerack
+
+    if project_dir:
+        project_dir = Path(project_dir)
+    elif os.environ.get("CYCLIST_PROJECT_DIR"):
+        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
+    else:
+        project_dir = Path.cwd()
+    result = stop_bikerack(project_dir)
+
+    if result["success"]:
+        click.echo(result["message"])
+    else:
+        click.echo(result["message"], err=True)
+        sys.exit(1)
+
+
+@bikerack.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def status(project_dir):
+    """Show BikeRack running state."""
+    from pennyfarthing_scripts.bikerack.launcher import get_status
+
+    if project_dir:
+        project_dir = Path(project_dir)
+    elif os.environ.get("CYCLIST_PROJECT_DIR"):
+        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
+    else:
+        project_dir = Path.cwd()
+    result = get_status(project_dir)
+
+    if result["running"]:
+        click.echo("BikeRack is running")
+        click.echo(f"  PID: {result['pid']}")
+        click.echo(f"  Port: {result['port']}")
+        click.echo(f"  Dashboard: {result['dashboard']}")
+    else:
+        click.echo("BikeRack is not running")