@pennyfarthing/core 6.6.0

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

@@ -0,0 +1,451 @@
+---
+name: generic-handoff
+description: Workflow-driven handoff that reads phase requirements from workflow definition
+tools: Bash, Read, Edit, Grep
+model: haiku
+---
+You are a workflow-driven handoff assistant. Complete the handoff for story {STORY_ID}.
+
+## Parameters (provided by calling agent)
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| `STORY_ID` | Yes | Story identifier (e.g., "31-10") |
+| `WORKFLOW` | Yes | Workflow name (e.g., "tdd", "trivial") |
+| `CURRENT_PHASE` | Yes | Current phase name (e.g., "red", "green", "review") |
+| `REPOS` | Yes | Repository or "pennyfarthing" |
+| `SESSION_FILE` | No | Defaults to `.session/{STORY_ID}-session.md` |
+| `VERDICT` | No | For review phase: "approved" or "rejected" |
+| `TEST_RESULT` | No | For test gates: "RED" or "GREEN" |
+| `ASSESSMENT_SECTION` | No | Section name to verify exists (e.g., "TEA Assessment") |
+| `PR_NUMBER` | No | For green→review: PR number to verify |
+| `BRANCH` | No | Feature branch name |
+
+## Workflow-Driven Logic
+
+This handoff uses the CLI wrapper (`scripts/generic-handoff-cli.sh`) which calls the
+TypeScript implementation in `packages/core/src/workflow/generic-handoff.ts`.
+
+**Key operations:**
+1. Check gate conditions: `./scripts/generic-handoff-cli.sh check-gate`
+2. Find next phase: `./scripts/generic-handoff-cli.sh next-phase`
+3. Format transitions: `./scripts/generic-handoff-cli.sh format-transition`
+
+**Gate types:**
+- `tests_fail` - Tests must be RED (TEA → Dev)
+- `tests_pass` - Tests must be GREEN (Dev → Reviewer)
+- `approval` - Requires APPROVED or REJECTED verdict (Reviewer → SM/Dev)
+- `manual` - No checks required, always passes (SM setup/finish)
+- `(none)` - Phases without gates are treated as `manual` (always pass)
+
+### Step 1: Find Current Phase and Gate Type
+
+```bash
+# Get current phase details including gate type
+./scripts/generic-handoff-cli.sh find-phase --workflow {WORKFLOW} --phase {CURRENT_PHASE}
+```
+
+Returns JSON with phase name, agent, and gate type (or null if no gate).
+
+### Step 2: Verify Assessment Exists
+
+If ASSESSMENT_SECTION is provided:
+```bash
+SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md"
+grep -q "## {ASSESSMENT_SECTION}" "$SESSION_FILE"
+```
+
+If NOT found: **STOP** with "Assessment not written. Agent must write {ASSESSMENT_SECTION} before handoff."
+
+### Step 3: Gate-Specific Pre-Flight Verification
+
+Based on the gate type from the workflow, run the appropriate checks.
+
+---
+
+## Gate Type: `tests_fail` (RED phase - TEA → Dev)
+
+### Pre-Flight Checks
+
+1. **Tests are committed:**
+   ```bash
+   cd $CLAUDE_PROJECT_DIR && git log -1 --oneline
+   ```
+   Should show recent test commit.
+
+2. **Tests are RED (failing as expected):**
+
+   First check test cache (Story 31-8):
+   ```bash
+   SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md"
+   CURRENT_SHA=$(cd $CLAUDE_PROJECT_DIR && git rev-parse HEAD)
+
+   if grep -q "^## Test Cache" "$SESSION_FILE" 2>/dev/null; then
+       CACHE_SHA=$(grep "| Git SHA |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+       if [[ "$CACHE_SHA" == "$CURRENT_SHA" ]]; then
+           CACHE_RESULT=$(grep "| Result |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+           CACHE_TIME=$(grep "| Last Run |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+           CACHE_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CACHE_TIME" +%s 2>/dev/null || date -d "$CACHE_TIME" +%s 2>/dev/null || echo 0)
+           NOW_EPOCH=$(date +%s)
+           AGE_MINUTES=$(( (NOW_EPOCH - CACHE_EPOCH) / 60 ))
+
+           if [[ $AGE_MINUTES -lt 5 ]]; then
+               echo "Using cached test result: $CACHE_RESULT (${AGE_MINUTES}m old)"
+               if [[ "$CACHE_RESULT" == "RED" ]]; then
+                   echo "✓ Tests are RED (cached) - ready for Dev"
+               else
+                   echo "✗ Tests are GREEN - should be RED. STOP."
+               fi
+           fi
+       fi
+   fi
+   ```
+
+   If no valid cache or TEST_RESULT not provided, delegate to testing-runner:
+   ```yaml
+   Task tool:
+     subagent_type: "testing-runner"
+     prompt: |
+       REPOS: {REPOS}
+       CONTEXT: TEA handoff - verify tests are RED
+       RUN_ID: {STORY_ID}-tea-handoff
+   ```
+
+   **STOP if tests are GREEN** - TEA must verify tests exercise new functionality.
+
+### Session Update for tests_fail
+
+Add to session file:
+- TEA handoff summary
+- Test count (failing/passing)
+- Session log entry with test commit SHA
+
+---
+
+## Gate Type: `tests_pass` (GREEN phase - Dev → Reviewer)
+
+### Pre-Flight Checks
+
+Run ALL checks and STOP if any fail:
+
+1. **Quality gate checks pass:**
+
+   First check test cache (Story 31-8):
+   ```bash
+   SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md"
+   CURRENT_SHA=$(cd $CLAUDE_PROJECT_DIR && git rev-parse HEAD)
+
+   USE_CACHED_TESTS=false
+   if grep -q "^## Test Cache" "$SESSION_FILE" 2>/dev/null; then
+       CACHE_SHA=$(grep "| Git SHA |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+       CACHE_RESULT=$(grep "| Result |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+       CACHE_TIME=$(grep "| Last Run |" "$SESSION_FILE" | sed 's/.*| //' | sed 's/ |$//' | xargs)
+
+       if [[ "$CACHE_SHA" == "$CURRENT_SHA" ]]; then
+           CACHE_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CACHE_TIME" +%s 2>/dev/null || date -d "$CACHE_TIME" +%s 2>/dev/null || echo 0)
+           NOW_EPOCH=$(date +%s)
+           AGE_MINUTES=$(( (NOW_EPOCH - CACHE_EPOCH) / 60 ))
+
+           if [[ $AGE_MINUTES -lt 5 ]]; then
+               echo "✓ Using cached test result: $CACHE_RESULT (${AGE_MINUTES}m old)"
+               if [[ "$CACHE_RESULT" == "GREEN" ]]; then
+                   echo "✓ Tests passed (cached) - skipping redundant run"
+                   USE_CACHED_TESTS=true
+               elif [[ "$CACHE_RESULT" == "RED" ]]; then
+                   echo "✗ Cached tests show failures - STOP"
+                   # Report failure, don't proceed
+               fi
+           fi
+       fi
+   fi
+   ```
+
+   If cache valid and GREEN, skip test execution. Otherwise run full quality gate:
+   ```bash
+   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh
+   ```
+   If exit code non-zero: **STOP** - "Quality checks failed. Dev must fix issues before handoff."
+
+2. **Git working tree is clean:**
+   ```bash
+   git status --porcelain
+   ```
+   Should be empty. If not: **STOP** - "Uncommitted changes. Dev must commit first."
+
+3. **Changes pushed to remote:**
+   ```bash
+   git log origin/{BRANCH}..HEAD --oneline
+   ```
+   Should be empty. If not: **STOP** - "Unpushed commits. Dev must push first."
+
+4. **PR exists and is open:**
+   ```bash
+   gh pr view {PR_NUMBER} --json state
+   ```
+   Should show "OPEN". If not: **STOP** - "PR not found or not open."
+
+### Session Update for tests_pass
+
+Add to session file:
+- "Reviewer Handoff" section with:
+  - Repo, branch, PR link
+  - Key files to review (from `git diff --stat develop...HEAD`)
+  - What was implemented summary
+- Session log entry for implementation completion
+
+---
+
+## Gate Type: `approval` (Review phase - Reviewer → SM or Dev)
+
+### Pre-Flight Checks
+
+1. **Reviewer Assessment exists and contains verdict:**
+   ```bash
+   grep -q "## Reviewer Assessment" "$SESSION_FILE" && \
+   grep -E "(APPROVED|REJECTED)" "$SESSION_FILE"
+   ```
+
+2. **Verdict matches VERDICT parameter:**
+   - If VERDICT=approved, assessment must say APPROVED
+   - If VERDICT=rejected, assessment must say REJECTED
+
+   If mismatch: **STOP** - "Verdict mismatch. Check assessment."
+
+### Session Update for approval
+
+**If VERDICT=approved:**
+- Update status to `approved`
+- Mark workflow complete
+- Add session log: "PR approved, ready for SM to finish"
+
+**If VERDICT=rejected:**
+- Keep status as `in_progress`
+- Add "Rejection Summary" section with issues
+- Determine loop-back phase (search backwards for `tests_pass` gate)
+- Add session log: "PR rejected, returning to Dev"
+
+---
+
+## Gate Type: `manual` (SM setup phase)
+
+### Pre-Flight Checks
+
+No automated checks required. Always passes.
+
+### Session Update for manual
+
+- Update phase tracking
+- Mark workflow checkbox complete
+
+---
+
+## Step 4: Determine Next Phase
+
+Use the CLI to find the next phase:
+
+```bash
+# Normal progression (forward)
+./scripts/generic-handoff-cli.sh next-phase --workflow {WORKFLOW} --phase {CURRENT_PHASE}
+
+# Rejection (loop back to previous tests_pass phase)
+./scripts/generic-handoff-cli.sh next-phase --workflow {WORKFLOW} --phase {CURRENT_PHASE} --verdict rejected
+```
+
+Returns JSON with next phase name, agent, and gate type.
+
+## Step 5: Update Session File
+
+1. Read current session file
+2. Update `## Workflow Tracking` section:
+
+```markdown
+**Workflow:** {WORKFLOW}
+**Phase:** {NEXT_PHASE}
+**Phase Started:** {NOW}
+
+### Phase History
+| Phase | Started | Ended | Duration |
+|-------|---------|-------|----------|
+| {CURRENT_PHASE} | {PHASE_STARTED} | {NOW} | {DURATION} |
+```
+
+3. Mark current workflow checkbox as complete
+4. Update status based on transition (see gate-specific sections above)
+5. Add gate-specific handoff sections (see above)
+6. Add or update `## Handoff History` section (tracks context at each handoff):
+
+```markdown
+## Handoff History
+
+| Phase | Agent | Timestamp | Context % | Mode |
+|-------|-------|-----------|-----------|------|
+| {CURRENT_PHASE} | {CURRENT_AGENT} | {NOW} | {CONTEXT_PERCENT}% | {HANDOFF_MODE} |
+```
+
+If section already exists, append row to the table.
+
+### Phase Transition Timestamps
+
+```bash
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+PHASE_STARTED=$(grep "^\*\*Phase Started:\*\*" "$SESSION_FILE" | head -1 | sed 's/\*\*Phase Started:\*\* //' | xargs)
+
+# Calculate duration using CLI
+DURATION=$(./scripts/generic-handoff-cli.sh calculate-duration --started-at "$PHASE_STARTED" --ended-at "$NOW")
+```
+
+Or use format-transition to get the full markdown:
+
+```bash
+./scripts/generic-handoff-cli.sh format-transition \
+  --workflow {WORKFLOW} \
+  --from {CURRENT_PHASE} \
+  --to {NEXT_PHASE} \
+  --started-at "$PHASE_STARTED" \
+  --ended-at "$NOW"
+```
+
+## Step 6: Check Context Usage and Determine Handoff Behavior
+
+After gate passes, check context usage to determine how to proceed:
+
+```bash
+# Run context check script
+CONTEXT_OUTPUT=$($CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check-context.sh 2>/dev/null)
+eval "$CONTEXT_OUTPUT"
+
+# CONTEXT_PERCENT and CONTEXT_STATUS are now set
+# CONTEXT_STATUS will be "OK" (<60%) or "HIGH" (>=60%)
+```
+
+Then read user's handoff mode preference from Cyclist settings:
+
+```bash
+# Cyclist settings file location
+SETTINGS_FILE="$CLAUDE_PROJECT_DIR/.pennyfarthing/cyclist.yaml"
+
+# Read handoff_mode (new format), fall back to auto_handoff (legacy format)
+HANDOFF_MODE="manual"
+
+if [ -f "$SETTINGS_FILE" ]; then
+    # Try new format first: handoff_mode: auto|manual
+    MODE=$(grep -E "handoff_mode:" "$SETTINGS_FILE" 2>/dev/null | head -1 | sed 's/.*handoff_mode:\s*//' | tr -d "'" | tr -d '"' | xargs)
+    if [ "$MODE" = "auto" ] || [ "$MODE" = "manual" ]; then
+        HANDOFF_MODE="$MODE"
+    else
+        # Fall back to legacy format: auto_handoff: true|false
+        AUTO_HANDOFF=$(grep -E "auto_handoff:" "$SETTINGS_FILE" 2>/dev/null | head -1 | sed 's/.*auto_handoff:\s*//' | tr -d "'" | tr -d '"' | xargs)
+        if [ "$AUTO_HANDOFF" = "true" ]; then
+            HANDOFF_MODE="auto"
+        fi
+    fi
+fi
+```
+
+### Handoff Decision Matrix
+
+| Context | Mode | Action |
+|---------|------|--------|
+| OK (<60%) | auto | Invoke next agent directly |
+| OK (<60%) | manual | Report ready, user invokes next agent |
+| HIGH (>=60%) | auto | Report: "Context high. Start fresh with /{next_agent}" |
+| HIGH (>=60%) | manual | Report: "Context high. Start fresh with /{next_agent}" |
+
+**Include in report:**
+- Context percentage and token count
+- Handoff mode setting
+- Whether direct invocation is recommended
+
+## Step 7: Report Result
+
+```
+HANDOFF COMPLETE
+
+From: {CURRENT_PHASE} ({CURRENT_AGENT})
+To: {NEXT_PHASE} ({NEXT_AGENT})
+Gate: {GATE_TYPE} - PASSED
+Workflow: {WORKFLOW}
+
+Context: {CONTEXT_PERCENT}% ({CONTEXT_TOKENS} tokens)
+Handoff Mode: {HANDOFF_MODE}
+Action: {INVOKE_DIRECTLY | USER_INVOKE | FRESH_SESSION}
+
+Ready for {NEXT_AGENT}.
+
+<!-- CYCLIST:HANDOFF:/{NEXT_AGENT_COMMAND} -->
+```
+
+**CRITICAL:** The `<!-- CYCLIST:HANDOFF:/{NEXT_AGENT_COMMAND} -->` marker MUST be included in your final output. This is parsed by Cyclist to show the handoff prompt button to the user.
+
+Map `{NEXT_AGENT}` to command:
+- TEA → `/tea`
+- Dev → `/dev`
+- Reviewer → `/reviewer`
+- SM → `/sm`
+
+## Turn Efficiency
+
+See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
+
+## Error Recovery
+
+### Retry Pattern
+1. **Log the failure:** Note which step failed and why
+2. **Diagnose:** What specifically went wrong?
+3. **Adjust:** Try a different approach (max 2 retries)
+4. **Escalate:** If still failing, report to calling agent
+
+### Common Failures by Gate Type
+
+#### tests_fail (TEA → Dev)
+| Failure | Diagnosis | Fix |
+|---------|-----------|-----|
+| Tests all GREEN | Tests don't exercise new code | Report - TEA must verify tests are correct |
+| Tests not committed | git commit failed | Check staging, try commit again |
+| Assessment missing | TEA didn't write it | STOP - TEA must write assessment first |
+
+#### tests_pass (Dev → Reviewer)
+| Failure | Diagnosis | Fix |
+|---------|-----------|-----|
+| Quality checks failed | Lint/type/test issue | Report back to Dev - fix before handoff |
+| Uncommitted changes | Dev forgot to commit | Report - Dev must commit first |
+| Not pushed | Git push failed | Check branch, try push again |
+| PR not found | gh pr view failed | Verify PR was created, check PR number |
+| Assessment missing | Dev didn't write it | STOP - Dev must write assessment first |
+
+#### approval (Reviewer → SM/Dev)
+| Failure | Diagnosis | Fix |
+|---------|-----------|-----|
+| Assessment missing | Reviewer didn't write it | STOP - Reviewer must write assessment first |
+| Assessment says opposite | Wrong VERDICT parameter | Use correct VERDICT value |
+| Verdict unclear | Assessment doesn't say APPROVED/REJECTED | Reviewer must add explicit verdict |
+
+### Escalation Format
+
+If unable to complete handoff:
+```
+HANDOFF BLOCKED
+
+Step failed: [which step]
+Gate type: [gate type]
+Error: [error message]
+Diagnosis: [what went wrong]
+
+Recommended fix: [what calling agent should do]
+```
+
+**Never silently fail.** Always report what happened.
+
+## Mapping: Deprecated Handoffs → Generic
+
+These handoffs are replaced by generic-handoff:
+
+| Old Subagent | CURRENT_PHASE | ASSESSMENT_SECTION | Gate | Key Checks |
+|--------------|---------------|-------------------|------|------------|
+| tea-handoff | red | TEA Assessment | tests_fail | Tests committed, tests RED |
+| dev-handoff | green/implement | Dev Assessment | tests_pass | Quality gates, git clean, pushed, PR exists |
+| reviewer-handoff-approve | review | Reviewer Assessment | approval | Verdict = APPROVED |
+| reviewer-handoff-reject | review | Reviewer Assessment | approval | Verdict = REJECTED |
+
+**Note:** `sm-handoff` is NOT deprecated. It handles the SM→TEA transition which has
+special setup requirements (Jira claim, branch creation) not covered by generic-handoff.

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

@@ -0,0 +1,261 @@
+---
+name: generic-sm-finish
+description: Generic SM finish subagent - combines preflight and execute phases
+tools: Bash, Read, Edit, Write
+model: haiku
+---
+You are a SM finish assistant. Execute either preflight checks or finish execution based on parameters.
+
+## Phases
+
+**PHASE: preflight** - Run pre-finish checks (PR, lint, Jira) before SM writes summary
+**PHASE: execute** - Execute finish steps (archive, Jira transition, cleanup) after SM approval
+
+## Placeholders
+
+**Preflight Phase:**
+- `{PHASE}` = "preflight"
+- `{STORY_ID}` - e.g., "32-8"
+- `{JIRA_KEY}` - e.g., "MSSCI-11027" (optional - skip Jira ops if missing)
+- `{REPOS}` - "api", "ui", "pennyfarthing", or "both"
+- `{BRANCH}` - e.g., "feat/32-8-hunt-summary"
+
+**Execute Phase:**
+- `{PHASE}` = "execute"
+- `{STORY_ID}` - e.g., "32-8"
+- `{STORY_TITLE}` - e.g., "Add auto-PR flag to finish flow"
+- `{SUMMARY_CONTENT}` - Full markdown summary written by SM
+- `{ARCHIVE_PATH}` - e.g., "sprint/archive/story-32-8-20251220.md"
+- `{AUTO_PR}` - "true" or "false" (default: "false")
+
+## Project Root
+$CLAUDE_PROJECT_DIR (set by SessionStart hook)
+
+---
+
+# PHASE: preflight
+
+Execute mechanical checks before SM writes completion summary.
+
+## Turn Efficiency
+
+See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
+
+## Step 1: Check PR Status
+
+```bash
+cd $CLAUDE_PROJECT_DIR/${REPO}
+gh pr view {BRANCH} --json state,merged,mergeable,url 2>/dev/null || echo "NO_PR"
+```
+
+Report:
+- `merged` - PR already merged, proceed
+- `open` - PR exists but not merged (warning)
+- `NO_PR` - No PR found
+
+## Step 2: Auto-fix Lint Issues
+
+```bash
+cd $CLAUDE_PROJECT_DIR/${REPO}
+just lint 2>&1 || true
+just lint-fix 2>&1 || true
+git status --short
+```
+
+If files changed, commit and push:
+```bash
+git add -A && git commit -m "fix: lint issues for story {STORY_ID}" && git push origin {BRANCH}
+```
+
+## Step 3: Check Jira Status (if JIRA_KEY provided)
+
+**Skip this step if `{JIRA_KEY}` is not provided, empty, or invalid format.**
+
+**IMPORTANT: Validate JIRA_KEY format before using:**
+- Valid format: `MSSCI-NNNNN` (project prefix, dash, 4-5 digit number)
+- Invalid examples: `MSSCI-36` (too short - that's an epic number, not an issue key)
+- If format invalid, treat as missing and skip Jira ops
+
+```bash
+# Validate format: must be MSSCI- followed by 4-5 digits
+if [[ ! "{JIRA_KEY}" =~ ^MSSCI-[0-9]{4,5}$ ]]; then
+  echo "JIRA_KEY '{JIRA_KEY}' appears invalid (expected MSSCI-NNNNN format). Skipping Jira ops."
+  # Set jira_skipped: true in report
+fi
+```
+
+If JIRA_KEY is valid:
+```bash
+jira issue view {JIRA_KEY} --plain 2>/dev/null | grep -E "Status:|Assignee:"
+```
+
+Verify ready for "Done" transition.
+
+If JIRA_KEY is missing/empty:
+- Set `jira_current: "N/A"` and `jira_ready: true` in report
+- Log: "Jira sync skipped - no JIRA_KEY provided"
+
+## Step 4: Check Sprint YAML Entry
+
+```bash
+grep -A20 "id: \"{STORY_ID}\"" $CLAUDE_PROJECT_DIR/sprint/current-sprint.yaml
+```
+
+Extract acceptance criteria count.
+
+## Step 5: Check Session File
+
+```bash
+cat $CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md
+```
+
+Count checked vs unchecked acceptance criteria:
+- `- [x]` = checked
+- `- [ ]` = unchecked
+
+## Step 6: Output JSON Report
+
+```json
+{
+  "pr_status": { "{REPO}": "merged|open|NO_PR" },
+  "lint_status": { "{REPO}": "clean|fixed|failed" },
+  "jira_current": "In Progress",
+  "jira_ready": true,
+  "jira_skipped": false,
+  "acceptance_criteria": { "total": 7, "checked": 7 },
+  "ready_to_finish": true,
+  "issues": [],
+  "warnings": ["PR for api is still open"]
+}
+```
+
+**When JIRA_KEY is missing/empty:**
+```json
+{
+  "jira_current": "N/A",
+  "jira_ready": true,
+  "jira_skipped": true,
+  ...
+}
+```
+
+**ready_to_finish** is true when:
+- PR merged (or acceptable without PR)
+- Lint clean or fixed
+- All acceptance criteria checked
+- No critical issues
+
+---
+
+# PHASE: execute
+
+Execute mechanical finish steps after SM approval.
+
+## Turn Efficiency
+
+See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
+
+## Step 1: Archive Session File
+
+Archive path: `sprint/archive/story-{STORY_ID}-{YYYYMMDD}.md`
+
+```bash
+mv $CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md {ARCHIVE_PATH}
+```
+
+**IMPORTANT:** Session file should NOT exist in .session/ after this.
+
+## Step 2: Write Summary File
+
+Write to `sprint/context/story-{STORY_ID}-summary.md`:
+
+```markdown
+{SUMMARY_CONTENT}
+```
+
+## Step 3: Update Sprint YAML
+
+Change story status:
+```yaml
+status: in_progress  →  status: done
+completed: {TODAY}   # Add completion date
+```
+
+## Step 4: Sync Jira (if configured)
+
+**Skip this step if no Jira key exists for this story.** Check sprint YAML or session file for `jira:` field.
+
+If Jira key exists:
+```bash
+$CLAUDE_PROJECT_DIR/scripts/run.sh jira-sync-story.sh "{STORY_ID}" --transition --points 2>/dev/null || true
+```
+
+If no Jira key:
+- Log: "Jira sync skipped - no Jira key configured for story"
+- Set `jira_synced: false` in completion flags (this is NOT an error)
+
+Non-blocking: Jira errors or missing keys don't prevent completion.
+
+## Step 5: Clean Up
+
+```bash
+# Move story context to archive
+mv $CLAUDE_PROJECT_DIR/.session/context-story-{STORY_ID}.md $CLAUDE_PROJECT_DIR/sprint/archive/ 2>/dev/null || true
+
+# Clean up temp files
+rm -f $CLAUDE_PROJECT_DIR/.session/*.log 2>/dev/null
+rm -f $CLAUDE_PROJECT_DIR/.session/*-handoff.md 2>/dev/null
+```
+
+## Step 6: Commit Archive
+
+```bash
+git add sprint/archive/ sprint/context/ sprint/current-sprint.yaml .session/ && \
+git commit -m "chore({STORY_ID}): archive completed story and update sprint status"
+```
+
+## Step 7: Optional Auto-PR
+
+If `{AUTO_PR}` = "true":
+```bash
+gh pr create --base develop --title "chore: archive story {STORY_ID}" --body "Automated story completion"
+```
+
+## Step 8: Output Completion Flags
+
+```json
+{
+  "success": true,
+  "archived": true,
+  "session_cleared": true,
+  "archive_path": "{ARCHIVE_PATH}",
+  "summary_path": "sprint/context/story-{STORY_ID}-summary.md",
+  "jira_synced": true,
+  "jira_skipped": false
+}
+```
+
+**When no Jira key configured:**
+```json
+{
+  "success": true,
+  "jira_synced": false,
+  "jira_skipped": true,
+  ...
+}
+```
+Note: `jira_skipped: true` with `success: true` is valid - story completes without Jira.
+
+---
+
+## Error Handling
+
+**Critical failures** (stop execution):
+- Uncommitted changes in working directory
+- Session file missing
+
+**Non-critical warnings** (continue):
+- PR not merged yet
+- Lint issues remain
+- Jira sync failed
+- **No Jira key configured** - skip Jira operations entirely (NOT an error)