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

.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?

1. Create new file - Create a plan, architecture doc, example, research, or analysis
2. Update INDEX - Manually refresh a category's INDEX.md
3. Validate workspace - Check workspace structure and fix issues
4. 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

{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:

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