@dotdotgod/hermes 0.0.0-stage → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +94 -0
- package/README.md +126 -2
- package/__init__.py +48 -0
- package/mcp/bridge-entry.mjs +41 -0
- package/mcp/bridge.mjs +16217 -0
- package/mcp/cli.mjs +5842 -0
- package/mcp/server.mjs +23573 -0
- package/mcp/tools.json +749 -0
- package/package.json +37 -3
- package/plugin.yaml +18 -0
- package/policy.py +78 -0
- package/proxy.py +95 -0
- package/runtime.py +239 -0
- package/skills/document-clarify/SKILL.md +41 -0
- package/skills/impact-review/SKILL.md +31 -0
- package/skills/project-initializer/SKILL.md +37 -0
- package/skills/project-initializer/references/agent-docs.md +41 -0
- package/skills/project-initializer/scripts/init_project.sh +525 -0
- package/skills/project-initializer/templates/case-and-evidence.json +224 -0
- package/skills/project-initializer/templates/dotdotgod.config.json +239 -0
- package/skills/project-initializer/templates/policy.json +246 -0
- package/skills/project-initializer/templates/portfolio.json +260 -0
- package/skills/project-initializer/templates/publication.json +270 -0
- package/skills/project-initializer/templates/research.json +292 -0
- package/skills/project-initializer/templates/software.json +239 -0
- package/skills/project-load/SKILL.md +31 -0
|
@@ -0,0 +1,525 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
set -eu
|
|
3
|
+
|
|
4
|
+
SCRIPT_DIR=$(CDPATH= cd -P "$(dirname "$0")" && pwd)
|
|
5
|
+
TEMPLATES_DIR="$SCRIPT_DIR/../templates"
|
|
6
|
+
|
|
7
|
+
usage() {
|
|
8
|
+
cat <<'EOF'
|
|
9
|
+
Usage: init_project.sh <project-root> [--project-name NAME] [--template NAME] [--documentation-root PATH] [--dotdot-setting] [--dry-run]
|
|
10
|
+
|
|
11
|
+
Initializes:
|
|
12
|
+
AGENTS.md, CLAUDE.md, CODEX.md
|
|
13
|
+
dotdotgod.config.json
|
|
14
|
+
docs/README.md
|
|
15
|
+
docs/spec/README.md
|
|
16
|
+
docs/test/README.md
|
|
17
|
+
docs/arch/README.md
|
|
18
|
+
docs/plan/README.md
|
|
19
|
+
docs/archive/README.md
|
|
20
|
+
.gitignore entries for docs/plan, docs/archive, and .dotdotgod
|
|
21
|
+
EOF
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
PROJECT_ROOT=""
|
|
25
|
+
PROJECT_NAME=""
|
|
26
|
+
DRY_RUN=0
|
|
27
|
+
DOTDOT_SETTING=0
|
|
28
|
+
TEMPLATE_NAME="software"
|
|
29
|
+
DOCUMENTATION_ROOT="docs"
|
|
30
|
+
|
|
31
|
+
while [ "$#" -gt 0 ]; do
|
|
32
|
+
case "$1" in
|
|
33
|
+
--project-name)
|
|
34
|
+
[ "$#" -ge 2 ] || {
|
|
35
|
+
echo "error: --project-name requires a value" >&2
|
|
36
|
+
exit 2
|
|
37
|
+
}
|
|
38
|
+
PROJECT_NAME=$2
|
|
39
|
+
shift 2
|
|
40
|
+
;;
|
|
41
|
+
--template)
|
|
42
|
+
[ "$#" -ge 2 ] || {
|
|
43
|
+
echo "error: --template requires a value" >&2
|
|
44
|
+
exit 2
|
|
45
|
+
}
|
|
46
|
+
TEMPLATE_NAME=$2
|
|
47
|
+
shift 2
|
|
48
|
+
;;
|
|
49
|
+
--documentation-root)
|
|
50
|
+
[ "$#" -ge 2 ] || { echo "error: --documentation-root requires a value" >&2; exit 2; }
|
|
51
|
+
DOCUMENTATION_ROOT=$2
|
|
52
|
+
shift 2
|
|
53
|
+
;;
|
|
54
|
+
--dotdot-setting)
|
|
55
|
+
DOTDOT_SETTING=1
|
|
56
|
+
shift
|
|
57
|
+
;;
|
|
58
|
+
--dry-run)
|
|
59
|
+
DRY_RUN=1
|
|
60
|
+
shift
|
|
61
|
+
;;
|
|
62
|
+
-h|--help)
|
|
63
|
+
usage
|
|
64
|
+
exit 0
|
|
65
|
+
;;
|
|
66
|
+
-*)
|
|
67
|
+
echo "error: unknown option: $1" >&2
|
|
68
|
+
usage >&2
|
|
69
|
+
exit 2
|
|
70
|
+
;;
|
|
71
|
+
*)
|
|
72
|
+
if [ -n "$PROJECT_ROOT" ]; then
|
|
73
|
+
echo "error: unexpected argument: $1" >&2
|
|
74
|
+
usage >&2
|
|
75
|
+
exit 2
|
|
76
|
+
fi
|
|
77
|
+
PROJECT_ROOT=$1
|
|
78
|
+
shift
|
|
79
|
+
;;
|
|
80
|
+
esac
|
|
81
|
+
done
|
|
82
|
+
|
|
83
|
+
[ -n "$PROJECT_ROOT" ] || {
|
|
84
|
+
usage >&2
|
|
85
|
+
exit 2
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
case "$PROJECT_ROOT" in
|
|
89
|
+
/*) ;;
|
|
90
|
+
*) PROJECT_ROOT="$(pwd)/$PROJECT_ROOT" ;;
|
|
91
|
+
esac
|
|
92
|
+
|
|
93
|
+
case "$DOCUMENTATION_ROOT" in
|
|
94
|
+
''|/*|*\\*|*'..'*|*'*'*|*'?'*|*'['*|*']'*|*'{'*|*'}'*|.dotdotgod*|dotdotgod.config.json*)
|
|
95
|
+
echo "error: invalid documentation root: $DOCUMENTATION_ROOT" >&2
|
|
96
|
+
exit 2
|
|
97
|
+
;;
|
|
98
|
+
esac
|
|
99
|
+
DOCUMENTATION_ROOT=$(printf '%s' "$DOCUMENTATION_ROOT" | sed 's#^\./##; s#//*#/#g; s#/$##')
|
|
100
|
+
|
|
101
|
+
if [ -z "$PROJECT_NAME" ]; then
|
|
102
|
+
PROJECT_NAME=$(basename "$PROJECT_ROOT")
|
|
103
|
+
fi
|
|
104
|
+
|
|
105
|
+
CONFIG_PATH="$PROJECT_ROOT/dotdotgod.config.json"
|
|
106
|
+
case "$TEMPLATE_NAME" in
|
|
107
|
+
*[!a-z0-9-]*|'')
|
|
108
|
+
echo "error: template name must be kebab-case: $TEMPLATE_NAME" >&2
|
|
109
|
+
exit 2
|
|
110
|
+
;;
|
|
111
|
+
esac
|
|
112
|
+
CONFIG_TEMPLATE="$TEMPLATES_DIR/$TEMPLATE_NAME.json"
|
|
113
|
+
if [ ! -e "$CONFIG_PATH" ] && [ ! -f "$CONFIG_TEMPLATE" ]; then
|
|
114
|
+
echo "error: bundled template not found: $TEMPLATE_NAME; custom templates require the dotdotgod CLI" >&2
|
|
115
|
+
exit 2
|
|
116
|
+
fi
|
|
117
|
+
|
|
118
|
+
print_result() {
|
|
119
|
+
status=$1
|
|
120
|
+
path=$2
|
|
121
|
+
extra=${3:-}
|
|
122
|
+
if [ -n "$extra" ]; then
|
|
123
|
+
printf '%-13s %s %s\n' "$status" "$path" "$extra"
|
|
124
|
+
else
|
|
125
|
+
printf '%-13s %s\n' "$status" "$path"
|
|
126
|
+
fi
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
write_file() {
|
|
130
|
+
path=$1
|
|
131
|
+
content=$2
|
|
132
|
+
|
|
133
|
+
if [ -e "$path" ]; then
|
|
134
|
+
print_result "skipped" "$path"
|
|
135
|
+
return
|
|
136
|
+
fi
|
|
137
|
+
|
|
138
|
+
if [ "$DRY_RUN" -eq 1 ]; then
|
|
139
|
+
print_result "would_create" "$path"
|
|
140
|
+
return
|
|
141
|
+
fi
|
|
142
|
+
|
|
143
|
+
mkdir -p "$(dirname "$path")"
|
|
144
|
+
printf '%s\n' "$content" > "$path"
|
|
145
|
+
print_result "created" "$path"
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
ensure_directory() {
|
|
149
|
+
path=$1
|
|
150
|
+
if [ -e "$path" ]; then
|
|
151
|
+
print_result "skipped" "$path"
|
|
152
|
+
return
|
|
153
|
+
fi
|
|
154
|
+
if [ "$DRY_RUN" -eq 1 ]; then
|
|
155
|
+
print_result "would_create" "$path"
|
|
156
|
+
return
|
|
157
|
+
fi
|
|
158
|
+
mkdir -p "$path"
|
|
159
|
+
print_result "created" "$path"
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
ensure_gitignore_entry() {
|
|
163
|
+
entry=$1
|
|
164
|
+
path="$PROJECT_ROOT/.gitignore"
|
|
165
|
+
existed=0
|
|
166
|
+
[ -f "$path" ] && existed=1
|
|
167
|
+
|
|
168
|
+
if [ -f "$path" ] && grep -Fxq "$entry" "$path"; then
|
|
169
|
+
return
|
|
170
|
+
fi
|
|
171
|
+
|
|
172
|
+
if [ "$DRY_RUN" -eq 1 ]; then
|
|
173
|
+
if [ -f "$path" ]; then
|
|
174
|
+
print_result "would_update" "$path" "add=$entry"
|
|
175
|
+
else
|
|
176
|
+
print_result "would_create" "$path" "add=$entry"
|
|
177
|
+
fi
|
|
178
|
+
return
|
|
179
|
+
fi
|
|
180
|
+
|
|
181
|
+
mkdir -p "$PROJECT_ROOT"
|
|
182
|
+
if [ -f "$path" ] && [ -s "$path" ]; then
|
|
183
|
+
last_char=$(tail -c 1 "$path" || true)
|
|
184
|
+
[ "$last_char" = "" ] || printf '\n' >> "$path"
|
|
185
|
+
fi
|
|
186
|
+
printf '%s\n' "$entry" >> "$path"
|
|
187
|
+
if [ "$existed" -eq 1 ]; then
|
|
188
|
+
print_result "updated" "$path" "add=$entry"
|
|
189
|
+
else
|
|
190
|
+
print_result "created" "$path" "add=$entry"
|
|
191
|
+
fi
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
if [ "$DRY_RUN" -ne 1 ]; then
|
|
195
|
+
mkdir -p "$PROJECT_ROOT"
|
|
196
|
+
fi
|
|
197
|
+
|
|
198
|
+
DOTDOT_AGENT_RULE=""
|
|
199
|
+
if [ "$DOTDOT_SETTING" -eq 1 ]; then
|
|
200
|
+
DOTDOT_AGENT_RULE='
|
|
201
|
+
- Follow the project documentation structure in `$DOCUMENTATION_ROOT/arch/DOCS_STRUCTURE.md` and code conventions in `$DOCUMENTATION_ROOT/arch/CODE_CONVENTIONS.md`.'
|
|
202
|
+
fi
|
|
203
|
+
|
|
204
|
+
ARCH_README_EXTRA=""
|
|
205
|
+
if [ "$DOTDOT_SETTING" -eq 1 ]; then
|
|
206
|
+
ARCH_README_EXTRA='
|
|
207
|
+
|
|
208
|
+
## Index
|
|
209
|
+
|
|
210
|
+
- `DOCS_STRUCTURE.md`: documentation layout, naming, README index, spec current-state writing contract, and domain directory promotion rules.
|
|
211
|
+
- `CODE_CONVENTIONS.md`: dotdot code conventions, including abstraction boundaries, source file size guidance, impact hotspot handling, and extraction/testability rules. If conventions grow across multiple topics, promote them to `conventions/README.md` with supporting UPPER_SNAKE_CASE files.'
|
|
212
|
+
fi
|
|
213
|
+
|
|
214
|
+
write_file "$PROJECT_ROOT/AGENTS.md" "# AGENTS.md
|
|
215
|
+
|
|
216
|
+
Canonical instructions for AI coding agents working in this repository.
|
|
217
|
+
|
|
218
|
+
## Project
|
|
219
|
+
|
|
220
|
+
- Name: $PROJECT_NAME
|
|
221
|
+
- Purpose: TODO: describe the product, service, or library.
|
|
222
|
+
- Primary stack: TODO: list runtime, framework, database, and package manager.
|
|
223
|
+
|
|
224
|
+
## Working Rules
|
|
225
|
+
|
|
226
|
+
- Read existing code and docs before changing behavior.
|
|
227
|
+
- Keep changes scoped to the user's request.
|
|
228
|
+
- Preserve user edits and unrelated dirty worktree changes.
|
|
229
|
+
- Prefer existing local patterns over introducing new abstractions.
|
|
230
|
+
- Update docs when behavior, architecture, or test strategy changes.
|
|
231
|
+
- When using the dotdotgod CLI, run \`dotdotgod validate\` after docs changes and follow its traceability guidance for behavior specs.$DOTDOT_AGENT_RULE
|
|
232
|
+
|
|
233
|
+
## dotdotgod
|
|
234
|
+
|
|
235
|
+
dotdotgod is a project memory CLI for AI agents.
|
|
236
|
+
|
|
237
|
+
Use \`dotdotgod --help\` to discover available project-memory commands and their usage.
|
|
238
|
+
|
|
239
|
+
## Commands
|
|
240
|
+
|
|
241
|
+
Document the project-specific commands here:
|
|
242
|
+
|
|
243
|
+
\`\`\`bash
|
|
244
|
+
# Install dependencies
|
|
245
|
+
TODO
|
|
246
|
+
|
|
247
|
+
# Run tests
|
|
248
|
+
TODO
|
|
249
|
+
|
|
250
|
+
# Run the app
|
|
251
|
+
TODO
|
|
252
|
+
\`\`\`
|
|
253
|
+
|
|
254
|
+
## Documentation Map
|
|
255
|
+
|
|
256
|
+
- \`$DOCUMENTATION_ROOT/spec/\`: product behavior, API contracts, user-facing requirements.
|
|
257
|
+
- \`$DOCUMENTATION_ROOT/test/\`: test strategy, regression cases, manual verification notes.
|
|
258
|
+
- \`$DOCUMENTATION_ROOT/arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
|
|
259
|
+
- \`$DOCUMENTATION_ROOT/\`: all directories use kebab-case; all markdown file names use UPPER_SNAKE_CASE, including \`README.md\`.
|
|
260
|
+
- \`$DOCUMENTATION_ROOT/\`: prefer keeping individual markdown files under 200 lines and under 10,000 characters; split larger docs into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview.
|
|
261
|
+
- \`$DOCUMENTATION_ROOT/\`: when adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` index/table of contents in the same change.
|
|
262
|
+
- \`$DOCUMENTATION_ROOT/\`: each docs subdirectory \`README.md\` acts as the local table of contents; list important files, task directories, status, and a one-line purpose for each entry.
|
|
263
|
+
- \`$DOCUMENTATION_ROOT/\`: start small with a single focused markdown file; when one domain grows into multiple docs, promote it to \`$DOCUMENTATION_ROOT/<area>/<domain>/README.md\` plus related UPPER_SNAKE_CASE files in that directory.
|
|
264
|
+
- \`$DOCUMENTATION_ROOT/arch/\`: code conventions may start as \`CODE_CONVENTIONS.md\`; when they grow across multiple topics, use \`$DOCUMENTATION_ROOT/arch/conventions/README.md\` as the index with supporting UPPER_SNAKE_CASE files.
|
|
265
|
+
- \`$DOCUMENTATION_ROOT/plan/\`: local active implementation plans. Create one kebab-case directory per task (\`$DOCUMENTATION_ROOT/plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
|
|
266
|
+
- \`$DOCUMENTATION_ROOT/archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`$DOCUMENTATION_ROOT/archive/plan/<task-slug>/\`; put temporary reports and investigations under \`$DOCUMENTATION_ROOT/archive/report/<report-slug>/\`. Ignored by git by default.
|
|
267
|
+
|
|
268
|
+
## Agent-Specific Entrypoints
|
|
269
|
+
|
|
270
|
+
- \`CLAUDE.md\` imports this file with \`@AGENTS.md\`.
|
|
271
|
+
- \`CODEX.md\` points users to this file.
|
|
272
|
+
|
|
273
|
+
Keep long-lived instructions here so agent-specific files do not drift."
|
|
274
|
+
|
|
275
|
+
write_file "$PROJECT_ROOT/CLAUDE.md" "# CLAUDE.md
|
|
276
|
+
|
|
277
|
+
@AGENTS.md"
|
|
278
|
+
|
|
279
|
+
write_file "$PROJECT_ROOT/CODEX.md" "# CODEX.md
|
|
280
|
+
|
|
281
|
+
See [AGENTS.md](./AGENTS.md)."
|
|
282
|
+
|
|
283
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/README.md" "# Docs
|
|
284
|
+
|
|
285
|
+
This directory keeps project knowledge close to the code.
|
|
286
|
+
|
|
287
|
+
## Naming
|
|
288
|
+
|
|
289
|
+
- All directories under \`$DOCUMENTATION_ROOT/\` use kebab-case.
|
|
290
|
+
- All markdown file names under \`$DOCUMENTATION_ROOT/\` use UPPER_SNAKE_CASE, including \`README.md\`.
|
|
291
|
+
- Prefer keeping individual markdown files under 200 lines and under 10,000 characters; split larger docs into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview.
|
|
292
|
+
|
|
293
|
+
## Indexing
|
|
294
|
+
|
|
295
|
+
- When adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` index/table of contents in the same change.
|
|
296
|
+
- Each docs subdirectory \`README.md\` acts as the local table of contents; list important files, task directories, status, and a one-line purpose for each entry.
|
|
297
|
+
- Start small with a single focused markdown file; when one domain grows into multiple docs, promote it to \`$DOCUMENTATION_ROOT/<area>/<domain>/README.md\` plus related UPPER_SNAKE_CASE files in that directory.
|
|
298
|
+
|
|
299
|
+
## Map
|
|
300
|
+
|
|
301
|
+
- \`spec/\`: product behavior, API contracts, user-facing requirements.
|
|
302
|
+
- \`test/\`: test strategy, regression cases, manual verification notes.
|
|
303
|
+
- \`arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
|
|
304
|
+
- \`plan/\`: local active implementation plans. Create one kebab-case directory per task (\`plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
|
|
305
|
+
- \`archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`archive/plan/<task-slug>/\`; put temporary reports and investigations under \`archive/report/<report-slug>/\`. Ignored by git by default."
|
|
306
|
+
|
|
307
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/spec/README.md" "# Specs
|
|
308
|
+
|
|
309
|
+
Use this area for behavior specs, API contracts, and product requirements.
|
|
310
|
+
|
|
311
|
+
For projects using the dotdotgod CLI, behavior specs may be required by \`dotdotgod validate\` to include fenced \`json dotdotgod\` traceability blocks as the final section. The CLI owns the schema and prints property-level repair guidance when validation fails."
|
|
312
|
+
|
|
313
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/test/README.md" "# Tests
|
|
314
|
+
|
|
315
|
+
Use this area for test strategy, coverage notes, regression cases, and manual verification records."
|
|
316
|
+
|
|
317
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/arch/README.md" "# Architecture
|
|
318
|
+
|
|
319
|
+
Use this area for architecture decisions, code conventions, module boundaries, data flow notes, infrastructure/runtime dependencies, integration boundaries, and migration design.$ARCH_README_EXTRA"
|
|
320
|
+
|
|
321
|
+
if [ "$DOTDOT_SETTING" -eq 1 ]; then
|
|
322
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/arch/DOCS_STRUCTURE.md" "# Docs Structure
|
|
323
|
+
|
|
324
|
+
Long-term documentation structure for this project.
|
|
325
|
+
|
|
326
|
+
## Top-Level Areas
|
|
327
|
+
|
|
328
|
+
- \`$DOCUMENTATION_ROOT/spec/\`: product behavior, API contracts, user-facing requirements, and feature contracts.
|
|
329
|
+
- \`$DOCUMENTATION_ROOT/test/\`: test strategy, coverage notes, regression cases, and manual verification records.
|
|
330
|
+
- \`$DOCUMENTATION_ROOT/arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
|
|
331
|
+
- \`$DOCUMENTATION_ROOT/plan/\`: local active implementation plans.
|
|
332
|
+
- \`$DOCUMENTATION_ROOT/archive/\`: local completed plans, historical notes, payload captures, and investigation notes.
|
|
333
|
+
|
|
334
|
+
## Naming
|
|
335
|
+
|
|
336
|
+
- Directories under \`$DOCUMENTATION_ROOT/\` use kebab-case.
|
|
337
|
+
- Markdown files under \`$DOCUMENTATION_ROOT/\` use UPPER_SNAKE_CASE.
|
|
338
|
+
- \`README.md\` is the only mixed-case markdown filename exception and is required for index/overview files.
|
|
339
|
+
|
|
340
|
+
## File Size Guideline
|
|
341
|
+
|
|
342
|
+
Prefer keeping individual markdown files under 200 lines and 10,000 characters. When either guideline is exceeded, split the document into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview. Configured validation exceptions should stay narrow and intentional.
|
|
343
|
+
|
|
344
|
+
## README Indexes
|
|
345
|
+
|
|
346
|
+
Each docs subdirectory \`README.md\` acts as the local table of contents. It should list important files, task directories, status, and a one-line purpose for each entry.
|
|
347
|
+
|
|
348
|
+
When adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` in the same change.
|
|
349
|
+
|
|
350
|
+
## Domain Directory Promotion
|
|
351
|
+
|
|
352
|
+
Start small with one focused markdown file. When one domain grows into multiple docs, promote it to \`$DOCUMENTATION_ROOT/<area>/<domain>/README.md\` and place related UPPER_SNAKE_CASE markdown files in that directory.
|
|
353
|
+
|
|
354
|
+
## Spec Writing Contract
|
|
355
|
+
|
|
356
|
+
Behavior specs describe the current product contract: supported commands, API shapes, user-visible behavior, defaults, constraints, and validation outcomes.
|
|
357
|
+
|
|
358
|
+
Specs should not describe how behavior changed over time. Rewrite historical-change wording into direct current-state rules. Historical context, migration rationale, future extension ideas, and completed-plan notes belong in \`$DOCUMENTATION_ROOT/arch/\`, \`$DOCUMENTATION_ROOT/test/\`, \`$DOCUMENTATION_ROOT/archive/\`, or active \`$DOCUMENTATION_ROOT/plan/\` files rather than behavior specs. If compatibility behavior is still user-visible, keep it in the spec but phrase it as a current supported or unsupported rule.
|
|
359
|
+
|
|
360
|
+
Config/action terms such as \`remove\`, \`exclude\`, \`fallback\`, and \`replacement semantics\` are allowed when they name current behavior precisely.
|
|
361
|
+
|
|
362
|
+
## Traceability Blocks
|
|
363
|
+
|
|
364
|
+
Behavior specs may include fenced \`json dotdotgod\` traceability blocks as the final section to connect specs to source, tests, related docs, and verification commands. The dotdotgod CLI owns the schema and validation behavior.
|
|
365
|
+
|
|
366
|
+
## Plan and Archive Directories
|
|
367
|
+
|
|
368
|
+
Active task plans use \`$DOCUMENTATION_ROOT/plan/<task-slug>/README.md\`. Completed or superseded plan task directories move to \`$DOCUMENTATION_ROOT/archive/plan/<task-slug>/\`. Temporary investigations, reports, payload captures, and historical notes move to \`$DOCUMENTATION_ROOT/archive/report/<report-slug>/\`.
|
|
369
|
+
|
|
370
|
+
\`$DOCUMENTATION_ROOT/plan\` and \`$DOCUMENTATION_ROOT/archive\` are ignored by git by default.
|
|
371
|
+
"
|
|
372
|
+
|
|
373
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/arch/CODE_CONVENTIONS.md" "# Code Conventions
|
|
374
|
+
|
|
375
|
+
Dotdot code conventions for keeping implementation simple and maintainable.
|
|
376
|
+
|
|
377
|
+
## Abstraction Boundaries
|
|
378
|
+
|
|
379
|
+
- Do not introduce unnecessary abstractions.
|
|
380
|
+
- Do not abstract code that is not reused.
|
|
381
|
+
- Do not abstract reused code when the reused behavior is likely to split into separate features or flows later.
|
|
382
|
+
- Prefer local, explicit code until a stable reuse pattern appears.
|
|
383
|
+
|
|
384
|
+
## Source File Size
|
|
385
|
+
|
|
386
|
+
- Keep source files small enough to read in one focused pass by humans and coding agents.
|
|
387
|
+
- If code grows beyond 150 lines, consider splitting or extracting focused units even when it is not reused.
|
|
388
|
+
- Review files approaching 250 lines for focused extraction by responsibility.
|
|
389
|
+
- Split by behavior or responsibility, not by arbitrary layers.
|
|
390
|
+
|
|
391
|
+
## Dotdotgod Impact Hotspots
|
|
392
|
+
|
|
393
|
+
- Treat repeated \`dotdotgod graph impact\` results that collapse onto one large file as a design signal, not as normal precision.
|
|
394
|
+
- Dotdotgod impact reveals mixed-responsibility hotspots; it does not replace focused module boundaries.
|
|
395
|
+
- When unrelated changes keep pointing to the same source file, split the file by behavior so impact results, tests, and docs can map to narrower responsibilities.
|
|
396
|
+
|
|
397
|
+
## Extraction and Testability
|
|
398
|
+
|
|
399
|
+
- Prefer extracting pure helpers when behavior can be tested without runtime dependencies.
|
|
400
|
+
- Keep runtime integration explicit and local until reuse is stable.
|
|
401
|
+
- Put testable logic in focused modules before adding broad framework abstractions.
|
|
402
|
+
- Preserve plain-text readability: avoid dense clever code, hidden control flow, and large mixed-responsibility files.
|
|
403
|
+
"
|
|
404
|
+
fi
|
|
405
|
+
|
|
406
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/plan/README.md" "# Plans
|
|
407
|
+
|
|
408
|
+
Use this area for active implementation plans.
|
|
409
|
+
|
|
410
|
+
## Naming
|
|
411
|
+
|
|
412
|
+
- Task directories use kebab-case: \`$DOCUMENTATION_ROOT/plan/<task-slug>/\`.
|
|
413
|
+
- Markdown file names use UPPER_SNAKE_CASE: \`README.md\`, \`RESEARCH_NOTES.md\`, \`VERIFICATION.md\`.
|
|
414
|
+
|
|
415
|
+
## Structure
|
|
416
|
+
|
|
417
|
+
- Create one directory per task: \`$DOCUMENTATION_ROOT/plan/<task-slug>/\`.
|
|
418
|
+
- Put the task overview, index, scope, status, and main plan in \`$DOCUMENTATION_ROOT/plan/<task-slug>/README.md\`.
|
|
419
|
+
- Add supporting research, checklists, payload captures, or verification notes as additional UPPER_SNAKE_CASE markdown files in the same task directory.
|
|
420
|
+
- Move completed or superseded task directories to \`$DOCUMENTATION_ROOT/archive/plan/<task-slug>/\`.
|
|
421
|
+
|
|
422
|
+
This directory is local-only and ignored by git by default."
|
|
423
|
+
|
|
424
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/archive/README.md" "# Archive
|
|
425
|
+
|
|
426
|
+
Use this area for local completed plans, temporary reports, historical notes, payload captures, and investigation notes.
|
|
427
|
+
|
|
428
|
+
## Naming
|
|
429
|
+
|
|
430
|
+
- Archived plan task directories preserve their kebab-case task slug.
|
|
431
|
+
- Archived report directories use a focused kebab-case report slug.
|
|
432
|
+
- Markdown file names use UPPER_SNAKE_CASE, including \`README.md\`.
|
|
433
|
+
|
|
434
|
+
## Structure
|
|
435
|
+
|
|
436
|
+
- Move completed plan task directories from \`$DOCUMENTATION_ROOT/plan/<task-slug>/\` to \`$DOCUMENTATION_ROOT/archive/plan/<task-slug>/\`.
|
|
437
|
+
- Put temporary investigations, reports, payload captures, and historical notes under \`$DOCUMENTATION_ROOT/archive/report/<report-slug>/\`.
|
|
438
|
+
- Preserve each archive directory's \`README.md\` overview/index and supporting UPPER_SNAKE_CASE markdown files.
|
|
439
|
+
- Additional archive categories can be added later as focused kebab-case subdirectories when needed.
|
|
440
|
+
|
|
441
|
+
This directory is local-only and ignored by git by default."
|
|
442
|
+
|
|
443
|
+
if [ ! -e "$CONFIG_PATH" ]; then
|
|
444
|
+
case "$TEMPLATE_NAME" in
|
|
445
|
+
software)
|
|
446
|
+
;;
|
|
447
|
+
research)
|
|
448
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/research/README.md" "# Research
|
|
449
|
+
|
|
450
|
+
Use this area for research notes, sources, and findings."
|
|
451
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/record/README.md" "# Research Records
|
|
452
|
+
|
|
453
|
+
Use this area for dated measurements, experiments, and execution records."
|
|
454
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/report/README.md" "# Reports
|
|
455
|
+
|
|
456
|
+
Use this area for research diagnoses, analyses, results, and performance reports."
|
|
457
|
+
ensure_directory "$PROJECT_ROOT/outputs"
|
|
458
|
+
;;
|
|
459
|
+
case-and-evidence)
|
|
460
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/case/README.md" "# Case Records
|
|
461
|
+
|
|
462
|
+
Use this area for canonical case facts, questions, and decisions."
|
|
463
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/evidence/README.md" "# Evidence
|
|
464
|
+
|
|
465
|
+
Use this area for factual, legal, and other supporting evidence."
|
|
466
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/outputs/README.md" "# Case Outputs
|
|
467
|
+
|
|
468
|
+
Use this area for maintained case outputs."
|
|
469
|
+
;;
|
|
470
|
+
publication)
|
|
471
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/outline/README.md" "# Publication Outline
|
|
472
|
+
|
|
473
|
+
Use this area for publication structure and outlines."
|
|
474
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/chapters/README.md" "# Chapter Plans
|
|
475
|
+
|
|
476
|
+
Use this area for chapter plans and direction."
|
|
477
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/claims/README.md" "# Claims
|
|
478
|
+
|
|
479
|
+
Use this area for maintained claims and their support."
|
|
480
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/research/README.md" "# Research Sources
|
|
481
|
+
|
|
482
|
+
Use this area for research sources and supporting notes."
|
|
483
|
+
ensure_directory "$PROJECT_ROOT/book"
|
|
484
|
+
;;
|
|
485
|
+
portfolio)
|
|
486
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/strategy/README.md" "# Portfolio Strategy
|
|
487
|
+
|
|
488
|
+
Use this area for portfolio strategy and risk rules."
|
|
489
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/positions/README.md" "# Position Theses
|
|
490
|
+
|
|
491
|
+
Use this area for position theses and investment conclusions."
|
|
492
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/journal/README.md" "# Decision Journal
|
|
493
|
+
|
|
494
|
+
Use this area for dated investment decisions and reviews."
|
|
495
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/report/README.md" "# Market Research
|
|
496
|
+
|
|
497
|
+
Use this area for maintained market research and analysis."
|
|
498
|
+
ensure_directory "$PROJECT_ROOT/data"
|
|
499
|
+
;;
|
|
500
|
+
policy)
|
|
501
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/policy/README.md" "# Policy Documents
|
|
502
|
+
|
|
503
|
+
Use this area for integrated policy proposals and outputs."
|
|
504
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/sections/README.md" "# Policy Sections
|
|
505
|
+
|
|
506
|
+
Use this area for source policy sections."
|
|
507
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/evidence/README.md" "# Policy Evidence
|
|
508
|
+
|
|
509
|
+
Use this area for evidence supporting policy proposals."
|
|
510
|
+
write_file "$PROJECT_ROOT/$DOCUMENTATION_ROOT/outputs/README.md" "# Submission Outputs
|
|
511
|
+
|
|
512
|
+
Use this area for maintained policy submission outputs."
|
|
513
|
+
;;
|
|
514
|
+
esac
|
|
515
|
+
fi
|
|
516
|
+
|
|
517
|
+
if [ -e "$CONFIG_PATH" ]; then
|
|
518
|
+
print_result "skipped" "$CONFIG_PATH"
|
|
519
|
+
else
|
|
520
|
+
write_file "$CONFIG_PATH" "$(sed 's#"root": "docs"#"root": "'$DOCUMENTATION_ROOT'"#; s#"docs/#"'$DOCUMENTATION_ROOT'/#g' "$CONFIG_TEMPLATE")"
|
|
521
|
+
fi
|
|
522
|
+
|
|
523
|
+
ensure_gitignore_entry "$DOCUMENTATION_ROOT/plan"
|
|
524
|
+
ensure_gitignore_entry "$DOCUMENTATION_ROOT/archive"
|
|
525
|
+
ensure_gitignore_entry ".dotdotgod"
|