Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.md text eol=lf
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
176 changes: 88 additions & 88 deletions entries/skills/prep/SKILL.md → skills/prep/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,88 +1,88 @@
---
name: prep
description: Bootstrap work on a Linear ticket — fetch ticket, create branch, mark in-progress, explore codebase, and plan implementation. Use when user says "prep", "start ticket", "begin work", "pick up ticket", or provides a Linear ticket ID to start working on.
user-invocable: true
---
# Prep
Bootstrap a Linear ticket for development: fetch ticket, create branch, mark in-progress, explore codebase, and produce an implementation plan. **No code changes are made.**
## Step 1: Resolve the Linear Ticket
**A. Get the ticket ID.**
- The ticket ID is a **required argument**. The user must provide it when invoking the skill (e.g., `/prep TRA-573`).
- If no argument was provided, respond with a friendly message and **STOP** — do not continue:
> No ticket ID provided. Run `/prep` with your Linear ticket ID — e.g., `/prep TRA-573` — and I'll handle the rest.
**B. Fetch the ticket.**
- Call Linear MCP to fetch the ticket by its ID. Retrieve its **title**, **description**, **status**, **priority**, and **git branch name**.
- On success: log `Found <ticket-id>: <title>` and continue.
- On failure (bad ID, MCP unavailable, auth error): report the specific error and **STOP**. Tell the user to re-run with a valid ticket ID (e.g., `/prep TRA-573`). Do not prompt or retry.
## Step 2: Create Git Branch
**A. Ask for base branch.**
- Use the **AskUserQuestion** tool to ask:
> Base branch? Options:
> 1. `main` (press Enter)
> 2. Current branch (`<show current branch name here>`)
> 3. Type a specific branch name
- Option 1 (Enter/main): use `origin/main`.
- Option 2 (current): use `origin/<current-branch>`. If current branch has no remote tracking, use the local branch as base.
- Option 3 (custom): use `origin/<provided-name>`. Verify it exists with `git rev-parse --verify origin/<branch>`. If not found, try the local ref. If neither exists, report the error and ask again.
**B. Create and checkout the branch.**
1. Run `git fetch origin` to ensure the latest refs.
2. Use the **git branch name from the Linear ticket** (retrieved in Step 1) as the branch name. Do NOT generate your own branch name.
3. Run `git checkout -b <branch-name> <base-ref>`.
4. Log: `Created branch: <branch-name> from <base>`
## Step 3: Mark Ticket In Progress
- Update the ticket status to **"In Progress"** via Linear MCP.
- Log: `<ticket-id> moved to In Progress`
## Step 4: Explore & Understand
Now dig into the ticket and codebase. **Do NOT write any code or edit any files.**
1. **Parse the ticket** — extract what needs to change, the expected outcome, and any acceptance criteria or constraints from the description.
2. **Explore the codebase** — use the Explore agent or Grep/Glob/Read tools to find:
- Relevant files, components, schemas, queries, or utilities
- Existing patterns that relate to the work
- Dependencies or upstream/downstream impacts
3. **Identify key files** — list the files that will likely need changes and why.
## Step 5: Draft Implementation Plan
Present a structured plan to the user:
```
## Implementation Plan — <ticket-id>: <title>
### Understanding
[1-2 sentence summary of what the ticket asks for]
### Approach
[High-level strategy for the implementation]
### Steps
1. [Concrete step with file paths]
2. [Next step...]
...
### Files to Modify
- `path/to/file.tsx` — reason
- `path/to/other.ts` — reason
### Files to Create (if any)
- `path/to/new-file.tsx` — purpose
### Risks / Open Questions
- [Anything unclear or worth flagging]
```
After presenting, ask: **"Want me to proceed with this plan, adjust anything, or stop here?"**
**CRITICAL:** Do NOT write code, create files, or make any changes. This skill is planning-only.
---
name: prep
description: Bootstrap work on a Linear ticket — fetch ticket, create branch, mark in-progress, explore codebase, and plan implementation. Use when user says "prep", "start ticket", "begin work", "pick up ticket", or provides a Linear ticket ID to start working on.
user-invocable: true
---

# Prep

Bootstrap a Linear ticket for development: fetch ticket, create branch, mark in-progress, explore codebase, and produce an implementation plan. **No code changes are made.**

## Step 1: Resolve the Linear Ticket

**A. Get the ticket ID.**
- The ticket ID is a **required argument**. The user must provide it when invoking the skill (e.g., `/prep TRA-573`).
- If no argument was provided, respond with a friendly message and **STOP** — do not continue:
> No ticket ID provided. Run `/prep` with your Linear ticket ID — e.g., `/prep TRA-573` — and I'll handle the rest.

**B. Fetch the ticket.**
- Call Linear MCP to fetch the ticket by its ID. Retrieve its **title**, **description**, **status**, **priority**, and **git branch name**.
- On success: log `Found <ticket-id>: <title>` and continue.
- On failure (bad ID, MCP unavailable, auth error): report the specific error and **STOP**. Tell the user to re-run with a valid ticket ID (e.g., `/prep TRA-573`). Do not prompt or retry.

## Step 2: Create Git Branch

**A. Ask for base branch.**
- Use the **AskUserQuestion** tool to ask:
> Base branch? Options:
> 1. `main` (press Enter)
> 2. Current branch (`<show current branch name here>`)
> 3. Type a specific branch name
- Option 1 (Enter/main): use `origin/main`.
- Option 2 (current): use `origin/<current-branch>`. If current branch has no remote tracking, use the local branch as base.
- Option 3 (custom): use `origin/<provided-name>`. Verify it exists with `git rev-parse --verify origin/<branch>`. If not found, try the local ref. If neither exists, report the error and ask again.

**B. Create and checkout the branch.**
1. Run `git fetch origin` to ensure the latest refs.
2. Use the **git branch name from the Linear ticket** (retrieved in Step 1) as the branch name. Do NOT generate your own branch name.
3. Run `git checkout -b <branch-name> <base-ref>`.
4. Log: `Created branch: <branch-name> from <base>`

## Step 3: Mark Ticket In Progress

- Update the ticket status to **"In Progress"** via Linear MCP.
- Log: `<ticket-id> moved to In Progress`

## Step 4: Explore & Understand

Now dig into the ticket and codebase. **Do NOT write any code or edit any files.**

1. **Parse the ticket** — extract what needs to change, the expected outcome, and any acceptance criteria or constraints from the description.
2. **Explore the codebase** — use the Explore agent or Grep/Glob/Read tools to find:
- Relevant files, components, schemas, queries, or utilities
- Existing patterns that relate to the work
- Dependencies or upstream/downstream impacts
3. **Identify key files** — list the files that will likely need changes and why.

## Step 5: Draft Implementation Plan

Present a structured plan to the user:

```
## Implementation Plan — <ticket-id>: <title>

### Understanding
[1-2 sentence summary of what the ticket asks for]

### Approach
[High-level strategy for the implementation]

### Steps
1. [Concrete step with file paths]
2. [Next step...]
...

### Files to Modify
- `path/to/file.tsx` — reason
- `path/to/other.ts` — reason

### Files to Create (if any)
- `path/to/new-file.tsx` — purpose

### Risks / Open Questions
- [Anything unclear or worth flagging]
```

After presenting, ask: **"Want me to proceed with this plan, adjust anything, or stop here?"**

**CRITICAL:** Do NOT write code, create files, or make any changes. This skill is planning-only.
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,6 @@ lastUpdated: 2026-05-15
"field": "value"
}
```
````

## Related

Expand All @@ -157,7 +156,4 @@ lastUpdated: 2026-05-15
## Walkthrough

https://www.loom.com/share/<id>

```

```
````
152 changes: 76 additions & 76 deletions entries/skills/ship-pr/SKILL.md → skills/ship-pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,77 +1,77 @@
---
name: ship-pr
description: Commit all changes, push to remote, create a draft GitHub PR, and sync with Linear (attach PR link, move ticket to In Review). Use when user says "ship", "ship PR", "create draft PR", "push and PR", "open PR", or invokes /ship-pr.
user-invocable: true
---
# Ship PR
Commit all changes, push to remote, create a draft pull request, and sync everything with Linear.
## Context Awareness
Before executing each step, check if the conversation already has the needed information (e.g., ticket details, git status). If it does, skip redundant commands and API calls — but NEVER skip user confirmations or gates defined within a step.
## Step 1: Resolve the Linear Ticket
Linear integration is **mandatory**. The ticket provides context for the PR title, body, and post-PR updates. This step MUST succeed before continuing.
**A. Get the ticket ID.**
- If the user provided an argument (e.g., `/ship-pr TRA-573`), use that ticket ID directly.
- If no argument was provided, check the conversation context for a Linear ticket already discussed or fetched.
- If found: use the **AskUserQuestion** tool to confirm: `Proceed with <ticket-id>: <title>? (yes / or enter a different ticket ID)`
- If not found: **STOP** with: `No ticket ID found. Re-run with /ship-pr <ticket-id>`
**B. Fetch the ticket.**
- If the ticket was already fetched in this conversation, use the existing details.
- Otherwise, call the Linear MCP tool to fetch the ticket and retrieve its **title**, **description**, **current status**, and **URL**.
- On success: log `Found <ticket-id>: <title>` and continue immediately. Do NOT ask for confirmation.
- On failure (bad ID, MCP unavailable, auth error, any error): **STOP the skill entirely**. Report the error and tell the user to re-run with a valid ticket ID.
## Step 2: Git Status & Diff
1. Run `git status` and `git diff HEAD` (can be parallel).
2. If the working tree is clean (no changes to commit), **STOP the skill**. Inform the user there is nothing to commit.
## Step 3: Commit
1. Stage all changes (including untracked files). Before staging, check for sensitive files (`.env`, credentials, secrets, API keys). If found, warn the user and exclude them.
2. Commit with a message following `docs/GIT_CONVENTIONS.md` conventions.
3. If changes are logically distinct enough to warrant multiple commits, split them. Otherwise, one commit is fine.
## Step 4: Push
1. Derive `{owner}/{repo}` from `git remote get-url origin`.
2. Run `gh api repos/{owner}/{repo} --jq '{push: .permissions.push, private: .private}'`.
- If error or `push: false`: report which account is active (`gh api user --jq '.login'`) and that it lacks push access. **STOP**.
3. If the repo is **public** and `push: true`: confirm with the user via **AskUserQuestion**: "Active account is `{username}` — push to `{owner}/{repo}`?" **STOP** if the user declines.
4. Push branch to remote with `git push -u origin HEAD`.
5. If push fails (auth error, rejected, protected branch), report the error and **STOP**.
## Step 5: Create Draft PR
1. Run `gh pr create --draft`.
2. **PR title:** `<ticket-id>: <prefix>: <short description>`
- Prefix: `feat`, `fix`, `style`, `refactor`, `chore`, `docs`
- Example: `TRA-573: feat: add \`HeroSection\` component`
3. **PR body** (use HEREDOC):
```
## Problem / Intent
[from Linear ticket description]
## Approach
[high-level solution concept from the diff]
---
Ticket: [<ticket-id>](<ticket URL retrieved in Step 1>)
```
4. Wrap code/component names in backticks in both title and body.
5. Do NOT include: file change summaries, test plan checklists, "Generated with Claude Code" footers, or any sections beyond what's defined above.
6. If `gh pr create` fails (e.g., PR already exists for this branch, auth error, no upstream), report the error and **STOP**.
## Step 6: Update Linear Ticket
After the PR is created (can be parallel):
1. Attach the PR URL to the Linear ticket as a link. Use the exact PR title as the link title.
2. Move the ticket status to **"In Review"**.
---
name: ship-pr
description: Commit all changes, push to remote, create a draft GitHub PR, and sync with Linear (attach PR link, move ticket to In Review). Use when user says "ship", "ship PR", "create draft PR", "push and PR", "open PR", or invokes /ship-pr.
user-invocable: true
---

# Ship PR

Commit all changes, push to remote, create a draft pull request, and sync everything with Linear.

## Context Awareness

Before executing each step, check if the conversation already has the needed information (e.g., ticket details, git status). If it does, skip redundant commands and API calls — but NEVER skip user confirmations or gates defined within a step.

## Step 1: Resolve the Linear Ticket

Linear integration is **mandatory**. The ticket provides context for the PR title, body, and post-PR updates. This step MUST succeed before continuing.

**A. Get the ticket ID.**
- If the user provided an argument (e.g., `/ship-pr TRA-573`), use that ticket ID directly.
- If no argument was provided, check the conversation context for a Linear ticket already discussed or fetched.
- If found: use the **AskUserQuestion** tool to confirm: `Proceed with <ticket-id>: <title>? (yes / or enter a different ticket ID)`
- If not found: **STOP** with: `No ticket ID found. Re-run with /ship-pr <ticket-id>`

**B. Fetch the ticket.**
- If the ticket was already fetched in this conversation, use the existing details.
- Otherwise, call the Linear MCP tool to fetch the ticket and retrieve its **title**, **description**, **current status**, and **URL**.
- On success: log `Found <ticket-id>: <title>` and continue immediately. Do NOT ask for confirmation.
- On failure (bad ID, MCP unavailable, auth error, any error): **STOP the skill entirely**. Report the error and tell the user to re-run with a valid ticket ID.

## Step 2: Git Status & Diff

1. Run `git status` and `git diff HEAD` (can be parallel).
2. If the working tree is clean (no changes to commit), **STOP the skill**. Inform the user there is nothing to commit.

## Step 3: Commit

1. Stage all changes (including untracked files). Before staging, check for sensitive files (`.env`, credentials, secrets, API keys). If found, warn the user and exclude them.
2. Commit with a message following `docs/GIT_CONVENTIONS.md` conventions.
3. If changes are logically distinct enough to warrant multiple commits, split them. Otherwise, one commit is fine.

## Step 4: Push

1. Derive `{owner}/{repo}` from `git remote get-url origin`.
2. Run `gh api repos/{owner}/{repo} --jq '{push: .permissions.push, private: .private}'`.
- If error or `push: false`: report which account is active (`gh api user --jq '.login'`) and that it lacks push access. **STOP**.
3. If the repo is **public** and `push: true`: confirm with the user via **AskUserQuestion**: "Active account is `{username}` — push to `{owner}/{repo}`?" **STOP** if the user declines.
4. Push branch to remote with `git push -u origin HEAD`.
5. If push fails (auth error, rejected, protected branch), report the error and **STOP**.

## Step 5: Create Draft PR

1. Run `gh pr create --draft`.
2. **PR title:** `<ticket-id>: <prefix>: <short description>`
- Prefix: `feat`, `fix`, `style`, `refactor`, `chore`, `docs`
- Example: `TRA-573: feat: add \`HeroSection\` component`
3. **PR body** (use HEREDOC):
```
## Problem / Intent
[from Linear ticket description]

## Approach
[high-level solution concept from the diff]

---
Ticket: [<ticket-id>](<ticket URL retrieved in Step 1>)
```
4. Wrap code/component names in backticks in both title and body.
5. Do NOT include: file change summaries, test plan checklists, "Generated with Claude Code" footers, or any sections beyond what's defined above.
6. If `gh pr create` fails (e.g., PR already exists for this branch, auth error, no upstream), report the error and **STOP**.

## Step 6: Update Linear Ticket

After the PR is created (can be parallel):
1. Attach the PR URL to the Linear ticket as a link. Use the exact PR title as the link title.
2. Move the ticket status to **"In Review"**.
3. If either Linear update fails, warn the user but do NOT roll back the PR.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loading