| name | thoughts-management |
| description | Manage thoughts directory operations including initialization and metadata generation. Use when initializing a new project's thoughts/ structure or when gathering git metadata for document frontmatter. |
| allowed-tools | Bash |
Thoughts Directory Management
Manage the thoughts/ directory system for organizing research, plans, and notes.
When to use this Skill
Use this Skill automatically in these situations:
- When gathering metadata for document frontmatter (git commit, branch, author)
- When initializing a new project that needs thoughts/ structure
Available operations
Initialize thoughts directory
Creates the complete thoughts/ directory structure in the current project.
When to use:
- First time setting up thoughts/ in a new project
- When thoughts/ directory doesn't exist
Command:
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-init
What it does:
- Creates directory structure:
{username}/, shared/
- Creates initial README.md
Generate metadata
Generates git and project metadata for document frontmatter.
When to use:
- Before creating research document frontmatter
- Before creating implementation plan frontmatter
- When you need current git commit, branch, repository info
- When you need timestamp information
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:
- Research document frontmatter fields
- Implementation plan frontmatter fields
- Any document requiring git context
Workflow integration
Metadata collection workflow
- Need to create document with frontmatter
- Gather metadata:
bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-metadata
- Use output to populate YAML frontmatter fields
- Create the document
Directory structure
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
Best practices
- Gather metadata before writing - Populate frontmatter with real values, never placeholders
- Use
grep -r thoughts/ to search - Searches all subdirectories recursively
Configuration
Set custom username (optional):
export THOUGHTS_USER=your_name
Default username: nikey_es
Troubleshooting
Metadata returns "no-branch" or "no-commit"
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.
Permission denied on scripts
Cause: Scripts are not executable
Solution: Run chmod:
chmod +x ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/*
Script reference
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-metadata | Generate git metadata | Before creating frontmatter |
Integration with commands
The following slash commands use this Skill:
/stepwise-core:research-codebase - Uses thoughts-init and thoughts-metadata/stepwise-core:create-plan - Uses thoughts-init and thoughts-metadata/stepwise-core:implement-plan - Uses thoughts-init
