Skip to content

Commit 5b77e11

Browse files
author
DavidQ
committed
PLAN_PR_DEV_CONSOLE_COMMAND_PACKS
- Planned namespaced command packs for the interactive dev console - Defined scalable grouping, help behavior, and output conventions - Preserved engine-safe and sample-safe boundaries
1 parent 0a7267a commit 5b77e11

11 files changed

Lines changed: 369 additions & 29 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
codex_commands.md
5+
16
MODEL: GPT-5.4-codex
27
REASONING: high
38

49
COMMAND:
5-
Create RULES_OF_ENGAGEMENT.md and remove duplicate rule files.
10+
Create BUILD_PR_DEV_CONSOLE_COMMAND_PACKS as a docs-only, repo-structured delta.
611

7-
- Consolidate RULES.txt and WORKFLOW.md
8-
- Keep single source of truth
9-
- Do not touch runtime code
10-
- Package to <project folder>/tmp/BUILD_PR_RULES_OF_ENGAGEMENT_STANDARDIZATION_delta.zip
12+
Requirements:
13+
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
14+
- Docs-first only
15+
- No implementation code in this bundle
16+
- Plan namespaced command packs for the existing dev console
17+
- Define command registry shape, help behavior, output contract, and validation conventions
18+
- Keep implementation future scope limited to tools/dev and optional tests only
19+
- Do not modify engine core
20+
- Keep commit_comment.txt header-free
21+
- Package output to:
22+
<project folder>/tmp/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1 @@
1-
BUILD_PR_RULES_OF_ENGAGEMENT_STANDARDIZATION
2-
3-
- Standardized rules into single source of truth
4-
- Removed duplicate rule files
1+
docs: define dev console command-pack contracts, help behavior, and validation conventions

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
APPLY_PR_RULES_OF_ENGAGEMENT_STANDARDIZATION
1+
APPLY_PR_DEV_CONSOLE_COMMAND_PACKS

‎docs/dev/change_summary.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
change_summary.txt
5+
6+
Summary
7+
- Added PLAN PR for dev console command packs
8+
- Defined grouped command architecture for future console growth
9+
- Preserved docs-first workflow and commit_comment no-header exception

‎docs/dev/file_tree.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
file_tree.txt
5+
6+
docs/pr/PLAN_PR_DEV_CONSOLE_COMMAND_PACKS.md
7+
docs/dev/codex_commands.md
8+
docs/dev/commit_comment.txt
9+
docs/dev/change_summary.txt
10+
docs/dev/validation_checklist.txt
11+
docs/dev/file_tree.txt
12+
docs/dev/next_command.txt

‎docs/dev/reports/change_summary.txt‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ David Quesenberry
44
change_summary.txt
55

66
Summary
7-
- Added canonical `docs/dev/RULES_OF_ENGAGEMENT.md` as the single source of truth.
8-
- Consolidated rule/workflow guidance from legacy `RULES.txt` and `WORKFLOW.md`.
9-
- Removed duplicate rule files from active/archive locations.
10-
- Updated active docs references to point at `RULES_OF_ENGAGEMENT.md`.
7+
- Added docs-only BUILD PR contract for namespaced dev-console command packs.
8+
- Defined command registry and command-pack schema.
9+
- Defined help behavior for global, pack, and command-level discovery.
10+
- Defined normalized output contract and validation/error conventions.
11+
- Constrained future implementation scope to `tools/dev` and optional `tests/tools` only.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,10 @@ David Quesenberry
33
04/05/2026
44
file_tree.txt
55

6-
docs/dev/RULES_OF_ENGAGEMENT.md
7-
docs/dev/README.md
8-
docs/getting-started.md
9-
docs/dev/WORKFLOW_RULES.md (removed)
10-
docs/archive/dev-ops/RULES.txt (removed)
11-
docs/archive/dev-ops/WORKFLOW.md (removed)
12-
docs/dev/start_of_day/RULES_OF_ENGAGEMENT.md (removed)
6+
docs/pr/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md
7+
docs/dev/codex_commands.md
8+
docs/dev/commit_comment.txt
9+
docs/dev/next_command.txt
1310
docs/dev/reports/change_summary.txt
1411
docs/dev/reports/file_tree.txt
1512
docs/dev/reports/validation_checklist.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,22 @@ validation_checklist.txt
66
VALIDATION CHECKLIST
77

88
Workflow
9-
- Single rules source created at `docs/dev/RULES_OF_ENGAGEMENT.md`
10-
- Legacy `RULES.txt` and `WORKFLOW.md` consolidated
11-
- Duplicate rule docs removed
9+
- PLAN_PR source exists: `docs/pr/PLAN_PR_DEV_CONSOLE_COMMAND_PACKS.md`
10+
- BUILD_PR created as docs-only delta
11+
- No implementation/runtime code included
1212

13-
Safety
14-
- Docs-only changes
15-
- No runtime code changes
16-
- References updated from `WORKFLOW_RULES.md` to `RULES_OF_ENGAGEMENT.md`
13+
Contract Coverage
14+
- Command-pack registry shape defined
15+
- Namespaced command definition shape defined
16+
- Help behavior defined for `help`, `help <pack>`, `help <command>`
17+
- Output contract standardized
18+
- Validation/error conventions and codes defined
19+
20+
Scope Safety
21+
- Future implementation constrained to `tools/dev` and optional `tests/tools`
22+
- No engine core modifications required by contract
23+
- `docs/dev/commit_comment.txt` remains header-free
1724

1825
Packaging
19-
- Delta ZIP generated at `<project folder>/tmp/BUILD_PR_RULES_OF_ENGAGEMENT_STANDARDIZATION_delta.zip`
26+
- Delta ZIP output path set to:
27+
`<project folder>/tmp/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip`

‎docs/dev/validation_checklist.txt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
validation_checklist.txt
5+
6+
VALIDATION CHECKLIST
7+
8+
Workflow
9+
- PLAN_PR created
10+
- One PR per purpose
11+
- No implementation code in bundle
12+
13+
Header Rules
14+
- Header present in all new files except docs/dev/commit_comment.txt
15+
- commit_comment.txt contains no Toolbox Aid header
16+
17+
Plan Quality
18+
- Command pack structure defined
19+
- Registry model defined
20+
- Help behavior defined
21+
- Output contract defined
22+
- Validation conventions defined
23+
- Engine-safe boundary preserved

‎docs/pr/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md
5+
6+
# BUILD PR
7+
Dev Console Command Packs
8+
9+
## Source Of Truth
10+
- Plan input: `docs/pr/PLAN_PR_DEV_CONSOLE_COMMAND_PACKS.md`
11+
- Workflow: `PLAN_PR -> BUILD_PR -> APPLY_PR`
12+
- This BUILD is docs-only and defines implementation-ready contracts without shipping runtime code.
13+
14+
## Objective
15+
Define a namespaced command-pack model for the existing dev console so command registration, help output, validation, and output formatting are consistent and scalable.
16+
17+
## Scope
18+
- Define command-pack and command registry shape
19+
- Define built-in help behavior for pack and command discovery
20+
- Define output contract for command execution results
21+
- Define validation conventions and error surface
22+
- Keep future implementation scope limited to `tools/dev` and optional tests
23+
24+
## Out Of Scope
25+
- No engine core changes
26+
- No runtime refactor beyond command-registry adoption path
27+
- No autocomplete feature requirement in this slice
28+
- No multi-sample rollout in this slice
29+
30+
## Implementation Boundaries (Future Apply Scope)
31+
- Allowed implementation folders:
32+
- `tools/dev/`
33+
- optional `tests/tools/`
34+
- Not allowed:
35+
- `engine/`
36+
- runtime core rewrites
37+
- unrelated tools/samples/games
38+
39+
## Command Registry Shape
40+
Use a registry composed of command packs.
41+
42+
### Command Pack Contract
43+
- `packId`: string (namespace token, example: `scene`)
44+
- `label`: string (human-readable title)
45+
- `description`: string
46+
- `commands`: array of command definitions
47+
- `contextRequirements` (optional): array of required context keys
48+
49+
### Command Contract
50+
- `name`: full namespaced command, example `scene.info`
51+
- `summary`: short command description
52+
- `usage`: usage string
53+
- `arguments` (optional): argument spec array
54+
- `handler(context, args)`: execution handler
55+
- `outputHint` (optional): formatting hint (`text`, `table`, `json`)
56+
- `validate(args, context)` (optional): pre-execution validator
57+
58+
## Help Behavior Contract
59+
Support these forms:
60+
- `help`
61+
- lists command packs and basic usage
62+
- `help <pack>`
63+
- lists commands inside that pack
64+
- `help <full.command>`
65+
- shows command summary, usage, args, validation notes
66+
67+
Behavior rules:
68+
- Unknown pack/command returns structured error output (not silent fail)
69+
- Help output is stable and deterministic (sorted by pack then command name)
70+
71+
## Command Output Contract
72+
All command executions should normalize to:
73+
- `status`: `ready | failed`
74+
- `title`: string
75+
- `lines`: string array
76+
- `details` (optional): structured payload object
77+
- `code` (optional): machine-readable error/result code
78+
79+
Output conventions:
80+
- Success uses `status=ready`
81+
- Validation/lookup failures use `status=failed` with explicit `code`
82+
- Empty output should still return at least one user-facing line
83+
84+
## Validation Conventions
85+
Normalize these cases:
86+
- Unknown command
87+
- `code=COMMAND_NOT_FOUND`
88+
- Unknown pack in help
89+
- `code=COMMAND_PACK_NOT_FOUND`
90+
- Invalid arguments
91+
- `code=INVALID_COMMAND_ARGS`
92+
- Missing context dependencies
93+
- `code=MISSING_COMMAND_CONTEXT`
94+
- Handler failure
95+
- `code=COMMAND_EXECUTION_FAILED`
96+
97+
Validation behavior:
98+
- Reject invalid command execution before handler call when possible
99+
- Return structured non-silent failure with actionable message
100+
101+
## Suggested Pack Coverage
102+
- `scene.*`
103+
- `render.*`
104+
- `entity.*`
105+
- `debug.*`
106+
- `input.*`
107+
- `hotreload.*`
108+
- `validation.*`
109+
110+
## Future Candidate Files (Implementation Phase)
111+
- `tools/dev/commandPacks/sceneCommandPack.js`
112+
- `tools/dev/commandPacks/renderCommandPack.js`
113+
- `tools/dev/commandPacks/entityCommandPack.js`
114+
- `tools/dev/commandPacks/debugCommandPack.js`
115+
- `tools/dev/commandPacks/inputCommandPack.js`
116+
- `tools/dev/commandPacks/hotReloadCommandPack.js`
117+
- `tools/dev/commandPacks/validationCommandPack.js`
118+
- `tools/dev/devConsoleCommandRegistry.js`
119+
- `tools/dev/devConsoleIntegration.js`
120+
- Optional tests under `tests/tools/`
121+
122+
## Acceptance Criteria
123+
- Namespaced command pack model documented
124+
- Registry and command definition shape documented
125+
- Help behavior documented for global/pack/command modes
126+
- Output contract documented and standardized
127+
- Validation conventions documented with explicit error codes
128+
- Future scope constrained to `tools/dev` and optional tests
129+
- No engine-core change requirements introduced
130+
131+
## Manual Validation Checklist
132+
- Confirm pack and command schema is complete enough to implement directly
133+
- Confirm help behavior covers global, pack, and command views
134+
- Confirm output contract supports both human and structured tooling usage
135+
- Confirm validation conventions avoid silent failures
136+
- Confirm no implementation scope leaks outside `tools/dev` and optional tests
137+
138+
## Packaging
139+
Expected BUILD delta ZIP:
140+
- `<project folder>/tmp/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip`

0 commit comments

Comments
 (0)