Initial commit: .claude folder with agents and skills

.claude/skills/create-structure-outline/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: create-structure-outline
+description: create a phased implementation plan based on research and design decisions
+---
+
+# Create Structure Outline
+
+You are creating a phased implementation plan based on research findings and design decisions.
+
+## Input
+
+- `changeRequest`: The user's original change request
+- `researchDocumentPath`: Path to the research document (e.g., `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research.md`)
+- `designDecisions`: List of design decisions made during the design discussion phase
+- `patternsToFollow`: List of patterns identified during research
+
+## Steps
+
+1. **Read all input documents FULLY**:
+   - Use Read tool WITHOUT limit/offset to read the research document
+   - Understand the current state of the codebase from research findings
+   - Review all design decisions and patterns to follow
+
+2. **Check for related task content**:
+   - If a path in `.humanlayer/tasks/TASKNAME` is mentioned, use `ls .humanlayer/tasks/TASKNAME`
+   - Read all relevant files in the task directory
+   - Read relevant files mentioned in the task files
+
+3. **Spawn sub-agents for follow-up research**:
+
+   **For deeper investigation:**
+   - **codebase-locator**: Find additional files if needed
+   - **codebase-analyzer**: Deep-dive on specific implementations
+   - **codebase-pattern-finder**: Find more examples of patterns
+   - **web-search-researcher**: Research external best practices
+
+   Do not run agents in the background - FOREGROUND AGENTS ONLY.
+
+4. **Create a phased implementation plan**:
+   - Break the work into logical phases
+   - Each phase should be independently testable
+   - Order phases vertically rather than horizontally - wire everything together in a testable way and then add functionality incrementally
+
+5. **For each phase, specify**:
+   - Overview of what's being built
+   - Specific file changes with descriptions
+   - Validation approach - how we'll manually verify the phase works
+
+6. **Document what's out of scope**:
+   - What we're NOT doing in this plan
+   - Future enhancements to consider later
+
+
+## Output Document
+
+1. **Read the structure outline template**
+
+`Read({SKILLBASE}/references/structure_outline_template.md)`
+
+2. **Write the structure outline** to `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-structure-outline.md`
+   - First, find the task directory: `ls .humanlayer/tasks | grep -i "eng-XXXX"`
+   - If the directory doesn't exist, create: `.humanlayer/tasks/ENG-XXXX-description/`
+   - Format: `YYYY-MM-DD-structure-outline.md` where YYYY-MM-DD is today's date
+   - Directory naming:
+     - With ticket: `.humanlayer/tasks/ENG-1478-parent-child-tracking/2025-01-08-structure-outline.md`
+     - Without ticket: `.humanlayer/tasks/improve-error-handling/2025-01-08-structure-outline.md`
+
+3. **Read the final output template**
+
+`Read({SKILLBASE}/references/structure_outline_final_answer.md)`
+
+4. Respond to the user with a summary following the template, including GitHub permalinks
+
+## Work with the user to iterate on the design
+
+3. **If the user gives any input along the way**:
+   - DO NOT just accept the correction
+   - Spawn new research tasks to verify the correct information
+   - Read the specific files/directories they mention
+   - Only proceed once you've verified the facts yourself
+   - interpret ALL user feedback as instructions to update the document, not to begin implementation
+   - Update the structure according to the user's feedback
+
+<guidance>
+## Cloud Permalinks
+
+When you write or edit documents in .humanlayer/tasks/, a cloud permalink is automatically provided in the hook response.
+- The permalink appears as `additionalContext` after Write/Edit/MultiEdit operations
+- Use this permalink in your final output for easy navigation
+- Example format: `http(s)://{DOMAIN}/artifacts/{artifactId}`
+
+## Markdown Formatting
+
+When writing markdown files that contain code blocks showing other markdown (like README examples or SKILL.md templates), use 4 backticks (````) for the outer fence so inner 3-backtick code blocks don't prematurely close it:
+
+````markdown
+# Example README
+## Installation
+```bash
+npm install example
+```
+````
+
+## Phase Validation Design
+
+Not every phase requires manual validation, don't put steps for manual validation just to have them. 
+
+There's a good chance that if a phase cannot be manually checked, the phase is either too small
+or not vertical enough. The goal of manual validation is to avoid getting to the end of a 1000+ line
+code change and then having to figure out which part went wrong.
+
+Automated testing is always better than manual testing - be thoughtful based on your knowledge 
+of the codebase and testing patterns.
+
+</guidance>

.claude/skills/create-structure-outline/references/structure_outline_final_answer.md

@@ -0,0 +1,29 @@
+### Status
+
+- Document: [.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-structure-outline.md](cloud permalink from hook)
+- Ticket: [ENG-XXXX](ticket URL if known, otherwise omit link)
+- Phases: [count]
+- Open Questions: [count or "none"]
+
+### Phase Summary
+
+1. [Phase 1 title]: [brief description]
+2. [Phase 2 title]: [brief description]
+...
+
+### Open Questions (if any)
+
+- [question 1]
+- ...
+
+### Next Steps
+
+Please let me know any feedback you want and I'll incorporate it, or, to continue to writing the plan, use a prompt like
+
+```text
+use the create-plan skill for [.humanlayer/tasks/ENG-XXXX-description]
+```
+
+---
+
+You can view the full document here: [YYYY-MM-DD-structure-outline.md](cloud permalink from hook)

.claude/skills/create-structure-outline/references/structure_outline_template.md

@@ -0,0 +1,84 @@
+---
+task: eng-xxxx-description
+type: structure-outline
+repo: [current repository]
+branch: [current branch name]
+sha: [result of git rev-parse HEAD]
+---
+
+# [Plan Title]
+
+[2-3 sentence plan summary]
+
+## Current State
+
+- [current state of codebase relevant to this change]
+- ...
+
+## Desired End State
+
+- [what will be true when this is done]
+- ...
+
+## What we're not doing
+
+- [things that are out of scope]
+- ...
+
+### Patterns to follow
+
+#### [title First pattern from research]
+
+[summary of the pattern] - e.g. [path/to/file]
+
+```
+[succint code examples demonstrating the pattern]
+```
+
+```
+[succint code examples demonstrating the pattern]
+```
+
+#### [title Second pattern from the research]
+
+...
+
+### Design Summary
+
+Full discussion doc: [design-discussion.md](./YYYY-MM-DD-design-discussion.md)
+
+#### [decision 1, e.g. use x column on y table]
+
+[deciscion, rationale, code snippets]
+
+#### [decision 2]
+
+...
+
+---
+
+## Phase 1: [Phase Title]
+
+[Overview of what this phase accomplishes]
+
+### File Changes
+
+- **`path/to/file.ts`**: [what changes in this file]
+- ...
+
+### Validation
+
+[How we'll know it's working as intended - what part of the vertical slice will be testable]
+
+---
+
+## Phase 2: [Phase Title]
+
+...
+
+---
+
+## Open Questions
+
+- [questions about plan structure that need clarification]
+- ...