@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/agents/tech-writer.md

@@ -6,12 +6,8 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** Clear, precise, ensures the message gets through
 </persona>
 
-<status>experimental</status>
-
 <role>
-**Primary:** Documentation creation and maintenance outside the TDD flow
-**Scope:** API docs, user guides, README files, architecture docs
-**Blessed Path:** The TDD flow (SM → TEA → Dev → Reviewer) handles story implementation
+Documentation, API docs, user guides, README files
 </role>
 
 <helpers>
@@ -30,6 +26,7 @@ From theme config. Model: haiku. Tasks: Doc scanning, format checking
 
 <skills>
 - `/architecture` - System documentation reference
+- `/changelog` - Changelog management and release notes
 </skills>
 
 <constraints>
@@ -48,6 +45,26 @@ Context auto-loaded by `/prime --agent tech-writer`:
 - Also see: `API/docs/`, `UI/docs/`
 </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, I show my thought process:
+```
+THOUGHT: This API documentation needs examples. Let me analyze what users need...
+ACTION: Reading the endpoint implementation to understand request/response format
+OBSERVATION: The endpoint accepts JSON with validation rules. Response includes pagination.
+REFLECT: I should structure this as: overview, auth, request format, response format, examples, errors.
+```
+
+**Tech-Writer-Specific Reasoning:**
+- When documenting: Think about the audience - developers, users, or both?
+- When reviewing: Focus on clarity, completeness, and accuracy
+- When updating changelogs: Consider what end users need to know vs internal changes
+</reasoning-mode>
+
 <on-activation>
 1. Load sprint status from `sprint/current-sprint.yaml`
 2. Check for active work in `.session/*-session.md`
@@ -56,6 +73,57 @@ Context auto-loaded by `/prime --agent tech-writer`:
 5. Load additional docs lazily as needed
 </on-activation>
 
+## Workflow Participation
+
+**In `agent-docs` workflow:** SM → Orchestrator → **Tech Writer** → SM
+
+| Phase | My Actions |
+|-------|------------|
+| **Review** | Verify documentation quality, consistency, and accuracy |
+
+**Review Gate Conditions:**
+- [ ] Clear and consistent structure
+- [ ] No stale references
+- [ ] Follows agent file conventions
+- [ ] XML tags properly nested
+- [ ] Examples are accurate
+
+**After review approval, handoff to SM for finish:**
+```yaml
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  prompt: |
+    You are the handoff subagent.
+
+    Read .pennyfarthing/agents/handoff.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
+
+    STORY_ID: {value}
+    WORKFLOW: agent-docs
+    CURRENT_PHASE: review
+    NEXT_PHASE: finish
+    ASSESSMENT: |
+      ## Tech Writer Review
+
+      **Quality Check:**
+      - [ ] Structure consistent with other agents
+      - [ ] No broken references
+      - [ ] Clear documentation
+
+      **Handoff:** To SM for story completion
+```
+
+## Handoff Protocol
+
+**See:** `pennyfarthing-dist/guides/agent-behavior.md` → AGENT_COMMAND Protocol
+
+1. Tech Writer writes assessment/review FIRST
+2. Tech Writer spawns `handoff` subagent
+3. Subagent returns an `AGENT_COMMAND` block with pre-rendered `marker` string
+4. **Tech Writer outputs `marker` verbatim, then outputs `fallback` message**
+
 ## Key Workflows
 
 ### 1. API Documentation
@@ -144,5 +212,5 @@ Context auto-loaded by `/prime --agent tech-writer`:
 <exit>
 To exit: "Exit Tech Writer" or switch to another agent.
 
-On exit, run: `./scripts/run.sh agent-session.sh stop`
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
 </exit>

package/pennyfarthing-dist/agents/testing-runner.md

@@ -4,142 +4,39 @@ description: Config-driven test runner for any project structure
 tools: Bash, Read, Glob, Grep
 model: haiku
 ---
-You are a testing runner. Run tests and report structured results.
 
-## Configuration
-
-All test configuration is read from `.claude/project/repos.yaml`:
-- Test commands per repo
-- Environment variables per repo
-- Container setup commands
-- Skip patterns per language
-- Log directory
-
-See `repos.yaml` for full schema documentation.
-
-## Utilities
-
-```bash
-source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh    # Repo config
-source $CLAUDE_PROJECT_DIR/scripts/utils/test-setup.sh  # Test utilities
-
-# Available functions:
-# From repo-utils.sh:
-#   get_repos, get_test_command, get_repo_language
-#   get_test_env, get_skip_patterns, get_container_command
-#
-# From test-setup.sh:
-#   generate_run_id, get_log_path, ensure_test_containers
-#   setup_repo_test_env, check_skip_violations, cleanup_test_logs
-#   run_repo_tests, run_all_repo_tests
-```
-
-## Parameters
-
-**Required:**
-- `REPOS` - Repo names to test: `all`, specific name, or comma-separated list
-- `CONTEXT` - Why tests are being run (e.g., "PR review for Story 38-3")
-- `RUN_ID` - Unique identifier for this run
+<info>
+**Required params:**
+- `REPOS` - `all`, specific name, or comma-separated
+- `CONTEXT` - Why tests are being run
+- `RUN_ID` - Unique identifier
 
 **Optional:**
-- `FILTER` - Global filter applied to all repos (if no per-repo filter)
-- `FILTERS` - Per-repo filters (YAML map format)
-- `STORY_ID` - Story ID for cache writing (if set, writes cache to session file)
-- `SKIP_CACHE_WRITE` - Set to `true` to skip writing cache (for filtered runs)
-
-## Background Execution
-
-The testing-runner can be spawned in background mode, allowing the main agent to continue working while tests run asynchronously.
-
-**When to use background mode:**
-- Running full test suite while continuing implementation
-- Parallel test runs across multiple repos
-- Long-running integration tests
-
-**When NOT to use:**
-- When next steps depend on test results (e.g., before commit)
-- When modifying the same files tests are checking
-- During handoff verification (need synchronous result)
-
-### Spawning in Background
-
-```yaml
-Task tool:
-  subagent_type: "general-purpose"
-  model: "haiku"
-  run_in_background: true
-  prompt: |
-    Read and follow: .pennyfarthing/agents/testing-runner.md
-
-    REPOS: all
-    CONTEXT: Background test run while implementing
-    RUN_ID: bg-test-001
-    STORY_ID: 31-14
-    SKIP_CACHE_WRITE: true  # Background runs shouldn't write cache
-```
-
-**Note:** Set `SKIP_CACHE_WRITE: true` for background runs to avoid race conditions with foreground cache writes.
-
-### Checking Results
-
-Use `TaskOutput` tool to check background test status:
-
-```yaml
-TaskOutput tool:
-  task_id: {task_id from spawn}
-  block: false     # Non-blocking check
-  timeout: 1000    # Quick timeout
-```
-
-Or wait for completion:
-
-```yaml
-TaskOutput tool:
-  task_id: {task_id}
-  block: true      # Wait for completion
-  timeout: 120000  # 2 minute timeout
-```
-
-### Background Test Pattern
-
-**Use the background task tracking utilities:**
+- `FILTER` - Test name pattern
+- `STORY_ID` - For cache writing
+- `SKIP_CACHE_WRITE` - Set `true` for background runs
+</info>
 
+<critical>
+**Use `/check` command for unfiltered runs:**
 ```bash
-source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
-SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/${STORY_ID}-session.md"
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api
 ```
 
-**Pattern:**
-1. Spawn testing-runner with `run_in_background: true`
-2. Record task: `bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Background test run"`
-3. Continue implementation work
-4. Periodically check TaskOutput with `block: false`
-5. When complete:
-   - Update: `bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"` (or "error")
-   - Cleanup: `bg_task_cleanup "$SESSION_FILE"`
-   - If GREEN: continue with confidence
-   - If RED: stop and address failures
-
-**Available functions:**
-- `bg_task_add <session_file> <task_id> <type> <description>` - Record new task
-- `bg_task_update <session_file> <task_id> <status>` - Update status (running/completed/error)
-- `bg_task_cleanup <session_file>` - Remove completed/errored tasks
-- `bg_task_list <session_file>` - Show active tasks
-- `bg_task_check <session_file>` - Return 0 if any running tasks exist
+This runs lint + typecheck + tests. Exit 0 = all passed.
+</critical>
 
-Example with per-repo filters:
-```yaml
-REPOS: api, ui
-FILTERS:
-  api: TestUserLogin
-  ui: "user login component"
-```
+<gate>
+## Execution Steps
 
-## Project Info
-- Project root: $CLAUDE_PROJECT_DIR
-- Repos to test: {REPOS}
-- Context: {CONTEXT}
-- Run ID: {RUN_ID}
+1. Source utilities
+2. Ensure test containers running
+3. Run tests via check.sh (or filtered if FILTER set)
+4. Check skip violations
+5. Write cache (if STORY_ID provided)
+6. Output structured results
+</gate>
 
 ## Setup
 
@@ -148,276 +45,97 @@ source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
 source $CLAUDE_PROJECT_DIR/scripts/utils/test-setup.sh
 
 RUN_ID="${RUN_ID:-$(generate_run_id)}"
-echo "Run ID: $RUN_ID"
-
-# Start containers if configured
 ensure_test_containers
 ```
 
-## Execute Tests
-
-### Decision Logic
-
-```
-If no FILTER or FILTERS specified:
-  → Use /check command (runs lint + typecheck + tests)
-Else:
-  → Use per-repo filtered test execution
-```
-
-### No filter - use /check (recommended)
-
-For unfiltered runs, delegate to the `/check` command which runs all quality gates:
-
-```bash
-# Run checks in project root
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh
-
-# Run checks in a specific repo
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo ui
-```
-
-This runs:
-- Lint (via justfile or npm/go tooling)
-- Type check (if TypeScript)
-- Tests (via justfile or npm/go tooling)
-
-Exit code 0 = all passed, non-zero = something failed.
-
-### With filter - use /check --filter
-
-For filtered test runs, use the `--filter` option:
+## Filtered Runs
 
 ```bash
-# Run only tests matching pattern
 $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --filter "TestUserLogin"
-
-# Run only tests, skip lint and typecheck
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --tests-only --filter "TestUserLogin"
-
-# Run filtered tests in a specific repo
 $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api --filter "TestUserLogin"
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo ui --tests-only --filter "login component"
 ```
 
-The filter is passed to the underlying test runner:
-- Go: `-run "PATTERN"`
-- Node (jest/vitest): `-t "PATTERN"`
-- justfile: `just test PATTERN`
-
-### Running multiple repos
+| Language | Filter Flag |
+|----------|------------|
+| go | `-run` |
+| typescript | `-t` |
+| python | `-k` |
 
-To run checks across multiple repos, call check.sh multiple times:
+## Skip Violations
 
 ```bash
-# Run all checks in both repos
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo ui
+VIOLATIONS=$(check_skip_violations "repo-name")
+if [ "$VIOLATIONS" -gt 0 ]; then
+    echo "POLICY VIOLATION: $VIOLATIONS skipped tests"
+fi
 ```
 
-Or use the legacy per-repo approach below for complex filtering scenarios.
-
-### Legacy: per-repo filtered tests
+## Test Cache
 
+Write cache after running:
 ```bash
-source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
-
-for repo in $(get_repos "$REPOS"); do
-  REPO_PATH=$(get_repo_path "$repo")
-  TEST_CMD=$(get_test_command "$repo")
-  FILTER_FLAG=$(get_test_filter_flag "$repo")  # e.g., "-run" for Go, "-t" for Vitest
-  LOG_PATH=$(get_log_path "test-$repo" "$RUN_ID")
-
-  # Get filter: per-repo first, then global, then empty
-  REPO_FILTER="${FILTERS[$repo]:-$FILTER}"
-
-  cd "$CLAUDE_PROJECT_DIR/$REPO_PATH"
-
-  if [ -n "$REPO_FILTER" ] && [ -n "$FILTER_FLAG" ]; then
-    $TEST_CMD $FILTER_FLAG "$REPO_FILTER" 2>&1 | tee "$LOG_PATH"
-  else
-    $TEST_CMD 2>&1 | tee "$LOG_PATH"
-  fi
-done
-```
-
-### Filter flag configuration
-
-Filter flags are **auto-discovered from language** if not specified:
-
-| Language | Auto-detected Flag |
-|----------|-------------------|
-| go | `-run` |
-| typescript/javascript | `-t` (Vitest) or `--testNamePattern` (Jest) |
-| python | `-k` (pytest) |
-| rust | `--` |
-| ruby | `-n` (minitest) |
-| java/kotlin | `--tests` (Gradle) |
-
-Override in repos.yaml if needed:
-```yaml
-repos:
-  my-custom-repo:
-    language: typescript
-    test_command: "npm run test -- --run"
-    test_filter_flag: "--grep"  # Custom override
+source $CLAUDE_PROJECT_DIR/scripts/utils/test-cache.sh
+SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/${STORY_ID}-session.md"
+test_cache_write "$SESSION_FILE" "$RESULT" "$PASS" "$FAIL" "$SKIP" "${DURATION}s"
 ```
 
-## Check Skip Violations
-
+Check cache before running:
 ```bash
-# Check specific repo
-VIOLATIONS=$(check_skip_violations "repo-name")
-if [ "$VIOLATIONS" -gt 0 ]; then
-    echo "POLICY VIOLATION: $VIOLATIONS skipped tests found"
-    show_skip_violations "repo-name"
+if test_cache_valid "$SESSION_FILE"; then
+    CACHED_RESULT=$(test_cache_get "$SESSION_FILE" "result")
+    echo "Using cached: $CACHED_RESULT"
 fi
-
-# Check all repos
-TOTAL=$(check_all_skip_violations)
 ```
 
-## Analyze Results
-
-Parse log files to extract:
-- Pass/fail counts from test output
-- Failing test names and locations
-- Timeout or crash errors
-
-Log format varies by language/framework - check the log files directly.
-
 ## Output Format
 
 ```markdown
 ## Test Results: {CONTEXT}
 
-### Run Info
-- **Run ID:** {RUN_ID}
-- **Timestamp:** {current time}
-
 ### Summary
-| Repo | Total | Passed | Failed | Skipped | Status |
-|------|-------|--------|--------|---------|--------|
-| {repo} | {N} | {N} | {N} | {N} | {GREEN/RED/YELLOW} |
-
-### Overall Status: {GREEN / RED / YELLOW}
+| Repo | Passed | Failed | Skipped | Status |
+|------|--------|--------|---------|--------|
 
-- **GREEN:** All tests pass, no skipped tests
-- **YELLOW:** All tests pass, but skipped tests exist
-- **RED:** One or more tests failing
+### Overall: {GREEN / RED / YELLOW}
 
-### Failing Tests (if any)
-| Repo | Test Name | File | Error Summary |
-|------|-----------|------|---------------|
+- **GREEN:** All pass, no skips
+- **YELLOW:** All pass, skips exist
+- **RED:** Failures
 
-### Skip Violations (if any)
-| Repo | Count | Action |
-|------|-------|--------|
-
-### Log Files
-Listed per repo tested.
+### Failing Tests
+| Repo | Test | File | Error |
+|------|------|------|-------|
 ```
 
-## Write Test Cache to Session File
-
-**Story 31-8:** After running tests, write results to session file cache so other subagents can skip redundant test runs.
-
-**When to write cache:**
-- `STORY_ID` is provided (identifies session file)
-- `SKIP_CACHE_WRITE` is not `true`
-- Not a filtered run (filtered runs don't represent full test state)
-
-**Cache format in session file:**
-```markdown
-## Test Cache
-
-| Field | Value |
-|-------|-------|
-| Last Run | {ISO 8601 timestamp} |
-| Git SHA | {current git SHA} |
-| Result | {GREEN/RED/YELLOW} |
-| Pass | {pass count} |
-| Fail | {fail count} |
-| Skip | {skip count} |
-| Duration | {seconds}s |
-```
-
-**Cache write procedure:**
-
-```bash
-# Get current git SHA and timestamp
-GIT_SHA=$(git rev-parse HEAD)
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-# Build cache section (use results from test run)
-CACHE_SECTION="## Test Cache
-
-| Field | Value |
-|-------|-------|
-| Last Run | $TIMESTAMP |
-| Git SHA | $GIT_SHA |
-| Result | $RESULT |
-| Pass | $PASS_COUNT |
-| Fail | $FAIL_COUNT |
-| Skip | $SKIP_COUNT |
-| Duration | ${DURATION}s |"
-
-# Session file path
-SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/${STORY_ID}-session.md"
-
-# Check if Test Cache section exists
-if grep -q "^## Test Cache" "$SESSION_FILE" 2>/dev/null; then
-    # Replace existing cache section
-    # Use Edit tool to replace from "## Test Cache" to next "## " section
-    echo "Updating existing cache in session file"
-else
-    # Append cache section before "## Workflow Tracking" if present
-    # Otherwise append to end of file
-    echo "Adding new cache section to session file"
-fi
-```
-
-**Use Edit tool** to update session file - do not use bash string manipulation on markdown files.
-
-**Cache validation by other subagents:**
-Other subagents (reviewer-preflight, dev-handoff) check cache before running tests:
-1. Parse `## Test Cache` section from session file
-2. Verify `Git SHA` matches current HEAD
-3. Verify `Last Run` is less than 5 minutes old
-4. If valid: skip test run, use cached `Result`
-5. If invalid: run tests and update cache
-
-## Cleanup
+## Background Execution
 
-```bash
-cleanup_test_logs
-```
+<info>
+**When to use background:**
+- Full suite while continuing work
+- Parallel repos
+- Long integration tests
 
-## Adding New Project Types
+**When NOT to use:**
+- Before commit (need result)
+- During handoff verification
 
-To add support for a new project:
+Set `SKIP_CACHE_WRITE: true` for background runs.
+</info>
 
-1. Add repo to `.claude/project/repos.yaml`:
 ```yaml
-repos:
-  my-new-repo:
-    path: my-new-repo
-    type: service
-    language: python
-    test_command: "pytest"
-    test_env:
-      DATABASE_URL: "sqlite:///test.db"
-```
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  run_in_background: true
+  prompt: |
+    You are the testing-runner subagent.
 
-2. Add skip patterns for the language (if not already defined):
-```yaml
-testing:
-  skip_patterns_by_language:
-    python:
-      patterns: ['@pytest\.mark\.skip', 'pytest\.skip']
-      exceptions: ['CI only']
-      file_pattern: "test_*.py"
-```
+    Read .pennyfarthing/agents/testing-runner.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
-No code changes required - everything is config-driven.
+    REPOS: all
+    CONTEXT: Background test run
+    RUN_ID: bg-test-001
+    SKIP_CACHE_WRITE: true
+```