Initial commit: .claude folder with agents and skills

.claude/skills/describe-pr/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: describe-pr
+description: Generate PR Description in CI (no user input)
+---
+
+# Generate PR Description
+
+You are tasked with generating a comprehensive pull request description using the repository's standard template with rich linking and deviation analysis.
+
+## Steps to follow:
+
+1. **Read the PR description template:**
+
+   `Read({SKILLBASE}/references/pr_description_template.md)`
+
+2. **Identify the PR to describe:**
+   - Check if the current branch has an associated PR: `gh pr view --json url,number,title,state,headRefName 2>/dev/null`
+   - If no PR exists for the current branch, list open PRs: `gh pr list --limit 10 --json number,title,headRefName,author`
+   - Select or ask about the target PR
+
+3. **Gather PR metadata:**
+   - Get PR info: `gh pr view {number} --json url,number,title,state,baseRefName,headRefName,commits,files`
+   - Get repo info: `gh repo view --json owner,name`
+   - Store the PR URL for diff link generation
+
+4. **Discover task directory and ticket:**
+   - Get branch name from PR: extract `headRefName` from step 2
+   - Extract task slug (strip prefix before `/`, e.g., `dexter/eng-2612-feature` -> `eng-2612-feature`)
+   - Extract ticket ID (e.g., `ENG-2612` or `LL-25` from the slug)
+   - Check for task directory: `ls .humanlayer/tasks/ | grep -i "{ticket-id}"`
+   - [if applicable] Get Linear ticket URL: `linear get-issue-v2 {TICKET_ID} --fields url 2>/dev/null`
+       - if linear tools not found or ticket not found, skip this step that's fine
+   - If task directory exists, set `TASK_DIR`
+   - Note: Cloud permalinks are automatically provided when you write artifacts
+
+5. **Generate diff URLs:**
+   - Run: `scripts/pr_diff_urls.sh {pr_number}`
+   - Store the output for use in the description
+
+6. **Gather comprehensive PR information:**
+   - Get full PR diff: `gh pr diff {number}`
+   - Read through the entire diff carefully
+   - For context, read any files referenced but not shown in the diff
+   - Understand the purpose and impact of each change
+   - Identify user-facing changes vs internal implementation details
+
+7. **Analyze for plan deviations (if plan file exists):**
+   - Check if task directory has a plan file: `ls .humanlayer/tasks/{task-dir}/*-plan.md 2>/dev/null`
+   - If plan file exists, use the Task tool with `subagent_type=implementation-reviewer`:
+     ```
+     Analyze deviations between the plan at .humanlayer/tasks/{task-dir}/{plan-file}
+     and the current implementation. Compare against the base branch.
+     ```
+   - Include the agent's output in the "Deviations from the plan" section
+
+8. **Determine output path:**
+   - If task directory exists: `.humanlayer/tasks/{task-slug}/pr-description.md`
+   - If no task directory: `.humanlayer/tasks/pr-{number}/description.md`
+
+9. **Generate the description:**
+   Fill out each section from the template:
+   - **Header links**: Include Linear ticket link and rpi task dir link (if available)
+   - **What problems**: Based on ticket/plan context and code changes
+   - **What user-facing changes**: Bulleted list with diff permalinks from step 5
+   - **How I implemented it**: Journey through the PR with file/line permalinks
+   - **Deviations from plan**: Include agent output from step 7 (or "No plan file found")
+   - **How to verify it**: Include worktree setup commands with actual branch name
+   - **Changelog entry**: Concise one-line summary
+
+10. **Save the description:**
+    - Write the completed description to the path from step 8
+    - A cloud permalink will be automatically provided in the hook response
+    - Show the generated description
+
+11. **Update the PR:**
+    - Update PR: `gh pr edit {number} --body-file {output-path}`
+    - Confirm the update was successful
+
+12. **Update the user:**
+    - Read the final output template:
+    `Read({SKILLBASE}/references/describe_pr_final_answer.md)`
+    - Respond with a summary following the template, including the PR URL and key details.
+
+## Important notes:
+- Always read the template from `{SKILLBASE}/references/pr_description_template.md`
+- Generate diff URLs using `scripts/pr_diff_urls.sh` for consistency
+- Use the `implementation-reviewer` agent for deviation analysis when a plan exists
+- Focus on the "why" as much as the "what"
+- Include breaking changes or migration notes prominently
+
+Remember, you must respond to the user according to the output template at `{SKILLBASE}/references/describe_pr_final_answer.md`

.claude/skills/describe-pr/references/describe_pr_final_answer.md

@@ -0,0 +1,26 @@
+### Status
+
+- PR: [#{number} - {title}]({pr_url})
+- Description saved: [.humanlayer/tasks/{task-dir}/pr-description.md](cloud permalink from hook)
+- Ticket: [{TICKET_ID}]({linear_ticket_url}) (if applicable)
+
+### Summary
+
+[2-3 sentence summary of what the PR does and key implementation decisions]
+
+### Files Changed
+
+- `{file_path}` - [brief description]
+- ...
+
+### Deviations from Plan
+
+[Brief summary of any deviations found, or "No plan file found" / "Implemented as planned"]
+
+### Next Steps
+
+The PR description has been updated at [pr_url].
+
+---
+
+You can view the full document here: [pr-description.md](cloud permalink from hook)

.claude/skills/describe-pr/references/pr_description_template.md

@@ -0,0 +1,72 @@
+# PR Description Template
+
+Use this template to generate PR descriptions. Fill in each section based on your analysis.
+
+## Header Links
+
+[{TICKET_ID}]({LINEAR_TICKET_URL}) | [task rpi]({RPI_TASK_DIR_URL})
+
+## What problems was I solving
+
+[Describe the user pain points or problems this PR addresses. What will be true or possible now that this is shipped? How will success be measured qualitatively and quantitatively?]
+
+## What user-facing changes did I ship
+
+[Bulleted list with GitHub diff permalinks to changed files]
+
+- [{file_path}]({pr_url}/files#diff-{sha256_hash}) - [brief description of change]
+- ...
+
+## How I implemented it
+
+[A journey through the PR with permalinks to file diffs and/or line diffs. Walk through the implementation chronologically or by component.]
+
+### Database Changes
+- [{migration_file}]({pr_url}/files#diff-{hash}) - [description]
+
+### Backend Changes
+- [{file}]({pr_url}/files#diff-{hash}R{line}) - [description of specific line/function]
+
+### Frontend Changes
+- [{file}]({pr_url}/files#diff-{hash}) - [description]
+
+## Deviations from the plan
+
+[If a plan file exists in the task directory, analyze the final code state compared to the plan. This section helps reviewers who already reviewed the plan understand the diff between what they read and what was actually implemented.]
+
+### Implemented as planned
+- [item]
+
+### Deviations/surprises
+- [item with explanation]
+
+### Additions not in plan
+- [item with rationale]
+
+### Items planned but not implemented
+- [item with reason]
+
+## How to verify it
+
+[Steps a reviewer could take to test this PR]
+
+### Setup
+```bash
+git fetch
+scripts/create_worktree.sh {branch_name}
+cd ~/wt/synclayer/{worktree_dir_name}
+```
+
+### Manual Testing
+- [ ] [verification step 1]
+- [ ] [verification step 2]
+
+### Automated Tests
+```bash
+bun run typecheck
+bun run test
+```
+
+## Description for the changelog
+
+[One-line summary suitable for a changelog]