Skip to content

Commit 3362521

Browse files
ToolboxAidToolboxAid
authored
Merge pull request #66 from ToolboxAid/pr/26172-OWNER-017-project-instructions-bootstrap-install
PR_26172_OWNER_017-project-instructions-bootstrap-install
2 parents 4cd3e36 + 08ef154 commit 3362521

20 files changed

Lines changed: 1686 additions & 195 deletions

‎docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Project Instructions Operating System
2+
3+
Read `README.txt` first.
4+
5+
This file is the root index for the append-first Project Instructions operating system under `docs_build/dev/ProjectInstructions/`.
6+
7+
## Purpose
8+
9+
The Project Instructions operating system provides additive governance for:
10+
11+
- backlog ownership
12+
- team assignments
13+
- multi-team branch and scope rules
14+
- Build Path status synchronization
15+
- tile overlay status behavior
16+
- deprecation workflow
17+
- archive and history preservation
18+
19+
## Preservation
20+
21+
Existing Project Instructions remain preserved in their current locations. This operating system adds structure without deleting or rewriting existing documentation.
22+
23+
## Folders
24+
25+
- `addendums/` contains additive governance rules.
26+
- `backlog/` contains the central backlog file, `BACKLOG_MASTER.md`.
27+
- `team_assignments/` contains current team assignment records.
28+
- `deprecation/` contains deprecation workflow documentation.
29+
- `archive/` contains retained reference material.
30+
- `archive/history/` contains timestamped history snapshots.
31+
32+
## Merge Control
33+
34+
No PR in this operating system is merged without explicit owner approval.
35+
36+
## OWNER Governance
37+
38+
OWNER override wording:
39+
40+
`OWNER override approved: <reason>`
41+
42+
OWNER follows the same safety rules:
43+
- One active OWNER branch at a time.
44+
- One active OWNER assignment at a time.
45+
- OWNER may override team locks, but may not silently delete, rewrite, or remove protected instructions.
46+
- OWNER override must be explicitly documented.

‎docs_build/dev/ProjectInstructions/README.txt‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Read this file first.
2+
3+
Folder purpose:
4+
This folder is the append-first Project Instructions operating system for Game Foundry Studio. It organizes active governance, backlog, team assignment, deprecation, and history material without deleting or rewriting the existing Project Instructions files elsewhere in the repository.
5+
6+
Preservation rules:
7+
Preserve all existing documentation. Add new files or append explicit references unless the owner explicitly approves deletion or rewrite. When a conflict appears, stop, explain the conflict, and request owner approval before changing existing instruction text.
8+
9+
Backlog workflow:
10+
Backlog work is tracked under backlog/. BACKLOG_MASTER.md is the planned source for backlog item status, notes, and references. Backlog item text is treated as immutable once created; status and notes may change under the governance addendums.
11+
12+
Team assignment workflow:
13+
Team assignments are tracked under team_assignments/. A team pulls work from BACKLOG_MASTER.md, marks the item building when assigned, and records the active assignment under the owning team. Teams work only on assigned items unless an OWNER override explicitly changes the assignment.
14+
15+
No direct commits to main:
16+
Do not commit directly to main unless the owner explicitly instructs that exception. Normal work must use PR branches, draft PRs, validation evidence, and owner-controlled merge approval.
17+
18+
OWNER override rule:
19+
An OWNER override must use this wording:
20+
OWNER override approved: <reason>
21+
22+
The override must explain why normal team, branch, assignment, or backlog routing is being changed.
23+
24+
History snapshot rule:
25+
When a governance or instruction state needs a history snapshot, add a new file under archive/history/ using:
26+
CCYYMMDD_HHMMSS.md
27+
28+
Do not rewrite history snapshots after creation unless the owner explicitly approves.

‎docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# TEAM_START_COMMANDS
2+
3+
## Start Team Alpha
4+
5+
Ready-to-copy command:
6+
7+
```text
8+
OWNER override approved: Start Team Alpha from the ProjectInstructions release gate.
9+
10+
Read docs_build/dev/ProjectInstructions/README.txt first.
11+
Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md.
12+
Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.
13+
14+
Pull one [ ] item for Team Alpha from BACKLOG_MASTER.md.
15+
Stop if Team Alpha already has an active branch.
16+
Stop if Team Alpha already has an active assignment.
17+
Stop if no [ ] Team Alpha backlog item is available.
18+
19+
Change the selected backlog item from [ ] to [.].
20+
Add the selected assignment under Team Alpha in TEAM_ASSIGNMENTS.md.
21+
Create one Team Alpha branch for the selected assignment.
22+
Work only that assignment.
23+
```
24+
25+
## Start Team Beta
26+
27+
Ready-to-copy command:
28+
29+
```text
30+
OWNER override approved: Start Team Beta from the ProjectInstructions release gate.
31+
32+
Read docs_build/dev/ProjectInstructions/README.txt first.
33+
Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md.
34+
Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.
35+
36+
Pull one [ ] item for Team Beta from BACKLOG_MASTER.md.
37+
Stop if Team Beta already has an active branch.
38+
Stop if Team Beta already has an active assignment.
39+
Stop if no [ ] Team Beta backlog item is available.
40+
41+
Change the selected backlog item from [ ] to [.].
42+
Add the selected assignment under Team Beta in TEAM_ASSIGNMENTS.md.
43+
Create one Team Beta branch for the selected assignment.
44+
Work only that assignment.
45+
```
46+
47+
## Start Team Gamma
48+
49+
Ready-to-copy command:
50+
51+
```text
52+
OWNER override approved: Start Team Gamma from the ProjectInstructions release gate.
53+
54+
Read docs_build/dev/ProjectInstructions/README.txt first.
55+
Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md.
56+
Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.
57+
58+
Pull one [ ] item for Team Gamma from BACKLOG_MASTER.md.
59+
Stop if Team Gamma already has an active branch.
60+
Stop if Team Gamma already has an active assignment.
61+
Stop if no [ ] Team Gamma backlog item is available.
62+
63+
Change the selected backlog item from [ ] to [.].
64+
Add the selected assignment under Team Gamma in TEAM_ASSIGNMENTS.md.
65+
Create one Team Gamma branch for the selected assignment.
66+
Work only that assignment.
67+
```
68+
69+
## Day Work / EOD Merge Reminder
70+
71+
Ready-to-copy reminder:
72+
73+
```text
74+
Commit/push during the day is allowed only on assigned team/OWNER/PR branches.
75+
76+
Merge to main is EOD-only and owner-approved, unless the owner explicitly says:
77+
"Merge this PR now."
78+
79+
Do not treat sequential PR completion as merge approval.
80+
```

‎docs_build/dev/ProjectInstructions/addendums/build_path_sync.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Build Path Status Sync Governance
2+
3+
## Purpose
4+
5+
This addendum keeps the central backlog and Toolbox Build Path aligned.
6+
7+
## Source Of Truth
8+
9+
`docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` is the source of truth for tool status.
10+
11+
## Build Path Sync
12+
13+
`toolbox/index.html` Build Path tiles must match tool status from `BACKLOG_MASTER.md`.
14+
15+
When a central backlog tool status changes, update the matching Build Path tile.
16+
17+
Status and Build Path changes should be in the same PR when practical.
18+
19+
## Phase Percentages
20+
21+
Phase percentages are calculated from tools in each phase.
22+
23+
Rules:
24+
- completed tools count as complete
25+
- planned, wireframe, building, and blocked tools remain in the denominator
26+
- deprecated tools are excluded from the denominator
27+
- phase percentage must be recalculated when a tool status changes
28+
29+
## Validation
30+
31+
PRs that change backlog status or Build Path status must document:
32+
- backlog item changed
33+
- matching Build Path tile changed
34+
- phase percentage before and after
35+
- skipped sync, if any, with reason

‎docs_build/dev/ProjectInstructions/addendums/deprecation.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Deprecation Governance
2+
3+
## Purpose
4+
5+
This addendum defines how Project Instructions backlog and Build Path items become deprecated while staying traceable.
6+
7+
## Deprecation Group
8+
9+
Deprecation is its own group and must not be hidden inside normal completion work.
10+
11+
## Traceability
12+
13+
Deprecated items must preserve:
14+
- original item text
15+
- deprecated status
16+
- owner approval reference
17+
- replacement path, if any
18+
- archive/removal decision, if any
19+
20+
## Owner Approval
21+
22+
Owner approval is required before archive or removal.
23+
24+
No team may remove a deprecated item solely because it is deprecated.
25+
26+
## Build Path Display
27+
28+
Deprecated Build Path items use red overlay if visible.
29+
30+
Deprecated items do not count against current MVP completion.
31+
32+
If a deprecated item remains visible, it must communicate Deprecated status to creators without relying on color alone.

‎docs_build/dev/ProjectInstructions/addendums/multi_team.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Multi-Team Codex Execution Governance
2+
3+
## All-Team Preferred Codex Execution Method
4+
5+
Preferred execution model:
6+
Single Codex session with multiple sequential PRs.
7+
8+
Applies to:
9+
- Team Alfa through Team Zulu
10+
- Team OWNER
11+
12+
Purpose:
13+
Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped.
14+
15+
Rules:
16+
- One Codex session may execute multiple sequential PRs.
17+
- Each PR must still have one clear purpose.
18+
- Each PR must create or use its own approved branch.
19+
- Each PR may be committed and pushed during active work.
20+
- Each PR may be opened as a draft PR during active work.
21+
- Do not commit directly to main.
22+
- Do not merge to main during active work unless the owner explicitly says: "Merge this PR now."
23+
- If later PRs depend on earlier unmerged PRs, Codex must either:
24+
- stack the dependent PRs, or
25+
- stop and request owner approval for the dependency model.
26+
- Codex should reduce chit-chat by planning the full sequence before starting.
27+
- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion.
28+
29+
## Day Work / EOD Merge Rule
30+
31+
During active work:
32+
- Work happens on assigned team branches, OWNER branches, or scoped PR branches.
33+
- Commits are allowed only on assigned non-main branches.
34+
- Pushes are allowed and expected.
35+
- Draft PRs are allowed and expected.
36+
- Direct commits to main are prohibited.
37+
- Merges to main are prohibited unless explicitly approved by the owner.
38+
39+
At end of day:
40+
- Owner reviews ready PRs.
41+
- Owner explicitly approves which PRs merge.
42+
- Only owner-approved PRs may merge to main.
43+
- After merge, return to main and pull latest main.
44+
- Do not treat sequential PR completion as merge approval.
45+
46+
Commit/push during the day is allowed only on assigned team/OWNER/PR branches.
47+
48+
Merge to main is EOD-only and owner-approved, unless the owner explicitly says:
49+
"Merge this PR now."
50+
51+
## Conflict Note
52+
53+
Existing ProjectInstructions wording that appears to require immediate or automatic merge remains preserved for traceability.
54+
55+
This addendum clarifies that merge to `main` remains owner-controlled. If a workflow rule appears to conflict with this addendum, stop and request explicit owner approval before merging.

‎docs_build/dev/ProjectInstructions/addendums/preservation.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Preservation And Archive Governance
2+
3+
## Purpose
4+
5+
This addendum protects Project Instructions material from accidental deletion, rewrite, or drift.
6+
7+
## Append-First Documentation
8+
9+
Project Instructions documentation is append-first.
10+
11+
Allowed default actions:
12+
- add new files
13+
- append dated notes
14+
- append references
15+
- add new governance addendums
16+
- add archive snapshots
17+
18+
## Owner Approval Required
19+
20+
Do not delete Project Instructions material unless the owner explicitly approves deletion.
21+
22+
Do not rewrite Project Instructions material unless the owner explicitly approves rewrite.
23+
24+
If a requested change conflicts with existing Project Instructions, stop before editing. Explain:
25+
- the conflicting files
26+
- the conflicting rule text
27+
- the requested change
28+
- the recommended action
29+
30+
Then request owner approval.
31+
32+
## Archive Instead Of Delete
33+
34+
When material is no longer active, archive it instead of deleting it. Archive entries must preserve enough context to explain why the material moved out of active use.
35+
36+
## History Snapshots
37+
38+
History snapshots go to:
39+
40+
`docs_build/dev/ProjectInstructions/archive/history/CCYYMMDD_HHMMSS.md`
41+
42+
Use 24-hour local time for `HHMMSS` unless the owner specifies another time basis.

‎docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Team Release Readiness Gate
2+
3+
## Purpose
4+
5+
This gate prevents Team Alpha, Team Beta, Team Gamma, or Team OWNER from starting regular assigned work before the ProjectInstructions operating system is ready.
6+
7+
## Release Rule
8+
9+
Teams may start only when all of the following are true:
10+
11+
- `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` exists and is populated.
12+
- `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md` exists.
13+
- OWNER governance exists.
14+
- One-active-branch-per-team rule exists.
15+
- No-direct-main rule exists.
16+
- Out-of-scope stop rule exists.
17+
- Build Path sync rule exists.
18+
19+
## Gate Outcome
20+
21+
If every requirement is true, team start commands may be issued.
22+
23+
If any requirement is missing, stop and report:
24+
- missing requirement
25+
- expected file or rule
26+
- current branch
27+
- recommended owner action
28+
29+
## No Silent Starts
30+
31+
Teams must not infer readiness from an incomplete stack. Readiness must be documented before team work begins.

‎docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Build Path Tile Overlay Status Governance
2+
3+
## Purpose
4+
5+
This addendum defines visual overlay status rules for Build Path tiles.
6+
7+
## Overlay Mapping
8+
9+
| Backlog Status | Meaning | Tile Overlay |
10+
| --- | --- | --- |
11+
| `[ ]` Planned | Planned | black overlay 70% |
12+
| `[?]` Wireframe | Wireframe | black overlay 80% |
13+
| `[.]` Building | Building | black overlay 90% |
14+
| `[x]` Complete | Complete | 100% transparent / no visible overlay |
15+
| `[!]` Blocked | Blocked | yellow overlay 80% |
16+
| `[-]` Deprecated | Deprecated | red overlay 80% |
17+
18+
## Completion Denominator
19+
20+
Blocked items remain in the completion denominator.
21+
22+
Deprecated items are excluded from the completion denominator.
23+
24+
## Badge Text
25+
26+
Blocked and Deprecated tiles must show badge text.
27+
28+
Badge text must be visible enough for a creator to understand why the tile is blocked or deprecated without relying on color alone.
29+
30+
## Validation
31+
32+
PRs that change tile overlay behavior must document:
33+
- status mapping affected
34+
- badge text affected
35+
- phase percentage denominator effect
36+
- skipped UI validation, if any, with reason

0 commit comments

Comments
 (0)