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?
- 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
{category}/{YYYY-MM-DD}-{kebab-case-description}.md
Examples:
plans/2025-01-07-user-authentication-migration.mdarchitecture/2025-01-07-event-sourcing-design.mdresearch/2025-01-07-auth-library-comparison.mdexamples/2025-01-07-pagination-pattern.mdanalysis/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 docscompound-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
1---2name: claude-workspace3description: This skill should be used when creating or organizing working files in the .claude/ directory. It enforces consistent structure, naming conventions, and required cross-references for plans, architecture docs, examples, research, and analysis files.4---5
6# Claude Workspace Organization
7
8## Purpose
9
10Maintain organized working files in the `.claude/` directory with enforced structure, consistent naming, and required cross-references to codebase files and related documentation.
11
12**Use this skill when:**
13- Creating implementation plans, architecture decisions, or design documents
14- Documenting research findings or code analysis
15- Capturing reusable code examples or patterns
16- Organizing existing loose planning files
17- Validating workspace structure
18
19## Directory Structure
20
21```
22.claude/
23├── plans/ # Implementation plans, migration plans, project plans
24│ └── INDEX.md
25├── architecture/ # ADRs, design decisions, system diagrams
26│ └── INDEX.md
27├── examples/ # Code examples, usage patterns, reference implementations
28│ └── INDEX.md
29├── research/ # Research notes, external findings, comparative analysis
30│ └── INDEX.md
31└── analysis/ # Code analysis, performance studies, security reviews
32 └── INDEX.md
33```
34
35---
36
37## Essential Principles
38
39### 1. Every File Links to Codebase
40
41Every working file MUST contain at least one link to a relevant codebase file. No orphan documentation.
42
43### 2. Every File Links to Related .claude/ Docs
44
45Files should cross-reference related documents in other categories when relevant connections exist.
46
47### 3. INDEX.md is Auto-Updated
48
49When creating or modifying files, always update the category's INDEX.md.
50
51### 4. Consistent Frontmatter
52
53All files use YAML frontmatter with required fields per category. See [frontmatter-schemas.md](./references/frontmatter-schemas.md).
54
55---
56
57## Intake
58
59**What would you like to do?**
60
611. **Create new file** - Create a plan, architecture doc, example, research, or analysis
622. **Update INDEX** - Manually refresh a category's INDEX.md
633. **Validate workspace** - Check workspace structure and fix issues
644. **Migrate existing** - Organize loose files into proper structure
65
66**Wait for response before proceeding.**
67
68---
69
70## Routing
71
72| Response | Workflow |
73|----------|----------|
74| 1, "create", "new", "add", "plan", "architecture", "example", "research", "analysis" | [create-file.md](./workflows/create-file.md) |
75| 2, "index", "update index", "refresh" | [update-index.md](./workflows/update-index.md) |
76| 3, "validate", "check", "verify" | [validate-workspace.md](./workflows/validate-workspace.md) |
77| 4, "migrate", "organize", "cleanup", "move" | [migrate-existing.md](./workflows/migrate-existing.md) |
78
79---
80
81## Quick Reference
82
83### File Naming Convention
84
85```
86{category}/{YYYY-MM-DD}-{kebab-case-description}.md
87```
88
89**Examples:**
90- `plans/2025-01-07-user-authentication-migration.md`
91- `architecture/2025-01-07-event-sourcing-design.md`
92- `research/2025-01-07-auth-library-comparison.md`
93- `examples/2025-01-07-pagination-pattern.md`
94- `analysis/2025-01-07-n-plus-one-audit.md`
95
96See [naming-conventions.md](./references/naming-conventions.md) for details.
97
98### Required Cross-References
99
100Every file MUST include a `## Related` section:
101
102```markdown
103## Related
104
105### Codebase
106- [user.rb](../../app/models/user.rb) - Primary model affected by this plan
107
108### Related Documentation
109- [Auth Architecture](../architecture/2025-01-07-auth-design.md) - Design decision this implements
110```
111
112See [cross-reference-rules.md](./references/cross-reference-rules.md) for full rules.
113
114### Category Guide
115
116| Category | Purpose | Status Values |
117|----------|---------|---------------|
118| plans/ | Implementation plans, migration plans | draft, in-progress, approved, implemented, superseded |
119| architecture/ | ADRs, design decisions | proposed, accepted, deprecated, superseded |
120| examples/ | Code patterns, reference implementations | (no status) |
121| research/ | External research, comparisons | in-progress, complete |
122| analysis/ | Code analysis, performance studies | in-progress, complete |
123
124See [file-categories.md](./references/file-categories.md) for detailed guidance.
125
126---
127
128## Integration Points
129
130**Invoked by:**
131- Manual invocation when creating planning/architecture documents
132- When Claude detects file creation that should go in .claude/
133- `/workspace` command (if configured)
134
135**Works with:**
136- `file-todos` - Todos can link to plans or architecture docs
137- `compound-docs` - Solution docs can reference research or analysis files
138- `/workflows:plan` - Plans created via workflow can use this organization
139
140---
141
142## Success Criteria
143
144A workspace file is valid when ALL of the following are true:
145
146- Valid YAML frontmatter with all required fields
147- File in correct category directory
148- Filename follows `YYYY-MM-DD-description.md` pattern
149- At least one codebase link in `## Related > ### Codebase`
150- INDEX.md updated with file entry
majiayu000