@pennyfarthing/core 7.0.1 → 7.4.0

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

@@ -1,193 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
-# 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

@@ -1,162 +0,0 @@
-# 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)