@pennyfarthing/core 7.6.1 → 7.7.0

package/pennyfarthing-dist/agents/workflow-status-check.md

@@ -10,6 +10,12 @@ Universal entry point telling agents: what work exists, what phase, and whether
 Uses `/sprint` skill scripts for deterministic output.
 </info>
 
+<arguments>
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `CALLING_AGENT` | Yes | Agent requesting status check (e.g., "SM", "Architect", "PM") |
+</arguments>
+
 ---
 
 ## Execution
@@ -45,24 +51,36 @@ fi
 
 ---
 
+<output>
 ## Output Format
 
-```markdown
-## Workflow Status Report
-
-### Detected State
-**{STATE}**
-
-### Sprint Summary
-[Output from sprint-status.sh]
+Return a `STATUS_CHECK_RESULT` block:
 
-### Active Session
-| Story | Phase | Status | Branch |
-|-------|-------|--------|--------|
+### Success
+```
+STATUS_CHECK_RESULT:
+  status: success
+  state: {FINISH_STATE|IN_PROGRESS_STATE|NEW_WORK_STATE|EMPTY_BACKLOG_STATE}
+  story_id: {ID or null}
+  phase: {current phase or null}
+  phase_owner: {agent name or null}
+  sprint_number: {N}
+  backlog_count: {N}
+
+  next_steps:
+    - FINISH_STATE: "Proceed to Finish Flow - spawn sm-finish with PHASE=preflight"
+    - IN_PROGRESS_STATE: "Report phase owner '{phase_owner}' should continue. Run handoff-marker.sh {phase_owner}"
+    - NEW_WORK_STATE: "Present available stories to user. Await selection, then spawn sm-setup MODE=setup"
+    - EMPTY_BACKLOG_STATE: "Report backlog empty. Suggest promoting from future.yaml"
+```
 
-### Recommended Action
-- FINISH_STATE → Proceed to finish flow
-- IN_PROGRESS_STATE → Report which agent should continue
-- NEW_WORK_STATE → Show available stories
-- EMPTY_BACKLOG_STATE → Suggest promoting stories from future.yaml
+### Active Session Details (if IN_PROGRESS_STATE)
+```
+  session:
+    story_id: {ID}
+    title: "{title}"
+    workflow: {workflow}
+    phase: {phase}
+    branch: {branch}
 ```
+</output>

package/pennyfarthing-dist/commands/benchmark.md

@@ -151,7 +151,11 @@ Cross-role mode: Prospero --as dev should see dev scenarios, not SM scenarios.
 ls scenarios/{category}/*.yaml | xargs -I {} yq -r '"{}|\(.name)|\(.difficulty)|\(.title)|\(.description)"' {}
 ```
 
-**Present choices with AskUserQuestion:**
+**Present choices (Reflector-aware):**
+
+First output marker: `<!-- CYCLIST:CHOICES:scenario -->`
+
+Then use AskUserQuestion:
 ```yaml
 AskUserQuestion:
   questions:
@@ -416,6 +420,20 @@ agent:
   cross_role: true
 ```
 
+**REQUIRED: Capture Pennyfarthing version in metadata:**
+```bash
+# Get version from package.json
+version=$(node -p "require('./package.json').version")
+```
+
+Include in summary.yaml:
+```yaml
+metadata:
+  created_at: "{ISO timestamp}"
+  pennyfarthing_version: "{version}"  # REQUIRED for baseline staleness detection
+  model: sonnet
+```
+
 **ALWAYS save summary.yaml, even for n=1.** This ensures consistent data structure for analysis.
 
 Display:

package/pennyfarthing-dist/commands/continue-session.md

@@ -58,7 +58,7 @@ If checkpoints exist, parse and present them:
 Which checkpoint would you like to restore? (Enter number or 'all' for most recent of each label)
 ```
 
-Use `AskUserQuestion` to let user choose.
+Output `<!-- CYCLIST:CHOICES:checkpoint -->` marker, then use AskUserQuestion to let user choose.
 
 ## Step 3: Restore Checkpoint
 

package/pennyfarthing-dist/commands/solo.md

@@ -380,6 +380,11 @@ else:
      avg_output_tokens: {avg_out}
      tokens_per_point: {tpp:.2f}
 
+   metadata:
+     created_at: {ISO8601 timestamp}
+     pennyfarthing_version: {version from package.json}  # REQUIRED
+     model: sonnet
+
    # Include baseline comparison if baseline exists and theme != control
    baseline_comparison:
      control_mean: {baseline_mean}

package/pennyfarthing-dist/commands/theme-maker.md

@@ -28,7 +28,7 @@ If invalid, explain the rules and ask again.
 
 ### Step 2: Mode Selection
 
-Use `AskUserQuestion` to let the user choose their creation mode:
+Output `<!-- CYCLIST:CHOICES:mode -->` marker, then use AskUserQuestion:
 
 ```yaml
 questions:
@@ -253,7 +253,7 @@ Display a preview of all generated agents before confirming:
 
 ### Step 4: Confirm or Regenerate
 
-Use `AskUserQuestion` to let the user decide:
+Output `<!-- CYCLIST:CHOICES:confirm -->` marker, then use AskUserQuestion:
 
 ```yaml
 questions:
@@ -380,7 +380,7 @@ Same as AI-Driven mode - ask for the theme concept:
 
 ### Step 2: Generate Options for Each Agent
 
-For each agent type, generate 3-4 fitting character suggestions based on the universe. Present options using `AskUserQuestion`:
+For each agent type, generate 3-4 fitting character suggestions based on the universe. Output `<!-- CYCLIST:CHOICES:agent -->` marker, then present options using AskUserQuestion:
 
 ```yaml
 questions:
@@ -458,7 +458,7 @@ Show a preview of the complete theme before confirming. Include OCEAN scores for
 
 ### Step 5: Confirm or Edit
 
-Use `AskUserQuestion` to let the user decide:
+Output `<!-- CYCLIST:CHOICES:confirm -->` marker, then use AskUserQuestion:
 
 ```yaml
 questions:
@@ -608,7 +608,7 @@ Show a preview of the complete theme including OCEAN profiles:
 
 ### Step 6: Confirm or Edit
 
-Use `AskUserQuestion` to let the user decide:
+Output `<!-- CYCLIST:CHOICES:confirm -->` marker, then use AskUserQuestion:
 
 ```yaml
 questions:

package/pennyfarthing-dist/commands/work.md

@@ -113,7 +113,7 @@ If multiple session files exist (parallel work):
 Which would you like to continue?
 ```
 
-Use AskUserQuestion to let user choose, then invoke appropriate agent.
+Output `<!-- CYCLIST:CHOICES:session -->` marker, then use AskUserQuestion to let user choose, then invoke appropriate agent.
 </multiple-sessions>
 
 <reference>

package/pennyfarthing-dist/guides/XML-TAGS.md

@@ -116,6 +116,185 @@ Tags that organize agent content.
 
 **Purpose:** How to leave agent mode and cleanup.
 
+## Workflow Tags (TDD Agents)
+
+Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Reviewer).
+
+### `<phase-check>`
+
+**Purpose:** Verify agent owns the current workflow phase before proceeding. Prevents agents from acting on stories they shouldn't own.
+
+**Usage:** SM, TEA, Dev, Reviewer - runs `phase-owner.sh` on activation to determine correct owner.
+
+```markdown
+<phase-check>
+## On Startup: Check Phase
+
+Read `**Workflow:**` and `**Phase:**` from session. Query:
+```bash
+OWNER=$(.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+```
+
+**If OWNER != "dev":** Run `handoff-marker.sh $OWNER`, output result, tell user.
+</phase-check>
+```
+
+### `<handoff-gate>`
+
+**Purpose:** Exit checklist that MUST be completed before handoff. Ensures assessment is written and subagent is spawned.
+
+**Usage:** TEA, Dev, Reviewer - mandatory checklist before exiting.
+
+```markdown
+<handoff-gate>
+## MANDATORY: Complete Before Exiting
+
+- [ ] Write Assessment to session file
+- [ ] Spawn `handoff` subagent
+- [ ] Verify handoff completed (subagent emits marker)
+</handoff-gate>
+```
+
+**Difference from `<gate>`:** `<handoff-gate>` is specifically for phase transitions; `<gate>` is for general prerequisites.
+
+### `<handoffs>`
+
+**Purpose:** Documents handoff relationships for strategic agents that coordinate but don't participate in the TDD cycle.
+
+**Usage:** PM, Architect, DevOps, Tech-Writer, UX-Designer, Orchestrator.
+
+```markdown
+<handoffs>
+### From PM/SM
+**When:** Epic needs architectural design
+**Input:** Business requirements, constraints
+**Action:** Design solution and provide guidance
+
+### To Dev
+**When:** Design is complete
+**Output:** Architecture decision and implementation plan
+</handoffs>
+```
+
+## Subagent Tags
+
+Tags used specifically by Haiku subagents for parameter contracts.
+
+### `<params>`
+
+**Purpose:** Define the parameter contract for subagents. Specifies what the calling agent must provide in the prompt.
+
+**Usage:** Subagents only (sm-setup, sm-finish, sm-handoff, sm-file-summary, handoff, testing-runner, reviewer-preflight).
+
+**Standard format (table):**
+```markdown
+<params>
+| Param | Required | Description |
+|-------|----------|-------------|
+| `STORY_ID` | Yes | Story identifier, e.g., "31-10" |
+| `WORKFLOW` | Yes | Workflow type: "tdd", "trivial", etc. |
+| `FILTER` | No | Test name pattern for filtered runs |
+</params>
+```
+
+**Note:** Use `<info>` for contextual information that isn't a parameter contract.
+
+### `<output>`
+
+**Purpose:** Define the standardized output format for subagents. Ensures calling agents receive both data AND instructions on what to do next.
+
+**Usage:** All subagents must use this format for their final output.
+
+**Standard format:**
+```markdown
+<output>
+## Output Format
+
+Return a `{SUBAGENT}_RESULT` block:
+
+### Success
+\`\`\`
+{SUBAGENT}_RESULT:
+  status: success
+  {data fields...}
+
+  next_steps:
+    - {instruction 1}
+    - {instruction 2}
+\`\`\`
+
+### Blocked
+\`\`\`
+{SUBAGENT}_RESULT:
+  status: blocked
+  error: "{description}"
+  fix: "{recommended action}"
+
+  next_steps:
+    - {what caller should do}
+\`\`\`
+</output>
+```
+
+**Required fields:**
+- `status`: `success` | `blocked` | `warning`
+- `next_steps`: Array of instructions for the calling agent
+
+**Why this matters:** Subagent output is NOT visible to users (only to the calling agent). Clear next steps ensure the caller knows exactly what to do with the result.
+
+## Specialized Tags (Single-Agent Use)
+
+Tags used by specific agents for their unique responsibilities.
+
+### `<adversarial-mindset>`
+
+**Purpose:** Sets skeptical review stance. Establishes the reviewer's critical, problem-hunting approach.
+
+**Usage:** Reviewer-only.
+
+```markdown
+<adversarial-mindset>
+**You are not here to approve code. You are here to find problems.**
+
+Assume the code is broken until you prove otherwise.
+**Default stance:** Skeptical. Suspicious. Looking for the flaw.
+</adversarial-mindset>
+```
+
+### `<review-checklist>`
+
+**Purpose:** Mandatory review steps the Reviewer must complete before making a judgment.
+
+**Usage:** Reviewer-only.
+
+```markdown
+<review-checklist>
+## MANDATORY Review Steps
+
+- [ ] **Trace data flow:** Pick a user input, follow it end-to-end
+- [ ] **Verify error handling:** What happens on failure?
+- [ ] **Security analysis:** Auth checks? Input sanitization?
+- [ ] **Make judgment:** APPROVE only if no Critical/High issues
+</review-checklist>
+```
+
+### `<self-review>`
+
+**Purpose:** Pre-handoff quality check for Dev to verify implementation before passing to Reviewer.
+
+**Usage:** Dev-only.
+
+```markdown
+<self-review>
+## Self-Review Before Handoff
+
+- [ ] Code is wired to front end or other components
+- [ ] Code follows project patterns
+- [ ] All acceptance criteria met
+- [ ] Tests passing (not skipped!)
+</self-review>
+```
+
 ## Usage Guidelines
 
 1. **`<critical>` sparingly** - If everything is critical, nothing is. Reserve for true invariants.

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -151,6 +151,10 @@ overrides:
 
 ## Reflector
 
+<critical>
+**EVERY TURN MUST END WITH A CYCLIST MARKER.** A Stop hook enforces this - you will be blocked if you forget.
+</critical>
+
 <info>
 HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:value -->`
 
@@ -160,6 +164,7 @@ HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:
 | `CONTEXT_CLEAR` | `/agent` | Clears session, reloads with agent |
 | `QUESTION` | `yesno` or `open` | Shows input dialog |
 | `CHOICES` | `opt1,opt2,opt3` | Shows choice buttons |
+| `CONTINUE` | (none) | Shows "Continue" button for status updates |
 
 **Examples:**
 ```
@@ -168,30 +173,38 @@ HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:
 <!-- CYCLIST:QUESTION:yesno -->
 <!-- CYCLIST:QUESTION:open -->
 <!-- CYCLIST:CHOICES:option1,option2,option3 -->
+<!-- CYCLIST:CONTINUE -->
 ```
 
 **When to use:**
 - `HANDOFF` - End of phase (TEA→Dev, Dev→Reviewer)
 - `CONTEXT_CLEAR` - Context >80% at handoff
 - `QUESTION`/`CHOICES` - User input needed mid-work
+- `CONTINUE` - Status updates, task completion, any turn that isn't a handoff or question
 </info>
 
 <critical>
-**Question Reflector Enforcement:** A Stop hook validates that ANY question to the user has a reflector marker. Emit the marker BEFORE your question.
-
-**Question types requiring markers:**
+**Marker Selection Guide:**
+
+| Situation | Marker |
+|-----------|--------|
+| Workflow handoff to next agent | `<!-- CYCLIST:HANDOFF:/agent -->` |
+| Handoff with context >80% | `<!-- CYCLIST:CONTEXT_CLEAR:/agent -->` |
+| Yes/no question | `<!-- CYCLIST:QUESTION:yesno -->` |
+| Open-ended question | `<!-- CYCLIST:QUESTION:open -->` |
+| Multiple choice | `<!-- CYCLIST:CHOICES:a,b,c -->` |
+| Status update / task complete | `<!-- CYCLIST:CONTINUE -->` |
+| Providing information | `<!-- CYCLIST:CONTINUE -->` |
+| Reporting an error/blocker | `<!-- CYCLIST:CONTINUE -->` |
+
+**Question types requiring QUESTION/CHOICES markers:**
 - Direct questions ending with `?`
 - Implicit questions: "let me know if...", "would you like...", "should I..."
 - Choice offerings: "Option A or Option B"
 - Requests for input: "what do you think", "your preference"
 - Clarification requests: "could you clarify"
 
-**Marker selection:**
-- `<!-- CYCLIST:QUESTION:yesno -->` - Yes/no questions
-- `<!-- CYCLIST:QUESTION:open -->` - Open-ended questions
-- `<!-- CYCLIST:CHOICES:a,b,c -->` - Multiple choice (list options)
-
-**Exempt (no marker needed):**
+**Exempt from question detection (but still need CONTINUE):**
 - Rhetorical questions you answer yourself
 - Questions inside code blocks or examples
 - Historical context ("the question was...")