npm - @pennyfarthing/core - Versions diffs - 7.0.1 → 7.4.0 - Mend

@pennyfarthing/core 7.0.1 → 7.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (692) hide show

package/pennyfarthing-dist/guides/persona-system.md DELETED Viewed

@@ -1,294 +0,0 @@
-# Persona System Documentation
-The Pennyfarthing persona system allows you to customize agent personalities through themes, attributes, and per-agent overrides.
-## Quick Start
-### Change Theme
-Edit `.pennyfarthing/config.local.yaml`:
-```yaml
-theme: star-trek  # 102 themes available!
-```
-Or use the `/set-theme` command:
-```bash
-/set-theme star-trek
-```
-Restart your Claude session. All agents now use Star Trek characters.
-### Discover Themes
-```bash
-/list-themes              # See all 102 themes
-/show-theme alice-in-wonderland  # See theme details
-```
-### Adjust Personality Attributes
-```yaml
-attributes:
-  verbosity: low       # Brief responses
-  humor: disabled      # No character quirks
-```
-### Override Single Agent
-```yaml
-overrides:
-  reviewer:
-    theme: discworld   # Keep Granny for reviews even in Star Trek mode
-```
----
-## Configuration File
-**Location:** `.pennyfarthing/config.local.yaml` (local, not tracked in git)
-```yaml
-# Base theme (102 themes available - see /list-themes)
-theme: discworld       # See categories below
-# Personality modifiers
-attributes:
-  verbosity: medium    # low | medium | high
-  formality: casual    # formal | casual | playful
-  humor: enabled       # enabled | disabled | subtle
-  emoji_use: minimal   # none | minimal | frequent
-# Per-agent customization
-overrides: {}
-```
----
-## Available Themes
-**102 themes available** across categories. Use `/list-themes` to see all, `/show-theme <name>` for details.
-### Theme Categories
-| Category | Examples | Count |
-|----------|----------|-------|
-| **TV Series** | `mash`, `star-trek`, `the-office`, `breaking-bad`, `game-of-thrones`, `firefly` | 30+ |
-| **Film** | `princess-bride`, `lord-of-the-rings`, `matrix`, `pulp-fiction`, `avengers` | 20+ |
-| **Literature** | `alice-in-wonderland`, `discworld`, `shakespeare`, `jane-austen`, `sherlock` | 15+ |
-| **Anime** | `one-piece`, `naruto`, `dragon-ball-z`, `death-note`, `cowboy-bebop` | 10+ |
-| **Games** | `zelda`, `final-fantasy`, `mass-effect`, `portal`, `elder-scrolls` | 10+ |
-| **History/Myth** | `greek-mythology`, `norse-mythology`, `ancient-rome`, `arthurian` | 8+ |
-| **Other** | `minimalist`, `sesame-street`, `muppets`, `parks-and-rec` | 10+ |
-### Theme Tiers
-Themes are rated by persona quality:
-| Tier | Description | Examples |
-|------|-------------|----------|
-| **S** | Top-tier, highly refined | `alice-in-wonderland`, `star-trek`, `discworld` |
-| **A** | Excellent quality | `princess-bride`, `office`, `mash` |
-| **B** | Good quality | `matrix`, `avengers` |
-| **U** | Unrated/new | Recently added themes |
-### Featured Themes
-**Discworld** - Terry Pratchett characters
-- SM: Captain Carrot (supportive, by the book)
-- TEA: Igor (precise, thorough)
-- Dev: Ponder Stibbons (methodical)
-- Reviewer: Granny Weatherwax (uncompromising)
-**Star Trek** - The Next Generation crew
-- SM: Captain Picard ("Make it so")
-- TEA: Data (precise, analytical)
-- Dev: Geordi La Forge (creative problem solver)
-- Reviewer: Spock (logical analysis)
-**Alice in Wonderland** - Carroll's classic
-- SM: The White Rabbit (time-conscious)
-- TEA: The Caterpillar (methodical questioning)
-- Dev: The Mad Hatter (creative solutions)
-- Reviewer: The Queen of Hearts (exacting standards)
-**Minimalist** - Professional mode
-- All agents: Role name only, no personas
----
-## Personality Attributes
-These modify behavior independent of theme.
-### Verbosity
-| Value | Effect |
-|-------|--------|
-| `low` | Brief, focused responses. Skip pleasantries. |
-| `medium` | Balanced detail and brevity. (Default) |
-| `high` | Detailed explanations. Walk through reasoning. |
-### Formality
-| Value | Effect |
-|-------|--------|
-| `formal` | Professional language. Avoid contractions. |
-| `casual` | Conversational but competent. (Default) |
-| `playful` | Light, humorous communication. |
-### Humor
-| Value | Effect |
-|-------|--------|
-| `disabled` | No character quirks or catchphrases. |
-| `subtle` | Occasional character references. |
-| `enabled` | Full character immersion. (Default) |
-### Emoji Use
-| Value | Effect |
-|-------|--------|
-| `none` | No emojis. |
-| `minimal` | Headers and status only. (Default) |
-| `frequent` | Emojis throughout responses. |
----
-## Per-Agent Overrides
-### Use Different Theme for One Agent
-```yaml
-overrides:
-  reviewer:
-    theme: discworld   # Granny even in Star Trek mode
-```
-### Custom Persona File
-```yaml
-overrides:
-  dev:
-    custom: my-custom-dev.yaml  # In .pennyfarthing/personas/custom/
-```
-### Override Attributes for One Agent
-```yaml
-overrides:
-  sm:
-    attributes:
-      verbosity: high
-      humor: disabled
-```
----
-## Creating Custom Themes
-1. Copy an existing theme as template:
-   ```bash
-   cp .pennyfarthing/personas/themes/discworld.yaml .pennyfarthing/personas/themes/my-theme.yaml
-   ```
-2. Edit the theme file with your characters
-3. Update config:
-   ```yaml
-   theme: my-theme
-   ```
-### Theme File Structure
-```yaml
-theme:
-  name: My Theme
-  description: Description of theme
-  source: Origin/inspiration
-agents:
-  sm:
-    character: Character Name
-    style: Communication style
-    expertise: Areas of expertise
-    role: Role description
-    quirk: Optional personality quirk
-    emoji: Optional emoji
-    helper:
-      name: Helper name
-      style: Helper style
-```
----
-## Creating Custom Personas
-For individual agent customization without a full theme.
-1. Create file in `.pennyfarthing/personas/custom/`:
-   ```yaml
-   # my-custom-dev.yaml
-   character: My Custom Character
-   style: My style
-   expertise: My expertise
-   quirk: My quirk
-   helper:
-     name: My Helper
-     style: Helper style
-   ```
-2. Reference in config:
-   ```yaml
-   overrides:
-     dev:
-       custom: my-custom-dev.yaml
-   ```
----
-## How It Works
-1. Agent activation reads `.claude/persona-config.yaml`
-2. Loads base theme from `.pennyfarthing/personas/themes/{theme}.yaml`
-3. Checks for per-agent overrides
-4. Applies attribute modifiers
-5. Agent embodies the resulting persona
-### Loading Priority
-1. Custom file (if specified in overrides)
-2. Override theme (if specified in overrides)
-3. Base theme
-4. Hardcoded fallback (if config missing)
----
-## Tips
-- **Start with minimalist** if characters are distracting
-- **Use `humor: subtle`** for balanced personality
-- **Override reviewer** to keep strict reviewing even in playful themes
-- **Custom themes** are great for team branding
----
-## File Locations
-| File | Purpose |
-|------|---------|
-| `.pennyfarthing/config.local.yaml` | Active configuration (local, not tracked) |
-| `pennyfarthing-dist/personas/attributes.yaml` | Attribute definitions |
-| `pennyfarthing-dist/personas/themes/*.yaml` | 102 theme definitions |
-| `.claude/project/personas/*.yaml` | Custom project personas |
-## Theme Commands
-| Command | Purpose |
-|---------|---------|
-| `/list-themes` | List all 102 available themes |
-| `/show-theme <name>` | Show theme details and characters |
-| `/set-theme <name>` | Set the active theme |
-| `/theme-maker` | Interactive wizard to create custom themes |
-| `/create-theme` | Create a new custom theme |
-| `/job-fair` | Discover which characters excel at each role |

package/pennyfarthing-dist/guides/shared-agent-behavior.md DELETED Viewed

@@ -1,388 +0,0 @@
-# Shared Agent Behavior (All Agents)
-**This file defines behavior common to ALL agents - strategic and tactical.**
-Every agent MUST follow these protocols.
----
-## Environment Setup
-### $CLAUDE_PROJECT_DIR
-All paths use `$CLAUDE_PROJECT_DIR` as the base:
-```bash
-# Available from <env> block at session start
-Working directory: /path/to/project  # This IS $CLAUDE_PROJECT_DIR
-```
-**Always use absolute paths:**
-```bash
-# CORRECT
-cd $CLAUDE_PROJECT_DIR/API && just test
-# WRONG - relative paths fail
-cd API && just test
-```
----
-## Sidecar Memory System
-Every agent has a sidecar directory for project-specific memory that persists across sessions.
-### Sidecar Location
-```
-.claude/project/agents/{agent}-sidecar/
-├── patterns.md      # Implementation patterns discovered
-├── gotchas.md       # Things that bite you
-└── decisions.md     # Past architectural decisions
-```
-### Loading Sidecar (MANDATORY on Activation)
-**Every agent MUST load their sidecar on activation:**
-```bash
-AGENT_NAME="{your-agent}"  # dev, tea, sm, reviewer, architect, etc.
-SIDECAR_DIR="$CLAUDE_PROJECT_DIR/.claude/project/agents/${AGENT_NAME}-sidecar"
-if [ -d "$SIDECAR_DIR" ]; then
-    echo "=== Loading Sidecar Memory ==="
-    cat "$SIDECAR_DIR/patterns.md" 2>/dev/null | head -100
-    cat "$SIDECAR_DIR/gotchas.md" 2>/dev/null | head -50
-    cat "$SIDECAR_DIR/decisions.md" 2>/dev/null | head -50
-fi
-```
-**After loading, internalize:**
-- Patterns that apply to current work
-- Gotchas to watch for
-- Decisions that constrain options
-### Capturing Learnings (MANDATORY before Handoff/Exit)
-**Before handing off or exiting, ask yourself:**
-1. Did I discover a pattern worth remembering?
-2. Did I hit a gotcha that wasted time?
-3. Did I make a decision that future work should know?
-**If YES to any, append to the appropriate sidecar file:**
-```markdown
----
-## [YYYY-MM-DD] [Story-ID or Context] Brief Title
-**Context:** What situation triggered this
-**Learning:** What we discovered
-**Apply When:** When to use this knowledge
-```
-### What Goes Where
-| File | Content | Example |
-|------|---------|---------|
-| `patterns.md` | How to do things well | "Use errgroup for parallel DB calls" |
-| `gotchas.md` | Mistakes to avoid | "npm needs --legacy-peer-deps" |
-| `decisions.md` | Why we chose X over Y | "Don't refactor PaymentService" |
-### When NOT to Write
-- Trivial learnings (obvious to any developer)
-- One-time fixes (won't apply again)
-- Already in project docs
----
-## Confidence Protocol
-Before taking significant actions, assess confidence:
-| Level | Indicators | Action |
-|-------|-----------|--------|
-| **HIGH** | Matches sidecar patterns, clear requirements | Proceed autonomously |
-| **MEDIUM** | Some unknowns, first time for this pattern | Ask before risky actions |
-| **LOW** | Architectural changes, security-sensitive | Always ask user first |
-### Expressing Uncertainty
-When uncertain, SAY SO:
-```
-GOOD: "I'm not sure if this is the right approach. Here's my reasoning..."
-GOOD: "I found two options. Let me explain the tradeoffs..."
-BAD: [silently picks one approach without mentioning alternatives]
-```
----
-## Reasoning Mode (Toggleable)
-**Default:** Quiet mode - internal reasoning, show only key decisions
-**Verbose mode:** User says "verbose mode" to see full reasoning chain
-### When Verbose Mode is ON
-```
-THOUGHT: [what you're trying to accomplish]
-ACTION: [tool/command you'll use]
-OBSERVATION: [what was the result]
-REFLECT: [did it work? what next?]
-```
-### When Quiet Mode is ON (Default)
-Show only:
-- Key decisions and reasoning
-- Results and outcomes
-- Questions and blockers
----
-## Session File Awareness
-Check for active work on activation:
-```bash
-cd $CLAUDE_PROJECT_DIR
-# Check for session files
-if [ -f ".session/{STORY_ID}-session.md" ]; then
-    echo "=== Active Work Session ==="
-    head -50 .session/{STORY_ID}-session.md
-fi
-# Check for worktree sessions
-ls .session/*-session.md (with worktree field) 2>/dev/null
-```
----
-## Skills Usage
-Agents invoke skills based on task:
-| Skill | When to Use |
-|-------|-------------|
-| `/sprint-context` | Sprint status, backlog, story context |
-| `/testing` | Running tests, TDD workflow |
-| `/dev-patterns` | Implementation patterns, common fixes |
-| `/code-review` | Review checklists and patterns |
-| `/story-management` | Story creation, sizing, sprint workflow |
-| `/just` | Run just recipes for project tasks |
-| `/jira` | Jira CLI commands for sprint management |
-| `/theme` | Manage persona themes |
-| `/mermaid` | Generate diagrams in markdown |
-| `/changelog` | Maintain changelogs, auto-generate release notes |
-See `/help` or the `pennyfarthing-dist/skills/` directory for all available skills.
----
-## Structured Output Markers (Cyclist Integration)
-Emit HTML comment markers to enable 100% accurate quick-action button detection in Cyclist.
-### Marker Format
-```html
-<!-- CYCLIST:TYPE:value -->
-```
-| Marker | Usage | Example |
-|--------|-------|---------|
-| `HANDOFF` | Agent handoff | `<!-- CYCLIST:HANDOFF:/tea -->` |
-| `QUESTION` | Yes/No questions | `<!-- CYCLIST:QUESTION:yesno -->` |
-| `CHOICES` | Numbered choices | `<!-- CYCLIST:CHOICES:1,2,3 -->` |
-### When to Emit
-- **Before handoffs:** Include marker after handoff text
-- **Before yes/no questions:** Include marker after question
-- **Before numbered choices:** Include marker listing choice numbers
-### Example Usage
-```markdown
-Ready to hand off to the Caterpillar for test writing.
-**Invoke `/tea` to begin the RED phase.**
-<!-- CYCLIST:HANDOFF:/tea -->
-```
-```markdown
-Shall I proceed with the implementation?
-<!-- CYCLIST:QUESTION:yesno -->
-```
-```markdown
-Which approach do you prefer?
-1. Option A - Simple approach
-2. Option B - More flexible
-3. Option C - Full featured
-<!-- CYCLIST:CHOICES:1,2,3 -->
-```
-### Key Points
-- Markers are **invisible** to users (HTML comments)
-- Markers are **optional** - pattern detection still works as fallback
-- Place marker at **end of message** after relevant text
-- Use **exact agent names**: `/sm`, `/tea`, `/dev`, `/reviewer`, `/architect`, etc.
----
-## Handoff Action Protocol
-When handing off to the next agent in a workflow, the `generic-handoff` subagent determines
-what action to take based on context usage AND the user's handoff mode preference.
-### Handoff Mode Setting
-The user's preference is stored in `.pennyfarthing/cyclist.yaml`:
-```yaml
-handoff_mode: auto   # or "manual"
-```
-The handoff subagent reads this setting and returns an `Action` field.
-### Action Values
-| Action | Meaning | What to Do |
-|--------|---------|------------|
-| `INVOKE_DIRECTLY` | Auto mode + context OK | **Immediately invoke next agent** - do NOT ask permission |
-| `USER_INVOKE` | Manual mode | Tell user: "Ready for {Agent}. Invoke `/{agent}` when ready." |
-| `FRESH_SESSION` | Context too high (>70%) | Tell user: "Context high. Start fresh session with `/{agent}`" |
-### CRITICAL: Follow the Action
-When handoff returns `Action: INVOKE_DIRECTLY`:
-- **DO** immediately use the Skill tool to invoke the next agent
-- **DO NOT** ask "Shall I proceed?" or "Ready to hand off?"
-- **DO NOT** wait for user confirmation
-Asking permission when auto-handoff is enabled defeats the purpose of the setting.
-### Example Flow
-```
-1. Agent completes work
-2. Agent writes assessment to session file
-3. Agent spawns generic-handoff subagent
-4. Subagent returns: "Action: INVOKE_DIRECTLY"
-5. Agent IMMEDIATELY invokes: Skill tool with skill: "{next-agent}"
-```
-### Handoff Marker
-Always include the Cyclist marker at the end of handoff messages:
-```html
-<!-- CYCLIST:HANDOFF:/{next-agent} -->
-```
-This enables quick-action buttons in the Cyclist UI, but the agent must still
-invoke the skill when Action is `INVOKE_DIRECTLY`.
----
-## Turn Efficiency Protocol
-Minimize API round-trips by parallelizing independent operations and batching commands.
-### Core Principles
-1. **Parallelize file reads** - Read multiple independent files in one turn
-2. **Batch bash commands** - Combine git/shell operations with `&&`
-3. **Spawn subagents in parallel** - When results don't depend on each other
-### Examples
-**File reads:**
-```
-# EFFICIENT: Read session + context + related files in one turn
-Read: .session/X-Y-session.md, .session/context-story-X-Y.md, src/feature.ts (parallel)
-```
-**Bash batching:**
-```bash
-# EFFICIENT: Combine git operations
-git status && git branch --show-current && git log -1 --oneline
-# EFFICIENT: Commit, push, and verify in single command
-git add . && git commit -m "feat(X-Y): implement feature" && git push -u origin $(git branch --show-current)
-```
-**Subagent parallelism:**
-```yaml
-# EFFICIENT: If doing both status check AND backlog research
-# spawn both in same turn when results don't depend on each other
-```
-See `/dev-patterns` skill → "Turn-Efficient Patterns" for complete guidance.
-**Note:** Individual agents may include agent-specific examples beyond these core patterns.
----
-## Test Delegation Protocol
-**NEVER run tests directly.** Always delegate to the `testing-runner` subagent.
-### Why Delegate?
-- Consistent test execution across all agents
-- Proper result caching (Story 31-8)
-- Standardized output format for handoff
-- Supports multi-repo test orchestration
-### Invocation Template
-```yaml
-Task tool:
-  subagent_type: "testing-runner"
-  prompt: |
-    REPOS: all | repo1,repo2
-    CONTEXT: why running tests
-    RUN_ID: unique-id
-    # Optional - omit to run all tests:
-    FILTER: pattern  # global filter
-    FILTERS:         # or per-repo filters
-      repo1: pattern1
-      repo2: pattern2
-```
-### What NOT to Do
-```bash
-# WRONG - Never run these directly
-just test
-go test ./...
-npm test
-pytest
-```
-Always spawn `testing-runner` instead.
----
-## Exit Protocol
-Before exiting or switching agents:
-1. **Capture learnings** to sidecar (see above)
-2. **Update session file** if work in progress
-3. **Report status** to user
----
-**This behavior is inherited by all agents. Strategic and tactical agents add their own protocols on top.**