@pennyfarthing/core 10.2.0 → 10.3.1

package/pennyfarthing-dist/workflows/architecture.yaml

@@ -26,8 +26,8 @@ workflow:
 
   # Variables available in step files
   variables:
-    output_file: planning-artifacts/architecture.md
-    planning_artifacts: planning-artifacts
+    output_file: sprint/planning/architecture.md
+    planning_artifacts: sprint/planning/
     input_required:
       - prd
 

package/pennyfarthing-dist/workflows/epics-and-stories/workflow.yaml

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

package/pennyfarthing-dist/workflows/implementation-readiness/workflow.yaml

@@ -28,8 +28,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/implementation-readiness-report.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/implementation-readiness-report.md
 
   # Agent assignment - PM/SM role for adversarial review
   agent: sm

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

@@ -22,8 +22,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/prd.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/prd.md
 
   # Gates - pause for user approval at key decision points
   gates:

package/pennyfarthing-dist/workflows/product-brief/workflow.yaml

@@ -16,8 +16,8 @@ workflow:
   # Variables available in step files
   variables:
     project_root: .
-    planning_artifacts: ./artifacts
-    output_file: artifacts/product-brief.md
+    planning_artifacts: sprint/planning/
+    output_file: sprint/planning/product-brief.md
 
   # Template for product brief output
   template: ./templates/product-brief.template.md

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/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

@@ -150,7 +150,7 @@ def get_latest_observation(file_content: str) -> dict | None:
     last_entry = re.sub(r"\n---\s*$", "", last_entry).strip()
     # Remove the **Trigger:** line
     lines = last_entry.split("\n")
-    text_lines = [l for l in lines if not l.startswith("**Trigger:**")]
+    text_lines = [line for line in lines if not line.startswith("**Trigger:**")]
     text = "\n".join(text_lines).strip()
 
     if not text:

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")

package/pennyfarthing_scripts/bikerack/launcher.py

@@ -0,0 +1,181 @@
+"""BikeRack launcher — core lifecycle functions.
+
+Story 101-5: BikeRack launcher CLI (pf bikerack start/stop/status)
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+from typing import NoReturn
+
+
+def is_process_alive(pid: int) -> bool:
+    """Check if a process with given PID is alive."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def cleanup_files(project_dir: Path) -> None:
+    """Clean up .bikerack-port and .bikerack-pid files."""
+    for name in (".bikerack-port", ".bikerack-pid"):
+        try:
+            (project_dir / name).unlink()
+        except FileNotFoundError:
+            pass
+
+
+def read_port_file(project_dir: Path) -> int | None:
+    """Read port from .bikerack-port file. Returns None if not found."""
+    try:
+        return int((project_dir / ".bikerack-port").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def read_pid_file(project_dir: Path) -> int | None:
+    """Read PID from .bikerack-pid file. Returns None if not found."""
+    try:
+        return int((project_dir / ".bikerack-pid").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def write_pid_file(project_dir: Path, pid: int) -> None:
+    """Write .bikerack-pid file."""
+    (project_dir / ".bikerack-pid").write_text(str(pid))
+
+
+def build_otel_env(port: int) -> dict[str, str]:
+    """Build the 5 OTEL environment variables from discovered port (Rule 5)."""
+    return {
+        "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
+        "OTEL_LOGS_EXPORTER": "otlp",
+        "OTEL_METRICS_EXPORTER": "otlp",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
+        "OTEL_EXPORTER_OTLP_ENDPOINT": f"http://localhost:{port}",
+    }
+
+
+def _find_framework_dir() -> Path:
+    """Locate the pennyfarthing framework root from this package's location."""
+    # pennyfarthing_scripts/bikerack/launcher.py -> pennyfarthing/
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def start_wheelhub(project_dir: Path) -> subprocess.Popen:
+    """Start WheelHub server in background with IS_BIKERACK=1."""
+    framework_dir = _find_framework_dir()
+    bikerack_entry = framework_dir / "packages" / "cyclist" / "dist" / "bikerack.js"
+
+    env = os.environ.copy()
+    env["IS_BIKERACK"] = "1"
+    env["CYCLIST_PROJECT_DIR"] = str(project_dir)
+
+    return subprocess.Popen(
+        ["node", str(bikerack_entry)],
+        env=env,
+        cwd=str(project_dir),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+def poll_for_port_file(
+    project_dir: Path, timeout: float = 5.0, interval: float = 0.1
+) -> int:
+    """Poll for .bikerack-port file, return port number."""
+    port_file = project_dir / ".bikerack-port"
+    deadline = time.monotonic() + timeout
+
+    while True:
+        if port_file.exists():
+            return int(port_file.read_text().strip())
+        if time.monotonic() >= deadline:
+            raise TimeoutError(
+                f"Timed out waiting for {port_file} after {timeout}s"
+            )
+        time.sleep(interval)
+
+
+def register_cleanup(project_dir: Path, pid: int) -> None:
+    """Register atexit handler to kill WheelHub and clean up files (Rule 8)."""
+
+    def _cleanup(project_dir: Path, pid: int) -> None:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except (ProcessLookupError, OSError):
+            pass
+        cleanup_files(project_dir)
+
+    atexit.register(_cleanup, project_dir, pid)
+
+
+def exec_claude(otel_env: dict[str, str], project_dir: Path | None = None) -> NoReturn:
+    """Replace current process with Claude CLI using os.execvpe (CE-4)."""
+    env = os.environ.copy()
+    env.update(otel_env)
+    if project_dir:
+        os.chdir(project_dir)
+    os.execvpe("claude", ["claude"], env)
+
+
+def is_already_running(project_dir: Path) -> tuple[bool, int | None, int | None]:
+    """Check if BikeRack is already running.
+
+    Returns (is_running, pid_or_none, port_or_none).
+    Cleans up stale files if PID is dead.
+    """
+    pid = read_pid_file(project_dir)
+    port = read_port_file(project_dir)
+
+    if pid is None or port is None:
+        return (False, None, None)
+
+    if is_process_alive(pid):
+        return (True, pid, port)
+
+    cleanup_files(project_dir)
+    return (False, None, None)
+
+
+def stop_bikerack(project_dir: Path) -> dict:
+    """Stop running BikeRack instance. Returns {success, pid, message}."""
+    pid = read_pid_file(project_dir)
+
+    if pid is None:
+        return {"success": False, "message": "BikeRack is not running"}
+
+    if not is_process_alive(pid):
+        cleanup_files(project_dir)
+        return {"success": False, "message": "BikeRack is not running (stale PID)"}
+
+    os.kill(pid, signal.SIGTERM)
+    cleanup_files(project_dir)
+    return {"success": True, "pid": pid, "message": f"Stopped BikeRack (PID {pid})"}
+
+
+def get_status(project_dir: Path) -> dict:
+    """Get BikeRack running status. Returns {running, pid, port, dashboard}."""
+    pid = read_pid_file(project_dir)
+    port = read_port_file(project_dir)
+
+    if pid is None or port is None:
+        return {"running": False}
+
+    if not is_process_alive(pid):
+        return {"running": False}
+
+    return {
+        "running": True,
+        "pid": pid,
+        "port": port,
+        "dashboard": f"http://localhost:{port}/bikerack",
+    }

package/pennyfarthing_scripts/cli.py

@@ -65,6 +65,11 @@ from pennyfarthing_scripts.validate.cli import validate  # noqa: E402
 
 cli.add_command(validate)
 
+# Import and register bikerack group
+from pennyfarthing_scripts.bikerack.cli import bikerack  # noqa: E402
+
+cli.add_command(bikerack)
+
 
 @cli.group()
 def agent():