Claude Workspace Organization

Purpose

Maintain organized working files in the .claude/ directory with enforced structure, consistent naming, and required cross-references to codebase files and related documentation.

Use this skill when:

•Creating implementation plans, architecture decisions, or design documents
•Documenting research findings or code analysis
•Capturing reusable code examples or patterns
•Organizing existing loose planning files
•Validating workspace structure

Directory Structure

code

.claude/
├── plans/              # Implementation plans, migration plans, project plans
│   └── INDEX.md
├── architecture/       # ADRs, design decisions, system diagrams
│   └── INDEX.md
├── examples/           # Code examples, usage patterns, reference implementations
│   └── INDEX.md
├── research/           # Research notes, external findings, comparative analysis
│   └── INDEX.md
└── analysis/           # Code analysis, performance studies, security reviews
    └── INDEX.md

Essential Principles

1. Every File Links to Codebase

Every working file MUST contain at least one link to a relevant codebase file. No orphan documentation.

2. Every File Links to Related .claude/ Docs

Files should cross-reference related documents in other categories when relevant connections exist.

3. INDEX.md is Auto-Updated

When creating or modifying files, always update the category's INDEX.md.

4. Consistent Frontmatter

All files use YAML frontmatter with required fields per category. See frontmatter-schemas.md.

Intake

What would you like to do?

•Create new file - Create a plan, architecture doc, example, research, or analysis
•Update INDEX - Manually refresh a category's INDEX.md
•Validate workspace - Check workspace structure and fix issues
•Migrate existing - Organize loose files into proper structure

Wait for response before proceeding.

Routing

Response	Workflow
1, "create", "new", "add", "plan", "architecture", "example", "research", "analysis"	create-file.md
2, "index", "update index", "refresh"	update-index.md
3, "validate", "check", "verify"	validate-workspace.md
4, "migrate", "organize", "cleanup", "move"	migrate-existing.md

Quick Reference

File Naming Convention

code

{category}/{YYYY-MM-DD}-{kebab-case-description}.md

Examples:

•plans/2025-01-07-user-authentication-migration.md
•architecture/2025-01-07-event-sourcing-design.md
•research/2025-01-07-auth-library-comparison.md
•examples/2025-01-07-pagination-pattern.md
•analysis/2025-01-07-n-plus-one-audit.md

See naming-conventions.md for details.

Required Cross-References

Every file MUST include a ## Related section:

markdown

## Related

### Codebase
- [user.rb](../../app/models/user.rb) - Primary model affected by this plan

### Related Documentation
- [Auth Architecture](../architecture/2025-01-07-auth-design.md) - Design decision this implements

See cross-reference-rules.md for full rules.

Category Guide

Category	Purpose	Status Values
plans/	Implementation plans, migration plans	draft, in-progress, approved, implemented, superseded
architecture/	ADRs, design decisions	proposed, accepted, deprecated, superseded
examples/	Code patterns, reference implementations	(no status)
research/	External research, comparisons	in-progress, complete
analysis/	Code analysis, performance studies	in-progress, complete

See file-categories.md for detailed guidance.

Integration Points

Invoked by:

•Manual invocation when creating planning/architecture documents
•When Claude detects file creation that should go in .claude/
•/workspace command (if configured)

Works with:

•file-todos - Todos can link to plans or architecture docs
•compound-docs - Solution docs can reference research or analysis files
•/workflows:plan - Plans created via workflow can use this organization

Success Criteria

A workspace file is valid when ALL of the following are true:

•Valid YAML frontmatter with all required fields
•File in correct category directory
•Filename follows YYYY-MM-DD-description.md pattern
•At least one codebase link in ## Related > ### Codebase
•INDEX.md updated with file entry