Separate Principles, Practices, and Philosophy from operational conventions in Ways of Working

[MariusStorhaug]

Section 1 — Context and Request

Context

Issue #38 consolidated all universal conventions into the new top-level Ways of Working chapter. That move achieved its goal — shared norms are no longer buried under "Agents". But the chapter now mixes two layers that have different audiences, different cadence, and different reasons to change:

• Foundations — the why and how we think. Evergreen beliefs, product mindset, and engineering philosophy. They change rarely and are read to understand, not to look something up.
  • Principles.md — vision/mission, product mindset, cross-platform, AI-first, least-privilege.
  • development-practices.md — how the team thinks, plans, builds, ships, improves.
  • continuous-x-and-continuous-ai.md — Continuous X practices, Continuous AI, DevOps Dojo.
  • devops-reference.md — DevOps principles, practices, and reading list.
• Operational conventions — the how we do specific things. Procedural rules consulted mid-task. They are updated often and read to look something up.
  • Issue-Format.md, Issue-Hierarchy.md, PR-Format.md, Commit-Conventions.md, Review-Etiquette.md, Readme-Driven-Context.md, Workflow.md, Goal-Setting.md, Git-Worktrees.md.

A contributor (or agent) trying to answer "how do I format a PR" currently scrolls past pages of philosophy; someone trying to absorb the mindset scrolls past label tables. The flat chapter index lists both layers side by side with no signal about which is foundational reading and which is a quick-reference convention.

Request

Filter the foundational pages — Principles, Practices, and Philosophy — out of the operational conventions so the two layers are clearly separated within the documentation. The foundational set sits together as evergreen "why we work this way" material; the operational conventions remain the procedural quick-reference contributors and agents consult during work.

Page	Layer	Disposition
Principles.md	Foundations (Principles)	Filter out into foundations group
development-practices.md	Foundations (Practices)	Filter out into foundations group
continuous-x-and-continuous-ai.md	Foundations (Philosophy)	Filter out into foundations group
devops-reference.md	Foundations (Philosophy)	Filter out into foundations group
Issue-Format.md, Issue-Hierarchy.md, PR-Format.md, Commit-Conventions.md, Review-Etiquette.md, Readme-Driven-Context.md	Operational conventions	Stay
Workflow.md, Goal-Setting.md	Process / planning	Stay (see open decision)
Git-Worktrees.md	Tooling	Stay

Acceptance criteria

• The foundational pages (Principles, Practices, Philosophy) are grouped together and visually/structurally distinct from the operational conventions.
• No content is lost or rewritten — this is a relocation and regrouping, not an edit.
• The Ways-of-Working/index.md clearly distinguishes the two layers, pointing readers to foundations for the why and conventions for the how.
• All internal cross-links to the moved pages are updated; the site builds with no broken links.
• Navigation orders foundations before, or clearly apart from, the operational conventions.

---

Section 2 — Technical Decisions

Grouping target. Open: Two viable shapes — (a) a sub-section/group within Ways of Working (e.g. a Foundations/ folder with the four pages plus an index.md), or (b) a new top-level chapter dedicated to principles and philosophy. Recommendation: option (a), a Foundations/ sub-group under Ways of Working. It keeps all "ways of working" under one chapter while separating the evergreen layer from the procedural one, and avoids fragmenting the nav the way #38 just consolidated it. To be resolved before the implementation plan is finalized.

Group name. Open: Candidates — Foundations, Principles & Philosophy, Mindset. Recommendation: Foundations — neutral, covers principles + practices + philosophy without implying a methodology.

Membership of Workflow.md and Goal-Setting.md. Open: These straddle the line (planning philosophy vs. process). Default: leave them as operational/process pages and move only the four clearly-foundational documents. Revisit if they read as more philosophical than procedural.

Move vs. copy. Move the files (git mv). Single source of truth; the existing relative links are updated to the new location rather than duplicated. Mirrors the decision in #38.

Scope of editing. Relocation and regrouping only — no content rewrite. The index.md gains a short framing of the two layers. Deeper content edits, if any, are a separate follow-up.

Navigation config. Update the Zensical navigation (src/zensical.toml) so the foundations group is ordered ahead of the operational conventions.

---

Section 3 — Implementation Plan

Restructure

• Decide the grouping target and name (resolve the open decisions in Section 2).
• Create the foundations group index.md introducing the layer (what it is, who it is for).
• Move Principles.md into the foundations group.
• Move development-practices.md into the foundations group.
• Move continuous-x-and-continuous-ai.md into the foundations group.
• Move devops-reference.md into the foundations group.

Wiring

• Update Ways-of-Working/index.md to frame the two layers and link the foundations group.
• Audit and fix all internal cross-links to the four moved pages across src/docs/.
• Update the navigation in src/zensical.toml for ordering.

Verification

• Build the site and confirm no broken links.

---

Follow-up to #38.