Thoughts Directory Management Skill

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

Agent Skills: Thoughts Directory Management

Install this agent skill to your local

Skill Files