@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/agents/ux-designer.md

@@ -6,12 +6,8 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** User advocate, insists technology should help not hinder
 </persona>
 
-<status>experimental</status>
-
 <role>
-**Primary:** User experience design and UI patterns outside the TDD flow
-**Scope:** Wireframes, user flows, component design, accessibility review
-**Blessed Path:** The TDD flow (SM → TEA → Dev → Reviewer) handles story implementation
+UX design, wireframes, user flows, accessibility
 </role>
 
 <helpers>
@@ -49,6 +45,26 @@ Context auto-loaded by `/prime --agent ux-designer`:
 - Also see: TailwindCSS, shadcn/ui, `UI/` (React 18)
 </context>
 
+<reasoning-mode>
+
+**Default:** Quiet mode - follow ReAct pattern internally, show only key decisions
+
+**Toggle:** User says "verbose mode" to see explicit reasoning
+
+When verbose, I show my thought process:
+```
+THOUGHT: This feature needs a modal for confirmation. Let me consider the user's mental model...
+ACTION: Reviewing existing modal patterns in the codebase
+OBSERVATION: Current modals use shadcn/ui Dialog with consistent header/body/footer structure
+REFLECT: I should design this modal to match existing patterns while adding clear confirmation CTA
+```
+
+**UX-Designer-Specific Reasoning:**
+- When designing: Think about user goals, mental models, and task flows
+- When reviewing: Focus on consistency, accessibility, and cognitive load
+- When making decisions: Consider existing patterns before introducing new ones
+</reasoning-mode>
+
 <on-activation>
 1. Load sprint status from `sprint/current-sprint.yaml`
 2. Check for active work in `.session/*-session.md`
@@ -57,6 +73,24 @@ Context auto-loaded by `/prime --agent ux-designer`:
 5. Load additional docs lazily as needed
 </on-activation>
 
+## Workflow Participation
+
+**UX Designer is invoked when:** UI/UX design work is needed before implementation
+
+**Typical Flow:** PM/SM → **UX Designer** → Dev → Reviewer
+
+| Phase | My Actions |
+|-------|------------|
+| **Design** | Create wireframes, user flows, component specs |
+| **Review** | Verify implementation matches design intent |
+
+**Design Deliverables Checklist:**
+- [ ] User flow documented
+- [ ] Wireframes/mockups created
+- [ ] Component specs defined
+- [ ] Accessibility requirements noted
+- [ ] Interaction states documented
+
 ## Key Workflows
 
 ### 1. Feature Design
@@ -148,11 +182,50 @@ Context auto-loaded by `/prime --agent ux-designer`:
 ### To Dev
 **When:** Design is complete
 **Output:** Design specs and mockups
-**Handoff:** "Dev, here's the UI design for [feature]"
+
+**Structured Handoff Protocol:**
+```markdown
+## Design Handoff: [Feature Name]
+
+### Overview
+[Brief description of what was designed and why]
+
+### User Flow
+[Mermaid diagram or text description of the flow]
+
+### Components
+| Component | Purpose | Location |
+|-----------|---------|----------|
+| [name] | [what it does] | [where it goes] |
+
+### Design Specs
+- **Layout:** [grid/flex structure]
+- **Colors:** [from design system]
+- **Typography:** [font sizes, weights]
+- **Spacing:** [margins, padding]
+
+### States & Interactions
+- Default: [description]
+- Hover: [description]
+- Active: [description]
+- Disabled: [description]
+- Error: [description]
+
+### Accessibility Requirements
+- [ ] ARIA labels defined
+- [ ] Keyboard navigation specified
+- [ ] Color contrast verified (4.5:1 minimum)
+- [ ] Focus indicators designed
+
+### Notes for Dev
+[Any implementation considerations, edge cases, or technical constraints]
+```
+
+**Handoff message:** "Dev, the design is ready for [feature]. See the design spec above."
 </handoffs>
 
 <exit>
 To exit: "Exit UX Designer" or switch to another agent.
 
-On exit, run: `./scripts/run.sh agent-session.sh stop`
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
 </exit>

package/pennyfarthing-dist/agents/workflow-status-check.md

@@ -1,242 +1,49 @@
 ---
 name: workflow-status-check
-description: Scan .session files and git status to determine workflow state
-tools: Bash, Read, Glob, Grep
+description: Determine workflow state using sprint scripts
+tools: Bash, Read
 model: haiku
 ---
-You are a workflow status check assistant. Scan the work state and report.
 
-Universal entry point telling each agent: what work exists, what phase, and whether to activate.
+<info>
+Universal entry point telling agents: what work exists, what phase, and whether to activate.
+Uses `/sprint` skill scripts for deterministic output.
+</info>
 
-## Project Root
-$CLAUDE_PROJECT_DIR (set by SessionStart hook)
-
-## Turn Efficiency
-
-See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
-
-## Step 1: Scan Session Files
-
-```bash
-# EFFICIENT: List and preview all session files in one command
-ls -la .session/*-session.md 2>/dev/null && for f in .session/*-session.md; do [ -f "$f" ] && head -50 "$f"; done
-```
+---
 
-For each session file found, extract:
-- Story ID (from `## Story X-Y:` line)
-- Title
-- Phase (from `**Phase:**` line)
-- Status (from `**Status:**` line)
-- Repos (from `**Repos:**` line)
-- Branch (from `**Branch:**` line)
-- Jira key (from `**Jira:**` line)
-- Started date (from `**Started:**` line)
-- Workflow (from `**Workflow:**` line in Workflow Tracking section)
-- Phase Started (from `**Phase Started:**` line - ISO 8601 timestamp)
+## Execution
 
-**Workflow field extraction:**
-```bash
-# Extract workflow name (defaults to "tdd" if not found for backward compatibility)
-WORKFLOW=$(grep "^\*\*Workflow:\*\*" "$SESSION_FILE" | head -1 | sed 's/\*\*Workflow:\*\* //' | xargs)
-[ -z "$WORKFLOW" ] && WORKFLOW="tdd"
+Run the sprint status script and parse output:
 
-# Extract phase started timestamp
-PHASE_STARTED=$(grep "^\*\*Phase Started:\*\*" "$SESSION_FILE" | head -1 | sed 's/\*\*Phase Started:\*\* //' | xargs)
-```
-
-For worktree detection, check INSIDE the session file:
 ```bash
-# Check if this is a worktree session
-grep "^worktree:" "$SESSION_FILE"
-# If found, also extract:
-# - worktree: (the worktree name, e.g., wt-5-3a)
-# - path: (the worktree path)
-# - api_port: (the API port)
-# - ui_port: (the UI port)
+.pennyfarthing/scripts/core/run.sh sprint/sprint-status.sh
 ```
 
-## Step 1.5: Check Epic Context
-
-**Before proceeding with git status or state determination, verify epic context exists.**
+Then check for active sessions:
 
 ```bash
-# Check for epic context files
-EPIC_CONTEXTS=$(ls .session/context-epic-*.md 2>/dev/null)
-
-if [ -z "$EPIC_CONTEXTS" ]; then
-    echo "EPIC_CONTEXT_STATUS: MISSING"
-    echo "No epic context files found in .session/"
+if ls .session/*-session.md 1>/dev/null 2>&1; then
+  for f in .session/*-session.md; do head -30 "$f"; done
 else
-    echo "EPIC_CONTEXT_STATUS: PRESENT"
-    # List found epic contexts
-    for ctx in $EPIC_CONTEXTS; do
-        EPIC_ID=$(basename "$ctx" | sed 's/context-epic-\(.*\).md/\1/')
-        EPIC_TITLE=$(grep "^# Epic" "$ctx" | head -1 | sed 's/# Epic [0-9]*: //')
-        echo "  - Epic $EPIC_ID: $EPIC_TITLE"
-    done
+  echo "No active sessions"
 fi
 ```
 
-**If no epic context exists AND we're in NEW_WORK_STATE, this blocks /new-work.**
-
-## Step 2: Check Git Status
-
-Use `repo-scan.sh` for git status across all repos:
-
-```bash
-source $CLAUDE_PROJECT_DIR/scripts/utils/repo-scan.sh
-scan_all_repos_status
-# Returns one line per repo: repo|branch|uncommitted|ahead
-```
-
-## Step 2.5: Detect Drift (Merged but Not Closed)
-
-**Check for drifted stories before state determination.** A story is "drifted" when its branch was merged but YAML or Jira still shows status other than `done`.
-
-```bash
-source $CLAUDE_PROJECT_DIR/pennyfarthing-dist/scripts/utils/sprint-common.sh
-drifted=$(detect_drift)
-
-if [ -n "$drifted" ]; then
-    echo "=== Drifted Stories Detected ==="
-    echo "The following stories have merged branches but are not marked 'done':"
-    echo "$drifted"
-    echo ""
-    echo "Each entry shows: story_id:yaml_status:jira_status"
-fi
-```
-
-**Drift detection checks both:**
-- **YAML drift**: Sprint YAML shows `in_progress` but branch is merged
-- **Jira drift**: Jira shows status other than "Done" or "Closed" but branch is merged
-
-**If drift found:**
-1. Report drifted stories with their YAML and Jira status to the user
-2. Offer auto-reconcile option (y/n) to update both YAML and Jira to done
-3. If user accepts, call `reconcile_drift` for each story which:
-   - Updates YAML status to `done`
-   - Transitions Jira issue to "Done"
-   - Logs reconciliation to `.session/reconciliation.log`
-
-**Auto-reconcile prompt:**
-```
-Would you like to auto-reconcile these drifted stories? (y/n)
-This will update YAML status to 'done' and transition Jira to 'Done'.
-```
-
-## Step 2.6: Check Jira Ownership for In-Progress Stories
-
-**CRITICAL for multi-developer coordination.** For any story with `status: in_progress` in the YAML, verify WHO owns it in Jira.
-
-```bash
-# Get current user for comparison
-CURRENT_USER=$(jira me 2>/dev/null || echo "unknown")
-
-# For each in_progress story, extract Jira key and check assignment
-# First, find in_progress stories and their Jira keys
-grep -B10 "status: in_progress" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml | grep -E "(id:|jira:)" | paste - - | while read line; do
-    STORY_ID=$(echo "$line" | grep -oE 'id: "[^"]+"' | cut -d'"' -f2)
-    JIRA_KEY=$(echo "$line" | grep -oE 'MSSCI-[0-9]+')
-
-    if [ -n "$JIRA_KEY" ]; then
-        # Query Jira for assignment
-        JIRA_INFO=$(jira issue view "$JIRA_KEY" --raw 2>/dev/null | jq -r '{
-            assignee: (.fields.assignee.displayName // "Unassigned"),
-            status: .fields.status.name
-        }' 2>/dev/null)
-
-        ASSIGNEE=$(echo "$JIRA_INFO" | jq -r '.assignee')
-        echo "OWNERSHIP_CHECK: $STORY_ID | $JIRA_KEY | $ASSIGNEE"
-    fi
-done
-```
-
-**Ownership Classification:**
-- `Unassigned` → Available for current user to claim
-- Current user's name → YOUR work, can continue
-- Someone else's name → **COLLEAGUE'S WORK - DO NOT OFFER**
-
-## Step 2.7: Check Background Tasks
-
-**Detect any running background tasks in session files.**
-
-```bash
-source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
-
-# Check each session file for active background tasks
-for session_file in .session/*-session.md; do
-    [ -f "$session_file" ] || continue
-
-    if bg_task_check "$session_file"; then
-        STORY_ID=$(basename "$session_file" | sed 's/-session.md//')
-        echo "BACKGROUND_TASKS: $STORY_ID"
-        bg_task_list "$session_file"
-    fi
-done
-```
-
-**If background tasks found:**
-- Report which session has active background tasks
-- Warn that results should be checked before proceeding
-- Include in status output under "Background Tasks" section
-
-**Background Task Status Values:**
-- `running` - Task still executing, check with TaskOutput
-- `completed` - Task finished, safe to cleanup
-- `error` - Task failed, may need investigation
-
-## Step 3: Determine Workflow State
-
-**First, check the sprint YAML for ground truth:**
-```bash
-# What does the YAML actually say?
-grep -E "status: (in_progress|backlog|done)" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml | sort | uniq -c
-```
-
-Apply these rules in order:
-- **MISSING_EPIC_CONTEXT**: No epic context files AND no active session files
-- **FINISH_STATE**: Session file has Phase=`approved` OR (Phase=`review` AND Status=`approved`)
-- **NEW_WORK_STATE**: No *-session.md files AND no `status: in_progress` stories owned by current user in YAML
-- **IN_PROGRESS_STATE**: Session file exists with active phase, OR YAML has `status: in_progress` stories owned by current user
-- **COLLEAGUE_IN_PROGRESS**: YAML has `status: in_progress` but Jira shows assigned to someone else
-
-**CRITICAL:** The sprint YAML `status:` field is the source of truth for story completion.
-- `status: done` = story is DONE, do not report as in-progress
-- `status: in_progress` = story is being worked - CHECK JIRA FOR OWNER
-- `status: backlog` = story is available for new work
-
-**CRITICAL:** Jira assignment is the source of truth for WHO owns in-progress work.
-- If Jira shows assigned to someone other than current user, that story is OFF LIMITS
-- Report colleague-owned stories in output but DO NOT offer them as resumable work
-
-**Note:** MISSING_EPIC_CONTEXT takes precedence over NEW_WORK_STATE. User must run `/start-epic` before `/new-work`.
-
-## Step 4: Check Readiness
-
-For **FINISH_STATE** - check PRs using `repo-scan.sh`:
-```bash
-source $CLAUDE_PROJECT_DIR/scripts/utils/repo-scan.sh
-check_repo_pr "REPO_NAME" "BRANCH_NAME"
-# Returns PR URL or "none"
-```
+---
 
-For **NEW_WORK_STATE** - check sprint YAML for actual story statuses:
-```bash
-# Count stories by status in current sprint
-echo "=== Sprint Story Status ==="
-grep -E "^\s+status:" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml | sort | uniq -c
+## State Determination
 
-# List any in_progress stories (these are ACTUALLY in progress)
-echo "=== In-Progress Stories ==="
-grep -B5 "status: in_progress" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml | grep -E "(id:|title:|status:)"
+| State | Condition |
+|-------|-----------|
+| `FINISH_STATE` | Session exists with Phase=approved OR Status=approved |
+| `IN_PROGRESS_STATE` | Session exists with active phase (tea/dev/review) |
+| `NEW_WORK_STATE` | No sessions AND sprint has backlog/ready stories |
+| `EMPTY_BACKLOG_STATE` | No sessions AND sprint has NO backlog/ready stories |
 
-# Count backlog stories available
-echo "=== Backlog Available ==="
-grep -c "status: backlog" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml 2>/dev/null || echo "0"
-```
+**Important:** Sprints are fixed two-week periods (kanban-style). Never suggest closing a sprint early or starting sprint planning when backlog is empty. The correct response to `EMPTY_BACKLOG_STATE` is to suggest promoting stories from `future.yaml`.
 
-**IMPORTANT:** Only report a story as "in progress" if the YAML shows `status: in_progress`.
-Stories with `status: done` are DONE - do not list them as in-progress even if they appear in sprint history.
+---
 
 ## Output Format
 
@@ -244,89 +51,18 @@ Stories with `status: done` are DONE - do not list them as in-progress even if t
 ## Workflow Status Report
 
 ### Detected State
-**{MISSING_EPIC_CONTEXT | FINISH_STATE | NEW_WORK_STATE | IN_PROGRESS_STATE}**
-
-*Note: If colleague work exists, state is still NEW_WORK_STATE (their work doesn't block you).*
-
-### Epic Context Status
-| Status | Epic ID | Title |
-|--------|---------|-------|
-| ✓ PRESENT | 1 | Agentic Best Practices Implementation |
-
-*If MISSING:*
-| Status | Action Required |
-|--------|-----------------|
-| ✗ MISSING | Run `/start-epic` to generate epic technical context |
-
-### Active Work Sessions (Your Work)
-| Story | Title | Workflow | Phase | Phase Started | Status | Repos |
-|-------|-------|----------|-------|---------------|--------|-------|
-| 32-8 | Threat Hunt Summary | tdd | tea | 2026-01-13T14:30:00Z | in-progress | both |
-
-### Colleague Work (DO NOT OFFER)
-| Story | Title | Jira | Assignee | Status |
-|-------|-------|------|----------|--------|
-| 7-2 | Job-Fair Role-Selective | MSSCI-11387 | Michael Pursifull | In Progress |
-
-*Stories assigned to colleagues in Jira are excluded from work options.*
-
-### Background Tasks
-| Story | Task ID | Type | Started | Status |
-|-------|---------|------|---------|--------|
-| 31-14 | abc123 | testing-runner | 14:30 | running |
-
-*If any tasks show "running", check results with TaskOutput before proceeding.*
-
-### Git State
-| Repo | Type | Branch | Uncommitted | Ahead of Origin |
-|------|------|--------|-------------|-----------------|
-| conductor-api | api | feat/32-8-hunt-summary | 0 files | 0 commits |
-| conductor-ui | ui | feat/32-8-hunt-summary | 0 files | 0 commits |
+**{STATE}**
 
-Note: For multi-repo projects, this table dynamically includes all configured repos.
+### Sprint Summary
+[Output from sprint-status.sh]
 
-### Readiness Assessment
+### Active Session
+| Story | Phase | Status | Branch |
+|-------|-------|--------|--------|
 
-**For FINISH:**
-- PR Status: {merged | open | none}
-- Uncommitted Changes: {yes | no}
-- Tests: {unknown - run separately}
-
-**For NEW_WORK:**
-- Backlog Stories: {N} available
-- Current Sprint: Sprint {N}
-
-### Agent Guidance & Phase Flow
-
-| Phase | Active Agent | Next → |
-|-------|--------------|--------|
-| MISSING_EPIC | - | Run `/start-epic` |
-| (none)/complete | SM | → TEA |
-| sm | TEA | → Dev |
-| tea | Dev | → Reviewer |
-| dev | Reviewer | → SM |
-| review/approved | SM | Finish |
-
-### Multi-Developer Coordination
-
-| Scenario | Action |
-|----------|--------|
-| Story in YAML `in_progress` + Jira assigned to YOU | Your work - offer to continue |
-| Story in YAML `in_progress` + Jira assigned to COLLEAGUE | Their work - DO NOT offer, show in "Colleague Work" |
-| Story in YAML `in_progress` + Jira unassigned | Orphaned work - offer to claim or skip |
-| Story in YAML `backlog` + Jira unassigned | Available - offer as new work option |
-
-**For {CALLING_AGENT}:** {specific action based on phase and state}
+### Recommended Action
+- FINISH_STATE → Proceed to finish flow
+- IN_PROGRESS_STATE → Report which agent should continue
+- NEW_WORK_STATE → Show available stories
+- EMPTY_BACKLOG_STATE → Suggest promoting stories from future.yaml
 ```
-
-## Error Recovery
-
-On failure: Log → Diagnose → Retry (max 2) → Escalate to calling agent
-
-| Failure | Fix |
-|---------|-----|
-| Session unreadable | Report for manual inspection |
-| Git command failed | Use absolute paths |
-| gh CLI failed | User may need `gh auth` |
-
-If partial failure, report what worked and mark unknowns. **Never silently fail.**

package/pennyfarthing-dist/commands/architect.md

@@ -5,7 +5,7 @@ description: System Architect - Technical design and architecture
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/run.sh" agent-session.sh start "architect"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "architect"
 ```
 This finds the project root and loads your persona. Adopt the character shown in the output.
 
@@ -13,7 +13,7 @@ Then load and follow `.pennyfarthing/agents/architect.md`
 </agent-activation>
 
 <agent-exit>
-On exit: Capture learnings to sidecar, run `agent-session.sh stop`
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
 </agent-exit>
 
 <purpose>

package/pennyfarthing-dist/commands/close-epic.md

@@ -67,15 +67,18 @@ Recalculate and update the summary section:
 
 ### Step 6: Jira Transition (Optional)
 
-If epic has `jira_key`:
+If epic has `jira_key`, use `/jira move` skill:
 ```bash
 # Check if Jira CLI available
 if command -v jira &> /dev/null; then
     echo "Transition Jira epic to Done? (y/n)"
-    # If yes: jira issue move $JIRA_KEY "Done"
+    # If yes, use /jira move skill:
+    # jira issue move $JIRA_KEY "Done" --project MSSCI
 fi
 ```
 
+**Note:** Always use `/jira` skill commands - see `.claude/skills/jira/skill.md` for syntax.
+
 ### Step 7: Archive Context (Optional)
 
 If `.session/context-epic-{N}.md` exists:

package/pennyfarthing-dist/commands/create-branches-from-story.md

@@ -100,16 +100,16 @@ Use this instead of Step 3 if you need to work on multiple stories simultaneousl
 cd $CLAUDE_PROJECT_DIR
 
 # Create worktree with branches (both API and UI)
-./scripts/run.sh worktree-manager.sh create [story-id] feat/[story-id]-[description]
+./scripts/run.sh git/worktree-manager.sh create [story-id] feat/[story-id]-[description]
 
 # Example: Story 5-2
-./scripts/run.sh worktree-manager.sh create 5-2 feat/5-2-csv-import
+./scripts/run.sh git/worktree-manager.sh create 5-2 feat/5-2-csv-import
 
 # For API-only work
-./scripts/run.sh worktree-manager.sh create [story-id] feat/[story-id]-[description] api
+./scripts/run.sh git/worktree-manager.sh create [story-id] feat/[story-id]-[description] api
 
 # For UI-only work
-./scripts/run.sh worktree-manager.sh create [story-id] feat/[story-id]-[description] ui
+./scripts/run.sh git/worktree-manager.sh create [story-id] feat/[story-id]-[description] ui
 ```
 
 This creates:
@@ -119,16 +119,7 @@ This creates:
 
 **Skip to Step 5b** if using worktrees.
 
-### 4. Create Pennyfarthing Session
-
-```bash
-cd $CLAUDE_PROJECT_DIR
-
-# Start new work session
-./scripts/run.sh new-work.sh
-```
-
-### 5. Document the Work
+### 4. Document the Work
 
 Edit `.session/{STORY_ID}-session.md`:
 
@@ -232,7 +223,7 @@ cd $CLAUDE_PROJECT_DIR/worktrees/[story-id]/API
 cd $CLAUDE_PROJECT_DIR/worktrees/[story-id]/UI
 
 # Get port configuration for dev servers
-eval $(./scripts/run.sh worktree-manager.sh ports [story-id])
+eval $(./scripts/run.sh git/worktree-manager.sh ports [story-id])
 echo "API: $API_PORT, UI: $UI_PORT"
 ```
 
@@ -253,11 +244,7 @@ git checkout main && git pull
 git checkout -b feature/AUTH-123-user-authentication
 git push -u origin feature/AUTH-123-user-authentication
 
-# 3. Create Pennyfarthing session
-cd ..
-./scripts/run.sh new-work.sh
-
-# 4. Edit session file
+# 3. Edit session file
 # Update .session/{STORY_ID}-session.md with story details
 
 # 5. Start working
@@ -359,9 +346,6 @@ cd ../UI && git checkout main && git pull && \
 git checkout -b feature/STORY-ID-description && \
 git push -u origin feature/STORY-ID-description
 
-# Create session
-cd .. && ./scripts/run.sh new-work.sh
-
 # Edit session
 # Update .session/{STORY_ID}-session.md
 

package/pennyfarthing-dist/commands/dev.md

@@ -5,7 +5,7 @@ description: Developer - Feature implementation and coding
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/run.sh" agent-session.sh start "dev"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "dev"
 ```
 This finds the project root and loads your persona. Adopt the character shown in the output.
 
@@ -13,7 +13,7 @@ Then load and follow `.pennyfarthing/agents/dev.md`
 </agent-activation>
 
 <agent-exit>
-On exit: Capture learnings to sidecar, run `agent-session.sh stop`
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
 </agent-exit>
 
 <purpose>

package/pennyfarthing-dist/commands/devops.md

@@ -5,7 +5,7 @@ description: DevOps Engineer - Infrastructure and deployment automation
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/run.sh" agent-session.sh start "devops"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "devops"
 ```
 This finds the project root and loads your persona. Adopt the character shown in the output.
 
@@ -13,7 +13,7 @@ Then load and follow `.pennyfarthing/agents/devops.md`
 </agent-activation>
 
 <agent-exit>
-On exit: Capture learnings to sidecar, run `agent-session.sh stop`
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
 </agent-exit>
 
 <purpose>
@@ -55,5 +55,5 @@ Infrastructure and deployment automation specialist who maintains CI/CD pipeline
 - **Agent:** `.pennyfarthing/agents/devops.md`
 - **Sidecar:** `.claude/project/agents/devops-sidecar/`
 - **Skills:** `/just`
-- **Context:** `.pennyfarthing/guides/shared-context.md`, architecture documentation
+- **Context:** `.pennyfarthing/guides/agent-behavior.md`, architecture documentation
 </reference>

package/pennyfarthing-dist/commands/git-cleanup.md

@@ -21,7 +21,7 @@ All changes MUST follow this workflow:
 ### 1. Gather Current State and Check for Unpushed Commits
 
 ```bash
-./scripts/run.sh git-status-all.sh
+./scripts/run.sh git/git-status-all.sh
 ```
 
 This shows branch, changes, and unpushed commits for all repos.
@@ -51,7 +51,7 @@ fi
 
 ```bash
 echo "=== Worktree Status ==="
-./scripts/run.sh worktree-manager.sh status
+./scripts/run.sh git/worktree-manager.sh status
 ```
 
 This shows all active worktrees with their branches and uncommitted changes.
@@ -240,7 +240,7 @@ When running this command, Claude should:
 
 ```bash
 # View what needs cleanup (all repos)
-./scripts/run.sh git-status-all.sh
+./scripts/run.sh git/git-status-all.sh
 
 # Create cleanup branch
 git checkout develop && git pull
@@ -278,7 +278,7 @@ Stale feature branches can accumulate over time. Include branch cleanup as part
 ```bash
 echo "=== Branch Status ==="
 
-./scripts/run.sh check-status.sh
+./scripts/run.sh misc/check-status.sh
 ```
 
 ### Remove Merged Branches
@@ -322,7 +322,7 @@ done
 
 ```bash
 echo "=== Final State ==="
-./scripts/run.sh git-status-all.sh
+./scripts/run.sh git/git-status-all.sh
 echo ""
 echo "=== Branches ==="