Interactive guide to supported workflows with context-aware assistance
Provides interactive, context-aware guidance for navigating agentic workflows with parallel research assistance.
/plugin marketplace add coalesce-labs/catalyst/plugin install catalyst-meta@catalystinheritYou 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.
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.
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.
Based on detection results, determine user's current state:
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).
Based on user's choice, spawn parallel research to provide comprehensive guidance:
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!
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.
Read relevant command files and provide quick reference.
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.
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!
Always provide links to detailed documentation:
docs/AGENTIC_WORKFLOW_GUIDE.mddocs/WORKFLOW_DISCOVERY_SYSTEM.mddocs/FRONTMATTER_STANDARD.mdREADME.mdIf 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.
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
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!
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?**
The parallel agents can detect:
Based on detected state, provide:
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)
This command serves as an interactive, intelligent guide to the entire workflow system!