qwen-base 1.0.0

package/src/framework/frameworks/claudemd-strategy.md

@@ -0,0 +1,158 @@
+# The CLAUDE.md Strategy
+
+Composable framework for auditing and writing high-performance CLAUDE.md files. Source of truth for the `/base:audit-claude-md` workflow.
+
+---
+
+## The Structure: What, Why, Who, Where, How
+
+Every CLAUDE.md follows five sections in this exact order. Each section answers one question. Together they give Claude complete operating context without bloat.
+
+### What
+What this document is and what this workspace contains.
+
+One line. Sets the contract. Claude knows this is its instruction set.
+
+> "This file provides guidance to Claude Code when working with code in this repository."
+
+### Why
+The philosophy. Identity context. Why this workspace exists.
+
+This is where you separate identity from operations. CLAUDE.md answers the "who am I working with?" question. Operational details (how to run a specific project, current sprint status) live elsewhere and get referenced with `@` pointers.
+
+### Who
+Business context. Who the user is, what they do, what matters to them.
+
+Not a life story. Enough context that Claude can make relevant suggestions. Business name, what the business does, revenue model, team, tech stack. The goal: Claude should be able to answer "what does this person's business look like?" after reading this section.
+
+### Where
+Workspace structure. The directory map.
+
+This section serves double duty:
+1. Tells Claude where to find things
+2. Plants the blueprint for the workspace architecture — the Where section describes a structure that may or may not exist yet
+
+Use a tree diagram. Include:
+- Each top-level directory and its purpose
+- Key subdirectories if they have meaning
+- What goes where (decision guide)
+
+### How
+Ecosystem strategy. Tool strategy. Git strategy. Quick references.
+
+This is the operational layer:
+- What systems/frameworks are in use (compact table with location pointers)
+- Git strategy (what gets tracked, what gets ignored)
+- Rules (see NEVER pattern below)
+- Quick reference table for common actions
+
+---
+
+## The NEVER Pattern: Rules as Anti-Patterns
+
+**The single most important discovery from 40+ sessions of compliance testing.**
+
+### The Pattern
+
+```
+NEVER [wrong action] — [right action]
+```
+
+Negative framing with absolute language gets near-perfect adherence. Every high-compliance rule follows this format.
+
+### Why This Works
+
+It's a binary check. Claude can look at its own output and ask: "Did I do the forbidden thing or not?" No judgment call. No interpretation. No sliding scale.
+
+| Framing | Compliance | Why |
+|---------|-----------|-----|
+| "Try to use templates when possible" | ~40% | Ambiguous. "When possible" is a judgment call Claude resolves toward skipping. |
+| "Always use templates" | ~65% | Better, but "always" gets weighed against context. Claude may decide exceptions apply. |
+| "NEVER create from scratch — use templates" | ~95% | Binary. The forbidden action is unambiguous. |
+
+### Rules for Writing Rules
+
+1. **One rule per line.** No compound rules. If it has "and" in it, split it.
+2. **The wrong action comes first.** Claude anchors on the first thing it reads. Make the forbidden action the anchor.
+3. **The right action is the alternative.** Not a lecture — a redirect. "Don't do X — do Y instead."
+4. **Defer complexity to reference docs.** The rule stays short. The details live in a separate file loaded on demand.
+
+---
+
+## The @ Reference System
+
+CLAUDE.md stays lean by pointing to other files instead of inlining their content.
+
+```
+@LINKS.md — Personal branding URLs
+@projects/dashboard-build/PLANNING.md — Active project context
+```
+
+Claude reads `@`-referenced files on demand. Your CLAUDE.md stays lean while still giving Claude access to deep context.
+
+**What to inline vs what to reference:**
+- **Inline:** Identity (who, what, why), workspace structure, rules, quick references
+- **Reference:** Active project details, task lists, state files, detailed specs
+
+---
+
+## What Stays Out
+
+The test: **if it changes every week, it doesn't belong in CLAUDE.md.**
+
+CLAUDE.md is the constitution, not the daily newspaper.
+
+| Doesn't belong | Where it goes |
+|----------------|---------------|
+| Task lists / current work | State files, project tracking systems |
+| Project specs | Each project's PLANNING.md |
+| Rules for specific domains | Domain-specific rule files loaded on demand (e.g., CARL) |
+| Daily status updates | State files |
+| Detailed framework docs | Separate files, `@`-referenced |
+
+---
+
+## Line Budget
+
+Target: **under 100 lines.** This is a routing document, not a knowledge base.
+
+If your CLAUDE.md is over 100 lines, content is being inlined that should be referenced or removed. Common offenders:
+- Inline system/framework descriptions (replace with a compact table)
+- Redundant location tables when a tree diagram already exists
+- Documentation system descriptions (the tree covers this)
+- Standalone sections for single rules (consolidate into Rules section)
+
+---
+
+## Audit Criteria
+
+When auditing an existing CLAUDE.md, check:
+
+### Structure
+- [ ] Follows What → Why → Who → Where → How order
+- [ ] Each section is correctly labeled
+- [ ] No orphan sections outside the five-section model
+
+### Content Placement
+- [ ] Identity/philosophy in Why (not scattered)
+- [ ] Business context in Who (not bloated)
+- [ ] Directory map in Where (tree format, not just a table)
+- [ ] All operational content in How (git, systems, rules, quick ref)
+- [ ] No task lists, state files, or volatile data inlined
+
+### Rules
+- [ ] All rules use NEVER pattern (not "always", "try to", "prefer")
+- [ ] One rule per line, no compound rules
+- [ ] Wrong action first, right action as redirect
+- [ ] Complex rules defer to reference docs
+
+### Leanness
+- [ ] Under 100 lines (excluding code blocks in Where tree)
+- [ ] No redundant sections (e.g., key locations table + tree diagram)
+- [ ] System descriptions are a compact table, not inline paragraphs
+- [ ] `@` references used for anything that changes frequently
+
+### CARL Integration (if present)
+- [ ] Operational rules that belong in domain-specific contexts are flagged for CARL migration
+- [ ] CLAUDE.md rules are constitutional (identity-level), not operational
+- [ ] No duplication between CLAUDE.md rules and CARL domain rules

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

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

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

@@ -0,0 +1,171 @@
+<purpose>
+Audit an existing CLAUDE.md against the CLAUDE.md Strategy framework, then interactively rewrite it with user approval at each stage. Detects CARL installation and routes operational rules accordingly.
+</purpose>
+
+<user-story>
+As an AI builder, I want my CLAUDE.md audited against a proven strategy so I get a compliant, lean configuration file — with operational rules properly routed to CARL or preserved as an artifact for later.
+</user-story>
+
+<when-to-use>
+- During /base:scaffold (optional step)
+- When user says "audit my claude.md", "improve my claude.md", "rewrite my claude.md"
+- Entry point: /base:audit-claude-md
+</when-to-use>
+
+<context-files>
+@{~/.qwen/commands/qwen-base/frameworks/claudemd-strategy.md}
+@{~/.qwen/commands/qwen-base/templates/claudemd-template.md}
+</context-files>
+
+<steps>
+
+<step name="load_strategy" priority="first">
+Load the CLAUDE.md Strategy framework and template.
+
+1. Read `@{~/.qwen/commands/qwen-base/frameworks/claudemd-strategy.md}` — this is the source of truth
+2. Read `@{~/.qwen/commands/qwen-base/templates/claudemd-template.md}` — this is the structural reference
+3. Internalize: five-section model (What/Why/Who/Where/How), NEVER pattern, line budget, audit criteria
+
+You MUST understand the full strategy before reading the user's file. The strategy defines what "correct" looks like.
+</step>
+
+<step name="read_and_catalog">
+Read the user's existing CLAUDE.md and catalog every piece of content.
+
+1. Read `CLAUDE.md` from workspace root
+2. If no CLAUDE.md exists → skip to `generate_fresh` step
+3. For every section, paragraph, rule, table, and reference in the file, classify each as:
+   - **KEEP** — belongs in CLAUDE.md per the strategy (identity, structure, constitutional rules)
+   - **REMOVE** — doesn't belong (volatile data, task lists, state references, redundant sections)
+   - **RESTRUCTURE** — right content, wrong location or format (e.g., rule using "always" instead of NEVER pattern, operational content in wrong section)
+   - **CARL_CANDIDATE** — operational rule or domain-specific behavior that belongs in a rules engine, not CLAUDE.md
+
+4. Count total lines. Note if over 100-line budget.
+</step>
+
+<step name="present_audit">
+Present the full audit to the user. This is INTERACTIVE — do not proceed without approval.
+
+Present a structured report:
+
+**Section Order Compliance:**
+- Current order vs required order (What → Why → Who → Where → How)
+- Orphan sections (content outside the five-section model)
+
+**Content Classification:**
+For each piece of existing content, show:
+```
+[KEEP] "Business context section" → stays in Who
+[REMOVE] "Active Work section" → volatile, belongs in state management
+[RESTRUCTURE] "LSP rule" → move to How/Rules, convert to NEVER pattern
+[CARL_CANDIDATE] "When writing tests, always..." → operational rule, not identity
+```
+
+**Line Budget:**
+- Current: {N} lines
+- Target: under 100
+- Reduction plan: what removal/restructuring achieves
+
+**Missing Content:**
+- Sections required by strategy that don't exist yet
+
+Ask: **"Does this audit look right? Any items you want to reclassify before I proceed?"**
+
+Wait for user response. Adjust classifications based on their feedback.
+</step>
+
+<step name="detect_carl">
+Check for CARL installation to determine rule routing.
+
+1. Check for `.carl/manifest` in workspace root (workspace-level CARL)
+2. Check for `~/.carl/manifest` (global-level CARL)
+3. If CARL found:
+   - Report: "CARL detected at {location}. Operational rules will be proposed as CARL domain rules."
+   - Note which existing CARL domains overlap with CARL_CANDIDATE items
+4. If CARL not found:
+   - Report: "No CARL installation detected."
+   - Offer: "I can: (a) install CARL now and set up domains, or (b) save operational rules as an artifact in `.base/artifacts/` for later CARL setup"
+   - If user picks (b): rules go to `.base/artifacts/claudemd-audit-rules.md` (create `.base/artifacts/` if needed)
+   - If user picks (a): guide CARL installation, then route rules to domains
+
+Wait for user decision before proceeding.
+</step>
+
+<step name="propose_rewrite">
+Build the new CLAUDE.md section by section, presenting each for approval.
+
+For EACH section (What, Why, Who, Where, How):
+
+1. **Show the proposed content** for that section
+2. **Show what changed** vs the original (additions, removals, restructuring)
+3. **Ask for approval**: "Accept this section? Or modify?"
+4. If user modifies → incorporate changes
+5. If user accepts → lock section, move to next
+
+**Section-specific guidance:**
+
+**What:** One-liner. Rarely needs changes unless missing entirely.
+
+**Why:** Philosophy/identity. Pull from existing philosophy content. Strip operational routing details that belong in How.
+
+**Who:** Business context. Preserve existing content. Trim if bloated. Ensure it answers "what does this person's business look like?"
+
+**Where:** Scan actual filesystem with `ls` to verify tree accuracy. Update tree to match reality. Remove subdirectories that don't add meaning. Collapse verbose trees to stay within budget.
+
+**How:** Assemble from:
+- Systems table (compact, one row per system)
+- Git strategy table (from existing or detected .gitignore)
+- Rules (NEVER pattern only — constitutional rules stay here, operational rules route to CARL/artifact)
+- Quick reference (common actions → instructions)
+</step>
+
+<step name="route_carl_candidates">
+Handle operational rules that were classified as CARL_CANDIDATE.
+
+**If CARL is installed:**
+1. Group candidates by likely CARL domain (DEVELOPMENT, CONTENT, CLIENTS, etc.)
+2. Present: "These rules are proposed for CARL domain `{domain}`:"
+3. Show each rule in NEVER pattern format
+4. Ask: "Approve these for CARL? Modify? Skip?"
+5. For approved rules: provide the exact CARL command to add them (do NOT execute without explicit permission)
+
+**If CARL artifact path:**
+1. Write all CARL_CANDIDATE rules to `.base/artifacts/claudemd-audit-rules.md`
+2. Format: group by proposed domain, NEVER pattern, include rationale
+3. Tell user: "Rules saved to `.base/artifacts/claudemd-audit-rules.md`. When you're ready to set up CARL, run this file through Claude to create the domains."
+</step>
+
+<step name="write_and_finalize">
+Write the approved CLAUDE.md.
+
+1. Assemble all approved sections into final document
+2. Verify line count (warn if over 100)
+3. Write to `CLAUDE.base.md` in workspace root (NEVER overwrite CLAUDE.md directly)
+4. Present final diff summary: sections added, removed, restructured, rules routed
+
+Tell user:
+- "Review `CLAUDE.base.md`. To adopt it: `mv CLAUDE.base.md CLAUDE.md`"
+- "Your original CLAUDE.md is untouched."
+- If CARL candidates were routed: "Operational rules are in {location}."
+</step>
+
+</steps>
+
+<output>
+- `CLAUDE.base.md` — strategy-compliant CLAUDE.md ready for adoption
+- CARL domain rules (if CARL installed) or `.base/artifacts/claudemd-audit-rules.md` (if not)
+- Original CLAUDE.md untouched
+</output>
+
+<acceptance-criteria>
+- [ ] Strategy framework loaded and understood before audit begins
+- [ ] Every line of existing CLAUDE.md classified (KEEP/REMOVE/RESTRUCTURE/CARL_CANDIDATE)
+- [ ] Full audit presented to user with approval gate before rewriting
+- [ ] CARL installation detected and rule routing decided with user
+- [ ] Each section proposed individually with user approval
+- [ ] All rules use NEVER pattern
+- [ ] Final output under 100 lines
+- [ ] Operational rules routed to CARL or saved as artifact
+- [ ] Original CLAUDE.md never modified
+- [ ] User informed of how to adopt and next steps
+</acceptance-criteria>