pageel/para-workspace

---

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

/
├── 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:

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

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)

Heuristics (Soft Rules — change = MINOR/PATCH)

Kernel ↔ Workspace Contracts

---

🛠️ CLI Reference

# Core Commands
para init [--profile] [--lang]  # Create workspace
para status [--json]            # System health
para update                     # Auto-update & migrate
para scaffold       # Create structured paths
para install [--force]          # Sync governed libraries
para archive        # Graduation review
para migrate [--from] [--to]    # Workspace migration

# Configuration
para config [key] [value]       # Manage workspace settings

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

# MCP Server Management (v1.8.2)
para mcp-setup            # Auto-configure MCP in IDE
para mcp-list                   # List MCP-capable tools
para mcp-remove           # 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

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

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

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

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

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

# Remove an MCP server entry from IDE config
./para mcp-remove 

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:

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

• [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)
• [x] Systemic Enforcement of Project-Specific Rules (scan-project-rules, lint-plan v2.0, QA Pre-flight Gate) (shipped in v1.9.6)
• [ ] Plugin Hooks & vibecode_session 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.7