erk 0.4.5__py3-none-any.whl

erk-0.4.5.dist-info/METADATA

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: erk
+Version: 0.4.5
+Summary: Add your description here
+Author-email: Dagster Labs <hello@dagsterlabs.com>
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.7
+Requires-Dist: erk-shared
+Requires-Dist: erk-statusline
+Requires-Dist: packaging>=21.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: python-frontmatter>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual-dev>=1.8.0
+Requires-Dist: textual>=3.0.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0
+Requires-Dist: tomlkit>=0.12.0
+Description-Content-Type: text/markdown
+
+# erk
+
+`erk` is a CLI tool for plan-oriented agentic engineering.
+
+For the philosophy and design principles behind erk, see [The TAO of erk](TAO.md).
+
+## User Setup
+
+### Prerequisites
+
+Ensure you have these tools installed:
+
+- `python` (3.10+)
+- `claude` - Claude Code CLI
+- `uv` - Fast Python environment management
+- `gt` - Graphite for stacked PRs
+- `gh` - GitHub CLI
+
+### Initialize Erk
+
+```bash
+erk init
+```
+
+This command:
+
+- Prompts for worktrees root directory (where all worktrees are stored)
+- Creates global config at `~/.erk/config.toml`
+- Detects Graphite (`gt`) availability for branch creation
+- Creates repo-specific `config.toml` with preset selection (`auto`, `generic`, `dagster`)
+- Offers to add `.env`, `.erk/scratch/`, and `.impl/` to `.gitignore`
+- Shows shell integration setup instructions (completion + auto-activation)
+
+### Shell Integration
+
+`erk init` will display shell integration instructions to add to your `.zshrc` or `.bashrc`. Copy these instructions manually - erk doesn't modify your shell config automatically.
+
+**Why manual setup?** Shell integration is essential for the core workflow: it enables commands such as `erk br co` and `erk wt co` to change your terminal's directory and activate the correct Python environment. Without it, these commands run in a subprocess and have no effect on your shell. We ask you to add it manually so you stay in control of your shell configuration.
+
+To view the instructions again later: `erk init --shell`
+
+Or append directly:
+
+```bash
+erk init --shell >> ~/.zshrc  # or ~/.bashrc
+```
+
+### Verify Setup
+
+Run the doctor command to verify your environment:
+
+```bash
+erk doctor
+```
+
+This checks that all prerequisites are installed and configured correctly.
+
+## Local Plan-Driven Workflow
+
+The primary workflow: create a plan, save it, implement it, ship it. **Often completes without touching an IDE.**
+
+### Planning Phase
+
+1. Start a Claude Code session:
+
+   ```bash
+   claude
+   ```
+
+2. Enter plan mode and develop your plan
+
+3. Save plan to GitHub issue (system prompts automatically after plan mode)
+
+### Implementation
+
+4. Execute the plan:
+
+   ```bash
+   erk implement <issue-number>
+   ```
+
+   This creates a worktree, activates the environment, and runs Claude Code with the plan.
+
+### PR Submission
+
+5. Submit the PR:
+
+   ```bash
+   erk pr submit
+   ```
+
+   Or from within Claude Code: `/erk:pr-submit`
+
+### Code Review Iteration
+
+6. Review PR feedback in GitHub
+
+7. Address feedback:
+
+   ```
+   /erk:pr-address
+   ```
+
+8. Repeat until approved
+
+### Landing
+
+9. Merge and clean up:
+   ```bash
+   erk pr land
+   ```
+
+> **Note:** This entire workflow—from planning through shipping—can happen without opening an IDE. You create plans, submit code, review feedback in GitHub, address it via Claude Code, and land.
+
+## Iteration Patterns
+
+### Quick Iteration
+
+For rapid commits within a worktree:
+
+```
+/quick-submit
+```
+
+Commits all changes and submits with Graphite.
+
+### Rebasing and Stack Management
+
+When your stack needs rebasing:
+
+```bash
+erk pr auto-restack --dangerous
+```
+
+Or from Claude Code: `/erk:auto-restack`
+
+To fix merge conflicts during a rebase:
+
+```
+/erk:fix-conflicts
+```
+
+## Common Workflows
+
+### Auto-Restack: Intelligent Conflict Resolution
+
+When working with stacked PRs, rebasing is a frequent operation. `erk pr auto-restack` automates this process with intelligent conflict resolution.
+
+**What it does:**
+
+1. Runs `gt restack` to rebase your stack onto the latest trunk
+2. If conflicts occur, launches Claude Code with the `/erk:fix-conflicts` command
+3. After resolution, automatically continues the restack process
+4. Repeats until the entire stack is cleanly rebased
+
+**Basic usage:**
+
+```bash
+erk pr auto-restack --dangerous
+```
+
+**From within Claude Code:**
+
+```
+/erk:auto-restack
+```
+
+> Note: The `--dangerous` flag acknowledges that auto-restack invokes Claude with `--dangerously-skip-permissions`.
+
+**When to use it:**
+
+- After merging a PR that's below yours in the stack
+- When trunk has been updated and you need to incorporate changes
+- When Graphite shows your stack needs rebasing
+- After running `erk pr land` on a parent branch
+
+**How conflict resolution works:**
+
+When conflicts are detected, erk spawns a Claude Code session that:
+
+1. Identifies all conflicting files
+2. Analyzes the nature of each conflict (content vs import conflicts)
+3. Resolves conflicts while preserving the intent of both changes
+4. Stages resolved files and continues the rebase
+
+**Example scenario:**
+
+```
+trunk ← feature-a ← feature-b ← feature-c (you are here)
+```
+
+If `feature-a` merges into trunk, running `erk pr auto-restack --dangerous` will:
+
+1. Rebase `feature-b` onto the new trunk
+2. Resolve any conflicts (with Claude's help if needed)
+3. Rebase `feature-c` onto the updated `feature-b`
+4. Resolve any conflicts at this level too
+
+The result: your entire stack is cleanly rebased with minimal manual intervention.
+
+### Checkout PR from GitHub
+
+When reviewing or debugging a PR—whether from a teammate or a remote agent run—you can check it out directly using the PR number or URL from the GitHub page.
+
+**Basic usage:**
+
+```bash
+# Using PR number
+erk pr checkout 123
+
+# Using GitHub URL (copy directly from browser)
+erk pr checkout https://github.com/owner/repo/pull/123
+```
+
+This creates a local worktree for the PR branch and changes your shell to that directory.
+
+**Syncing with Graphite:**
+
+After checkout, sync with Graphite to enable stack management:
+
+```bash
+erk pr sync --dangerous
+```
+
+This registers the branch with Graphite so you can use standard `gt` commands (`gt pr`, `gt land`, etc.).
+
+> Note: The `--dangerous` flag acknowledges that sync invokes Claude with `--dangerously-skip-permissions`.
+
+**Complete workflow:**
+
+```bash
+# 1. Checkout the PR (copy URL from GitHub)
+erk pr checkout https://github.com/myorg/myrepo/pull/456
+
+# 2. Sync with Graphite
+erk pr sync --dangerous
+
+# 3. Now iterate normally
+claude
+# ... make changes ...
+/quick-submit
+
+# 4. Or land when approved
+erk pr land
+```
+
+**When to use it:**
+
+- Reviewing a teammate's PR locally
+- Debugging a PR created by remote agent execution
+- Taking over a PR that needs local iteration
+- Running tests or making fixes on someone else's branch
+
+## Documentation Extraction
+
+Erk supports extracting reusable documentation from implementation sessions into the `docs/learned/` folder—a directory of **agent-generated, agent-consumed documentation**.
+
+This documentation:
+
+- Captures patterns discovered during implementation
+- Gets loaded by future agent sessions via AGENTS.md routing
+- Builds institutional knowledge over time
+
+To extract documentation from a session:
+
+```
+/erk:create-extraction-plan
+```
+
+## Remote Execution
+
+For sandboxed, parallel execution via GitHub Actions:
+
+1. Create a plan (via Claude Code plan mode)
+
+2. Submit for remote execution:
+   ```bash
+   erk plan submit <issue-number>
+   ```
+
+The agent runs in GitHub Actions and creates a PR automatically.
+
+## Debugging Remote PRs
+
+When a remote implementation needs local iteration:
+
+```bash
+erk pr checkout <pr-number>
+erk pr sync --dangerous
+```
+
+This checks out the PR into a local worktree for debugging and iteration.
+
+## Planless Workflow
+
+For smaller changes that don't require formal planning:
+
+1. Create a worktree:
+
+   ```bash
+   erk wt create <branch-name>
+   ```
+
+2. Iterate normally in Claude Code
+
+3. Submit PR:
+
+   ```bash
+   erk pr submit
+   ```
+
+4. Merge and clean up:
+   ```bash
+   erk pr land
+   ```
+
+## File Locations
+
+| Location   | Contents                                         |
+| ---------- | ------------------------------------------------ |
+| `.erk/`    | Erk configuration, scratch storage, session data |
+| `.impl/`   | Implementation plans (at worktree root)          |
+| `.claude/` | Claude Code commands, skills, hooks              |
+
+### Gitignore
+
+`erk init` automatically adds these entries to your `.gitignore`. If you ran `erk init`, this is already configured:
+
+```gitignore
+.erk/scratch/
+.impl/
+```
+
+`.impl/` contains temporary implementation plans that shouldn't be committed. `.erk/scratch/` holds session-specific working files.
+
+## Plan Mode GitHub Integration
+
+By default, erk modifies Claude Code's plan mode behavior. When you exit plan mode, erk prompts you to save the plan to GitHub as an issue before proceeding. This enables the plan-driven workflow where plans become trackable issues that can be implemented via `erk implement <issue-number>`.
+
+To disable this behavior and use standard Claude Code plan mode:
+
+```bash
+erk config set github_planning false
+```
+
+To re-enable:
+
+```bash
+erk config set github_planning true
+```
+
+When disabled, exiting plan mode works exactly as it does in standard Claude Code.