chore - clean up stale yml references in documentation (#123)

* chore - clean up stale yml references in documentation

- update CLAUDE.md to reference rules/*.md instead of context/*.yml
- rewrite mantra/FORMAT.md for current rules-based architecture
- update companion docs (context-format.md, format-guide.md, test.md, rule-design.md)
- update skill files to reference rules/ and context/ directories
- update rules files (context-format.md, behavior.md)

* chore - bump plugin versions (mantra 0.4.2, memento 0.3.8, onus 0.3.3)

Author: dpuglielli

.claude-plugin/marketplace.json

@@ -8,19 +8,19 @@
       "name": "memento",
       "source": "./memento",
       "description": "Session persistence - persist context across conversation resets with branch-based session tracking",
-      "version": "0.3.7"
+      "version": "0.3.8"
     },
     {
       "name": "mantra",
       "source": "./mantra",
       "description": "Context refresh - periodic re-injection of behavioral guidance to prevent context drift",
-      "version": "0.4.1"
+      "version": "0.4.2"
     },
     {
       "name": "onus",
       "source": "./onus",
       "description": "Work-item automation - fetches issues, generates commits/PRs, syncs progress",
-      "version": "0.3.2"
+      "version": "0.3.3"
     }
   ]
 }

.claude/sessions/chore-cleanup-stale-yml-references.md

@@ -0,0 +1,38 @@
+# Session: chore/cleanup-stale-yml-references
+
+## Details
+- **Type**: Chore
+- **Branch**: `chore/cleanup-stale-yml-references`
+- **Created**: 2026-01-14
+
+## Goal
+Remove stale references to `.yml` context files throughout documentation. The project migrated from `context/*.yml` to `rules/*.md` but documentation still referenced the old pattern.
+
+## Session Log
+- 2026-01-14: Identified stale yml references in CLAUDE.md, FORMAT.md, shared code, and companion docs
+- 2026-01-14: Updated CLAUDE.md - meta table, plugin structure, context system, ownership table
+- 2026-01-14: Rewrote mantra/FORMAT.md to reflect rules/*.md pattern
+- 2026-01-14: Updated context/context-format.md and context/format-guide.md
+- 2026-01-14: Updated context/test.md and context/rule-design.md
+- 2026-01-14: Updated all skill files (work-item-handler, session-manager, resume)
+- 2026-01-14: Updated rules/context-format.md and rules/behavior.md
+- 2026-01-14: Note: shared/index.js keeps findYmlFiles() for backwards compatibility
+
+## Files Changed
+- CLAUDE.md
+- mantra/FORMAT.md
+- mantra/context/context-format.md
+- mantra/context/format-guide.md
+- mantra/context/test.md
+- mantra/context/rule-design.md
+- mantra/rules/context-format.md
+- mantra/rules/behavior.md
+- onus/skills/work-item-handler/SKILL.md
+- memento/skills/session-manager/SKILL.md
+- memento/skills/resume/SKILL.md
+
+## Next Steps
+- [x] Update documentation files
+- [x] Update skill files
+- [x] Update rules files
+- [ ] Commit and merge

CLAUDE.md

@@ -8,7 +8,7 @@ This repository is the source code for memento, mantra, and onus plugins—and t
 
 | Concept | Source Code (what we develop) | Running Instance (what's active) |
 |---------|------------------------------|----------------------------------|
-| mantra context | `mantra/context/*.yml` | Injected via hooks on each prompt |
+| mantra rules | `mantra/rules/*.md` | Injected via hooks on each prompt |
 | memento sessions | `memento/templates/*.md` | `.claude/sessions/*.md` in each plugin dir |
 | onus work items | `onus/hooks/work-item.js` | Tracking issues for this repo |
 
@@ -39,8 +39,8 @@ Each plugin follows the same structure:
 <plugin>/
 ├── .claude-plugin/plugin.json   # Plugin manifest
 ├── hooks/                       # Hook implementations (SessionStart, UserPromptSubmit)
-├── rules/                       # Rule files (*.md with YAML frontmatter)
-├── context/                     # Context files (*.yml) and companion docs
+├── rules/                       # Rule files (*.md with YAML frontmatter, auto-injected)
+├── context/                     # Companion docs (*.md, loaded on-demand)
 ├── commands/                    # Skill commands (*.md)
 ├── lib/                         # Bundled shared utilities
 └── package.json                 # Plugin dependencies
@@ -104,8 +104,8 @@ Run `npm run build` to re-bundle shared code after changes.
 ### Context System
 
 Two-tier context pattern:
-- `*.yml` - Compact rules, machine-optimized (~850 tokens vs ~7,750 for prose)
-- `*.md` - Detailed examples, loaded on-demand
+- `rules/*.md` - Compact rules in YAML frontmatter (auto-injected via hooks)
+- `context/*.md` - Detailed examples and companion docs (loaded on-demand)
 
 Context loading order: base (plugin) → sibling plugins → project extensions → CLAUDE.md
 
@@ -115,9 +115,9 @@ Each plugin owns specific context domains. When adding or modifying context, res
 
 | Plugin | Domain | Files |
 |--------|--------|-------|
-| **mantra** | AI behavior, format conventions | `behavior.yml`, `format-guide.yml`, `context-format.yml` |
-| **memento** | Session management | `sessions.yml` |
-| **onus** | Git operations, work items | `git.yml`, `work-items.yml` |
+| **mantra** | AI behavior, format conventions | `rules/behavior.md`, `rules/context-format.md`, `rules/format-guide.md`, `rules/test.md`, `rules/rule-design.md` |
+| **memento** | Session management | `rules/sessions.md` |
+| **onus** | Git operations, work items | `rules/git.md`, `rules/work-items.md` |
 
 **Ownership rules:**
 - Single source of truth: each concept defined in exactly one place

mantra/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mantra",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Behavioral rules for Claude Code sessions - auto-injected via hooks, zero config",
   "author": {
     "name": "David Puglielli"

mantra/FORMAT.md

@@ -6,20 +6,24 @@ This document defines the format for context files used by mantra.
 
 **Base context** (shipped with plugin):
 ```
-<plugin-root>/context/
-├── behavior.yml       # AI behavior rules
-├── behavior.md        # Detailed behavior guide
-├── context-format.yml # Format specification
-├── context-format.md  # Detailed format guide
-└── format-guide.yml   # Compact YAML conventions
+<plugin-root>/
+├── rules/                 # Rule files (auto-injected)
+│   ├── behavior.md        # AI behavior rules (frontmatter + optional body)
+│   ├── test.md            # Testing conventions
+│   └── ...
+└── context/               # Companion docs (on-demand)
+    ├── behavior.md        # Detailed behavior guide
+    ├── test.md            # Detailed test examples
+    └── ...
 ```
 
 **Project extensions** (your project):
 ```
-.claude/context/
-├── project.yml        # Project-specific context
-├── testing.yml        # Testing patterns
-└── *.yml              # Additional context
+.claude/
+├── rules/                 # Project rule overrides
+│   └── *.md               # Custom rules with YAML frontmatter
+└── context/               # Project companion docs
+    └── *.md               # Detailed examples
 ```
 
 **Loading order**: base → sibling plugins → project extensions → CLAUDE.md
@@ -28,22 +32,47 @@ This document defines the format for context files used by mantra.
 
 Each topic should have TWO files:
 
-### 1. YAML File (`.yml`)
+### 1. Rule File (`rules/*.md`)
 **Purpose:** Quick context injection for Claude
+**Format:** YAML frontmatter (extracted and injected automatically)
 **Characteristics:**
 - Token-efficient (aim for 89% reduction vs prose)
-- Key-value assertions
+- Key-value assertions in frontmatter
 - Minimal prose
-- Target size: 10-30 lines
+- Target size: 10-30 lines of frontmatter
 
-### 2. Markdown File (`.md`)
+### 2. Companion Doc (`context/*.md`)
 **Purpose:** Detailed reference for humans and Claude deep-dives
 **Characteristics:**
 - Full prose explanations
 - Code examples
 - Edge cases and troubleshooting
 - Not injected automatically (read on-demand)
 
+## Rule File Format
+
+Rule files use YAML frontmatter with an optional markdown body:
+
+```markdown
+---
+companion: behavior.md
+type: actionable
+
+## Assessment
+stance: skeptical-default
+assess-first: correctness, architecture, risks
+never: eager-agreement, sycophantic-tone
+
+## Implementation
+mode: discuss-first (non-trivial) | build-first (trivial)
+order: syntax → runtime → logic → optimize
+---
+
+Optional body content (usually omitted for rule files).
+```
+
+The frontmatter between `---` markers is extracted and injected.
+
 ## YAML Format Conventions
 
 ### Operators
@@ -71,14 +100,15 @@ Each topic should have TWO files:
 
 **Don't:**
 - Write complete sentences
-- Include explanations (put in `.md` file)
+- Include explanations (put in companion `.md` file)
 - Use markdown formatting in YAML
 - Repeat information
 
-### Example
+### Example Frontmatter
 
 ```yaml
-# behavior.yml - Compact Reference
+# behavior.md - Compact Reference
+companion: context/behavior.md
 
 ## Assessment
 stance: skeptical-default
@@ -102,18 +132,17 @@ skip: simple-DTOs, getters, boilerplate
 
 | File | Purpose |
 |------|---------|
-| `project.yml` | Project identity, architecture, tech stack |
-| `behavior.yml` | AI behavior rules, assessment stance |
-| `git.yml` | Git conventions, commit format, PR rules |
-| `testing.yml` | Testing patterns, what to test/skip |
-| `sessions.yml` | Session management workflow |
-| `<domain>.yml` | Domain-specific context |
+| `behavior.md` | AI behavior rules, assessment stance |
+| `git.md` | Git conventions, commit format, PR rules |
+| `test.md` | Testing patterns, what to test/skip |
+| `sessions.md` | Session management workflow |
+| `<domain>.md` | Domain-specific rules |
 
 ### Naming Rules
 - Use lowercase
 - Use hyphens for multi-word names
 - Be descriptive but concise
-- Pair with same-name `.md` file for details
+- Pair with same-name companion file in `context/` for details
 
 ## Token Efficiency
 
@@ -132,13 +161,13 @@ Context files are injected into Claude's context window. Efficiency matters.
 
 1. **Abbreviate consistently** - Use same short forms throughout
 2. **Omit obvious context** - Don't repeat what's in project files
-3. **Use references** - Point to `.md` files for details
+3. **Use references** - Point to companion `.md` files for details
 4. **Prioritize** - Put most important rules first
 5. **Prune regularly** - Remove obsolete content
 
 ## Interpretation Guide
 
-When Claude reads compact YAML:
+When Claude reads compact YAML frontmatter:
 
 | Pattern | Interpretation |
 |---------|----------------|
@@ -153,7 +182,7 @@ When Claude reads compact YAML:
 
 mantra validates:
 - File exists and is readable
-- Valid YAML syntax
+- Valid YAML frontmatter syntax
 - File size within limits
 
 mantra does NOT validate:
@@ -166,8 +195,8 @@ mantra does NOT validate:
 If migrating from a single `CLAUDE.md`:
 
 1. **Identify topics** - Group related rules
-2. **Extract assertions** - Pull out key rules for YAML
-3. **Keep details** - Leave examples/explanations in `.md`
+2. **Create rule file** - Add YAML frontmatter to `rules/<topic>.md`
+3. **Keep details** - Leave examples/explanations in `context/<topic>.md`
 4. **Test refresh** - Verify context injects correctly
 
 ### Before (CLAUDE.md excerpt)
@@ -179,10 +208,14 @@ or Co-Authored-By tags. Commit messages should be lowercase after
 the issue number. Format: "#N - verb description"
 ```
 
-### After (git.yml)
-```yaml
+### After (rules/git.md)
+```markdown
+---
 # Git Workflow - Compact Reference
+companion: context/git.md
+
 commit-format: "#N - verb desc" | "chore - desc"
 commit-style: HEREDOC, lowercase-after-dash
 no: attribution, co-authored-by, emojis
+---
 ```