pal-e-docs

Project Page Template

template-project-page Template

active template
Project

Project Page Template

A project houses kanbans together for the purpose of an overarching goal. The project page is the entry point — it defines the goal (Vision), the needs (User Stories), the system (Architecture), and the execution (Board). Tagged project-page,active.
See convention-kanban-over-plans for the foundational axioms.

Template

Section Order

  • Vision — the overarching goal (stable, rarely changes)
  • User Stories — index table linking to user-story notes. The needs the project serves. Stories are the kanban's reason for being.
  • Architecture — three architecture notes (domain, dataflow, deployment). The system that serves the needs. Architecture is the kanban's map.
  • Board — the primary kanban. Implements the stories through the architecture.
  • Status — what's true right now (updated after milestones)
  • Milestones — one-line links to milestone notes (lean, details in linked notes)
  • Repos — what code lives where (table)

Architecture Diagrams

Every project gets three architecture diagram notes (note_type: architecture). These are separate notes (not inline) to keep the project page lean and allow diagrams to evolve independently.
Diagram Slug pattern Mermaid type Answers
<strong>Domain Model</strong> <code>arch-domain-{project}</code> erDiagram What are the business entities and how do they relate?
<strong>Data Flow</strong> <code>arch-dataflow-{project}</code> sequenceDiagram How does information move through the system at runtime?
<strong>Deployment</strong> <code>arch-deployment-{project}</code> graph TB Where do services run and how do they connect?
Together these are three lenses on one system: the what, the when, and the where.

Naming Convention

Slug: project-[project-slug] (e.g., project-pal-e-services)
Tags: project-page,active
Project: the project it describes

Key Principles

Principle What it means
Project = goal + kanbans A project houses kanbans together for an overarching goal. Vision defines the goal. Stories and architecture give the kanban purpose. The board is the execution.
One primary board per project Permanent kanban, not time-boxed sprints. Decomposition boards exist for large tickets. All boards serve the same overarching goal.
Stories + Architecture = kanban anchors User stories define WHY (acceptance criteria, success metrics). Architecture defines WHAT/WHERE (the system map). Together they give the kanban its definition of done.
Project page = stable identity The project page is the entry point. It rarely changes. The board is the living execution view. Architecture diagrams evolve as the system grows.

What Changed (2026-04-12)

  • Added project definition. "A project houses kanbans together for the purpose of an overarching goal." Encoded as the opening statement and in Key Principles.
  • Clarified relationship between sections. Vision = goal. Stories = needs (WHY). Architecture = system (WHAT/WHERE). Board = execution (implements stories through architecture).
  • Clarified board scope. "One primary board per project, plus decomposition boards as needed." Previously said "one board per project" which contradicted template-board's fractal decomposition model.
  • Story keys must be slug-friendly. e.g. ai-assistant, roster-view — not numbered codes like WS-S5.

What Changed (2026-03-24)

  • Removed Plan section. Plans are obsolete — kanban boards are the decomposition tool. Architecture diagrams are the project anchor. Existing plan notes retained as historical reference.
  • Reordered sections: Vision, User Stories, Architecture, Board, Status, Milestones, Repos. Architecture promoted above Board to reflect its role as the stable project anchor.
  • Removed Inbox/Backlog section from template. Backlog is a board column, not a project page section.
  • Simplified Key Principles. Removed plan-centric principles (one plan per project, TODOs are transient).
  • convention-kanban-over-plans — foundational axioms (kanban purpose, project definition)
  • template-user-story — user story note format (the WHY)
  • template-architecture — architecture note format (the WHAT/WHERE)
  • template-board — decomposition boards for large tickets
  • template-ticket — board item conventions (traceability triangle)
  • sop-board-workflow — column semantics and flow rules
  • note-conventions — note_type and status definitions