Manage thoughts directory operations including initialization, synchronization, and metadata generation. Use after creating or modifying research documents, implementation plans, or notes to keep the searchable directory synchronized. Also use when gathering git metadata for document frontmatter.
Automatically synchronizes a searchable thoughts directory using hardlinks after creating or modifying research documents, implementation plans, or notes. Also generates git metadata for document frontmatter when needed.
/plugin marketplace add nikeyes/stepwise-dev/plugin install stepwise-dev@stepwise-devThis skill is limited to using the following tools:
scripts/thoughts-initscripts/thoughts-metadatascripts/thoughts-syncManage the thoughts/ directory system for organizing research, plans, and notes with efficient searchable hardlinks.
Use this Skill automatically in these situations:
thoughts/shared/research/thoughts/shared/plans/thoughts/Creates the complete thoughts/ directory structure in the current project.
When to use:
Command:
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-init
What it does:
{username}/, shared/, searchable/.gitignore for searchable/ directorySynchronizes hardlinks in thoughts/searchable/ for efficient grep operations.
When to use:
Command:
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync
What it does:
Important: Always run this after creating or modifying documents in thoughts/
Generates git and project metadata for document frontmatter.
When to use:
Command:
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-metadata
Output format:
Current Date/Time (TZ): 2025-01-12 14:30:45 PST
ISO DateTime: 2025-01-12T14:30:45-0800
Date Short: 2025-01-12
Current Git Commit Hash: abc123def456
Current Branch Name: main
Repository Name: my-project
Git User: John Doe
Git Email: john@example.com
Timestamp For Filename: 2025-01-12_14-30-45
Use this metadata to populate:
/stepwise-dev:research_codebase commandthoughts/shared/research/bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync
/stepwise-dev:create_plan or /stepwise-dev:iterate_plan commandthoughts/shared/plans/bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-metadata
The thoughts/ system maintains this structure:
thoughts/
├── {username}/ # Personal notes (default: nikey_es)
│ ├── tickets/ # Ticket documentation
│ └── notes/ # Personal observations
├── shared/ # Team-shared documents
│ ├── research/ # Research documents
│ ├── plans/ # Implementation plans
│ └── prs/ # PR descriptions
└── searchable/ # Auto-generated hardlinks
└── [hardlinks to all .md files for fast grep]
thoughts-sync creates hardlinks, not copiessearchable/, always document paths by removing "searchable/"thoughts/searchable/nikey_es/notes/X.md → thoughts/nikey_es/notes/X.mdSet custom username (optional):
export THOUGHTS_USER=your_name
Default username: nikey_es
Cause: Files were deleted from thoughts/ but hardlinks remain in searchable/
Solution: The script automatically cleans them up. No action needed.
Cause: Not in a git repository or git not available
Solution: Ensure you're in a git repository. For testing, the script provides fallback values.
Cause: Scripts are not executable
Solution: Run chmod:
chmod +x ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/*
All scripts are located in: ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/
| Script | Purpose | When to use |
|---|---|---|
thoughts-init | Initialize directory structure | Once per project |
thoughts-sync | Synchronize hardlinks | After every document change |
thoughts-metadata | Generate git metadata | Before creating frontmatter |
The following slash commands automatically use this Skill:
/stepwise-dev:research_codebase - Uses thoughts-metadata and thoughts-sync/stepwise-dev:create_plan - Uses thoughts-metadata and thoughts-sync/stepwise-dev:iterate_plan - Uses thoughts-sync/stepwise-dev:implement_plan - Uses thoughts-sync/stepwise-dev:validate_plan - Uses thoughts-syncThese commands will automatically invoke the appropriate scripts when needed.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.