Skill

thoughts-management

Manages thoughts/ directory: initializes structure with hardlinks, syncs searchable/ for grep searches, generates git metadata for frontmatter. Use after creating/modifying research docs, plans, notes, or project init.

Bash

Git

git-workflow

automation

Install

npx claudepluginhub nikeyes/stepwise-dev --plugin stepwise-core

Tool Access

This skill is limited to using the following tools:

Bash

Preview

Manage the thoughts/ directory system for organizing research, plans, and notes with efficient searchable hardlinks.

Supporting Assets

scripts/thoughts-initscripts/thoughts-metadatascripts/thoughts-sync

SKILL.md

Similar Skills

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

168.3k

subagent-driven-development

3 files

Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.

superpowers

168.3k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

168.3k

Stats

Parent Repo Stars16

Parent Repo Forks0

Last CommitFeb 19, 2026

Used By2 plugins

Actions

View Source View Plugin View on GitHub View README

Thoughts Directory Management

Manage the thoughts/ directory system for organizing research, plans, and notes with efficient searchable hardlinks.

When to use this Skill

Use this Skill automatically in these situations:

After creating research documents in thoughts/shared/research/
After creating implementation plans in thoughts/shared/plans/
After modifying any markdown files in thoughts/
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/, searchable/
Generates .gitignore for searchable/ directory
Creates initial README.md
Runs initial sync to create hardlinks

Sync searchable directory

Synchronizes hardlinks in thoughts/searchable/ for efficient grep operations.

When to use:

After creating new markdown files in thoughts/
After modifying existing markdown files in thoughts/
After completing a /stepwise-dev:research_codebase command
After completing a /stepwise-dev:create_plan command
After completing a /stepwise-dev:iterate_plan command

Command:

bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync

What it does:

Creates hardlinks for all .md files in searchable/
Removes orphaned links (when source files are deleted)
Maintains flat searchable/ structure for fast grep
Reports statistics (added, removed, skipped)

Important: Always run this after creating or modifying documents in thoughts/

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

Research workflow

Run /stepwise-dev:research_codebase command
Command generates research document in thoughts/shared/research/

Automatically run sync:

bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync

Planning workflow

Run /stepwise-dev:create_plan or /stepwise-dev:iterate_plan command
Command generates/updates plan in thoughts/shared/plans/

Automatically run sync:

bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-sync

Metadata collection workflow

Need to create document with frontmatter

First, gather metadata:

bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-metadata

Use output to populate YAML frontmatter fields
Create the document
Sync after creation

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
└── searchable/            # Auto-generated hardlinks
    └── [hardlinks to all .md files for fast grep]

Key concepts

Hardlinks vs copies

thoughts-sync creates hardlinks, not copies
Same file, multiple directory entries
No disk space duplication
Fast grep across all documents in searchable/

Searchable directory

Contains hardlinks to ALL .md files in thoughts/
Flattened structure for efficient searching
Automatically maintained by thoughts-sync
Gitignored (generated, not source)

Path handling

When finding files in searchable/, always document paths by removing "searchable/"
Preserve all other subdirectories: thoughts/searchable/nikey_es/notes/X.md → thoughts/nikey_es/notes/X.md
Never change directory structure when removing "searchable/" prefix

Best practices

Always sync after document creation - Keep searchable/ up to date
Gather metadata before writing - Populate frontmatter with real values, never placeholders
Run sync even for single files - Maintains consistency
Don't edit files in searchable/ - Edit in original locations only
Let the scripts handle hardlinks - Don't create them manually

Configuration

Set custom username (optional):

export THOUGHTS_USER=your_name

Default username: nikey_es

Troubleshooting

Sync reports orphaned links

Cause: Files were deleted from thoughts/ but hardlinks remain in searchable/

Solution: The script automatically cleans them up. No action needed.

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-sync`	Synchronize hardlinks	After every document change
`thoughts-metadata`	Generate git metadata	Before creating frontmatter

Integration with commands

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-sync

These commands will automatically invoke the appropriate scripts when needed.