# PARA Workspace
**The Workspace Framework for Humans & AI Agents**
[](https://opensource.org/licenses/MIT)
[](./CHANGELOG.md)
[](https://antigravity.google/)
πΊπΈ English β’
π»π³ TiαΊΏng Viα»t β’
π¨π³ δΈζ β’
πͺπΈ EspaΓ±ol β’
π«π· FranΓ§ais
---
| Section | Description |
| :--- | :--- |
| [π Overview](#-overview) | What it is, three foundational principles |
| [π Architecture](#-architecture) | Repo structure + generated workspace structure |
| [π₯ Installation](#-installation) | Prerequisites, setup, profiles, troubleshooting |
| [π§ The Kernel](#-the-kernel) | Invariants, heuristics, contracts |
| [π οΈ CLI Reference](#οΈ-cli-reference) | All CLI commands |
| [π Workflow Catalog](#-workflow-catalog) | 32 governed workflows |
| [π‘οΈ Rule Catalog](#οΈ-rule-catalog) | 14 governance rules |
| [𧩠Skill Catalog](#-skill-catalog) | 21 reusable skills |
| [π Tool System](#-tool-system-v180) | Install external agentic plugins |
| [𧩠Task Management](#-task-management-hybrid-3-file-model) | Hybrid 3-File model |
| [π Upgrading](#-upgrading-versions) | Auto update + clean slate |
| [πΊοΈ Roadmap](#οΈ-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.
```mermaid
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`)
```