feat(plugin): native Claude Code plugin + dual-mode npx install

.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "base",
+  "owner": {
+    "name": "ChristopherKahler",
+    "url": "https://github.com/ChristopherKahler"
+  },
+  "metadata": {
+    "description": "BASE — Builder's Automated State Engine: workspace lifecycle management, data surfaces, and audit tooling for Claude Code."
+  },
+  "plugins": [
+    {
+      "name": "base",
+      "description": "BASE — Builder's Automated State Engine: workspace lifecycle management, data surfaces, and audit tooling for Claude Code.",
+      "version": "3.1.5",
+      "source": ".",
+      "category": "framework",
+      "keywords": ["base", "workspace", "scaffold", "audit", "groom", "surfaces", "operator", "lifecycle"]
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "base",
+  "version": "3.1.5",
+  "description": "BASE — Builder's Automated State Engine: workspace lifecycle management, data surfaces, and audit tooling for Claude Code.",
+  "author": {
+    "name": "Chris Kahler"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ChristopherKahler/base#readme"
+}

.github/workflows/plugin-install.yml

@@ -0,0 +1,26 @@
+name: plugin-install
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate-and-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+      - name: Validate plugin + marketplace manifest (strict)
+        run: claude plugin validate . --strict
+      - name: Install smoke test (claude can install the plugin)
+        run: |
+          set -euo pipefail
+          claude plugin marketplace add ./
+          claude plugin install base@base
+          claude plugin list
+          claude plugin list | grep -i base

.gitignore

@@ -11,3 +11,8 @@ DIRECTORY-STRATEGY-SPEC.md
 
 # Node
 node_modules/
+# mcp/node_modules is created as a symlink by the SessionStart hook;
+# the trailing-slash pattern above matches directories but NOT symlinks,
+# so we add a slash-less entry to cover the symlink case as well.
+mcp/node_modules
+__pycache__/

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "base-mcp": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/index.js"],
+      "env": {
+        "CLAUDE_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}",
+        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
+      }
+    }
+  }
+}

src/framework/context/base-principles.md → base-framework/context/base-principles.md

@@ -1,69 +1,69 @@
-# BASE Principles
-
-## Core Laws
-
-1. **If it's not current, it's harmful.** Stale context documents feed AI bad information. Maintenance isn't optional.
-2. **Every file earns its place.** If you can't explain why it's here in 5 seconds, it moves or dies.
-3. **Archive > delete.** When in doubt, archive. You can always delete later. You can't un-delete.
-4. **The workspace is the product.** Treat it like production code, not a scratch pad.
-5. **Clean as you go.** The best time to file something correctly is when you create it. The second best time is now.
-6. **Scaffold generates manifest. Manifest drives everything.** One configuration point. No manual bookkeeping.
-7. **Tools register themselves.** PAUL projects auto-register with BASE. No human memory required.
-
-## Drift Score
-
-Drift is the gap between documented state and actual state. Measured in days-overdue across all tracked areas.
-
-- **0** — Everything current. Workspace is clean.
-- **1-7** — Minor drift. Normal during execution sprints. Fix at next groom.
-- **8-14** — Moderate drift. Context documents are likely misleading AI. Groom soon.
-- **15+** — Critical drift. Sessions are operating on stale context. Groom NOW.
-
-## Maintenance Cadence
-
-| What | Default Cadence | Override |
-|------|----------------|---------|
-| projects.json | Every session or weekly | workspace.json |
-| Project directory | Monthly | workspace.json |
-| Tools/MCP | Monthly | workspace.json |
-| System layer | Monthly | workspace.json |
-| Full audit | Quarterly or after major shifts | On demand |
-
-## Backlog Rules
-
-Items have time-based properties enforced by grooming:
-
-- **Added** — auto-set when item enters backlog
-- **Review-by** — priority-based: High=7d, Medium=14d, Low=30d
-- **Staleness** — 2x review-by threshold. Auto-archive if reached without action.
-
-During groom: items past review-by surface as "decide or kill." Items past staleness auto-archive with a note.
-
-## Graduation Flow
-
-Backlog items don't sit forever. They graduate to active when the operator is ready to work on them.
-
-```
-BACKLOG (status=backlog in projects.json)
-  → ACTIVE (status updated to in_progress/todo via base_update_project)
-  → DONE (archived via base_archive_project with outcome)
-```
-
-**TASKS vs PROJECTS:** A task is bounded — it has a finish line. "Extract .mcp.json secrets" is a task. "Build the CARL MCP server" might start as a task but could become a project if it grows. The operator decides during groom.
-
-**Graduation is never automatic.** The groom flow asks explicitly: "Ready to work on any backlog items?" The operator decides what graduates and where it lands.
-
-**Items can also move backward:** An active project that loses priority can return to backlog status. A project that stalls can move to DEFERRED. Nothing is permanent.
-
-## Scaffold Modes
-
-BASE scaffold operates in two modes:
-
-- **Standard** (`/base:scaffold`) — Data layer only. Creates `.base/` with workspace.json, `.base/data/state.json`, ROADMAP.md. Scans and tracks what exists. Framework-agnostic.
-- **Full** (`/base:scaffold --full`) — Data layer + projects.json + entities.json. Offers CLAUDE.md audit. The "batteries included" version for AI builders who want the full system.
-
-Standard mode works for any workspace. Full mode provides Chris's proven operational structure.
-
-## File Location
-
-BASE operates strictly out of `.base/`. All data (projects.json, entities.json, state.json, psmm.json) lives in `.base/data/`. Configuration (workspace.json) and documentation (ROADMAP.md) live in `.base/`. Data is accessed via MCP tools (`base_list_projects`, `base_add_project`, `base_update_project`, `base_get_state`, etc.). `.base/data/` is the canonical location for all structured data.
+# BASE Principles
+
+## Core Laws
+
+1. **If it's not current, it's harmful.** Stale context documents feed AI bad information. Maintenance isn't optional.
+2. **Every file earns its place.** If you can't explain why it's here in 5 seconds, it moves or dies.
+3. **Archive > delete.** When in doubt, archive. You can always delete later. You can't un-delete.
+4. **The workspace is the product.** Treat it like production code, not a scratch pad.
+5. **Clean as you go.** The best time to file something correctly is when you create it. The second best time is now.
+6. **Scaffold generates manifest. Manifest drives everything.** One configuration point. No manual bookkeeping.
+7. **Tools register themselves.** PAUL projects auto-register with BASE. No human memory required.
+
+## Drift Score
+
+Drift is the gap between documented state and actual state. Measured in days-overdue across all tracked areas.
+
+- **0** — Everything current. Workspace is clean.
+- **1-7** — Minor drift. Normal during execution sprints. Fix at next groom.
+- **8-14** — Moderate drift. Context documents are likely misleading AI. Groom soon.
+- **15+** — Critical drift. Sessions are operating on stale context. Groom NOW.
+
+## Maintenance Cadence
+
+| What | Default Cadence | Override |
+|------|----------------|---------|
+| projects.json | Every session or weekly | workspace.json |
+| Project directory | Monthly | workspace.json |
+| Tools/MCP | Monthly | workspace.json |
+| System layer | Monthly | workspace.json |
+| Full audit | Quarterly or after major shifts | On demand |
+
+## Backlog Rules
+
+Items have time-based properties enforced by grooming:
+
+- **Added** — auto-set when item enters backlog
+- **Review-by** — priority-based: High=7d, Medium=14d, Low=30d
+- **Staleness** — 2x review-by threshold. Auto-archive if reached without action.
+
+During groom: items past review-by surface as "decide or kill." Items past staleness auto-archive with a note.
+
+## Graduation Flow
+
+Backlog items don't sit forever. They graduate to active when the operator is ready to work on them.
+
+```
+BACKLOG (status=backlog in projects.json)
+  → ACTIVE (status updated to in_progress/todo via base_update_project)
+  → DONE (archived via base_archive_project with outcome)
+```
+
+**TASKS vs PROJECTS:** A task is bounded — it has a finish line. "Extract .mcp.json secrets" is a task. "Build the CARL MCP server" might start as a task but could become a project if it grows. The operator decides during groom.
+
+**Graduation is never automatic.** The groom flow asks explicitly: "Ready to work on any backlog items?" The operator decides what graduates and where it lands.
+
+**Items can also move backward:** An active project that loses priority can return to backlog status. A project that stalls can move to DEFERRED. Nothing is permanent.
+
+## Scaffold Modes
+
+BASE scaffold operates in two modes:
+
+- **Standard** (`/base:scaffold`) — Data layer only. Creates `.base/` with workspace.json, `.base/data/state.json`, ROADMAP.md. Scans and tracks what exists. Framework-agnostic.
+- **Full** (`/base:scaffold --full`) — Data layer + projects.json + entities.json. Offers CLAUDE.md audit. The "batteries included" version for AI builders who want the full system.
+
+Standard mode works for any workspace. Full mode provides Chris's proven operational structure.
+
+## File Location
+
+BASE operates strictly out of `.base/`. All data (projects.json, entities.json, state.json, psmm.json) lives in `.base/data/`. Configuration (workspace.json) and documentation (ROADMAP.md) live in `.base/`. Data is accessed via MCP tools (`base_list_projects`, `base_add_project`, `base_update_project`, `base_get_state`, etc.). `.base/data/` is the canonical location for all structured data.

src/framework/frameworks/audit-strategies.md → base-framework/frameworks/audit-strategies.md

@@ -1,53 +1,53 @@
-# Audit Strategies
-
-Reusable audit strategies that can be applied to any workspace area. The workspace manifest (`workspace.json`) maps areas to strategies. The audit command reads the manifest and applies the appropriate strategy to each area.
-
-## Strategies
-
-### staleness
-**Applies to:** Data files (projects.json, state.json, any tracked document)
-**What it does:** Check file modification timestamps against configured thresholds. Flag files past their groom cadence.
-**Config:**
-- `threshold_days` — days after which the file is considered stale
-**Output:** List of stale files with age, recommended action (update or review)
-
-### classify
-**Applies to:** Directories with lifecycle items (projects/, clients/)
-**What it does:** List all items in the directory. For each, present to operator for classification: active, archive, or delete. Check for planning docs, recent activity, git history.
-**Config:**
-- `states` — classification options (default: ["active", "archive", "delete"])
-- `archive_path` — where archived items go (default: `{path}/_archive/`)
-**Output:** Classification decisions, items moved to archive, items deleted
-
-### cross-reference
-**Applies to:** Tools/servers that have a config file mapping (e.g., MCP servers vs .mcp.json)
-**What it does:** Compare directory contents against a configuration file. Identify directories not referenced in config (orphaned) and config entries pointing to missing directories (broken).
-**Config:**
-- `config_file` — path to the configuration file to cross-reference
-**Output:** Orphaned items, broken references, recommendations
-
-### dead-code
-**Applies to:** System directories (hooks, commands, skills)
-**What it does:** Scan for files that appear unused — no references from other files, no recent invocations, no clear purpose. Presents findings for human decision.
-**Config:**
-- `reference_check` — whether to search for references in other files (default: true)
-**Output:** Potentially dead files with evidence, operator decides keep/delete
-
-### pipeline-status
-**Applies to:** Content pipelines, task queues, any workflow with stages
-**What it does:** Check items in each pipeline stage. Flag stuck items (in same stage too long), empty stages, bottlenecks.
-**Config:**
-- `stages` — ordered list of pipeline stages
-- `stuck_threshold_days` — days in one stage before flagging
-**Output:** Pipeline health report, stuck items, stage distribution
-
-## Extending Strategies
-
-Custom strategies can be added for workspace-specific needs. A strategy is defined by:
-1. A name (kebab-case)
-2. What it applies to (description)
-3. What it checks (logic)
-4. What config it needs (parameters)
-5. What it outputs (findings format)
-
-Add custom strategies to this file and reference them in `workspace.json`.
+# Audit Strategies
+
+Reusable audit strategies that can be applied to any workspace area. The workspace manifest (`workspace.json`) maps areas to strategies. The audit command reads the manifest and applies the appropriate strategy to each area.
+
+## Strategies
+
+### staleness
+**Applies to:** Data files (projects.json, state.json, any tracked document)
+**What it does:** Check file modification timestamps against configured thresholds. Flag files past their groom cadence.
+**Config:**
+- `threshold_days` — days after which the file is considered stale
+**Output:** List of stale files with age, recommended action (update or review)
+
+### classify
+**Applies to:** Directories with lifecycle items (projects/, clients/)
+**What it does:** List all items in the directory. For each, present to operator for classification: active, archive, or delete. Check for planning docs, recent activity, git history.
+**Config:**
+- `states` — classification options (default: ["active", "archive", "delete"])
+- `archive_path` — where archived items go (default: `{path}/_archive/`)
+**Output:** Classification decisions, items moved to archive, items deleted
+
+### cross-reference
+**Applies to:** Tools/servers that have a config file mapping (e.g., MCP servers vs .mcp.json)
+**What it does:** Compare directory contents against a configuration file. Identify directories not referenced in config (orphaned) and config entries pointing to missing directories (broken).
+**Config:**
+- `config_file` — path to the configuration file to cross-reference
+**Output:** Orphaned items, broken references, recommendations
+
+### dead-code
+**Applies to:** System directories (hooks, commands, skills)
+**What it does:** Scan for files that appear unused — no references from other files, no recent invocations, no clear purpose. Presents findings for human decision.
+**Config:**
+- `reference_check` — whether to search for references in other files (default: true)
+**Output:** Potentially dead files with evidence, operator decides keep/delete
+
+### pipeline-status
+**Applies to:** Content pipelines, task queues, any workflow with stages
+**What it does:** Check items in each pipeline stage. Flag stuck items (in same stage too long), empty stages, bottlenecks.
+**Config:**
+- `stages` — ordered list of pipeline stages
+- `stuck_threshold_days` — days in one stage before flagging
+**Output:** Pipeline health report, stuck items, stage distribution
+
+## Extending Strategies
+
+Custom strategies can be added for workspace-specific needs. A strategy is defined by:
+1. A name (kebab-case)
+2. What it applies to (description)
+3. What it checks (logic)
+4. What config it needs (parameters)
+5. What it outputs (findings format)
+
+Add custom strategies to this file and reference them in `workspace.json`.