@chrisai/base 2.3.0

package/src/commands/history.md

@@ -0,0 +1,27 @@
+---
+name: base:history
+description: Workspace evolution timeline
+allowed-tools: [Read, Glob, Bash]
+---
+
+<objective>
+Show workspace evolution — grooming history, audits, major changes over time.
+
+**When to use:** "workspace history", "show evolution", "what's changed".
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/history.md
+</execution_context>
+
+<context>
+@.base/STATE.md
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/history.md
+</process>
+
+<success_criteria>
+- [ ] Timeline of workspace events displayed
+</success_criteria>

package/src/commands/pulse.md

@@ -0,0 +1,33 @@
+---
+name: base:pulse
+description: Daily workspace health briefing
+allowed-tools: [Read, Glob, Grep, Bash]
+---
+
+<objective>
+Workspace health briefing — drift score, stale areas, overdue grooming, quick status.
+
+**When to use:** Session start, "what's the state of my workspace", daily check-in.
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/pulse.md
+@.claude/skills/base/context/base-principles.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.base/workspace.json
+@.base/STATE.md
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/pulse.md
+</process>
+
+<success_criteria>
+- [ ] Drift score calculated and displayed
+- [ ] Stale areas identified
+- [ ] Groom cadence checked
+</success_criteria>

package/src/commands/scaffold.md

@@ -0,0 +1,33 @@
+---
+name: base:scaffold
+description: Set up BASE in a new workspace
+argument-hint: "[--full]"
+allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
+---
+
+<objective>
+Guided workspace setup — scan, configure, install BASE infrastructure. Optional --full mode adds operational templates.
+
+**When to use:** First-time BASE installation, "set up base", "scaffold my workspace".
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/scaffold.md
+@.claude/skills/base/templates/workspace-json.md
+@.claude/skills/base/templates/state-md.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/scaffold.md
+</process>
+
+<success_criteria>
+- [ ] .base/ directory structure created
+- [ ] workspace.json generated from scan
+- [ ] STATE.md initialized
+- [ ] Hooks and MCP servers installed (if --full)
+</success_criteria>

package/src/commands/status.md

@@ -0,0 +1,28 @@
+---
+name: base:status
+description: Quick workspace health check
+allowed-tools: [Read, Glob, Bash]
+---
+
+<objective>
+One-liner workspace health status — drift score and area summary.
+
+**When to use:** Quick check, "workspace status", "how's my workspace".
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/status.md
+</execution_context>
+
+<context>
+@.base/workspace.json
+@.base/STATE.md
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/status.md
+</process>
+
+<success_criteria>
+- [ ] Health status displayed
+</success_criteria>

package/src/commands/surface-convert.md

@@ -0,0 +1,35 @@
+---
+name: base:surface-convert
+description: Convert a markdown file into a data surface
+argument-hint: "<file-path>"
+allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
+---
+
+<objective>
+Convert an existing @-mentioned markdown file into a structured data surface. Analyzes structure, proposes schema, migrates content.
+
+**When to use:** User has a markdown file they want to convert to a structured surface.
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/surface-convert.md
+@.base/hooks/_template.py
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.base/workspace.json
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/surface-convert.md
+</process>
+
+<success_criteria>
+- [ ] .base/data/{name}.json created with migrated items
+- [ ] .base/hooks/{name}-hook.py created
+- [ ] workspace.json updated with surface registration
+- [ ] settings.json updated with hook entry
+- [ ] Original markdown file preserved
+</success_criteria>

package/src/commands/surface-create.md

@@ -0,0 +1,34 @@
+---
+name: base:surface-create
+description: Create a new data surface (guided)
+argument-hint: "[surface-name]"
+allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
+---
+
+<objective>
+Create a new data surface through guided conversation. Generates JSON data file, injection hook, workspace.json registration, and settings.json hook entry.
+
+**When to use:** User wants to track something new as a structured data surface.
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/surface-create.md
+@.base/hooks/_template.py
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.base/workspace.json
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/surface-create.md
+</process>
+
+<success_criteria>
+- [ ] .base/data/{name}.json created
+- [ ] .base/hooks/{name}-hook.py created
+- [ ] workspace.json updated with surface registration
+- [ ] settings.json updated with hook entry
+</success_criteria>

package/src/commands/surface-list.md

@@ -0,0 +1,27 @@
+---
+name: base:surface-list
+description: Show all registered data surfaces
+allowed-tools: [Read, Bash]
+---
+
+<objective>
+Display all registered data surfaces with item counts and hook status.
+
+**When to use:** User wants to see what surfaces exist.
+</objective>
+
+<execution_context>
+@.claude/skills/base/tasks/surface-list.md
+</execution_context>
+
+<context>
+@.base/workspace.json
+</context>
+
+<process>
+Follow task: @.claude/skills/base/tasks/surface-list.md
+</process>
+
+<success_criteria>
+- [ ] All registered surfaces displayed with counts
+</success_criteria>

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

@@ -0,0 +1,71 @@
+# 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 |
+|------|----------------|---------|
+| ACTIVE.md | Every session or weekly | workspace.json |
+| BACKLOG.md | Weekly groom | 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.md when the operator is ready to work on them.
+
+```
+BACKLOG (waiting review)
+  → ACTIVE.md TASKS (standalone, bounded work items)
+  → ACTIVE.md PROJECT (complex work warranting its own project entry)
+  → DONE (closed with outcome + date)
+```
+
+**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 task that loses priority can return to backlog. 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, STATE.md, ROADMAP.md. Scans and tracks what exists. Framework-agnostic.
+- **Full** (`/base:scaffold --full`) — Data layer + operational templates. Creates ACTIVE.md, BACKLOG.md from templates. Offers CLAUDE.md audit. Sets up symlinks. 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 state files (ACTIVE.md, BACKLOG.md, STATE.md, workspace.json, ROADMAP.md) live in `.base/`. Symlinks at workspace root are a **migration tool only** — offered when existing references (CLAUDE.md @mentions, hooks) would break. New installations never need symlinks. `.base/` is the canonical location.

package/src/framework/frameworks/audit-strategies.md

@@ -0,0 +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:** Working memory files (ACTIVE.md, BACKLOG.md, 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`.

package/src/framework/frameworks/satellite-registration.md

@@ -0,0 +1,44 @@
+# Satellite Registration Framework
+
+## What Are Satellites
+
+Satellites are projects that live in their own git repos inside the workspace (e.g., `apps/*`). They run their own Claude Code sessions independently. BASE needs visibility into them without owning them.
+
+## Registration Flow
+
+### Automatic (via PAUL init)
+When `/paul:init` runs in a subdirectory:
+1. Check if parent directory has `.base/workspace.json`
+2. If yes, write registration entry: project name, path, engine type, state file path, date
+3. Report: "Registered with BASE workspace: {workspace-name}"
+
+### Automatic (via BASE scaffold)
+When `/base:scaffold` runs:
+1. Scan configured satellite directories (default: `apps/`)
+2. Detect existing `.paul/` directories
+3. Auto-register discovered projects
+4. Report: "Found {N} satellite projects. Registered."
+
+### Automatic (via BASE groom)
+During groom:
+1. Read registered satellites from workspace.json
+2. Check each path exists (clean up broken registrations)
+3. Scan satellite directories for unregistered projects with `.paul/`
+4. Flag: "Found unregistered project: {name}. Register?"
+
+## Health Checks
+
+During `/base:pulse` and `/base:groom`, for each satellite:
+1. Read the state file (e.g., `.paul/STATE.md`)
+2. Check last modification date
+3. Extract current phase/milestone if parseable
+4. Report health: active, stale, or unknown
+
+BASE never modifies satellite state. It only reads and reports. PAUL (or whatever engine) manages the project. BASE manages the workspace those projects live in.
+
+## Deregistration
+
+Satellites are deregistered when:
+- The project directory no longer exists (auto-cleaned during groom)
+- The user explicitly removes it during audit
+- The project is archived (moved to `_archive/` or similar)

package/src/framework/tasks/audit-claude-md.md

@@ -0,0 +1,68 @@
+<purpose>
+Audit an existing CLAUDE.md and generate a recommended alternative (CLAUDE.base.md) that follows BASE workspace conventions. Never overwrites the user's existing file.
+</purpose>
+
+<user-story>
+As an AI builder setting up BASE, I want my CLAUDE.md audited against best practices, so that I get a recommended version I can adopt without losing my current config.
+</user-story>
+
+<when-to-use>
+- During /base:scaffold (optional step)
+- When user says "audit my claude.md", "improve my claude.md"
+- Entry point routes here via /base:audit-claude-md
+</when-to-use>
+
+<steps>
+
+<step name="read_existing" priority="first">
+Read the user's existing CLAUDE.md.
+
+1. Read `CLAUDE.md` from workspace root
+2. If no CLAUDE.md exists, skip audit and generate fresh from template
+3. Parse sections: identify what's covered (identity, structure, conventions, tool config, etc.)
+4. Note what's missing vs BASE best practices
+</step>
+
+<step name="assess_and_recommend">
+Compare against BASE workspace conventions.
+
+Check for:
+- [ ] Working memory references (@ACTIVE.md, @BACKLOG.md, @STATE.md)
+- [ ] Workspace structure tree (accurate to actual filesystem?)
+- [ ] Git strategy documentation
+- [ ] Tool priority declarations (LSP, etc.)
+- [ ] Business/identity context (who, what, why)
+- [ ] CARL/BASE integration references
+- [ ] Key locations table
+- [ ] Documentation system description
+- [ ] Banned words / style preferences
+
+For each missing or outdated section, prepare a recommendation.
+</step>
+
+<step name="generate_alternative">
+Generate CLAUDE.base.md as a recommended version.
+
+1. Build a complete CLAUDE.md following BASE conventions
+2. Preserve all existing content that's still accurate
+3. Add missing sections from BASE template
+4. Update workspace structure tree to match actual filesystem
+5. Write to `CLAUDE.base.md` (NOT CLAUDE.md)
+6. Present diff summary: "Here's what changed vs your current CLAUDE.md"
+
+Tell user: "Review CLAUDE.base.md. If you want to adopt it, rename it to CLAUDE.md. Your original is untouched."
+</step>
+
+</steps>
+
+<output>
+CLAUDE.base.md file in workspace root — a recommended CLAUDE.md following BASE conventions. Original CLAUDE.md is never modified.
+</output>
+
+<acceptance-criteria>
+- [ ] Existing CLAUDE.md read and analyzed
+- [ ] All BASE best-practice sections checked
+- [ ] CLAUDE.base.md generated with recommendations
+- [ ] Original CLAUDE.md untouched
+- [ ] User informed of differences and how to adopt
+</acceptance-criteria>

package/src/framework/tasks/audit.md

@@ -0,0 +1,64 @@
+<purpose>
+Deep workspace optimization. Dynamically generate audit phases from the workspace manifest, run each area's configured audit strategy, and execute operator-approved changes.
+</purpose>
+
+<user-story>
+As an AI builder, I want a thorough workspace audit that adapts to my workspace structure, so that every area gets properly reviewed regardless of how complex my setup is.
+</user-story>
+
+<when-to-use>
+- Quarterly or after major workspace shifts
+- When user says "base audit", "deep clean", "optimize workspace"
+- Entry point routes here via /base:audit
+</when-to-use>
+
+<steps>
+
+<step name="generate_phases" priority="first">
+Read workspace manifest and generate audit phases dynamically.
+
+1. Read `.base/workspace.json`
+2. For each area, create an audit phase using its configured strategy
+3. Present phase list: "Audit will cover {N} phases: {list with strategies}"
+4. Create task tracking for each phase
+
+**Wait for operator confirmation. Allow them to skip or reorder phases.**
+</step>
+
+<step name="execute_phases">
+Run each phase using its configured audit strategy.
+
+For each phase:
+1. Announce: "Phase {N}: {area-name} ({strategy})"
+2. Execute the strategy (reference frameworks/audit-strategies.md)
+3. Present findings
+4. Collect operator decisions (keep/archive/delete/move)
+5. Execute approved changes
+6. Mark phase complete
+
+Strategies are documented in `@frameworks/audit-strategies.md`.
+</step>
+
+<step name="record_audit">
+Record the audit results.
+
+1. Update `.base/STATE.md`
+2. Write audit record to `.base/audits/{YYYY-MM-DD}.md`
+3. Log to `.base/ROADMAP.md`
+4. Report final summary: phases completed, items changed, new drift score
+</step>
+
+</steps>
+
+<output>
+Complete workspace audit with dynamic phases. All areas reviewed, changes executed, audit recorded.
+</output>
+
+<acceptance-criteria>
+- [ ] Phases generated dynamically from manifest (not hardcoded)
+- [ ] Each area audited using its configured strategy
+- [ ] Operator approved all changes before execution
+- [ ] Audit record written to audits/ directory
+- [ ] STATE.md updated
+- [ ] ROADMAP.md updated with audit entry
+</acceptance-criteria>