zhongwei/gh-coalesce-labs-catalyst-plugins-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:14:39 +08:00
commit bb966f5886
35 changed files with 8872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
commands/.auto-discover-pattern.md Normal file
View File

@@ -0,0 +1,180 @@
# Auto-Discovery Pattern for Workflow Commands
This document defines the standard pattern for commands that should automatically discover recent documents from workflow context.
## The Problem
Commands have bash scripts to check workflow context, but they're **suggestions** for Claude - not guaranteed to execute. Users shouldn't have to paste file paths when we just created the file.
## The Solution
**Explicit, mandatory auto-discovery at the start of every workflow command.**
## Standard Pattern
### 1. Initial Response (REQUIRED)
Every workflow command must start with this EXACT pattern:
```markdown
## Initial Response
When this command is invoked, IMMEDIATELY run this bash script BEFORE responding to the user:
```bash
# Auto-discover recent document from workflow context
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_DOC=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent <TYPE>)
if [[ -n "$RECENT_DOC" ]]; then
echo "📋 Auto-discovered recent <TYPE>: $RECENT_DOC"
echo ""
fi
fi
```
**Replace `<TYPE>` with:** `handoffs`, `plans`, `research`, or `prs`
**CRITICAL**: This bash script MUST be executed FIRST, before any other response.
```
### 2. Logic Flow (REQUIRED)
After running the auto-discovery script:
```markdown
1. **If user provided a file path as parameter**:
- Use that path (user override)
- Proceed with the command
2. **If no parameter provided but RECENT_DOC found**:
- Show the user: "Found recent <TYPE>: $RECENT_DOC"
- Ask: "Proceed with this document? [Y/n]"
- If yes: proceed with RECENT_DOC
- If no: ask for document path
3. **If no parameter and no RECENT_DOC found**:
- List available documents (if applicable)
- Ask user for document path
```
### 3. Command-Specific Examples
#### `/resume-handoff`
```markdown
## Initial Response
IMMEDIATELY run this bash script BEFORE responding:
```bash
# Auto-discover recent handoff
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_HANDOFF=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent handoffs)
if [[ -n "$RECENT_HANDOFF" ]]; then
echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
echo ""
fi
fi
```
Then apply logic:
1. User provided path? → Use it
2. RECENT_HANDOFF found? → Ask to proceed with it
3. Nothing found? → Show available handoffs and ask
```
#### `/implement-plan`
```markdown
## Initial Response
IMMEDIATELY run this bash script BEFORE responding:
```bash
# Auto-discover recent plan
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_PLAN=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent plans)
if [[ -n "$RECENT_PLAN" ]]; then
echo "📋 Auto-discovered recent plan: $RECENT_PLAN"
echo ""
fi
fi
```
Then apply logic:
1. User provided path? → Use it
2. RECENT_PLAN found? → Ask to proceed with it
3. Nothing found? → Ask for plan path
```
#### `/create-plan`
Note: This command doesn't auto-discover (it creates new), but should reference recent research:
```markdown
## Context Gathering
After understanding the task, suggest recent research:
```bash
# Find recent research that might be relevant
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_RESEARCH=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent research)
if [[ -n "$RECENT_RESEARCH" ]]; then
echo "💡 Found recent research: $RECENT_RESEARCH"
echo "Would you like me to reference this research in the plan?"
fi
fi
```
```
## Key Principles
1. **Execute First, Ask Later**: Run auto-discovery BEFORE any user interaction
2. **Make it Visible**: Always show what was found with emoji indicator
3. **Allow Override**: User-provided paths always take precedence
4. **Graceful Fallback**: If nothing found, proceed with normal flow
5. **Confirm Before Proceeding**: Ask user to confirm auto-discovered document
## Commands That Need Auto-Discovery
### High Priority (Must Have)
- `/resume-handoff` → auto-find recent handoff ✅ (partially implemented)
- `/implement-plan` → auto-find recent plan ✅ (partially implemented)
- `/validate-plan` → auto-find plan being validated ❌ (missing)
### Medium Priority (Should Have)
- `/create-plan` → suggest recent research ❌ (missing)
- `/describe-pr` → find related plan/research ❌ (missing)
### Low Priority (Nice to Have)
- `/merge-pr` → reference PR description ❌ (missing)
## Testing Checklist
For each command with auto-discovery:
- [ ] Run bash script is FIRST thing command does
- [ ] Script output is visible to user
- [ ] User can override with explicit path
- [ ] User is asked to confirm auto-discovered doc
- [ ] Graceful fallback if nothing found
- [ ] Works with workflow context from hooks
## Implementation Status
| Command | Auto-Discovery | Status | Notes |
|---------|---------------|--------|-------|
| `/resume-handoff` | handoffs | 🟡 Partial | Has script but not explicit enough |
| `/implement-plan` | plans | 🟡 Partial | Has script but not explicit enough |
| `/validate-plan` | plans | ❌ Missing | Needs implementation |
| `/create-plan` | research (suggest) | ❌ Missing | Should offer to reference |
| `/describe-pr` | plans | ❌ Missing | Could auto-reference plan |
## Next Steps
1. Update `/resume-handoff` with explicit pattern
2. Update `/implement-plan` with explicit pattern
3. Add auto-discovery to `/validate-plan`
4. Add research suggestion to `/create-plan`
5. Test full workflow: research → plan → implement → validate

77
commands/README.md Normal file
View File

@@ -0,0 +1,77 @@
# Thoughts Commands
Context handoff and collaboration tools using the thoughts system.
## Commands
### `/create-handoff`
Create handoff document for passing work to another developer or session.
**Usage:**
```
/create-handoff
> What work are you handing off?
```
**Creates:**
- Handoff document in `thoughts/shared/handoffs/YYYY-MM-DD-description.md`
- Includes: Current state, work completed, next steps, blockers, context
**Content:**
- Current ticket/task
- Work completed (with file:line references)
- Files modified
- Next steps (prioritized)
- Known blockers
- Important context
### `/resume-handoff`
Resume work from handoff document.
**Usage:**
```
/resume-handoff thoughts/shared/handoffs/YYYY-MM-DD-file.md
```
**Process:**
- Reads full handoff document
- Loads context (ticket, files, blockers)
- Presents next steps
- Asks how to proceed
**Benefits:**
- Quick context restoration
- No lost work
- Clear continuation path
## Use Cases
**Handoffs:**
- End of day → Resume next morning
- Developer → Developer
- Blocked work → When unblocked
**Collaboration:**
- Pair programming context
- Code review preparation
- Onboarding new team members
## Thoughts System
Commands use the HumanLayer thoughts system:
- `thoughts/personal/` - Your private notes
- `thoughts/shared/` - Team-shared documents
- `thoughts/global/` - Cross-project knowledge
Initialize with: `humanlayer thoughts init`

198
commands/commit.md Normal file
View File

@@ -0,0 +1,198 @@
---
description: Create conventional commits for session changes
category: version-control-git
tools: Bash, Read
model: inherit
version: 2.0.0
---
# Commit Changes
You are tasked with creating git commits using conventional commit format for the changes made
during this session.
## Process:
1. **Analyze what changed:**
- Review the conversation history and understand what was accomplished
- Run `git status` to see current changes
- Run `git diff --cached` to see staged changes (if any)
- Run `git diff` to see unstaged changes
- Get changed file list: `git diff --name-only` and `git diff --cached --name-only`
2. **Auto-detect conventional commit components:**
**Type detection (suggest to user):**
- If only `*.md` files in `docs/`: suggest `docs`
- If only test files (`*test*`, `*spec*`): suggest `test`
- If `package.json`, `*.lock` files: suggest `build`
- If `.github/workflows/`: suggest `ci`
- If mix of changes: suggest `feat` or `fix` based on context
- Otherwise: ask user to choose from: `feat`, `fix`, `refactor`, `chore`, `docs`, `style`,
`perf`, `test`, `build`, `ci`
**Scope detection (suggest to user):**
- Parse changed file paths
- Map to scopes:
- `agents/*.md` → `agents`
- `commands/*.md` → `commands`
- `hack/*` → `hack`
- `docs/*.md` → `docs`
- `.claude/` → `claude`
- Multiple dirs or root files → empty scope (cross-cutting)
**Extract ticket reference:**
- Get current branch: `git branch --show-current`
- Extract ticket pattern: `{PREFIX}-{NUMBER}` (e.g., RCW-13, ENG-123)
- Will be added to commit footer
3. **Generate conventional commit message:**
**Format:**
```
<type>(<scope>): <short summary>
<body - optional but recommended>
<footer - ticket reference>
```
**Rules:**
- Header max 100 characters
- Type: lowercase
- Subject: imperative mood, no period, no capital first letter
- Body: explain WHY, not what (optional for simple changes)
- Footer: `Refs: TICKET-123` if ticket in branch name
**Example:**
```
feat(commands): add conventional commit support to /catalyst-dev:commit
Updates the commit command to automatically detect commit type
and scope from changed files, following conventional commits spec.
Extracts ticket references from branch names for traceability.
Refs: RCW-13
```
4. **Present plan to user:**
- Show detected type and scope with confidence
- Show generated commit message
- Explain: "Detected changes suggest: `<type>(<scope>): <summary>`"
- List files to be committed
- Ask: "Proceed with this commit? [Y/n/e(dit)]"
- Y: execute as-is
- n: abort
- e: allow user to edit message
5. **Execute commit:**
- Stage files: `git add <specific-files>` (NEVER use `-A` or `.`)
- Create commit with message
- Show result: `git log --oneline -n 1`
- Show summary: `git show --stat HEAD`
## Configuration
Reads from `.claude/config.json`:
```json
{
"catalyst": {
"commit": {
"useConventional": true,
"scopes": ["agents", "commands", "hack", "docs", "claude", "config"],
"autoDetectType": true,
"autoDetectScope": true,
"requireBody": false
},
"project": {
"ticketPrefix": "RCW"
}
}
}
```
## Type Reference
**Types that appear in CHANGELOG:**
- `feat` - New feature
- `fix` - Bug fix
- `perf` - Performance improvement
- `revert` - Revert previous commit
**Internal types:**
- `docs` - Documentation only
- `style` - Formatting, no code change
- `refactor` - Code restructuring, no behavior change
- `test` - Adding/updating tests
- `build` - Build system or dependencies
- `ci` - CI/CD configuration
- `chore` - Maintenance tasks
## Examples
**Feature:**
```
feat(agents): add codebase-pattern-finder agent
Implements new agent for finding similar code patterns across
the codebase with concrete examples and file references.
Refs: RCW-45
```
**Fix:**
```
fix(commands): handle missing PR template gracefully
Previously crashed when thoughts/shared/pr_description.md was
missing. Now provides clear error with setup instructions.
Refs: RCW-78
```
**Documentation:**
```
docs(hack): add README for installation scripts
Documents all scripts in hack/ directory with usage examples
and explains when to use each installation method.
Refs: RCW-12
```
**Chore (no ticket):**
```
chore(config): update conventional commit scopes
Adds new scopes for agents and commands directories.
```
## Important:
- **NEVER add co-author information or Claude attribution**
- Commits should be authored solely by the user
- Do not include any "Generated with Claude" messages
- Do not add "Co-Authored-By" lines
- Write commit messages as if the user wrote them
- Use conventional format for consistency and changelog generation
- Keep header under 100 characters
- Use imperative mood: "add feature" not "added feature"
## Remember:
- You have the full context of what was done in this session
- Group related changes together logically
- Keep commits focused and atomic when possible
- The user trusts your judgment - they asked you to commit
- Suggest type and scope based on file analysis
- Extract ticket from branch name automatically
- Allow user to override suggestions

179
commands/create_handoff.md Normal file
View File

@@ -0,0 +1,179 @@
---
description: Create handoff document for passing work to another session
category: workflow
tools: Write, Bash, Read
model: inherit
version: 1.0.0
---
# Create Handoff
## Prerequisites
Before executing, verify all required tools and systems:
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Validate plugin scripts
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Configuration Note
This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
prefix:
- Read from `.claude/config.json` if available
- Otherwise use a generic format like `TICKET-XXX`
- Examples: `ENG-123`, `FEAT-456`, `BUG-789`
You are tasked with writing a handoff document to hand off your work to another agent in a new
session. You will create a handoff document that is thorough, but also **concise**. The goal is to
compact and summarize your context without losing any of the key details of what you're working on.
## Process
### 1. Filepath & Metadata
Use the following information to understand how to create your document: - create your file under
`thoughts/shared/handoffs/PROJ-XXX/YYYY-MM-DD_HH-MM-SS_description.md`, where: - YYYY-MM-DD is
today's date - HH-MM-SS is the hours, minutes and seconds based on the current time, in 24-hour
format (i.e. use `13:00` for `1:00 pm`) - PROJ-XXX is the ticket number directory (replace with
`general` if no ticket) - description is a brief kebab-case description (optionally including ticket
number) - Get current git information for metadata (branch, commit, repository name) using git
commands - Examples: - With ticket:
`thoughts/shared/handoffs/PROJ-123/2025-01-08_13-55-22_PROJ-123_auth-feature.md` - Without ticket:
`thoughts/shared/handoffs/general/2025-01-08_13-55-22_refactor-api.md`
### 2. Handoff writing.
using the above conventions, write your document. use the defined filepath, and the following YAML
frontmatter pattern. Use the metadata gathered in step 1, Structure the document with YAML
frontmatter followed by content:
Use the following template structure:
```markdown
---
date: [Current date and time with timezone in ISO format]
researcher: [Researcher name from thoughts status]
git_commit: [Current commit hash]
branch: [Current branch name]
repository: [Repository name]
topic: "[Feature/Task Name] Implementation Strategy"
tags: [implementation, strategy, relevant-component-names]
status: complete
last_updated: [Current date in YYYY-MM-DD format]
last_updated_by: [Researcher name]
type: implementation_strategy
---
# Handoff: {TICKET or General} - {very concise description}
## Task(s)
{description of the task(s) that you were working on, along with the status of each (completed, work
in progress, planned/discussed). If you are working on an implementation plan, make sure to call out
which phase you are on. Make sure to reference the plan document and/or research document(s) you are
working from that were provided to you at the beginning of the session, if applicable.}
## Critical References
{List any critical specification documents, architectural decisions, or design docs that must be
followed. Include only 2-3 most important file paths. Leave blank if none.}
## Recent changes
{describe recent changes made to the codebase that you made in line:file syntax}
## Learnings
{describe important things that you learned - e.g. patterns, root causes of bugs, or other important
pieces of information someone that is picking up your work after you should know. consider listing
explicit file paths.}
## Artifacts
{ an exhaustive list of artifacts you produced or updated as filepaths and/or file:line references -
e.g. paths to feature documents, implementation plans, etc that should be read in order to resume
your work.}
## Action Items & Next Steps
{ a list of action items and next steps for the next agent to accomplish based on your tasks and
their statuses}
## Other Notes
{ other notes, references, or useful information - e.g. where relevant sections of the codebase are,
where relevant documents are, or other important things you leanrned that you want to pass on but
that don't fall into the above categories}
```
---
### 3. Approve and Sync
Ask the user to review and approve the document. if they request any changes, you should make them
and ask for approval again. Once the user approves the documents, you should run
`humanlayer thoughts sync` to save the document.
### Track in Workflow Context
After saving the handoff document, add it to workflow context:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" add handoffs "$HANDOFF_FILE" "${TICKET_ID:-null}"
fi
```
Once this is completed, you should respond to the user with the template between
<template_response></template_response> XML tags. do NOT include the tags in your response.
<template_response> Handoff created and synced! You can resume from this handoff in a new session
with the following command:
```bash
/catalyst-dev:resume_handoff path/to/handoff.md
```
</template_response>
for example (between <example_response></example_response> XML tags - do NOT include these tags in
your actual response to the user)
<example_response> Handoff created and synced! You can resume from this handoff in a new session
with the following command:
```bash
/catalyst-dev:resume_handoff thoughts/shared/handoffs/PROJ-123/2025-01-08_13-44-55_PROJ-123_create-context-compaction.md
```
</example_response>
---
##. Additional Notes & Instructions
- **more information, not less**. This is a guideline that defines the minimum of what a handoff
should be. Always feel free to include more information if necessary.
- **be thorough and precise**. include both top-level objectives, and lower-level details as
necessary.
- **avoid excessive code snippets**. While a brief snippet to describe some key change is important,
avoid large code blocks or diffs; do not include one unless it's absolutely necessary. Prefer
using `/path/to/file.ext:line` references that an agent can follow later when it's ready, e.g.
`packages/dashboard/src/app/dashboard/page.tsx:12-24`

587
commands/create_plan.md Normal file
View File

@@ -0,0 +1,587 @@
---
description: Create detailed implementation plans through an interactive process
category: workflow
tools: Read, Write, Grep, Glob, Task, TodoWrite, Bash
model: inherit
version: 1.0.0
---
# Implementation Plan
## Configuration Note
This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
prefix:
- Read from `.claude/config.json` if available
- Otherwise use a generic format like `TICKET-XXX`
- Examples: `ENG-123`, `FEAT-456`, `BUG-789`
You are tasked with creating detailed implementation plans through an interactive, iterative
process. You should be skeptical, thorough, and work collaboratively with the user to produce
high-quality technical specifications.
## Prerequisites
Before executing, verify all required tools and systems:
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Validate plugin scripts
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Initial Response
**STEP 1: Check for recent research (OPTIONAL)**
IMMEDIATELY run this bash script to find recent research that might be relevant:
```bash
# Find recent research that might inform this plan
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_RESEARCH=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent research)
if [[ -n "$RECENT_RESEARCH" ]]; then
echo "💡 Found recent research: $RECENT_RESEARCH"
echo ""
fi
fi
```
**STEP 2: Gather initial input**
After checking for research, follow this logic:
1. **If user provided parameters** (file path or ticket reference):
- Immediately read any provided files FULLY
- If RECENT_RESEARCH was found, ask: "Should I reference the recent research document in this plan?"
- Begin the research process
2. **If no parameters provided**:
- Show any RECENT_RESEARCH that was found
- Respond with:
```
I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
Please provide:
1. The task/ticket description (or reference to a ticket file)
2. Any relevant context, constraints, or specific requirements
3. Links to related research or previous implementations
```
If RECENT_RESEARCH exists, add:
```
💡 I found recent research: $RECENT_RESEARCH
Would you like me to use this as context for the plan?
```
Continue with:
```
I'll analyze this information and work with you to create a comprehensive plan.
Tip: You can also invoke this command with a ticket file directly: `/create_plan thoughts/allison/tickets/proj_123.md`
For deeper analysis, try: `/create_plan think deeply about thoughts/allison/tickets/proj_123.md`
```
Then wait for the user's input.
## Process Steps
### Step 1: Context Gathering & Initial Analysis
1. **Read all mentioned files immediately and FULLY**:
- Ticket files (e.g., `thoughts/allison/tickets/proj_123.md`)
- Research documents
- Related implementation plans
- Any JSON/data files mentioned
- **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. **Spawn initial research tasks to gather context**: Before asking the user any questions, use
specialized agents to research in parallel:
- Use the **codebase-locator** agent to find all files related to the ticket/task
- Use the **codebase-analyzer** agent to understand how the current implementation works
- If relevant, use the **thoughts-locator** agent to find any existing thoughts documents about
this feature
- If a Linear ticket is mentioned, use the **linear-ticket-reader** agent to get full details
These agents will:
- Find relevant source files, configs, and tests
- Identify the specific directories to focus on (e.g., if WUI is mentioned, they'll focus on
humanlayer-wui/)
- Trace data flow and key functions
- Return detailed explanations with file:line references
3. **Read all files identified by research tasks**:
- After research tasks complete, read ALL files they identified as relevant
- Read them FULLY into the main context
- This ensures you have complete understanding before proceeding
4. **Analyze and verify understanding**:
- Cross-reference the ticket requirements with actual code
- Identify any discrepancies or misunderstandings
- Note assumptions that need verification
- Determine true scope based on codebase reality
5. **Present informed understanding and focused questions**:
```
Based on the ticket and my research of the codebase, I understand we need to [accurate summary].
I've found that:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]
Questions that my research couldn't answer:
- [Specific technical question that requires human judgment]
- [Business logic clarification]
- [Design preference that affects implementation]
```
Only ask questions that you genuinely cannot answer through code investigation.
### Step 2: Research & Discovery
After getting initial clarifications:
1. **If the user corrects any misunderstanding**:
- 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
2. **Create a research todo list** using TodoWrite to track exploration tasks
3. **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 local codebase:**
- **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
**For external research:**
- **external-research** - To research framework patterns and best practices from popular repos
- Ask: "How does [framework] recommend implementing [feature]?"
- Ask: "What's the standard approach for [pattern] in [library]?"
- Examples: React patterns, Express middleware, Next.js routing, Prisma schemas
**For historical context:**
- **thoughts-locator** - To find any research, plans, or decisions about this area
- **thoughts-analyzer** - To extract key insights from the most relevant documents
**For related tickets:**
- **linear-searcher** - To find similar issues or past implementations
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
4. **Wait for ALL sub-tasks to complete** before proceeding
5. **Present findings and design options**:
```
Based on my research, here's what I found:
**Current State:**
- [Key discovery about existing code]
- [Pattern or convention to follow]
**Design Options:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]
**Open Questions:**
- [Technical uncertainty]
- [Design decision needed]
Which approach aligns best with your vision?
```
### Step 3: Plan Structure Development
Once aligned on approach:
1. **Create initial plan outline**:
```
Here's my proposed plan structure:
## Overview
[1-2 sentence summary]
## Implementation Phases:
1. [Phase name] - [what it accomplishes]
2. [Phase name] - [what it accomplishes]
3. [Phase name] - [what it accomplishes]
Does this phasing make sense? Should I adjust the order or granularity?
```
2. **Get feedback on structure** before writing details
### Step 4: Detailed Plan Writing
After structure approval:
1. **Write the plan** to `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-description.md`
- Format: `YYYY-MM-DD-PROJ-XXXX-description.md` where:
- YYYY-MM-DD is today's date
- PROJ-XXXX is the ticket number (omit if no ticket)
- description is a brief kebab-case description
- Examples:
- With ticket: `2025-01-08-PROJ-123-parent-child-tracking.md`
- Without ticket: `2025-01-08-improve-error-handling.md`
2. **Use this template structure**:
````markdown
# [Feature/Task Name] Implementation Plan
## Overview
[Brief description of what we're implementing and why]
## Current State Analysis
[What exists now, what's missing, key constraints discovered]
## Desired End State
[A Specification of the desired end state after this plan is complete, and how to verify it]
### Key Discoveries:
- [Important finding with file:line reference]
- [Pattern to follow]
- [Constraint to work within]
## What We're NOT Doing
[Explicitly list out-of-scope items to prevent scope creep]
## Implementation Approach
[High-level strategy and reasoning]
## Phase 1: [Descriptive Name]
### Overview
[What this phase accomplishes]
### Changes Required:
#### 1. [Component/File Group]
**File**: `path/to/file.ext` **Changes**: [Summary of changes]
```[language]
// Specific code to add/modify
```
### Success Criteria:
#### Automated Verification:
- [ ] Migration applies cleanly: `make migrate`
- [ ] Unit tests pass: `make test-component`
- [ ] Type checking passes: `npm run typecheck`
- [ ] Linting passes: `make lint`
- [ ] Integration tests pass: `make test-integration`
#### Manual Verification:
- [ ] Feature works as expected when tested via UI
- [ ] Performance is acceptable under load
- [ ] Edge case handling verified manually
- [ ] No regressions in related features
---
## Phase 2: [Descriptive Name]
[Similar structure with both automated and manual success criteria...]
---
## Testing Strategy
### Unit Tests:
- [What to test]
- [Key edge cases]
### Integration Tests:
- [End-to-end scenarios]
### Manual Testing Steps:
1. [Specific step to verify feature]
2. [Another verification step]
3. [Edge case to test manually]
## Performance Considerations
[Any performance implications or optimizations needed]
## Migration Notes
[If applicable, how to handle existing data/systems]
## References
- Original ticket: `thoughts/allison/tickets/proj_XXXX.md`
- Related research: `thoughts/shared/research/[relevant].md`
- Similar implementation: `[file:line]`
````
### Step 5: Sync and Review
1. **Sync the thoughts directory**:
- Run `humanlayer thoughts sync` to sync the newly created plan
- This ensures the plan is properly indexed and available
2. **Track in Workflow Context**:
After saving the plan document, add it to workflow context:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" add plans "$PLAN_FILE" "${TICKET_ID}"
fi
```
3. **Check context usage and present plan**:
**Monitor your context** and present:
```
✅ Implementation plan created!
**Plan location**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-description.md`
## 📊 Context Status
Current usage: {X}% ({Y}K/{Z}K tokens)
{If >60%}:
⚠️ **Context Alert**: We're at {X}% context usage.
**Recommendation**: Clear context before implementation phase.
**Why?** The implementation phase will:
- Load the complete plan file
- Read multiple source files
- Track progress with TodoWrite
- Benefit from fresh context for optimal performance
**What to do**:
1. ✅ Review the plan (read the file above)
2. ✅ Close this session (clear context)
3. ✅ Start fresh session in worktree
4. ✅ Run `/implement-plan {plan-path}`
This is normal! Context is meant to be cleared between phases.
{If <60%}:
✅ Context healthy ({X}%).
---
Please review the plan and let me know:
- Are the phases properly scoped?
- Are the success criteria specific enough?
- Any technical details that need adjustment?
- Missing edge cases or considerations?
```
4. **Iterate based on feedback** - be ready to:
- Add missing phases
- Adjust technical approach
- Clarify success criteria (both automated and manual)
- Add/remove scope items
- After making changes, run `humanlayer thoughts sync` again
- **Monitor context** - if >70% during iterations, warn user to review file offline
5. **Continue refining** until the user is satisfied
6. **Final context check** after approval:
- If context >50%, remind user to clear before implementation
- Provide clear instructions on next steps with fresh context
## Important Guidelines
1. **Be Skeptical**:
- Question vague requirements
- Identify potential issues early
- Ask "why" and "what about"
- Don't assume - verify with code
2. **Be Interactive**:
- Don't write the full plan in one shot
- Get buy-in at each major step
- Allow course corrections
- Work collaboratively
3. **Be Thorough**:
- Read all context files COMPLETELY before planning
- Research actual code patterns using parallel sub-tasks
- Include specific file paths and line numbers
- Write measurable success criteria with clear automated vs manual distinction
- automated steps should use `make` whenever possible - for example
`make -C humanlayer-wui check` instead of `cd humanlayer-wui && bun run fmt`
4. **Be Practical**:
- Focus on incremental, testable changes
- Consider migration and rollback
- Think about edge cases
- Include "what we're NOT doing"
5. **Track Progress**:
- Use TodoWrite to track planning tasks
- Update todos as you complete research
- Mark planning tasks complete when done
6. **No Open Questions in Final Plan**:
- If you encounter open questions during planning, STOP
- Research or ask for clarification immediately
- Do NOT write the plan with unresolved questions
- The implementation plan must be complete and actionable
- Every decision must be made before finalizing the plan
## Success Criteria Guidelines
**Always separate success criteria into two categories:**
1. **Automated Verification** (can be run by execution agents):
- Commands that can be run: `make test`, `npm run lint`, etc.
- Specific files that should exist
- Code compilation/type checking
- Automated test suites
2. **Manual Verification** (requires human testing):
- UI/UX functionality
- Performance under real conditions
- Edge cases that are hard to automate
- User acceptance criteria
**Format example:**
```markdown
### Success Criteria:
#### Automated Verification:
- [ ] Database migration runs successfully: `make migrate`
- [ ] All unit tests pass: `go test ./...`
- [ ] No linting errors: `golangci-lint run`
- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
#### Manual Verification:
- [ ] New feature appears correctly in the UI
- [ ] Performance is acceptable with 1000+ items
- [ ] Error messages are user-friendly
- [ ] Feature works correctly on mobile devices
```
## Common Patterns
### For Database Changes:
- Start with schema/migration
- Add store methods
- Update business logic
- Expose via API
- Update clients
### For New Features:
- Research existing patterns first
- Start with data model
- Build backend logic
- Add API endpoints
- Implement UI last
### For Refactoring:
- Document current behavior
- Plan incremental changes
- Maintain backwards compatibility
- Include migration strategy
## Sub-task Spawning Best Practices
When spawning research sub-tasks:
1. **Spawn multiple tasks in parallel** for efficiency
2. **Each task should be focused** on a specific area
3. **Provide detailed instructions** including:
- Exactly what to search for
- Which directories to focus on
- What information to extract
- Expected output format
4. **Be EXTREMELY specific about directories**:
- If the ticket mentions "WUI", specify `humanlayer-wui/` directory
- If it mentions "daemon", specify `hld/` directory
- Never use generic terms like "UI" when you mean "WUI"
- Include the full path context in your prompts
5. **Specify read-only tools** to use
6. **Request specific file:line references** in responses
7. **Wait for all tasks to complete** before synthesizing
8. **Verify sub-task results**:
- If a sub-task returns unexpected results, spawn follow-up tasks
- Cross-check findings against the actual codebase
- Don't accept results that seem incorrect
Example of spawning multiple tasks:
```python
# Spawn these tasks concurrently:
tasks = [
Task("Research database schema", db_research_prompt),
Task("Find API patterns", api_research_prompt),
Task("Investigate UI components", ui_research_prompt),
Task("Check test patterns", test_research_prompt)
]
```
## Example Interaction Flow
```
User: /implementation_plan
Assistant: I'll help you create a detailed implementation plan...
User: We need to add parent-child tracking for Claude sub-tasks. See thoughts/allison/tickets/proj_456.md
Assistant: Let me read that ticket file completely first...
[Reads file fully]
Based on the ticket, I understand we need to track parent-child relationships for Claude sub-task events in the hld daemon. Before I start planning, I have some questions...
[Interactive process continues...]
```

351
commands/create_pr.md Normal file
View File

@@ -0,0 +1,351 @@
---
description: Create pull request with automatic Linear integration
category: version-control-git
tools: Bash(linearis *), Bash(git *), Bash(gh *), Read, Task
model: inherit
version: 1.0.0
---
# Create Pull Request
Orchestrates the complete PR creation flow: commit → rebase → push → create → describe → link Linear
ticket.
## Prerequisites
Before executing, verify required tools are installed:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Configuration
Read team configuration from `.claude/config.json`:
```bash
CONFIG_FILE=".claude/config.json"
TEAM_KEY=$(jq -r '.catalyst.linear.teamKey // "PROJ"' "$CONFIG_FILE")
```
## Process:
### 1. Check for uncommitted changes
```bash
git status --porcelain
```
If there are uncommitted changes:
- Offer to commit: "You have uncommitted changes. Create commits now? [Y/n]"
- If yes: internally call `/catalyst-dev:commit` workflow
- If no: proceed (user may want to commit manually later)
### 2. Verify not on main/master branch
```bash
branch=$(git branch --show-current)
```
If on `main` or `master`:
- Error: "Cannot create PR from main branch. Create a feature branch first."
- Exit
### 3. Detect base branch
```bash
# Check which exists
if git show-ref --verify --quiet refs/heads/main; then
base="main"
elif git show-ref --verify --quiet refs/heads/master; then
base="master"
else
base=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
fi
```
### 4. Check if branch is up-to-date with base
```bash
# Fetch latest
git fetch origin $base
# Check if behind
if git log HEAD..origin/$base --oneline | grep -q .; then
echo "Branch is behind $base"
fi
```
If behind:
- Auto-rebase: `git rebase origin/$base`
- If conflicts:
- Show conflicting files
- Error: "Rebase conflicts detected. Resolve conflicts and run /catalyst-dev:create_pr again."
- Exit
### 5. Check for existing PR
```bash
gh pr view --json number,url,title,state 2>/dev/null
```
If PR exists:
- Show: "PR #{number} already exists: {title}\n{url}"
- Ask: "What would you like to do?\n [D] Describe/update this PR\n [S] Skip (do nothing)\n [A]
Abort"
- If D: call `/catalyst-dev:describe_pr` and exit
- If S: exit with success message
- If A: exit
- **This is the ONLY interactive prompt in the happy path**
### 6. Extract ticket from branch name
```bash
branch=$(git branch --show-current)
# Extract pattern: PREFIX-NUMBER using configured team key
if [[ "$branch" =~ ($TEAM_KEY-[0-9]+) ]]; then
ticket="${BASH_REMATCH[1]}" # e.g., RCW-13
fi
```
### 7. Generate PR title from branch and ticket
```bash
# Branch format examples:
# - RCW-13-implement-pr-lifecycle → "RCW-13: implement pr lifecycle"
# - feature-add-validation → "add validation"
# Extract description from branch name
if [[ "$ticket" ]]; then
# Remove ticket prefix from branch
desc=$(echo "$branch" | sed "s/^$ticket-//")
# Convert kebab-case to spaces
desc=$(echo "$desc" | tr '-' ' ')
# Capitalize first word
desc="$(tr '[:lower:]' '[:upper:]' <<< ${desc:0:1})${desc:1}"
title="$ticket: $desc"
else
# No ticket in branch
desc=$(echo "$branch" | tr '-' ' ')
desc="$(tr '[:lower:]' '[:upper:]' <<< ${desc:0:1})${desc:1}"
title="$desc"
fi
```
### 8. Push branch
```bash
# Check if branch has upstream
if ! git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null; then
# No upstream, push with -u
git push -u origin HEAD
else
# Has upstream, check if up-to-date
git push
fi
```
### 9. Create PR
**CRITICAL: NO CLAUDE ATTRIBUTION**
DO NOT add any of the following to the PR:
- ❌ "Generated with Claude Code" or similar messages
- ❌ "Co-Authored-By: Claude" lines
- ❌ Any reference to AI assistance
- ❌ Links to Claude Code or Anthropic
The PR should be authored solely by the user (git author). Keep the description clean and professional.
```bash
# Minimal initial body (NO CLAUDE ATTRIBUTION)
body="Automated PR creation. Comprehensive description generating..."
# If ticket exists, add reference
if [[ "$ticket" ]]; then
body="$body\n\nRefs: $ticket"
fi
# Create PR (author will be the git user)
gh pr create --title "$title" --body "$body" --base "$base"
```
Capture PR number and URL from output.
### Track in Workflow Context
After creating the PR, add it to workflow context:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" add prs "$PR_URL" "${TICKET_ID:-null}"
fi
```
### 10. Auto-call /catalyst-dev:describe_pr
Immediately call `/catalyst-dev:describe_pr` with the PR number to:
- Generate comprehensive description
- Run verification checks
- Update PR title (refined from code analysis)
- Save to thoughts/
- Update Linear ticket
### 11. Update Linear ticket (if ticket found)
If ticket was extracted from branch:
```bash
# Verify linearis is available
if ! command -v linearis &> /dev/null; then
echo "⚠️ Linearis CLI not found - skipping Linear ticket update"
echo "Install: npm install -g --install-links ryanrozich/linearis#feat/cycles-cli"
else
# Update ticket state to "In Review"
linearis issues update "$ticket" --state "In Review" --assignee "@me"
# Add comment with PR link
linearis comments create "$ticket" \
--body "PR created and ready for review!\n\n**PR**: $prUrl\n\nDescription has been auto-generated with verification checks."
fi
```
### 12. Report success
```
✅ Pull request created successfully!
**PR**: #{number} - {title}
**URL**: {url}
**Base**: {base_branch}
**Ticket**: {ticket} (moved to "In Review")
Description has been generated and verification checks have been run.
Review the PR on GitHub!
```
## Error Handling
**On main/master branch:**
```
❌ Cannot create PR from main branch.
Create a feature branch first:
git checkout -b TICKET-123-feature-name
```
**Rebase conflicts:**
```
❌ Rebase conflicts detected
Conflicting files:
- src/file1.ts
- src/file2.ts
Resolve conflicts and run:
git add <resolved-files>
git rebase --continue
/catalyst-dev:create_pr
```
**GitHub CLI not configured:**
```
❌ GitHub CLI not configured
Run: gh auth login
Then: gh repo set-default
```
**Linearis CLI not found:**
```
⚠️ Linearis CLI not found
PR created successfully, but Linear ticket not updated.
Install Linearis:
npm install -g --install-links ryanrozich/linearis#feat/cycles-cli
Configure:
export LINEAR_API_TOKEN=your_token
```
**Linear ticket not found:**
```
⚠️ Could not find Linear ticket for {ticket}
PR created successfully, but ticket not updated.
Update manually or check ticket ID.
```
## Configuration
Uses `.claude/config.json`:
```json
{
"catalyst": {
"project": {
"ticketPrefix": "RCW"
},
"linear": {
"teamKey": "RCW",
"inReviewStatusName": "In Review"
}
}
}
```
## Examples
**Branch: `RCW-13-implement-pr-lifecycle`**
```
Extracting ticket: RCW-13
Generated title: "RCW-13: Implement pr lifecycle"
Creating PR...
✅ PR #2 created
Calling /catalyst-dev:describe_pr to generate description...
Updating Linear ticket RCW-13 → In Review
✅ Complete!
```
**Branch: `feature-add-validation` (no ticket)**
```
No ticket found in branch name
Generated title: "Feature add validation"
Creating PR...
✅ PR #3 created
Calling /catalyst-dev:describe_pr...
⚠️ No Linear ticket to update
✅ Complete!
```
## Integration with Other Commands
- **Calls `/catalyst-dev:commit`** - if uncommitted changes (optional)
- **Calls `/catalyst-dev:describe_pr`** - always, to generate comprehensive description
- **Sets up for `/catalyst-dev:merge_pr`** - PR is now ready for review and eventual merge
## Remember:
- **Minimize prompts** - only ask when PR already exists
- **Auto-rebase** - keep branch up-to-date with base
- **Auto-link Linear** - extract ticket from branch, update status with Linearis CLI
- **Auto-describe** - comprehensive description generated immediately
- **Fail fast** - stop on conflicts or errors with clear messages
- **Graceful degradation** - If Linearis not installed, warn but continue

105
commands/create_worktree.md Normal file
View File

@@ -0,0 +1,105 @@
---
description: Create a git worktree for parallel work and optionally launch implementation session
category: version-control-git
tools: Bash, Read
model: inherit
version: 1.0.0
---
## Configuration Note
This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
prefix:
- Read from `.claude/config.json` if available
- Otherwise use a generic format like `TICKET-XXX`
- Examples: `ENG-123`, `FEAT-456`, `BUG-789`
You are tasked with creating a git worktree for parallel development work.
## Process
When this command is invoked:
1. **Gather required information**:
- Worktree name (e.g., PROJ-123, feature-name)
- Base branch (default: current branch)
- Optional: Path to implementation plan
2. **Confirm with user**: Present the worktree details and get confirmation before creating.
3. **Create the worktree**: Use the create-worktree.sh script:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" <worktree_name> [base_branch]
```
The script automatically:
- Detects GitHub org/repo from git remote
- Uses `GITHUB_SOURCE_ROOT` environment variable if set
- Creates worktrees in a clean, organized structure
4. **Initialize thoughts** (REQUIRED - handled automatically by script):
The create-worktree.sh script automatically initializes thoughts and syncs with the shared
repository, giving the worktree access to:
- Shared research documents
- Implementation plans
- Handoff documents
- Team knowledge base
5. **Optional: Launch implementation session**: If a plan file path was provided, ask if the user
wants to launch Claude in the worktree:
```bash
humanlayer launch --model opus -w <worktree_path> \
"/implement_plan <plan_path> and when done: create commit, create PR, update Linear ticket"
```
## Worktree Location Convention
**Recommended Setup**: Set `GITHUB_SOURCE_ROOT` environment variable for clean organization:
```bash
# In ~/.zshrc or ~/.bashrc
export GITHUB_SOURCE_ROOT="$HOME/code-repos/github"
```
**Convention**:
- **Main repository**: `${GITHUB_SOURCE_ROOT}/<org>/<repo>`
- Example: `~/code-repos/github/coalesce-labs/catalyst`
- **Worktrees**: `${GITHUB_SOURCE_ROOT}/<org>/<repo>-worktrees/<feature>`
- Example: `~/code-repos/github/coalesce-labs/catalyst-worktrees/PROJ-123`
**Fallback behavior** (if `GITHUB_SOURCE_ROOT` not set):
- Defaults to `~/wt/<repo_name>/<worktree_name>`
**Why this convention?**
- ✅ Main branches and worktrees are organized together by org/repo
- ✅ Easy to find: all worktrees for a project in one place
- ✅ Clean separation: `<repo>` vs `<repo>-worktrees`
- ✅ Configurable per-developer via environment variable
- ✅ No hardcoded paths in scripts or documentation
**Example with GITHUB_SOURCE_ROOT**:
```
~/code-repos/github/
├── coalesce-labs/
│ ├── catalyst/ # Main branch
│ └── catalyst-worktrees/ # All worktrees
│ ├── PROJ-123-feature/
│ └── PROJ-456-bugfix/
└── acme/
├── api/ # Main branch
└── api-worktrees/ # All worktrees
└── ENG-789-oauth/
```
## Example Interaction
```
User: /catalyst-dev:create_worktree PROJ-123
```

117
commands/cycle_plan.md Normal file
View File

@@ -0,0 +1,117 @@
---
description: Plan work for current or next cycle using Linearis and GitHub
category: project-task-management
tools: Bash(linearis *), Bash(gh *), Read, Write, TodoWrite
model: inherit
version: 1.0.0
status: placeholder
---
# Cycle Planning
**Status**: Placeholder for v1.0 - Full implementation coming in future release
## Planned Functionality
This command will help you plan work for the current or upcoming cycle by:
1. Fetching current and next cycle information
2. Listing backlog tickets ready for planning
3. Interactively assigning tickets to cycles
4. Setting milestones and priorities
5. Generating cycle plan summary
## Current Workaround
Use Linearis CLI directly:
```bash
# Get active cycle
linearis cycles list --team TEAM --active
# List backlog tickets (filter with jq - issues list only supports --limit)
linearis issues list --limit 100 | jq '.[] | select(.state.name == "Backlog")'
# Assign ticket to cycle
linearis issues update TICKET-123 --cycle "Sprint 2025-11"
# Set priority
linearis issues update TICKET-123 --priority 2
```
### Example Workflow
```bash
# 1. View active cycle
linearis cycles list --team ENG --active | jq '.[] | {name, startsAt, endsAt, progress}'
# 2. View next cycle
linearis cycles list --team ENG --limit 5 | jq '.[1]'
# 3. List backlog tickets ready for planning (filter with jq)
linearis issues list --limit 100 | \
jq '.[] | select(.state.name == "Backlog") | {id, title, priority}'
# 4. Review recent PRs to understand current work
# This helps identify work done but not captured in Linear tickets
gh pr list --state merged --limit 20 --json number,title,author,mergedAt,closedAt
# Filter by date range (e.g., last 2 weeks for planning context)
gh pr list --state merged --search "merged:>=$(date -v-14d +%Y-%m-%d)" \
--json number,title,author,mergedAt --jq '.[] | "\(.author.login): \(.title)"'
# 5. Identify who is working on what
gh pr list --state open --json number,title,author,createdAt | \
jq 'group_by(.author.login) | map({author: .[0].author.login, prs: map({number, title})})'
# 6. Assign high-priority tickets to next cycle
linearis issues update ENG-123 --cycle "Sprint 2025-11" --priority 2
linearis issues update ENG-124 --cycle "Sprint 2025-11" --priority 2
# 7. Generate summary (manual)
# Count tickets by cycle and priority
```
## Future Implementation
When fully implemented, this command will:
- **Interactive cycle selection** - Choose current or next cycle
- **Smart backlog filtering** - Show tickets by priority and readiness
- **Batch assignment** - Select multiple tickets to assign at once
- **Capacity planning** - Estimate points/hours per ticket
- **Milestone tracking** - Group tickets by project milestones
- **PR-based work tracking** - Auto-detect work from merged/open PRs to identify:
- Work completed but not tracked in Linear
- Who is actively working on what
- Team velocity based on PR activity
- **Team activity report** - Show contribution breakdown by team member
- **Summary generation** - Create cycle plan document in thoughts/
Track progress at: https://github.com/coalesce-labs/catalyst/issues
## Configuration
Uses `.claude/config.json`:
```json
{
"linear": {
"teamKey": "ENG",
"defaultTeam": "Backend"
}
}
```
## Tips
- Plan cycles **before they start** - gives team time to review
- Prioritize by **user impact** and **dependencies**
- Leave **buffer capacity** for bugs and urgent tasks
- Use **milestones** to group related work
- Review cycle plans in team meetings for alignment
- **Check PR activity** before planning to understand:
- What work has been completed recently
- Who is actively contributing
- Untracked work that should be captured in Linear
- Team velocity and capacity trends

143
commands/cycle_review.md Normal file
View File

@@ -0,0 +1,143 @@
---
description: Review cycle progress and identify blockers using Linearis and GitHub
category: project-task-management
tools: Bash(linearis *), Bash(gh *), Read, Write, TodoWrite
model: inherit
version: 1.0.0
status: placeholder
---
# Cycle Review
**Status**: Placeholder for v1.0 - Full implementation coming in future release
## Planned Functionality
This command will help you review cycle progress by:
1. Fetching active cycle details
2. Calculating completion percentage by status
3. Identifying blocked tickets
4. Generating velocity metrics
5. Creating cycle summary report
## Current Workaround
Use Linearis CLI directly:
```bash
# Get active cycle with tickets
linearis cycles read "Sprint 2025-10" --team TEAM
# List tickets by status (use cycles read to get all issues, then filter)
linearis cycles read "Sprint 2025-10" --team TEAM | \
jq '.issues[] | select(.state.name == "In Progress")'
linearis cycles read "Sprint 2025-10" --team TEAM | \
jq '.issues[] | select(.state.name == "Done")'
# Calculate completion manually (count tickets)
```
### Example Workflow
```bash
# 1. Get active cycle info
CYCLE=$(linearis cycles list --team ENG --active | jq -r '.[0].name')
echo "Active cycle: $CYCLE"
# 2. Get all tickets in cycle
linearis issues list --team ENG | \
jq --arg cycle "$CYCLE" '.[] | select(.cycle.name == $cycle)'
# 3. Count by status (use cycles read to get issues)
CYCLE_DATA=$(linearis cycles read "$CYCLE" --team ENG)
echo "Backlog:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "Backlog")] | length'
echo "In Progress:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "In Progress")] | length'
echo "Done:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "Done")] | length'
# 4. Calculate completion percentage
# total_tickets = backlog + in_progress + done
# completion = (done / total_tickets) * 100
# 5. Find blocked tickets (use cycles read)
linearis cycles read "$CYCLE" --team ENG | \
jq '.issues[] | select(.state.name == "Blocked") | {id, title, blockedReason}'
# 6. Review PRs merged during cycle
# Get cycle start date (example: 2 weeks ago)
CYCLE_START=$(date -v-14d +%Y-%m-%d)
# List all PRs merged during cycle
gh pr list --state merged --search "merged:>=$CYCLE_START" \
--json number,title,author,mergedAt --jq \
'.[] | "\(.mergedAt | split("T")[0]) - \(.author.login): \(.title)"'
# 7. Identify active contributors
gh pr list --state merged --search "merged:>=$CYCLE_START" \
--json author --jq '[.[].author.login] | group_by(.) | map({author: .[0], count: length}) | sort_by(-.count)'
# 8. Check open PRs (work in progress)
gh pr list --state open --json number,title,author,createdAt,isDraft | \
jq '.[] | {author: .author.login, title, days_open: ((now - (.createdAt | fromdateiso8601)) / 86400 | floor), draft: .isDraft}'
# 9. Find work without Linear tickets
# Compare PR titles with Linear ticket IDs (TEAM-XXX pattern)
gh pr list --state merged --search "merged:>=$CYCLE_START" \
--json number,title --jq '.[] | select(.title | test("TEAM-[0-9]+") | not) | {number, title}'
```
## Future Implementation
When fully implemented, this command will:
- **Automated metrics** - Calculate completion, velocity, cycle time
- **Status breakdown** - Show tickets grouped by status with percentages
- **Blocker identification** - Highlight blocked tickets with reasons
- **Trend analysis** - Compare to previous cycles
- **Risk assessment** - Identify at-risk tickets (large, old, no progress)
- **PR-based activity tracking** - Analyze GitHub PR data to:
- Identify who completed what work during the cycle
- Find work done without Linear tickets (untracked work)
- Calculate actual velocity based on merged PRs
- Show contributor activity breakdown
- Flag stale PRs that need attention
- **Work reconciliation** - Match PRs to Linear tickets, flag mismatches
- **Team contribution report** - Show per-person breakdown of PRs and tickets
- **Summary generation** - Create review document in thoughts/
- **Burndown visualization** - Show progress over time (text-based chart)
Track progress at: https://github.com/coalesce-labs/catalyst/issues
## Configuration
Uses `.claude/config.json`:
```json
{
"linear": {
"teamKey": "ENG",
"defaultTeam": "Backend"
}
}
```
## Tips
- Review **mid-cycle** to course-correct
- Review **end-of-cycle** for retrospectives
- Track **blockers daily** - don't wait for review
- Compare velocity across cycles for **capacity planning**
- Document **lessons learned** for process improvement
- Celebrate **wins** - acknowledge team progress
- **Use PR data to understand actual work**:
- Merged PRs show completed work (even if not in Linear)
- Open PRs show current work in progress
- PR activity reveals team contribution patterns
- Missing ticket references indicate process gaps
- **Reconcile Linear and GitHub regularly** to ensure all work is tracked

227
commands/debug.md Normal file
View File

@@ -0,0 +1,227 @@
---
description: Debug issues by investigating logs, database state, and git history
category: dev
tools: Read, Bash, Task, Grep
model: inherit
version: 1.0.0
---
# Debug
You are tasked with helping debug issues during manual testing or implementation. This command
allows you to investigate problems by examining logs, database state, and git history without
editing files. Think of this as a way to bootstrap a debugging session without using the primary
window's context.
## Initial Response
When invoked WITH a plan/ticket file:
```
I'll help debug issues with [file name]. Let me understand the current state.
What specific problem are you encountering?
- What were you trying to test/implement?
- What went wrong?
- Any error messages?
I'll investigate the logs, database, and git state to help figure out what's happening.
```
When invoked WITHOUT parameters:
```
I'll help debug your current issue.
Please describe what's going wrong:
- What are you working on?
- What specific problem occurred?
- When did it last work?
I can investigate logs, database state, and recent changes to help identify the issue.
```
## Environment Information
You have access to these key locations and tools:
**Logs** (automatically created by `make daemon` and `make wui`):
- MCP logs: `~/.humanlayer/logs/mcp-claude-approvals-*.log`
- Combined WUI/Daemon logs: `~/.humanlayer/logs/wui-${BRANCH_NAME}/codelayer.log`
- First line shows: `[timestamp] starting [service] in [directory]`
**Database**:
- Location: `~/.humanlayer/daemon-{BRANCH_NAME}.db`
- SQLite database with sessions, events, approvals, etc.
- Can query directly with `sqlite3`
**Git State**:
- Check current branch, recent commits, uncommitted changes
- Similar to how `commit` and `describe_pr` commands work
**Service Status**:
- Check if daemon is running: `ps aux | grep hld`
- Check if WUI is running: `ps aux | grep wui`
- Socket exists: `~/.humanlayer/daemon.sock`
## Process Steps
### Step 1: Understand the Problem
After the user describes the issue:
1. **Read any provided context** (plan or ticket file):
- Understand what they're implementing/testing
- Note which phase or step they're on
- Identify expected vs actual behavior
2. **Quick state check**:
- Current git branch and recent commits
- Any uncommitted changes
- When the issue started occurring
### Step 2: Investigate the Issue
Spawn parallel Task agents for efficient investigation:
```
Task 1 - Check Recent Logs:
Find and analyze the most recent logs for errors:
1. Find latest daemon log: ls -t ~/.humanlayer/logs/daemon-*.log | head -1
2. Find latest WUI log: ls -t ~/.humanlayer/logs/wui-*.log | head -1
3. Search for errors, warnings, or issues around the problem timeframe
4. Note the working directory (first line of log)
5. Look for stack traces or repeated errors
Return: Key errors/warnings with timestamps
```
```
Task 2 - Database State:
Check the current database state:
1. Connect to database: sqlite3 ~/.humanlayer/daemon.db
2. Check schema: .tables and .schema for relevant tables
3. Query recent data:
- SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;
- SELECT * FROM conversation_events WHERE created_at > datetime('now', '-1 hour');
- Other queries based on the issue
4. Look for stuck states or anomalies
Return: Relevant database findings
```
```
Task 3 - Git and File State:
Understand what changed recently:
1. Check git status and current branch
2. Look at recent commits: git log --oneline -10
3. Check uncommitted changes: git diff
4. Verify expected files exist
5. Look for any file permission issues
Return: Git state and any file issues
```
### Step 3: Present Findings
Based on the investigation, present a focused debug report:
````markdown
## Debug Report
### What's Wrong
[Clear statement of the issue based on evidence]
### Evidence Found
**From Logs** (`~/.humanlayer/logs/`):
- [Error/warning with timestamp]
- [Pattern or repeated issue]
**From Database**:
```sql
-- Relevant query and result
[Finding from database]
```
````
**From Git/Files**:
- [Recent changes that might be related]
- [File state issues]
### Root Cause
[Most likely explanation based on evidence]
### Next Steps
1. **Try This First**:
```bash
[Specific command or action]
```
2. **If That Doesn't Work**:
- Restart services: `make daemon` and `make wui`
- Check browser console for WUI errors
- Run with debug: `HUMANLAYER_DEBUG=true make daemon`
### Can't Access?
Some issues might be outside my reach:
- Browser console errors (F12 in browser)
- MCP server internal state
- System-level issues
Would you like me to investigate something specific further?
````
## Important Notes
- **Focus on manual testing scenarios** - This is for debugging during implementation
- **Always require problem description** - Can't debug without knowing what's wrong
- **Read files completely** - No limit/offset when reading context
- **Think like `commit` or `describe_pr`** - Understand git state and changes
- **Guide back to user** - Some issues (browser console, MCP internals) are outside reach
- **No file editing** - Pure investigation only
## Quick Reference
**Find Latest Logs**:
```bash
ls -t ~/.humanlayer/logs/daemon-*.log | head -1
ls -t ~/.humanlayer/logs/wui-*.log | head -1
````
**Database Queries**:
```bash
sqlite3 ~/.humanlayer/daemon.db ".tables"
sqlite3 ~/.humanlayer/daemon.db ".schema sessions"
sqlite3 ~/.humanlayer/daemon.db "SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;"
```
**Service Check**:
```bash
ps aux | grep hld # Is daemon running?
ps aux | grep wui # Is WUI running?
```
**Git State**:
```bash
git status
git log --oneline -10
git diff
```
Remember: This command helps you investigate without burning the primary window's context. Perfect
for when you hit an issue during manual testing and need to dig into logs, database, or git state.

557
commands/describe_pr.md Normal file
View File

@@ -0,0 +1,557 @@
---
description: Generate or update PR description with incremental changes
category: version-control-git
tools: Bash, Read, Write
model: inherit
version: 2.0.0
---
# Generate/Update PR Description
Generates or updates PR description with incremental information, auto-updates title, and links
Linear tickets.
## Prerequisites
Before executing, verify all required tools and systems:
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Validate plugin scripts
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Process:
### 1. Read PR description template
```bash
# Check if template exists
if [ ! -f "thoughts/shared/pr_description.md" ]; then
echo "❌ PR description template not found"
fi
```
If missing:
```
❌ PR description template missing
Your humanlayer thoughts setup is incomplete. Create a template at:
thoughts/shared/pr_description.md
See the PR description template you created earlier for reference.
```
Read template fully to understand all sections.
### 2. Identify target PR
**If argument provided:**
- Use that PR number: `/describe_pr 123`
**If no argument:**
```bash
# Try current branch
gh pr view --json number,url,title,state,body,headRefName,baseRefName 2>/dev/null
```
If no PR on current branch OR on main/master:
```bash
# List recent PRs
gh pr list --limit 10 --json number,title,headRefName,state
```
Ask user: "Which PR would you like to describe? (enter number)"
### 3. Extract ticket reference
**From multiple sources:**
```bash
# 1. From branch name
branch=$(gh pr view $pr_number --json headRefName -q .headRefName)
if [[ "$branch" =~ ([A-Z]+)-([0-9]+) ]]; then
ticket="${BASH_REMATCH[0]}"
fi
# 2. From PR title
title=$(gh pr view $pr_number --json title -q .title)
if [[ "$title" =~ ([A-Z]+)-([0-9]+) ]]; then
ticket="${BASH_REMATCH[0]}"
fi
# 3. From existing PR body
body=$(gh pr view $pr_number --json body -q .body)
if [[ "$body" =~ Refs:\ ([A-Z]+-[0-9]+) ]]; then
ticket="${BASH_REMATCH[1]}"
fi
```
### 4. Read existing descriptions
**Read current PR body from GitHub:**
```bash
current_body=$(gh pr view $pr_number --json body -q .body)
```
**Read saved description (if exists):**
```bash
saved_desc="thoughts/shared/prs/${pr_number}_description.md"
if [ -f "$saved_desc" ]; then
# Read fully
# Note what sections exist vs what's new
fi
```
**Check for metadata header:**
```markdown
<!-- Auto-generated: 2025-10-06T10:30:00Z -->
<!-- Last updated: 2025-10-06T14:45:00Z -->
<!-- PR: #123 -->
<!-- Previous commits: abc123,def456 -->
```
### 5. Gather comprehensive PR information
```bash
# Full diff
gh pr diff $pr_number
# Commit history with messages
gh pr view $pr_number --json commits
# Changed files
gh pr view $pr_number --json files
# PR metadata
gh pr view $pr_number --json url,title,number,state,baseRefName,headRefName,author
# CI/CD status
gh pr checks $pr_number
```
### 6. Analyze changes incrementally
**If this is an UPDATE (saved description exists):**
```bash
# Extract previous commit list from metadata
prev_commits=$(grep "Previous commits:" $saved_desc | sed 's/.*: //')
# Get current commits
current_commits=$(gh pr view $pr_number --json commits -q '.commits[].oid' | tr '\n' ',' | sed 's/,$//')
# Compare
new_commits=$(comm -13 <(echo "$prev_commits" | tr ',' '\n' | sort) <(echo "$current_commits" | tr ',' '\n' | sort))
```
**Analysis:**
- Identify what's NEW since last description
- Deep analysis of:
- Code changes and architectural impact
- Breaking changes
- User-facing vs internal changes
- Migration requirements
- Security implications
### 7. Merge descriptions intelligently
**Auto-generated sections (always update):**
- **Summary** - regenerate based on ALL changes
- **Changes Made** - append new changes, preserve old
- **How to Verify It** - update checklist, rerun checks
- **Changelog Entry** - update to reflect all changes
**Preserve manual edits in:**
- **Reviewer Notes** - keep existing unless explicitly empty
- **Screenshots/Videos** - never overwrite
- **Manually checked boxes** - preserve [x] marks for manual steps
- **Post-Merge Tasks** - append new, keep existing
**Merging strategy:**
```markdown
## Changes Made
### Backend Changes
[Existing changes from previous description]
**New changes** (since last update):
- [New change 1]
- [New change 2]
### Frontend Changes
[Existing + new merged together]
```
**Add change summary at top:**
```markdown
<!-- Auto-generated: 2025-10-06T15:00:00Z -->
<!-- Last updated: 2025-10-06T15:00:00Z -->
<!-- PR: #123 -->
<!-- Previous commits: abc123,def456,ghi789 -->
---
**Update History:**
- 2025-10-06 15:00: Added validation logic, updated tests (3 new commits)
- 2025-10-06 10:30: Initial implementation (5 commits)
---
```
### 8. Add Linear reference
If ticket found:
```markdown
## Related Issues/PRs
- Fixes https://linear.app/{workspace}/issue/{ticket}
- Related to [any other linked issues]
```
Get Linear ticket details:
```bash
# Use Linearis CLI to get ticket details
linearis issues read "$ticket"
# Extract title and description with jq
ticket_title=$(linearis issues read "$ticket" | jq -r '.title')
ticket_description=$(linearis issues read "$ticket" | jq -r '.description')
```
Use ticket title and description for context.
### 9. Generate updated title
**Title generation rules:**
```bash
# If ticket exists
if [[ "$ticket" ]]; then
# Get ticket title from Linear
ticket_title=$(linear API or fallback to branch)
# Format: TICKET: Descriptive title (max 72 chars)
title="$ticket: ${ticket_title:0:60}"
else
# Generate from primary change
# Analyze commits and code changes
title="Brief summary of main change"
fi
```
**Auto-update without prompt** - title is auto-generated section.
### 10. Run verification checks
**For each checklist item in "How to Verify It":**
```bash
# Example: "- [ ] Build passes: `make build`"
# Extract command: make build
# Try to run
if command -v make >/dev/null 2>&1; then
if make build 2>&1; then
# Mark as checked
checkbox="- [x] Build passes: \`make build\` ✅"
else
# Mark unchecked with error
checkbox="- [ ] Build passes: \`make build\` ❌ (failed: $error)"
fi
else
# Can't run
checkbox="- [ ] Build passes: \`make build\` (manual verification required)"
fi
```
**Common checks to attempt:**
- `make test` / `npm test` / `pytest`
- `make lint` / `npm run lint`
- `npm run typecheck` / `tsc --noEmit`
- `make build` / `npm run build`
**Document results:**
- ✅ if passed
- ❌ if failed (with error)
- Manual required if can't automate
### 11. Save and sync
**Save description:**
```bash
# Add metadata header
cat > "thoughts/shared/prs/${pr_number}_description.md" <<EOF
<!-- Auto-generated: $(date -u +%Y-%m-%dT%H:%M:%SZ) -->
<!-- Last updated: $(date -u +%Y-%m-%dT%H:%M:%SZ) -->
<!-- PR: #$pr_number -->
<!-- Previous commits: $commit_list -->
[Full description content]
EOF
```
**Sync thoughts:**
```bash
humanlayer thoughts sync
```
### 12. Update PR on GitHub
**CRITICAL: NO CLAUDE ATTRIBUTION**
Before updating the PR, ensure the description contains NO Claude attribution:
❌ **Remove these if present**:
- "Generated with Claude Code" or similar messages
- "Co-Authored-By: Claude" lines
- Any reference to AI assistance or Anthropic
- Links to Claude Code documentation
✅ **Keep descriptions professional and human-authored**:
- Focus on code changes and their purpose
- Attribute work to the git author (the human developer)
- Write in first-person if needed ("I added...", "We implemented...")
**Update title:**
```bash
gh pr edit $pr_number --title "$new_title"
```
**Update body:**
```bash
# Ensure no Claude attribution in the description file
gh pr edit $pr_number --body-file "thoughts/shared/prs/${pr_number}_description.md"
```
### 13. Update Linear ticket
If ticket found:
```bash
# Verify linearis is available
if ! command -v linearis &> /dev/null; then
echo "⚠️ Linearis CLI not found - skipping Linear ticket update"
else
# If not already in "In Review", move it and assign to self
linearis issues update "$ticket" --state "In Review" --assignee "@me"
# Add comment about update with PR link
linearis comments create "$ticket" \
--body "PR description updated!\n\n**Changes**: ${updateSummary}\n**Verification**: ${checksPassedCount}/${totalChecks} automated checks passed\n\nView PR: ${prUrl}"
fi
```
### 14. Report results
**If first-time generation:**
```
✅ PR description generated!
**PR**: #123 - {title}
**URL**: {url}
**Verification**: {X}/{Y} automated checks passed
**Linear**: {ticket} updated
Manual verification steps remaining:
- [ ] Test feature in staging
- [ ] Verify UI on mobile
Review PR on GitHub!
```
**If incremental update:**
```
✅ PR description updated!
**Changes since last update**:
- 3 new commits
- Added validation logic
- Updated tests
**Verification**: {X}/{Y} automated checks passed
**Sections updated**: Summary, Changes Made, How to Verify It
**Sections preserved**: Reviewer Notes, Screenshots
**What changed**:
Updated: Summary, Backend Changes, Automated Checks
Preserved: Manual verification steps, Reviewer notes
Added: New validation section
Review updated PR: {url}
```
## Metadata Management
**First generation:**
```markdown
<!-- Auto-generated: 2025-10-06T10:00:00Z -->
<!-- Last updated: 2025-10-06T10:00:00Z -->
<!-- PR: #123 -->
<!-- Previous commits: abc123,def456 -->
```
**Subsequent updates:**
```markdown
<!-- Auto-generated: 2025-10-06T10:00:00Z -->
<!-- Last updated: 2025-10-06T15:30:00Z -->
<!-- PR: #123 -->
<!-- Previous commits: abc123,def456,ghi789,jkl012 -->
---
**Update History:**
- 2025-10-06 15:30: Added error handling, fixed tests (2 commits)
- 2025-10-06 10:00: Initial implementation (2 commits)
---
```
## Incremental Update Examples
**Example 1: Code review changes**
```
User pushes 2 commits after code review feedback
/catalyst-dev:describe_pr detects:
- 2 new commits
- Changes in validation logic
- New tests added
Updates:
- Appends to "Backend Changes"
- Updates "How to Verify It" (reruns test check)
- Updates Summary to mention review changes
- Preserves reviewer notes and screenshots
- Adds to update history
```
**Example 2: Multiple updates**
```
Update 1 (initial): 5 commits
Update 2 (review): 3 commits
Update 3 (fixes): 2 commits
Description shows:
- Complete history in update log
- All changes accumulated
- Latest verification status
- All manual notes preserved
```
## Error Handling
**No PR found:**
```
❌ No PR found for current branch
Open PRs:
#120 - Feature A (feature-a branch)
#121 - Fix B (fix-b branch)
Which PR? (enter number)
```
**Template missing:**
```
❌ PR description template required
Create: thoughts/shared/pr_description.md
See earlier in conversation for template structure.
```
**Verification command fails:**
```
⚠️ Some automated checks failed
Failed:
- make test (exit code 1)
Error: 2 tests failed in validation.test.ts
Passed:
- make lint ✅
- make build ✅
Fix failing tests before merge or document as known issues.
```
## Configuration
Uses `.claude/config.json`:
```json
{
"catalyst": {
"project": {
"ticketPrefix": "RCW"
},
"linear": {
"teamId": "team-id",
"inReviewStatusName": "In Review"
},
"pr": {
"testCommand": "make test",
"lintCommand": "make lint",
"buildCommand": "make build"
}
}
}
```
## Remember:
- **No interactive prompts** - fully automated
- **Incremental updates** - preserve manual edits, append new
- **Auto-update title** - based on analysis
- **Run verification** - attempt all automated checks
- **Link Linear** - extract ticket, update status
- **Show what changed** - clear summary of updates
- **Full context** - read entire existing description
- **Metadata tracking** - commit history, timestamps

190
commands/implement_plan.md Normal file
View File

@@ -0,0 +1,190 @@
---
description: Implement approved technical plans from thoughts/shared/plans/
category: workflow
tools: Read, Write, Edit, Grep, Glob, Task, TodoWrite, Bash
model: inherit
version: 1.0.0
---
# Implement Plan
You are tasked with implementing an approved technical plan from `thoughts/shared/plans/`. These
plans contain phases with specific changes and success criteria.
## Prerequisites
Before executing, verify required tools are installed:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Initial Response
**STEP 1: Auto-discover recent plan (REQUIRED)**
IMMEDIATELY run this bash script BEFORE any other response:
```bash
# Auto-discover most recent plan from workflow context
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_PLAN=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent plans)
if [[ -n "$RECENT_PLAN" ]]; then
echo "📋 Auto-discovered recent plan: $RECENT_PLAN"
echo ""
fi
fi
```
**STEP 2: Determine which plan to implement**
After running the auto-discovery script, follow this logic:
1. **If user provided a plan path as parameter**:
- Use the provided path (user override)
- Skip to Step 3
2. **If no parameter provided AND RECENT_PLAN was found**:
- Show user: "📋 Found recent plan: $RECENT_PLAN"
- Ask: "**Proceed with this plan?** [Y/n]"
- If yes: use RECENT_PLAN and skip to Step 3
- If no: proceed to option 3
3. **If no parameter AND no RECENT_PLAN found**:
- List available plans from `thoughts/shared/plans/`
- Show most recent 5 plans with dates and ticket numbers
- Ask user which plan to implement
- Wait for user input with plan path
**STEP 3: Read and prepare**
Once you have a plan path:
- Read the plan completely (no limit/offset)
- Check for any existing checkmarks (- [x]) to see what's done
- Read the original ticket and all files mentioned in the plan
- Think deeply about how the pieces fit together
- Create a todo list to track your progress
- Start implementing if you understand what needs to be done
## Implementation Philosophy
Plans are carefully designed, but reality can be messy. Your job is to:
- Follow the plan's intent while adapting to what you find
- Implement each phase fully before moving to the next
- Verify your work makes sense in the broader codebase context
- Update checkboxes in the plan as you complete sections
When things don't match the plan exactly, think about why and communicate clearly. The plan is your
guide, but your judgment matters too.
If you encounter a mismatch:
- STOP and think deeply about why the plan can't be followed
- Present the issue clearly:
```
Issue in Phase [N]:
Expected: [what the plan says]
Found: [actual situation]
Why this matters: [explanation]
How should I proceed?
```
## Verification Approach
After implementing a phase:
- Run the success criteria checks (usually `make check test` covers everything)
- Fix any issues before proceeding
- Update your progress in both the plan and your todos
- Check off completed items in the plan file itself using Edit
- **Check context usage** - monitor token consumption
Don't let verification interrupt your flow - batch it at natural stopping points.
## Context Management During Implementation
**Monitor context proactively throughout implementation**:
**After Each Phase**:
```
✅ Phase {N} complete!
## 📊 Context Status
Current usage: {X}% ({Y}K/{Z}K tokens)
{If >60%}:
⚠️ **Context Alert**: We're at {X}% usage.
**Recommendation**: Create a handoff before continuing to Phase {N+1}.
**Why?** Implementation accumulates context:
- File reads
- Code changes
- Test outputs
- Error messages
- Context clears ensure continued high performance
**Options**:
1. ✅ Create handoff and clear context (recommended)
- Use `/create-handoff` to generate properly formatted handoff
- Format: `thoughts/shared/handoffs/{ticket}/YYYY-MM-DD_HH-MM-SS_description.md`
- Includes timestamp for lexical sorting by recency
2. Continue to next phase (if close to completion)
**To resume**: Start fresh session, run `/implement-plan {plan-path}`
(The plan file tracks progress with checkboxes - you'll resume automatically)
{If <60%}:
✅ Context healthy. Ready for Phase {N+1}.
```
**When to Warn**:
- After any phase if context >60%
- If context >70%, strongly recommend handoff
- If context >80%, STOP and require handoff
- If user is spinning on errors (3+ attempts), suggest context clear
**Educate About Phase-Based Context**:
- Explain that implementation is designed to work in chunks
- Each phase completion is a natural handoff point
- Plan file preserves progress across sessions
- Fresh context = fresh perspective on next phase
**Creating a Handoff**:
When recommending a handoff, guide the user:
1. Offer to create the handoff using `/create-handoff`
2. Or create a manual handoff following the timestamp convention
3. Handoff filename format: `thoughts/shared/handoffs/{ticket}/YYYY-MM-DD_HH-MM-SS_description.md`
4. Include: completed phases, next steps, key learnings, file references
5. Update plan file with checkboxes for completed work
## If You Get Stuck
When something isn't working as expected:
- First, make sure you've read and understood all the relevant code
- Consider if the codebase has evolved since the plan was written
- Present the mismatch clearly and ask for guidance
Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.
## Resuming Work
If the plan has existing checkmarks:
- Trust that completed work is done
- Pick up from the first unchecked item
- Verify previous work only if something seems off
Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and
maintain forward momentum.

489
commands/linear.md Normal file
View File

@@ -0,0 +1,489 @@
---
description: Manage Linear tickets with workflow automation
category: project-task-management
tools: Bash(linearis *), Read, Write, Edit, Grep
model: inherit
version: 1.0.0
---
# Linear - Ticket Management
You are tasked with managing Linear tickets, including creating tickets from thoughts documents,
updating existing tickets, and following a structured workflow using the Linearis CLI.
## Prerequisites Check
First, verify that Linearis CLI is installed and configured:
```bash
if ! command -v linearis &> /dev/null; then
echo "❌ Linearis CLI not found"
echo ""
echo "Install with:"
echo " npm install -g --install-links ryanrozich/linearis#feat/cycles-cli"
echo ""
echo "Configure with:"
echo " export LINEAR_API_TOKEN=your_token"
echo " # or create ~/.linear_api_token file"
exit 1
fi
```
## Configuration
Read team configuration from `.claude/config.json`:
```bash
CONFIG_FILE=".claude/config.json"
# Read team key (e.g., "ENG", "PROJ")
TEAM_KEY=$(jq -r '.catalyst.linear.teamKey // "PROJ"' "$CONFIG_FILE")
# Read default team name (optional)
DEFAULT_TEAM=$(jq -r '.catalyst.linear.defaultTeam // null' "$CONFIG_FILE")
# Read thoughts repo URL
THOUGHTS_URL=$(jq -r '.catalyst.linear.thoughtsRepoUrl // "https://github.com/org/thoughts/blob/main"' "$CONFIG_FILE")
```
**Configuration in `.claude/config.json`**:
```json
{
"linear": {
"teamKey": "ENG",
"defaultTeam": "Backend",
"thoughtsRepoUrl": "https://github.com/coalesce-labs/thoughts/blob/main"
}
}
```
## Initial Response
If tools are available, respond based on the user's request:
### For general requests:
```
I can help you with Linear tickets. What would you like to do?
1. Create a new ticket from a thoughts document
2. Add a comment to a ticket (I'll use our conversation context)
3. Search for tickets
4. Update ticket status or details
5. Move ticket through workflow
```
Then wait for the user's input.
---
## Workflow & Status Progression
This workflow ensures alignment through planning before implementation:
### Workflow Statuses
1. **Backlog** → New ideas and feature requests
2. **Triage** → Initial review and prioritization
3. **Spec Needed** → Needs problem statement and solution outline
4. **Research Needed** → Requires investigation
5. **Research in Progress** → Active research underway
6. **Ready for Plan** → Research complete, needs implementation plan
7. **Plan in Progress** → Writing implementation plan
8. **Plan in Review** → Plan under discussion
9. **Ready for Dev** → Plan approved, ready to implement
10. **In Dev** → Active development
11. **In Review** → PR submitted
12. **Done** → Completed
**Note**: These statuses must be configured in your Linear workspace settings. The Linearis CLI will
read and use whatever states exist in your workspace.
### Key Principle
**Review and alignment happen at the plan stage (not PR stage)** to move faster and avoid rework.
### Workflow Commands Integration
These commands automatically update ticket status:
- `/catalyst-dev:create_plan` → Moves ticket to "Plan in Progress"
- Plan completed → Moves to "Plan in Review"
- `/catalyst-dev:implement_plan` → Moves to "In Dev"
- `/catalyst-dev:create_pr` → Moves to "In Review"
- `/catalyst-dev:merge_pr` → Moves to "Done"
---
## Important Conventions
### URL Mapping for Thoughts Documents
When referencing thoughts documents, always provide GitHub links:
- `thoughts/shared/...` → `{thoughtsRepoUrl}/repos/{project}/shared/...`
- `thoughts/{user}/...` → `{thoughtsRepoUrl}/repos/{project}/{user}/...`
- `thoughts/global/...` → `{thoughtsRepoUrl}/global/...`
### Default Values
- **Status**: Create new tickets in "Backlog" status
- **Priority**: Default to Medium (3) for most tasks
- Urgent (1): Critical blockers, security issues
- High (2): Important features with deadlines, major bugs
- Medium (3): Standard implementation tasks (default)
- Low (4): Nice-to-haves, minor improvements
---
## Action-Specific Instructions
### 1. Creating Tickets from Thoughts
#### Steps to follow:
1. **Locate and read the thoughts document:**
- If given a path, read the document directly
- If given a topic/keyword, search thoughts/ directory using Grep
- If multiple matches found, show list and ask user to select
- Create a TodoWrite list to track: Read document → Analyze → Draft → Create
2. **Analyze the document content:**
- Identify the core problem or feature being discussed
- Extract key implementation details or technical decisions
- Note any specific code files or areas mentioned
- Look for action items or next steps
- Identify what stage the idea is at (early ideation vs ready to implement)
3. **Check for related context (if mentioned in doc):**
- If the document references specific code files, read relevant sections
- If it mentions other thoughts documents, quickly check them
- Look for any existing Linear tickets mentioned
4. **Draft the ticket summary:** Present a draft to the user:
```
## Draft Linear Ticket
**Title**: [Clear, action-oriented title]
**Description**:
[2-3 sentence summary of the problem/goal]
## Key Details
- [Bullet points of important details from thoughts]
- [Technical decisions or constraints]
- [Any specific requirements]
## Implementation Notes (if applicable)
[Any specific technical approach or steps outlined]
## References
- Source: `thoughts/[path]` ([View on GitHub](converted URL))
- Related code: [any file:line references]
---
Based on the document, this seems to be at the stage of: [ideation/planning/ready to implement]
```
5. **Interactive refinement:** Ask the user:
- Does this summary capture the ticket accurately?
- What priority? (Default: Medium/3)
- Any additional context to add?
- Should we include more/less implementation detail?
- Do you want to assign it to yourself?
Note: Ticket will be created in "Backlog" status by default.
6. **Create the Linear ticket using Linearis CLI:**
```bash
# Create issue with linearis
linearis issues create \
--team "$TEAM_KEY" \
--title "[refined title]" \
--description "[final description in markdown]" \
--priority [1-4] \
--status "Backlog"
# Capture the created issue ID from output
ISSUE_ID=$(linearis issues create ... | jq -r '.id')
```
**Note**: Linearis creates issues in the team's default backlog state. To set specific status or
assignee, create first then update:
```bash
# Assign to self
linearis issues update "$ISSUE_ID" --assignee "@me"
```
7. **Post-creation actions:**
- Show the created ticket URL
- Ask if user wants to:
- Add a comment with additional implementation details
- Update the original thoughts document with the ticket reference
- If yes to updating thoughts doc:
```
Add at the top of the document:
---
linear_ticket: [TEAM-123]
created: [date]
---
```
### 2. Adding Comments to Existing Tickets
When user wants to add a comment to a ticket:
1. **Determine which ticket:**
- Use context from the current conversation to identify the relevant ticket
- If uncertain, use `linearis issues read TEAM-123` to show ticket details and confirm
2. **Format comments for clarity:**
- Keep concise (~10 lines) unless more detail needed
- Focus on key insights or most useful information
- Include relevant file references with backticks and GitHub links
3. **File reference formatting:**
- Wrap paths in backticks: `thoughts/user/example.md`
- Add GitHub link after: `([View](url))`
- Do this for both thoughts/ and code files
4. **Comment structure example:**
```markdown
Implemented retry logic in webhook handler to address rate limit issues.
Key insight: The 429 responses were clustered during batch operations, so exponential backoff
alone wasn't sufficient - added request queuing.
Files updated:
- `src/webhooks/handler.ts` ([GitHub](link))
- `thoughts/shared/rate_limit_analysis.md` ([GitHub](link))
```
5. **Add comment with Linearis:**
```bash
linearis comments create TEAM-123 --body "Your comment text here"
```
### 3. Moving Tickets Through Workflow
When moving tickets to a new status:
1. **Get current status:**
```bash
linearis issues read TEAM-123 | jq -r '.state.name'
```
2. **Suggest next status based on workflow:**
```
Backlog → Triage (for initial review)
Triage → Spec Needed (needs more detail) OR Research Needed (needs investigation)
Spec Needed → Research Needed (once problem outlined)
Research Needed → Research in Progress (starting research)
Research in Progress → Ready for Plan (research complete)
Ready for Plan → Plan in Progress (starting plan with /catalyst-dev:create_plan)
Plan in Progress → Plan in Review (plan complete)
Plan in Review → Ready for Dev (plan approved)
Ready for Dev → In Dev (starting work with /catalyst-dev:implement_plan)
In Dev → In Review (PR created)
In Review → Done (PR merged)
```
3. **Automatic status updates:** When certain commands are run, automatically update ticket status:
- `/catalyst-dev:create_plan` with ticket → Move to "Plan in Progress"
- Plan synced and linked → Move to "Plan in Review"
- `/catalyst-dev:implement_plan` with ticket → Move to "In Dev"
- `/catalyst-dev:create_pr` with ticket → Move to "In Review"
- `/catalyst-dev:merge_pr` with ticket → Move to "Done"
4. **Manual status updates:**
```bash
linearis issues update TEAM-123 --state "In Progress"
```
5. **Add comment explaining the transition:**
```bash
linearis comments create TEAM-123 --body "Moving to In Progress: Starting implementation"
```
### 4. Searching for Tickets
When user wants to find tickets:
1. **Gather search criteria:**
- Query text
- Status filters
- Assignee filters
2. **Execute search:**
```bash
# List all issues (linearis issues list only supports --limit, not --team)
linearis issues list --limit 100
# Filter by team using jq
linearis issues list --limit 100 | jq '.[] | select(.team.key == "TEAM")'
# Filter by status using jq
linearis issues list --limit 100 | jq '.[] | select(.state.name == "In Progress")'
# Filter by assignee using jq
linearis issues list --limit 100 | jq '.[] | select(.assignee.email == "user@example.com")'
# Search by text (filter JSON output with jq)
linearis issues list --limit 100 | \
jq '.[] | select(.title | contains("search term"))'
```
3. **Present results:**
- Show ticket ID, title, status, assignee
- Include direct links to Linear
- Parse JSON output for display
---
## Integration with Other Commands
### Automatic Ticket Updates
When these commands are run, check if there's a related Linear ticket and update it:
**During `/catalyst-dev:create_plan`:**
1. If ticket mentioned, move to "Plan in Progress"
2. When plan complete, add comment with plan link
3. Move to "Plan in Review"
**During `/catalyst-dev:implement_plan`:**
1. If ticket in plan metadata, move to "In Dev"
2. Add comment: "Started implementation from plan: [link]"
**During `/catalyst-dev:create_pr`:**
1. If ticket mentioned in PR or plan, move to "In Review"
2. Add comment with PR link
**During `/catalyst-dev:merge_pr`:**
1. Move ticket to "Done"
2. Add comment with merge details
---
## Example Workflows
### Workflow 1: Thought → Ticket → Plan → Implement
```bash
# 1. Research and document
/catalyst-dev:research_codebase "authentication patterns"
# Saves to thoughts/shared/research/auth-patterns.md
# 2. Create ticket from research
/catalyst-dev:linear create thoughts/shared/research/auth-patterns.md
# Creates ticket in Backlog
# 3. Create plan
/catalyst-dev:create_plan
# Reads research, creates plan
# Ticket moves to "Plan in Progress" → "Plan in Review"
# 4. Implement
/catalyst-dev:implement_plan thoughts/shared/plans/2025-01-08-auth-feature.md
# Ticket moves to "In Dev"
# 5. Create PR
/catalyst-dev:create_pr
# Ticket moves to "In Review"
# 6. Merge PR
/catalyst-dev:merge_pr
# Ticket moves to "Done"
```
### Workflow 2: Quick Ticket Updates
```bash
# Add progress comment
linearis comments create PROJ-123 --body "Completed phase 1, moving to phase 2"
# Move ticket forward
linearis issues update PROJ-123 --state "In Dev"
# Search for related tickets
linearis issues list --team PROJ | jq '.[] | select(.title | contains("authentication"))'
```
---
## Linearis CLI Reference
### Common Commands
```bash
# List issues (only --limit supported, use jq for filtering)
linearis issues list --limit 50
# Filter by status using jq
linearis issues list --limit 100 | jq '.[] | select(.state.name == "In Progress")'
# Read specific issue
linearis issues read TICKET-123
# Create issue
linearis issues create "Title" --description "Description" --state "Todo"
# Update issue state
linearis issues update TICKET-123 --state "In Progress"
# Update assignee
linearis issues update TICKET-123 --assignee <user-id>
# Add comment
linearis comments create TICKET-123 --body "Comment text"
# List cycles
linearis cycles list --team TEAM [--active]
# Read cycle
linearis cycles read "Sprint 2025-10" --team TEAM
```
### JSON Output Parsing
Linearis returns JSON, parse with jq:
```bash
# Get ticket status
linearis issues read TEAM-123 | jq -r '.state.name'
# Get ticket title
linearis issues read TEAM-123 | jq -r '.title'
# Get assignee
linearis issues read TEAM-123 | jq -r '.assignee.name'
# Filter list by keyword
linearis issues list --team TEAM | jq '.[] | select(.title | contains("bug"))'
```
---
## Notes
- **Configuration**: Use `.claude/config.json` for team settings
- **Status mapping**: Use status names that exist in your Linear workspace
- **Automation**: Workflow commands auto-update tickets when ticket IDs are referenced
- **CLI required**: Linearis CLI must be installed and configured with LINEAR_API_TOKEN
This command integrates seamlessly with the create_plan → implement_plan → validate_plan workflow
while keeping Linear tickets in sync!

646
commands/merge_pr.md Normal file
View File

@@ -0,0 +1,646 @@
---
description: Safely merge PR with verification and Linear integration
category: version-control-git
tools: Bash(linearis *), Bash(git *), Bash(gh *), Read
model: inherit
version: 1.0.0
---
# Merge Pull Request
Safely merges a PR after comprehensive verification, with Linear integration and automated cleanup.
## Configuration
Read team configuration from `.claude/config.json`:
```bash
CONFIG_FILE=".claude/config.json"
TEAM_KEY=$(jq -r '.catalyst.linear.teamKey // "PROJ"' "$CONFIG_FILE")
TEST_CMD=$(jq -r '.catalyst.pr.testCommand // "make test"' "$CONFIG_FILE")
```
## Process:
### 1. Identify PR to merge
**If argument provided:**
- Use that PR number: `/merge_pr 123`
**If no argument:**
```bash
# Try current branch
gh pr view --json number,url,title,state,mergeable 2>/dev/null
```
If no PR on current branch:
```bash
gh pr list --limit 10 --json number,title,headRefName,state
```
Ask: "Which PR would you like to merge? (enter number)"
### 2. Get PR details
```bash
gh pr view $pr_number --json \
number,url,title,state,mergeable,mergeStateStatus,\
baseRefName,headRefName,reviewDecision
```
**Extract:**
- PR number, URL, title
- Mergeable status
- Base branch (usually main)
- Head branch (feature branch)
- Review decision (APPROVED, REVIEW_REQUIRED, etc.)
### 3. Verify PR is open and mergeable
```bash
state=$(gh pr view $pr_number --json state -q .state)
mergeable=$(gh pr view $pr_number --json mergeable -q .mergeable)
```
**If PR not OPEN:**
```
❌ PR #$pr_number is $state
Only open PRs can be merged.
```
**If not mergeable (CONFLICTING):**
```
❌ PR has merge conflicts
Resolve conflicts first:
gh pr checkout $pr_number
git fetch origin $base_branch
git merge origin/$base_branch
# ... resolve conflicts ...
git push
```
Exit with error.
### 4. Check if head branch is up-to-date with base
```bash
# Checkout PR branch
gh pr checkout $pr_number
# Fetch latest base
base_branch=$(gh pr view $pr_number --json baseRefName -q .baseRefName)
git fetch origin $base_branch
# Check if behind
if git log HEAD..origin/$base_branch --oneline | grep -q .; then
echo "Branch is behind $base_branch"
fi
```
**If behind:**
```bash
# Auto-rebase
git rebase origin/$base_branch
# Check for conflicts
if [ $? -ne 0 ]; then
echo "❌ Rebase conflicts"
git rebase --abort
exit 1
fi
# Push rebased branch
git push --force-with-lease
```
**If conflicts during rebase:**
```
❌ Rebase conflicts detected
Conflicting files:
$(git diff --name-only --diff-filter=U)
Resolve manually:
1. Fix conflicts in listed files
2. git add <resolved-files>
3. git rebase --continue
4. git push --force-with-lease
5. Run /catalyst-dev:merge_pr again
```
Exit with error.
### 5. Run local tests
**Read test command from config:**
```bash
test_cmd=$(jq -r '.catalyst.pr.testCommand // "make test"' .claude/config.json)
```
**Execute tests:**
```bash
echo "Running tests: $test_cmd"
if ! $test_cmd; then
echo "❌ Tests failed"
exit 1
fi
```
**If tests fail:**
```
❌ Local tests failed
Fix failing tests before merge:
$test_cmd
Or skip tests (not recommended):
/catalyst-dev:merge_pr $pr_number --skip-tests
```
Exit with error (unless `--skip-tests` flag provided).
### 6. Check CI/CD status
```bash
gh pr checks $pr_number
```
**Parse output for failures:**
- If all checks pass: continue
- If required checks fail: prompt user
- If optional checks fail: warn but allow
**If required checks failing:**
```
⚠️ Some required CI checks are failing
Failed checks:
- build (required)
- lint (required)
Passed checks:
- test ✅
- security ✅
Continue merge anyway? [y/N]:
```
If user says no: exit. If user says yes: continue (user override).
### 7. Check approval status
```bash
review_decision=$(gh pr view $pr_number --json reviewDecision -q .reviewDecision)
```
**Review decisions:**
- `APPROVED` - proceed
- `CHANGES_REQUESTED` - prompt user
- `REVIEW_REQUIRED` - prompt user
- `null` / empty - no reviews, prompt user
**If not approved:**
```
⚠️ PR has not been approved
Review status: $review_decision
Continue merge anyway? [y/N]:
```
If user says no: exit. If user says yes: continue (user override).
**Skip these prompts if** `requireApproval: false` in config.
### 8. Extract ticket reference
```bash
branch=$(gh pr view $pr_number --json headRefName -q .headRefName)
title=$(gh pr view $pr_number --json title -q .title)
# From branch using configured team key
if [[ "$branch" =~ ($TEAM_KEY-[0-9]+) ]]; then
ticket="${BASH_REMATCH[1]}"
fi
# From title if not in branch
if [[ -z "$ticket" ]] && [[ "$title" =~ ($TEAM_KEY-[0-9]+) ]]; then
ticket="${BASH_REMATCH[1]}"
fi
```
### 9. Show merge summary
```
About to merge:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PR: #$pr_number - $title
From: $head_branch
To: $base_branch
Commits: $commit_count
Files: $file_count changed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reviews: $review_status
CI: $ci_status
Tests: ✅ Passed locally
Ticket: $ticket (will move to Done)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Merge strategy: Squash and merge
Proceed? [Y/n]:
```
### 10. Execute squash merge
```bash
gh pr merge $pr_number --squash --delete-branch
```
**Always:**
- Squash merge (combines all commits into one)
- Delete remote branch automatically
**Capture merge commit SHA:**
```bash
merge_sha=$(git rev-parse HEAD)
```
### 11. Update Linear ticket
If ticket found and not using `--no-update`:
```bash
# Verify linearis is available
if ! command -v linearis &> /dev/null; then
echo "⚠️ Linearis CLI not found - skipping Linear ticket update"
echo "Install: npm install -g --install-links ryanrozich/linearis#feat/cycles-cli"
else
# Move to "Done"
linearis issues update "$ticket" --state "Done"
# Add merge comment
linearis comments create "$ticket" \
--body "✅ PR merged!\n\n**PR**: #${prNumber} - ${prTitle}\n**Merge commit**: ${mergeSha}\n**Merged into**: ${baseBranch}\n\nView PR: ${prUrl}"
fi
```
### 12. Delete local branch and update base
```bash
# Switch to base branch
git checkout $base_branch
# Pull latest (includes merge commit)
git pull origin $base_branch
# Delete local feature branch
git branch -d $head_branch
# Confirm deletion
echo "✅ Deleted local branch: $head_branch"
```
**Always delete local branch** - no prompt (remote already deleted).
### 13. Extract post-merge tasks
**Read PR description:**
```bash
desc_file="thoughts/shared/prs/${pr_number}_description.md"
if [ -f "$desc_file" ]; then
# Extract "Post-Merge Tasks" section
tasks=$(sed -n '/## Post-Merge Tasks/,/^##/p' "$desc_file" | grep -E '^\- \[')
fi
```
**If tasks exist:**
```
📋 Post-merge tasks from PR description:
- [ ] Update documentation
- [ ] Monitor error rates in production
- [ ] Notify stakeholders
Save these tasks? [Y/n]:
```
If yes:
```bash
# Save to thoughts
cat > "thoughts/shared/post_merge_tasks/${ticket}_tasks.md" <<EOF
# Post-Merge Tasks: $ticket
Merged: $(date)
PR: #$pr_number
$tasks
EOF
humanlayer thoughts sync
```
### 14. Report success summary
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ PR #$pr_number merged successfully!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Merge details:
Strategy: Squash and merge
Commit: $merge_sha
Base branch: $base_branch (updated)
Merged by: @$user
Cleanup:
Remote branch: $head_branch (deleted)
Local branch: $head_branch (deleted)
Linear:
Ticket: $ticket → Done ✅
Comment: Added with merge details
Post-merge tasks: $task_count saved to thoughts/
Next steps:
- Monitor deployment
- Check CI/CD pipeline
- Verify in production
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
## Flags
**`--skip-tests`** - Skip local test execution
```bash
/catalyst-dev:merge_pr 123 --skip-tests
```
**`--no-update`** - Don't update Linear ticket
```bash
/catalyst-dev:merge_pr 123 --no-update
```
**`--keep-branch`** - Don't delete local branch
```bash
/catalyst-dev:merge_pr 123 --keep-branch
```
**Combined:**
```bash
/catalyst-dev:merge_pr 123 --skip-tests --no-update
```
## Error Handling
**Rebase conflicts:**
```
❌ Rebase conflicts detected
Conflicting files:
- src/app.ts
- tests/app.test.ts
Resolve manually:
gh pr checkout $pr_number
git fetch origin $base_branch
git rebase origin/$base_branch
# Fix conflicts
git add <files>
git rebase --continue
git push --force-with-lease
/catalyst-dev:merge_pr $pr_number
```
**Tests failing:**
```
❌ Tests failed (exit code 1)
Failed tests:
- validation.test.ts:45 - Expected true but got false
- auth.test.ts:12 - Timeout exceeded
Fix tests or skip (not recommended):
/catalyst-dev:merge_pr $pr_number --skip-tests
```
**CI checks failing:**
```
⚠️ Required CI checks failing
Failed:
- build: Compilation error in src/types.ts
- security: Dependency vulnerability found
You can:
1. Fix issues and try again
2. Override and merge anyway (not recommended)
Override? [y/N]:
```
**Linearis CLI not found:**
```
⚠️ Linearis CLI not found
PR merged successfully, but Linear ticket not updated.
Install Linearis:
npm install -g --install-links ryanrozich/linearis#feat/cycles-cli
Configure:
export LINEAR_API_TOKEN=your_token
Then update ticket manually:
linearis issues update $ticket --state "Done"
```
**Linear API error:**
```
⚠️ Could not update Linear ticket $ticket
Error: Ticket not found or API unavailable
PR merged successfully, but ticket status not updated.
Update manually in Linear.
```
**Branch deletion error:**
```
⚠️ Could not delete local branch $head_branch
Error: Branch has unpushed commits
This won't affect the merge (already complete).
Delete manually: git branch -D $head_branch
```
## Configuration
Uses `.claude/config.json`:
```json
{
"catalyst": {
"project": {
"ticketPrefix": "RCW"
},
"linear": {
"teamKey": "RCW",
"doneStatusName": "Done"
},
"pr": {
"defaultMergeStrategy": "squash",
"deleteRemoteBranch": true,
"deleteLocalBranch": true,
"updateLinearOnMerge": true,
"requireApproval": false,
"requireCI": false,
"testCommand": "make test"
}
}
}
```
## Examples
**Happy path (all checks pass):**
```bash
/catalyst-dev:merge_pr 123
Running tests: make test
✅ All tests passed
✅ CI checks passed
✅ PR approved
About to merge PR #123...
[shows summary]
Proceed? Y
✅ Merged!
✅ Linear ticket RCW-13 → Done
✅ Branches deleted
```
**With failing CI (user override):**
```bash
/catalyst-dev:merge_pr 124
⚠️ Some CI checks failing
Continue anyway? y
✅ Merged (with overrides)
```
**Skip tests:**
```bash
/catalyst-dev:merge_pr 125 --skip-tests
⚠️ Skipping tests (not recommended)
✅ Merged!
```
**Linearis not installed:**
```bash
/catalyst-dev:merge_pr 126
✅ PR merged successfully!
⚠️ Linearis CLI not found - Linear ticket not updated
Install Linearis to enable automatic ticket updates.
```
## Safety Features
**Fail fast on:**
- Merge conflicts (can't auto-resolve)
- Test failures (unless --skip-tests)
- Rebase conflicts
- PR not in mergeable state
**Prompt for confirmation on:**
- Missing required approvals
- Failing CI checks
- Any exceptional circumstance
**Always automated:**
- Rebase if behind (no conflicts)
- Squash merge
- Delete remote branch
- Delete local branch
- Update Linear to Done (if Linearis available)
- Pull latest base branch
**Graceful degradation:**
- If Linearis not installed, warn but continue
- Merge succeeds regardless of Linear integration
## Post-Merge Workflow
```
PR merged
↓
Linear ticket → Done (if Linearis available)
↓
Branches deleted
↓
Base branch updated locally
↓
Post-merge tasks extracted
↓
Monitor deployment
```
## Remember:
- **Always squash merge** - clean history
- **Always delete branches** - no orphan branches
- **Always run tests** - unless explicitly skipped
- **Auto-rebase** - keep up-to-date with base
- **Fail fast** - stop on conflicts or test failures
- **Update Linear** - move ticket to Done automatically (if Linearis available)
- **Extract tasks** - save post-merge checklist
- **Clear summary** - show what happened
- **Only prompt for exceptions** - approvals missing, CI failing
- **Graceful degradation** - Work without Linearis if needed

715
commands/research_codebase.md Normal file
View File

@@ -0,0 +1,715 @@
---
description: Conduct comprehensive codebase research using parallel sub-agents
category: workflow
tools: Read, Write, Grep, Glob, Task, TodoWrite, Bash
model: inherit
version: 1.0.0
---
# Research Codebase
You are tasked with conducting comprehensive research across the codebase to answer user questions
by spawning parallel sub-agents and synthesizing their findings.
## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
- DO NOT suggest improvements or changes unless the user explicitly asks for them
- DO NOT perform root cause analysis unless the user explicitly asks for them
- DO NOT propose future enhancements unless the user explicitly asks for them
- DO NOT critique the implementation or identify problems
- DO NOT recommend refactoring, optimization, or architectural changes
- ONLY describe what exists, where it exists, how it works, and how components interact
- You are creating a technical map/documentation of the existing system
## Prerequisites
Before executing, verify all required tools and systems:
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Validate plugin scripts
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Initial Setup
When this command is invoked, respond with:
```
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
```
Then wait for the user's research query.
## Steps to Follow After Receiving the Research Query
### Step 1: Read Any Directly Mentioned Files First
- If the user mentions specific files (tickets, docs, JSON), read them FULLY first
- **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
- **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
- This ensures you have full context before decomposing the research
### Step 2: Analyze and Decompose the Research Question
- Break down the user's query into composable research areas
- Take time to think deeply about the underlying patterns, connections, and architectural
implications the user might be seeking
- Identify specific components, patterns, or concepts to investigate
- Create a research plan using TodoWrite to track all subtasks
- Consider which directories, files, or architectural patterns are relevant
### Step 3: Spawn Parallel Sub-Agent Tasks for Comprehensive Research
Create multiple Task agents to research different aspects concurrently.
We have specialized agents that know how to do specific research tasks:
**For codebase research:**
- Use the **codebase-locator** agent to find WHERE files and components live
- Use the **codebase-analyzer** agent to understand HOW specific code works (without critiquing it)
- Use the **codebase-pattern-finder** agent to find examples of existing patterns (without
evaluating them)
**IMPORTANT**: All agents are documentarians, not critics. They will describe what exists without
suggesting improvements or identifying issues.
**For thoughts directory (if using thoughts system):**
- Use the **thoughts-locator** agent to discover what documents exist about the topic
- Use the **thoughts-analyzer** agent to extract key insights from specific documents (only the most
relevant ones)
**For external research (only if user explicitly asks):**
- Use the **external-research** agent for external documentation and resources
- IF you use external research agents, instruct them to return LINKS with their findings, and
INCLUDE those links in your final report
**For Linear tickets (if relevant):**
- Use the **linear-ticket-reader** agent to get full details of a specific ticket (if Linear MCP
available)
- Use the **linear-searcher** agent to find related tickets or historical context
The key is to use these agents intelligently:
- Start with locator agents to find what exists
- Then use analyzer agents on the most promising findings to document how they work
- Run multiple agents in parallel when they're searching for different things
- Each agent knows its job - just tell it what you're looking for
- Don't write detailed prompts about HOW to search - the agents already know
- Remind agents they are documenting, not evaluating or improving
**Example of spawning parallel research tasks:**
```
I'm going to spawn 3 parallel research tasks:
Task 1 - Find WHERE components live:
"Use codebase-locator to find all files related to [topic]. Focus on [specific directories if known]."
Task 2 - Understand HOW it works:
"Use codebase-analyzer to analyze [specific component] and document how it currently works. Include data flow and key integration points."
Task 3 - Find existing patterns:
"Use codebase-pattern-finder to find similar implementations of [pattern] in the codebase. Show concrete examples."
```
### Step 4: Wait for All Sub-Agents to Complete and Synthesize Findings
- **IMPORTANT**: Wait for ALL sub-agent tasks to complete before proceeding
- Compile all sub-agent results (both codebase and thoughts findings if applicable)
- Prioritize live codebase findings as primary source of truth
- Use thoughts/ findings as supplementary historical context (if thoughts system is used)
- Connect findings across different components
- Document specific file paths and line numbers (format: `file.ext:line`)
- Explain how components interact with each other
- Include temporal context where relevant (e.g., "This was added in commit abc123")
- Mark all research tasks as complete in TodoWrite
### Step 5: Gather Metadata for the Research Document
Collect metadata for the research document:
**If using thoughts system with metadata script:**
- Run `hack/spec_metadata.sh` or equivalent to generate metadata
- Metadata includes: date, researcher, git commit, branch, repository
**If using simple approach:**
- Get current date/time
- Get git commit hash: `git rev-parse HEAD`
- Get current branch: `git branch --show-current`
- Get repository name from `.git/config` or working directory
**Document Storage:**
All research documents are stored in the **thoughts system** for persistence:
**Required location:** `thoughts/shared/research/YYYY-MM-DD-{ticket}-{description}.md`
**Why thoughts/shared/**:
- ✅ Persisted across sessions (git-backed via HumanLayer)
- ✅ Shared across worktrees
- ✅ Synced via `humanlayer thoughts sync`
- ✅ Team collaboration ready
**Filename format:**
- With ticket: `thoughts/shared/research/YYYY-MM-DD-PROJ-XXXX-description.md`
- Without ticket: `thoughts/shared/research/YYYY-MM-DD-description.md`
Replace `PROJ` with your ticket prefix from `.claude/config.json`.
**Examples:**
- `thoughts/shared/research/2025-01-08-PROJ-1478-parent-child-tracking.md`
- `thoughts/shared/research/2025-01-08-authentication-flow.md` (no ticket)
### Step 6: Generate Research Document
Create a structured research document with the following format:
```markdown
---
date: YYYY-MM-DDTHH:MM:SS+TZ
researcher: { your-name }
git_commit: { commit-hash }
branch: { branch-name }
repository: { repo-name }
topic: "{User's Research Question}"
tags: [research, codebase, { component-names }]
status: complete
last_updated: YYYY-MM-DD
last_updated_by: { your-name }
---
# Research: {User's Research Question}
**Date**: {date/time with timezone} **Researcher**: {your-name} **Git Commit**: {commit-hash}
**Branch**: {branch-name} **Repository**: {repo-name}
## Research Question
{Original user query, verbatim}
## Summary
{High-level documentation of what you found. 2-3 paragraphs explaining the current state of the
system in this area. Focus on WHAT EXISTS, not what should exist.}
## Detailed Findings
### {Component/Area 1}
**What exists**: {Describe the current implementation}
- File location: `path/to/file.ext:123`
- Current behavior: {what it does}
- Key functions/classes: {list with file:line references}
**Connections**: {How this component integrates with others}
- Calls: `other-component.ts:45` - {description}
- Used by: `consumer.ts:67` - {description}
**Implementation details**: {Technical specifics without evaluation}
### {Component/Area 2}
{Same structure as above}
### {Component/Area N}
{Continue for all major findings}
## Code References
Quick reference of key files and their roles:
- `path/to/file1.ext:123-145` - {What this code does}
- `path/to/file2.ext:67` - {What this code does}
- `path/to/file3.ext:200-250` - {What this code does}
## Architecture Documentation
{Document the current architectural patterns, conventions, and design decisions observed in the
code. This is descriptive, not prescriptive.}
### Current Patterns
- **Pattern 1**: {How it's implemented in the codebase}
- **Pattern 2**: {How it's implemented in the codebase}
### Data Flow
{Document how data moves through the system in this area}
```
Component A → Component B → Component C {Describe what happens at each step}
```
### Key Integrations
{Document how different parts of the system connect}
## Historical Context (from thoughts/)
{ONLY if using thoughts system}
{Include insights from thoughts/ documents that provide context}
- `thoughts/shared/research/previous-doc.md` - {Key decision or insight}
- `thoughts/shared/plans/plan-123.md` - {Related implementation detail}
## Related Research
{Links to other research documents that touch on related topics}
- `research/YYYY-MM-DD-related-topic.md` - {How it relates}
## Open Questions
{Areas that would benefit from further investigation - NOT problems to fix, just areas where understanding could be deepened}
- {Question 1}
- {Question 2}
```
### Step 7: Add GitHub Permalinks (If Applicable)
**If you're on the main/master branch OR if the commit is pushed:**
Generate GitHub permalinks and replace file references:
```
https://github.com/{owner}/{repo}/blob/{commit-hash}/{file-path}#L{line}
```
For line ranges:
```
https://github.com/{owner}/{repo}/blob/{commit-hash}/{file-path}#L{start}-L{end}
```
**If working on a feature branch that's not pushed yet:**
- Keep local file references: `path/to/file.ext:line`
- Add note: "GitHub permalinks will be added once this branch is pushed"
### Step 8: Sync and Present Findings
**If using thoughts system:**
- Run `humanlayer thoughts sync` to sync the thoughts directory
- This updates symlinks, creates searchable index, and commits to thoughts repo
**If using simple approach:**
- Just save the file to your research directory
- Optionally commit to git
**Present to user:**
```markdown
✅ Research complete!
**Research document**: {file-path}
## Summary
{2-3 sentence summary of key findings}
## Key Files
{Top 3-5 most important file references}
## What I Found
{Brief overview - save details for the document}
---
## 📊 Context Status
Current usage: {X}% ({Y}K/{Z}K tokens)
{If >60%}: ⚠️ **Recommendation**: Context is getting full. For best results in the planning phase, I
recommend clearing context now.
**Options**:
1. ✅ Clear context now (recommended) - Close this session and start fresh for planning
2. Create handoff to pause work
3. Continue anyway (may impact performance)
**Why clear?** Fresh context ensures optimal AI performance for the planning phase, which will load
additional files and research.
{If <60%}: ✅ Context healthy. Ready to proceed to planning phase if needed.
---
Would you like me to:
1. Dive deeper into any specific area?
2. Create an implementation plan based on this research?
3. Explore related topics?
```
### Step 9: Handle Follow-Up Questions
If the user has follow-up questions:
1. **DO NOT create a new research document** - append to the same one
2. **Update frontmatter fields:**
- `last_updated`: {new date}
- `last_updated_by`: {your name}
- Add `last_updated_note`: "{Brief note about what was added}"
3. **Add new section to existing document:**
```markdown
---
## Follow-up Research: {Follow-up Question}
**Date**: {date} **Updated by**: {your-name}
### Additional Findings
{New research results using same structure as above}
```
4. **Spawn new sub-agents as needed** for the follow-up research
5. **Re-sync** (if using thoughts system)
## Important Notes
### Proactive Context Management
**Monitor Your Context Throughout Research**:
- Check token usage after spawning parallel agents
- After synthesis phase, check context again
- **If context >60%**: Warn user and recommend handoff
**Example Warning**:
```
⚠️ Context Usage Alert: Currently at 65% (130K/200K tokens)
Research is complete, but context is getting full. Before continuing to
planning phase, I recommend creating a handoff to preserve this work
and start fresh.
Would you like me to:
1. Create a handoff now (recommended)
2. Continue and clear context manually
3. Proceed anyway (not recommended - may impact planning quality)
**Why this matters**: The planning phase will load additional context.
Starting fresh ensures optimal AI performance.
```
**When to Warn**:
- After Step 7 (document generated) if context >60%
- After Step 9 (follow-up complete) if context >70%
- Anytime during research if context >80%
**Educate the User**:
- Explain WHY clearing context matters (performance, token efficiency)
- Explain WHEN to clear (between phases)
- Offer to create handoff yourself if `/create-handoff` command exists
### Parallel Execution
- ALWAYS use parallel Task agents for efficiency
- Don't wait for one agent to finish before spawning the next
- Spawn all research tasks at once, then wait for all to complete
### Research Philosophy
- Always perform fresh codebase research - never rely solely on existing docs
- The `thoughts/` directory (if used) provides historical context, not primary source
- Focus on concrete file paths and line numbers - make it easy to navigate
- Research documents should be self-contained and understandable months later
### Sub-Agent Prompts
- Be specific about what to search for
- Specify directories to focus on when known
- Make prompts focused on read-only documentation
- Remind agents they are documentarians, not critics
### Cross-Component Understanding
- Document how components interact, not just what they do individually
- Trace data flow across boundaries
- Note integration points and dependencies
### Temporal Context
- Include when things were added/changed if relevant
- Note deprecated patterns still in the codebase
- Don't judge - just document the timeline
### GitHub Links
- Use permalinks for permanent references
- Include line numbers for precision
- Link to specific commits, not branches (branches move)
### Main Agent Role
- Your role is synthesis, not deep file reading
- Let sub-agents do the detailed reading
- You orchestrate, compile, and connect their findings
- Focus on the big picture and cross-component connections
### Documentation Style
- Sub-agents document examples and usage patterns as they exist
- Main agent synthesizes into coherent narrative
- Both levels: documentarian, not evaluator
- Never recommend changes or improvements unless explicitly asked
### File Reading Rules
- ALWAYS read mentioned files fully before spawning sub-tasks
- Use Read tool WITHOUT limit/offset for complete files
- This is critical for proper decomposition
### Follow the Steps
- These numbered steps are not suggestions - follow them exactly
- Don't skip steps or reorder them
- Each step builds on the previous ones
### Thoughts Directory Handling
**If using thoughts system:**
- `thoughts/searchable/` is a special directory - paths found there should be documented as their
actual location
- Example: `thoughts/searchable/allison/notes.md` → document as `thoughts/allison/notes.md`
- Don't change directory names (keep `allison/`, don't change to `shared/`)
**If NOT using thoughts system:**
- Skip thoughts-related agents
- Skip thoughts sync commands
- Save research docs to `research/` directory in workspace root
### Frontmatter Consistency
- Always include complete frontmatter as shown in template
- Use ISO 8601 dates with timezone
- Keep tags consistent across research documents
- Update `last_updated` fields when appending follow-ups
## Linear Integration
If a Linear ticket is associated with the research, the command can automatically update the ticket
status.
### How It Works
**Ticket detection** (same as other commands):
1. User provides ticket ID explicitly: `/research_codebase PROJ-123`
2. Ticket mentioned in research query
3. Auto-detected from current context
**Status updates:**
- When research starts → Move ticket to **"Research"**
- When research document is saved → Add comment with link to research doc
### Implementation Pattern
**At research start** (Step 2 - after reading mentioned files):
```bash
# If ticket is detected or provided
if [[ -n "$ticketId" ]]; then
# Check if Linearis CLI is available
if command -v linearis &> /dev/null; then
# Update ticket state to "Research" (use --state NOT --status!)
linearis issues update "$ticketId" --state "Research"
# Add comment (use 'comments create' NOT 'issues comment'!)
linearis comments create "$ticketId" --body "Starting research: [user's research question]"
else
echo "⚠️ Linearis CLI not found - skipping Linear ticket update"
fi
fi
```
**After research document is saved** (Step 6 - after generating document):
```bash
# Attach research document to ticket
if [[ -n "$ticketId" ]] && [[ -n "$githubPermalink" ]]; then
# Check if Linearis CLI is available
if command -v linearis &> /dev/null; then
# Add completion comment with research doc link
linearis comments create "$ticketId" \
--body "Research complete! See findings: $githubPermalink"
else
echo "⚠️ Linearis CLI not found - skipping Linear ticket update"
fi
fi
```
### User Experience
**With ticket:**
```bash
/catalyst-dev:research_codebase PROJ-123
> "How does authentication work?"
```
**What happens:**
1. Command detects ticket PROJ-123
2. Moves ticket from Backlog → Research
3. Adds comment: "Starting research: How does authentication work?"
4. Conducts research with parallel agents
5. Saves document to thoughts/shared/research/
6. Attaches document to Linear ticket
7. Adds comment: "Research complete! See findings: [link]"
**Without ticket:**
```bash
/catalyst-dev:research_codebase
> "How does authentication work?"
```
**What happens:**
- Same research process, but no Linear updates
- User can manually attach research to ticket later
### Configuration
Uses the same Linear configuration as other commands from `.claude/config.json`:
- `linear.teamId`
- `linear.thoughtsRepoUrl` (for GitHub permalinks)
### Error Handling
**If Linear MCP not available:**
- Skip Linear integration silently
- Continue with research as normal
- Note in output: "Research complete (Linear not configured)"
**If ticket not found:**
- Show warning: "Ticket PROJ-123 not found in Linear"
- Ask user: "Continue research without Linear integration? (Y/n)"
**If status update fails:**
- Log error but continue research
- Include note in final output: "⚠️ Could not update Linear ticket status"
## Integration with Other Commands
This command integrates with the complete development workflow:
```
/research-codebase → research document (+ Linear: Research)
↓
/create-plan → implementation plan (+ Linear: Planning)
↓
/implement-plan → code changes (+ Linear: In Progress)
↓
/describe-pr → PR created (+ Linear: In Review)
```
**How it connects:**
- **research_codebase → Linear**: Moves ticket to "Research" status and attaches research document
- **research_codebase → create_plan**: Research findings provide foundation for planning. The
create_plan command can reference research documents in its "References" section.
- **Research before planning**: Always research the codebase first to understand what exists before
planning changes.
- **Shared agents**: Both research_codebase and create_plan use the same specialized agents
(codebase-locator, codebase-analyzer, codebase-pattern-finder).
- **Documentation persistence**: Research documents serve as permanent reference for future work.
## Example Workflow
```bash
# User starts research
/research-codebase
# You respond with initial prompt
# User asks: "How does authentication work in the API?"
# You execute:
# 1. Read any mentioned files fully
# 2. Decompose into research areas (auth middleware, token validation, session management)
# 3. Spawn parallel agents:
# - codebase-locator: Find auth-related files
# - codebase-analyzer: Understand auth middleware implementation
# - codebase-pattern-finder: Find auth usage patterns
# - thoughts-locator: Find previous auth discussions (if using thoughts)
# 4. Wait for all agents
# 5. Synthesize findings
# 6. Generate research document at research/2025-01-08-authentication-system.md
# 7. Present summary to user
# User follows up: "How does it integrate with the database?"
# You append to same document with new findings
```
### Track in Workflow Context
After saving the research document, add it to workflow context:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" add research "$DOC_PATH" "${TICKET_ID:-null}"
fi
```
## Adaptation Notes
This command is adapted from HumanLayer's research_codebase command. Key differences for
portability:
- **Thoughts system**: Made optional - can use simple `research/` directory
- **Metadata script**: Made optional - can generate metadata inline
- **Ticket prefixes**: Read from `.claude/config.json` or use PROJ- placeholder
- **Linear integration**: Made optional - only used if Linear MCP available
- **Web research**: Uses `external-research` agent instead of `web-search-researcher`
The core workflow and philosophy remain the same: parallel sub-agents, documentarian mindset, and
structured output.

289
commands/resume_handoff.md Normal file
View File

@@ -0,0 +1,289 @@
---
description: Resume work from a handoff document
category: workflow
tools: Read, Bash, TodoWrite
model: inherit
version: 1.0.0
---
# Resume work from a handoff document
## Prerequisites
Before executing, verify required tools are installed:
```bash
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-prerequisites.sh" || exit 1
fi
```
## Configuration Note
This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
prefix:
- Read from `.claude/config.json` if available
- Otherwise use a generic format like `TICKET-XXX`
- Examples: `ENG-123`, `FEAT-456`, `BUG-789`
You are tasked with resuming work from a handoff document through an interactive process. These
handoffs contain critical context, learnings, and next steps from previous work sessions that need
to be understood and continued.
## Initial Response
**STEP 1: Auto-discover recent handoff (REQUIRED)**
IMMEDIATELY run this bash script BEFORE any other response:
```bash
# Auto-discover most recent handoff from workflow context
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_HANDOFF=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent handoffs)
if [[ -n "$RECENT_HANDOFF" ]]; then
echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
echo ""
fi
fi
```
**STEP 2: Determine which handoff to use**
After running the auto-discovery script, follow this logic:
1. **If user provided a file path as parameter**:
- Use the provided path (user override)
- Skip to Step 3
2. **If user provided a ticket number (like PROJ-123)**:
- Run `humanlayer thoughts sync` to ensure `thoughts/` is up to date
- Look in `thoughts/shared/handoffs/PROJ-123/` directory
- List all handoffs for that ticket
- If multiple exist, use the most recent (by timestamp in filename `YYYY-MM-DD_HH-MM-SS`)
- If none exist, tell user and wait for input
- Skip to Step 3
3. **If no parameters provided AND RECENT_HANDOFF was found**:
- Show user: "📋 Found recent handoff: $RECENT_HANDOFF"
- Ask: "**Proceed with this handoff?** [Y/n]"
- If yes: use RECENT_HANDOFF and skip to Step 3
- If no: proceed to option 4
4. **If no parameters AND no RECENT_HANDOFF found**:
- List available handoffs from `thoughts/shared/handoffs/`
- Show most recent 5 handoffs with dates
- Ask user which one to use
- Wait for user input with path or ticket number
**STEP 3: Analyze the handoff**
Once you have a handoff path:
- Read the handoff document FULLY (no limit/offset)
- Immediately read any research or plan documents it references
- Do NOT use sub-agents to read these critical files
- Ingest all context from the handoff
- Propose course of action to user
- Get confirmation before proceeding
## Process Steps
### Step 1: Read and Analyze Handoff
1. **Read handoff document completely**:
- Use the Read tool WITHOUT limit/offset parameters
- Extract all sections:
- Task(s) and their statuses
- Recent changes
- Learnings
- Artifacts
- Action items and next steps
- Other notes
2. **Spawn focused research tasks**: Based on the handoff content, spawn parallel research tasks to
verify current state:
```
Task 1 - Verify recent changes:
Check if the recent changes mentioned in the handoff still exist.
1. Verify files mentioned in "Recent changes" section
2. Check if the described changes are still present
3. Look for any subsequent modifications
4. Identify any conflicts or regressions
Use tools: Read, Grep, Glob
Return: Current state of recent changes with file:line references
```
```
Task 2 - Validate current codebase state:
Verify the current state against what's described in the handoff.
1. Check files mentioned in "Learnings" section
2. Verify patterns and implementations still exist
3. Look for any breaking changes since handoff
4. Identify new related code added since handoff
Use tools: Read, Grep, Glob
Return: Validation results and any discrepancies found
```
```
Task 3 - Gather artifact context:
Read all artifacts mentioned in the handoff.
1. Read feature documents listed in "Artifacts"
2. Read implementation plans referenced
3. Read any research documents mentioned
4. Extract key requirements and decisions
Use tools: Read
Return: Summary of artifact contents and key decisions
```
3. **Wait for ALL sub-tasks to complete** before proceeding
4. **Read critical files identified**:
- Read files from "Learnings" section completely
- Read files from "Recent changes" to understand modifications
- Read any new related files discovered during research
### Step 2: Synthesize and Present Analysis
1. **Present comprehensive analysis**:
```
I've analyzed the handoff from [date] by [researcher]. Here's the current situation:
**Original Tasks:**
- [Task 1]: [Status from handoff] → [Current verification]
- [Task 2]: [Status from handoff] → [Current verification]
**Key Learnings Validated:**
- [Learning with file:line reference] - [Still valid/Changed]
- [Pattern discovered] - [Still applicable/Modified]
**Recent Changes Status:**
- [Change 1] - [Verified present/Missing/Modified]
- [Change 2] - [Verified present/Missing/Modified]
**Artifacts Reviewed:**
- [Document 1]: [Key takeaway]
- [Document 2]: [Key takeaway]
**Recommended Next Actions:**
Based on the handoff's action items and current state:
1. [Most logical next step based on handoff]
2. [Second priority action]
3. [Additional tasks discovered]
**Potential Issues Identified:**
- [Any conflicts or regressions found]
- [Missing dependencies or broken code]
Shall I proceed with [recommended action 1], or would you like to adjust the approach?
```
2. **Get confirmation** before proceeding
### Step 3: Create Action Plan
1. **Use TodoWrite to create task list**:
- Convert action items from handoff into todos
- Add any new tasks discovered during analysis
- Prioritize based on dependencies and handoff guidance
2. **Present the plan**:
```
I've created a task list based on the handoff and current analysis:
[Show todo list]
Ready to begin with the first task: [task description]?
```
### Step 4: Begin Implementation
1. **Start with the first approved task**
2. **Reference learnings from handoff** throughout implementation
3. **Apply patterns and approaches documented** in the handoff
4. **Update progress** as tasks are completed
## Guidelines
1. **Be Thorough in Analysis**:
- Read the entire handoff document first
- Verify ALL mentioned changes still exist
- Check for any regressions or conflicts
- Read all referenced artifacts
2. **Be Interactive**:
- Present findings before starting work
- Get buy-in on the approach
- Allow for course corrections
- Adapt based on current state vs handoff state
3. **Leverage Handoff Wisdom**:
- Pay special attention to "Learnings" section
- Apply documented patterns and approaches
- Avoid repeating mistakes mentioned
- Build on discovered solutions
4. **Track Continuity**:
- Use TodoWrite to maintain task continuity
- Reference the handoff document in commits
- Document any deviations from original plan
- Consider creating a new handoff when done
5. **Validate Before Acting**:
- Never assume handoff state matches current state
- Verify all file references still exist
- Check for breaking changes since handoff
- Confirm patterns are still valid
## Common Scenarios
### Scenario 1: Clean Continuation
- All changes from handoff are present
- No conflicts or regressions
- Clear next steps in action items
- Proceed with recommended actions
### Scenario 2: Diverged Codebase
- Some changes missing or modified
- New related code added since handoff
- Need to reconcile differences
- Adapt plan based on current state
### Scenario 3: Incomplete Handoff Work
- Tasks marked as "in_progress" in handoff
- Need to complete unfinished work first
- May need to re-understand partial implementations
- Focus on completing before new work
### Scenario 4: Stale Handoff
- Significant time has passed
- Major refactoring has occurred
- Original approach may no longer apply
- Need to re-evaluate strategy
## Example Interaction Flow
```
User: /catalyst-dev:resume_handoff specification/feature/handoffs/handoff-0.md
Assistant: Let me read and analyze that handoff document...
[Reads handoff completely]
[Spawns research tasks]
[Waits for completion]
[Reads identified files]
I've analyzed the handoff from [date]. Here's the current situation...
[Presents analysis]
Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?
User: Yes, proceed with the webhook validation
Assistant: [Creates todo list and begins implementation]
```

117
commands/roadmap_review.md Normal file
View File

@@ -0,0 +1,117 @@
---
description: Review project roadmap and milestone progress
category: project-task-management
tools: Bash(linearis *), Read, Write, TodoWrite
model: inherit
version: 1.0.0
status: placeholder
---
# Roadmap Review
**Status**: Placeholder for v1.0 - Full implementation coming in future release
## Planned Functionality
This command will help you review your roadmap by:
1. Listing all active projects
2. Showing milestone progress for each project
3. Identifying project dependencies
4. Calculating project completion
5. Generating roadmap summary
## Current Workaround
Use Linearis CLI directly:
```bash
# List projects
linearis projects list --team TEAM
# Parse project status from JSON
linearis projects list --team TEAM | jq '.[] | {name, status, progress}'
# List tickets for specific project
linearis issues list --team TEAM | jq '.[] | select(.project.name == "Project Name")'
```
### Example Workflow
```bash
# 1. List all active projects
linearis projects list --team ENG | \
jq '.[] | select(.state != "completed") | {name, lead, targetDate}'
# 2. Get project details with ticket counts
for project in $(linearis projects list --team ENG | jq -r '.[].name'); do
echo "Project: $project"
# Count tickets by status
linearis issues list --team ENG | \
jq --arg proj "$project" '
[.[] | select(.project.name == $proj)] |
group_by(.state.name) |
map({status: .[0].state.name, count: length})
'
done
# 3. Identify project dependencies
# (Manual - look at project descriptions or ticket relationships)
# 4. Calculate overall progress
# total_tickets in project
# completed_tickets in project
# progress = (completed / total) * 100
# 5. Identify at-risk projects
# - No tickets completed in last 2 weeks
# - Target date approaching with <50% completion
# - Blocked tickets preventing progress
```
## Future Implementation
When fully implemented, this command will:
- **Project overview** - Show all projects with key metrics
- **Milestone tracking** - Group tickets by milestone with progress
- **Dependency visualization** - Show project relationships and blockers
- **Risk analysis** - Identify at-risk projects (delayed, under-resourced)
- **Timeline view** - Show project timelines and conflicts
- **Resource allocation** - Show team members assigned to projects
- **Summary generation** - Create roadmap document in thoughts/
- **Trend analysis** - Compare progress month-over-month
Track progress at: https://github.com/coalesce-labs/catalyst/issues
## Configuration
Uses `.claude/config.json`:
```json
{
"linear": {
"teamKey": "ENG",
"defaultTeam": "Backend"
}
}
```
## Tips
- Review roadmap **monthly** or **quarterly**
- Update **target dates** based on actual velocity
- Document **dependencies** explicitly in project descriptions
- Identify **resource constraints** early
- Communicate **delays** proactively to stakeholders
- Use **milestones** to track major deliverables
- Archive **completed projects** to reduce noise
- Link projects to **company OKRs** for alignment
## Related Commands
- `/cycle-plan` - Plan work within cycles for a project
- `/cycle-review` - Review cycle progress
- `/catalyst-dev:linear` - Manage individual tickets
- `/create-plan` - Create implementation plans for tickets

216
commands/validate_plan.md Normal file
View File

@@ -0,0 +1,216 @@
---
description: Validate that implementation plans were correctly executed
category: workflow
---
# Validate Plan
You are tasked with validating that an implementation plan was correctly executed, verifying all
success criteria and identifying any deviations or issues.
## Initial Setup
When invoked:
1. **Determine context** - Are you in an existing conversation or starting fresh?
- If existing: Review what was implemented in this session
- If fresh: Need to discover what was done through git and codebase analysis
2. **Locate the plan**:
- If plan path provided, use it
- Otherwise, search recent commits for plan references or ask user
3. **Gather implementation evidence**:
```bash
# Check recent commits
git log --oneline -n 20
git diff HEAD~N..HEAD # Where N covers implementation commits
# Run comprehensive checks
cd $(git rev-parse --show-toplevel) && make check test
```
## Validation Process
### Step 1: Context Discovery
If starting fresh or need more context:
1. **Read the implementation plan** completely
2. **Identify what should have changed**:
- List all files that should be modified
- Note all success criteria (automated and manual)
- Identify key functionality to verify
3. **Spawn parallel research tasks** to discover implementation:
```
Task 1 - Verify database changes:
Research if migration [N] was added and schema changes match plan.
Check: migration files, schema version, table structure
Return: What was implemented vs what plan specified
Task 2 - Verify code changes:
Find all modified files related to [feature].
Compare actual changes to plan specifications.
Return: File-by-file comparison of planned vs actual
Task 3 - Verify test coverage:
Check if tests were added/modified as specified.
Run test commands and capture results.
Return: Test status and any missing coverage
```
### Step 2: Systematic Validation
For each phase in the plan:
1. **Check completion status**:
- Look for checkmarks in the plan (- [x])
- Verify the actual code matches claimed completion
2. **Run automated verification**:
- Execute each command from "Automated Verification"
- Document pass/fail status
- If failures, investigate root cause
3. **Assess manual criteria**:
- List what needs manual testing
- Provide clear steps for user verification
4. **Think deeply about edge cases**:
- Were error conditions handled?
- Are there missing validations?
- Could the implementation break existing functionality?
### Step 3: Generate Validation Report
**Before generating report, check context usage**:
Create comprehensive validation summary:
```
# Validation Report: {Feature Name}
**Plan**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-feature.md`
**Validated**: {date}
**Validation Status**: {PASS/FAIL/PARTIAL}
## 📊 Context Status
Current usage: {X}% ({Y}K/{Z}K tokens)
{If >60%}:
⚠️ **Context Alert**: Validation consumed {X}% of context.
**Recommendation**: After reviewing this report, clear context before PR creation.
**Why?** PR description generation benefits from fresh context to:
- Synthesize changes clearly
- Write concise summaries
- Avoid accumulated error context
**Next steps**:
1. Review this validation report
2. Address any failures
3. Close this session (clear context)
4. Start fresh for: `/catalyst-dev:commit` and `/describe-pr`
{If <60%}:
✅ Context healthy. Ready for PR creation.
---
{Continue with rest of validation report...}
```
```markdown
## Validation Report: [Plan Name]
### Implementation Status
✓ Phase 1: [Name] - Fully implemented ✓ Phase 2: [Name] - Fully implemented ⚠️ Phase 3: [Name] -
Partially implemented (see issues)
### Automated Verification Results
✓ Build passes: `make build` ✓ Tests pass: `make test` ✗ Linting issues: `make lint` (3 warnings)
### Code Review Findings
#### Matches Plan:
- Database migration correctly adds [table]
- API endpoints implement specified methods
- Error handling follows plan
#### Deviations from Plan:
- Used different variable names in [file:line]
- Added extra validation in [file:line] (improvement)
#### Potential Issues:
- Missing index on foreign key could impact performance
- No rollback handling in migration
### Manual Testing Required:
1. UI functionality:
- [ ] Verify [feature] appears correctly
- [ ] Test error states with invalid input
2. Integration:
- [ ] Confirm works with existing [component]
- [ ] Check performance with large datasets
### Recommendations:
- Address linting warnings before merge
- Consider adding integration test for [scenario]
- Document new API endpoints
```
## Working with Existing Context
If you were part of the implementation:
- Review the conversation history
- Check your todo list for what was completed
- Focus validation on work done in this session
- Be honest about any shortcuts or incomplete items
## Important Guidelines
1. **Be thorough but practical** - Focus on what matters
2. **Run all automated checks** - Don't skip verification commands
3. **Document everything** - Both successes and issues
4. **Think critically** - Question if the implementation truly solves the problem
5. **Consider maintenance** - Will this be maintainable long-term?
## Validation Checklist
Always verify:
- [ ] All phases marked complete are actually done
- [ ] Automated tests pass
- [ ] Code follows existing patterns
- [ ] No regressions introduced
- [ ] Error handling is robust
- [ ] Documentation updated if needed
- [ ] Manual test steps are clear
## Relationship to Other Commands
Recommended workflow:
1. `/catalyst-dev:implement_plan` - Execute the implementation
2. `/catalyst-dev:commit` - Create atomic commits for changes
3. `/catalyst-dev:validate_plan` - Verify implementation correctness
4. `/catalyst-dev:describe_pr` - Generate PR description
The validation works best after commits are made, as it can analyze the git history to understand
what was implemented.
Remember: Good validation catches issues before they reach production. Be constructive but thorough
in identifying gaps or improvements.

592
commands/workflow_help.md Normal file
View File

@@ -0,0 +1,592 @@
---
description: Interactive guide to supported workflows with context-aware assistance
category: workflow
tools: Read, Grep, Glob, Task
model: inherit
version: 1.0.0
---
# Workflow Help
You are an interactive workflow guide that helps users navigate the supported workflows in this
repository using parallel sub-agents for research and context-aware guidance.
## Initial Response
When this command is invoked WITHOUT parameters:
```
# 🎯 Workflow Guide
I can help you navigate the supported workflows in this workspace.
## Available Workflows
**1. Development Workflow** (research → plan → implement → validate → PR)
- `/research-codebase` → Document existing system
- `/create-plan` → Create implementation plan
- `/implement-plan` → Execute approved plan
- `/validate-plan` → Verify implementation
- Handoffs & worktrees for context management
**2. Workflow Discovery** (discover → import → create → validate)
- `/discover-workflows` → Research external repositories
- `/import-workflow` → Adapt external workflows
- `/create-workflow` → Build new agents/commands
- `/validate-frontmatter` → Ensure consistency
**3. Utilities**
- `/catalyst-dev:commit` → Create structured commits
- `/describe-pr` → Generate PR descriptions
- `/catalyst-dev:debug` → Investigate issues
- `/catalyst-dev:linear` → Linear ticket integration
---
**Which workflow would you like to learn about?**
Type the number (1-3) or workflow name, or ask a question like:
- "I have a ticket to implement - what should I do?"
- "How do I pause work and resume later?"
- "What's the complete development workflow?"
```
Then wait for user input.
## Processing User Input
### Step 1: Detect Context
Check if the user is already in a workflow by spawning parallel detection tasks:
**Task 1 - Check for Active Work**:
```
Use codebase-locator agent:
"Search for recent uncommitted changes, work-in-progress files, or partial implementations. Look for:
- Git status (uncommitted files)
- WIP branches
- Partial plan files with unchecked boxes
- Draft handoffs
Return: Evidence of active work with file paths"
Tools: Bash (git status), Grep, Glob
```
**Task 2 - Find Recent Documents**:
```
Use thoughts-locator agent (or Glob if no thoughts):
"Find the most recent research, plan, or handoff documents. Look in:
- thoughts/shared/research/ (or research/)
- thoughts/shared/plans/ (or plans/)
- thoughts/shared/handoffs/ (or handoffs/)
Return: 3 most recent documents with dates and topics"
Tools: Bash (ls -t), Grep, Glob
```
**Task 3 - Detect Worktree**:
```
"Check if currently in a git worktree (not main repo).
Run: pwd and git worktree list
Return: Whether in worktree, worktree name if applicable"
Tools: Bash
```
WAIT for all tasks to complete.
### Step 2: Analyze Context
Based on detection results, determine user's current state:
- **In Worktree with Plan** → Likely in Implementation phase
- **Recent Research Doc** → May be ready for Planning
- **Recent Plan Doc** → May be ready for Implementation
- **Recent Handoff** → May want to resume
- **No Active Work** → Starting fresh
### Step 3: Provide Context-Aware Guidance
**If User is in Active Workflow:**
```
🎯 **I see you're currently working on {detected-context}**
**Current State:**
- {What I detected - be specific with file paths}
- {Where you likely are in workflow}
**Suggested Next Steps:**
1. {Most likely next action}
2. {Alternative action}
3. {How to pause/handoff if needed}
**Context Management:**
⚠️ Remember to CLEAR CONTEXT between workflow phases!
- Current phase: {detected-phase}
- Clear context after: {when to clear}
**Note**: I can monitor my own context usage and will proactively warn you if it gets high. You can also check anytime with `/context`.
Would you like me to:
1. Continue with next step
2. Explain the complete workflow
3. Help you pause/create handoff
4. Something else
```
**If User is Starting Fresh:**
Proceed to workflow selection (Step 4).
### Step 4: Workflow Selection
Based on user's choice, spawn parallel research to provide comprehensive guidance:
#### For Development Workflow (Option 1):
Spawn 3 parallel research tasks:
**Task 1 - Read Workflow Guide**:
```
"Read docs/AGENTIC_WORKFLOW_GUIDE.md and extract:
- Complete workflow phases
- Context clearing guidelines
- When to use each command
Return: Concise summary of complete workflow"
Tools: Read
```
**Task 2 - Find Command Examples**:
```
"Search for examples in:
- commands/research_codebase.md
- commands/create_plan.md
- commands/implement_plan.md
Extract example usage and common patterns
Return: Concrete examples users can follow"
Tools: Read, Grep
```
**Task 3 - Check for User Files**:
```
"Check if user has any existing research, plans, or handoffs.
Look in thoughts/ or research/, plans/, handoffs/ directories.
Return: What files exist, suggesting next steps based on what's there"
Tools: Glob, Bash
```
WAIT for all tasks.
**Present Comprehensive Guide:**
```
# 🔄 Development Workflow: Research → Plan → Implement → Validate → PR
{Synthesize findings from 3 parallel tasks}
## Complete Process
### Phase 1: Research 🔍
**When**: Need to understand existing codebase before planning
**Command**: `/research-codebase`
{Include example from Task 2}
{Note any existing research docs from Task 3}
**Output**: `thoughts/shared/research/YYYY-MM-DD-PROJ-XXXX-description.md`
**After**: ✅ **CLEAR CONTEXT**
---
### Phase 2: Planning 📋
**When**: Ready to create implementation plan
**Command**: `/create-plan`
{Include example}
**Output**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-description.md`
**After**: ✅ **CLEAR CONTEXT**
---
### Phase 3: Worktree Creation 🌲
**When**: Plan approved, ready to implement
**How**:
\`\`\`bash
"${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" PROJ-123 feature-name
cd ~/wt/{project}/PROJ-123-feature
\`\`\`
**After**: ✅ **CLEAR CONTEXT** (fresh session in worktree)
---
### Phase 4: Implementation ⚙️
**When**: In worktree with approved plan
**Command**: `/implement-plan thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-feature.md`
{Include example}
**Checkpoints**: After EACH phase in plan
**After**: ✅ **CLEAR CONTEXT**
---
### Phase 5: Validation ✅
**When**: All implementation phases complete
**Command**: `/validate-plan`
**After**: ✅ **CLEAR CONTEXT**
---
### Phase 6: PR Creation 🚀
**Commands**:
\`\`\`bash
/catalyst-dev:commit
gh pr create --fill
/describe-pr
\`\`\`
**Output**: `thoughts/shared/prs/pr_{number}_{description}.md`
**After**: ✅ **CLEAR CONTEXT** - workflow complete!
---
## 🔄 Handoff System (Pause/Resume)
**Create Handoff** (to pause work):
\`\`\`bash
/create-handoff
\`\`\`
**Output**: `thoughts/shared/handoffs/PROJ-XXXX/YYYY-MM-DD_HH-MM-SS_description.md`
**Resume Handoff**:
\`\`\`bash
/resume-handoff {path-or-ticket}
\`\`\`
---
## ⚠️ Context Management
**CLEAR CONTEXT between EVERY phase**
- After research document created
- After plan approved
- After creating handoff
- Before implementation in worktree
- After implementation complete
- Before validation
- After PR created
**Why?** Keeps AI performance optimal (40-60% context utilization)
**How to check**: I monitor my context automatically and will warn you.
You can also check anytime with `/context` command.
**When I warn you**:
- I'll show current usage: e.g., "65% (130K/200K tokens)"
- I'll explain why clearing helps
- I'll offer to create a handoff if needed
- I'll tell you exactly what to do next
**Context clearing is NORMAL and EXPECTED** - it's how we maintain quality!
---
{Based on Task 3 - suggest next step}
**Your Next Step:**
{If existing files found:} You have {file} - ready to {next-action}?
{If no files:} Start with: `/research-codebase` or `/create-plan`
**Need more details on any phase?** Just ask!
```
#### For Workflow Discovery (Option 2):
Spawn parallel research:
**Task 1**: Read `docs/WORKFLOW_DISCOVERY_SYSTEM.md` **Task 2**: Read command files
(discover_workflows, import_workflow, etc.) **Task 3**: Check if user has any workflow catalog
WAIT and synthesize similar to above.
#### For Utilities (Option 3):
Read relevant command files and provide quick reference.
### Step 5: Answer Follow-Up Questions
**If user asks specific questions:**
Spawn focused research tasks to answer:
**Example**: "How do I pause work and resume later?"
```
Task 1: "Read docs/AGENTIC_WORKFLOW_GUIDE.md section on Handoff System"
Task 2: "Find examples in commands/create_handoff.md and commands/resume_handoff.md"
Task 3: "Check if user has existing handoffs"
```
Present targeted answer with examples.
### Step 6: Provide Quick Actions
**Always end with actionable next steps:**
```
---
## Ready to Get Started?
**Quick Actions:**
1. 📝 Start research: `/research-codebase`
2. 📋 Create plan: `/create-plan`
3. 🔄 Resume work: `/resume-handoff {ticket}`
4. 🔍 Discover workflows: `/discover-workflows`
5. ❓ Ask me anything else!
**Pro Tips:**
- Clear context between phases for best performance
- Read outputs completely before next phase
- Use handoffs liberally - context is precious
- Worktrees isolate your changes safely
Type a command or ask another question!
```
## Important Guidelines
### Context-Aware Assistance
1. **Always detect current state first** using parallel agents
2. **Don't assume** - verify with actual file checks
3. **Be specific** with file paths and next actions
4. **Remind about context clearing** at appropriate points
### Compression & Conciseness
1. **Parallel agents research details** - keep main context clean
2. **Synthesize findings** - don't dump raw agent outputs
3. **Provide examples** - concrete > abstract
4. **Quick reference** - users can dive deeper if needed
### Link to Documentation
**Always provide links** to detailed documentation:
- Full workflow: `docs/AGENTIC_WORKFLOW_GUIDE.md`
- Workflow discovery: `docs/WORKFLOW_DISCOVERY_SYSTEM.md`
- Frontmatter: `docs/FRONTMATTER_STANDARD.md`
- Main README: `README.md`
### Web Research (If Needed)
If user asks about external concepts:
**Use external-research agent**:
```
"Research {topic} from HumanLayer or Anthropic documentation.
Return: Summary with links to sources"
Tools: WebSearch, WebFetch, mcp__deepwiki__ask_question
```
Include links in response.
## Example Interactions
### Example 1: User in Middle of Workflow
```
User: /workflow-help
[Agent spawns 3 parallel detection tasks]
Agent: 🎯 **I see you're currently working on PROJ-123 OAuth implementation**
**Current State:**
- Worktree: `~/wt/my-project/PROJ-123-oauth`
- Plan: `thoughts/shared/plans/2025-01-08-PROJ-123-oauth.md`
- Status: Phase 2/4 complete (checkboxes updated)
**You're in Implementation Phase**
**Suggested Next Steps:**
1. ✅ Continue implementing Phase 3: `/implement-plan` (will resume from checkboxes)
2. 🔄 Need to pause? `/create-handoff` before stopping
3. 📖 Review plan: Check `thoughts/shared/plans/2025-01-08-PROJ-123-oauth.md`
**Context Management:**
⚠️ If context feels full (>60%), clear and resume with plan file
Would you like me to:
1. Continue with Phase 3
2. Show complete workflow overview
3. Help create handoff to pause work
```
### Example 2: User Starting Fresh
```
User: I have a ticket to implement OAuth support
[Agent spawns detection tasks - finds no active work]
Agent: 🎯 **Great! Let's start the Development Workflow for OAuth support**
I don't see any existing research or plans for this, so let's start from the beginning.
## Recommended Approach
### Step 1: Research Phase 🔍
First, understand how authentication currently works:
\`\`\`
/research-codebase
\`\`\`
When prompted, ask: "How does authentication currently work? What patterns exist?"
**Output**: `thoughts/shared/research/YYYY-MM-DD-PROJ-XXX-auth-system.md`
**After research**: ✅ **CLEAR CONTEXT** (close this conversation, start fresh)
---
### Step 2: Planning Phase 📋
Create implementation plan:
\`\`\`
/create-plan
\`\`\`
Reference your research doc when planning.
**Output**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXX-oauth-support.md`
**After plan approved**: ✅ **CLEAR CONTEXT**
---
{Continue with remaining phases...}
**Ready to start research?** Type `/research-codebase` or ask more questions!
```
### Example 3: Quick Question
```
User: How do I pause work and resume later?
[Agent reads handoff documentation]
Agent: 🔄 **Pausing and Resuming Work**
Use the **Handoff System** to pause/resume:
### To Pause:
\`\`\`bash
/create-handoff
\`\`\`
Creates: `thoughts/shared/handoffs/PROJ-XXXX/YYYY-MM-DD_HH-MM-SS_description.md`
The handoff captures:
- Current progress
- Critical file references
- Next action items
- Blockers/questions
**After creating handoff**: ✅ **CLEAR CONTEXT** - you can safely stop
---
### To Resume:
\`\`\`bash
/resume-handoff thoughts/shared/handoffs/PROJ-123/2025-01-08_14-30-45_oauth.md
\`\`\`
Or if command supports:
\`\`\`bash
/resume-handoff PROJ-123 # Finds latest handoff
\`\`\`
**The resume process:**
1. Reads handoff + linked docs
2. Verifies current state
3. Proposes next actions
4. Continues where you left off
---
**Pro Tip**: Create handoffs liberally! Any time:
- End of day
- Context fills up (>60%)
- Need to switch tasks
- Blocked and need input
See full guide: `docs/AGENTIC_WORKFLOW_GUIDE.md` (Handoff System section)
**Anything else?**
```
## Advanced Features
### Workflow State Detection
The parallel agents can detect:
- Current git branch
- Worktree vs main repo
- Recent files modified
- Plan files with checkboxes
- Research documents
- Handoff documents
- PR status
### Personalized Guidance
Based on detected state, provide:
- Specific file paths to reference
- Exact commands to run next
- Progress indicators (Phase X of Y)
- Context clearing reminders at right moments
### Link to External Resources
When relevant, include links:
```
**Further Reading:**
- [HumanLayer Advanced Context Engineering](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents)
- [12 Factor Agents](https://github.com/humanlayer/12-factor-agents)
- [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
```
## Important Notes
- **Use parallel agents** to research docs - keeps main context clean
- **Be context-aware** - detect where user is in workflow
- **Provide concrete examples** - not just theory
- **Remind about context clearing** - critical for performance
- **Link to detailed docs** - comprehensive info available
- **Quick actionable steps** - users can start immediately
- **Follow-up friendly** - can answer deeper questions
This command serves as an interactive, intelligent guide to the entire workflow system!