Initial commit: .claude folder with agents and skills

.claude/skills/create-design-discussion/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: create-design-discussion
+description:  first step of planning
+---
+
+# Design Discussion Phase
+
+You are now in the Design Discussion phase. Based on the research findings and the user's change request, work with them to make design decisions.
+
+## Steps to follow after receiving the user's request
+
+1. **Read all mentioned files immediately and FULLY**:
+   - Ticket files (e.g., `.humanlayer/tasks/eng-1234-description/ticket.md`)
+   - Research documents (e.g. `.humanlayer/tasks/eng-1234-description/research.md`)
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
+   - **NEVER** read files partially - if a file is mentioned, read it completely
+
+2. **Check for related task content**:
+   - if a path in `.humanlayer/tasks/TASKNAME` is mentioned, use Bash(`ls .humanlayer/tasks/TASKNAME`)
+   - **IMPORTANT** DO NOT USE search or glob or grep, as .humanlayer/tasks may be a symlink and those tools don't traverse symlinks
+   - read all relevant files in the task directory to fully understand the work so far
+
+3. **Create a research todo list** using TodoWrite to track exploration tasks
+
+4. **Spawn parallel sub-tasks for comprehensive research**:
+   - Create multiple Task agents to research different aspects concurrently
+   - Use the right agent for each type of research:
+
+   **For deeper investigation:**
+   - **codebase-locator** - To find more specific files (e.g., "find all files that handle [specific component]")
+   - **codebase-analyzer** - To understand implementation details (e.g., "analyze how [system] works")
+   - **codebase-pattern-finder** - To find similar features we can model after
+
+   Each agent knows how to:
+   - Find the right files and code patterns
+   - Identify conventions and patterns to follow
+   - Look for integration points and dependencies
+   - Return specific file:line references
+   - Find tests and examples
+
+## Work with the user to iterate on the design
+
+1. **Present patterns to follow** based on the research
+   - Identify existing patterns in the codebase that should be followed
+   - Include file locations and multiline code snippets showing the pattern
+
+2. **Discuss design decisions**
+   - For each major design choice, present options with pros/cons
+   - Make recommendations based on codebase conventions
+   - Record final decisions with rationale
+
+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 with updates once you've verified the facts yourself
+   - interpret ALL user feedback as instructions to update the document, not to begin implementation
+
+## Output Format
+
+1. **Read the design discussion Template**
+
+`Read({SKILLBASE}/references/design_discussion_template.md)`
+
+2. **Write the design discussion** to `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-design-discussion.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-design-discussion.md` where YYYY-MM-DD is today's date
+   - Directory naming:
+     - With ticket: `.humanlayer/tasks/ENG-1478-parent-child-tracking/2025-01-08-design-discussion.md`
+     - Without ticket: `.humanlayer/tasks/improve-error-handling/2025-01-08-design-discussion.md`
+
+3. **Read the final output template**
+
+`Read({SKILLBASE}/references/design_discussion_final_answer.md)`
+
+4.  Respond to the user with a summary following the template, including GitHub permalinks
+
+<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
+```
+````
+</guidance>

.claude/skills/create-design-discussion/references/design_discussion_final_answer.md

@@ -0,0 +1,39 @@
+### Status
+
+- Document: [.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-design-discussion.md](cloud permalink from hook)
+- Ticket: [ENG-XXXX](ticket URL if known, otherwise omit link)
+- Open Design Questions: [count or "none - all resolved"]
+
+### Patterns to Follow
+
+- [pattern 1]
+- [pattern 2]
+- ...
+
+### Design Questions
+
+#### [Question Title]
+
+[The design question]
+
+- Option A: [description]
+- Option B: [description]
+
+Recommendation: [recommendation with rationale]
+
+#### [Second Question Title]
+
+...
+
+
+### Next Steps
+
+Please let me know any feedback you want and I'll incorporate it, or, to continue to the next phase, use a prompt like
+
+```text
+use the create-structure-outline skill for [.humanlayer/tasks/ENG-XXX-description]
+```
+
+---
+
+You can view the full document here: [YYYY-MM-DD-design-discussion.md](cloud permalink from hook)

.claude/skills/create-design-discussion/references/design_discussion_template.md

@@ -0,0 +1,76 @@
+---
+task: eng-xxxx-description
+type: design-discussion
+repo: [current repository]
+branch: [current branch name]
+sha: [result of git rev-parse HEAD]
+---
+
+### Summary of change request
+
+[summary of what the user wants to build based on their request and the ticket]
+
+### Current State 
+
+- [current state of codebase]
+- ..
+- ..
+
+### Desired End State
+
+- [what will be true when this work is done]
+- [user story, problems that will be solved, new things a user can do]
+- ..
+
+### 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 Questions
+
+#### [title first question]
+
+[the design question]
+
+- Option A: ...
+[optional: short code snippet]
+- Option B: ...
+[optional: short code snippet]
+- ..
+
+Reccomendation: [....]
+
+#### [title second design question]
+
+...
+
+
+### Resolved Design Questions
+
+#### [title resolved question]
+
+[option chosen] - [rationale] - [patternt to follow]
+
+
+#### [ title second resolved question]
+
+...