@chrisai/base 2.3.0

package/src/framework/tasks/surface-convert.md

@@ -0,0 +1,143 @@
+<purpose>
+Convert an existing @-mentioned markdown file into a structured data surface. Analyzes the markdown structure, proposes a schema, migrates content, and generates all surface artifacts (JSON, hook, registration).
+</purpose>
+
+<user-story>
+As an AI builder, I want to convert my existing markdown tracking files into structured surfaces so Claude gets cheap passive awareness instead of expensive @-file parsing.
+</user-story>
+
+<when-to-use>
+- /base:surface convert {file-path}
+- "convert this file to a surface", "make this a data surface"
+- User has a markdown file they @-mention regularly and wants it structured
+</when-to-use>
+
+<context>
+@.base/hooks/_template.py
+@.base/workspace.json
+</context>
+
+<steps>
+
+<step name="read" priority="first">
+## Step 1: Read & Analyze
+
+1. Read the specified markdown file completely
+2. Detect structure:
+   - **Headings** → potential categories or priority groups
+   - **Bold labels** (e.g., `**Status:**`) → field names
+   - **List items** → individual entries
+   - **Checkboxes** → checklist/progress fields
+   - **Dates** → timestamp fields
+   - **File paths** → location fields
+   - **Tables** → structured data (archived items, reference tables)
+3. Identify patterns:
+   - How many distinct items?
+   - What fields recur across items?
+   - Are there priority/status groupings?
+   - Is there an archived/done section?
+
+Present findings:
+```
+Detected structure in {file}:
+  Items found: {count}
+  Sections: {list of heading-based groups}
+  Recurring fields: {field names}
+  Archived section: {yes/no}
+```
+</step>
+
+<step name="propose">
+## Step 2: Propose Schema
+
+Based on analysis, propose:
+
+1. **Surface name** — infer from filename (e.g., ACTIVE.md → "active")
+2. **Schema** — field names, types, required fields, ID prefix
+3. **Sample conversion** — show 2-3 items converted to JSON
+
+```
+Proposed schema for "{name}":
+  ID prefix: {PREFIX}
+  Required: {fields}
+  Optional: {fields}
+  Priority levels: {if detected}
+
+Sample conversion:
+  "{heading item}" →
+  {
+    "id": "PREFIX-001",
+    "title": "...",
+    "status": "...",
+    ...
+  }
+```
+
+Ask: "Does this schema look right? Adjust anything?"
+
+**Wait for response.**
+</step>
+
+<step name="confirm">
+## Step 3: Confirm
+
+Apply any user adjustments to the schema. Lock it for generation.
+
+If user is satisfied, confirm:
+"Schema locked. I'll generate the surface and migrate {count} items."
+</step>
+
+<step name="generate">
+## Step 4: Generate Artifacts
+
+Same generation as surface-create Step 5:
+- `.base/data/{name}.json` — with migrated items (not empty)
+- `.base/hooks/{name}-hook.py` — from _template.py with appropriate grouping
+- workspace.json surface registration
+- settings.json hook entry
+
+Include staleness detection with sensible defaults based on detected priority levels.
+</step>
+
+<step name="migrate">
+## Step 5: Migrate Content
+
+Parse every item from the markdown into JSON entries:
+- Map heading groups to priority/category fields
+- Map bold labels to field values
+- Preserve checklists as arrays of {text, done} objects
+- Preserve dates in ISO format
+- Preserve file paths as location fields
+- Map done/closed/archived sections to the archived array
+
+Report:
+```
+Migration complete:
+  Items migrated: {count}
+  Archived items: {count}
+  Unmapped items: {count, if any — list them}
+```
+
+If any items couldn't be auto-mapped, present them for manual resolution.
+</step>
+
+<step name="cleanup">
+## Step 6: Clean Up
+
+1. Check if the original file is @-referenced in CLAUDE.md
+2. If found, offer: "Remove @{file} from CLAUDE.md? The surface hook replaces it."
+3. Suggest: "Original file preserved at {path} for reference."
+
+Do NOT delete the original markdown file — the user decides its fate.
+</step>
+
+</steps>
+
+<verification>
+After conversion:
+- [ ] .base/data/{name}.json exists with migrated items
+- [ ] Item count matches source markdown
+- [ ] .base/hooks/{name}-hook.py exists and produces output
+- [ ] workspace.json and settings.json updated
+- [ ] Original markdown file is untouched
+</verification>

package/src/framework/tasks/surface-create.md

@@ -0,0 +1,184 @@
+<purpose>
+Create a new data surface through guided conversation. Generates: JSON data file, injection hook, workspace.json registration, and settings.json hook entry. The user answers questions; Claude generates everything.
+</purpose>
+
+<user-story>
+As an AI builder, I want to create custom data surfaces so Claude has structured, passive awareness of any domain I track — without manually wiring JSON files, hooks, and config.
+</user-story>
+
+<when-to-use>
+- /base:surface create {name}
+- "create a surface", "add a new surface", "I want to track X"
+- User wants structured data with hook injection and MCP access
+</when-to-use>
+
+<context>
+@.base/hooks/_template.py
+@.base/workspace.json
+</context>
+
+<steps>
+
+<step name="define" priority="first">
+## Step 1: Define
+
+Extract surface name from args or ask: "What should this surface be called? (lowercase, no spaces)"
+
+**Validate:**
+1. Name is lowercase, alphanumeric + hyphens only
+2. Not already registered in workspace.json surfaces section
+3. No reserved names: "active", "backlog", "psmm", "staging"
+
+Ask: "What does this surface track? (one sentence)"
+→ This becomes the `description` in workspace.json.
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="schema">
+## Step 2: Schema
+
+Ask: "What fields does each item need?"
+
+Guide through these decisions (one at a time):
+
+1. **Required fields** — What must every item have?
+   - Default minimum: `["title"]`
+   - Common additions: status, priority, category, assignee, due_date
+
+2. **ID prefix** — Auto-suggest first 3 chars of name, uppercase.
+   - e.g., surface "clients" → prefix "CLI"
+   - User can override
+
+3. **Priority/status enums** — If the surface has priority or status fields:
+   - Ask: "What priority levels?" (e.g., high, medium, low)
+   - Ask: "What status values?" (e.g., active, pending, done)
+
+4. **Time rules** (optional) — If the surface benefits from review-by dates:
+   - Ask: "Should items have review-by deadlines? If so, how many days per priority level?"
+   - Default: none
+
+Build the schema object from answers:
+```json
+{
+  "id_prefix": "CLI",
+  "required_fields": ["title", "status"],
+  "priority_levels": ["high", "medium", "low"],
+  "status_values": ["active", "pending", "done"]
+}
+```
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="injection">
+## Step 3: Injection
+
+Ask: "How should items appear in Claude's context each prompt?"
+
+Guide through:
+
+1. **Grouping** — How to organize items in the injection?
+   - By priority (default) | By status | By date | Flat (no grouping)
+
+2. **Summary format** — What fields to show per line?
+   - Default: `- [ID] Title (status)`
+   - Can add: priority tag, due date, custom field
+
+3. **Staleness thresholds** — Days before an item is flagged STALE per priority:
+   - Suggest defaults based on priority levels from Step 2
+   - e.g., high: 5d, medium: 10d, low: 30d
+   - User can adjust
+
+4. **Behavioral mode:**
+   - Silent (default) — passive awareness, respond only when asked
+   - Proactive — mention items unprompted (rare, use for critical surfaces)
+   - Threshold — stay silent unless deadline/staleness threshold crossed
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="tools">
+## Step 4: Tools (Informational)
+
+Inform the user:
+
+"All 7 BASE MCP tools work automatically with your new surface:
+- `base_list_surfaces` — see all surfaces
+- `base_get_surface("{name}")` — read all items
+- `base_get_item("{name}", id)` — get specific item
+- `base_add_item("{name}", data)` — add new item (validates required fields, auto-generates ID)
+- `base_update_item("{name}", id, data)` — update fields (resets staleness clock)
+- `base_archive_item("{name}", id)` — move to archived
+- `base_search(query, "{name}")` — search items
+
+No configuration needed — BASE MCP auto-discovers surfaces from workspace.json."
+
+**Continue to generation.**
+</step>
+
+<step name="generate" priority="critical">
+## Step 5: Generate
+
+Create all artifacts:
+
+**1. Data file:** `.base/data/{name}.json`
+```json
+{
+  "surface": "{name}",
+  "version": 1,
+  "last_modified": "{timestamp}",
+  "items": [],
+  "archived": []
+}
+```
+
+**2. Hook file:** `.base/hooks/{name}-hook.py`
+- Read `.base/hooks/_template.py` as the starting point
+- Customize SURFACE_NAME, grouping logic, summary format, staleness thresholds, behavioral directive
+- Use the injection decisions from Step 3
+- Include `from datetime import date` for staleness calculation
+- Follow the _template.py contract exactly
+
+**3. Registration:** Add to `.base/workspace.json` surfaces section:
+```json
+"{name}": {
+  "file": "data/{name}.json",
+  "description": "{description from Step 1}",
+  "hook": true,
+  "silent": true,
+  "schema": { ...schema from Step 2... }
+}
+```
+
+**4. Hook registration:** Add to `.claude/settings.json` UserPromptSubmit hooks:
+```json
+{
+  "type": "command",
+  "command": "python3 {absolute_workspace_path}/.base/hooks/{name}-hook.py"
+}
+```
+Use absolute path resolved from workspace root.
+
+**5. Report:**
+```
+Surface "{name}" created:
+  Data:     .base/data/{name}.json (empty, ready for items)
+  Hook:     .base/hooks/{name}-hook.py (will inject next prompt)
+  Schema:   {id_prefix}-NNN, {required_fields}
+  Tools:    base_get_item("{name}", id), base_add_item("{name}", data), etc.
+
+Add your first item: base_add_item("{name}", {title: "..."})
+```
+</step>
+
+</steps>
+
+<verification>
+After generation:
+- [ ] .base/data/{name}.json exists and is valid JSON
+- [ ] .base/hooks/{name}-hook.py exists and parses as valid Python
+- [ ] workspace.json has the surface registration
+- [ ] settings.json has the hook entry with absolute path
+- [ ] Hook outputs correct XML when piped test input
+</verification>

package/src/framework/tasks/surface-list.md

@@ -0,0 +1,42 @@
+<purpose>
+Display all registered data surfaces with item counts, hook status, and staleness summary.
+</purpose>
+
+<when-to-use>
+- /base:surface list
+- "what surfaces exist", "show surfaces", "list surfaces"
+</when-to-use>
+
+<steps>
+
+<step name="read_and_display">
+## Show Surfaces
+
+1. Call `base_list_surfaces` to get all registered surfaces with item counts
+2. For each surface, read the data file to count stale items (items with no `updated` field or `updated` older than threshold)
+
+Display as:
+
+```
+Data Surfaces
+═══════════════════════════════════════
+
+| Surface | Items | Hook | Description |
+|---------|-------|------|-------------|
+| active  | 12    | ✓    | Active work items, projects, and tasks |
+| backlog | 8     | ✓    | Future work queue, ideas, and deferred tasks |
+
+Total: {count} surfaces, {total_items} items
+
+Create a new surface: /base:surface create {name}
+Convert a file:      /base:surface convert {path}
+```
+
+If no surfaces registered:
+```
+No data surfaces registered.
+Run /base:surface create {name} to create your first surface.
+```
+</step>
+
+</steps>

package/src/framework/templates/active-md.md

@@ -0,0 +1,112 @@
+# ACTIVE.md Template
+
+Output file: `.base/ACTIVE.md`
+
+Symlink at workspace root: `ACTIVE.md → .base/ACTIVE.md` (for backward compatibility with hooks and rules that reference root-level ACTIVE.md)
+
+```template
+# Active Work
+
+> **Working memory for Claude Code sessions.** Read at session start, update as work progresses.
+> This is NOT documentation - it's task tracking. Obsidian handles the knowledge graph.
+>
+> **Update workflow:** Claude asks status questions → User responds via voice → Claude updates this file.
+> **Not active?** → Move to `BACKLOG.md` for future work queue.
+> **Graduation:** Backlog items move here (as TASKS or under a PROJECT) when they get attention.
+
+---
+
+## URGENT
+
+[Projects with hard deadlines or critical momentum. Max 2-3 at a time.]
+
+### {Project Name}
+**Status:** [Current state — be specific]
+**Location:** `{path/to/project/}`
+**Deadline:** {YYYY-MM-DD}
+**Next:** [Single most important next action]
+**Blocked:** [What's preventing progress, or "None"]
+**Notes:** [Context that helps a fresh session understand this project]
+
+---
+
+## HIGH PRIORITY
+
+[Projects in active development without hard deadlines.]
+
+### {Project Name}
+**Status:** [Current state]
+**Location:** `{path/to/project/}`
+**Target:** [Target date or milestone, if any]
+**Next:** [Single most important next action]
+**Blocked:** [What's preventing progress, or "None"]
+**Notes:** [Context]
+
+---
+
+## ONGOING
+
+[Always-running work. No end date. Check in during groom.]
+
+### {Project Name}
+**Status:** [Current state]
+**Location:** `{path/to/project/}`
+**Next:** [What to do next or maintain]
+**Notes:** [Context]
+
+---
+
+## TASKS
+
+> Standalone work items graduated from backlog. Bounded, not ongoing. Close when done.
+
+### {Task Name}
+**Status:** [In Progress | Blocked | Ready]
+**Next:** [What needs to happen]
+**Blocked:** [Dependencies, or "None"]
+**Notes:** [Context. Include backlog origin if relevant.]
+
+---
+
+## DEFERRED
+
+[Paused work. Revisit during groom.]
+
+---
+
+## DONE / CLOSED
+
+| Project/Task | Outcome | Date |
+|-------------|---------|------|
+| {name} | {what happened} | {YYYY-MM-DD or Mon YYYY} |
+
+---
+
+## Quick Reference
+
+| Project | Status | Priority |
+|---------|--------|----------|
+| {name} | {status} | **{URGENT/HIGH/MEDIUM/ONGOING}** |
+```
+
+## Field Documentation
+
+| Field | Purpose | Update Cadence |
+|-------|---------|---------------|
+| Status | Current state of the project — be specific, not generic | Every session or when it changes |
+| Location | Path to project folder or app directory | Set once, update on moves |
+| Deadline | Hard deadline if one exists | Set once, update if it moves |
+| Target | Soft target or milestone | Set once, update as needed |
+| Next | THE single next action. Not a list. One thing. | Every session |
+| Blocked | What's preventing progress. Forces clarity. | Update when blockers change |
+| Notes | Context for a fresh Claude session to understand the project | Update when major shifts happen |
+
+## Section Rules
+
+| Section | What Goes Here | Graduation Path |
+|---------|---------------|----------------|
+| URGENT | Hard deadlines, critical momentum | → DONE when shipped |
+| HIGH | Active development, no hard deadline | → DONE when shipped, or → DEFERRED if paused |
+| ONGOING | No end date, maintain indefinitely | Never closes, just evolves |
+| TASKS | Bounded work from backlog. Has a finish line. | → DONE when complete |
+| DEFERRED | Paused. Revisit during groom. | → Back to active, or → DONE/killed |

package/src/framework/templates/backlog-md.md

@@ -0,0 +1,100 @@
+# BACKLOG.md Template
+
+Output file: `.base/BACKLOG.md`
+
+Symlink at workspace root: `BACKLOG.md → .base/BACKLOG.md` (for backward compatibility)
+
+```template
+# Backlog
+
+> **Future work, ideas, and deferred tasks.** Not actively working on these - they're queued.
+> For active work, see `ACTIVE.md`. For project details, see `projects/{name}/PLANNING.md`.
+>
+> **Graduation:** Items move to ACTIVE.md (as TASKS or PROJECTS) during groom when ready to work on.
+> **Time-based rules:** Items have review-by dates. Past review-by = "decide or kill." Past staleness = auto-archive.
+
+**Last reviewed:** {YYYY-MM-DD}
+
+---
+
+## Quick Capture
+
+> Raw ideas. Process into proper entries during groom.
+
+- {idea}
+
+---
+
+## High Priority Queue
+
+> Next up when capacity opens. Ready to start. Review-by: 7 days.
+
+### {Item Name}
+**Priority:** High
+**Location:** `{path/}` (if applicable)
+**Planning:** `{projects/{name}/PLANNING.md}` (if complex)
+**Context:** [Why this matters, background info]
+**Next Steps:**
+- [ ] [First action]
+- [ ] [Second action]
+**Added:** {YYYY-MM-DD}
+**Notes:** [Additional context]
+
+---
+
+## Medium Priority
+
+> Important but not urgent. Review-by: 14 days.
+
+### {Item Name}
+**Priority:** Medium
+**Location:** `{path/}`
+**Context:** [Why this matters]
+**Next Steps:**
+- [ ] [First action]
+**Added:** {YYYY-MM-DD}
+
+---
+
+## Low Priority / Someday
+
+> Nice to have. May never happen. Review-by: 30 days.
+
+---
+
+## Processing Rules
+
+1. **Quick Capture** → dump raw idea, process during groom
+2. **Groom Review** → convert captures to proper entries with context
+3. **Time-based enforcement:**
+   - High: review-by 7 days from Added date
+   - Medium: review-by 14 days from Added date
+   - Low: review-by 30 days from Added date
+   - Staleness = 2x review-by → auto-archive with note
+4. **Graduate** → move to ACTIVE.md TASKS (bounded) or PROJECT (complex)
+5. **Kill** → delete if no longer relevant
+6. **Archive** → keep for reference but remove from active backlog
+```
+
+## Field Documentation
+
+| Field | Purpose | Required? |
+|-------|---------|-----------|
+| Priority | Determines review-by threshold (H:7d, M:14d, L:30d) | Yes |
+| Location | Path to relevant code/docs | If applicable |
+| Planning | Link to PLANNING.md if complex | If applicable |
+| Context | Why this matters — enough for a fresh session to understand | Yes |
+| Next Steps | Concrete actions, not vague goals | Yes (at least 1) |
+| Added | Date item entered backlog — drives time-based rules | Yes |
+| Blocked by | Other backlog items or projects this depends on | If applicable |
+| Notes | Extra context, links, decisions | Optional |
+
+## Graduation Criteria
+
+An item is ready to graduate from backlog when:
+- It has clear next steps defined
+- The operator has capacity to work on it
+- Any blockers have been resolved
+- The operator explicitly says "let's do this" during groom
+
+**Graduation is never automatic.** The groom flow asks: "Ready to work on any of these?" The operator decides.

package/src/framework/templates/state-md.md

@@ -0,0 +1,48 @@
+# STATE.md Template
+
+Output file: `.base/STATE.md`
+
+```template
+# BASE — Workspace State
+
+**Workspace:** {workspace-name}
+**Last Groom:** {YYYY-MM-DD}
+**Groom Cadence:** {cadence} ({day})
+**Next Groom Due:** {YYYY-MM-DD}
+**Drift Score:** {0-N}
+
+## Health
+
+| Area | Status | Last Touched | Groom Due |
+|------|--------|-------------|-----------|
+| {area-name} | {Current|Stale|Critical} | {YYYY-MM-DD} | {YYYY-MM-DD} |
+
+## Satellites
+
+| Project | Engine | Phase | Last Activity |
+|---------|--------|-------|--------------|
+| {project-name} | {paul|custom} | {current-phase} | {YYYY-MM-DD} |
+
+## Drift Indicators
+
+- ACTIVE.md age: {N} days
+- BACKLOG.md age: {N} days
+- Backlog items past review-by: {N}
+- Orphaned session contexts: {N}
+- Untracked root files: {N}
+- Satellites with stale state: {N}
+
+## Last Audit
+
+**Date:** {YYYY-MM-DD}
+**Phases:** {N}
+**Outcome:** [Brief summary of what was cleaned/changed]
+```
+
+## Status Values
+
+| Status | Meaning | Drift Contribution |
+|--------|---------|-------------------|
+| Current | Within groom cadence | 0 |
+| Stale | Past groom cadence by 1-2x | Days overdue |
+| Critical | Past groom cadence by 2x+ | Days overdue (weighted 2x) |

package/src/framework/templates/workspace-json.md

@@ -0,0 +1,50 @@
+# Workspace Manifest Template
+
+Output file: `.base/workspace.json`
+
+```template
+{
+  "workspace": "{workspace-name}",
+  "created": "{YYYY-MM-DD}",
+  "groom_cadence": "{weekly|bi-weekly|monthly}",
+  "groom_day": "{day-of-week}",
+  "areas": {
+    "{area-name}": {
+      "type": "{working-memory|directory|config-cross-ref|system-layer|custom}",
+      "description": "[Human-readable purpose of this area]",
+      "paths": ["{file-or-directory-paths}"],
+      "groom": "{weekly|bi-weekly|monthly}",
+      "audit": {
+        "strategy": "{staleness|classify|cross-reference|dead-code|pipeline-status}",
+        "config": {}
+      }
+    }
+  },
+  "satellites": {
+    "{project-name}": {
+      "path": "{relative-path-to-project}",
+      "engine": "{paul|custom|none}",
+      "state": "{path-to-state-file}",
+      "registered": "{YYYY-MM-DD}"
+    }
+  }
+}
+```
+
+## Field Documentation
+
+| Field | Type | Description |
+|-------|------|------------|
+| workspace | string | Name of this workspace (typically the directory name) |
+| created | date | When BASE was initialized in this workspace |
+| groom_cadence | enum | Default grooming frequency for the workspace |
+| groom_day | string | Preferred day for weekly grooming |
+| areas | object | Map of tracked workspace areas |
+| areas.*.type | enum | Classification of the area for audit strategy selection |
+| areas.*.paths | array | Files or directories this area tracks |
+| areas.*.groom | enum | Grooming frequency for this specific area (overrides default) |
+| areas.*.audit.strategy | enum | Which audit strategy to apply (see audit-strategies.md) |
+| areas.*.audit.config | object | Strategy-specific configuration |
+| satellites | object | External projects tracked by BASE but managed by their own engines |
+| satellites.*.engine | enum | What orchestration tool manages this project |
+| satellites.*.state | string | Path to the project's state file for health checks |