1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
# Working-Files Convention
Applies to: `**/*` (every project)
How in-progress task artifacts are organized in the project tree, and how
they migrate to their permanent home when the task ships.
## The Rule
Every in-progress task that produces files (drafts, source documents,
diagrams, scripts, sample data, transcripts, sub-deliverables) gets a
dedicated subdirectory under the project's `working/` directory, named
after the task. All artifacts for that task live in that subdirectory —
the org source, every supporting file, every draft revision, every
generated artifact — until the task is marked done.
When the task is marked done, the files get **renamed individually** and
**moved flat** into the appropriate permanent home (typically `assets/`,
or an area-specific `assets/` like `deepsat/assets/`). The working
subdirectory is then empty and gets deleted.
**Never rename the directory itself as a substitute for filing.** Renaming
the working subdir to its permanent name keeps every file together as a
bundle, but loses the flat-filing property — future grep for an artifact
hits a nested path instead of a single canonical name. Always rename the
files individually with a shared prefix so they sort together but live as
flat siblings in `assets/`.
## Directory Layout
<project-root>/
working/
<task-slug>/
<artifact-1>
<artifact-2>
...
Examples:
work/working/tech-deck-vol2/
tech-deck-vol2.org
slide-04-platform-at-a-glance.mmd
slide-04-platform-at-a-glance.png
vol1-template.pptx
finances/working/2026-q2-tax-return/
schedule-c.org
receipts-import.csv
depreciation-worksheet.ods
work/working/SE-297-justin-onboarding/
justin-tasking-options.org
rate-research.org
advisory-agreement-draft.docx
## Task-Slug Naming
Keep the slug short, kebab-case, and recognizable on a 1-second scan.
- Topic-led for narrative tasks: `tech-deck-vol2`, `branching-strategy-spec`, `tampa-trip`.
- Ticket-led for ticket-driven tasks: `SE-297-justin-onboarding`, `DEE-722-vincent-vetting`.
- Date-led for time-boxed work: `2026-q2-tax-return`, `2026-05-sofweek-prep`.
Avoid: trailing dates on topic-led slugs (`tech-deck-vol2-2026-05-18`)
when the task is open-ended; the slug names *the task*, not a snapshot.
## Filing on Completion
When the task is marked done:
1. **Decide each file's permanent home.** Usually one of:
- `<area>/assets/` (e.g. `deepsat/assets/`) — for area-scoped reference
material (transcripts, PDFs, diagrams that document the area's state).
- Project-root `assets/` — for project-scoped material.
- `<area>/<topic>/` — for material that joins an existing topic
subdirectory (rare; only when the topic dir already exists).
2. **Rename each file** so it carries the task context and is sortable
alongside its siblings. Standard form:
`<YYYY-MM-DD>-<task-slug>-<descriptor>.<ext>`
Examples:
- `tech-deck-vol2.org` → `2026-05-18-tech-deck-vol2-source.org`
- `slide-04-platform-at-a-glance.png` → `2026-05-18-tech-deck-vol2-slide-04-diagram.png`
- `vol1-template.pptx` → `2026-05-08-tech-deck-vol1-template.pptx`
(use the date the artifact originated, not the date the task closed,
when it's clearly meaningful — Vol 1 template predates Vol 2 work)
3. **Move flat into the permanent home.** No nested subdirectory in
`assets/`. The files sort together by date + task-slug prefix.
4. **Delete the now-empty `working/<task-slug>/` subdirectory.**
5. **Update any inbound links.** Tasks in `todo.org`, references in
`notes.org`, cross-links from other documents — all need their `file:`
paths updated to the new flat-filed locations. Use grep to find every
occurrence before deleting the working dir.
## Why This Shape
- *Discovery during work* — every artifact for the current task is in
one place. No hunting across `assets/`, `drafts/`, scratch dirs.
- *Discovery after completion* — `assets/` stays a flat searchable
store. Every artifact is reachable by a single `find assets/ -name '*<slug>*'`.
- *Atomic completion* — the act of filing forces a review of every
artifact's permanent value. Files that aren't worth keeping get
deleted in the move; the rename forces a meaningful name.
- *No orphan subdirs in `assets/`* — renaming the directory instead of
files would bury artifacts inside a nested path that no flat search
reaches. Three years from now `assets/old-tech-deck-2026/slide.png`
is harder to find than `assets/2026-05-18-tech-deck-vol2-slide-04-diagram.png`.
## When the Rule Doesn't Apply
- *Single-file scratch work that lives one day* — a `/tmp/foo.txt` for
a draft is fine. The convention is for tasks producing multiple
artifacts or artifacts worth keeping.
- *Source-controlled subprojects* — code under `<project>/code/<repo>/`
follows the subproject's own conventions, not this rule.
- *Inbox content* — `inbox/` and `daily-prep/` follow their own
conventions (dated filenames, processed and moved on cadence).
## Implementation Note for Claude Sessions
When the user starts a new task that's going to produce file artifacts:
1. Propose the working-dir path before creating any files
(`working/<task-slug>/`).
2. Create the directory and put the first artifact there.
3. Add or update the inbound link in `todo.org` to point at the new
path.
4. Note the working-dir in the task's body so future sessions find it.
When the user marks the task done:
1. List every file in the working subdir.
2. Propose renames + permanent homes for each.
3. Move flat after confirmation.
4. Delete the empty working subdir.
5. Update inbound links.
The directory layout is the same shape across every project — see
per-project `CLAUDE.md` or `notes.org` for project-specific
permanent-home conventions (e.g. `deepsat/assets/` vs project-root
`assets/`).
|
