@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/templates/setup-env.sh.template

@@ -0,0 +1,18 @@
+#!/usr/bin/env zsh
+# Project-specific environment setup
+# Called during Claude Code session start
+
+# Export to CLAUDE_ENV_FILE for session persistence
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+    {
+        echo "export PROJECT_NAME=\"${PROJECT_NAME}\""
+        echo "export PROJECT_LABEL=\"${PROJECT_NAME}\""
+        # Add project-specific env vars here
+        # echo "export API_REPO=\"api\""
+        # echo "export UI_REPO=\"ui\""
+    } >> "$CLAUDE_ENV_FILE"
+fi
+
+# Display project info
+echo "Project: ${PROJECT_NAME}"
+echo "Pennyfarthing: npm package"

package/pennyfarthing-dist/templates/shared-context.md.template

@@ -0,0 +1,70 @@
+# Shared Agent Context
+
+This file contains common context loaded by all agents.
+
+## Project
+
+- **Name:** ${PROJECT_NAME}
+- **Sprint Status:** `sprint/current-sprint.yaml`
+- **Active Work:** `.session/{story-id}-session.md`
+- **Agent Framework:** Pennyfarthing (npm)
+
+### Tech Stack
+
+| Component | Language | Framework |
+|-----------|----------|-----------|
+| Example | TypeScript | Node.js |
+
+### Repo Structure
+
+```
+${PROJECT_NAME}/
+├── src/                    # Source code
+├── tests/                  # Tests
+├── docs/                   # Documentation
+├── sprint/                 # Sprint YAML files
+├── scripts/                # Utility scripts
+└── .claude/                # Claude Code configuration
+    ├── core/               # Pennyfarthing core (managed)
+    ├── project/            # Project-specific config
+    │   ├── agents/         # Agent sidecars (project knowledge)
+    │   ├── docs/           # This file, agent-scopes.yaml
+    │   └── hooks/          # setup-env.sh
+    ├── skills/             # Core skills (managed)
+    ├── personas/           # Persona themes (managed)
+    └── manifest.json       # Pennyfarthing version tracking
+```
+
+## Git Branch Strategy
+
+- **All work:** Feature branches
+- **Branch from:** `develop` (or `main` if no develop branch)
+- **PRs target:** `develop`
+- **Naming:** `feat/[story]-[description]` or `fix/[issue]-[description]`
+
+## TDD Workflow
+
+1. **SM** creates story and hands off to TEA
+2. **TEA** writes failing tests, hands off to Dev
+3. **Dev** implements to pass tests, hands off to Reviewer
+4. **Reviewer** reviews code, approves or requests changes
+
+## Testing Commands
+
+```bash
+# Run tests
+npm test
+
+# Run specific test
+npm test -- --grep "test name"
+```
+
+## Building
+
+```bash
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+```

package/pennyfarthing-dist/templates/sidecar/decisions.md.template

@@ -0,0 +1,40 @@
+# ${AGENT_NAME} Decisions
+
+Architecture Decision Records (ADRs) for ${AGENT_NAME} work.
+
+## Decision Template
+
+Use this format for significant technical choices:
+
+### [Decision Title]
+
+**Status:** Proposed / Accepted / Superseded
+
+**Context:** Why was this decision needed? What problem were we solving?
+
+**Decision:** What did we decide to do?
+
+**Rationale:** Why this approach? What were the tradeoffs?
+
+**Alternatives Considered:**
+- Option A: [description and why we didn't choose it]
+- Option B: [description and why we didn't choose it]
+
+**Consequences:** What is the impact? What becomes easier/harder?
+
+**Date:** When was this decided?
+
+---
+
+## Decisions to Document
+
+Start with significant choices:
+- Architecture patterns
+- Technology selections
+- Process decisions
+- Design approaches
+- Library/dependency choices
+- Data storage strategies
+- API design choices
+
+Keep 5-15 active decisions. Supersede rather than delete when contexts change.

package/pennyfarthing-dist/templates/sidecar/gotchas.md.template

@@ -0,0 +1,37 @@
+# ${AGENT_NAME} Gotchas
+
+Common pitfalls and edge cases encountered during ${AGENT_NAME} work.
+
+## Gotcha Template
+
+Use this format to document lessons learned:
+
+### [Gotcha Title]
+
+**Situation:** When does this happen? What triggers it?
+
+**Problem:** What goes wrong? What's the symptom?
+
+**Prevention:** How to avoid this.
+
+**Fix:** What to do if you hit it anyway.
+
+**Example:**
+```
+real example from experience
+```
+
+---
+
+## Gotchas to Document
+
+Start with things that caused surprises:
+- Confusing error messages
+- Unexpected dependencies
+- Side effects of common operations
+- Environment-specific issues
+- Race conditions or timing issues
+- Configuration gotchas
+- Data loss risks
+
+Keep 5-15 active gotchas. Archive when issues are resolved.

package/pennyfarthing-dist/templates/sidecar/patterns.md.template

@@ -0,0 +1,34 @@
+# ${AGENT_NAME} Patterns
+
+Capture successful patterns discovered during ${AGENT_NAME} work.
+
+## Pattern Template
+
+Use this format to document recurring patterns:
+
+### [Pattern Name]
+
+**Context:** When does this pattern apply? What problem does it solve?
+
+**Solution:** What to do. Step-by-step or best practice.
+
+**Example:**
+```
+code or workflow example
+```
+
+**Why it works:** Key insight or reasoning.
+
+---
+
+## Examples to Add
+
+Start with patterns you discover:
+- Common Git workflows
+- Effective communication patterns
+- Code organization approaches
+- Testing strategies
+- Build/deployment patterns
+- Error recovery procedures
+
+Keep 5-15 active patterns. Archive older entries to sprint/archive/ when they become obsolete.

package/pennyfarthing-dist/workflows/agent-docs.yaml

@@ -0,0 +1,70 @@
+# Agent Documentation Workflow
+# For agent file creation, updates, and improvements
+#
+# Flow: Orchestrator → Tech Writer → SM
+# Use for: Agent file updates, process improvements, skill maintenance
+
+workflow:
+  name: agent-docs
+  description: Agent file and process documentation updates
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, story_context]
+      note: SM sets up the story but immediately hands off to Orchestrator
+
+    - name: analyze
+      agent: orchestrator
+      input: [session_file, story_context]
+      output: [audit_report, proposed_changes]
+      gate:
+        type: manual
+        condition: Changes identified and documented
+
+    - name: implement
+      agent: orchestrator
+      input: [audit_report, proposed_changes]
+      output: [updated_files]
+      gate:
+        type: validation
+        condition: Agent files parse correctly, no broken references
+
+    - name: review
+      agent: tech-writer
+      input: [updated_files]
+      output: [approval]
+      gate:
+        type: approval
+        condition: |
+          Documentation quality review:
+          - Clear and consistent structure
+          - No stale references
+          - Follows agent file conventions
+          - XML tags properly nested
+          - Examples are accurate
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    types: [docs, refactor, infrastructure]
+    labels: [agent-file, process-improvement, skill-update]
+    repos: [pennyfarthing]
+
+  notes: |
+    This workflow is for meta-work on the Pennyfarthing system itself:
+    - Updating agent definitions (.pennyfarthing/agents/*.md)
+    - Creating or updating skills (.claude/skills/*/skill.md)
+    - Process improvements and workflow refinements
+    - Agent coordination documentation
+
+    Tech Writer reviews for documentation quality, not code correctness.
+    Focus areas:
+    - Consistent XML tag usage across agents
+    - Clear handoff protocols
+    - Accurate subagent references
+    - No hardcoded theme/character names

package/pennyfarthing-dist/workflows/bdd.yaml

@@ -0,0 +1,58 @@
+# BDD Workflow - Behavior-Driven Development
+# UI-first workflow for features that need UX design before implementation
+#
+# Flow: SM → UX-Designer → TEA → Dev → Reviewer → SM
+# Use for UI components, user-facing features, and behavior-centric stories
+
+workflow:
+  name: bdd
+  description: Behavior-driven development with UX design phase
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: design
+      agent: ux-designer
+      input: [session_file, story_context]
+      output: [design_spec, user_flows, wireframes, behavior_scenarios]
+      gate:
+        type: design_review
+        condition: UX spec defines user flows and acceptance behaviors
+
+    - name: red
+      agent: tea
+      input: [design_spec, behavior_scenarios, story_context]
+      output: [failing_tests]
+      gate:
+        type: tests_fail
+        condition: Behavior scenarios have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, design_spec, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, UX spec implemented
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests, design_spec]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, UX requirements met
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    types: [ui, ux, behavior, component, settings, feature]
+    tags: [bdd, ux-first]
+    points:
+      min: 2

package/pennyfarthing-dist/workflows/tdd.yaml

@@ -0,0 +1,50 @@
+# TDD Workflow - Test-Driven Development
+# Default workflow for feature development in Pennyfarthing
+#
+# Flow: SM → TEA → Dev → Reviewer → SM
+# Scale routing: 1-2 pts use 'trivial' workflow instead
+
+workflow:
+  name: tdd
+  description: Test-driven development with code review
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, no blocking issues
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    types: [feature, enhancement]
+    points:
+      min: 3
+    default: true

package/pennyfarthing-dist/workflows/trivial.yaml

@@ -0,0 +1,40 @@
+# Trivial Workflow - Quick Fixes
+# For small changes that don't need full TDD ceremony
+#
+# Flow: SM → Dev → Reviewer → SM (skips TEA)
+# Use for: chores, fixes, 1-2 point stories
+
+workflow:
+  name: trivial
+  description: Quick fixes without full TDD ceremony
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches]
+
+    - name: implement
+      agent: dev
+      input: [session_file]
+      output: [implementation]
+      gate:
+        type: tests_pass
+        condition: Existing tests still pass
+
+    - name: review
+      agent: reviewer
+      input: [implementation]
+      output: [approval]
+      gate:
+        type: approval
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session]
+
+  triggers:
+    types: [chore, fix, refactor]
+    points:
+      max: 2