7 · Optional enhancements

TL;DR

Objective — surface three SHOULD-not-skip topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + CHANGELOG version management) and capture the operator’s decision on each — never silently drop them.

User part + done-when

👤 User part — these are decisions: the operator chooses which to adopt and records the call. The agent must present all three, never assume yes or no, and scaffold only what’s chosen.

Done when each topic was surfaced and its decision recorded — and, for anything adopted, the scaffold / standards / CHANGELOG.md actually exist.  ·  ⏱ ~20–40 min if adopted  ·  🔀 (👤 decisions, 🤖 scaffolding).

Background

These three topics are SHOULD, not skip-by-default. The agent must surface them and capture the operator’s decision — never silently drop them.

Topic	What it gives you	Adopt when
Project structure	A predictable Admin-Local/ home for the vault, docs, and versions	You want the full scaffold from day one (recommended)
Commit & doc standards	Searchable history + an auditable vendor seam	Team work, or you want disciplined history
Version management	SemVer + CHANGELOG.md distinct from the vendor’s line	You’ll ship updates over time (almost everyone)

Steps

1. Decide which topics to adopt

Present all three to the operator and record each choice in the project log before scaffolding anything.

Who does this

👤 User (the operator) decides adopt-or-not for each topic — this is a workflow preference, so the agent surfaces and records rather than assuming.

1. Surface the three topics and record the decisions.

   • ✅ Each of the three topics was presented, and its adopt/skip decision is written in the project log.

2. Scaffold the project structure (if adopted)

A consistent Admin-Local/ layout gives every later phase a known home for credentials, docs, and version snapshots.

1. Create the Admin-Local/ scaffold.

   mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
   mkdir -p Admin-Local/1-Project/{1-ProjectInfo,2-ProjectVault,3-ProjectTemplates}
   mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
   # Expected: the Admin-Local tree is created

   • ✅ Phases 3–11 now have a known home for credentials, docs, and versions.

2. Lock the vault so credentials can never be committed.

   printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-ProjectVault/.gitignore
   # Expected: the vault ignores everything except its .gitignore + README

   • ✅ Admin-Local/1-Project/2-ProjectVault/.gitignore ignores all but itself + README.

3. Seed the project records — a ProjectCard (domains, IPs, SSH aliases, port, repo URL) in 1-ProjectInfo/, and a CHANGELOG.md at the repo root. Fill the ProjectCard from the infrastructure created in Prerequisites.

   • ✅ A ProjectCard exists with this project’s real domains, IPs, SSH aliases, and repo URL.

3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. Never commit (already in .gitignore): .env / .env.* (except .env.example), vendor/, node_modules/, IDE settings. Always commit: composer.json + composer.lock, package.json + package-lock.json, config/*.php, database/migrations/*.php, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

Type	Format	Example
Author import	📦 T1 Setup-Author: …	📦 T1 Setup-Author: Import v10.4
Setup/config	🔧 T2 Setup-Config: …	🔧 T2 Setup-Config: Add GA tracking
App feature	🔨 T3 Add-Feature: …	🔨 T3 Add-Feature: Arabic support
Deploy	🚀 T4 Deploy-App: …	🚀 T4 Deploy-App: Deploy v1.5.1

Before any customization in this or later phases, know which mechanism to use — this is what prevents “modified vendor file” sprawl that blocks future updates:

Mechanism	Use when	Lives in
Vendor Customizations	Patching an existing vendor file	resources/vendor-customizations/
ZajModules	Adding new functionality (route, view, service)	packages/ZajModules/{Type}/{Cat}/{Name}/
_zaj migrations	Extending a vendor table schema	database/migrations/*_zaj.php

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → _zaj migration.

4. Adopt version management — SemVer + CHANGELOG (if adopted)

If you’ll ship updates (almost everyone), adopt semantic versioning and a CHANGELOG.md now so your versions stay distinct from the vendor’s author-vX.X.X line. vMAJOR.MINOR.PATCH — bump by the nature of the change:

Change	Bump	Example
Bug fix / security patch	PATCH (1.0.0 → 1.0.1)	Fixed login error
New feature, backward compatible	MINOR (1.0.0 → 1.1.0)	Added export
Breaking change	MAJOR (1.0.0 → 2.0.0)	Changed API responses

Keep CHANGELOG.md in Keep a Changelog form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set composer.json and package.json name/version/description, change license to proprietary, and keep package.json private: true.

Your first release is v1.0.0 — even if the vendor is v10.4

The author-vX.X.X tag tracks the vendor’s version. Your project’s first public release is always v1.0.0, created later (release finalization), not here. Annotated tags (git tag -a v1.0.0 -m "…") are recommended for releases.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Topics surfaced — each optional topic was presented and the operator’s choice recorded.
• 🤖 Scaffold (if adopted) — Admin-Local/ + gitignored vault exist.
• 🔀 Standards (if adopted) — commit format + Zaj customization strategy understood.
• 🔀 Versioning (if adopted) — CHANGELOG.md started and package metadata set.

→Next step

Phase 3 · Local development