erk 0.4.5__py3-none-any.whl

erk/data/claude/commands/erk/git-pr-push.md

@@ -0,0 +1,345 @@
+---
+description: Create git commit and push branch as PR using git + GitHub CLI
+argument-hint: <description>
+---
+
+# Push PR (Git Only)
+
+Automatically create a git commit with a helpful summary message and push the current branch as a pull request using standard git + GitHub CLI (no Graphite required).
+
+## Usage
+
+```bash
+# Invoke the command (description argument is optional but recommended)
+/erk:git-pr-push "Add user authentication feature"
+
+# Without argument (will analyze changes automatically)
+/erk:git-pr-push
+```
+
+## What This Command Does
+
+Handles the complete git-only push-pr workflow:
+
+1. Check for uncommitted changes and stage/commit them if needed
+2. Analyze git diff to generate meaningful commit message
+3. Create commit with AI-generated message
+4. Push to origin with upstream tracking
+5. Create GitHub PR (or find existing one)
+6. Report results with PR URL
+
+## Key Differences from /gt:submit-branch
+
+- Uses standard `git push` instead of `gt submit`
+- Uses `gh pr create` instead of Graphite's PR submission
+- No stack operations (no restack, no stack metadata updates)
+- Simpler workflow: git -> push -> PR (no Graphite layer)
+- Works in any git repository (not just Graphite-enabled repos)
+
+## Prerequisites
+
+- Git repository with remote configured
+- GitHub CLI (`gh`) installed and authenticated
+- Run `gh auth status` to verify authentication
+- Run `gh auth login` if not authenticated
+
+## Implementation
+
+Execute the git-only push-pr workflow with the following steps:
+
+### Step 1: Verify Prerequisites
+
+Check GitHub CLI authentication and get current git state:
+
+```bash
+# Check GitHub CLI authentication (show status for verification)
+gh auth status
+
+# Get current branch name
+current_branch=$(git branch --show-current)
+
+# Check for uncommitted changes
+has_changes=$(git status --porcelain)
+```
+
+If `gh auth status` fails, report error and tell user to run `gh auth login`.
+
+### Step 2: Stage Changes (if needed)
+
+If `has_changes` is non-empty, stage all changes:
+
+```bash
+git add .
+```
+
+### Step 3: Analyze Staged Diff
+
+Get the staged diff and analyze it to generate a commit message:
+
+```bash
+# Get repository root for relative paths
+repo_root=$(git rev-parse --show-toplevel)
+
+# Get staged diff for analysis
+git diff --staged
+```
+
+Load the `erk-diff-analysis` skill for commit message generation guidance.
+
+### Step 4: Create Commit
+
+Create the commit with your AI-generated message using heredoc:
+
+```bash
+git commit -m "$(cat <<'COMMIT_MSG'
+[Your generated commit message here]
+COMMIT_MSG
+)"
+```
+
+### Step 5: Push to Remote
+
+Push the branch to origin with upstream tracking:
+
+```bash
+git push -u origin "$(git branch --show-current)"
+```
+
+### Step 6: Get Closing Text
+
+Get the issue closing text if this worktree was created from a GitHub issue:
+
+```bash
+closing_text=$(erk exec get-closing-text 2>/dev/null || echo "")
+```
+
+This reads `.impl/issue.json` and returns `Closes #N` if an issue reference exists.
+
+### Step 6.5: Check for Existing PR
+
+Before creating a new PR, check if one already exists for the current branch:
+
+```bash
+existing_pr=$(gh pr list --head "$(git branch --show-current)" --state open --json number,url,isDraft --jq '.[0]')
+```
+
+**Decision logic:**
+
+- If `existing_pr` is empty or null: No existing PR, proceed to Step 7
+- If `existing_pr` has data: PR exists, skip Step 7 and go directly to Step 8
+
+If an existing PR was found, extract its details for reporting:
+
+```bash
+pr_url=$(echo "$existing_pr" | jq -r '.url')
+pr_number=$(echo "$existing_pr" | jq -r '.number')
+is_draft=$(echo "$existing_pr" | jq -r '.isDraft')
+```
+
+### Step 7: Create GitHub PR (if no existing PR)
+
+**Skip this step if an existing PR was found in Step 6.5.** The push in Step 5 already updated the existing PR with new commits.
+
+Extract PR title (first line) and body (remaining lines) from commit message, then create PR with closing text appended:
+
+```bash
+# Get the commit message
+commit_msg=$(git log -1 --pretty=%B)
+
+# Extract first line as title
+pr_title=$(echo "$commit_msg" | head -n 1)
+
+# Extract remaining lines as body (skip empty first line after title)
+commit_body=$(echo "$commit_msg" | tail -n +2)
+
+# Append closing text if present
+if [ -n "$closing_text" ]; then
+    pr_body="${commit_body}
+
+${closing_text}"
+else
+    pr_body="${commit_body}"
+fi
+
+# Create PR using GitHub CLI
+gh pr create --title "$pr_title" --body "$pr_body"
+```
+
+### Step 8: Validate PR Rules
+
+Run the PR check command to validate the PR was created correctly:
+
+```bash
+erk pr check
+```
+
+This validates:
+
+- Issue closing reference (Closes #N) is present when `.impl/issue.json` exists
+- PR body contains the standard checkout footer
+
+If any checks fail, display the output and warn the user, but continue to Step 9.
+
+### Step 9: Report Results
+
+Display a clear summary based on whether a PR was created or found:
+
+**If a NEW PR was created (Step 7 was executed):**
+
+```
+## Branch Submission Complete
+
+### What Was Done
+
+✓ Staged all uncommitted changes
+✓ Created commit with AI-generated message
+✓ Pushed branch to origin with upstream tracking
+✓ Created GitHub PR
+✓ Linked to issue #N (will auto-close on merge)  [only if closing_text was present]
+
+### View PR
+
+[PR URL from gh pr create output]
+```
+
+**If an EXISTING PR was found (Step 7 was skipped):**
+
+```
+## Branch Submission Complete
+
+### What Was Done
+
+✓ Staged all uncommitted changes
+✓ Created commit with AI-generated message
+✓ Pushed branch to origin with upstream tracking
+✓ Found existing PR #N for this branch (skipped PR creation)
+✓ Linked to issue #M (will auto-close on merge)  [only if closing_text was present]
+
+### Note
+
+[If is_draft is true]: This is a draft PR. When ready for review, run: `gh pr ready`
+
+### View PR
+
+[PR URL extracted from existing_pr]
+```
+
+**Conditional lines:**
+
+- The "Linked to issue" line should only appear if `closing_text` was non-empty
+- The "Note" section with draft guidance should only appear if `is_draft` is true
+
+**CRITICAL**: The PR URL MUST be the absolute last line of your output. Do not add any text after it.
+
+## Error Handling
+
+When errors occur, provide clear guidance:
+
+**GitHub CLI not authenticated:**
+
+```
+❌ GitHub CLI is not authenticated
+
+To use this command, authenticate with GitHub:
+    gh auth login
+```
+
+**Nothing to commit:**
+
+```
+❌ No changes to commit
+
+Your working directory is clean. Make some changes first.
+```
+
+**Push failed (diverged branches):**
+
+```
+❌ Push failed: branch has diverged
+
+Option 1: Pull and merge
+    git pull origin [branch]
+
+Option 2: Force push (⚠️ overwrites remote)
+    git push -f origin [branch]
+```
+
+Note: The "PR already exists" case is now handled automatically in Step 6.5. If a PR exists for the current branch, the command will skip PR creation and report the existing PR URL instead.
+
+## Best Practices
+
+### Never Change Directory
+
+**NEVER use `cd` during execution.** Always use absolute paths or git's `-C` flag.
+
+```bash
+# ❌ WRONG
+cd /path/to/repo && git status
+
+# ✅ CORRECT
+git -C /path/to/repo status
+```
+
+**Rationale:** Changing directories pollutes the execution context and makes it harder to reason about state. The working directory should remain stable throughout the entire workflow.
+
+### Never Write to Temporary Files
+
+**NEVER write commit messages or other content to temporary files.** Always use in-context manipulation and shell built-ins.
+
+```bash
+# ❌ WRONG - Triggers permission prompts
+echo "$message" > "${TMPDIR:-/tmp}/commit_msg.txt"
+git commit -F "${TMPDIR:-/tmp}/commit_msg.txt"
+
+# ✅ CORRECT - In-memory heredoc
+git commit -m "$(cat <<'EOF'
+$message
+EOF
+)"
+```
+
+**Rationale:** Temporary files require filesystem permissions and create unnecessary I/O. Since agents operate in isolated contexts, there's no risk of context pollution from in-memory manipulation.
+
+## Quality Standards
+
+### Always
+
+- Be concise and strategic in analysis
+- Use component-level descriptions
+- Highlight breaking changes prominently
+- Note test coverage patterns
+- Use relative paths from repository root
+- Provide clear error guidance
+- Use standard git + GitHub CLI commands (no Graphite dependencies)
+
+### Never
+
+- Add Claude attribution or footer to commit messages
+- Speculate about intentions without code evidence
+- Provide exhaustive lists of every function touched
+- Include implementation details (specific variable names, line numbers)
+- Provide time estimates
+- Use vague language like "various changes"
+- Retry failed operations automatically
+- Write to temporary files (use in-context quoting and shell built-ins instead)
+- Use Graphite-specific commands (`gt submit`, `gt restack`, etc.)
+
+## Self-Verification
+
+Before completing, verify:
+
+- [ ] GitHub CLI authentication checked
+- [ ] Git status verified
+- [ ] Uncommitted changes staged (if any existed)
+- [ ] Staged diff analyzed
+- [ ] Diff analysis is concise and strategic (3-5 key changes max)
+- [ ] Commit message has no Claude footer
+- [ ] File paths are relative to repository root
+- [ ] Commit created successfully
+- [ ] Branch pushed to origin with upstream tracking
+- [ ] Closing text obtained (if issue reference exists)
+- [ ] GitHub PR created successfully (or existing PR found)
+- [ ] PR URL extracted from output
+- [ ] Results displayed with "What Was Done" section listing actions
+- [ ] PR URL placed at end under "View PR" section
+- [ ] Any errors handled with helpful guidance

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

@@ -0,0 +1,96 @@
+---
+description: Create a stacked branch and implement a saved plan
+---
+
+# /erk:implement-stacked-plan
+
+Create a graphite-stacked branch from a saved plan issue and implement it in the current worktree.
+
+## Usage
+
+```
+/erk:implement-stacked-plan <issue-number>
+```
+
+## When to Use This Command
+
+✅ **Use when**: You have a saved plan (GitHub issue) and want to implement it as a stacked branch on top of your current branch.
+
+❌ **Don't use when**:
+
+- You just finished planning and want to save + implement → Use `/erk:plan-implement`
+- You want to implement in a new worktree → Use `erk implement <issue-number>`
+
+## Prerequisites
+
+- Must be in a git repository managed by erk
+- Must have a saved plan issue on GitHub (with `erk-plan` label)
+- GitHub CLI (`gh`) must be authenticated
+- Graphite CLI (`gt`) must be available
+
+---
+
+## Agent Instructions
+
+### Step 1: Validate Argument
+
+Extract the issue number from the argument (handles `#123` or `123` format).
+
+If no issue number provided, display usage and stop:
+
+```
+Usage: /erk:implement-stacked-plan <issue-number>
+
+Example: /erk:implement-stacked-plan 4128
+```
+
+### Step 2: Record Current Branch
+
+Get the current branch name (this will be the parent for stacking):
+
+```bash
+git branch --show-current
+```
+
+Save this as `parent_branch`.
+
+### Step 3: Setup Implementation
+
+Run the setup command to fetch the plan, create the branch, and set up `.impl/`:
+
+```bash
+erk exec setup-impl-from-issue <issue-number>
+```
+
+Parse the output to get the `branch` name from the JSON.
+
+If this fails, display the error and stop.
+
+### Step 4: Track with Graphite
+
+Register the new branch with graphite, stacked on the parent:
+
+```bash
+gt track --branch <branch-name> --parent <parent_branch>
+```
+
+This makes the branch part of the graphite stack for proper PR management.
+
+### Step 5: Execute Implementation
+
+Invoke the standard implementation workflow:
+
+```
+/erk:plan-implement
+```
+
+This handles all remaining steps: reading the plan, loading context, executing phases, running CI, and creating the PR.
+
+---
+
+## Notes
+
+- The issue must have the `erk-plan` label
+- The branch will be stacked on whatever branch you were on when you started
+- Use this when you want to add a stacked change in the current worktree
+- Differs from `erk implement` which creates a new worktree

erk/data/claude/commands/erk/land.md

@@ -0,0 +1,193 @@
+---
+description: Land PR with objective awareness - updates objective after landing
+argument-hint: "[branch|PR#|URL] [--skip-objective]"
+---
+
+# /erk:pr-land
+
+Objective-aware wrapper for `erk pr land`. Lands the PR first, then offers to update the linked objective if one exists.
+
+## Usage
+
+```bash
+# Land PR for current branch
+/erk:pr-land
+
+# Land PR for specific branch
+/erk:pr-land feature-branch
+
+# Land PR by number
+/erk:pr-land 123
+
+# Land PR by URL
+/erk:pr-land https://github.com/owner/repo/pull/123
+
+# Skip objective update prompt
+/erk:pr-land --skip-objective
+```
+
+---
+
+## Agent Instructions
+
+### Step 1: Parse Arguments
+
+Parse the command arguments:
+
+- `$ARGUMENTS` may contain: branch name, PR number, PR URL, or be empty (use current branch)
+- Check for `--skip-objective` flag
+
+### Step 2: Determine Branch Name
+
+If no branch argument provided, get current branch:
+
+```bash
+git branch --show-current
+```
+
+If argument is a PR number or URL, extract the branch name:
+
+```bash
+# For PR number
+gh pr view <number> --json headRefName -q '.headRefName'
+
+# For PR URL (extract number first, then use above)
+```
+
+### Step 3: Resolve to PR Number
+
+**Critical:** Always resolve the branch to a PR number. The `erk pr land` command only accepts PR numbers or URLs, not branch names.
+
+```bash
+# Get PR number for branch
+gh pr list --head <branch-name> --state open --json number -q '.[0].number'
+```
+
+If no open PR found, check all states:
+
+```bash
+gh pr list --head <branch-name> --state all --limit 1 --json number -q '.[0].number'
+```
+
+**If no PR found:** Report error and exit - cannot land without a PR.
+
+### Step 4: Extract Plan Issue Number (P-prefix Detection)
+
+Parse the plan issue number from the branch name pattern `P<number>-...`
+
+Example: `P3699-objective-aware-pr-land` -> Plan Issue #3699
+
+**If branch doesn't have P-prefix:** Record that there's no plan link. Continue to Step 6.
+
+### Step 5: Check for Objective Link
+
+If branch has P-prefix, use the `get-plan-metadata` exec command to extract the objective issue:
+
+```bash
+erk exec get-plan-metadata <plan-number> objective_issue
+```
+
+**Output format:**
+
+```json
+{
+  "success": true,
+  "value": 3400,
+  "issue_number": 3509,
+  "field": "objective_issue"
+}
+```
+
+- If `success` is `true` and `value` is an integer, record that objective issue number
+- If `success` is `true` and `value` is `null`, there's no objective link
+- If `success` is `false`, warn and skip objective workflow (fail-open behavior)
+
+### Step 6: Execute erk pr land
+
+Land the PR using the resolved PR number. Use `--force` to skip interactive confirmation (required for non-TTY execution):
+
+```bash
+erk pr land <PR_NUMBER> --force
+```
+
+**If landing fails:** Report the error and exit.
+
+### Step 7: Post-Land Objective Update
+
+**Only runs if:** Landing succeeded AND plan has `objective_issue` AND `--skip-objective` not passed
+
+1. Display: "PR #`<pr>` landed successfully."
+2. Display: "This PR is part of Objective #`<objective>`."
+3. Prompt user with AskUserQuestion:
+
+```
+Would you like to update the objective now?
+
+Options:
+1. Yes, update objective (Recommended)
+2. Skip - I'll update it later
+```
+
+**If user selects "Yes":**
+
+Run the `/erk:objective-update-with-landed-pr` workflow inline:
+
+1. Post an action comment to the objective issue with:
+   - What was done (infer from PR title/description)
+   - Lessons learned (infer from implementation)
+   - Roadmap updates (which steps are now done)
+
+2. Update the objective body:
+   - Mark relevant roadmap steps as `done`
+   - Add PR number to the step
+   - Update "Current Focus" section
+
+3. Check if all steps are complete - if so, offer to close the objective.
+
+**If user selects "Skip":** Just report success and remind them to update later.
+
+### Step 8: Report Results
+
+Display final status:
+
+- PR landing result
+- Objective update result (if applicable)
+- Link to objective issue (if applicable)
+
+---
+
+## Fail-Open Behavior
+
+The command lands normally (no blocking) when:
+
+| Scenario                          | Action                          |
+| --------------------------------- | ------------------------------- |
+| Branch has no P-prefix            | Land normally, skip objective   |
+| Plan issue not found              | Warn, land normally             |
+| `objective_issue` is null/missing | Land normally, skip objective   |
+| `--skip-objective` flag passed    | Land normally, skip objective   |
+| Objective update fails            | Warn but report landing success |
+| Any parsing/API error             | Warn, continue with landing     |
+
+**Principle:** Landing always proceeds. Objective update is post-land and optional.
+
+---
+
+## Output Format
+
+- **Start:** "Resolving PR for branch..."
+- **No PR found:** "Error: No PR found for branch `<branch>`"
+- **Landing:** "Landing PR #`<number>`..."
+- **Success:** "PR #`<number>` landed successfully."
+- **Objective prompt:** (as shown above)
+- **Objective updated:** "Objective #`<number>` updated."
+- **End:** Show final status and any relevant links
+
+---
+
+## Error Handling
+
+- **No PR found:** Report error and exit (cannot land without PR)
+- **Landing fails:** Report `erk pr land` error output and exit
+- **Objective update fails:** Warn but report landing as successful
+- **API errors during objective check:** Warn and skip objective workflow