GitHub & Workspace Workflow Standards

Normative standards governing repository structure, CI/CD, documentation topology, and contribution workflow across the alawein portfolio.

Workspace Model

Topology: Hub-and-Spoke.

The Hub (_pkos): Central repository for global standards, governance templates, and identity canon.
The Spokes: Individual project repositories (Morphism, BMJ, etc.) that consume hub templates but own local execution.

Repository Standards (The Golden Baseline)

Every repository in the workspace MUST maintain:

README.md — Entry point with standard structure (Overview, Setup, Usage, Governance).
SSOT.md — The normative source of truth for the project's identity and surfaces.
AGENTS.md — Governance binding for AI agents and session handoff protocols.

CI/CD & Quality Gates

Philosophy: "Green means healthy." No swallowed errors or || true hacks.
Rigor: Mandatory Lint, Type-Check, Test (Unit/E2E), and Build steps in every workflow.
Stack: Standardize on Node 22 (npm) and Python 3.10+ (uv/ruff).

Documentation Management — The Five Lanes Topology

All docs must live in one of these root directories:

| Lane | Purpose | |------|---------| | governance/ | Rules, Doctrine, AGENTS.md | | architecture/ | Specifications, technical reasoning, ADRs | | operations/ | Runbooks, deployment logs, maintenance | | reference/ | Schemas, API keys (placeholders), lookup tables | | about/ | Public-facing narrative, pitch decks, vision |

Contribution Workflow

Branching: Feature-based branches (feat/, fix/, chore/).
Commits: Conventional Commits enforced. Format: type(scope): subject.
Validation: Automated pre-commit or CI checks for structural consistency.

Provenance: Extracted from Downloads/Workspace_Tools/GITHUB_WORKFLOW_SSOT.md (last verified 2026-03-26). This content was not covered by db/projects/workspace-tools.md (which describes the tools monorepo) or any other existing record.