@pennyfarthing/core 6.6.2 → 7.0.2

package/README.md

@@ -1,6 +1,6 @@
 # Pennyfarthing
 
-**v6.5.0** | *The outer loop goes once, the inner loop goes many times.*
+**v7.0.0** | *The outer loop goes once, the inner loop goes many times.*
 
 <img src="pennyfarthing.png" alt="Pennyfarthing Logo" width="75" style="float:left; margin:10px" margin="10px">
 
@@ -30,7 +30,7 @@ Explore all themes with OCEAN spider charts, Chernoff faces, and 1020 character
 cd your-project
 
 # Install CLI (1.1 MB)
-npm install --save-dev pennyfarthing
+npm install --save-dev @pennyfarthing/core
 
 # Initialize (creates symlinks, no file copying)
 npx pennyfarthing init
@@ -147,11 +147,8 @@ After initialization:
 ```
 your-project/
 ├── .claude/
-│   ├── agents/               # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/agents/
-│   ├── commands/             # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/commands/
-│   ├── skills/               # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/skills/
-│   ├── personas/             # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/personas/
-│   ├── scripts/              # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/scripts/
+│   ├── commands/             # → symlinks to @pennyfarthing/core commands
+│   ├── skills/               # → symlinks to @pennyfarthing/core skills
 │   ├── project/              # YOUR customizations
 │   │   ├── agents/*-sidecar/ # Agent memory/learnings
 │   │   ├── docs/             # shared-context.md
@@ -159,6 +156,11 @@ your-project/
 │   ├── manifest.json         # Installation manifest
 │   └── settings.local.json   # Claude Code settings
 ├── .pennyfarthing/
+│   ├── agents/               # → symlink to @pennyfarthing/core agents
+│   ├── guides/               # → symlink to @pennyfarthing/core guides
+│   ├── personas/             # → symlink to @pennyfarthing/core personas
+│   ├── scripts/              # → symlink to @pennyfarthing/core scripts
+│   ├── sidecars/             # Agent learning files
 │   └── config.local.yaml     # Theme selection (gitignored)
 ├── sprint/
 │   ├── current-sprint.yaml   # Active sprint
@@ -229,7 +231,7 @@ Override locally with `.claude/pennyfarthing/preferences.local.yaml` (gitignored
 
 ```bash
 # Update CLI
-npm update pennyfarthing
+npm update @pennyfarthing/core
 
 # Update visual terminal (if installed)
 npm update @pennyfarthing/cyclist
@@ -250,17 +252,23 @@ pennyfarthing uninstall --all
 
 Archived sprint data (`sprint/archive/`, `sprint/context/`) is always preserved.
 
-## What's New in v6.4
+## What's New in v7.0
 
-- **102 Themes** - 11 new themes added since v6.0
-- **20 Skills** - Expanded knowledge domains
-- **43 Commands** - More workflow entry points
-- **Sprint 10** - Customizable workflows and runtime permissions
+- **BREAKING: Package Renamed** - `pennyfarthing` → `@pennyfarthing/core`
+- **BREAKING: Directory Restructure** - Content moved from `.claude/` to `.pennyfarthing/`
+- **Cyclist Split** - Visual terminal is now optional `@pennyfarthing/cyclist` (160MB → 1.1MB core)
+- **Customizable Workflow Engine** - YAML-based workflow definitions with story routing
+- **BMAD Interoperability** - Parse and export BMAD format stories and epics
+- **Runtime Permission Management** - Approval gates, spot grants, `/permissions` skill
+- **Enhanced OTEL** - Tool enrichment for Bash, Read, Edit, Write, Grep/Glob spans
+- **Agent Modernization** - All agents updated with status tags and shared behavior
+
+See [CHANGELOG.md](CHANGELOG.md) for full migration guide.
 
 ## What's New in v6.5
 
 - **Simplified Installation** - Two packages for different needs:
-  - `pennyfarthing` - CLI only (1.1 MB)
+  - `@pennyfarthing/core` - CLI only (1.1 MB)
   - `@pennyfarthing/cyclist` - Optional visual terminal with portraits (160 MB)
 - **Portrait Optimization** - Cyclist bundles only 128px and 256px portraits (saves 450MB)
 - **Agent Modernization** - All agents updated with status tags and consolidated shared behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "6.6.2",
+  "version": "7.0.2",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {
@@ -28,14 +28,6 @@
   "bugs": {
     "url": "https://github.com/1898andCo/pennyfarthing/issues"
   },
-  "scripts": {
-    "build": "pnpm -r build && ./scripts/utils/generate-skill-docs.sh",
-    "docs": "./scripts/utils/generate-skill-docs.sh",
-    "dev": "pnpm -r --parallel dev",
-    "test": "pnpm -r test",
-    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
-    "clean": "pnpm -r clean"
-  },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -54,5 +46,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "packageManager": "pnpm@9.0.0"
-}
+  "scripts": {
+    "build": "pnpm -r build && ./scripts/utils/generate-skill-docs.sh",
+    "docs": "./scripts/utils/generate-skill-docs.sh",
+    "dev": "pnpm -r --parallel dev",
+    "test": "pnpm -r test",
+    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
+    "clean": "pnpm -r clean"
+  }
+}

package/pennyfarthing-dist/agents/README.md

@@ -49,7 +49,18 @@ Focus on specific repo(s), implement/test/document features.
 - **`ux-designer.md`** - UX Designer (UI design, UX)
 
 ### Official Subagents (Haiku-based)
-Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type`.
+Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type: "general-purpose"` and `model: "haiku"`.
+
+**Invocation pattern:**
+```yaml
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  prompt: |
+    Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+    {PARAMETERS}
+```
 
 - **`workflow-status-check.md`** - Detect workflow state
 - **`generic-sm-setup.md`** - Research OR setup mode (Story 31-11)
@@ -304,9 +315,12 @@ Subagents can run in background using Claude Code's `run_in_background` paramete
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   run_in_background: true
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Background test run while implementing
     RUN_ID: bg-test-001

package/pennyfarthing-dist/agents/architect.md

@@ -17,10 +17,21 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Architecture scanning, pattern analysis, codebase exploration.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `testing-runner` - Verify builds pass after design changes
-  - `sm-file-summary` - Summarize files for context gathering
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `testing-runner.md` - Verify builds pass after design changes
+  - `sm-file-summary.md` - Summarize files for context gathering
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -140,8 +151,11 @@ When design changes may affect build:
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Verifying build after design change
     RUN_ID: architect-verify

package/pennyfarthing-dist/agents/dev.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: run tests, gather results, update session for handoff
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests, gather results
-  - `generic-handoff` - Workflow-driven session update for handoff
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests, gather results
+  - `generic-handoff.md` - Workflow-driven session update for handoff
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -176,8 +187,11 @@ Then spawn with detected workflow (tdd, trivial, etc.):
 
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: green               # or "implement" for trivial workflow

package/pennyfarthing-dist/agents/devops.md

@@ -17,10 +17,21 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: System checks, log analysis, config scanning.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `testing-runner` - Verify CI pipeline and tests pass
-  - `sm-file-summary` - Summarize configuration files
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `testing-runner.md` - Verify CI pipeline and tests pass
+  - `sm-file-summary.md` - Summarize configuration files
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -140,8 +151,11 @@ Before any deployment:
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Pre-deployment verification
     RUN_ID: devops-verify

package/pennyfarthing-dist/agents/generic-handoff.md

@@ -104,8 +104,11 @@ Based on the gate type from the workflow, run the appropriate checks.
    If no valid cache or TEST_RESULT not provided, delegate to testing-runner:
    ```yaml
    Task tool:
-     subagent_type: "testing-runner"
+     subagent_type: "general-purpose"
+     model: "haiku"
      prompt: |
+       Read and follow: .pennyfarthing/agents/testing-runner.md
+
        REPOS: {REPOS}
        CONTEXT: TEA handoff - verify tests are RED
        RUN_ID: {STORY_ID}-tea-handoff

package/pennyfarthing-dist/agents/orchestrator.md

@@ -17,12 +17,23 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Status checks, metrics gathering, file scanning.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan session files and git status
-  - `testing-runner` - Run tests to verify changes
-  - `sm-file-summary` - Summarize agent files for audit
-  - `generic-handoff` - Update session for phase transitions
-  - `Explore` - Search for patterns across codebase
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan session files and git status
+  - `testing-runner.md` - Run tests to verify changes
+  - `sm-file-summary.md` - Summarize agent files for audit
+  - `generic-handoff.md` - Update session for phase transitions
+  - `Explore` - Search for patterns across codebase (Claude Code built-in)
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -238,8 +249,11 @@ REFLECT: I should follow this pattern for consistency
 Never run `just test`, `npm test`, etc. directly. Always spawn:
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: pennyfarthing
     CONTEXT: Verify agent file changes don't break tests
     RUN_ID: orchestrator-verify
@@ -294,8 +308,11 @@ See `/dev-patterns` skill → "Turn-Efficient Patterns" for complete guidance.
 After completing file updates, spawn handoff helper:
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: agent-docs
     CURRENT_PHASE: implement

package/pennyfarthing-dist/agents/pm.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Backlog scanning, Jira queries, velocity calculation, status checks.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `sm-file-summary` - Summarize files for context gathering
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `sm-file-summary.md` - Summarize files for context gathering
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>

package/pennyfarthing-dist/agents/reviewer-preflight.md

@@ -97,58 +97,16 @@ fi
 
 Spawn a testing-runner subagent with:
 ```yaml
-subagent_type: "testing-runner"
-model: "haiku"
-description: "run tests"
-prompt: |
-  You are a testing runner for the Conductor project.
-  Run tests and report structured results.
-
-  ## Skills Reference
-  Read the testing skill at .claude/skills/testing/SKILL.md for test commands.
-  For troubleshooting failures, see .claude/skills/testing/references/troubleshooting.md
-
-  ## Project Info
-  - Project root: $CLAUDE_PROJECT_DIR (set by SessionStart hook)
-  - Repo(s) to test: {REPO}
-  - Context: PR review pre-flight for Story {STORY_ID}
-  - Run ID: {STORY_ID}-review
-
-  ## Execute Tests and Lints
-
-  Use repo-utils.sh for dynamic repo handling:
-  ```bash
-  source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
-  RUN_ID="{STORY_ID}-review"
-
-  for repo in $(get_repo_names); do
-      repo_path=$(get_repo_path "$repo")
-      test_cmd=$(get_test_command "$repo")
-      lint_cmd=$(get_lint_command "$repo")
-
-      cd $CLAUDE_PROJECT_DIR/$repo_path
-
-      # Run tests
-      if [[ -n "$test_cmd" ]]; then
-          $test_cmd 2>&1 | tee $CLAUDE_PROJECT_DIR/.session/test-{STORY_ID}-reviewer-verify.log
-      fi
-
-      # Run linter
-      if [[ -n "$lint_cmd" ]]; then
-          $lint_cmd 2>&1 | tee $CLAUDE_PROJECT_DIR/.session/lint-{STORY_ID}-${repo}.log
-      fi
-  done
-  ```
-
-  ## Check for Forbidden Skip Patterns
-  ```bash
-  source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
-  for repo in $(get_repo_names); do
-      check_skip_violations "$repo"
-  done
-  ```
-
-  ## Output structured results per testing-runner.md format
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  description: "run tests"
+  prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
+    REPOS: {REPOS}
+    CONTEXT: PR review pre-flight for Story {STORY_ID}
+    RUN_ID: {STORY_ID}-review
 ```
 
 If you cannot spawn a subagent, run the tests directly using the testing skill commands.

package/pennyfarthing-dist/agents/reviewer.md

@@ -35,10 +35,21 @@ A bug you miss ships to production. A security hole you miss gets exploited. An
 <helpers>
 From theme config. Model: haiku. Tasks: gather pre-flight data, update session for approval/rejection
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests
-  - `reviewer-preflight` - Gather pre-flight data (tests, lint, smells)
-  - `generic-handoff` - Workflow-driven session update (approve or reject)
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests
+  - `reviewer-preflight.md` - Gather pre-flight data (tests, lint, smells)
+  - `generic-handoff.md` - Workflow-driven session update (approve or reject)
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -109,8 +120,11 @@ Spawn Helper to gather mechanical data:
 
 ```yaml
 Task tool:
-  subagent_type: "reviewer-preflight"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/reviewer-preflight.md
+
     STORY_ID: {value}
     REPOS: {value}
     BRANCH: {value}
@@ -241,8 +255,11 @@ Then spawn with detected workflow:
 ```yaml
 # Approval
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: review
@@ -252,8 +269,11 @@ Task tool:
 
 # Rejection
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: review

package/pennyfarthing-dist/agents/sm.md

@@ -16,20 +16,25 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Status checks, backlog scans, file summaries, Jira updates, session archival.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan session files and git status
-  - `testing-runner` - Run tests
-  - `generic-sm-setup` - Research backlog OR setup story (mode: research|setup)
-  - `generic-sm-finish` - Preflight checks OR execute finish (phase: preflight|execute)
-  - `generic-handoff` - Workflow-driven phase transitions (TEA/Dev/Reviewer)
-  - `sm-handoff` - SM→TEA/Dev handoff with Jira claim and branch verification
-  - `sm-file-summary` - Read and summarize files for context
-
-- **Removed subagents:** (deleted - use consolidated versions above)
-  - `sm-work-research` → use `generic-sm-setup` with MODE=research
-  - `sm-story-setup` → use `generic-sm-setup` with MODE=setup
-  - `sm-finish-bookkeeping` → use `generic-sm-finish` with PHASE=preflight
-  - `sm-finish-execution` → use `generic-sm-finish` with PHASE=execute
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan session files and git status
+  - `testing-runner.md` - Run tests
+  - `generic-sm-setup.md` - Research backlog OR setup story (mode: research|setup)
+  - `generic-sm-finish.md` - Preflight checks OR execute finish (phase: preflight|execute)
+  - `generic-handoff.md` - Workflow-driven phase transitions (TEA/Dev/Reviewer)
+  - `sm-handoff.md` - SM→TEA/Dev handoff with Jira claim and branch verification
+  - `sm-file-summary.md` - Read and summarize files for context
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -120,8 +125,11 @@ REFLECT: I should clarify AC4 with the user before proceeding.
 1. Run workflow status check:
    ```yaml
    Task tool:
-     subagent_type: "workflow-status-check"
+     subagent_type: "general-purpose"
+     model: "haiku"
      prompt: |
+       Read and follow: .pennyfarthing/agents/workflow-status-check.md
+
        CALLING_AGENT: SM
    ```
 2. Helper returns: `FINISH_STATE`, `NEW_WORK_STATE`, or `IN_PROGRESS_STATE`
@@ -136,8 +144,11 @@ I send helper to check the workflow status before anything else.
 
 ```yaml
 Task tool:
-  subagent_type: "workflow-status-check"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/workflow-status-check.md
+
     CALLING_AGENT: SM
 ```
 
@@ -169,8 +180,11 @@ Task tool:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-finish"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-finish.md
+
     PHASE: preflight
     STORY_ID: {value}
     JIRA_KEY: {value from session/YAML jira field, or omit if not found}
@@ -211,8 +225,11 @@ I read helper's bookkeeping report and write `sprint/context/story-{X-Y}-summary
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-finish"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-finish.md
+
     PHASE: execute
     STORY_ID: {value}
     SUMMARY_CONTENT: {value}
@@ -234,8 +251,11 @@ Helper does:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-setup"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-setup.md
+
     MODE: research
 ```
 
@@ -261,8 +281,11 @@ I receive helper's research report and present to the user:
 
 ```yaml
 Task tool:
-  subagent_type: "sm-file-summary"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/sm-file-summary.md
+
     STORY_ID: {value}
     FILE_LIST: |
       path/to/file1.go
@@ -344,8 +367,11 @@ Then spawn setup with the detected workflow:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-setup"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-setup.md
+
     MODE: setup
     STORY_ID: {value}
     JIRA_KEY: {value}
@@ -373,8 +399,11 @@ After story setup, spawn Helper to update session file for handoff:
 
 ```yaml
 Task tool:
-  subagent_type: "sm-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/sm-handoff.md
+
     STORY_ID: {value}
     REPOS: {value}
     TITLE: {value}

package/pennyfarthing-dist/agents/tea.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: run tests, gather results, update session for handoff
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests, gather results
-  - `generic-handoff` - Workflow-driven session update for handoff
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests, gather results
+  - `generic-handoff.md` - Workflow-driven session update for handoff
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -151,8 +162,11 @@ Then spawn with detected workflow:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd"
     CURRENT_PHASE: red

package/pennyfarthing-dist/agents/testing-runner.md

@@ -65,9 +65,12 @@ The testing-runner can be spawned in background mode, allowing the main agent to
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   run_in_background: true
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Background test run while implementing
     RUN_ID: bg-test-001

package/pennyfarthing-dist/guides/shared-context.md

@@ -9,7 +9,7 @@ Loaded automatically by `/prime --agent <name>` on agent activation.
 ## Project Info
 
 **Project:** Pennyfarthing - Claude Code agent orchestration framework
-**Version:** 6.3.0
+**Version:** 7.0.0
 **Type:** ES module with TypeScript (pnpm monorepo)
 **Node:** >=18.0.0
 

package/pennyfarthing-dist/scripts/doctor-dogfood.sh

@@ -119,19 +119,64 @@ echo ""
 echo "Checking symlinks..."
 echo ""
 
-# Check .claude/pennyfarthing symlink
-if [[ -L ".claude/pennyfarthing" ]]; then
-    TARGET=$(readlink ".claude/pennyfarthing")
-    if [[ "$TARGET" == "../pennyfarthing-dist" ]]; then
-        ok ".claude/pennyfarthing -> ../pennyfarthing-dist"
+# Check .pennyfarthing/ symlinks (new structure)
+PENNYFARTHING_SYMLINKS=("agents" "guides" "personas" "scripts")
+for item in "${PENNYFARTHING_SYMLINKS[@]}"; do
+    link_path=".pennyfarthing/$item"
+    expected_target="../pennyfarthing-dist/$item"
+
+    if [[ -L "$link_path" ]]; then
+        actual_target=$(readlink "$link_path")
+        if [[ "$actual_target" == "$expected_target" ]]; then
+            ok ".pennyfarthing/$item -> $expected_target"
+        else
+            warn ".pennyfarthing/$item points to: $actual_target (expected $expected_target)"
+        fi
+    elif [[ -d "$link_path" ]]; then
+        fail ".pennyfarthing/$item is a directory, should be symlink"
+        if $FIX_MODE; then
+            rm -rf "$link_path"
+            ln -s "$expected_target" "$link_path"
+            fix ".pennyfarthing/$item symlink created"
+        fi
     else
-        fail ".claude/pennyfarthing points to wrong target: $TARGET"
+        fail ".pennyfarthing/$item missing"
+        if $FIX_MODE; then
+            mkdir -p .pennyfarthing
+            ln -s "$expected_target" "$link_path"
+            fix ".pennyfarthing/$item symlink created"
+        fi
     fi
-elif [[ -d ".claude/pennyfarthing" ]]; then
-    fail ".claude/pennyfarthing is a directory, should be symlink"
-else
-    fail ".claude/pennyfarthing missing"
-fi
+done
+
+# Check .claude/ symlinks (commands and skills only)
+CLAUDE_SYMLINKS=("commands" "skills")
+for item in "${CLAUDE_SYMLINKS[@]}"; do
+    link_path=".claude/$item"
+    expected_target="../pennyfarthing-dist/$item"
+
+    if [[ -L "$link_path" ]]; then
+        actual_target=$(readlink "$link_path")
+        if [[ "$actual_target" == "$expected_target" ]]; then
+            ok ".claude/$item -> $expected_target"
+        else
+            warn ".claude/$item points to: $actual_target (expected $expected_target)"
+        fi
+    elif [[ -d "$link_path" ]]; then
+        warn ".claude/$item is a directory, should be symlink to pennyfarthing-dist/$item"
+        if $FIX_MODE; then
+            rm -rf "$link_path"
+            ln -s "$expected_target" "$link_path"
+            fix ".claude/$item symlink created"
+        fi
+    else
+        fail ".claude/$item missing"
+        if $FIX_MODE; then
+            ln -s "$expected_target" "$link_path"
+            fix ".claude/$item symlink created"
+        fi
+    fi
+done
 
 # Check scripts directory/symlink
 if [[ -L "scripts" ]]; then
@@ -194,14 +239,15 @@ echo ""
 echo "Checking build..."
 echo ""
 
-# Check if dist/ is up to date
-if [[ -d "dist" ]]; then
+# Check if packages/core/dist/ is up to date (monorepo structure)
+CORE_DIST="packages/core/dist"
+if [[ -d "$CORE_DIST" ]]; then
     # Check if any src file is newer than its dist counterpart
     OUTDATED=false
-    for src_file in src/cli/commands/*.ts; do
+    for src_file in packages/core/src/cli/commands/*.ts; do
         if [[ -f "$src_file" ]]; then
             base=$(basename "$src_file" .ts)
-            dist_file="dist/cli/commands/${base}.js"
+            dist_file="${CORE_DIST}/cli/commands/${base}.js"
             if [[ -f "$dist_file" ]]; then
                 if [[ "$src_file" -nt "$dist_file" ]]; then
                     OUTDATED=true
@@ -212,19 +258,19 @@ if [[ -d "dist" ]]; then
     done
 
     if $OUTDATED; then
-        warn "dist/ may be outdated (run: npm run build)"
+        warn "packages/core/dist/ may be outdated (run: npm run build)"
         if $FIX_MODE; then
             npm run build >/dev/null 2>&1
-            fix "Rebuilt dist/"
+            fix "Rebuilt packages"
         fi
     else
-        ok "dist/ appears up to date"
+        ok "packages/core/dist/ appears up to date"
     fi
 else
-    fail "dist/ directory missing"
+    fail "packages/core/dist/ missing"
     if $FIX_MODE; then
         npm run build >/dev/null 2>&1
-        fix "Built dist/"
+        fix "Built packages"
     fi
 fi
 
@@ -260,30 +306,19 @@ echo ""
 echo "Checking file locations..."
 echo ""
 
-# Check for files that should be in pennyfarthing-dist but aren't
-# Only check directories that are NOT symlinks (symlink dirs are fine)
-MISPLACED=0
-
-# .claude/agents should be a symlink, not a real directory with files
-if [[ -d ".claude/agents" ]] && [[ ! -L ".claude/agents" ]]; then
-    warn ".pennyfarthing/agents/ is a directory, should be symlink to pennyfarthing/agents"
-    ((MISPLACED++))
-fi
-
-# .claude/commands should be a symlink
-if [[ -d ".claude/commands" ]] && [[ ! -L ".claude/commands" ]]; then
-    warn ".claude/commands/ is a directory, should be symlink to pennyfarthing/commands"
-    ((MISPLACED++))
-fi
-
-# .claude/skills should be a symlink
-if [[ -d ".claude/skills" ]] && [[ ! -L ".claude/skills" ]]; then
-    warn ".claude/skills/ is a directory, should be symlink to pennyfarthing/skills"
-    ((MISPLACED++))
+# Check .pennyfarthing/sidecars exists (user-specific, not symlinked)
+if [[ -d ".pennyfarthing/sidecars" ]]; then
+    SIDECAR_COUNT=$(find .pennyfarthing/sidecars -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+    ok ".pennyfarthing/sidecars/ exists ($SIDECAR_COUNT agent sidecars)"
+else
+    warn ".pennyfarthing/sidecars/ missing (agent learning files)"
 fi
 
-if [[ $MISPLACED -eq 0 ]]; then
-    ok "All .claude/ directories properly symlinked"
+# Check .claude/project exists (project-specific customizations)
+if [[ -d ".claude/project" ]]; then
+    ok ".claude/project/ exists"
+else
+    warn ".claude/project/ missing"
 fi
 
 echo ""

package/pennyfarthing-dist/skills/cyclist/SKILL.md

@@ -20,6 +20,21 @@ Cyclist is a visual terminal interface for Claude Code that displays:
 - Story/session progress tracking
 - Git status and context information
 
+## Quick Start (Recommended)
+
+Use `just` commands from the project root:
+
+```bash
+# Start Cyclist Electron (recommended)
+just cyclist-electron
+
+# Start Cyclist web server only (browser-based)
+just cyclist-web
+
+# Start Cyclist for a different project
+just cyclist-electron project_dir=/path/to/project
+```
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -38,6 +53,20 @@ Cyclist is a visual terminal interface for Claude Code that displays:
 
 ## Launch Commands
 
+### Using Just (Recommended)
+
+```bash
+# Electron mode (from any pennyfarthing project)
+just cyclist-electron
+
+# Web mode (browser-based)
+just cyclist-web
+
+# With explicit project directory
+just cyclist-electron project_dir=/path/to/project
+just cyclist-web project_dir=/path/to/project
+```
+
 ### Web Backend (Browser Mode)
 
 Run from the **cyclist package directory**:
@@ -62,19 +91,10 @@ cyclist /path/to/project
 
 # Direct launch via open
 open -a Cyclist --args --project-dir=/path/to/project
-```
-
-### Quick Launch Examples
-
-```bash
-# Web mode for current directory
-cd packages/cyclist && CYCLIST_PROJECT_DIR=$PWD npm start
-
-# Web mode on custom port
-cd packages/cyclist && PORT=3000 CYCLIST_PROJECT_DIR=/path npm start
 
-# Dev mode with hot reload
-cd packages/cyclist && CYCLIST_DEV_WEB=1 CYCLIST_PROJECT_DIR=/path npm run dev:server
+# Development (from packages/cyclist)
+cd packages/cyclist
+CYCLIST_PROJECT_DIR=/path/to/project npm run dev
 ```
 
 ## Port Auto-Discovery
@@ -91,27 +111,61 @@ From `packages/cyclist/`:
 |--------|-------------|
 | `npm start` | Run production server |
 | `npm run dev` | Electron dev mode with file watching |
+| `npm run dev:once` | Build and run Electron once (no watching) |
 | `npm run dev:web` | Web server with tsx watch |
 | `npm run dev:server` | Server-only with tsx watch |
 | `npm run build` | Compile TypeScript |
 
+## Just Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `just cyclist-electron` | Start Electron dev mode |
+| `just cyclist-web` | Start web server mode |
+| `just cyclist-build` | Build Cyclist TypeScript |
+| `just cyclist-rebuild` | Rebuild native modules (node-pty) |
+| `just cyclist-setup` | Full clean + install + rebuild + build |
+| `just cyclist-build-and-install` | Build and install Cyclist.app |
+| `just test-cyclist` | Run Cyclist tests |
+
 ## Requirements
 
-- Project must have `.claude/` directory (Pennyfarthing-enabled)
-- For Electron: Cyclist.app must be installed
+- Project must have `.pennyfarthing/` directory with config (Pennyfarthing-enabled)
+- For Electron: Cyclist.app must be installed, or run from source
 - For web: Run from `packages/cyclist/` directory
 
 ## Troubleshooting
 
+### Window not appearing (Electron)
+
+The `package.json` has `"main": "dist/server.js"` for npm module use. The `dev` scripts explicitly run `electron dist/main.js` to use the correct entry point. If you run `electron .` directly, it will run the web server instead of the Electron main process.
+
+**Fix:** Use `just cyclist-electron` or `npm run dev` which run `electron dist/main.js`.
+
 ### Server won't start
-- Ensure you're in the cyclist package directory
+
+- Ensure you're in the cyclist package directory (or use `just` commands)
 - Run `npm run build` first if dist/ is stale
 - Check console for port conflict messages
 
 ### No portraits showing
+
 - Verify `pennyfarthing-dist/personas/portraits/` exists
-- Check theme in `.claude/persona-config.yaml`
+- Check theme in `.pennyfarthing/config.local.yaml`
 
 ### "Not a Pennyfarthing project"
-- Ensure project has `.claude/` directory
+
+- Ensure project has `.pennyfarthing/` directory with `config.local.yaml` or agent symlinks
+- Or has `.claude/` directory with persona-config.yaml (legacy)
 - Run `pennyfarthing init` in the project first
+- Or set `CYCLIST_PROJECT_DIR` to point to a valid project
+
+### Native module issues (node-pty)
+
+```bash
+# Rebuild native modules for current Electron version
+just cyclist-rebuild
+
+# Or full setup from scratch
+just cyclist-setup
+```