qwen-base 1.0.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 +183 -0
- package/bin/install.js +227 -0
- package/package.json +42 -0
- package/src/commands/audit-claude-md.md +44 -0
- package/src/commands/audit-claude.md +45 -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/orientation/tasks/deep-why.md +132 -0
- package/src/commands/orientation/tasks/elevator-pitch.md +115 -0
- package/src/commands/orientation/tasks/initiatives.md +98 -0
- package/src/commands/orientation/tasks/key-values.md +130 -0
- package/src/commands/orientation/tasks/new-orientation.md +162 -0
- package/src/commands/orientation/tasks/north-star.md +97 -0
- package/src/commands/orientation/tasks/project-mapping.md +103 -0
- package/src/commands/orientation/tasks/reorientation.md +96 -0
- package/src/commands/orientation/tasks/surface-vision.md +113 -0
- package/src/commands/orientation/tasks/task-seeding.md +93 -0
- package/src/commands/orientation/templates/operator-json.md +88 -0
- package/src/commands/orientation.md +87 -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/commands/weekly-domain.md +34 -0
- package/src/commands/weekly.md +39 -0
- package/src/framework/context/base-principles.md +69 -0
- package/src/framework/frameworks/audit-strategies.md +53 -0
- package/src/framework/frameworks/claude-config-alignment.md +256 -0
- package/src/framework/frameworks/claudemd-strategy.md +158 -0
- package/src/framework/frameworks/satellite-registration.md +44 -0
- package/src/framework/tasks/audit-claude-md.md +171 -0
- package/src/framework/tasks/audit-claude.md +330 -0
- package/src/framework/tasks/audit.md +64 -0
- package/src/framework/tasks/carl-hygiene.md +142 -0
- package/src/framework/tasks/groom.md +157 -0
- package/src/framework/tasks/history.md +34 -0
- package/src/framework/tasks/pulse.md +83 -0
- package/src/framework/tasks/scaffold.md +389 -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/tasks/weekly-domain-create.md +173 -0
- package/src/framework/tasks/weekly.md +347 -0
- package/src/framework/templates/claudemd-template.md +102 -0
- package/src/framework/templates/workspace-json.md +96 -0
- package/src/framework/utils/scan-claude-dirs.py +549 -0
- package/src/hooks/_template.py +130 -0
- package/src/hooks/active-hook.py +178 -0
- package/src/hooks/apex-insights.py +169 -0
- package/src/hooks/backlog-hook.py +115 -0
- package/src/hooks/base-pulse-check.py +216 -0
- package/src/hooks/operator.py +53 -0
- package/src/hooks/psmm-injector.py +67 -0
- package/src/hooks/satellite-detection.py +320 -0
- package/src/packages/base-mcp/index.js +119 -0
- package/src/packages/base-mcp/package.json +10 -0
- package/src/packages/base-mcp/tools/entities.js +228 -0
- package/src/packages/base-mcp/tools/operator.js +106 -0
- package/src/packages/base-mcp/tools/projects.js +324 -0
- package/src/packages/base-mcp/tools/psmm.js +206 -0
- package/src/packages/base-mcp/tools/satellite.js +243 -0
- package/src/packages/base-mcp/tools/state.js +201 -0
- package/src/packages/base-mcp/tools/validate.js +121 -0
- package/src/skill/base.md +110 -0
- package/src/templates/operator.json +66 -0
- package/src/templates/workspace.json +76 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:pulse
|
|
3
|
+
description: Daily workspace health briefing
|
|
4
|
+
allowed-tools: [Read, Glob, Grep, Bash]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<objective>
|
|
8
|
+
Workspace health briefing — drift score, stale areas, overdue grooming, quick status.
|
|
9
|
+
|
|
10
|
+
**When to use:** Session start, "what's the state of my workspace", daily check-in.
|
|
11
|
+
</objective>
|
|
12
|
+
|
|
13
|
+
<execution_context>
|
|
14
|
+
@{~/.qwen/commands/qwen-base/tasks/pulse.md}
|
|
15
|
+
@{~/.qwen/commands/qwen-base/context/base-principles.md}
|
|
16
|
+
</execution_context>
|
|
17
|
+
|
|
18
|
+
<context>
|
|
19
|
+
$ARGUMENTS
|
|
20
|
+
|
|
21
|
+
@.base/workspace.json
|
|
22
|
+
@.base/data/state.json
|
|
23
|
+
</context>
|
|
24
|
+
|
|
25
|
+
<process>
|
|
26
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/pulse.md}
|
|
27
|
+
</process>
|
|
28
|
+
|
|
29
|
+
<success_criteria>
|
|
30
|
+
- [ ] Drift score calculated and displayed
|
|
31
|
+
- [ ] Stale areas identified
|
|
32
|
+
- [ ] Groom cadence checked
|
|
33
|
+
</success_criteria>
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:scaffold
|
|
3
|
+
description: Set up BASE in a new workspace
|
|
4
|
+
argument-hint: "[--full]"
|
|
5
|
+
allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<objective>
|
|
9
|
+
Guided workspace setup — scan, configure, install BASE infrastructure. Optional --full mode adds operational templates.
|
|
10
|
+
|
|
11
|
+
**When to use:** First-time BASE installation, "set up base", "scaffold my workspace".
|
|
12
|
+
</objective>
|
|
13
|
+
|
|
14
|
+
<execution_context>
|
|
15
|
+
@{~/.qwen/commands/qwen-base/tasks/scaffold.md}
|
|
16
|
+
@{~/.qwen/commands/qwen-base/templates/workspace-json.md}
|
|
17
|
+
@{~/.qwen/commands/qwen-base/templates/workspace-json.md}
|
|
18
|
+
</execution_context>
|
|
19
|
+
|
|
20
|
+
<context>
|
|
21
|
+
$ARGUMENTS
|
|
22
|
+
</context>
|
|
23
|
+
|
|
24
|
+
<process>
|
|
25
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/scaffold.md}
|
|
26
|
+
</process>
|
|
27
|
+
|
|
28
|
+
<success_criteria>
|
|
29
|
+
- [ ] .base/ directory structure created
|
|
30
|
+
- [ ] workspace.json generated from scan
|
|
31
|
+
- [ ] state.json initialized
|
|
32
|
+
- [ ] Hooks and MCP servers installed (if --full)
|
|
33
|
+
</success_criteria>
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:status
|
|
3
|
+
description: Quick workspace health check
|
|
4
|
+
allowed-tools: [Read, Glob, Bash]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<objective>
|
|
8
|
+
One-liner workspace health status — drift score and area summary.
|
|
9
|
+
|
|
10
|
+
**When to use:** Quick check, "workspace status", "how's my workspace".
|
|
11
|
+
</objective>
|
|
12
|
+
|
|
13
|
+
<execution_context>
|
|
14
|
+
@{~/.qwen/commands/qwen-base/tasks/status.md}
|
|
15
|
+
</execution_context>
|
|
16
|
+
|
|
17
|
+
<context>
|
|
18
|
+
@.base/workspace.json
|
|
19
|
+
@.base/data/state.json
|
|
20
|
+
</context>
|
|
21
|
+
|
|
22
|
+
<process>
|
|
23
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/status.md}
|
|
24
|
+
</process>
|
|
25
|
+
|
|
26
|
+
<success_criteria>
|
|
27
|
+
- [ ] Health status displayed
|
|
28
|
+
</success_criteria>
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:surface-convert
|
|
3
|
+
description: Convert a markdown file into a data surface
|
|
4
|
+
argument-hint: "<file-path>"
|
|
5
|
+
allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<objective>
|
|
9
|
+
Convert an existing @-mentioned markdown file into a structured data surface. Analyzes structure, proposes schema, migrates content.
|
|
10
|
+
|
|
11
|
+
**When to use:** User has a markdown file they want to convert to a structured surface.
|
|
12
|
+
</objective>
|
|
13
|
+
|
|
14
|
+
<execution_context>
|
|
15
|
+
@{~/.qwen/commands/qwen-base/tasks/surface-convert.md}
|
|
16
|
+
@.base/hooks/_template.py
|
|
17
|
+
</execution_context>
|
|
18
|
+
|
|
19
|
+
<context>
|
|
20
|
+
$ARGUMENTS
|
|
21
|
+
|
|
22
|
+
@.base/workspace.json
|
|
23
|
+
</context>
|
|
24
|
+
|
|
25
|
+
<process>
|
|
26
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-convert.md}
|
|
27
|
+
</process>
|
|
28
|
+
|
|
29
|
+
<success_criteria>
|
|
30
|
+
- [ ] .base/data/{name}.json created with migrated items
|
|
31
|
+
- [ ] .base/hooks/{name}-hook.py created
|
|
32
|
+
- [ ] workspace.json updated with surface registration
|
|
33
|
+
- [ ] settings.json updated with hook entry
|
|
34
|
+
- [ ] Original markdown file preserved
|
|
35
|
+
</success_criteria>
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:surface-create
|
|
3
|
+
description: Create a new data surface (guided)
|
|
4
|
+
argument-hint: "[surface-name]"
|
|
5
|
+
allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<objective>
|
|
9
|
+
Create a new data surface through guided conversation. Generates JSON data file, injection hook, workspace.json registration, and settings.json hook entry.
|
|
10
|
+
|
|
11
|
+
**When to use:** User wants to track something new as a structured data surface.
|
|
12
|
+
</objective>
|
|
13
|
+
|
|
14
|
+
<execution_context>
|
|
15
|
+
@{~/.qwen/commands/qwen-base/tasks/surface-create.md}
|
|
16
|
+
@.base/hooks/_template.py
|
|
17
|
+
</execution_context>
|
|
18
|
+
|
|
19
|
+
<context>
|
|
20
|
+
$ARGUMENTS
|
|
21
|
+
|
|
22
|
+
@.base/workspace.json
|
|
23
|
+
</context>
|
|
24
|
+
|
|
25
|
+
<process>
|
|
26
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-create.md}
|
|
27
|
+
</process>
|
|
28
|
+
|
|
29
|
+
<success_criteria>
|
|
30
|
+
- [ ] .base/data/{name}.json created
|
|
31
|
+
- [ ] .base/hooks/{name}-hook.py created
|
|
32
|
+
- [ ] workspace.json updated with surface registration
|
|
33
|
+
- [ ] settings.json updated with hook entry
|
|
34
|
+
</success_criteria>
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:surface-list
|
|
3
|
+
description: Show all registered data surfaces
|
|
4
|
+
allowed-tools: [Read, Bash]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<objective>
|
|
8
|
+
Display all registered data surfaces with item counts and hook status.
|
|
9
|
+
|
|
10
|
+
**When to use:** User wants to see what surfaces exist.
|
|
11
|
+
</objective>
|
|
12
|
+
|
|
13
|
+
<execution_context>
|
|
14
|
+
@{~/.qwen/commands/qwen-base/tasks/surface-list.md}
|
|
15
|
+
</execution_context>
|
|
16
|
+
|
|
17
|
+
<context>
|
|
18
|
+
@.base/workspace.json
|
|
19
|
+
</context>
|
|
20
|
+
|
|
21
|
+
<process>
|
|
22
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-list.md}
|
|
23
|
+
</process>
|
|
24
|
+
|
|
25
|
+
<success_criteria>
|
|
26
|
+
- [ ] All registered surfaces displayed with counts
|
|
27
|
+
</success_criteria>
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:weekly-domain
|
|
3
|
+
description: Create a custom domain phase for the weekly ritual
|
|
4
|
+
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<objective>
|
|
8
|
+
Guided creation of a custom domain phase for /base:weekly. Walks the user through defining what to check, what tools to use, what questions to ask, and what output to produce.
|
|
9
|
+
|
|
10
|
+
**When to use:** "Add a domain to my weekly", "create a weekly domain phase", "I want to track X in my weekly".
|
|
11
|
+
</objective>
|
|
12
|
+
|
|
13
|
+
<execution_context>
|
|
14
|
+
@{~/.qwen/commands/qwen-base/tasks/weekly-domain-create.md}
|
|
15
|
+
</execution_context>
|
|
16
|
+
|
|
17
|
+
<context>
|
|
18
|
+
$ARGUMENTS
|
|
19
|
+
|
|
20
|
+
@.base/weekly.json
|
|
21
|
+
</context>
|
|
22
|
+
|
|
23
|
+
<process>
|
|
24
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/weekly-domain-create.md}
|
|
25
|
+
</process>
|
|
26
|
+
|
|
27
|
+
<success_criteria>
|
|
28
|
+
- [ ] User described the domain area
|
|
29
|
+
- [ ] Data sources identified (with tool discovery if needed)
|
|
30
|
+
- [ ] Weekly questions defined
|
|
31
|
+
- [ ] Position in weekly flow chosen
|
|
32
|
+
- [ ] Output type specified
|
|
33
|
+
- [ ] Domain phase config written to weekly.json
|
|
34
|
+
</success_criteria>
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: base:weekly
|
|
3
|
+
description: Weekly review and planning ritual
|
|
4
|
+
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<objective>
|
|
8
|
+
Guided weekly ritual — close the week, plan the next, run maintenance, lock in priorities with calendar events.
|
|
9
|
+
|
|
10
|
+
**When to use:** Weekly planning, "run my weekly", "weekly review", "time for my weekly".
|
|
11
|
+
</objective>
|
|
12
|
+
|
|
13
|
+
<execution_context>
|
|
14
|
+
@{~/.qwen/commands/qwen-base/tasks/weekly.md}
|
|
15
|
+
@{~/.qwen/commands/qwen-base/context/base-principles.md}
|
|
16
|
+
</execution_context>
|
|
17
|
+
|
|
18
|
+
<context>
|
|
19
|
+
$ARGUMENTS
|
|
20
|
+
|
|
21
|
+
@.base/workspace.json
|
|
22
|
+
@.base/data/state.json
|
|
23
|
+
@.base/weekly.json
|
|
24
|
+
</context>
|
|
25
|
+
|
|
26
|
+
<process>
|
|
27
|
+
Follow task: @{~/.qwen/commands/qwen-base/tasks/weekly.md}
|
|
28
|
+
</process>
|
|
29
|
+
|
|
30
|
+
<success_criteria>
|
|
31
|
+
- [ ] Week reviewed (daily logs consumed if available)
|
|
32
|
+
- [ ] Calendar audited with rules applied
|
|
33
|
+
- [ ] Workspace groomed (drift score updated)
|
|
34
|
+
- [ ] Priority stack set (outcome-based, aligned to north star)
|
|
35
|
+
- [ ] Backlog triaged (overdue items processed)
|
|
36
|
+
- [ ] Domain phases executed (if configured)
|
|
37
|
+
- [ ] Blockers identified, follow-ups queued
|
|
38
|
+
- [ ] Week committed — calendar events created, weekly.json entry logged
|
|
39
|
+
</success_criteria>
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# BASE Principles
|
|
2
|
+
|
|
3
|
+
## Core Laws
|
|
4
|
+
|
|
5
|
+
1. **If it's not current, it's harmful.** Stale context documents feed AI bad information. Maintenance isn't optional.
|
|
6
|
+
2. **Every file earns its place.** If you can't explain why it's here in 5 seconds, it moves or dies.
|
|
7
|
+
3. **Archive > delete.** When in doubt, archive. You can always delete later. You can't un-delete.
|
|
8
|
+
4. **The workspace is the product.** Treat it like production code, not a scratch pad.
|
|
9
|
+
5. **Clean as you go.** The best time to file something correctly is when you create it. The second best time is now.
|
|
10
|
+
6. **Scaffold generates manifest. Manifest drives everything.** One configuration point. No manual bookkeeping.
|
|
11
|
+
7. **Tools register themselves.** PAUL projects auto-register with BASE. No human memory required.
|
|
12
|
+
|
|
13
|
+
## Drift Score
|
|
14
|
+
|
|
15
|
+
Drift is the gap between documented state and actual state. Measured in days-overdue across all tracked areas.
|
|
16
|
+
|
|
17
|
+
- **0** — Everything current. Workspace is clean.
|
|
18
|
+
- **1-7** — Minor drift. Normal during execution sprints. Fix at next groom.
|
|
19
|
+
- **8-14** — Moderate drift. Context documents are likely misleading AI. Groom soon.
|
|
20
|
+
- **15+** — Critical drift. Sessions are operating on stale context. Groom NOW.
|
|
21
|
+
|
|
22
|
+
## Maintenance Cadence
|
|
23
|
+
|
|
24
|
+
| What | Default Cadence | Override |
|
|
25
|
+
|------|----------------|---------|
|
|
26
|
+
| projects.json | Every session or weekly | workspace.json |
|
|
27
|
+
| Project directory | Monthly | workspace.json |
|
|
28
|
+
| Tools/MCP | Monthly | workspace.json |
|
|
29
|
+
| System layer | Monthly | workspace.json |
|
|
30
|
+
| Full audit | Quarterly or after major shifts | On demand |
|
|
31
|
+
|
|
32
|
+
## Backlog Rules
|
|
33
|
+
|
|
34
|
+
Items have time-based properties enforced by grooming:
|
|
35
|
+
|
|
36
|
+
- **Added** — auto-set when item enters backlog
|
|
37
|
+
- **Review-by** — priority-based: High=7d, Medium=14d, Low=30d
|
|
38
|
+
- **Staleness** — 2x review-by threshold. Auto-archive if reached without action.
|
|
39
|
+
|
|
40
|
+
During groom: items past review-by surface as "decide or kill." Items past staleness auto-archive with a note.
|
|
41
|
+
|
|
42
|
+
## Graduation Flow
|
|
43
|
+
|
|
44
|
+
Backlog items don't sit forever. They graduate to active when the operator is ready to work on them.
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
BACKLOG (status=backlog in projects.json)
|
|
48
|
+
→ ACTIVE (status updated to in_progress/todo via base_update_project)
|
|
49
|
+
→ DONE (archived via base_archive_project with outcome)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**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.
|
|
53
|
+
|
|
54
|
+
**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.
|
|
55
|
+
|
|
56
|
+
**Items can also move backward:** An active project that loses priority can return to backlog status. A project that stalls can move to DEFERRED. Nothing is permanent.
|
|
57
|
+
|
|
58
|
+
## Scaffold Modes
|
|
59
|
+
|
|
60
|
+
BASE scaffold operates in two modes:
|
|
61
|
+
|
|
62
|
+
- **Standard** (`/base:scaffold`) — Data layer only. Creates `.base/` with workspace.json, `.base/data/state.json`, ROADMAP.md. Scans and tracks what exists. Framework-agnostic.
|
|
63
|
+
- **Full** (`/base:scaffold --full`) — Data layer + projects.json + entities.json. Offers CLAUDE.md audit. The "batteries included" version for AI builders who want the full system.
|
|
64
|
+
|
|
65
|
+
Standard mode works for any workspace. Full mode provides Chris's proven operational structure.
|
|
66
|
+
|
|
67
|
+
## File Location
|
|
68
|
+
|
|
69
|
+
BASE operates strictly out of `.base/`. All data (projects.json, entities.json, state.json, psmm.json) lives in `.base/data/`. Configuration (workspace.json) and documentation (ROADMAP.md) live in `.base/`. Data is accessed via MCP tools (`base_list_projects`, `base_add_project`, `base_update_project`, `base_get_state`, etc.). `.base/data/` is the canonical location for all structured data.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Audit Strategies
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Strategies
|
|
6
|
+
|
|
7
|
+
### staleness
|
|
8
|
+
**Applies to:** Data files (projects.json, state.json, any tracked document)
|
|
9
|
+
**What it does:** Check file modification timestamps against configured thresholds. Flag files past their groom cadence.
|
|
10
|
+
**Config:**
|
|
11
|
+
- `threshold_days` — days after which the file is considered stale
|
|
12
|
+
**Output:** List of stale files with age, recommended action (update or review)
|
|
13
|
+
|
|
14
|
+
### classify
|
|
15
|
+
**Applies to:** Directories with lifecycle items (projects/, clients/)
|
|
16
|
+
**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.
|
|
17
|
+
**Config:**
|
|
18
|
+
- `states` — classification options (default: ["active", "archive", "delete"])
|
|
19
|
+
- `archive_path` — where archived items go (default: `{path}/_archive/`)
|
|
20
|
+
**Output:** Classification decisions, items moved to archive, items deleted
|
|
21
|
+
|
|
22
|
+
### cross-reference
|
|
23
|
+
**Applies to:** Tools/servers that have a config file mapping (e.g., MCP servers vs .mcp.json)
|
|
24
|
+
**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).
|
|
25
|
+
**Config:**
|
|
26
|
+
- `config_file` — path to the configuration file to cross-reference
|
|
27
|
+
**Output:** Orphaned items, broken references, recommendations
|
|
28
|
+
|
|
29
|
+
### dead-code
|
|
30
|
+
**Applies to:** System directories (hooks, commands, skills)
|
|
31
|
+
**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.
|
|
32
|
+
**Config:**
|
|
33
|
+
- `reference_check` — whether to search for references in other files (default: true)
|
|
34
|
+
**Output:** Potentially dead files with evidence, operator decides keep/delete
|
|
35
|
+
|
|
36
|
+
### pipeline-status
|
|
37
|
+
**Applies to:** Content pipelines, task queues, any workflow with stages
|
|
38
|
+
**What it does:** Check items in each pipeline stage. Flag stuck items (in same stage too long), empty stages, bottlenecks.
|
|
39
|
+
**Config:**
|
|
40
|
+
- `stages` — ordered list of pipeline stages
|
|
41
|
+
- `stuck_threshold_days` — days in one stage before flagging
|
|
42
|
+
**Output:** Pipeline health report, stuck items, stage distribution
|
|
43
|
+
|
|
44
|
+
## Extending Strategies
|
|
45
|
+
|
|
46
|
+
Custom strategies can be added for workspace-specific needs. A strategy is defined by:
|
|
47
|
+
1. A name (kebab-case)
|
|
48
|
+
2. What it applies to (description)
|
|
49
|
+
3. What it checks (logic)
|
|
50
|
+
4. What config it needs (parameters)
|
|
51
|
+
5. What it outputs (findings format)
|
|
52
|
+
|
|
53
|
+
Add custom strategies to this file and reference them in `workspace.json`.
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# Claude Config Alignment Strategy
|
|
2
|
+
|
|
3
|
+
Standalone strategy for auditing `.qwen/` directory sprawl across a workspace. Discovers all `.qwen/` directories, catalogs their contents, classifies each item against a global/workspace/project hierarchy, and produces a remediation plan.
|
|
4
|
+
|
|
5
|
+
Designed to be composed into any audit workflow that touches the system layer. The `/base:audit-claude` command references this strategy directly. The general `/base:audit` can compose it in when running system-layer checks.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to Use
|
|
10
|
+
|
|
11
|
+
- During initial BASE setup on an existing workspace (lots of legacy `.qwen/` dirs)
|
|
12
|
+
- As part of periodic workspace audits
|
|
13
|
+
- After installing a new tool/skill globally and wanting to clean up project-level copies
|
|
14
|
+
- When the user suspects their Claude Code config is fragmented
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Discovery Rules
|
|
19
|
+
|
|
20
|
+
### What to scan
|
|
21
|
+
- All directories named `.claude` under the workspace root
|
|
22
|
+
- Recursively (projects may nest: `apps/foo/bar/.qwen/`)
|
|
23
|
+
|
|
24
|
+
### What to skip
|
|
25
|
+
- `node_modules/` — third-party packages may contain `.qwen/` dirs
|
|
26
|
+
- `_archive/` — archived projects are frozen, don't audit
|
|
27
|
+
- `.git/` — git internals
|
|
28
|
+
- `vendor/`, `dist/`, `build/` — build artifacts
|
|
29
|
+
|
|
30
|
+
### What to catalog per directory
|
|
31
|
+
For each discovered `.qwen/` directory, record:
|
|
32
|
+
- **Path** (relative to workspace root)
|
|
33
|
+
- **hooks/** — list filenames
|
|
34
|
+
- **commands/** — list subdirectories and files
|
|
35
|
+
- **skills/** — list skill directories
|
|
36
|
+
- **rules/** — list files
|
|
37
|
+
- **settings.json** — exists? contents summary
|
|
38
|
+
- **settings.local.json** — exists? contents summary
|
|
39
|
+
- **Other files** — anything unexpected
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Git Boundary Awareness
|
|
44
|
+
|
|
45
|
+
Understanding git boundaries is critical for correct classification. The scanner dataset includes `git_boundary` data for each directory.
|
|
46
|
+
|
|
47
|
+
### How git boundaries affect visibility
|
|
48
|
+
|
|
49
|
+
- **`has_own_git: true`** — This project has its own git root. It does NOT see the workspace root `.qwen/` or workspace `.mcp.json`. It only sees global `~/.qwen/` + its own `.qwen/`.
|
|
50
|
+
- **`has_own_git: false`** — This project inherits the workspace root. It sees global `~/.qwen/` + workspace root `.qwen/` + its own `.qwen/`.
|
|
51
|
+
|
|
52
|
+
### What this changes about classification
|
|
53
|
+
|
|
54
|
+
If a project has its own git root and contains a hook that also exists in the workspace root `.qwen/`, that's **not a duplicate running twice** — the workspace root version is invisible to that project. Removing the local copy would leave the project with NO version of that hook.
|
|
55
|
+
|
|
56
|
+
For own-git projects, the right framing is:
|
|
57
|
+
- Does a current version exist in **global** `~/.qwen/`? If yes, the local copy is a true DUPLICATE (global is always visible).
|
|
58
|
+
- Does a version only exist in **workspace root** `.qwen/`? Then the local copy is the project's ONLY access to that functionality. The right recommendation is PROMOTE_TO_GLOBAL — centralize it so all projects benefit, then clean up local copies.
|
|
59
|
+
- Is the local copy an outdated version of something in a baseline? It's DIVERGED.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Classification Rules
|
|
64
|
+
|
|
65
|
+
Each item found in a project-level `.qwen/` must be classified into exactly one category. These rules define how.
|
|
66
|
+
|
|
67
|
+
**Classification order:** TEMPLATE → ACCIDENTAL → DUPLICATE → DIVERGED → PROMOTE_TO_GLOBAL → STALE → GLOBAL_CANDIDATE → PROJECT_SPECIFIC
|
|
68
|
+
|
|
69
|
+
### DUPLICATE — Exists in a visible baseline, safe to remove
|
|
70
|
+
|
|
71
|
+
An item is a DUPLICATE if:
|
|
72
|
+
- Its MD5 hash matches a file in a baseline the project can **actually see**
|
|
73
|
+
- Global baseline (`~/.qwen/`): always checked — global is always visible
|
|
74
|
+
- Workspace root baseline (`.qwen/`): only checked if `has_own_git: false`
|
|
75
|
+
- A match against a **non-visible** baseline (workspace root for own-git projects) is NOT a duplicate — see PROMOTE_TO_GLOBAL
|
|
76
|
+
- Common examples: hooks copied into project dirs that now run globally, skills that were installed globally after being copied locally
|
|
77
|
+
|
|
78
|
+
**Verification before removal:**
|
|
79
|
+
1. Confirm the global version is the current/active version (not the other way around)
|
|
80
|
+
2. Confirm the project's `settings.json` doesn't reference the local copy with a relative path that would break if removed
|
|
81
|
+
3. If the local copy has modifications not in the global version, flag as DIVERGED instead
|
|
82
|
+
|
|
83
|
+
### DIVERGED — Local copy differs from global
|
|
84
|
+
|
|
85
|
+
An item is DIVERGED if:
|
|
86
|
+
- A version exists both locally and globally
|
|
87
|
+
- The local copy has meaningful differences (not just whitespace or path variations)
|
|
88
|
+
- Requires human decision: merge local changes into global? Keep local override? Or discard local changes?
|
|
89
|
+
|
|
90
|
+
**Never auto-resolve diverged items. Always present both versions and ask.**
|
|
91
|
+
|
|
92
|
+
### PROMOTE_TO_GLOBAL — Centralize to global, then clean up copies
|
|
93
|
+
|
|
94
|
+
An item is PROMOTE_TO_GLOBAL if:
|
|
95
|
+
- It exists in workspace root `.qwen/` (or the same pattern appears across multiple own-git projects) but NOT in global `~/.qwen/`
|
|
96
|
+
- For own-git projects: a file matching a non-visible baseline (workspace root) is NOT a duplicate — it's a signal something should be centralized
|
|
97
|
+
- When multiple projects have the same hook with the same MD5, that's strong evidence it belongs in global
|
|
98
|
+
- This is the most valuable finding: "put this in global and stop copying it into every project"
|
|
99
|
+
|
|
100
|
+
**PROMOTE_TO_GLOBAL is about removing the need for copies.** Once promoted, all project copies become true DUPLICATES (global is always visible) and can be safely removed.
|
|
101
|
+
|
|
102
|
+
**Promotion is a suggestion, never automatic.** After promoting to global, the global `settings.json` must also register the hook or it won't fire.
|
|
103
|
+
|
|
104
|
+
### GLOBAL_CANDIDATE — Should be promoted to global (single occurrence)
|
|
105
|
+
|
|
106
|
+
An item is a GLOBAL_CANDIDATE if:
|
|
107
|
+
- It exists in a project-level `.qwen/` but NOT in global
|
|
108
|
+
- It serves a user-level purpose (not project-specific)
|
|
109
|
+
- It would be useful across multiple projects
|
|
110
|
+
- Examples: a custom skill the user installed in one project but uses everywhere, a hook that provides general utility
|
|
111
|
+
|
|
112
|
+
**Promotion is a suggestion, never automatic.** Present the item, explain why it's a candidate, let operator decide.
|
|
113
|
+
|
|
114
|
+
### PROJECT_SPECIFIC — Legitimately belongs here
|
|
115
|
+
|
|
116
|
+
An item is PROJECT_SPECIFIC if:
|
|
117
|
+
- It references project-local paths, configs, or conventions
|
|
118
|
+
- It only makes sense in the context of this specific project
|
|
119
|
+
- Examples: project-specific commands, MCP server lists tailored to that project's stack, hooks that interact with project-local files
|
|
120
|
+
|
|
121
|
+
**These stay. Note them for reference but take no action.**
|
|
122
|
+
|
|
123
|
+
### STALE — References things that no longer exist
|
|
124
|
+
|
|
125
|
+
An item is STALE if:
|
|
126
|
+
- settings.json references MCP servers that aren't in the current `.mcp.json` or global config
|
|
127
|
+
- hooks reference scripts or tools that have been renamed or removed
|
|
128
|
+
- Settings use old configuration patterns that Claude Code no longer supports
|
|
129
|
+
- The `.qwen/` directory hasn't been modified in 60+ days AND the project itself shows no recent activity
|
|
130
|
+
|
|
131
|
+
**Present specific evidence of staleness. Never assume — prove it.**
|
|
132
|
+
|
|
133
|
+
### ACCIDENTAL — Clearly unintentional
|
|
134
|
+
|
|
135
|
+
An item is ACCIDENTAL if:
|
|
136
|
+
- Nested `.qwen/.qwen/` directories
|
|
137
|
+
- Empty `.qwen/` directories (no files at all)
|
|
138
|
+
- `.qwen/` inside directories that aren't projects (temp dirs, scratch folders)
|
|
139
|
+
|
|
140
|
+
**Safe to remove, but still confirm with operator.**
|
|
141
|
+
|
|
142
|
+
### TEMPLATE — Intentional scaffold template
|
|
143
|
+
|
|
144
|
+
An item is TEMPLATE if:
|
|
145
|
+
- It lives in a directory named `_template/`, `template/`, or `templates/`
|
|
146
|
+
- It contains placeholder values (e.g., `{{PROJECT_NAME}}`)
|
|
147
|
+
- It's designed to be copied, not used directly
|
|
148
|
+
|
|
149
|
+
**Never modify templates. Note them and move on.**
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Settings Reconciliation
|
|
154
|
+
|
|
155
|
+
Project-level `settings.json` and `settings.local.json` require special handling because they override global settings.
|
|
156
|
+
|
|
157
|
+
### Check for
|
|
158
|
+
1. **Hook definitions that duplicate global hooks** — If global `settings.json` already runs `base-pulse-check.py` on UserPromptSubmit, a project that also defines it runs it twice (or runs a stale version)
|
|
159
|
+
2. **Stale MCP server references** — Server names change. Old lists reference servers that no longer exist
|
|
160
|
+
3. **Empty hook arrays** — `"UserPromptSubmit": []` overrides global hooks with nothing, potentially breaking the user's setup
|
|
161
|
+
4. **Permission overrides** — Project-level allow/deny that may conflict with or duplicate global permissions
|
|
162
|
+
5. **enabledMcpjsonServers** — Lists that reference old server names
|
|
163
|
+
|
|
164
|
+
### Critical safety rule
|
|
165
|
+
**An empty hooks array `[]` in a project settings.json OVERRIDES the global hooks with nothing.** This is the most dangerous pattern — it silently disables all hooks for that project. Always flag this explicitly.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Remediation Safety Protocol
|
|
170
|
+
|
|
171
|
+
This is the most important section. `.qwen/` configuration is what makes Claude Code work. A broken config means a broken development environment. Every remediation action must follow these rules:
|
|
172
|
+
|
|
173
|
+
### Before any change
|
|
174
|
+
1. **Explain what will change and why** — No "cleaning up your config." Say exactly: "Removing `apps/casegate-v2/.qwen/hooks/carl-hook.py` because an identical version runs globally from `~/.qwen/hooks/dynamic-rules-loader.py`. The global hook already fires on every prompt in every project."
|
|
175
|
+
2. **Show evidence** — Side-by-side comparison, file dates, path references
|
|
176
|
+
3. **Wait for explicit approval** — Not "I'll go ahead and clean these up." Ask: "Approve this removal? [y/n]"
|
|
177
|
+
|
|
178
|
+
### During changes
|
|
179
|
+
4. **One category at a time** — Process all ACCIDENTAL items first (lowest risk), then DUPLICATES, then STALE, then DIVERGED. Save GLOBAL_CANDIDATE promotions for last.
|
|
180
|
+
5. **Verify after each change** — After removing a hook, confirm the project's settings.json no longer references it. After removing a skill, confirm no commands reference it.
|
|
181
|
+
6. **Never delete settings.json itself** — Even if everything in it is stale. The file's existence may matter. Clean its contents instead, or flag for operator to remove manually.
|
|
182
|
+
|
|
183
|
+
### After all changes
|
|
184
|
+
7. **Summary report** — What was changed, what was kept, what needs manual follow-up
|
|
185
|
+
8. **Recommend a test** — "Open Claude Code in {project} and verify hooks fire correctly"
|
|
186
|
+
|
|
187
|
+
### What this workflow NEVER does
|
|
188
|
+
- Modify `~/.qwen/` (global config) without explicit promotion approval
|
|
189
|
+
- Delete a `.qwen/` directory entirely (may have gitignore or settings implications)
|
|
190
|
+
- Batch-delete without per-item confirmation
|
|
191
|
+
- Assume a "messy" config is wrong — it may be working exactly as intended
|
|
192
|
+
- Move files between directories (copy + verify + then remove original)
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Output Format
|
|
197
|
+
|
|
198
|
+
The discovery phase produces an inventory. Present it as:
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
## .qwen/ Directory Inventory
|
|
202
|
+
|
|
203
|
+
Found {N} .qwen/ directories ({N} excluding templates and root).
|
|
204
|
+
|
|
205
|
+
### {relative/path/.qwen/}
|
|
206
|
+
hooks/: carl-hook.py, get-current-time-cst.py
|
|
207
|
+
settings.json: yes (hooks: 2 UserPromptSubmit)
|
|
208
|
+
settings.local.json: yes (MCP servers: 12)
|
|
209
|
+
skills/: ui-ux-pro-max/
|
|
210
|
+
commands/: (none)
|
|
211
|
+
Last modified: 2026-02-26
|
|
212
|
+
|
|
213
|
+
Classification:
|
|
214
|
+
- hooks/carl-hook.py → DUPLICATE (identical to ~/.qwen/hooks/dynamic-rules-loader.py)
|
|
215
|
+
- hooks/get-current-time-cst.py → DUPLICATE (identical to ~/.qwen/hooks/get-current-time-cst.sh)
|
|
216
|
+
- settings.json hooks → STALE (references local hook paths that would be removed)
|
|
217
|
+
- settings.local.json → PROJECT_SPECIFIC (MCP server list is project-tailored)
|
|
218
|
+
- skills/ui-ux-pro-max/ → DUPLICATE (exists at ~/.qwen/skills/ui-ux-pro-max/)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
The remediation phase groups by action type and risk level:
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
## Remediation Plan
|
|
225
|
+
|
|
226
|
+
### Safe Removals (ACCIDENTAL)
|
|
227
|
+
1. apps/hunter-exotics/.qwen/.qwen/ — nested .claude dir (accidental)
|
|
228
|
+
Action: Delete entire nested directory
|
|
229
|
+
Risk: None
|
|
230
|
+
|
|
231
|
+
### Duplicate Removals
|
|
232
|
+
2. apps/casegate-v2/.qwen/hooks/carl-hook.py — identical to global
|
|
233
|
+
Action: Delete file
|
|
234
|
+
Risk: Low — must also clean settings.json hook reference
|
|
235
|
+
|
|
236
|
+
(... etc, one per item ...)
|
|
237
|
+
|
|
238
|
+
### Requires Decision (DIVERGED)
|
|
239
|
+
5. apps/hunter-exotics/.qwen/settings.local.json — has project-specific MCP list
|
|
240
|
+
Local version: [12 servers including project-specific ones]
|
|
241
|
+
Global version: [different set]
|
|
242
|
+
Recommendation: Keep as PROJECT_SPECIFIC
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Composability
|
|
248
|
+
|
|
249
|
+
This strategy is a standalone reference document. It does not modify or depend on other strategy files. Any workflow can compose it in:
|
|
250
|
+
|
|
251
|
+
- `/base:audit-claude` — reads this strategy directly as its framework
|
|
252
|
+
- `/base:audit` — can reference this when auditing the system-layer area
|
|
253
|
+
- `/base:groom` — can optionally flag `.qwen/` drift during system-layer groom step
|
|
254
|
+
- Manual invocation — an operator can ask "audit my .claude dirs" and Claude reads this file
|
|
255
|
+
|
|
256
|
+
No registration in workspace.json is required. No modification to audit-strategies.md is needed.
|