@pennyfarthing/core 7.5.0 → 7.6.1

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: impl
+      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/architecture/steps/step-01-initialize.md

@@ -0,0 +1,101 @@
+# Step 1: Initialize Architecture Session
+
+<step-meta>
+number: 1
+name: initialize
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- DETECT existing workflow state before initialization
+- NEVER generate content without user input
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on initialization only - don't look ahead to future steps
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Initialize document and update frontmatter
+- Set up frontmatter `stepsCompleted: [1]` before loading next step
+- FORBIDDEN to load next step until setup is complete
+
+## Purpose
+
+Set up the architecture decision session by gathering inputs and establishing context.
+
+## Continuation Detection
+
+**First, check for existing workflow:**
+
+1. Look for existing `{output_file}`
+2. If exists, read complete file including frontmatter
+3. If frontmatter has `stepsCompleted` array → **Load `./step-01b-continue.md`**
+4. If not exists → proceed with fresh initialization below
+
+## Instructions
+
+1. **Verify required inputs exist**:
+   - Product Requirements Document (PRD) or feature brief
+   - Any existing architecture documentation
+   - Relevant ADRs from `docs/adr/`
+
+2. **Create session workspace**:
+   - Output file: `{output_file}`
+   - Working notes in session file
+
+3. **Identify stakeholders and constraints**:
+   - Who needs to approve this decision?
+   - What are the timeline constraints?
+   - Are there budget or resource limitations?
+
+## Actions
+
+- Check: `{output_file}` for existing workflow (continuation detection)
+- Read: `{planning_artifacts}/*prd*.md` or `{planning_artifacts}/*brief*.md`
+- Read: `docs/adr/*.md` (scan for relevant prior decisions)
+- Read: Existing architecture docs if referenced
+
+## Output
+
+Add to session file:
+
+```markdown
+## Architecture Session: {project_name}
+
+### Inputs Gathered
+- PRD: [path or "not found"]
+- Existing ADRs: [list relevant ones]
+- Constraints: [timeline, budget, resources]
+
+### Stakeholders
+- Decision maker: [name/role]
+- Reviewers: [list]
+```
+
+## Collaboration Menu
+
+After completing initialization, present options:
+
+- **[C] Continue** - Inputs gathered, proceed to Context Analysis
+- **[A] Advanced Elicitation** - Use discovery protocols to find additional context
+- **[R] Revise** - Need to locate missing inputs before proceeding
+
+## Success Metrics
+
+- Existing workflow detected and handed off to step-01b correctly
+- Fresh workflow initialized with proper setup
+- Input documents discovered and loaded
+- PRD requirement validated and communicated
+- User confirmed document setup before proceeding
+
+## Failure Modes
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not detecting PRD requirement
+- Not confirming inputs with user before proceeding
+
+## Next Step
+
+After user selects [C], proceed to Context Analysis to understand the technical landscape.

package/pennyfarthing-dist/workflows/architecture/steps/step-01b-continue.md

@@ -0,0 +1,93 @@
+# Step 1b: Workflow Continuation Handler
+
+<step-meta>
+number: 1b
+name: continue
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- DETECT existing workflow state from output document frontmatter
+- READ complete document to understand current progress
+- PRESENT continuation options to user before proceeding
+- NEVER proceed without user confirmation
+
+## Purpose
+
+Handle workflow resumption when an existing architecture document is detected. This step is invoked automatically when step 1 finds an existing document with `stepsCompleted` in frontmatter.
+
+## Detection Trigger
+
+Step 1 redirects here when:
+1. Output file `{output_file}` already exists
+2. Document has frontmatter with `stepsCompleted` array
+3. Workflow was previously started but not completed
+
+## Instructions
+
+1. **Read Existing State**:
+   - Parse frontmatter for `stepsCompleted` array
+   - Identify last completed step
+   - Load document content to understand current progress
+
+2. **Analyze Progress**:
+   - Which steps are complete?
+   - What decisions have been made?
+   - Are there any inconsistencies?
+
+3. **Present Continuation Options**:
+   Based on current state, offer user choices:
+
+## Actions
+
+- Read: `{output_file}` completely (including frontmatter)
+- Parse: `stepsCompleted` from frontmatter
+- Analyze: Current document state
+
+## Output
+
+Present to user:
+
+```markdown
+## Workflow Continuation
+
+**Document found:** {output_file}
+**Steps completed:** {stepsCompleted}
+**Last step:** {last_step_name}
+
+### Current Document State
+{summary of what's been decided so far}
+
+### Continuation Options
+
+- **[C] Continue** - Resume from step {next_step}
+- **[R] Restart** - Start fresh (will archive existing document)
+- **[V] View** - Show complete document before deciding
+```
+
+## Continuation Flow
+
+After user selects [C]:
+1. Load the next incomplete step file
+2. Resume workflow from that point
+3. Continue normal step progression
+
+After user selects [R]:
+1. Archive existing document to `{output_file}.backup-{timestamp}`
+2. Return to step 1 for fresh initialization
+3. Proceed with new workflow
+
+## Success Metrics
+
+- Existing workflow detected and state loaded correctly
+- User informed of current progress
+- Continuation or restart handled smoothly
+- No data loss (archive before restart)
+
+## Failure Modes
+
+- Proceeding without user confirmation
+- Not loading complete existing document
+- Losing work by overwriting without archive
+- Misreading stepsCompleted array

package/pennyfarthing-dist/workflows/architecture/steps/step-02-context.md

@@ -0,0 +1,115 @@
+# Step 2: Context Analysis
+
+<step-meta>
+number: 2
+name: context-analysis
+gate: true
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- ANALYZE loaded documents, don't assume or generate requirements
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on understanding project scope and requirements for architecture
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Present A/P/C menu after generating context analysis
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Analyze the project context and identify architectural concerns that will shape the decision.
+
+## Instructions
+
+1. **Extract Technical Constraints** from the PRD:
+   - Performance requirements (latency, throughput, scale)
+   - Security and compliance requirements
+   - Integration requirements with existing systems
+   - Technology mandates or restrictions
+
+2. **Map the Current Landscape**:
+   - What systems already exist?
+   - What are the integration points?
+   - What patterns are already in use?
+
+3. **Identify Key Concerns**:
+   - Scalability needs
+   - Reliability requirements
+   - Maintainability considerations
+   - Cost constraints
+
+## Actions
+
+- Read: `{planning_artifacts}/*prd*.md`
+- Read: `**/project-context.md` (if exists)
+- Grep: Search codebase for existing patterns
+
+## Output
+
+Add to session file:
+
+```markdown
+## Architecture Context
+
+### Technical Constraints
+- Performance: [requirements from PRD]
+- Security: [requirements]
+- Integration: [required touchpoints]
+
+### Current Landscape
+- Existing systems: [list]
+- Patterns in use: [list]
+- Tech stack: [languages, frameworks]
+
+### Key Concerns
+1. [Concern]: [Why it matters]
+2. [Concern]: [Why it matters]
+```
+
+<!-- GATE -->
+
+## Collaboration Menu (A/P/C)
+
+After generating context analysis, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to develop deeper insights about project context and architectural implications
+- **[P] Party Mode** - Bring multiple perspectives to analyze project requirements from different architectural angles
+- **[C] Continue** - Save the content to the document and proceed to pattern selection
+- **[R] Revise** - Need to gather more information or clarify constraints
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Ask probing questions about non-obvious constraints
+2. Explore edge cases and failure scenarios
+3. Identify implicit assumptions in requirements
+4. Dig deeper into integration complexity
+
+## Party Mode
+
+When user selects [P]:
+1. Present analysis from multiple viewpoints:
+   - **Security architect**: What could go wrong?
+   - **Performance engineer**: Where are the bottlenecks?
+   - **Operations**: How will this run in production?
+   - **Developer experience**: How maintainable is this?
+2. Synthesize perspectives into unified understanding
+
+## Success Metrics
+
+- Technical constraints extracted from PRD
+- Current landscape mapped accurately
+- Key concerns identified with rationale
+- User confirmed context before proceeding
+
+## Failure Modes
+
+- Generating requirements not found in documents
+- Proceeding without user confirmation
+- Missing critical constraints from PRD