@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/guides/SESSION-ARTIFACTS.md

@@ -0,0 +1,193 @@
+# Session Artifacts Naming Convention
+
+This guide defines the standard naming patterns for all files in `.session/`.
+
+## Why This Matters
+
+Consistent naming enables:
+1. **Predictable cleanup** - Scripts can reliably find and remove artifacts
+2. **Easy debugging** - Quickly identify what story/agent created a file
+3. **No accumulation** - Story-specific cleanup catches everything
+
+## File Categories
+
+| Category | Purpose | Lifecycle |
+|----------|---------|-----------|
+| `session` | Active work session file | Archived on story completion |
+| `context` | Technical context (story/epic) | Archived on completion |
+| `test` | Test execution output | Cleaned after 1 day or story completion |
+| `lint` | Lint execution output | Cleaned after 1 day or story completion |
+| `handoff` | Agent-to-agent transition data | Cleaned on story completion |
+
+## Naming Patterns
+
+### Session Files (Canonical)
+
+The primary work session file. One per active story.
+
+```
+{STORY_ID}-session.md
+```
+
+**Examples:**
+- `36-2-session.md`
+- `10-15-session.md`
+
+**Created by:** `generic-sm-setup MODE=setup`
+**Archived by:** `generic-sm-finish PHASE=execute` → `sprint/archive/story-{STORY_ID}-{DATE}.md`
+
+---
+
+### Context Files
+
+Technical context for stories and epics.
+
+```
+context-story-{STORY_ID}.md
+context-epic-{EPIC_NUM}.md
+```
+
+**Examples:**
+- `context-story-36-2.md`
+- `context-epic-10.md`
+
+**Created by:** SM (epic-tech-context task)
+**Archived by:** `generic-sm-finish PHASE=execute` (story), `/start-epic` or `/retro` (epic)
+
+---
+
+### Test Output Files
+
+Test execution logs and reports.
+
+```
+test-{STORY_ID}-{AGENT}-{PHASE}.log
+test-{STORY_ID}-{AGENT}-{PHASE}.md
+```
+
+**Components:**
+- `{STORY_ID}` - e.g., `36-2`
+- `{AGENT}` - `tea`, `dev`, `reviewer`
+- `{PHASE}` - `red`, `green`, `verify`
+
+**Examples:**
+- `test-36-2-tea-red.log`
+- `test-36-2-dev-green.md`
+- `test-36-2-reviewer-verify.log`
+
+**Created by:** `generic-handoff`, `reviewer-preflight`, `testing-runner`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Lint Output Files
+
+Lint execution logs.
+
+```
+lint-{STORY_ID}-{REPO}.log
+```
+
+**Examples:**
+- `lint-36-2-api.log`
+- `lint-36-2-ui.log`
+
+**Created by:** `reviewer-preflight`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Handoff Files
+
+Agent-to-agent transition data for structured handoffs.
+
+```
+handoff-{STORY_ID}-{FROM_AGENT}.md
+handoff-{STORY_ID}-{FROM_AGENT}.json
+```
+
+**Examples:**
+- `handoff-36-2-tea.md` (TEA → Dev)
+- `handoff-36-2-dev.json` (Dev → Reviewer)
+- `handoff-36-2-reviewer.md` (Reviewer → SM)
+
+**Created by:** Handoff subagents (`tea-handoff`, `dev-handoff`, `reviewer-handoff-*`)
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}`
+
+---
+
+## System Files
+
+These are managed automatically and should not be manually created.
+
+| File | Purpose | Management |
+|------|---------|------------|
+| `.gitkeep` | Keeps directory in git | Never delete |
+| `session-log.txt` | Session activity log | Rotated to 1000 lines by cleanup |
+| `agents/` | Agent session state (UUIDs) | Cleaned after 1 day |
+
+---
+
+## Cleanup Patterns
+
+The `session-cleanup.sh` script uses these patterns:
+
+### Story-specific cleanup (`--story {ID}`)
+```bash
+test-{STORY_ID}-*.log
+test-{STORY_ID}-*.md
+lint-{STORY_ID}-*.log
+handoff-{STORY_ID}-*.md
+handoff-{STORY_ID}-*.json
+context-story-{STORY_ID}.md
+```
+
+### Time-based cleanup (default: 1 day retention)
+```bash
+test-*.log
+test-*.md
+lint-*.log
+handoff-*.md
+handoff-*.json
+context-story-*.md
+```
+
+### Aggressive cleanup (`--aggressive`)
+```bash
+context-epic-*.md  # Only for completed epics
+```
+
+---
+
+## Migration from Old Patterns
+
+Old patterns that should no longer be used:
+
+| Old Pattern | New Pattern |
+|-------------|-------------|
+| `story-{ID}-context.md` | `context-story-{ID}.md` |
+| `epic-{N}-context.md` | `context-epic-{N}.md` |
+| `test-results-{repo}-{ID}.log` | `test-{ID}-{agent}-{phase}.log` |
+| `tea-{ID}-red-check-results.md` | `test-{ID}-tea-red.md` |
+| `dev-{ID}-red-verify-report.md` | `test-{ID}-dev-red.md` |
+| `{ID}-handoff-summary.md` | `handoff-{ID}-{agent}.md` |
+| `lint-results-{repo}-{ID}.log` | `lint-{ID}-{repo}.log` |
+
+---
+
+## Quick Reference
+
+```
+.session/
+├── .gitkeep                          # Git placeholder
+├── session-log.txt                   # Activity log (auto-rotated)
+├── agents/                           # Agent session state
+│   └── {uuid}.md                     # Per-session state
+├── 36-2-session.md                   # Active story session
+├── context-story-36-2.md             # Story technical context
+├── context-epic-10.md                # Epic technical context
+├── test-36-2-tea-red.log             # TEA test output
+├── test-36-2-dev-green.md            # Dev test report
+├── lint-36-2-api.log                 # Lint output
+└── handoff-36-2-tea.md               # TEA → Dev handoff
+```

package/pennyfarthing-dist/guides/agent-template-strategic.md

@@ -0,0 +1,148 @@
+# Strategic Agent Template
+
+**For:** PM, Architect, Tech-Writer, UX-Designer, DevOps, Orchestrator (support agents)
+
+This template defines the standard structure for strategic agents. These agents support the TDD flow but are not part of the core SM → TEA → Dev → Reviewer cycle.
+
+---
+
+## Section Order
+
+```
+1.  # Title
+2.  <persona>
+3.  <role>
+4.  <helpers>
+5.  <responsibilities>
+6.  <skills>
+7.  <constraints>        (optional)
+8.  <context>
+9.  <on-activation>
+10. ## Workflows (markdown sections)
+11. <handoffs>
+12. <exit>
+```
+
+---
+
+## Template
+
+```markdown
+# {NAME} Agent - {Role Title}
+
+<persona>
+Auto-loaded by `agent-session.sh start` from theme config. See output above.
+
+**Fallback if not loaded:** {Brief personality description}
+</persona>
+
+<role>
+**Primary:** {When this agent is invoked}
+**Blessed Path:** {Recommended workflow, e.g., "PM → /architect for design work"}
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: {What helpers do for this agent}
+
+**Skills I Use:**
+- `/skill-name` - {description}
+</helpers>
+
+<responsibilities>
+- {Duty 1 - what this agent is responsible for}
+- {Duty 2}
+- {Duty 3}
+</responsibilities>
+
+<skills>
+**Skills I Use:**
+- `/sprint-context` - Sprint status and backlog
+- `/architecture` - Architecture documentation
+</skills>
+
+<constraints>
+**This agent does NOT:**
+- {Constraint 1, e.g., "Write implementation code"}
+- {Constraint 2, e.g., "Make unilateral architecture decisions"}
+</constraints>
+
+<context>
+**See:** `.pennyfarthing/guides/shared-context.md` for project info and git strategy.
+**Work Directory:** {Where this agent's artifacts live}
+</context>
+
+<on-activation>
+1. Load sprint context from `sprint/current-sprint.yaml`
+2. Check for active work in `.session/*-session.md`
+3. {Agent-specific startup steps}
+4. Present task menu or offer to continue active work
+</on-activation>
+
+## Key Workflows
+
+### {Workflow 1 Name}
+
+**When:** {Trigger condition}
+**Output:** {What this workflow produces}
+
+{Workflow steps}
+
+### {Workflow 2 Name}
+
+**When:** {Trigger condition}
+**Output:** {What this workflow produces}
+
+{Workflow steps}
+
+<handoffs>
+**From:**
+- {Agent} → me: {When/why they hand off to me}
+
+**To:**
+- me → {Agent}: {When/why I hand off to them}
+</handoffs>
+
+<exit>
+To exit: "Exit {Agent}" or "Switch to [other agent]"
+
+On exit, run: `./scripts/run.sh agent-session.sh stop`
+</exit>
+```
+
+---
+
+## Section Descriptions
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| `<persona>` | Character/personality from theme | Yes |
+| `<role>` | When invoked, blessed path | Yes |
+| `<helpers>` | What Haiku helpers do | Yes |
+| `<responsibilities>` | Duties this agent performs | Yes |
+| `<skills>` | /commands this agent uses | Yes |
+| `<constraints>` | What this agent does NOT do | Optional |
+| `<context>` | Guide files and work directory | Yes |
+| `<on-activation>` | Startup checklist | Yes |
+| Workflows | Agent-specific procedures | Yes |
+| `<handoffs>` | From/to relationships | Yes |
+| `<exit>` | How to leave agent mode | Yes |
+
+---
+
+## Differences from Tactical Template
+
+| Aspect | Tactical | Strategic |
+|--------|----------|-----------|
+| `<reasoning-mode>` | Yes (verbose toggle) | No |
+| `<constraints>` | No | Optional |
+| Assessment Template | Yes (structured output) | No |
+| Handoff section | Auto-invoke logic | From/to relationships |
+| Flow position | Part of TDD cycle | Support/enable TDD |
+
+---
+
+## Notes
+
+- **Constraints section** is optional but recommended for agents that should NOT write code (Architect, UX, Tech-Writer)
+- **Handoffs** describe relationships, not automatic invocation (unlike tactical agents)
+- **Workflows** tend to be domain-specific (design, docs, infra) rather than phase-based

package/pennyfarthing-dist/guides/agent-template-tactical.md

@@ -0,0 +1,162 @@
+# Tactical Agent Template
+
+**For:** SM, TEA, Dev, Reviewer (TDD flow agents)
+
+This template defines the standard structure for tactical agents. All tactical agents should follow this section order for consistency and easy comparison.
+
+---
+
+## Section Order
+
+```
+1.  # Title
+2.  <persona>
+3.  <role>
+4.  <helpers>
+5.  <responsibilities>
+6.  <skills>
+7.  <context>
+8.  <reasoning-mode>
+9.  <on-activation>
+10. ## Workflows (markdown sections)
+11. ## Assessment Template
+12. ## Handoff
+13. <exit>
+```
+
+---
+
+## Template
+
+```markdown
+# {NAME} Agent - {Role Title}
+
+<persona>
+Auto-loaded by `agent-session.sh start` from theme config. See output above.
+
+**Fallback if not loaded:** {Brief personality description}
+</persona>
+
+<role>
+**Primary:** {When this agent is invoked, e.g., "via /tea for TDD test writing"}
+**Position:** {Where in TDD flow, e.g., "SM → **TEA** → Dev → Reviewer"}
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: {What helpers do for this agent}
+
+**Skills I Use:**
+- `/skill-name` - {description}
+</helpers>
+
+<responsibilities>
+- {Duty 1 - what this agent is responsible for}
+- {Duty 2}
+- {Duty 3}
+</responsibilities>
+
+<skills>
+**Skills I Use:**
+- `/sprint-context` - Sprint status and backlog
+- `/testing` - Test execution patterns
+</skills>
+
+<context>
+**See:** `.pennyfarthing/guides/tactical-agent-behavior.md` for shared tactical agent behavior.
+**See:** `.pennyfarthing/guides/shared-context.md` for project info and git strategy.
+</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, show thought process:
+```
+THOUGHT: {what I'm considering}
+ACTION: {what I'm doing}
+OBSERVATION: {what I found}
+REFLECT: {what this means}
+```
+
+**{Agent}-Specific Reasoning:**
+- {When doing X: reason about Y}
+- {When doing Z: think through W}
+
+**REMINDER:** Delegate test runs to testing-runner subagent.
+</reasoning-mode>
+
+<on-activation>
+1. Run workflow status check (helper: `.pennyfarthing/agents/workflow-status-check.md`)
+2. Read session file if active work exists
+3. Verify actual state matches session file
+4. Check if handed off to me (Phase field)
+5. If handed off: offer to start immediately
+6. If not: show task menu
+</on-activation>
+
+## Primary Workflow: {Workflow Name}
+
+{Agent-specific workflow description}
+
+### Step 1: {Step Name}
+{Description}
+
+### Step 2: {Step Name}
+{Description}
+
+## {Agent} Assessment Template
+
+```markdown
+## {Agent} Assessment
+
+**{Key field 1}:** {value}
+**{Key field 2}:** {value}
+
+**Handoff:** To {next agent} for {next task}
+```
+
+## Handoff (Context-Aware Auto-Invoke)
+
+After completing work:
+
+1. Write assessment to session file
+2. Spawn handoff helper (`.pennyfarthing/agents/{agent}-handoff.md`)
+3. Check context: `eval $(./scripts/run.sh check-context.sh)`
+4. If `HANDOFF_MODE=auto`: Use Skill tool to invoke next agent
+5. If `HANDOFF_MODE=ask`: Tell user to start fresh session
+
+<exit>
+To exit: "Exit {Agent}" or "Switch to [other agent]"
+
+On exit, run: `./scripts/run.sh agent-session.sh stop`
+</exit>
+```
+
+---
+
+## Section Descriptions
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| `<persona>` | Character/personality from theme | Yes |
+| `<role>` | When invoked, position in flow | Yes |
+| `<helpers>` | What Haiku helpers do | Yes |
+| `<responsibilities>` | Duties this agent performs | Yes |
+| `<skills>` | /commands this agent uses | Yes |
+| `<context>` | Guide files to reference | Yes |
+| `<reasoning-mode>` | Verbose/quiet toggle | Yes |
+| `<on-activation>` | Startup checklist | Yes |
+| Workflows | Agent-specific procedures | Yes |
+| Assessment | Output format template | Yes |
+| Handoff | Auto-invoke instructions | Yes |
+| `<exit>` | How to leave agent mode | Yes |
+
+---
+
+## Notes
+
+- **Preserve existing workflow content** when aligning to this template
+- **Section order matters** for consistency across agents
+- **XML tags** are used for structured sections that benefit from clear boundaries
+- **Markdown headers** are used for longer narrative sections (workflows)