erk 0.4.5__py3-none-any.whl

erk/data/claude/commands/erk/objective-create.md

@@ -0,0 +1,370 @@
+---
+description: Create a structured objective through guided conversation
+---
+
+# /erk:objective-create
+
+Create a new objective through an interactive, guided process. You describe what you want to accomplish, and Claude proposes a structured objective for your approval.
+
+## Usage
+
+```bash
+/erk:objective-create
+```
+
+---
+
+## Agent Instructions
+
+### Step 1: Prompt for Description
+
+Ask the user to describe what they want to accomplish:
+
+```
+What do you want to accomplish? Describe it however makes sense to you - goals,
+constraints, design decisions you've already made, context about the codebase, etc.
+
+I'll structure it into a formal objective for your review.
+```
+
+Wait for the user's response. They may provide:
+
+- A brief summary
+- A detailed brain dump
+- Existing notes or documentation
+- A combination of the above
+
+### Step 2: Analyze and Explore
+
+Based on the user's description:
+
+1. **Identify key elements:**
+   - What is the transformation/goal?
+   - What design decisions are mentioned or implied?
+   - What constraints exist?
+   - What's the scope?
+
+2. **Explore the codebase if needed:**
+   - If the user references specific code, read it to understand context
+   - If architecture decisions are mentioned, verify current state
+   - Gather enough context to propose realistic phases
+
+3. **Capture context for downstream implementers:**
+
+   During objective creation, you gather valuable context that would otherwise be lost: web searches, codebase exploration, user feedback, and your reasoning. **This context belongs in the objective issue.**
+
+   Ask yourself: "What would a future agent (or human) implementing this need to know?"
+
+   Examples of valuable context:
+   - **Inventories**: Grep results showing all instances of a pattern, categorized by type
+   - **Root cause analysis**: Why the current state exists, what caused the problem
+   - **Codebase findings**: Relevant files, existing patterns, architectural constraints
+   - **External research**: API docs, library behavior, migration guides discovered via web search
+   - **Design rationale**: Why certain approaches were chosen or rejected
+   - **User preferences**: Feedback and decisions made during the conversation
+
+   This context goes in a dedicated section after the Roadmap (see template below)
+
+### Step 3: Ask for Structure Preference
+
+After understanding the user's goals, present structure options using AskUserQuestion:
+
+```
+How would you like the objective structured?
+```
+
+**Options:**
+
+1. **Steelthread (Recommended)** - Phase 1A is a minimal vertical slice proving the concept works end-to-end, followed by Phase 1B to complete the feature. Best when you can demonstrate value with a partial implementation.
+2. **Linear** - Sequential phases, each building on the previous. Good when infrastructure must exist before any use case works (e.g., database schema before queries).
+3. **Single** - One phase, one PR. For small, focused objectives that don't need phasing.
+4. **Custom** - User describes their preferred structure
+
+**Selection guidelines:**
+
+- **Steelthread**: Default choice. Use when feasible - it de-risks the approach early by proving the concept works.
+- **Linear**: Use when Phase 1A doesn't make sense - e.g., building a new abstraction layer that has no value until complete.
+- **Single**: Use for objectives small enough to implement in one PR (typically 1-2 days of work).
+- **Custom**: Use when the user has a specific structure in mind.
+
+### Step 4: Propose Structured Objective
+
+Write a structured objective proposal and show it to the user. Use the appropriate template based on their structure choice:
+
+#### Steelthread Template (Recommended)
+
+```markdown
+# Objective: [Clear, Concise Title]
+
+[1-2 sentence summary of the transformation]
+
+## Goal
+
+[What the end state looks like - concrete examples of the new API/behavior/architecture]
+
+## Design Decisions
+
+- **[Decision 1]**: [rationale]
+- **[Decision 2]**: [rationale]
+
+## Roadmap
+
+### Phase 1A: [Name] Steelthread (1 PR)
+
+Minimal vertical slice proving the concept works end-to-end.
+
+| Step | Description                  | Status  | PR  |
+| ---- | ---------------------------- | ------- | --- |
+| 1A.1 | [Minimal infrastructure]     | pending |     |
+| 1A.2 | [Wire into one command/path] | pending |     |
+
+**Test:** [End-to-end acceptance test for steelthread]
+
+### Phase 1B: Complete [Name] (1 PR)
+
+Fill out remaining functionality.
+
+| Step | Description                    | Status  | PR  |
+| ---- | ------------------------------ | ------- | --- |
+| 1B.1 | [Extend to remaining commands] | pending |     |
+| 1B.2 | [Full test coverage]           | pending |     |
+
+**Test:** [Full acceptance criteria]
+
+### Phase 2: [Next Component] (1 PR)
+
+[Description]
+
+| Step | Description | Status  | PR  |
+| ---- | ----------- | ------- | --- |
+| 2.1  | ...         | pending |     |
+
+**Test:** [Verification criteria]
+
+## Implementation Context
+
+[Current architecture, target architecture, patterns to follow - include if helpful]
+
+## Exploration Notes
+
+[Context gathered during objective creation that implementers will need]
+
+## Related Documentation
+
+- Skills to load: [relevant skills]
+- Docs to reference: [relevant docs]
+```
+
+#### Linear Template
+
+```markdown
+# Objective: [Clear, Concise Title]
+
+[1-2 sentence summary]
+
+## Goal
+
+[End state description]
+
+## Design Decisions
+
+- **[Decision 1]**: [rationale]
+
+## Roadmap
+
+### Phase 1: [Foundation] (1 PR)
+
+[Description - this phase establishes infrastructure needed by subsequent phases]
+
+| Step | Description | Status  | PR  |
+| ---- | ----------- | ------- | --- |
+| 1.1  | ...         | pending |     |
+
+**Test:** [Verification criteria]
+
+### Phase 2: [Build on Foundation] (1 PR)
+
+[Description - uses Phase 1 infrastructure]
+
+| Step | Description | Status  | PR  |
+| ---- | ----------- | ------- | --- |
+| 2.1  | ...         | pending |     |
+
+**Test:** [Verification criteria]
+
+## Implementation Context
+
+[Context for implementers]
+
+## Exploration Notes
+
+[Gathered context]
+
+## Related Documentation
+
+- Skills to load: [relevant skills]
+- Docs to reference: [relevant docs]
+```
+
+#### Single Template
+
+```markdown
+# Objective: [Clear, Concise Title]
+
+[1-2 sentence summary]
+
+## Goal
+
+[End state description]
+
+## Design Decisions
+
+- **[Decision 1]**: [rationale]
+
+## Implementation
+
+| Step | Description | Status  | PR  |
+| ---- | ----------- | ------- | --- |
+| 1    | ...         | pending |     |
+| 2    | ...         | pending |     |
+
+**Test:** [Acceptance criteria]
+
+## Implementation Context
+
+[Context for implementers]
+
+## Related Documentation
+
+- Skills to load: [relevant skills]
+- Docs to reference: [relevant docs]
+```
+
+**Key structuring principles:**
+
+1. **One PR per phase**: Each phase should be a self-contained PR that:
+   - Has a coherent, reviewable scope
+   - Includes its own tests (unit + integration as appropriate)
+   - Leaves the system in a working state when merged
+
+2. **Always shippable**: After each merged PR, the system must remain functional. Never leave the codebase in a broken state between phases.
+
+3. **Test per phase**: Every phase needs a **Test:** section describing acceptance criteria. This becomes the definition of "done" for that PR.
+
+**Section guidelines:**
+
+- **Goal**: Always include - this is the north star
+- **Design Decisions**: Include if there are meaningful choices already made
+- **Roadmap**: Include for bounded objectives - break into shippable phases (1 PR each typically)
+- **Principles/Guidelines**: Include for perpetual objectives instead of a roadmap
+- **Implementation Context**: Include for larger refactors where current/target state matters
+- **Exploration Notes**: Include when you gathered valuable context during creation (inventories, research, reasoning). This is often the most valuable section for implementers
+- **Related Documentation**: Include if specific skills or docs are relevant
+
+**For perpetual objectives**, replace the Roadmap section with:
+
+```markdown
+## Principles
+
+- [Guiding principle 1]
+- [Guiding principle 2]
+
+## Current Focus
+
+[What to prioritize right now - can be updated as the objective evolves]
+```
+
+After showing the proposal, ask:
+
+```
+Does this capture what you're thinking? I can adjust any section, add more detail
+to the roadmap, or restructure the phases.
+```
+
+### Step 5: Iterate Until Approved
+
+The user may:
+
+- **Approve as-is**: Proceed to Step 6
+- **Request changes**: Make the requested adjustments and show again
+- **Add information**: Incorporate new details and show again
+- **Restructure**: Reorganize phases/steps based on feedback
+
+Continue iterating until the user approves.
+
+### Step 6: Write to Plan File and Create Issue
+
+Once approved:
+
+1. **Write the objective to the session's plan file:**
+   - Get the plan file path from the session context
+   - Write the approved objective content to that file
+
+2. **Create the GitHub issue:**
+
+   ```bash
+   erk exec objective-save-to-issue --session-id=<session-id> --format=display
+   ```
+
+3. **Report success:**
+
+   ```
+   Objective created: #<number>
+   URL: <issue-url>
+
+   Next steps:
+   - Use /erk:objective-create-plan <number> to create implementation plans for specific steps
+   - Track progress by updating step status in the issue
+   ```
+
+---
+
+## Output Format
+
+- **Start**: Single prompt asking what they want to accomplish
+- **After description**: Ask for structure preference
+- **After structure choice**: Show proposed structured objective
+- **Iteration**: Show updated objective after each change
+- **Success**: Issue number, URL, and next steps
+
+---
+
+## Differences from /erk:plan-save
+
+| Feature          | /erk:plan-save      | /erk:objective-create           |
+| ---------------- | ------------------- | ------------------------------- |
+| Label            | `erk-plan`          | `erk-plan` + `erk-objective`    |
+| Purpose          | Implementation plan | Roadmap or perpetual focus area |
+| Title suffix     | `[erk-plan]`        | None                            |
+| Metadata block   | Yes                 | No                              |
+| Commands section | Yes                 | No                              |
+| Body content     | Metadata only       | Objective directly              |
+| Input            | Existing plan file  | Interactive creation            |
+
+---
+
+## Types of Objectives
+
+**Bounded objectives** - Have a clear end state and roadmap:
+
+- "Refactor GitHub gateway into facade pattern"
+- "Add dark mode support"
+
+**Perpetual objectives** - Ongoing areas of focus without a defined end:
+
+- "Improve test coverage"
+- "Documentation maintenance"
+- "Performance optimization"
+
+The structure adapts to the type - perpetual objectives may have principles/guidelines instead of a phased roadmap.
+
+---
+
+## Error Cases
+
+| Scenario                     | Action                           |
+| ---------------------------- | -------------------------------- |
+| User provides no description | Re-prompt with examples          |
+| Not authenticated            | Report GitHub auth error         |
+| Issue creation fails         | Report API error, offer to retry |
+| Plan file write fails        | Report error with path           |

erk/data/claude/commands/erk/objective-list.md

@@ -0,0 +1,34 @@
+---
+description: List open objectives
+---
+
+# /erk:objective-list
+
+List all open objectives in the current repository.
+
+## Agent Instructions
+
+### Step 1: Fetch Open Objectives
+
+Run:
+
+```bash
+gh issue list --label "erk-objective" --state open --json number,title,createdAt --limit 50
+```
+
+### Step 2: Display Results
+
+Format output as a markdown table:
+
+| #    | Title                 | Created |
+| ---- | --------------------- | ------- |
+| #123 | Objective: Feature X  | 3d ago  |
+| #456 | Objective: Refactor Y | 1w ago  |
+
+If no objectives found, report: "No open objectives found."
+
+### Step 3: Suggest Next Steps
+
+After listing, suggest:
+
+- /erk:objective-create-plan <number> to start planning a step from an objective

erk/data/claude/commands/erk/objective-next-plan.md

@@ -0,0 +1,220 @@
+---
+description: Create an implementation plan from an objective step
+argument-hint: <issue-number-or-url>
+---
+
+# /erk:objective-create-plan
+
+Create an implementation plan for a specific step in an objective's roadmap.
+
+## Usage
+
+```bash
+/erk:objective-create-plan 3679
+/erk:objective-create-plan https://github.com/owner/repo/issues/3679
+/erk:objective-create-plan  # prompts for issue reference
+```
+
+---
+
+## Agent Instructions
+
+### Step 1: Parse Issue Reference
+
+Parse `$ARGUMENTS` to extract the issue reference:
+
+- If argument is a URL: extract issue number from path
+- If argument is a number: use directly
+- If no argument provided: try to get the default from pool.json (see below), then prompt if no default
+
+**Getting default objective from pool.json:**
+
+If no argument is provided, check if we're in a pool slot worktree with a last objective:
+
+```bash
+erk exec slot-objective
+```
+
+This returns JSON like:
+
+```json
+{ "objective_issue": 123, "slot_name": "erk-managed-wt-01" }
+```
+
+Or if not in a slot or no objective:
+
+```json
+{ "objective_issue": null, "slot_name": null }
+```
+
+If `objective_issue` is not null, use it as the default and inform the user: "Using objective #<number> from slot's last objective. Run with explicit argument to override."
+
+If no default found or not in a pool slot, prompt user using AskUserQuestion with "What objective issue should I work from?"
+
+### Step 2: Fetch and Validate Issue
+
+```bash
+gh issue view <issue-number> --json number,title,body,labels
+```
+
+**Validate this is an objective:**
+
+1. Check for `erk-objective` label
+2. If label is `erk-plan` instead: report error "This is an erk-plan issue, not an objective. Use `/erk:plan-implement` instead."
+3. If neither label: warn but proceed
+
+### Step 2.5: Create Objective Context Marker
+
+Create a marker to persist the objective issue number for the exit-plan-mode hook:
+
+```bash
+erk exec marker create --session-id $CLAUDE_CODE_SESSION_ID \
+  --associated-objective <objective-number> objective-context
+```
+
+Replace `<objective-number>` with the issue number from Step 2.
+
+This enables the exit-plan-mode-hook to suggest the correct save command with `--objective-issue` automatically.
+
+### Step 3: Load Objective Skill
+
+Load the `objective` skill for format templates and guidance.
+
+### Step 4: Parse Roadmap and Display Steps
+
+Parse the objective body to extract roadmap steps. Look for markdown tables with columns like:
+
+| Step | Description | Status | PR |
+
+Extract all steps and display them to the user:
+
+```
+Objective #<number>: <title>
+
+Roadmap Steps:
+  [1] Step 1A.1: <description> (pending)
+  [2] Step 1A.2: <description> (pending)
+  [3] Step 1B.1: <description> (done, PR #123)
+  ...
+```
+
+Show status indicators:
+
+- `(pending)` - available to plan
+- `(done, PR #XXX)` - already completed
+- `(blocked)` - cannot be worked yet
+- `(skipped)` - explicitly skipped
+
+### Step 5: Prompt User to Select Step
+
+Use AskUserQuestion to ask which step to plan:
+
+```
+Which step should I create a plan for?
+- Step 1A.1: <description>
+- Step 1A.2: <description>
+- Step 1B.1: <description>
+- (Other - specify step number or description)
+```
+
+Only show steps that are `pending` or `blocked` (not already `done` or `skipped`).
+
+If all steps are complete, report: "All roadmap steps are complete! Consider closing the objective."
+
+### Step 6: Gather Context for Planning
+
+Before entering plan mode, gather relevant context:
+
+1. **Objective context:** Goal, design decisions, current focus
+2. **Step context:** What the specific step requires
+3. **Prior work:** Look at completed steps and their PRs for patterns
+
+Use this context to inform the plan.
+
+### Step 7: Enter Plan Mode
+
+Enter plan mode to create the implementation plan:
+
+1. Use the EnterPlanMode tool
+2. Focus the plan on the specific step selected
+3. Reference the parent objective in the plan
+
+**Plan should include:**
+
+- Reference to objective: `Part of Objective #<number>, Step <step-id>`
+- Clear goal for this specific step
+- Implementation phases (typically 1-3 for a single step)
+- Files to modify
+- Test requirements
+
+### Step 8: Save Plan with Objective Link
+
+After the plan is approved in plan mode, the `exit-plan-mode-hook` will prompt to save or implement.
+
+**If the objective-context marker was created in Step 2.5:**
+The hook will automatically suggest the correct command with `--objective-issue=<objective-number>`. Simply follow the hook's suggestion.
+
+**If the marker was not created (fallback):**
+Use the objective-aware save command manually:
+
+```bash
+/erk:plan-save --objective-issue=<objective-number>
+```
+
+Replace `<objective-number>` with the objective issue number from Step 2.
+
+This will:
+
+- Create a GitHub issue with the erk-plan label
+- Link it to the parent objective (stored in metadata)
+- Enable objective-aware landing via `/erk:land`
+
+### Step 9: Verify Objective Link
+
+After saving, verify the issue has the objective link:
+
+```bash
+gh issue view <new-issue-number> --json body | grep -q "objective_issue"
+```
+
+**If verification fails** (objective_issue not found in body):
+
+The plan was saved without the objective link. Fix it by updating the issue body:
+
+1. Get current body: `gh issue view <issue-number> --json body -q '.body'`
+2. Add `objective_issue: <objective-number>` to the YAML metadata block
+3. Update: `gh issue edit <issue-number> --body "..."`
+
+Or simply close the incorrectly-created issue and re-run Step 8 with the correct command.
+
+---
+
+## Output Format
+
+- **Start:** "Loading objective #<number>..."
+- **After parsing:** Display roadmap steps with status
+- **After selection:** "Creating plan for step <step-id>: <description>"
+- **In plan mode:** Show plan content
+- **End:** Guide to `/erk:plan-save`
+
+---
+
+## Error Cases
+
+| Scenario                                | Action                                          |
+| --------------------------------------- | ----------------------------------------------- |
+| Issue not found                         | Report error and exit                           |
+| Issue is erk-plan                       | Redirect to `/erk:plan-implement`               |
+| No pending steps                        | Report all steps complete, suggest closing      |
+| Invalid argument format                 | Prompt for valid issue number                   |
+| Roadmap not parseable                   | Ask user to specify which step to plan          |
+| Verification fails (no objective_issue) | Fix issue body or recreate with correct command |
+
+---
+
+## Important Notes
+
+- **Objective context matters:** Read the full objective for design decisions and lessons learned
+- **One step at a time:** Each plan should focus on a single roadmap step
+- **Link back:** Always reference the parent objective in the plan
+- **Steelthread pattern:** If planning a Phase A step, focus on minimal vertical slice