@pennyfarthing/core 8.0.4 → 9.0.0

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

@@ -21,7 +21,7 @@ Never manually edit `sprint/current-sprint.yaml`. Use the scripts below for dete
 Show current sprint status with story counts and points.
 
 <run>
-.pennyfarthing/scripts sprint/sprint-status.sh [filter]
+.pennyfarthing/scripts/sprint/sprint-status.sh [filter]
 </run>
 
 <args>
@@ -31,10 +31,10 @@ Show current sprint status with story counts and points.
 </args>
 
 <example>
-.pennyfarthing/scripts sprint/sprint-status.sh           # All stories
-.pennyfarthing/scripts sprint/sprint-status.sh todo      # Backlog only
-.pennyfarthing/scripts sprint/sprint-status.sh in-progress  # WIP only
-.pennyfarthing/scripts sprint/sprint-status.sh done      # Completed only
+.pennyfarthing/scripts/sprint/sprint-status.sh           # All stories
+.pennyfarthing/scripts/sprint/sprint-status.sh todo      # Backlog only
+.pennyfarthing/scripts/sprint/sprint-status.sh in-progress  # WIP only
+.pennyfarthing/scripts/sprint/sprint-status.sh done      # Completed only
 </example>
 
 <output>
@@ -49,7 +49,7 @@ When filtered, only shows epics with matching stories.
 Show available stories grouped by epic with Jira context.
 
 <run>
-.pennyfarthing/scripts sprint/available-stories.sh
+.pennyfarthing/scripts/sprint/available-stories.sh
 </run>
 
 <output>
@@ -82,7 +82,7 @@ Shows backlog, user selects story, then proceeds to setup.
 #### With story ID: Direct start
 
 <run>
-.pennyfarthing/scripts sprint/check-story.sh <story-id>
+.pennyfarthing/scripts/sprint/check-story.sh <story-id>
 </run>
 
 <args>
@@ -97,14 +97,14 @@ Shows backlog, user selects story, then proceeds to setup.
 </output>
 
 <example>
-.pennyfarthing/scripts sprint/check-story.sh MSSCI-12038
+.pennyfarthing/scripts/sprint/check-story.sh MSSCI-12038
 # Returns: {"type": "story", "available": true, "title": "...", ...}
 </example>
 
 #### With epic ID: Start first available story in epic
 
 <run>
-.pennyfarthing/scripts sprint/check-story.sh <epic-id>
+.pennyfarthing/scripts/sprint/check-story.sh <epic-id>
 </run>
 
 <output>
@@ -113,14 +113,14 @@ Action: Automatically start work on `first_story` if available.
 </output>
 
 <example>
-.pennyfarthing/scripts sprint/check-story.sh MSSCI-11952
+.pennyfarthing/scripts/sprint/check-story.sh MSSCI-11952
 # Returns: {"type": "epic", "first_story": {"id": "MSSCI-11954", ...}, ...}
 </example>
 
 #### With `next`: Auto-select highest priority story
 
 <run>
-.pennyfarthing/scripts sprint/check-story.sh next
+.pennyfarthing/scripts/sprint/check-story.sh next
 </run>
 
 <output>
@@ -129,7 +129,7 @@ Action: Automatically start work on returned story.
 </output>
 
 <example>
-.pennyfarthing/scripts sprint/check-story.sh next
+.pennyfarthing/scripts/sprint/check-story.sh next
 # Returns: {"type": "next", "story": {"id": "MSSCI-11950", "priority": "P1", ...}}
 </example>
 
@@ -140,7 +140,7 @@ Action: Automatically start work on returned story.
 Archive a completed story to the sprint archive file.
 
 <run>
-.pennyfarthing/scripts sprint/archive-story.sh <story-id> [pr-number] [--apply]
+.pennyfarthing/scripts/sprint/archive-story.sh <story-id> [pr-number] [--apply]
 </run>
 
 <args>
@@ -153,10 +153,10 @@ Archive a completed story to the sprint archive file.
 
 <example>
 # Archive only (manual removal needed)
-.pennyfarthing/scripts sprint/archive-story.sh 35-2 368
+.pennyfarthing/scripts/sprint/archive-story.sh 35-2 368
 
 # Archive and remove atomically (recommended)
-.pennyfarthing/scripts sprint/archive-story.sh 35-2 368 --apply
+.pennyfarthing/scripts/sprint/archive-story.sh 35-2 368 --apply
 </example>
 
 <output>
@@ -173,7 +173,7 @@ Archive a completed story to the sprint archive file.
 Initialize a new sprint from template.
 
 <run>
-.pennyfarthing/scripts sprint/new-sprint.sh <yyww> <jira-id> <start> <end> "<goal>"
+.pennyfarthing/scripts/sprint/new-sprint.sh <yyww> <jira-id> <start> <end> "<goal>"
 </run>
 
 <args>
@@ -187,7 +187,7 @@ Initialize a new sprint from template.
 </args>
 
 <example>
-.pennyfarthing/scripts sprint/new-sprint.sh 2605 277 2026-02-03 2026-02-16 "Polish and stabilization"
+.pennyfarthing/scripts/sprint/new-sprint.sh 2605 277 2026-02-03 2026-02-16 "Polish and stabilization"
 </example>
 
 <output>
@@ -205,7 +205,7 @@ Warning: Prompts for confirmation if current sprint is still active.
 Show future work initiatives and epics available for promotion.
 
 <run>
-.pennyfarthing/scripts sprint/list-future.sh [--epic EPIC_ID]
+.pennyfarthing/scripts/sprint/list-future.sh [--epic EPIC_ID]
 </run>
 
 <args>
@@ -229,10 +229,10 @@ With `--epic`:
 
 <example>
 # Show all future work
-.pennyfarthing/scripts sprint/list-future.sh
+.pennyfarthing/scripts/sprint/list-future.sh
 
 # Show details for specific epic
-.pennyfarthing/scripts sprint/list-future.sh --epic epic-55
+.pennyfarthing/scripts/sprint/list-future.sh --epic epic-55
 </example>
 
 ---
@@ -242,7 +242,7 @@ With `--epic`:
 Move an epic from `future.yaml` to `current-sprint.yaml`.
 
 <run>
-.pennyfarthing/scripts sprint/promote-epic.sh <epic-id>
+.pennyfarthing/scripts/sprint/promote-epic.sh <epic-id>
 </run>
 
 <args>
@@ -252,7 +252,7 @@ Move an epic from `future.yaml` to `current-sprint.yaml`.
 </args>
 
 <example>
-.pennyfarthing/scripts sprint/promote-epic.sh epic-41
+.pennyfarthing/scripts/sprint/promote-epic.sh epic-41
 </example>
 
 <output>
@@ -278,7 +278,7 @@ These scripts read sprint YAML without modifying it. Use these instead of direct
 ### Get Story Field
 
 <run>
-.pennyfarthing/scripts sprint/get-story-field.sh <story-id> <field>
+.pennyfarthing/scripts/sprint/get-story-field.sh <story-id> <field>
 </run>
 
 <args>
@@ -289,9 +289,9 @@ These scripts read sprint YAML without modifying it. Use these instead of direct
 </args>
 
 <example>
-.pennyfarthing/scripts sprint/get-story-field.sh 35-2 workflow   # Returns: tdd
-.pennyfarthing/scripts sprint/get-story-field.sh 35-2 jira       # Returns: MSSCI-12345
-.pennyfarthing/scripts sprint/get-story-field.sh 35-2 status     # Returns: in_progress
+.pennyfarthing/scripts/sprint/get-story-field.sh 35-2 workflow   # Returns: tdd
+.pennyfarthing/scripts/sprint/get-story-field.sh 35-2 jira       # Returns: MSSCI-12345
+.pennyfarthing/scripts/sprint/get-story-field.sh 35-2 status     # Returns: in_progress
 </example>
 
 <output>
@@ -303,7 +303,7 @@ Field value or "null" if not found. Common fields: `workflow`, `status`, `jira`,
 ### Get Epic Field
 
 <run>
-.pennyfarthing/scripts sprint/get-epic-field.sh <epic-id> <field>
+.pennyfarthing/scripts/sprint/get-epic-field.sh <epic-id> <field>
 </run>
 
 <args>
@@ -314,8 +314,8 @@ Field value or "null" if not found. Common fields: `workflow`, `status`, `jira`,
 </args>
 
 <example>
-.pennyfarthing/scripts sprint/get-epic-field.sh epic-35 jira    # Returns: MSSCI-11234
-.pennyfarthing/scripts sprint/get-epic-field.sh 35 title        # Returns: Epic title
+.pennyfarthing/scripts/sprint/get-epic-field.sh epic-35 jira    # Returns: MSSCI-11234
+.pennyfarthing/scripts/sprint/get-epic-field.sh 35 title        # Returns: Epic title
 </example>
 
 <output>
@@ -347,7 +347,7 @@ When `/sprint work` (or `/new-work`) starts a story:
 <agent-activation>
 Load SM persona first:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts" core/agent-session.sh start "sm"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
 ```
 </agent-activation>
 

package/pennyfarthing-dist/workflows/patch.yaml

@@ -0,0 +1,68 @@
+# Patch Mode Workflow - Interrupt-Driven Bug Fix
+# For quick fixes during active story work
+#
+# Story: 74-1
+# Epic: epic-74 (Patch Mode Workflow)
+#
+# Flow: Dev only (no TEA, no review)
+# Use for: Blocking bugs, script errors, path fixes, urgent UI fixes
+#
+# Key difference from trivial:
+# - Branches from FEATURE branch, not develop
+# - Merges back to FEATURE branch
+# - Preserves and restores workflow state
+# - Supports nested patches (stack-based)
+
+workflow:
+  name: patch
+  description: Interrupt-driven bug fix during active story work
+  version: "1.0.0"
+
+  # Patch mode is NOT a full workflow - it's an interrupt
+  # It doesn't have phases in the traditional sense
+  type: interrupt
+
+  phases:
+    - name: fix
+      agent: dev
+      description: Fix the blocking issue
+      output: [fix_commit]
+      gate:
+        type: manual
+        condition: Fix verified working
+
+  # Branch naming
+  branch:
+    prefix: "patch/"
+    format: "{prefix}{description}-{timestamp}"
+
+  # Commit format
+  commit:
+    format: "fix(patch): {description} [from:{story_id}]"
+    coauthor: true
+
+  # State management
+  state:
+    file: ".session/patch-stack.yaml"
+    preserved_fields:
+      - story_id
+      - workflow
+      - phase
+      - agent
+      - feature_branch
+
+  # Integration
+  tirepump:
+    auto_restore: true
+    handoff_on_complete: true
+
+  triggers:
+    # Manual triggers
+    commands:
+      - "/patch"
+      - "/fix-blocker"
+    # Automatic triggers (future)
+    # error_patterns:
+    #   - "No such file or directory"
+    #   - "ModuleNotFoundError"
+    #   - "command not found"

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