PARA Workspace

The Governed Workspace Standard for AI Agents

🇺🇸 English • 🇻🇳 Tiếng Việt

---

🌌 Overview

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.

Three Foundational Principles

1. Repo ≠ Workspace — The repo contains governance (kernel, CLI, templates). It never contains user data.
2. Workspace = Runtime — Generated by para init, each workspace is a standalone instance where you and your agent work.
3. Kernel = Constitution — Immutable rules that all workspaces follow. Changes require an RFC + version bump.

Repo     (Constitution + Compiler)
  ↓ para init
Workspace (Operating System Runtime)
  ↓ agent attach
Agent    (Execution Environment)

---

📂 Architecture

Repo Structure (This Repository)

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
│   ├── guides/          # How-to: development, planning
│   ├── 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

Workspace Structure (Generated by para init)

<your-workspace>/
├── Projects/                          # Goal-oriented tasks (e.g., website-launch)
├── 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

---

📥 Installation

Prerequisites

• An AI Agent platform (see compatibility table below)
• Git (required — to clone and update)
• Bash 3.2+ (Linux/macOS native, Windows via Git Bash or WSL)

Platform Compatibility

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

Step 1: Clone & Install

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

Step 2: Verify

./para status
# ✅ If you see a health report → installation successful

What just happened?

1. The repo lives at Resources/references/para-workspace/ — it's a read-only reference source, not a user project.
2. chmod +x ensures all CLI scripts are executable (required on Linux/macOS).
3. para init creates the full PARA directory structure, runs install.sh automatically to sync kernel, workflows, governance rules, and generates a ./para wrapper.
4. You can now use ./para from your workspace root for all commands.

Updating

# 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:

1. git pull fetches latest code (self-restarts if scripts changed)
2. migrate.sh runs version-gated migration steps (only what's needed)
3. install.sh syncs kernel, workflows, rules, skills to workspace (with atomic rollback)
4. Audit log is updated in .para/audit.log

Troubleshooting

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

Windows Recovery

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

Available Profiles

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

What para init Does

• ✅ Creates Projects/, Areas/, Resources/, Archive/, and _inbox/
• ✅ Sets executable permissions on all CLI scripts
• ✅ Runs install.sh automatically, which:
  • Syncs governed workflows from catalog.yml into .agent/workflows/
  • Syncs governed rules from catalog.yml into .agent/rules/
  • Syncs workspace rules index into .agent/rules.md (trigger index)
  • Syncs skills into .agent/skills/ (if profile includes them)
  • Creates ./para wrapper at workspace root
  • Backs up conflicting files to .bak
• ✅ Generates .para-workspace.yml with kernel version tracking
• ✅ Initializes .para/ state (audit.log, migrations/, backups/) for full auditability

---

🧠 The Kernel

The Kernel is the constitution of PARA Workspace — the rules that all workspaces must follow.

Invariants (Hard Rules — change = MAJOR bump)

#	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

Heuristics (Soft Rules — change = MINOR/PATCH)

#	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 via Resources
H8	Workflow kernel compatibility
H9	Governed libraries require catalog.yml with kernel_min

Kernel ↔ Workspace Contracts

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

---

🛠️ CLI Reference

# 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).

---

📑 Workflow Catalog

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

---

🛡️ Rule Catalog

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

---

🏗️ Rule Architecture — Two-Tier Loading & Defense-in-Depth

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.

How It Works: Two-Tier Trigger Index

┌─────────────────────────────────────────────────────────────┐
│                    /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)  │
└─────────────────────────────────────────────────────────────┘

Defense-in-Depth: 4-Layer Rule Protection

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

---

🧩 Task Management (Hybrid 3-File Model)

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).

How It Works

1. Backlog Summary — /open reads only the Summary table (~10 lines) + top active items via grep. Never the full file.
2. Hot Lane — Agent writes ad-hoc quick tasks (- [ ] Fix CSS) to sprint-current.md and ticks [x] when done. Strategic tasks from backlog are read directly, not copied.
3. /end is the Sole Sync Point — At session close, /end runs Hot Lane Sync:
   • Quick [x] tasks → done.md (tagged #session)
   • Quick [ ] tasks → ask user: keep or promote to backlog?
   • Smart Suggest → reads session log, finds mentioned task IDs, suggests marking strategic tasks as Done (tagged #backlog)
4. Zero Ceremony During Coding — No /backlog update needed mid-session. Just code.
5. /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/.

---

🔄 Upgrading Versions

📖 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:

Mechanism 1: Auto Update (Recommended)

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.

Mechanism 2: Manual Clean Slate (For heavily modified workspaces)

If your workspace is very old (v1.3.x) or has been heavily customized, start fresh:

1. Run para init --profile=dev --lang=en in a completely new directory.
2. Copy your old Projects/ directories into the _inbox/ of the new workspace.
3. Use the /inbox workflow or let your AI agent sort them into the new correct structure.

---

🗺️ Roadmap

• Cross-Project Sync Queue (shipped in v1.3.6)
• Kernel Extraction & Repo Restructure (shipped in v1.4.0)
• Governed Libraries, RFC Process, Workspace Runtime Safety (shipped in v1.4.1)
• Landing Page paraworkspace.dev (shipped in v1.4.1)
• Plan-Aware Workflows & Token Optimization (shipped in v1.4.2)
• Automated Plan Cleanup via /end [done] (shipped in v1.4.3)
• Safety Guardrails & Terminal Allowlist (shipped in v1.4.5)
• Smart Archive & Version Migration (shipped in v1.4.6)
• macOS Compatibility & Safe Migration Pipeline (shipped in v1.4.7)
• Atomic Rollback, Dry-run Pipeline & README Rewrite (shipped in v1.4.8)
• Centralized Backup & Workspace Cleanup (shipped in v1.4.9)
• Project Rules Loading & Safe Update Workflow (shipped in v1.5.0)
• Hybrid 3-File Synchronization & Fast Mode (shipped in v1.5.1)
• Hybrid 3-File Integrity, Working Checkmarks & Docs Overhaul (shipped in v1.5.2)
• Hot Lane Refactor, /end Sync Point & Token Optimization (shipped in v1.5.3)
• Context Recovery, Workflow Pre-flight & Defense-in-Depth (shipped in v1.5.4)

---

🤝 Contributing

See CONTRIBUTING.md for guidelines. Key points:

• Kernel invariant changes require an RFC + MAJOR bump → See rfcs/TEMPLATE.md
• Heuristic changes require a PR + MINOR/PATCH bump
• All changes must pass test vectors in kernel/examples/

---

Built with ❤️ by Pageel. Standardizing the future of Agentic PKM.

Version: 1.5.4