The Kernel
The constitution of the PARA Workspace ecosystem. A set of immutable invariants and evolving heuristics that ensure predictability across all workspaces.
01. Foundational Principles
Repo ≠ Workspace
The repo contains governance (kernel, CLI, templates). It never contains user data.
Workspace = Runtime
Generated by `para init`, each workspace is a standalone instance where work happens.
Kernel = Constitution
Immutable rules that all workspaces follow. Changes require RFC + version bump.
02. Repository Structure
para-workspace/ ├── kernel/ # 🧠 Constitution │ ├── KERNEL.md # Master definition │ ├── invariants.md # 11 hard rules (MAJOR bump) │ ├── heuristics.md # 9 soft conventions │ └── schema/ # JSON strict validation ├── cli/ # 🔧 Compiler & Operations │ ├── para # Entry point (Bash 3.2+) │ └── commands/ # init, scaffold, migrate, etc. ├── templates/ # 📦 Scaffolding & Profiles │ ├── common/agent/ # Centralized rules & workflows │ └── profiles/ # dev, general, marketer, ceo └── docs/ # 📖 System Documentation
03. Workspace Structure
<your-workspace>/ ├── Projects/ # Goal-oriented tasks (active work) ├── Areas/ # Ongoing responsibilities (health, etc.) │ ├── Workspace/ # Master session logs & audits │ └── Learning/ # Shared knowledge base ├── Resources/ # Read-only references & tools ├── Archive/ # Cold storage for completed items ├── _inbox/ # Temporary landing zone ├── .agent/ # Governed library copies (Auto-synced) ├── .para/ # System state (Backups, Logs, Migrations) └── para # Local bootstrapper CLI
04. Kernel Invariants
I1 PARA directory structure is mandatory
I2 Hybrid 3-file task model (backlog = canonical, Hot Lane, /end sync)
I3 kebab-case project naming
I4 No active tasks = inactive project
I5 Areas contain no runtime tasks
I6 Archive is immutable cold storage
I7 Seeds are raw ideas, not tasks
I8 No loose files at workspace root
I9 Resources are read-only references
I10 Repo ↔ Workspace separation
I11 Workflow language compliance (preferences.language)
05. Kernel Heuristics
H1 Naming conventions (kebab-case, PascalCase)
H2 Context loading priority
H3 Semantic versioning with approval levels
H4 Standard project directory structure
H5 Beads lifecycle (Idea → Messy → Graduate)
H6 VCS & Git boundaries
H7 Cross-project references via Resources
H8 Workflow kernel compatibility
H9 Governed libraries require catalog.yml with kernel_min