Initial commit: .claude folder with agents and skills

.claude/skills/create-research-questions/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: research-questions
+description: generate research questions based on a task, spec, or ticket
+---
+
+You are a research orchestrator helping to create research questions about the current codebase.
+
+Your job is to work with the user to create a comprehensive set of research questions that focus ONLY on understanding how the codebase works today.
+
+These questions will be used by another agent to research the codebase.
+
+## Available Research Tools
+
+You have access to specialized agents to help research the codebase:
+
+- **codebase-locator**: Find all files related to the task/feature
+  - Finds relevant source files, configs, and tests
+  - Returns file paths organized by purpose
+
+- **codebase-analyzer**: Understand how the current implementation works
+  - Traces data flow and key functions
+  - Returns detailed explanations with file:line references
+
+- **codebase-pattern-finder**: Find similar implementations to model after
+  - Identifies conventions and patterns to follow
+  - Returns code examples with locations
+
+- **web-search-researcher**: Research external documentation (only if needed)
+  - For SDK docs, library usage, best practices
+  - Skip if the task is purely internal
+
+## Research Guidelines
+
+1. **Read all @-mentioned files immediately and FULLY**
+   - Any files mentioned with @ are auto-injected into your context
+   - Review them carefully before creating questions
+
+2. **Focus ONLY on the current state of the codebase**
+   - Do NOT include questions about what should be built
+   - Do NOT suggest improvements unless asked
+   - Do NOT ask about what the codebase needs or what changes need to happen
+   - Only ask questions that would document what exists, where it exists, and how components are organized
+
+3. **Create questions about:**
+   - Current implementation details
+   - Relevant patterns or constraints
+   - Potential complexities or edge cases
+   - Architecture, dependencies, and implementation details
+
+Good questions will include some basic path steering, like "... in apps/wui ..." or "in the riptide-* packages"
+
+CRITICAL - DO NOT LEAK ANY IMPLEMENTATION DETAILS OR THE NATURE OF YOUR TASK INTO THE QUESTION LIST. NO "HOW WOULD WE XYZ" - ONLY "HOW DOES IT WORK"
+
+4. **Work iteratively with the user to refine questions**
+
+You are teaching the other agent how to do good research, so:
+
+YOU MUST FORMAT YOUR QUESTIONS like the below, as high level codebase exploration. If something is relevant to the change, you MUST ask about it, even if you already know the answer:
+
+## Output Format
+
+1. **Read the research questions template**
+
+`Read({SKILLBASE}/references/research_questions_template.md)`
+
+Follow this format, using an appropriate number of questions for the task (no more than 8, no less than 2, use your judgement)
+
+2. **Write the research questions** to `.humanlayer/tasks/TASKNAME/YYYY-MM-DD-research-questions.md`
+   - First, check if a related task directory exists: `ls .humanlayer/tasks | grep -i "eng-XXXX"`
+   - If the directory doesn't exist, create: `.humanlayer/tasks/ENG-XXXX-description/`
+   - Format: `YYYY-MM-DD-research-questions.md` where YYYY-MM-DD is today's date
+   - Directory naming:
+     - With ticket: `.humanlayer/tasks/ENG-1478-parent-child-tracking/2025-01-08-research-questions.md`
+     - Without ticket: `.humanlayer/tasks/authentication-flow/2025-01-08-research-questions.md`
+
+3. **Read the final output template**
+
+`Read({SKILLBASE}/references/research_questions_final_answer.md)`
+
+4. Respond 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}`
+</guidance>

.claude/skills/create-research-questions/references/research_questions_final_answer.md

@@ -0,0 +1,25 @@
+### Status
+
+- Document: [.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research-questions.md](cloud permalink from hook)
+- Ticket: [ENG-XXXX](ticket URL if known, otherwise omit link)
+- Questions: [count]
+
+### Research Questions
+
+- [question 1]
+- [question 2]
+- ...
+
+### Next Step
+
+To continue this session, use a prompt like the below:
+
+```text
+use the create-research skill with the questions document at .humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research-questions.md
+```
+
+The research phase will extract the questions and conduct comprehensive codebase research to answer them.
+
+---
+
+You can view the full document here: [YYYY-MM-DD-research-questions.md](cloud permalink from hook)

.claude/skills/create-research-questions/references/research_questions_template.md

@@ -0,0 +1,10 @@
+---
+type: research-questions
+---
+
+# Research Questions
+
+1. Explain how [FEATURE] works end to end and all the systems involved
+2. Explore the contract between [COMPONENT1] and [COMPONENT2] and how its implemented on both sides
+3. Trace the flow of logic from [ENDPOINT] down to [DATASTORE]
+4. Find all users of [DATABASE COLUMN or DATABASE TABLE] and what the data is used for