Topics

#agentic-workflow #ai-agents #antigravity #dev-tools #para-method #personal-knowledge-management #pkm #productivity #second-brain #standard #structure #workspace-framework #workspace-template

Language breakdown

No language data available.

▸ Files click to expand

README

PARA Workspace

The Workspace Framework for Humans & AI Agents

🇺🇸 English • 🇻🇳 Tiếng Việt • 🇨🇳 中文 • 🇪🇸 Español • 🇫🇷 Français

🌌 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

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 you and your agent work.
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

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:

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)
Audit log is updated in .para/audit.log

Troubleshooting

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

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

🛡️ 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.

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

🏗️ 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  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

Backlog Summary — /open reads only the Summary table (~10 lines) + top active items via grep. Never the full file.
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.
/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)

Zero Ceremony During Coding — No /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/.

📚 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

Zero Global Dependencies: Tools are installed locally into .para/tools/ for isolation.
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.
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

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

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:

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

🗺️ Roadmap

[x] Cross-Project Sync Queue (shipped in v1.3.6)
[x] Kernel Extraction & Repo Restructure (shipped in v1.4.0)
[x] Governed Libraries, RFC Process, Workspace Runtime Safety (shipped in v1.4.1)
[x] Landing Page paraworkspace.dev (shipped in v1.4.1)
[x] Plan-Aware Workflows & Token Optimization (shipped in v1.4.2)
[x] Automated Plan Cleanup via /end [done] (shipped in v1.4.3)
[x] Safety Guardrails & Terminal Allowlist (shipped in v1.4.5)
[x] Smart Archive & Version Migration (shipped in v1.4.6)
[x] macOS Compatibility & Safe Migration Pipeline (shipped in v1.4.7)
[x] Atomic Rollback, Dry-run Pipeline & README Rewrite (shipped in v1.4.8)
[x] Centralized Backup & Workspace Cleanup (shipped in v1.4.9)
[x] Project Rules Loading & Safe Update Workflow (shipped in v1.5.0)
[x] Hybrid 3-File Synchronization & Fast Mode (shipped in v1.5.1)
[x] Hybrid 3-File Integrity, Working Checkmarks & Docs Overhaul (shipped in v1.5.2)
[x] Hot Lane Refactor, /end Sync Point & Token Optimization (shipped in v1.5.3)
[x] Context Recovery, Workflow Pre-flight & Defense-in-Depth (shipped in v1.5.4)
[x] Meta-Project & Ecosystem Support (shipped in v1.6.0)
[x] Unified Strategy → Plan Flow (shipped in v1.6.1)
[x] Unified Agent Index — Skills Loading & Proactive Trigger Check (shipped in v1.6.2)
[x] Central Gate — project.md as single source for context loading (shipped in v1.6.3)
[x] Para-Kit Skill v1.1.0, Recursive Sync & Git Hash Detection (shipped in v1.6.4)
[x] Update Flow Fix — Version Direction Detection & Migration History (shipped in v1.6.5)
[x] Knowledge System — KI schema, /knowledge workflow, graph-ready taxonomy (shipped in v1.7.0)
[x] System KI Governed Lifecycle — namespace guard, template sync, CLI hooks (shipped in v1.7.1)
[x] KI Index Schema Upgrade, Workflow Simplification & Knowledge Graph Seed (shipped in v1.7.2)
[x] Agent Path Convention Fix (BUG-28) & Rule Frontmatter (shipped in v1.7.3)
[x] Repo Path Standardization, Pending TODO Fix & Project Profile Skill (shipped in v1.7.4)
[x] KR7 Ephemeral Ban & /knowledge → /para-knowledge Rename (shipped in v1.7.5)
[x] Skill Catalog Architecture & Meta-Project Type (shipped in v1.7.6)
[x] Brainstorm Consolidation, Sidecar Skill & /docs (shipped in v1.7.7-1.7.8)
[x] Proactive Trigger Check & Cognitive Bypass Fix (shipped in v1.7.9-1.7.10)
[x] Backlog Governance & Extract Paradigm (shipped in v1.7.11-1.7.12)
[x] VERSIONS.yml Migration & Anti-Token Decay (shipped in v1.7.13)
[x] Content Authoring Ecosystem & Session Telemetry (shipped in v1.7.14)
[x] Harness Skill, Plan Status Gate & Roadmap Prefix Convention (shipped in v1.7.15)
[x] Spec Workflow, Dual-Format Guards & CLI Fixes (shipped in v1.7.16)
[x] Dynamic Tool System & para-graph integration (shipped in v1.8.0)
[x] Tool Intelligence Installer & manifest-declared AI intelligence (shipped in v1.8.1)
[x] MCP Auto-Setup — mcp-setup, mcp-list, mcp-remove CLI commands (shipped in v1.8.2)
[x] QA Governance Workflow & Sidecar Skill Integration (shipped in v1.8.6)
[x] TDD Governance Workflow (shipped in v1.8.7)
[x] Ecosystem-wide Para-Graph MCP Integration — Memory Ops lifecycle, Project Sidecar Skill, 43% workflow coverage (shipped in v1.8.9)
[x] Release Hardening, HTML Renderer Integration, Spec Rules & TDD Gate (shipped in v1.8.10)
[x] Release Hardening: dirty-check template override prompts in install-tool CLI, conflict diff detection, and staging/scan-sec/vibecode/resource workflows catalog integration (shipped in v1.8.11)
[x] Antigravity IDE 2.x and v1.x Config Migration & TDD hardening (shipped in v1.8.12)
[x] Node Path Resolution (NVM/fnm/Volta) & Rule/KI Artifact Authority improvements (shipped in v1.8.13)
[x] MCP Windows Path Conversion (BUG-37) & Plan Auto-Activation (shipped in v1.8.14)
[x] Vibecode DSP & Template Consolidation (shipped in v1.8.15)
[x] Platform Tracker Exemption & Decoupled Project Plans (shipped in v1.9.0)
[x] Plan/Session-Plan Templates & Dual-Format Guards (shipped in v1.9.1)
[x] Standards & Roadmaps Optimization (shipped in v1.9.2)
[x] Unified CSA HTML-Renderer Upgrade (shipped in v1.9.3)
[x] Local Development Sync & AI Index Auto-Sync (shipped in v1.9.4)
[x] Template Consolidation & Release (Diagnostics Debug, Self-Improvement, Remote, Report, Research) (shipped in v1.9.5)
[ ] Plugin Hooks & vibecodesession extensions (v1.10.0 — planned)_
[ ] Department System (v1.x.x — 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/

📄 License & References

This project is licensed under the MIT License.

The /scan-sec security audit module (governed under scan-sec SKILL.md) is built upon and references:

The vbsec repository (core execution architecture).
The OWASP Top 10 project (security standards and classifications).

Third-Party Dependencies

Core CLI Utilities

jq (JSON CLI parser, required for configuration updates).
Git (Required for version control and workspace updates).
Node.js (Runtime for graph analysis and HTML document renderers).

Frontend CDN Libraries (used in HTML rendering)

marked (Markdown parser).
mermaid (Flowchart/diagram engine).
force-graph (2D force-directed graph engine for code graph visualization).
lucide (UI icons).
Google Fonts (Inter, Outfit, Roboto, Fira Code typography).

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

Version: 1.9.5

🔗 More in this category

PARA Workspace

🌌 Overview

Three Foundational Principles

📂 Architecture

Repo Structure (This Repository)

Workspace Structure (Generated by para init)

📥 Installation

Prerequisites

Platform Compatibility

Step 1: Clone & Install

Set executable permissions

Initialize your workspace with a profile

Then open Git Bash or WSL at workspace root:

Step 2: Verify

✅ If you see a health report → installation successful

Updating

Preview changes before applying

Troubleshooting

Windows Recovery

Available Profiles

What para init Does

🧠 The Kernel

Invariants (Hard Rules — change = MAJOR bump)

Heuristics (Soft Rules — change = MINOR/PATCH)

Kernel ↔ Workspace Contracts

🛠️ CLI Reference

Configuration

Tool Management (v1.8.0)

MCP Server Management (v1.8.2)

Agent Capabilities

📑 Workflow Catalog

🛡️ Rule Catalog

🧩 Skill Catalog

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

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

Defense-in-Depth: 4-Layer Protection

🧩 Task Management (Hybrid 3-File Model)

How It Works

📚 Knowledge System (v1.7.0)

How It Works

KI Taxonomy

Lifecycle & Integration

Governance

🔌 Tool System (v1.8.0)

How it works

Available Tools

Usage

List installed tools

Run the installed tool

Remove tool

Tool Intelligence Installer (v1.8.1)

MCP Auto-Setup (v1.8.2)

Print the JSON snippet without modifying IDE config

List all tools with MCP servers available

Remove an MCP server entry from IDE config

🔄 Upgrading Versions

Mechanism 1: Auto Update (Recommended)

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

🗺️ Roadmap

🤝 Contributing

📄 License & References

Third-Party Dependencies

Core CLI Utilities

Frontend CDN Libraries (used in HTML rendering)

Workspace Structure (Generated by `para init`)

`✅ If you see a health report → installation successful`

What `para init` Does