🌌 PARA Workspace is a governed, open-source standard that defines how humans and AI agents organize knowledge and collaborate on projects. It ships as a repo containing a kernel (constitution), CLI tools, and templates — which generates workspaces where you actually work.
Copy the command below to clone the repository to your machine.
The Governed Workspace Standard for AI Agents
PARA Workspace is a governed, open-source standard that defines how humans and AI agents organize knowledge and collaborate on projects. It ships as a repo containing a kernel (constitution), CLI tools, and templates — which generates workspaces where you actually work. The kernel enforces 10 invariants and 9 heuristics so every workspace is predictable, auditable, and agent-friendly.
para init, each workspace is a standalone instance where you and your agent work.Repo (Constitution + Compiler)
↓ para init
Workspace (Operating System Runtime)
↓ agent attach
Agent (Execution Environment)
para-workspace/
├── .github/ # 🤖 CI/CD — validate-pr.yml, CODEOWNERS
├── rfcs/ # 📝 RFC Process — TEMPLATE.md, status in header
├── kernel/ # 🧠 Constitution
│ ├── KERNEL.md
│ ├── invariants.md # 10 hard rules (MAJOR bump)
│ ├── heuristics.md # 9 soft conventions
│ ├── schema/ # workspace, project, backlog, catalog schemas
│ └── examples/ # valid/ + invalid/ compliance vectors
├── cli/ # 🔧 Compiler
│ ├── para # Entry point (Bash 3.2+ compatible)
│ ├── lib/ # logger.sh, validator.sh, rollback.sh, fs.sh
│ └── commands/ # init, scaffold, status, migrate, archive, install, update
├── templates/ # 📦 Scaffolding & Governed Libraries
│ ├── common/agent/ # Centralized workflows/, rules/, skills/ + catalog.yml
│ │ └── projects/ # .project.yml template
│ └── profiles/ # dev, general, marketer, ceo presets
├── tests/ # 🧪 kernel/ + cli/ integration tests
├── docs/ # 📖 Documentation
│ ├── architecture/ # Architecture: overview, kernel, ecosystem
│ ├── guides/ # How-to: development, planning, meta-project
│ ├── reference/ # Lookup: CLI, workflows, project-rules
│ ├── rules/ # Individual rule documentation (10 files)
│ ├── changelog/ # Version history
│ └── workflows/ # Individual workflow docs (22 files)
├── CONTRIBUTING.md
├── VERSIONING.md
├── CHANGELOG.md
└── VERSION
para init)<your-workspace>/
├── Projects/ # Goal-oriented tasks
│ ├── my-app/ # Standard project (type: standard)
│ │ ├── repo/ # Source code (git repo)
│ │ ├── artifacts/ # Plans, tasks, decisions
│ │ ├── sessions/ # Session logs
│ │ ├── docs/ # Project documentation
│ │ └── project.md # Project contract
│ └── my-ecosystem/ # Ecosystem project (type: ecosystem) — v1.6.0+
│ ├── artifacts/ # Cross-project plans & backlog
│ ├── sessions/ # Session logs
│ ├── docs/ # Strategy & shared docs
│ └── project.md # satellites: [app, api, ...], NO repo/
├── Areas/ # Ongoing responsibilities (e.g., health, finance)
│ ├── Workspace/ # Master session log, audits, SYNC queue
│ └── Learning/ # Shared knowledge (from /learn)
├── Resources/ # Reference material & tools
│ ├── ai-agents/ # Kernel snapshot + governed library snapshots
│ └── references/ # The original PARA repository (read-only)
├── Archive/ # Cold storage for completed items
├── _inbox/ # Temporary landing zone for external downloads
├── .agent/ # Governed library copies (Auto-synced)
│ ├── rules.md # Workspace Rules Trigger Index (always loaded, with priority)
│ ├── rules/ # Active agent rules (.md)
│ ├── skills/ # Active agent skills (.md, /scripts)
│ └── workflows/ # Active agent workflows (.md)
├── .para/ # System state (DO NOT EDIT)
│ ├── archive/ # Smart Archive vault for deprecated files
│ ├── migrations/ # Migration execution logs
│ ├── backups/ # Date-stamped workflow & project backups
│ └── audit.log # Action history
├── para # Bootstrapper CLI
└── .para-workspace.yml # Workspace root metadata config
| Platform | Integration Point | Status | Notes |
|---|---|---|---|
| Google Antigravity | .agent/ (skills, workflows) |
✅ Verified | Designed and tested for this platform |
| Claude Code | CLAUDE.md + .agent/ |
⚪ Untested | May read .agent/rules/ directly — needs validation |
| Cursor | .cursor/rules/ |
⚪ Untested | Theory: copy rules to .cursor/rules/ |
| VS Code + Copilot | .github/copilot-instructions |
⚪ Untested | Theory: instructions only, no auto-trigger |
Bash (Linux / macOS / Windows Git Bash / WSL):
# Clone repo into the correct location
mkdir -p Resources/references
git clone https://github.com/pageel/para-workspace.git Resources/references/para-workspace
# Set executable permissions
chmod +x Resources/references/para-workspace/cli/para
chmod +x Resources/references/para-workspace/cli/commands/*.sh
# Initialize your workspace with a profile
./Resources/references/para-workspace/cli/para init --profile=dev --lang=en
PowerShell (alternative for Windows):
mkdir -Force Resources\references
git clone https://github.com/pageel/para-workspace.git Resources\references\para-workspace
# Then open Git Bash or WSL at workspace root:
./Resources/references/para-workspace/cli/para init --profile=dev --lang=en
./para status
# ✅ If you see a health report → installation successful
What just happened?
- The repo lives at
Resources/references/para-workspace/— it's a read-only reference source, not a user project.chmod +xensures all CLI scripts are executable (required on Linux/macOS).para initcreates the full PARA directory structure, runsinstall.shautomatically to sync kernel, workflows, governance rules, and generates a./parawrapper.- You can now use
./parafrom your workspace root for all commands.
# Pull latest from GitHub and re-sync workspace
./para update
# Preview changes before applying
./para update --dry-run
This will git pull the repo, run version-gated migrations, and re-sync all governed libraries. Existing user-customized files are backed up to .bak before overwriting (Smart Sync). If the install fails mid-operation, all changes are automatically rolled back.
What happens during update:
git pull fetches latest code (self-restarts if scripts changed)migrate.sh runs version-gated migration steps (only what's needed)install.sh syncs kernel, workflows, rules, skills to workspace (with atomic rollback).para/audit.log| Problem | Solution |
|---|---|
| macOS: permission denied | Run chmod +x on CLI scripts (Step 3 above) |
| Windows: file lock on update | See Windows Recovery below |
| Stale workspace (v1.3.x) | Use Manual Clean Slate |
If para update fails on Windows due to NTFS file locking:
cd Resources\references\para-workspace
git checkout -- .
git pull origin main
cd ..\..\..
.\para install
| Profile | Description | Best For |
|---|---|---|
general |
Minimal PARA structure | Personal PKM |
dev |
Technical Areas + AI tooling | Software developers |
marketer |
Campaign & customer Areas | Marketing professionals |
ceo |
Strategy & organizational oversight | Founders & leadership |
para init DoesProjects/, Areas/, Resources/, Archive/, and _inbox/install.sh automatically, which:catalog.yml into .agent/workflows/catalog.yml into .agent/rules/.agent/rules.md (trigger index).agent/skills/ (if profile includes them)./para wrapper at workspace root.bak.para-workspace.yml with kernel version tracking.para/ state (audit.log, migrations/, backups/) for full auditabilityThe Kernel is the constitution of PARA Workspace — the rules that all workspaces must follow.
| # | Rule |
|---|---|
| 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 |
| # | Guideline |
|---|---|
| H1 | Naming conventions (kebab-case, PascalCase) |
| H2 | Context loading priority |
| H3 | Semantic versioning with approval levels |
| H4 | Standard project directory structure |
| H5 | Beads lifecycle |
| H6 | VCS & Git boundaries |
| H7 | Cross-project references + Ecosystem (v1.6.0) |
| H8 | Workflow kernel compatibility |
| H9 | Governed libraries require catalog.yml with kernel_min |
| File | Schema | Enforced By |
|---|---|---|
.para-workspace.yml |
workspace.schema.json |
para init, para status |
Projects/*/.project.yml |
project.schema.json |
para scaffold, para review |
artifacts/tasks/backlog.md |
backlog.schema.json |
para verify |
*/catalog.yml |
catalog.schema.json |
para install, para update |
# Core Commands
para init [--profile] [--lang] # Create workspace
para status [--json] # System health
para update # Auto-update & migrate
para scaffold <type> <name> # Create structured paths
para install [--force] # Sync governed libraries
para archive <type> <name> # Graduation review
para migrate [--from] [--to] # Workspace migration
# Configuration
para config [key] [value] # Manage workspace settings
# Agent Capabilities
@[/para-workflow] list # Manage workflows
@[/para-rule] list # Manage rules
Platform Support: Linux, macOS (Bash 3.2+), Windows (Git Bash / WSL).
| Command | Description |
|---|---|
/backlog |
Manage project tasks via canonical backlog.md |
/backup |
Backup workflows, rules, config, and project data |
/brainstorm |
Collaborative ideation with structured output |
/config |
Manage workspace configuration |
/end |
Close session with PARA classification + automated cleanup |
/inbox |
Categorize files from _inbox/ into PARA |
/install |
Intelligent installer (handles updates/merges) |
/learn |
Capture lessons into Areas/Learning |
/merge |
Semantic merge for workflow conflicts |
/new-project |
Initialize new project with scaffolding |
/open |
Start session with context + plan phase loading |
/para |
Master controller for workspace management |
/docs |
Generate, review, and publish technical documentation |
/para-audit |
Macro Assessor for tracking workspace structural drift |
/para-rule |
Manage, install, and standardize agent rules |
/para-workflow |
Manage, install, and standardize agent workflows |
/plan |
Create, review, and update implementation plans |
/push |
Fast commit and push to GitHub |
/release |
Pre-release quality gate |
/retro |
Project retrospective before archiving |
/update |
Agent-guided safe workspace update with error recovery |
/verify |
Verify task completion with walkthroughs |
Rules govern agent behavior, security, and compliance. Loaded on-demand via a Two-Tier trigger index (~200 tokens). See Rules & Context Loading for the loading mechanism.
| Rule | Description | Priority |
|---|---|---|
governance |
Kernel invariants, scope containment, safety guardrails | 🔴 Critical |
vcs |
Git safety: commit, branch, merge, PR, secrets | 🔴 Critical |
hybrid-3-file-integrity |
6 constraints (C1–C6) for task management | 🟡 Important |
agent-behavior |
Communication, language, Context Recovery (v1.5.4) | 🟡 Important |
context-rules |
Loading order, isolation, Two-Tier trigger | 🟡 Important |
para-discipline |
PARA architecture compliance, 7 rules | 🟡 Important |
artifact-standard |
Plans, walkthroughs, persistent mirroring | 🟢 Standard |
naming |
kebab-case, PascalCase, camelCase conventions | 🟢 Standard |
versioning |
SemVer, autonomy levels, multi-location sync | 🟢 Standard |
exports-data |
Data export: _inbox/, UTF-8 BOM, naming |
🟢 Standard |
Rules aren't dumped into context all at once. PARA Workspace uses a progressive disclosure architecture that loads rules on-demand, saving ~90% of token budget while maintaining full compliance.
┌─────────────────────────────────────────────────────────────┐
│ /open starts session │
│ │
│ Step 2.5a: ALWAYS read workspace rules index │
│ ┌───────────────────────────────────────────────────┐ │
│ │ .agent/rules.md (~20 lines, ~200 tokens) │ │
│ │ ┌────────────┬──────────────────┬─────┐ │ │
│ │ │ governance │ Touching kernel/ │ 🔴 │ │ │
│ │ │ vcs │ Git operations │ 🔴 │ │ │
│ │ │ hybrid-3 │ tasks/ files │ 🟡 │ │ │
│ │ │ naming │ Creating files │ 🟢 │ │ │
│ │ │ ... │ ... │ │ │ │
│ │ └────────────┴──────────────────┴─────┘ │ │
│ │ Agent memorizes triggers → loads rules ON DEMAND │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ Step 2.5b: CONDITIONALLY read project rules index │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Projects/<name>/.agent/rules.md (~5-10 lines) │ │
│ │ Only if project.md has: has_rules: true │ │
│ │ Adds project-specific triggers on top of global │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ 💡 Total cost: ~250 tokens (vs ~2000 if all rules loaded) │
└─────────────────────────────────────────────────────────────┘
After a long conversation, AI agents lose context (truncation). PARA Workspace has 4 independent layers to ensure rules survive:
Layer What Where Survives
───── ───────────────────────── ───────────────────────────── ────────
1 Rule file instructions agent-behavior.md §4 ⚠️ Lost after truncation
2 Safety block in output /open Step 8 report ✅ In checkpoint summary
3 Workflow pre-flight Step 0: re-read rules.md ✅ Fresh from disk
4 File guard headers <!-- ⚠️ ... --> in file ✅ Inline in target file
Layer 4 supports 4 guard types: TASK (C1-C3), KERNEL (I9), GOVERNED (rules), WORKSPACE (session/sync).
Scenario: Agent forgets rules after truncation
Long conversation → Context window truncated → Agent loses rules
│
┌─────────────────────────┤
▼ ▼
Agent runs /push Agent edits done.md
│ │
Layer 3 catches: Layer 4 catches:
Step 0 re-reads <!-- ⚠️ APPEND-ONLY -->
.agent/rules.md reminds C2 constraint
│ │
VCS rules loaded Agent obeys guard
→ safe commit → append only ✅
📖 Full architecture: Context Recovery · Defense-in-Depth · Rule Layers
PARA Workspace uses a proprietary Hybrid 3-File Architecture (v1.5.3: Hot Lane) to solve the AI Agent "Context Window vs. Amnesia" problem.
Instead of forcing the agent to read one massive backlog file every time it opens a project (which wastes tokens and causes hallucination), tasks are distributed across three highly specialized files:
artifacts/tasks/
├── backlog.md # 📌 CANONICAL — Operational Authority. All strategic tasks live here.
├── sprint-current.md # 🔥 HOT LANE — Agent-writable buffer for ad-hoc quick tasks.
└── done.md # ✅ ARCHIVE — Append-only log with origin tags (#backlog / #session).
/open reads only the Summary table (~10 lines) + top active items via grep. Never the full file.- [ ] Fix CSS) to sprint-current.md and ticks [x] when done. Strategic tasks from backlog are read directly, not copied./end is the Sole Sync Point — At session close, /end runs Hot Lane Sync:[x] tasks → done.md (tagged #session)[ ] tasks → ask user: keep or promote to backlog?#backlog)/backlog update needed mid-session. Just code./backlog clean = Compress, Not Delete — Done items are compressed into 1 line per plan in backlog's ✅ Completed section. Details live in done.md (grouped by plan, linking to plans/done/). Lookup chain: backlog → done.md → plans/done/.📖 Note: For a detailed breakdown of all features, fixes, and updates in each version, please read our CHANGELOG.
PARA Workspace offers two official mechanisms to upgrade to a newer version:
For most healthy workspaces, the built-in update mechanism handles everything safely.
./para update
This will automatically pull the newest core code, run version-gated migrations (only steps relevant to your current version), sync the libraries, and securely move obsolete structural files to the .para/archive/ vault without deleting your custom data (Smart Archive). User-customized rules are protected with .bak backups.
If your workspace is very old (v1.3.x) or has been heavily customized, start fresh:
para init --profile=dev --lang=en in a completely new directory.Projects/ directories into the _inbox/ of the new workspace./inbox workflow or let your AI agent sort them into the new correct structure.paraworkspace.dev (shipped in v1.4.1)/end [done] (shipped in v1.4.3)See CONTRIBUTING.md for guidelines. Key points:
kernel/examples/Built with ❤️ by Pageel. Standardizing the future of Agentic PKM.
Version: 1.6.0