@pennyfarthing/core 7.6.0 → 7.7.0

package/pennyfarthing-dist/agents/sm-finish.md

@@ -5,57 +5,78 @@ tools: Bash, Read
 model: haiku
 ---
 
-<info>
-**Story:** {STORY_ID}
-**Jira:** {JIRA_KEY} (optional)
-**Repos:** {REPOS}
-**Branch:** {BRANCH}
-</info>
+<arguments>
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `STORY_ID` | Yes | Story identifier, e.g., "31-10" |
+| `JIRA_KEY` | No | Jira issue key (skip Jira checks if absent) |
+| `REPOS` | Yes | Repository name(s) |
+| `BRANCH` | Yes | Feature branch name |
+</arguments>
 
-<critical>
-Run ALL checks in parallel, then aggregate results.
-</critical>
+<execution>
+## Run Preflight Script
 
-<gate>
-## Parallel Checks
+The preflight script runs all checks in parallel using asyncio:
 
-1. **PR Status:** `gh pr view {BRANCH} --json state,merged,mergeable,url`
-2. **Lint:** `npm run lint`
-3. **Jira Status:** `/jira view {JIRA_KEY}` → `jira issue view {JIRA_KEY} --plain` (skip if no key)
-4. **Acceptance Criteria:** grep checkboxes from session file
-5. **Cleanup:** remove temp files from `.session/`
-</gate>
+```bash
+source .venv/bin/activate && python -m pennyfarthing_scripts.preflight finish {STORY_ID} --branch {BRANCH} --jira {JIRA_KEY}
+```
 
-## Jira Transition
+If no JIRA_KEY, omit the `--jira` flag.
+
+The script returns JSON with:
+- `status`: "success" or "blocked"
+- `ready_to_finish`: boolean
+- `issues`: array of blocking issues
+- `warnings`: array of non-blocking warnings
+- `next_steps`: array of recommended actions
+</execution>
 
 <critical>
+## Jira Transition
+
 The Jira transition to Done is handled by `/story finish` (finish-story.sh).
 Do NOT transition Jira here - that would duplicate the finish script's work.
 This subagent only performs preflight checks and assessment.
 </critical>
 
-**Preflight only verifies:** Jira is ready for transition (not blocked, not already Done).
+<output>
+## Output Format
 
-## Readiness Report
+Parse the JSON output from the preflight script and return a `FINISH_PREFLIGHT_RESULT` block.
 
-```json
-{
-  "pr_status": "merged|open|NO_PR",
-  "lint_status": "clean|failed",
-  "jira_current": "In Progress|Done|N/A",
-  "acceptance_criteria": { "total": N, "checked": N },
-  "ready_to_finish": true|false,
-  "issues": [],
-  "warnings": []
-}
+### Ready to Finish
+```yaml
+FINISH_PREFLIGHT_RESULT:
+  status: success
+  ready_to_finish: true
+  story_id: "{story_id from JSON}"
+  pr:
+    state: "{pr.state from JSON}"
+    merged: {pr.merged from JSON}
+    url: "{pr.url from JSON}"
+  lint:
+    clean: {lint.clean from JSON}
+  jira:
+    current: "{jira.current from JSON}"
+    key: "{jira.key from JSON}"
+  acceptance_criteria:
+    total: {acceptance_criteria.total from JSON}
+    checked: {acceptance_criteria.checked from JSON}
+  next_steps: {next_steps array from JSON}
 ```
 
-<info>
-**ready_to_finish = true when:**
-- PR merged (or acceptable for trivial)
-- Lint clean
-- All ACs checked
-- No critical issues
+### Not Ready
+```yaml
+FINISH_PREFLIGHT_RESULT:
+  status: blocked
+  ready_to_finish: false
+  issues: {issues array from JSON}
+  warnings: {warnings array from JSON}
+  next_steps: {next_steps array from JSON}
+```
 
-**Jira skipped:** Set `jira_skipped: true` if no valid key.
-</info>
+### Jira Skipped
+If `jira_skipped: true` in JSON, note this in output.
+</output>

package/pennyfarthing-dist/agents/sm-handoff.md

@@ -19,24 +19,27 @@ This subagent verifies prerequisites and updates session file only.
 Return `HANDOFF_RESULT` with the next agent name - SM runs `handoff-marker.sh` as their last action.
 </critical>
 
-<info>
-**From:** SM
-**To:** {NEXT_AGENT} (TEA or Dev)
-**Session:** `.session/{STORY_ID}-session.md`
-</info>
+<arguments>
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `STORY_ID` | Yes | Story identifier, e.g., "31-10" |
+| `NEXT_AGENT` | Yes | Target agent: `tea` or `dev` |
+| `NEXT_PHASE` | Yes | Target phase: `red` (TEA) or `implement` (Dev) |
+| `WORKFLOW` | Yes | Workflow type: "tdd", "trivial", etc. |
+</arguments>
 
 <gate>
 ## Handoff Checklist
 
-1. Session file exists with story context
-2. Acceptance criteria defined (count, don't mark)
-3. Feature branches created
-4. Jira story claimed (if applicable)
-5. Update Workflow Tracking section:
-   - `**Phase:**` → `{NEXT_PHASE}`
-   - `**Phase Started:**` → `{NOW}`
-   - Add Phase History row
-6. Report status summary
+- [ ] Session file exists with story context
+- [ ] Acceptance criteria defined (count, don't mark)
+- [ ] Feature branches created
+- [ ] Jira story claimed (if applicable)
+- [ ] Update Workflow Tracking section:
+  - `**Phase:**` → `{NEXT_PHASE}`
+  - `**Phase Started:**` → `{NOW}`
+  - Add Phase History row
+- [ ] Report status summary
 </gate>
 
 ## Phase Transition Update
@@ -58,51 +61,55 @@ Edit `## Workflow Tracking`:
 
 **Duration:** Subtract SM Started from {NOW}, format as `Xm` or `Xh Ym`.
 
+<output>
 ## Output Format
 
-Return a `HANDOFF_RESULT` block. SM will use this to run `handoff-marker.sh`.
-
-### Success Format
+Return a `HANDOFF_RESULT` block:
 
+### Success
 ```
 HANDOFF_RESULT:
   status: success
   next_agent: {NEXT_AGENT}
   next_phase: {NEXT_PHASE}
   story_id: {STORY_ID}
-  summary: "Session updated, branch verified, Jira claimed"
+  summary: "{what was done}"
+
+  next_steps:
+    - "Handoff complete. Run handoff-marker.sh as ABSOLUTE LAST ACTION."
+    - "Command: $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}"
+    - "Output marker result verbatim, then EXIT. Nothing after."
 ```
 
 ### Example (SM → TEA)
-
 ```
 HANDOFF_RESULT:
   status: success
   next_agent: tea
   next_phase: red
   story_id: MSSCI-12274
-  summary: "Session updated (setup → red), branch feat/MSSCI-12274-image-queue verified, 7 AC defined"
-```
-
-### Example (SM → Dev, trivial workflow)
+  summary: "Session updated (setup → red), branch verified, 7 AC defined"
 
-```
-HANDOFF_RESULT:
-  status: success
-  next_agent: dev
-  next_phase: implement
-  story_id: 46-3
-  summary: "Session updated (setup → implement), branch feat/46-3-fix-typo verified"
+  next_steps:
+    - "Handoff complete. Run handoff-marker.sh as ABSOLUTE LAST ACTION."
+    - "Command: $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh tea"
+    - "Output marker result verbatim, then EXIT. Nothing after."
 ```
 
-### Error Format
-
+### Blocked
 ```
 HANDOFF_RESULT:
   status: blocked
-  error: "{error message}"
+  error: "{description}"
   fix: "{recommended action}"
+  failed_check: "{which gate check failed}"
+
+  next_steps:
+    - "Handoff blocked: {error}"
+    - "Required action: {fix}"
+    - "Do NOT run handoff-marker.sh. Resolve issue first."
 ```
+</output>
 
 ---
 

package/pennyfarthing-dist/agents/sm-setup.md

@@ -5,10 +5,17 @@ tools: Bash, Read, Edit, Write
 model: haiku
 ---
 
-<info>
-**MODE: research** - Scan backlog for available stories
-**MODE: setup** - Execute story setup (Jira, branches, session)
-</info>
+<arguments>
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `MODE` | Yes | `research` (scan backlog) or `setup` (execute story setup) |
+| `STORY_ID` | setup | Story identifier, e.g., "31-10" |
+| `JIRA_KEY` | setup | Jira issue key, e.g., "MSSCI-12345" |
+| `REPOS` | setup | Repository name(s) |
+| `SLUG` | setup | Branch slug, e.g., "fix-typo" |
+| `WORKFLOW` | setup | Workflow type: "tdd", "trivial", etc. |
+| `ASSIGNEE` | No | Jira assignee (defaults to current user) |
+</arguments>
 
 ---
 
@@ -17,30 +24,45 @@ model: haiku
 <gate>
 ## Research Steps
 
-1. Use `/sprint backlog` for initial backlog scan:
-   ```bash
-   .pennyfarthing/scripts/core/run.sh sprint/available-stories.sh
-   ```
-2. Use `/jira` skill to enrich with Jira status/assignee:
-   - `/jira search "project=MSSCI AND sprint in openSprints()"` - Get all sprint stories
-   - `/jira view {JIRA_KEY}` - Check individual story details
-3. Check context availability
-4. Check dependencies
-5. Output report with recommendations
+- [ ] Use `/sprint backlog` for initial backlog scan:
+  ```bash
+  .pennyfarthing/scripts/core/run.sh sprint/available-stories.sh
+  ```
+- [ ] Use `/jira` skill to enrich with Jira status/assignee:
+  - `/jira search "project=MSSCI AND sprint in openSprints()"` - Get all sprint stories
+  - `/jira view {JIRA_KEY}` - Check individual story details
+- [ ] Check context availability
+- [ ] Check dependencies
+- [ ] Output report with recommendations
 </gate>
 
-## Output Format
-
-```markdown
-## Sprint {N} Backlog Research
+<output>
+## Output Format (MODE: research)
 
-### Available Stories
-| Story | Title | Points | Repos | Context |
-|-------|-------|--------|-------|---------|
+Return a `RESEARCH_RESULT` block:
 
-### Recommended Next
-**Story {ID}:** {TITLE} ({PTS} pts)
 ```
+RESEARCH_RESULT:
+  status: success
+  sprint_number: {N}
+  available_count: {N}
+  stories:
+    - id: "{STORY_ID}"
+      title: "{title}"
+      points: {N}
+      repos: ["{repo}"]
+      context_ready: {true|false}
+      blocked_by: ["{dependency}"] or null
+  recommended:
+    id: "{STORY_ID}"
+    reason: "{why this story}"
+
+  next_steps:
+    - "Present stories to user for selection."
+    - "Recommended: {recommended.id} - {recommended.reason}"
+    - "On selection: Spawn sm-setup with MODE=setup, STORY_ID={selected}"
+```
+</output>
 
 ---
 
@@ -55,12 +77,12 @@ Other formats break Cyclist detection.
 <gate>
 ## Setup Steps
 
-1. Verify epic has Jira key (auto-create if missing)
-2. Check workflow permissions (auto-prompt for missing)
-3. Claim story in Jira
-4. Write session file with Workflow Tracking section
-5. Create feature branch
-6. Update sprint YAML status
+- [ ] Verify epic has Jira key (auto-create if missing)
+- [ ] Check workflow permissions (auto-prompt for missing)
+- [ ] Claim story in Jira
+- [ ] Write session file with Workflow Tracking section
+- [ ] Create feature branch
+- [ ] Update sprint YAML status
 </gate>
 
 ## Step 1: Check Epic Jira
@@ -91,11 +113,13 @@ GRANTS=$(cat .claude/settings.local.json 2>/dev/null | jq '.permissions.grants /
 **For each required permission:**
 
 1. Check if a matching grant exists (same tool + scope)
-2. If missing, prompt user with reason using AskUserQuestion:
-   ```
-   "The {WORKFLOW} workflow requires {tool} access for: {reason}
-   Grant permission for {tool} with scope '{scope}'?"
-   ```
+2. If missing, prompt user for permission:
+   - First output marker: `<!-- CYCLIST:QUESTION:yesno -->`
+   - Then use AskUserQuestion with the prompt:
+     ```
+     "The {WORKFLOW} workflow requires {tool} access for: {reason}
+     Grant permission for {tool} with scope '{scope}'?"
+     ```
 3. If granted, add to `.claude/settings.local.json` under `permissions.grants[]`:
    ```json
    {
@@ -154,21 +178,39 @@ cd $CLAUDE_PROJECT_DIR && git checkout develop && git pull && \
 git checkout -b feat/{STORY_ID}-{SLUG}
 ```
 
-## Output
+<output>
+## Output Format (MODE: setup)
 
-```markdown
-## Setup Complete
+Return a `SETUP_RESULT` block:
 
-- [x] Jira claimed: {JIRA_KEY}
-- [x] Session file: `.session/{STORY_ID}-session.md`
-- [x] Branch: `feat/{STORY_ID}-{SLUG}`
+### Success
+```
+SETUP_RESULT:
+  status: success
+  story_id: "{STORY_ID}"
+  jira_key: "{JIRA_KEY}"
+  session_file: ".session/{STORY_ID}-session.md"
+  branch: "feat/{STORY_ID}-{SLUG}"
+  workflow: "{WORKFLOW}"
+  next_agent: "{tea|dev}"
+
+  next_steps:
+    - "Setup complete. Spawn sm-handoff to transition to {next_agent}."
+    - "Workflow '{workflow}' routes to: {next_agent}"
+    - "Session file ready at: {session_file}"
 ```
 
-## Error Handling
-
-```markdown
-## SETUP BLOCKED
-
-**Issue:** {DESCRIPTION}
-**Fix:** {RECOMMENDED_ACTION}
+### Blocked
+```
+SETUP_RESULT:
+  status: blocked
+  error: "{description}"
+  fix: "{recommended action}"
+  stage: "{epic_jira|permissions|jira_claim|session|branch}"
+
+  next_steps:
+    - "Setup blocked at {stage}: {error}"
+    - "Required action: {fix}"
+    - "Do NOT proceed with handoff until resolved."
 ```
+</output>