@pennyfarthing/core 10.1.0 → 10.2.0

package/pennyfarthing-dist/skills/sprint/skill.md

@@ -293,7 +293,7 @@ pf sprint story add <epic-id> "<title>" <points> [options]
 | `points` | Yes | Story points (1, 2, 3, 5, 8) |
 | `--type` | No | Story type: feature, bug, chore, refactor (default: feature) |
 | `--priority` | No | Priority: P0, P1, P2, P3 (default: P1) |
-| `--workflow` | No | Workflow: tdd, trivial, bdd (default: tdd) |
+| `--workflow` | No | Workflow: tdd, tdd-tandem, trivial, bdd, bdd-tandem (default: tdd) |
 | `--jira` | No | Jira issue key |
 </args>
 
@@ -399,6 +399,28 @@ pf sprint story claim <story-id>
 
 ---
 
+### `/sprint story assign <story-id> <assignee>`
+
+Assign a Jira story to a user. Shortcut for `/jira assign`.
+
+<run>
+pf jira assign <story-id> <assignee>
+</run>
+
+<args>
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `story-id` | Yes | Jira key (e.g., `MSSCI-14552`) |
+| `assignee` | Yes | Email or GitHub username (e.g., `keith.avery@1898andco.io`, `slabgorb`) |
+</args>
+
+<example>
+pf jira assign MSSCI-14552 keith.avery@1898andco.io
+pf jira assign MSSCI-14552 slabgorb
+</example>
+
+---
+
 ### `/sprint epic add <epic-id> <title> [options]`
 
 Add a new epic to the current sprint.
@@ -696,7 +718,7 @@ All gates must pass before handoff:
 | Sprint name | `"TO Sprint YYWW"` (e.g., "TO Sprint 2604") |
 | Story IDs | Jira keys `MSSCI-XXXXX` |
 | Status | `backlog`, `ready`, `in_progress`, `done` |
-| Workflow | `tdd`, `trivial`, `agent-docs`, `bdd` |
+| Workflow | `tdd`, `tdd-tandem`, `trivial`, `agent-docs`, `bdd`, `bdd-tandem` |
 | Priority | `P0`, `P1`, `P2`, `P3` |
 | in_sprint | `true`, `false` - Jira sprint membership |
 
@@ -761,6 +783,7 @@ For Jira integration, see `/jira` skill prerequisites.
 | `/sprint story template` | `pf sprint story template` |
 | `/sprint story finish ID` | `pf sprint story finish ID` |
 | `/sprint story claim ID` | `pf sprint story claim ID` |
+| `/sprint story assign ID USER` | `pf jira assign ID USER` |
 | `/sprint epic show ID` | `pf sprint epic show ID` |
 | `/sprint epic field ID FIELD` | `pf sprint epic field ID FIELD` |
 | `/sprint epic add ...` | `pf sprint epic add ...` |

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

@@ -163,6 +163,18 @@ SM → TEA → Dev → Reviewer → SM
 - Dev implements to make tests pass
 - **Triggers:** `types: [feature, enhancement]`, `points.min: 3`
 
+### TDD-Tandem (TDD with full tandem chain)
+
+```
+setup → red (+Architect) → green (+TEA) → review (+PM) → finish
+SM → TEA (+Architect) → Dev (+TEA) → Reviewer (+PM) → SM
+```
+
+- Full tandem chain: every phase has a backseat observer
+- Architect watches test design, TEA watches implementation, PM watches review
+- For high-stakes features needing cross-role visibility
+- **Triggers:** `tags: [tandem]`, `points.min: 3`
+
 ### Trivial (for 1-2 point fixes)
 
 ```
@@ -196,6 +208,17 @@ SM → UX-Designer → TEA → Dev → Reviewer → SM
 - For UI components and user-facing features
 - **Triggers:** `types: [ui, ux, behavior]`, `tags: [bdd, ux-first]`
 
+### BDD-Tandem (BDD with full tandem chain)
+
+```
+setup → design (+Architect) → red → green (+UX-Designer) → review (+PM) → finish
+SM → UX-Designer (+Architect) → TEA → Dev (+UX-Designer) → Reviewer (+PM) → SM
+```
+
+- Full tandem chain: Architect watches design, UX-Designer watches implementation, PM watches review
+- Everyone shares their cake — cross-role visibility at every phase
+- **Triggers:** `tags: [bdd-tandem, tandem, ux-first]`, `points.min: 3`
+
 ### Architecture (stepped workflow)
 
 ```
@@ -341,5 +364,5 @@ workflow:
 For comprehensive documentation on creating stepped workflows, see:
 
 - **[guides/bikelane.md](../../guides/bikelane.md)** - Full BikeLane user guide
-- **[docs/adr/0013-bmad-workflow-import.md](../../docs/adr/0013-bmad-workflow-import.md)** - Technical ADR
+- **ADR-0013: Stepped Workflow Support** - Technical ADR (see `docs/adr/0013-bmad-workflow-import.md` in framework repo)
 - **[pennyfarthing-dist/workflows/architecture.yaml](../../workflows/architecture.yaml)** - Example implementation

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

@@ -0,0 +1,65 @@
+# Architecture Workflow - Migrated from BMAD format
+# Collaborative architectural decision-making with progressive disclosure
+#
+# Flow: Initialize → [Continue?] → Context → Patterns → Components → Interfaces → Risks → Document
+# Use for architectural decisions, system design, and technical planning
+#
+# BMAD Enhancements:
+# - Continuation handler (step-01b) for resuming workflows
+# - A/P/C menus: Advanced Elicitation, Party Mode, Continue
+# - Web search integration for current technology versions
+# - AI agent consistency focus in component and risk steps
+# - Pre-documentation validation checks
+
+workflow:
+  name: architecture
+  description: Collaborative architectural decision facilitation for AI-agent consistency. Produces a decision-focused architecture document optimized for preventing agent conflicts through step-by-step discovery with A/P/C collaboration menus.
+  version: "2.0.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./steps/
+    pattern: step-{nn}-*.md
+    # Note: step-01b-continue.md is loaded conditionally by step-01 when existing workflow detected
+
+  # Variables available in step files
+  variables:
+    project_root: .
+    planning_artifacts: ./artifacts
+    output_file: artifacts/architecture.md
+    input_required:
+      - prd
+
+  # User approval gates - pause for confirmation at key decision points
+  # Steps with A/P/C menus naturally pause; these are the formal gates
+  gates:
+    after_steps: [2, 4, 6]
+    gate_marker: "<!-- GATE -->"
+
+  # Collaboration menus available in steps
+  collaboration:
+    menus:
+      - key: A
+        name: Advanced Elicitation
+        description: Use discovery protocols to develop deeper insights
+      - key: P
+        name: Party Mode
+        description: Bring multiple perspectives to analyze from different angles
+      - key: C
+        name: Continue
+        description: Save content and proceed to next step
+      - key: R
+        name: Revise
+        description: Need to gather more information or make changes
+
+  # Output template
+  template: ./templates/architecture-decision.md
+
+  # Agent assignment
+  agent: architect
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [architecture, design, adr, system-design]
+    tags: [architecture, stepped]

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

@@ -0,0 +1,70 @@
+# 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
+
+workflow:
+  name: bdd-tandem
+  description: BDD with full tandem chain across design, implementation, and review
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: design
+      agent: ux-designer
+      input: [session_file, story_context]
+      output: [design_spec, user_flows, wireframes, behavior_scenarios]
+      gate:
+        type: design_review
+        condition: UX spec defines user flows and acceptance behaviors
+      tandem:
+        partner: architect
+        scope: file-watch
+
+    - name: red
+      agent: tea
+      input: [design_spec, behavior_scenarios, story_context]
+      output: [failing_tests]
+      gate:
+        type: tests_fail
+        condition: Behavior scenarios have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, design_spec, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, UX spec implemented
+      tandem:
+        partner: ux-designer
+        scope: file-watch
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests, design_spec]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, UX requirements met
+      tandem:
+        partner: pm
+        scope: file-watch
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    types: [ui, ux, behavior, component, settings]
+    tags: [bdd-tandem, tandem, ux-first]
+    points:
+      min: 3
+    default: false

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_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 = [l for l in lines if not l.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/brownfield/__init__.py

@@ -6,17 +6,17 @@ Analyzes existing codebases and generates AI-ready documentation.
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,
-    ProjectType,
     DiscoveryResult,
+    ProjectType,
+    detect_architecture_patterns,
     detect_project_type,
     detect_tech_stack,
-    scan_directory_structure,
-    detect_architecture_patterns,
+    discover,
+    generate_ai_guidance_doc,
     generate_project_overview,
-    generate_tech_stack_doc,
     generate_source_tree_doc,
-    generate_ai_guidance_doc,
-    discover,
+    generate_tech_stack_doc,
+    scan_directory_structure,
 )
 
 __all__ = [

package/pennyfarthing_scripts/brownfield/__main__.py

@@ -1,6 +1,7 @@
 """Entry point for python -m pennyfarthing_scripts.brownfield."""
 
 import sys
+
 from pennyfarthing_scripts.brownfield.cli import cli
 
 if __name__ == "__main__":

package/pennyfarthing_scripts/brownfield/cli.py

@@ -12,7 +12,6 @@ import argparse
 import asyncio
 import sys
 from pathlib import Path
-from typing import Any
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,