---

Section	Description
🌌 Overview	What it is, three foundational principles
📂 Architecture	Repo structure + generated workspace structure
📥 Installation	Prerequisites, setup, profiles, troubleshooting
🧠 The Kernel	Invariants, heuristics, contracts
🛠️ CLI Reference	All CLI commands
📑 Workflow Catalog	27 governed workflows
🛡️ Rule Catalog	11 governance rules
🧩 Skill Catalog	9 reusable skills
🔌 Tool System	Install external agentic plugins
🧩 Task Management	Hybrid 3-File model
🔄 Upgrading	Auto update + clean slate
🗺️ Roadmap	Version history + planned features

🌌 Overview

PARA Workspace is an open-source workspace framework 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 invariants and 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.

flowchart TD
    R["🏛️ Repo\n(Constitution + Compiler)"]
    W["💻 Workspace\n(OS Runtime)"]
    A["🤖 Agent\n(Execution Environment)"]
    R -->|para init| W
    W -->|agent attach| A

    style R fill:#4a90d9,stroke:#2c5f8a,color:#fff
    style W fill:#50c878,stroke:#2e8b57,color:#fff
    style A fill:#ff8c42,stroke:#cc6633,color:#fff

---

📂 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    # 10 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/agents/    # Centralized workflows/, rules/, skills/ + catalog.yml
│   │   └── projects/    # .project.yml template
│   └── profiles/        # dev, general 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 (11 files)
│   └── 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
│   ├── 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
├── .agents/                            # Governed library copies (Auto-synced)
│   ├── rules.md                       # Workspace Rules Trigger Index (always loaded)
│   ├── skills.md                      # Workspace Skills Trigger Index (v1.6.2+)
│   ├── 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	.agents/ (skills, workflows)	✅ Verified	Designed and tested for this platform
Claude Code	CLAUDE.md + .agents/	⚪ Untested	May read .agents/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

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 .agents/workflows/
  • Syncs governed rules from catalog.yml into .agents/rules/
  • Syncs workspace rules index into .agents/rules.md (trigger index)
  • Syncs skills into .agents/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 + Ecosystem + Meta-Project (v1.7.6)
H8	Workflow kernel compatibility
H9	Governed libraries require catalog.yml with kernel_min
H10	Knowledge Items — schema, scope, slug validation (v1.7.0)

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

# Tool Management (v1.8.0)
para install-tool <name>        # Install a plugin from registry
para remove-tool <name>         # Remove installed plugin
para list-tools                 # List installed plugins

# MCP Server Management (v1.8.2)
para mcp-setup <tool>           # Auto-configure MCP in IDE
para mcp-list                   # List MCP-capable tools
para mcp-remove <tool>          # Remove MCP config from IDE

# 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
/spec	Write structured specifications before coding
/update	Agent-guided safe workspace update with error recovery
/verify	Verify task completion with walkthroughs
/para-knowledge	Manage Knowledge Items — dashboard, create, audit, archive
/para-skill	Co-Author engine for creating, validating, and testing AI Agent skills
/write	Write deep-dive content with structured sidecar templates
/logs	Session telemetry diagnostics and context budget analytics

---

🛡️ Rule Catalog

Rules govern agent behavior, security, and compliance. Loaded on-demand via a Two-Tier trigger index (~200 tokens). Skills are loaded via a parallel skills trigger index (v1.6.2). 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
knowledge	KI operations — write gate, approval, namespace (v1.7.0)	🔴 Critical
hybrid-3-file-integrity	6 constraints (C1–C6) for task management	🟡 Important
agent-behavior	Proactive Trigger Check, Context Recovery (v1.6.2)	🟡 Important
context-rules	Agent Index Loading (rules + skills), 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

---

🧩 Skill Catalog

Skills are reusable knowledge modules loaded on-demand via the skills trigger index. Unlike rules (which enforce constraints), skills provide templates, patterns, and reference material.

Skill	Description
PARA Kit	PARA workspace structure reference — schema, layout, kernel governance, intelligence routing
Formatting	Tables, diagrams, tree listings, ASCII box art
Page Map	Website visual structure management using PAGE_MAP.md and BLUEPRINT.md
PARA Skill	Governance skill for creating and validating PARA skills via Co-Author engine
Plan Templates	Detail Plan & Roadmap templates (Sidecar, v1.7.8)
Docs Templates	Architecture, CLI, Strategy templates (Sidecar, v1.7.8)
Brainstorm Templates	Decision & Research templates (Sidecar, v1.7.12)
Write Templates	Content type templates and writing rules (Sidecar, v1.7.14)
Harness Guards	Guard catalog and auto-scan protocol for context-aware safety guards (Sidecar, v1.7.15)

---

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

Rules and skills aren't dumped into context all at once. PARA Workspace uses a progressive disclosure architecture that loads indices on-demand, saving ~90% of token budget while maintaining full compliance.

How It Works: Two-Tier Trigger Index (v1.6.2)

flowchart TD
    START["🚀 /open starts session"] --> R

    subgraph T1["Tier 1 — ALWAYS"]
        R["📜 .agents/rules.md\n~20 lines · ~200 tokens"]
        S["🧩 .agents/skills.md\n~10 lines · ~100 tokens"]
    end

    R --> MEMO1["Agent memorizes triggers\n→ loads rules ON DEMAND"]
    S --> MEMO2["Agent memorizes triggers\n→ loads skills ON DEMAND"]

    START --> S
    MEMO1 --> CHECK
    MEMO2 --> CHECK

    subgraph T2["Tier 2 — CONDITIONAL"]
        CHECK{"Check project.md\nagent map"}
        CHECK -->|agent.rules: true| PR["📜 Project rules.md"]
        CHECK -->|agent.skills: true| PS["🧩 Project skills.md"]
        CHECK -->|neither| SKIP["Skip — no project indices"]
    end

    style T1 fill:#1a1a2e,stroke:#4a90d9,color:#e0e0e0
    style T2 fill:#1a1a2e,stroke:#50c878,color:#e0e0e0
    style START fill:#ff8c42,stroke:#cc6633,color:#fff
    style CHECK fill:#4a90d9,stroke:#2c5f8a,color:#fff

💡 Total cost: ~350 tokens (vs ~2,000 if all loaded upfront)

Defense-in-Depth: 4-Layer Protection

After a long conversation, AI agents lose context (truncation). PARA Workspace has 4 independent layers to ensure rules and skills survive:

block-beta
    columns 4
    block:header:4
        columns 4
        h1["Layer"] h2["What"] h3["Where"] h4["Survives"]
    end
    l1["1"] w1["Index instructions"] p1["agent-behavior.md §4"] s1["⚠️ Lost"]
    l2["2"] w2["Safety block"] p2["/open Step 8 report"] s2["✅ Checkpoint"]
    l3["3"] w3["Pre-flight"] p3["Step 0: re-read"] s3["✅ Disk"]
    l4["4"] w4["File guards"] p4["<!-- ⚠️ --> inline"] s4["✅ In-file"]

    style s1 fill:#d32f2f,color:#fff
    style s2 fill:#388e3c,color:#fff
    style s3 fill:#388e3c,color:#fff
    style s4 fill:#388e3c,color:#fff

Layer 3 uses Proactive Trigger Check (v1.6.2): BEFORE any side-effect, agent scans all trigger tables and loads matching rules/skills FIRST.

Layer 4 supports 6 guard types: STATUS GATE, MANDATORY, HARNESS GUARD, FILE GUARD (C1-C3, I9, GOVERNED), WORKFLOW GATE, CONTEXT RECOVERY.

Scenario: Agent forgets rules after truncation

sequenceDiagram
    participant C as 💬 Long Conversation
    participant T as ✂️ Truncation
    participant P as 🚀 Agent runs /push
    participant D as 📝 Agent edits done.md

    C->>T: Context window full
    T--xP: ⚠️ Rules lost!
    T--xD: ⚠️ Rules lost!

    Note over P: Layer 3 catches
    P->>P: Step 0 re-reads .agents/rules.md
    P->>P: VCS rules loaded → safe commit ✅

    Note over D: Layer 4 catches
    D->>D: Reads <!-- ⚠️ APPEND-ONLY -->
    D->>D: Obeys C2 → 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/.

---

📚 Knowledge System (v1.7.0)

AI agents lose context between sessions. Knowledge Items (KIs) are a core feature of Google Antigravity — the AI coding agent platform — that provides persistent memory across sessions, projects, and conversations.

KIs live outside the workspace, in Antigravity's platform-managed KI Store (~/.gemini/antigravity/knowledge/). This mirrors PARA Workspace's foundational principle: just as the repo governs but does not contain user data, PARA Workspace governs KI operations (schema, rules, lifecycle workflows) without owning the storage layer.

flowchart LR
    subgraph Platform["Antigravity Platform"]
        KI["📦 KI Store\n~/.gemini/antigravity/\nknowledge/"]
    end
    subgraph WS["PARA Workspace"]
        GOV["🛡️ Governance\nschema · rules\n/para-knowledge"]
    end
    GOV -->|governs| KI

    style Platform fill:#1a1a2e,stroke:#ff8c42,color:#e0e0e0
    style WS fill:#1a1a2e,stroke:#4a90d9,color:#e0e0e0
    style KI fill:#ff8c42,stroke:#cc6633,color:#fff
    style GOV fill:#4a90d9,stroke:#2c5f8a,color:#fff

How It Works

flowchart LR
    S1["🔍 Session 1\nAgent discovers insight"]
    S2["♻️ Session 2\nAuto-loaded"]
    SN["⚡ Session N\nApplies instantly"]
    KI[("💾 KI Store\nPlatform-managed")]

    S1 -->|save as KI| KI
    KI -->|auto-inject| S2
    S2 -->|refine| KI
    KI -->|auto-inject| SN

    style S1 fill:#4a90d9,stroke:#2c5f8a,color:#fff
    style S2 fill:#50c878,stroke:#2e8b57,color:#fff
    style SN fill:#ff8c42,stroke:#cc6633,color:#fff
    style KI fill:#9b59b6,stroke:#7d3c98,color:#fff

Unlike session logs (lost after truncation) or learning files (project-scoped), KIs are:

• Auto-injected at session start by the platform
• Cross-project — workspace-scoped KIs apply to all projects
• Graph-ready — domain × purpose taxonomy with relates_to and concepts fields

KI Taxonomy

Each KI is classified along two axes — domain (what) × purpose (how):

                  ┌────────────────────────────────────────────────────────┐
                  │                      PURPOSE                           │
                  ├──────────────┬──────────────┬─────────────┬────────────┤
                  │   context    │  reference   │   pitfall   │  playbook  │
                  │  (priming)   │  (lookup)    │  (gotchas)  │ (how-to)   │
     ┌────────────┼──────────────┼──────────────┼─────────────┼────────────┤
     │ workspace  │ PARA arch    │ kernel specs │ update bugs │ audit proc │
     │ engineering│ tech stack   │ API docs     │ dep gotchas │ deploy SOP │
  D  │ operations │ infra setup  │ CI/CD ref    │ env traps   │ rollback   │
  O  │ content    │ writing std  │ style guide  │ SEO traps   │ publish    │
  M  │ strategy   │ org context  │ roadmap      │ scope creep │ planning   │
  A  │ ...        │              │              │             │            │
  I  ├────────────┘              │              │             │            │
  N  │  (open — define your own) │              │             │            │
     └───────────────────────────┴──────────────┴─────────────┴────────────┘

Domain is an open string — define custom domains as needed.
Purpose is a fixed enum: context, reference, pitfall, playbook.

Lifecycle & Integration

Workflow	KI Integration
/open	Platform-injected KI context, scope matching for report
/plan	Pitfall KIs → Risks, Playbook KIs → Phase references
/end	Suggests creating/updating KIs from session insights
/brainstorm	Option F: Extract insight as KI
/retro	Graduates cross-project patterns to KIs
/para-knowledge	Full lifecycle: create, update, audit, archive

Governance

KI operations are governed by 7 rules (KR1–KR7) and validated against H10 (11 clauses):

• KR1 Write Gate: Only /para-knowledge workflow can create/modify KIs
• KR2 User Approval: Every KI creation requires explicit user consent
• KR3 Namespace: para_ prefix reserved for system KIs
• KR5 Recoverability: All KI operations are reversible
• KR7 Ephemeral Ban: No ephemeral file paths in KI references (v1.7.5)

📖 Full schema: ki.schema.json · Governance: heuristics.md H10

---

🔌 Tool System (v1.8.0)

PARA Workspace supports an extensible Dynamic Tool System that allows you to install external, language-agnostic plugins (like para-graph) directly into your workspace.

Tools are managed via a central registry (registry/tools.yml) and are installed as standalone tarballs.

How it works

1. Zero Global Dependencies: Tools are installed locally into .para/tools/ for isolation.
2. Multi-Runtime Support: The CLI auto-generates wrapper scripts (e.g. repo/cli/commands/graph.sh) that know how to invoke Node, Python, or binary executables.
3. Dev/Prod Fallback: If a tool's source code exists inside the workspace (Dev mode), the wrapper routes execution there. Otherwise, it falls back to the extracted tarball (Prod mode).

Available Tools

Tool	Description
para-graph	Hybrid Code-Knowledge Graph for PARA Workspace

💡 Version is resolved dynamically from registry/tools.yml — always installs the latest registered release.

Usage

# Install the para-graph plugin (structural code analysis & MCP server)
./para install-tool para-graph

# List installed tools
./para list-tools

# Run the installed tool
./para graph --help

# Remove tool
./para remove-tool para-graph

Tool Intelligence Installer (v1.8.1)

Tools can bundle AI intelligence (workflows, skills, rules) directly in their tool.manifest.yml:

agents:
  workflows:
    - source: templates/agents/workflows/para-graph.md
      target: para-graph.md
      version: "1.8.0"
  skills:
    - source: templates/agents/skills/graph-enrichment/
      target: graph-enrichment/
      version: "1.0.0"

When you run ./para install-tool <name>, the CLI will automatically parse this manifest and prompt you to install the bundled intelligence.
You can use --agents to install only the agents, or --no-agents to skip the prompt.
remove-tool will also offer to clean up any bundled agents it installed.

MCP Auto-Setup (v1.8.2)

Tools can declare an MCP server in their manifest via the mcp: block. PARA Workspace provides three CLI commands to manage MCP configurations across IDEs:

# Auto-configure MCP server for a tool in your IDE
./para mcp-setup <tool-name>

# Print the JSON snippet without modifying IDE config
./para mcp-setup <tool-name> --print-only

# List all tools with MCP servers available
./para mcp-list

# Remove an MCP server entry from IDE config
./para mcp-remove <tool-name>

Supported IDEs:

IDE	Config Path
Google Antigravity	~/.gemini/antigravity/mcp_config.json
Claude Desktop	~/.config/claude/claude_desktop_config.json (Linux)
Cursor	~/.cursor/mcp.json

The setup uses 2-Tier path resolution (Dev path → Prod path) to point to the correct entry, and jq-based atomic JSON merge with automatic backup.

---

🔄 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)
• Meta-Project & Ecosystem Support (shipped in v1.6.0)
• Unified Strategy → Plan Flow (shipped in v1.6.1)
• Unified Agent Index — Skills Loading & Proactive Trigger Check (shipped in v1.6.2)
• Central Gate — project.md as single source for context loading (shipped in v1.6.3)
• Para-Kit Skill v1.1.0, Recursive Sync & Git Hash Detection (shipped in v1.6.4)
• Update Flow Fix — Version Direction Detection & Migration History (shipped in v1.6.5)
• Knowledge System — KI schema, /knowledge workflow, graph-ready taxonomy (shipped in v1.7.0)
• System KI Governed Lifecycle — namespace guard, template sync, CLI hooks (shipped in v1.7.1)
• KI Index Schema Upgrade, Workflow Simplification & Knowledge Graph Seed (shipped in v1.7.2)
• Agent Path Convention Fix (BUG-28) & Rule Frontmatter (shipped in v1.7.3)
• Repo Path Standardization, Pending TODO Fix & Project Profile Skill (shipped in v1.7.4)
• KR7 Ephemeral Ban & /knowledge → /para-knowledge Rename (shipped in v1.7.5)
• Skill Catalog Architecture & Meta-Project Type (shipped in v1.7.6)
• Brainstorm Consolidation, Sidecar Skill & /docs (shipped in v1.7.7-1.7.8)
• Proactive Trigger Check & Cognitive Bypass Fix (shipped in v1.7.9-1.7.10)
• Backlog Governance & Extract Paradigm (shipped in v1.7.11-1.7.12)
• VERSIONS.yml Migration & Anti-Token Decay (shipped in v1.7.13)
• Content Authoring Ecosystem & Session Telemetry (shipped in v1.7.14)
• Harness Skill, Plan Status Gate & Roadmap Prefix Convention (shipped in v1.7.15)
• Spec Workflow, Dual-Format Guards & CLI Fixes (shipped in v1.7.16)
• Dynamic Tool System & para-graph integration (shipped in v1.8.0)
• Tool Intelligence Installer & manifest-declared AI intelligence (shipped in v1.8.1)
• MCP Auto-Setup — mcp-setup, mcp-list, mcp-remove CLI commands (shipped in v1.8.2)
• Department System (v1.9.0 — planned)
• Community & Trust Boundary (v1.10.0 — planned)

---

🤝 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.8.2