@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.
- package/README.md +157 -0
- package/bin/install.js +340 -0
- package/package.json +40 -0
- package/src/commands/audit-claude-md.md +31 -0
- package/src/commands/audit.md +33 -0
- package/src/commands/carl-hygiene.md +33 -0
- package/src/commands/groom.md +35 -0
- package/src/commands/history.md +27 -0
- package/src/commands/pulse.md +33 -0
- package/src/commands/scaffold.md +33 -0
- package/src/commands/status.md +28 -0
- package/src/commands/surface-convert.md +35 -0
- package/src/commands/surface-create.md +34 -0
- package/src/commands/surface-list.md +27 -0
- package/src/framework/context/base-principles.md +71 -0
- package/src/framework/frameworks/audit-strategies.md +53 -0
- package/src/framework/frameworks/satellite-registration.md +44 -0
- package/src/framework/tasks/audit-claude-md.md +68 -0
- package/src/framework/tasks/audit.md +64 -0
- package/src/framework/tasks/carl-hygiene.md +160 -0
- package/src/framework/tasks/groom.md +164 -0
- package/src/framework/tasks/history.md +34 -0
- package/src/framework/tasks/pulse.md +83 -0
- package/src/framework/tasks/scaffold.md +167 -0
- package/src/framework/tasks/status.md +35 -0
- package/src/framework/tasks/surface-convert.md +143 -0
- package/src/framework/tasks/surface-create.md +184 -0
- package/src/framework/tasks/surface-list.md +42 -0
- package/src/framework/templates/active-md.md +112 -0
- package/src/framework/templates/backlog-md.md +100 -0
- package/src/framework/templates/state-md.md +48 -0
- package/src/framework/templates/workspace-json.md +50 -0
- package/src/hooks/_template.py +129 -0
- package/src/hooks/active-hook.py +115 -0
- package/src/hooks/backlog-hook.py +107 -0
- package/src/hooks/base-pulse-check.py +206 -0
- package/src/hooks/psmm-injector.py +67 -0
- package/src/hooks/satellite-detection.py +131 -0
- package/src/packages/base-mcp/index.js +108 -0
- package/src/packages/base-mcp/package.json +10 -0
- package/src/packages/base-mcp/tools/surfaces.js +404 -0
- package/src/packages/carl-mcp/index.js +115 -0
- package/src/packages/carl-mcp/package.json +10 -0
- package/src/packages/carl-mcp/tools/decisions.js +269 -0
- package/src/packages/carl-mcp/tools/domains.js +361 -0
- package/src/packages/carl-mcp/tools/psmm.js +204 -0
- package/src/packages/carl-mcp/tools/staging.js +245 -0
- 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>
|