@chrisai/base 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +157 -0
  2. package/bin/install.js +340 -0
  3. package/package.json +40 -0
  4. package/src/commands/audit-claude-md.md +31 -0
  5. package/src/commands/audit.md +33 -0
  6. package/src/commands/carl-hygiene.md +33 -0
  7. package/src/commands/groom.md +35 -0
  8. package/src/commands/history.md +27 -0
  9. package/src/commands/pulse.md +33 -0
  10. package/src/commands/scaffold.md +33 -0
  11. package/src/commands/status.md +28 -0
  12. package/src/commands/surface-convert.md +35 -0
  13. package/src/commands/surface-create.md +34 -0
  14. package/src/commands/surface-list.md +27 -0
  15. package/src/framework/context/base-principles.md +71 -0
  16. package/src/framework/frameworks/audit-strategies.md +53 -0
  17. package/src/framework/frameworks/satellite-registration.md +44 -0
  18. package/src/framework/tasks/audit-claude-md.md +68 -0
  19. package/src/framework/tasks/audit.md +64 -0
  20. package/src/framework/tasks/carl-hygiene.md +160 -0
  21. package/src/framework/tasks/groom.md +164 -0
  22. package/src/framework/tasks/history.md +34 -0
  23. package/src/framework/tasks/pulse.md +83 -0
  24. package/src/framework/tasks/scaffold.md +167 -0
  25. package/src/framework/tasks/status.md +35 -0
  26. package/src/framework/tasks/surface-convert.md +143 -0
  27. package/src/framework/tasks/surface-create.md +184 -0
  28. package/src/framework/tasks/surface-list.md +42 -0
  29. package/src/framework/templates/active-md.md +112 -0
  30. package/src/framework/templates/backlog-md.md +100 -0
  31. package/src/framework/templates/state-md.md +48 -0
  32. package/src/framework/templates/workspace-json.md +50 -0
  33. package/src/hooks/_template.py +129 -0
  34. package/src/hooks/active-hook.py +115 -0
  35. package/src/hooks/backlog-hook.py +107 -0
  36. package/src/hooks/base-pulse-check.py +206 -0
  37. package/src/hooks/psmm-injector.py +67 -0
  38. package/src/hooks/satellite-detection.py +131 -0
  39. package/src/packages/base-mcp/index.js +108 -0
  40. package/src/packages/base-mcp/package.json +10 -0
  41. package/src/packages/base-mcp/tools/surfaces.js +404 -0
  42. package/src/packages/carl-mcp/index.js +115 -0
  43. package/src/packages/carl-mcp/package.json +10 -0
  44. package/src/packages/carl-mcp/tools/decisions.js +269 -0
  45. package/src/packages/carl-mcp/tools/domains.js +361 -0
  46. package/src/packages/carl-mcp/tools/psmm.js +204 -0
  47. package/src/packages/carl-mcp/tools/staging.js +245 -0
  48. package/src/skill/base.md +111 -0
@@ -0,0 +1,160 @@
1
+ <purpose>
2
+ Structured CARL domain maintenance. Review staged proposals, flag stale rules, audit domain health, and keep CARL lean and accurate.
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder, I want a guided CARL maintenance session, so that my domain rules stay relevant, staged proposals get decided on, and CARL doesn't become a dumping ground of stale rules.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - Monthly (on configured cadence)
11
+ - When pulse reports overdue CARL hygiene
12
+ - When user says "carl hygiene", "review carl rules", "clean up carl"
13
+ - Entry point routes here via /base:carl-hygiene
14
+ </when-to-use>
15
+
16
+ <steps>
17
+
18
+ <step name="assess" priority="first">
19
+ Gather CARL health data and present summary.
20
+
21
+ 1. Read `.base/workspace.json` for `carl_hygiene` config (threshold, max rules, last run)
22
+ 2. Read `.base/staging.json` for pending proposals (via `carl_get_staged`)
23
+ 3. For each domain file in `.carl/`:
24
+ - Count rules
25
+ - Parse metadata comments (`# Last reviewed:` lines)
26
+ - Flag rules where last_reviewed is older than `staleness_threshold_days`
27
+ - Flag domains exceeding `max_rules_per_domain`
28
+ 4. Present summary:
29
+ ```
30
+ CARL Hygiene Assessment
31
+ ━━━━━━━━━━━━━━━━━━━━━━
32
+ Staged proposals: {N} pending
33
+ Domains: {N} total, {N} with stale rules, {N} over max
34
+ Total rules: {N} across all domains
35
+ Last hygiene: {date or "never"}
36
+ ```
37
+
38
+ **Wait for operator confirmation before proceeding.**
39
+ </step>
40
+
41
+ <step name="review_proposals">
42
+ Process each pending staged proposal.
43
+
44
+ For each pending proposal from `carl_get_staged`:
45
+ 1. Present:
46
+ ```
47
+ Proposal {id} — {domain}
48
+ Proposed: {date} | Source: {source}
49
+ Rule: "{rule_text}"
50
+ Rationale: {rationale}
51
+ ```
52
+ 2. Ask: "**Approve**, **Kill**, **Archive**, or **Defer**?"
53
+ 3. Execute:
54
+ - Approve → `carl_approve_proposal(id)` (writes rule to domain file with metadata)
55
+ - Kill → `carl_kill_proposal(id)`
56
+ - Archive → `carl_archive_proposal(id)`
57
+ - Defer → skip (stays pending for next hygiene)
58
+
59
+ **After approval:** Add metadata comments above the new rule in the domain file:
60
+ ```
61
+ # Rule added: {today}
62
+ # Last reviewed: {today}
63
+ # Source: {proposal.source}
64
+ {DOMAIN}_RULE_{N}={rule_text}
65
+ ```
66
+
67
+ Process one proposal at a time. Wait for response between each.
68
+ </step>
69
+
70
+ <step name="review_stale_rules">
71
+ Review rules flagged as stale (last_reviewed > threshold).
72
+
73
+ For each domain with stale rules:
74
+ 1. Present domain name and total rule count
75
+ 2. For each stale rule:
76
+ ```
77
+ [{DOMAIN}] Rule {N} — last reviewed {date} ({days} days ago)
78
+ "{rule_text}"
79
+ ```
80
+ 3. Ask: "**Keep** (update reviewed date), **Archive**, or **Kill**?"
81
+ 4. Execute:
82
+ - Keep → Update `# Last reviewed:` comment to today
83
+ - Archive → Remove rule from domain file, add to `.carl/archive/archived-rules.json` with context
84
+ - Kill → Remove rule from domain file (with "Are you sure?" confirmation)
85
+
86
+ **When archiving:** Read `.carl/archive/archived-rules.json`, append:
87
+ ```json
88
+ {
89
+ "domain": "DOMAIN",
90
+ "rule_number": N,
91
+ "rule_text": "the rule",
92
+ "added": "original-added-date",
93
+ "archived": "today",
94
+ "reason": "operator's reason"
95
+ }
96
+ ```
97
+
98
+ Then renumber remaining rules in the domain file to close gaps.
99
+
100
+ Process one domain at a time.
101
+ </step>
102
+
103
+ <step name="review_domains">
104
+ Quick domain health check — guided Q&A.
105
+
106
+ 1. List all active domains with rule counts
107
+ 2. Cross-reference with `.base/ACTIVE.md` current projects:
108
+ - Any active projects missing a domain?
109
+ - Any domains for inactive/completed projects?
110
+ 3. Check recall phrases:
111
+ - "Do the recall phrases for {domain} still match how you talk about this work?"
112
+ 4. Check for domains over `max_rules_per_domain`:
113
+ - "Domain {X} has {N} rules (max: {max}). Any candidates to archive or consolidate?"
114
+ 5. Ask: "Any new domains to create? Any to deactivate?"
115
+
116
+ **Guided Q&A — don't force changes, just surface questions.**
117
+ </step>
118
+
119
+ <step name="review_decisions">
120
+ Quick check on per-domain decision health.
121
+
122
+ 1. List `.carl/decisions/*.json` files with counts
123
+ 2. Flag domains with 0 decisions (might be missing logging)
124
+ 3. Flag decisions older than 90 days (might be outdated)
125
+ 4. Ask: "Any decisions to review or archive?"
126
+
127
+ **Brief pass — decisions are mostly self-maintaining.**
128
+ </step>
129
+
130
+ <step name="log">
131
+ Record the hygiene session.
132
+
133
+ 1. Update `.base/workspace.json` → `carl_hygiene.last_run` to today's date
134
+ 2. Update `.base/STATE.md` → note CARL hygiene completed
135
+ 3. Report:
136
+ ```
137
+ CARL Hygiene Complete
138
+ ━━━━━━━━━━━━━━━━━━━━━
139
+ Proposals: {N} processed ({N} approved, {N} killed, {N} archived, {N} deferred)
140
+ Rules reviewed: {N} ({N} kept, {N} archived, {N} killed)
141
+ Domains: {N} active
142
+ Next hygiene due: {date based on cadence}
143
+ ```
144
+ </step>
145
+
146
+ </steps>
147
+
148
+ <output>
149
+ CARL domains reviewed and maintained. Staged proposals decided. Stale rules addressed. Domain health verified. Hygiene session logged to workspace.json.
150
+ </output>
151
+
152
+ <acceptance-criteria>
153
+ - [ ] All pending proposals presented and decided (approve/kill/archive/defer)
154
+ - [ ] Stale rules flagged and reviewed with operator
155
+ - [ ] Domain health check completed (rule counts, recall phrases)
156
+ - [ ] Archived rules moved to .carl/archive/archived-rules.json
157
+ - [ ] workspace.json carl_hygiene.last_run updated
158
+ - [ ] STATE.md updated with hygiene completion
159
+ - [ ] Operator confirmed completion of each step
160
+ </acceptance-criteria>
@@ -0,0 +1,164 @@
1
+ <purpose>
2
+ Structured weekly maintenance cycle. Walk through each workspace area, review with operator, enforce backlog time-based rules, graduate ready items, and log the groom.
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder, I want a guided workspace maintenance session, so that my context documents stay current, my backlog items graduate when ready, and my workspace doesn't drift.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - Weekly (on configured groom day)
11
+ - When pulse reports overdue grooming
12
+ - When user says "base groom", "let's groom", "workspace maintenance"
13
+ - Entry point routes here via /base:groom
14
+ </when-to-use>
15
+
16
+ <steps>
17
+
18
+ <step name="assess_scope" priority="first">
19
+ Determine what needs grooming.
20
+
21
+ 1. Read `.base/workspace.json` manifest
22
+ 2. Read `.base/STATE.md` for last groom dates per area
23
+ 3. Identify which areas are due for grooming (past their cadence)
24
+ 4. Sort by staleness (most overdue first)
25
+ 5. Present: "Groom session starting. {N} areas due for review: {list}. Estimated time: {N*5} minutes."
26
+
27
+ **Wait for operator confirmation before proceeding.**
28
+ </step>
29
+
30
+ <step name="groom_active">
31
+ Review ACTIVE.md — the working memory for projects and tasks.
32
+
33
+ 1. Read `.base/ACTIVE.md`
34
+ 2. Present summary: "{N} projects, {N} tasks, last updated {date}"
35
+ 3. For each project: "Still active? Status changed? Next action current?"
36
+ 4. For each task in TASKS section: "Done? Still in progress? Blocked?"
37
+ 5. Close completed tasks (move to DONE/CLOSED with outcome + date)
38
+ 6. Ask: "Anything new to add?"
39
+ 7. Update timestamp
40
+
41
+ Voice-friendly: walk through one entry at a time, wait for response.
42
+ </step>
43
+
44
+ <step name="groom_backlog">
45
+ Review BACKLOG.md — enforce time-based rules AND handle graduation.
46
+
47
+ **Time-based enforcement:**
48
+ 1. For each item, check Added date against review-by threshold:
49
+ - High priority: 7 days
50
+ - Medium priority: 14 days
51
+ - Low priority: 30 days
52
+ 2. Items past review-by → surface: "These items need a decision: {list}"
53
+ 3. Items past staleness (2x review-by) → "Auto-archiving: {list} (past {N} days without action)"
54
+ 4. Process operator decisions on each flagged item
55
+
56
+ **Graduation check:**
57
+ 5. For each remaining item, ask: "Ready to work on any of these?"
58
+ 6. If yes — determine destination:
59
+ - **As a TASK:** Item is bounded, standalone work. Move to ACTIVE.md → TASKS section.
60
+ Format: `### {Task Name}` with Status, Next, Blocked, Notes fields.
61
+ - **As a PROJECT:** Item is complex enough to warrant its own project entry.
62
+ Move to ACTIVE.md under appropriate priority section with full project format.
63
+ - **Stay in backlog:** Not ready yet. Keep with updated review-by date.
64
+ 7. For graduated items: remove from BACKLOG.md, add to ACTIVE.md in correct section
65
+ 8. Update BACKLOG.md timestamp
66
+
67
+ **The graduation question is explicit every groom.** Items don't graduate silently — the operator decides.
68
+ </step>
69
+
70
+ <step name="groom_directories">
71
+ Review directory-type areas (projects/, clients/, tools/).
72
+
73
+ For each directory area due for grooming:
74
+ 1. List contents
75
+ 2. Flag anything that looks orphaned or new since last groom
76
+ 3. Ask: "Anything to archive, delete, or reclassify?"
77
+ 4. Execute approved changes
78
+ </step>
79
+
80
+ <step name="groom_satellites">
81
+ Review PAUL satellite project health.
82
+
83
+ 1. Read `.base/workspace.json` — collect all satellite entries where `groom_check: true`
84
+ 2. If no satellites have `groom_check: true` → skip this step silently
85
+ 3. For each eligible satellite:
86
+ a. Read its STATE.md at the path in `satellite.state` (relative to workspace root)
87
+ b. If STATE.md is missing or unreadable → note as "⚠️ {name}: STATE.md not found"
88
+ c. Get last activity timestamp:
89
+ - PRIMARY: read `satellite.last_activity` from workspace.json entry (ISO timestamp written by session-start hook from paul.json)
90
+ - FALLBACK: if `last_activity` not present in workspace.json, parse "Last activity" line from the satellite's STATE.md
91
+ - If neither available → note as "⚠️ {name}: cannot determine last activity"
92
+ d. Parse "Loop Position" section from STATE.md → extract PLAN/APPLY/UNIFY markers (✓ = done, ○ = pending)
93
+ e. Evaluate health criteria:
94
+ - **STUCK LOOP**: Loop shows PLAN ✓ APPLY ○ or PLAN ✓ APPLY ✓ UNIFY ○, AND last activity > 7 days ago
95
+ - **ABANDONED PHASE**: Last activity > 14 days ago AND milestone status is not COMPLETE
96
+ - **MILESTONE DRIFT**: Milestone marked COMPLETE, loop shows ○ ○ ○ (no new milestone started), AND last activity > 14 days ago
97
+ 4. Collect all issues across satellites
98
+ 5. If issues found: surface as:
99
+ ```
100
+ ⚠️ Satellite health issues:
101
+ - {satellite-name}: {issue type} (last active: {date})
102
+ ```
103
+ 6. If no issues: output single line "Satellites: all healthy ({N} checked)"
104
+
105
+ **Report only — do NOT auto-fix.** Operator decides what to do with flagged satellites.
106
+ </step>
107
+
108
+ <step name="groom_system">
109
+ Review system layer areas (hooks, commands, skills, CARL).
110
+
111
+ 1. Quick scan for obvious dead items
112
+ 2. Only flag if something clearly wrong
113
+ 3. Ask: "Any system changes to note?"
114
+ 4. If CARL hygiene is enabled (workspace.json `carl_hygiene.proactive: true`):
115
+ - Check `.carl/staging/` for pending proposals
116
+ - Check rule timestamps for staleness
117
+ - Surface: "{N} staged proposals, {N} stale rules — run /base:carl-hygiene?"
118
+ </step>
119
+
120
+ <step name="log_groom">
121
+ Record the groom session.
122
+
123
+ 1. Update `.base/STATE.md` with new timestamps for all groomed areas
124
+ 2. Reset drift score
125
+ 3. Write groom summary to `.base/grooming/{YYYY}-W{NN}.md`:
126
+ ```markdown
127
+ # Groom Summary — Week {NN}, {YYYY}
128
+
129
+ **Date:** {YYYY-MM-DD}
130
+ **Areas Reviewed:** {list}
131
+ **Drift Score:** {before} → 0
132
+
133
+ ## Changes
134
+ - {what changed}
135
+
136
+ ## Graduated from Backlog
137
+ - {item} → ACTIVE.md TASKS / PROJECT
138
+
139
+ ## Archived / Killed
140
+ - {item} (reason)
141
+
142
+ ## Next Groom Due
143
+ {YYYY-MM-DD}
144
+ ```
145
+ 4. Report: "Groom complete. Drift score: 0. Next groom due: {date}."
146
+ </step>
147
+
148
+ </steps>
149
+
150
+ <output>
151
+ Updated workspace state. All due areas reviewed and current. Backlog time-based rules enforced. Ready items graduated. Groom summary logged.
152
+ </output>
153
+
154
+ <acceptance-criteria>
155
+ - [ ] All overdue areas reviewed with operator
156
+ - [ ] ACTIVE.md and BACKLOG.md timestamps updated
157
+ - [ ] Backlog time-based rules enforced (review-by, staleness)
158
+ - [ ] Graduation question asked explicitly for backlog items
159
+ - [ ] Graduated items properly moved to ACTIVE.md (TASKS or PROJECT)
160
+ - [ ] STATE.md updated with new groom date
161
+ - [ ] Groom summary written to grooming/ directory
162
+ - [ ] Drift score reset to 0
163
+ - [ ] Operator confirmed completion of each area
164
+ </acceptance-criteria>
@@ -0,0 +1,34 @@
1
+ <purpose>
2
+ Show workspace evolution over time. Read ROADMAP.md and present the chronological record of major workspace changes.
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder, I want to see how my workspace has evolved, so that I can understand the trajectory and make informed decisions about future changes.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - When user wants to review workspace history
11
+ - Entry point routes here via /base:history
12
+ </when-to-use>
13
+
14
+ <steps>
15
+
16
+ <step name="read_history" priority="first">
17
+ Read and present workspace evolution.
18
+
19
+ 1. Read `.base/ROADMAP.md`
20
+ 2. Present chronologically: dates, what changed, why
21
+ 3. Include audit summaries and major groom outcomes
22
+ 4. If ROADMAP.md is empty or missing: "No history yet. Run /base:audit or /base:groom to start building your workspace timeline."
23
+ </step>
24
+
25
+ </steps>
26
+
27
+ <output>
28
+ Chronological workspace evolution timeline from ROADMAP.md.
29
+ </output>
30
+
31
+ <acceptance-criteria>
32
+ - [ ] History presented in clear chronological format
33
+ - [ ] Includes both audits and significant groom outcomes
34
+ </acceptance-criteria>
@@ -0,0 +1,83 @@
1
+ <purpose>
2
+ Daily workspace activation. Read workspace state, calculate drift, present health dashboard, prime the operator for their session.
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder, I want a quick workspace health briefing at session start, so that I know what needs attention before I start working.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - Start of every work session
11
+ - When user says "base pulse", "what's the state of things", "workspace status"
12
+ - When the pulse hook detects overdue grooming and injects a prompt
13
+ - Entry point routes here via /base:pulse
14
+ </when-to-use>
15
+
16
+ <steps>
17
+
18
+ <step name="read_state" priority="first">
19
+ Read workspace state from `.base/workspace.json` and `.base/STATE.md`.
20
+
21
+ 1. Read `.base/workspace.json` — the manifest
22
+ 2. Read `.base/STATE.md` — the last known state
23
+ 3. If either file is missing, suggest running `/base:scaffold` first
24
+ 4. Extract: last groom date, groom cadence, area list, satellite list
25
+ </step>
26
+
27
+ <step name="calculate_drift">
28
+ Check each tracked area against filesystem reality.
29
+
30
+ For each area in the manifest:
31
+ 1. Check filesystem timestamps on tracked paths (stat modification dates)
32
+ 2. Compare against last groom date and area-specific cadence
33
+ 3. Calculate days overdue (0 if within cadence)
34
+ 4. Classify: Current (within cadence), Stale (1-2x overdue), Critical (2x+ overdue)
35
+
36
+ For each registered satellite:
37
+ 1. Check if state file exists and is readable
38
+ 2. Extract last modification date
39
+ 3. Report current phase if parseable
40
+
41
+ Calculate total drift score: sum of days-overdue across all areas, with Critical areas weighted 2x.
42
+ </step>
43
+
44
+ <step name="present_dashboard">
45
+ Present the health dashboard to the operator.
46
+
47
+ Format:
48
+ ```
49
+ BASE Pulse — {workspace-name}
50
+ Last Groom: {date} ({N} days ago)
51
+ Drift Score: {score}
52
+
53
+ | Area | Status | Age | Due |
54
+ |------|--------|-----|-----|
55
+ ...
56
+
57
+ Satellites:
58
+ | Project | Phase | Last Active |
59
+ ...
60
+
61
+ {Recommendation based on drift score}
62
+ ```
63
+
64
+ Recommendations:
65
+ - Drift 0: "Workspace is clean. Proceed normally."
66
+ - Drift 1-7: "Minor drift in {areas}. Consider grooming this week."
67
+ - Drift 8-14: "Moderate drift. Run /base:groom soon."
68
+ - Drift 15+: "Critical drift. Workspace context is stale. Run /base:groom now."
69
+ </step>
70
+
71
+ </steps>
72
+
73
+ <output>
74
+ Health dashboard with drift score, area statuses, satellite health, and recommended next action.
75
+ </output>
76
+
77
+ <acceptance-criteria>
78
+ - [ ] All manifest areas checked against filesystem reality
79
+ - [ ] Drift score calculated correctly
80
+ - [ ] Satellites checked for health
81
+ - [ ] Clear recommendation provided based on drift level
82
+ - [ ] Dashboard is concise and scannable (not a wall of text)
83
+ </acceptance-criteria>
@@ -0,0 +1,167 @@
1
+ <purpose>
2
+ Set up BASE in a new or existing workspace. Scan the workspace, ask guided questions, generate the manifest, install hooks, and establish baseline state. Optional --full mode adds operational templates (ACTIVE.md, BACKLOG.md, CLAUDE.md audit).
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder setting up my workspace, I want a guided scaffolding process that configures workspace management for my specific setup, so that I get maintenance automation without manual configuration.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - First-time BASE installation in any workspace
11
+ - When user says "base scaffold", "set up base", "initialize workspace management"
12
+ - Entry point routes here via /base:scaffold
13
+ - Use --full flag for batteries-included mode with operational templates
14
+ </when-to-use>
15
+
16
+ <context>
17
+ @templates/workspace-json.md
18
+ @templates/state-md.md
19
+ @templates/active-md.md
20
+ @templates/backlog-md.md
21
+ </context>
22
+
23
+ <steps>
24
+
25
+ <step name="detect_mode" priority="first">
26
+ Determine scaffold mode.
27
+
28
+ 1. Check if user specified `--full` or mentioned wanting templates/full setup
29
+ 2. If `--full`: operational templates will be offered after data layer setup
30
+ 3. If standard: data layer only (workspace.json, STATE.md, ROADMAP.md)
31
+ 4. Announce mode: "Running BASE scaffold ({standard|full} mode)."
32
+ </step>
33
+
34
+ <step name="scan_workspace">
35
+ Scan the workspace and detect what exists.
36
+
37
+ 1. List top-level directories and files
38
+ 2. Detect common patterns:
39
+ - ACTIVE.md, BACKLOG.md → working memory (note if already in .base/)
40
+ - projects/ → project tracking
41
+ - apps/ → satellite projects
42
+ - tools/ → tool management
43
+ - .claude/ → system layer
44
+ - .mcp.json → MCP configuration
45
+ - content/ → content pipeline
46
+ - clients/ → client work
47
+ - obsidian/ → knowledge graph
48
+ - .carl/ → CARL dynamic rules
49
+ 3. Detect satellite projects (directories with .paul/ inside apps/)
50
+ 4. Present findings: "I found: {list of detected areas}"
51
+
52
+ **Wait for confirmation before proceeding.**
53
+ </step>
54
+
55
+ <step name="guided_configuration">
56
+ Walk through each detected area and configure tracking.
57
+
58
+ For each detected area:
59
+ 1. "I found {area}. Want BASE to track this?"
60
+ 2. If yes: "What grooming cadence? (weekly/bi-weekly/monthly)"
61
+ 3. Auto-select audit strategy based on area type
62
+ 4. Allow override of defaults
63
+
64
+ Also ask:
65
+ - "What day do you prefer for weekly grooming?" (default: Friday)
66
+ - "Any directories I should scan for satellite projects?" (default: apps/)
67
+ - "Anything else you want tracked that I didn't detect?"
68
+
69
+ Build workspace.json from responses using `@templates/workspace-json.md` schema.
70
+ </step>
71
+
72
+ <step name="install_data_layer">
73
+ Create .base/ directory and generate all state files.
74
+
75
+ 1. Create `.base/` directory structure:
76
+ ```
77
+ .base/
78
+ ├── workspace.json
79
+ ├── STATE.md
80
+ ├── ROADMAP.md
81
+ ├── grooming/
82
+ └── audits/
83
+ ```
84
+ 2. Write workspace.json from guided configuration
85
+ 3. Generate initial STATE.md using `@templates/state-md.md` by checking current filesystem timestamps
86
+ 4. Initialize ROADMAP.md with scaffold entry
87
+ 5. Register any detected satellite projects in workspace.json
88
+ 6. Report: "BASE data layer installed. {N} areas tracked, {N} satellites registered."
89
+ </step>
90
+
91
+ <step name="install_operational_templates">
92
+ **Full mode only.** Offer operational templates for working memory files.
93
+
94
+ **ACTIVE.md:**
95
+ 1. Check if ACTIVE.md exists at workspace root
96
+ 2. If exists at root (not in .base/):
97
+ - "You have an existing ACTIVE.md. Want me to move it into .base/ and adopt BASE conventions?"
98
+ - If yes: move to `.base/ACTIVE.md`, audit against `@templates/active-md.md`
99
+ - Check for existing references (CLAUDE.md @mentions, hooks, etc.) — if found, offer symlink at root for backward compatibility
100
+ - If no: skip, user keeps their current setup
101
+ 3. If doesn't exist anywhere:
102
+ - "Want me to create ACTIVE.md from the BASE template?"
103
+ - If yes: generate from `@templates/active-md.md` directly in `.base/ACTIVE.md`
104
+ 4. Explain the TASKS section and graduation flow
105
+
106
+ **BACKLOG.md:**
107
+ 1. Same pattern — check if exists at root
108
+ 2. If exists: offer to move into .base/ with optional symlink for existing references
109
+ 3. If creating fresh: generate from `@templates/backlog-md.md` in `.base/BACKLOG.md`
110
+ 4. Explain time-based rules (review-by, staleness, graduation)
111
+
112
+ **CLAUDE.md:**
113
+ 1. Check if CLAUDE.md exists
114
+ 2. If exists: "Want me to audit your CLAUDE.md against BASE conventions?"
115
+ - If yes: route to `/base:audit-claude-md` task
116
+ 3. If doesn't exist: "Want me to generate a CLAUDE.md template for your workspace?"
117
+ - If yes: generate based on detected workspace structure
118
+
119
+ **Symlinks (migration only — not default):**
120
+ Symlinks are ONLY offered when scaffold detects existing files at workspace root that have references pointing to them (CLAUDE.md @mentions, hooks reading from root paths, etc.). BASE operates strictly out of `.base/`. Symlinks exist solely to prevent breaking existing references during migration.
121
+ - If existing references detected: "I found references to ACTIVE.md at root in your CLAUDE.md. Want a symlink for backward compatibility?"
122
+ - If no existing references: no symlinks offered. Files live in `.base/` only.
123
+ </step>
124
+
125
+ <step name="install_hooks">
126
+ Install and register BASE session hooks.
127
+
128
+ Session hooks: base-pulse-check.py, psmm-injector.py, satellite-detection.py
129
+
130
+ For each session hook:
131
+ 1. Check if `.claude/hooks/{hook}` exists in workspace
132
+ 2. If not: copy from `~/.claude/base-framework/hooks/{hook}` (global install source)
133
+ - If `~/.claude/base-framework/hooks/{hook}` doesn't exist either, warn:
134
+ "BASE framework not globally installed. Run `npx base-framework --global` first, then re-run scaffold."
135
+ 3. Check project `.claude/settings.json` for hook registration in UserPromptSubmit array
136
+ 4. If not registered: add the hook path to settings.json UserPromptSubmit array
137
+
138
+ Report: "Session hooks installed (pulse, PSMM injector, satellite detection). Workspace health will be monitored every session."
139
+ </step>
140
+
141
+ <step name="first_groom">
142
+ Offer to establish baseline.
143
+
144
+ 1. "Want to run an initial groom to establish baseline? This reviews each area once."
145
+ 2. If yes: run /base:groom flow
146
+ 3. If no: "Baseline set from filesystem timestamps. First groom due: {date}."
147
+ </step>
148
+
149
+ </steps>
150
+
151
+ <output>
152
+ Fully configured BASE installation. Standard mode: data layer with workspace.json, STATE.md, hooks. Full mode: adds operational templates (ACTIVE.md, BACKLOG.md with graduation flow, CLAUDE.md audit), symlinks, and guided first groom.
153
+ </output>
154
+
155
+ <acceptance-criteria>
156
+ - [ ] Workspace scanned and areas detected
157
+ - [ ] Operator confirmed tracked areas and cadences
158
+ - [ ] .base/ directory created with all required files
159
+ - [ ] workspace.json generated from guided configuration
160
+ - [ ] STATE.md reflects current filesystem state
161
+ - [ ] Satellite projects detected and registered
162
+ - [ ] Pulse hook installed and registered
163
+ - [ ] (Full mode) Operational templates offered and created if accepted
164
+ - [ ] (Full mode) Symlinks created for .base/ files
165
+ - [ ] (Full mode) Graduation flow and time-based rules explained
166
+ - [ ] Operator informed of next groom date
167
+ </acceptance-criteria>
@@ -0,0 +1,35 @@
1
+ <purpose>
2
+ Quick one-liner workspace health check. No conversation, just the numbers.
3
+ </purpose>
4
+
5
+ <user-story>
6
+ As an AI builder, I want a fast health check I can glance at, so that I know if anything needs attention without a full briefing.
7
+ </user-story>
8
+
9
+ <when-to-use>
10
+ - When user wants a quick check without full pulse
11
+ - Entry point routes here via /base:status
12
+ </when-to-use>
13
+
14
+ <steps>
15
+
16
+ <step name="quick_check" priority="first">
17
+ Read state and output one-liner.
18
+
19
+ 1. Read `.base/STATE.md`
20
+ 2. Calculate current drift score from timestamps
21
+ 3. Count overdue areas and past-due backlog items
22
+ 4. Output single line: "BASE: Drift {score} | {N} areas overdue | {N} backlog items past review-by | Last groom: {date}"
23
+ </step>
24
+
25
+ </steps>
26
+
27
+ <output>
28
+ Single-line health summary. No conversation.
29
+ </output>
30
+
31
+ <acceptance-criteria>
32
+ - [ ] Output is one line
33
+ - [ ] Drift score is current (not cached)
34
+ - [ ] Overdue counts are accurate
35
+ </acceptance-criteria>