erk 0.4.5__py3-none-any.whl

erk/data/claude/commands/erk/objective-update-with-landed-pr.md

@@ -0,0 +1,216 @@
+---
+description: Update objective issue after landing a PR
+---
+
+# /erk:objective-update-with-landed-pr
+
+Update an objective issue after landing a PR from a plan branch.
+
+## Usage
+
+Run after landing a PR:
+
+```bash
+/erk:objective-update-with-landed-pr
+```
+
+---
+
+## Agent Instructions
+
+### Step 0: Parse Arguments (if provided)
+
+Check `$ARGUMENTS` for pre-provided context:
+
+- `--pr <number>`: PR number that was just landed
+- `--objective <number>`: Objective issue number to update
+- `--branch <name>`: Original branch name (contains plan issue number in `P<number>-...` pattern)
+- `--auto-close`: If set and all steps are complete, close objective without asking
+
+**If all arguments are provided:** Use them directly. Parse the plan issue number from the branch name pattern to get implementation details. Skip Steps 1 and 4 (discovery steps).
+
+**If arguments are not provided:** Continue with Steps 1 and 4 to discover from git state (manual invocation case).
+
+### Step 1: Get Current Branch and Find Parent Objective
+
+**Skip this step if `--objective` was provided in arguments.**
+
+```bash
+git branch --show-current
+```
+
+Parse the plan issue number from the branch name pattern `P<number>-...`
+
+Example: `P3679-phase-1b-implement-fakes` -> Plan Issue #3679
+
+**Important:** The branch pattern `P<number>-...` points to an **erk-plan** issue, not the objective. After getting the plan issue number:
+
+1. Read the plan issue: `gh issue view <plan-number>`
+2. Find the parent objective reference (look for "Objective: #XXXX" or "[#XXXX]" link in the body)
+3. Use the objective issue number for all subsequent steps
+
+If the branch doesn't match the pattern:
+
+1. Ask the user for the objective issue number
+2. Use AskUserQuestion tool with options like "#3679", "#3680", or "Other"
+
+If the plan issue has no objective reference, ask the user which objective to update.
+
+### Step 2: Load Objective Skill
+
+Load the `objective` skill for format templates and guidelines.
+
+### Step 3: Read Current Objective State
+
+```bash
+gh issue view <issue-number>
+```
+
+Analyze the objective to identify:
+
+- Current roadmap structure (phases and steps)
+- Which phase/steps this PR likely completed
+- Current status of all steps
+- What "Current Focus" says
+
+### Step 4: Get PR Information
+
+**Skip this step if `--pr` was provided in arguments.**
+
+Find the most recently merged PR for this branch:
+
+```bash
+gh pr list --state merged --head <branch-name> --limit 1 --json number,title,url
+```
+
+If no merged PR is found:
+
+- Ask user if they want to specify a PR number
+- Or proceed without PR reference
+
+### Step 5: Post Action Comment
+
+Post an action comment using the objective skill template.
+
+**Template:**
+
+```markdown
+## Action: [Brief title - what was accomplished]
+
+**Date:** YYYY-MM-DD
+**PR:** #<pr-number>
+**Phase/Step:** <phase.step>
+
+### What Was Done
+
+- [Concrete action 1]
+- [Concrete action 2]
+
+### Lessons Learned
+
+- [Insight that should inform future work]
+
+### Roadmap Updates
+
+- Step X.Y: pending -> done
+```
+
+**Inferring content (DO NOT ask the user):**
+
+- **What Was Done:** Infer from PR title, PR description, and commit messages. The plan issue body contains the implementation plan with specific steps - use this to understand what was accomplished.
+- **Lessons Learned:** Infer from implementation patterns, architectural decisions made, or any non-obvious approaches taken. If the implementation was straightforward with no surprises, note what pattern worked well.
+- Be concrete and specific based on available context
+
+Use:
+
+```bash
+gh issue comment <issue-number> --body "$(cat <<'EOF'
+[action comment content]
+EOF
+)"
+```
+
+### Step 6: Update Objective Body
+
+After posting the action comment, update the issue body to reflect the new state.
+
+**Updates to make:**
+
+1. **Roadmap tables:** Change step statuses from `pending` to `done`
+2. **PR links:** Add the PR number to completed steps
+3. **Current Focus:** Update "Next action" to reflect what should happen next
+
+**How to update:**
+
+1. Fetch current body: `gh issue view <issue-number> --json body -q '.body'`
+2. Make the edits (status changes, PR links, Current Focus)
+3. Update: `gh issue edit <issue-number> --body "$(cat <<'EOF' ... EOF)"`
+
+### Step 7: Check Closing Triggers
+
+**After updating, check if the objective should be closed.**
+
+Count the roadmap steps:
+
+- Total steps
+- Steps with status `done` or `skipped`
+- Steps with status `pending` or `blocked`
+
+**If ALL steps are `done` or `skipped`:**
+
+**If `--auto-close` was provided:**
+
+1. Post a final "Action: Objective Complete" comment with summary
+2. Close the issue: `gh issue close <issue-number>`
+3. Report: "All steps complete - objective closed automatically"
+
+**Otherwise (interactive mode):**
+
+Ask the user:
+
+```
+All roadmap steps are complete. Should I close objective #<number> now?
+- Yes, close with final summary
+- Not yet, there may be follow-up work
+- I'll close it manually later
+```
+
+**If user says yes:**
+
+1. Post a final "Action: Objective Complete" comment with summary
+2. Close the issue: `gh issue close <issue-number>`
+
+**If not all steps are complete:**
+
+Report the update is done and what the next focus should be.
+
+---
+
+## Output Format
+
+- **Start:** "Updating objective #<number> after landing PR #<pr-number>"
+- **After action comment:** "Posted action comment to #<number>"
+- **After body update:** "Updated objective body - marked step X.Y as done"
+- **End:** Either "Objective #<number> closed" or "Objective updated. Next focus: [next action]"
+- **Always:** Display the objective URL: `https://github.com/<owner>/<repo>/issues/<number>`
+
+---
+
+## Error Cases
+
+| Scenario                           | Action                                       |
+| ---------------------------------- | -------------------------------------------- |
+| Branch doesn't match pattern       | Ask user for issue number                    |
+| Plan has no objective reference    | Ask user which objective to update           |
+| No merged PR found                 | Ask if user wants to specify a PR number     |
+| Issue not found                    | Report error and exit                        |
+| Issue has no `erk-objective` label | Warn user this may not be an objective issue |
+
+---
+
+## Important Notes
+
+- **Two-step workflow:** Always post action comment FIRST, then update body
+- **Lessons are mandatory:** Every action comment must include lessons learned
+- **Be specific:** "Fixed auth flow" not "Made improvements"
+- **Check closing triggers:** Don't let objectives linger in "ready to close" state

erk/data/claude/commands/erk/plan-implement.md

@@ -0,0 +1,202 @@
+---
+description: Save plan to GitHub and execute implementation in current worktree
+---
+
+# /erk:plan-implement
+
+User-facing command to save a plan to GitHub and immediately implement it.
+
+This is the primary implementation workflow - it orchestrates:
+
+1. Saving the plan to GitHub as an issue
+2. Setting up the `.impl/` folder
+3. Executing the implementation
+
+## Prerequisites
+
+- Must be in a git repository managed by erk
+- Must have a plan in `~/.claude/plans/` (from plan mode)
+- GitHub CLI (`gh`) must be authenticated
+
+## When NOT to Use This Command
+
+❌ **After `/erk:plan-save`** - The plan is already saved to GitHub. Use:
+
+- `erk implement <issue-number>` - CLI command to fetch and implement
+- `/erk:plan-implement-here <issue-number>` - Slash command alternative
+
+❌ **When implementing an existing GitHub issue** - Use the commands above instead.
+
+✅ **Use this command when**: You just finished planning in plan mode and want to immediately implement (save + implement in one step).
+
+---
+
+## Agent Instructions
+
+### Step 1: Check if .impl/ Already Set Up
+
+First, check if implementation is already set up (e.g., from `erk implement <issue>`):
+
+```bash
+erk exec impl-init --json
+```
+
+If this succeeds with `"valid": true` and `"has_issue_tracking": true`, the `.impl/` folder is already configured. **Skip directly to Step 4** (Read Plan and Load Context).
+
+If it fails or returns `"valid": false`, continue to Step 2 to save the plan.
+
+### Step 2: Extract Session ID
+
+Get the session ID from the `SESSION_CONTEXT` reminder in your conversation context.
+
+### Step 3: Save Plan to GitHub
+
+Save the current plan to GitHub and capture the issue number:
+
+```bash
+erk exec plan-save-to-issue --format json --session-id="<session-id>"
+```
+
+Parse the JSON output to get:
+
+- `issue_number`: The created issue number
+- `title`: The issue title (for branch naming)
+
+If this fails, display the error and stop.
+
+### Step 3b: Create Branch and Setup .impl/
+
+Now set up the implementation environment using the saved issue:
+
+```bash
+erk exec setup-impl-from-issue <issue-number>
+```
+
+This command:
+
+- Creates a feature branch from current branch (stacked) or trunk
+- Checks out the new branch in the current worktree
+- Creates `.impl/` folder with the plan content
+- Saves issue reference for PR linking
+
+If this fails, display the error and stop.
+
+### Step 3c: Re-run Implementation Initialization
+
+Run impl-init again now that .impl/ is set up:
+
+```bash
+erk exec impl-init --json
+```
+
+Use the returned `phases` for TodoWrite entries. If validation fails, display error and stop.
+
+### Step 4: Read Plan and Load Context
+
+Read `.impl/plan.md` to understand:
+
+- Overall goal and context
+- Context & Understanding sections (API quirks, architectural insights, pitfalls)
+- Implementation phases and dependencies
+- Success criteria
+
+**Context Consumption**: Plans contain expensive discoveries. Ignoring `[CRITICAL:]` tags, "Related Context:" subsections, or "DO NOT" items causes repeated mistakes.
+
+### Step 5: Load Related Documentation
+
+If plan contains "Related Documentation" section, load listed skills via Skill tool and read listed docs.
+
+### Step 6: Create TodoWrite Entries
+
+Create todo entries for each phase from impl-init output.
+
+### Step 7: Signal GitHub Started
+
+```bash
+erk exec impl-signal started --session-id="<session-id>" 2>/dev/null || true
+```
+
+This also deletes the Claude plan file (from `~/.claude/plans/`) since:
+
+- The content has been saved to GitHub issue
+- The content has been snapshotted to `.erk/scratch/`
+- Keeping it could cause confusion if the user tries to re-save
+
+### Step 8: Execute Each Phase Sequentially
+
+For each phase:
+
+1. **Mark phase as in_progress** (in TodoWrite)
+2. **Read task requirements** carefully
+3. **Implement code AND tests together**:
+   - Load `dignified-python-313` skill for coding standards
+   - Load `fake-driven-testing` skill for test patterns
+   - Follow project AGENTS.md standards
+4. **Mark phase as completed** (in TodoWrite)
+5. **Report progress**: changes made, what's next
+
+**Important:** `.impl/plan.md` is immutable - NEVER edit during implementation
+
+### Step 9: Report Progress
+
+After each phase: report changes made and what's next.
+
+### Step 10: Final Verification
+
+Confirm all tasks executed, success criteria met, note deviations, summarize changes.
+
+### Step 11: Signal GitHub Ended
+
+```bash
+erk exec impl-signal ended 2>/dev/null || true
+```
+
+### Step 12: Verify .impl/ Preserved
+
+**CRITICAL GUARDRAIL**: Verify the .impl/ folder was NOT deleted.
+
+```bash
+erk exec impl-verify
+```
+
+If this fails, you have violated instructions. The .impl/ folder must be preserved for user review.
+
+### Step 13: Run CI Iteratively
+
+1. If `.erk/prompt-hooks/post-plan-implement-ci.md` exists: follow its instructions
+2. Otherwise: check CLAUDE.md/AGENTS.md for CI commands
+
+After CI passes:
+
+- `.worker-impl/`: delete folder, commit cleanup, push
+- `.impl/`: **NEVER DELETE** - leave for user review (no auto-commit)
+
+### Step 14: Create/Update PR (if .worker-impl/ present)
+
+**Only if .worker-impl/ was present:**
+
+```bash
+gh pr create --fill --label "ai-generated" || gh pr edit --add-label "ai-generated"
+```
+
+Then validate PR rules:
+
+```bash
+erk pr check
+```
+
+If checks fail, display output and warn user.
+
+### Step 15: Output Format
+
+- **Start**: "Saving plan and setting up implementation..."
+- **After save**: "Plan saved as issue #X, setting up .impl/ folder..."
+- **Each phase**: "Phase X: [brief description]" with code changes
+- **End**: "Plan execution complete. [Summary]"
+
+---
+
+## Related Commands
+
+- `/erk:plan-save` - Save plan only, don't implement (for defer-to-later workflow)
+- `/erk:plan-implement-here` - Implement from existing GitHub issue (skips save step)

erk/data/claude/commands/erk/plan-save.md

@@ -0,0 +1,45 @@
+---
+description: Save the current session's plan to GitHub as an issue
+---
+
+# /erk:plan-save
+
+Save the current session's plan to GitHub as an issue with session context.
+
+## Issue Structure
+
+The created issue has a specific structure:
+
+- **Issue body**: Contains only the metadata header (schema version, timestamps, etc.)
+- **First comment**: Contains the actual plan content
+
+This separation keeps machine-readable metadata in the body while the human-readable plan is in the first comment.
+
+## Agent Instructions
+
+### Step 1: Extract Session ID
+
+Get the session ID from the `SESSION_CONTEXT` reminder in your conversation context.
+
+### Step 2: Run Save Command
+
+Run this command with the extracted session ID:
+
+```bash
+erk exec plan-save-to-issue --format display --session-id="<session-id-from-step-1>"
+```
+
+### Step 3: Display Results
+
+On success, **copy the command output exactly as printed**. This is critical:
+
+- Do NOT paraphrase or summarize
+- Do NOT add bullet points or change formatting
+- Do NOT omit any lines (especially the `--dangerous` option)
+- Show the output in a code block to preserve formatting
+
+On failure, display the error message and suggest:
+
+- Checking that a plan exists (enter Plan mode and exit it first)
+- Verifying GitHub CLI authentication (`gh auth status`)
+- Checking network connectivity

erk/data/claude/commands/erk/plan-submit.md

@@ -0,0 +1,39 @@
+---
+description: Submit the last created issue for remote implementation
+---
+
+# /erk:plan-submit
+
+## Goal
+
+Find the most recent GitHub issue created in this conversation and submit it for remote AI implementation via `erk plan submit`.
+
+## What This Command Does
+
+1. Search conversation for the last GitHub issue reference
+2. Extract the issue number
+3. Run `erk plan submit <issue_number>` to trigger remote implementation
+
+## Finding the Issue
+
+Search the conversation from bottom to top for these patterns (in priority order):
+
+1. **plan-save/save-raw-plan output**: Look for `**Issue:** https://github.com/.../issues/<number>`
+2. **Issue URL**: `https://github.com/<owner>/<repo>/issues/<number>`
+
+Extract the issue number from the most recent match.
+
+## Execution
+
+Once you have the issue number, run:
+
+```bash
+erk plan submit <issue_number>
+```
+
+Display the command output to the user. The `erk plan submit` command handles all validation (issue existence, labels, state).
+
+## Error Cases
+
+- **No issue found in conversation**: Report "No GitHub issue found in conversation. Run /erk:plan-save first to create an issue."
+- **erk plan submit fails**: Display the error output from the command (erk plan submit validates the issue)