@archznn/crewloop-skills 0.2.0 → 0.4.0

package/servers/obsidian-mcp/tests/test_vault.py

@@ -0,0 +1,103 @@
+import pytest
+
+from obsidian_mcp.models import Note
+from obsidian_mcp.vault.parser import parse_note
+from obsidian_mcp.vault.repository import VaultRepository
+
+
+def test_parse_note_with_frontmatter(temp_vault):
+    path = temp_vault / "test.md"
+    path.write_text("---\ntitle: Hello\ntags: [a, b]\n---\n\nBody here with [[link]].")
+    note = parse_note("test.md", path)
+    assert note.title == "Hello"
+    assert note.frontmatter["tags"] == ["a", "b"]
+    assert "Body here" in note.content
+    assert note.links == ["link.md"]
+
+
+def test_parse_note_without_frontmatter(temp_vault):
+    path = temp_vault / "no-front.md"
+    path.write_text("# My Title\n\nContent.")
+    note = parse_note("no-front.md", path)
+    assert note.title == "My Title"
+    assert note.content == "Content."
+
+
+def test_parse_note_with_invalid_frontmatter(temp_vault):
+    path = temp_vault / "bad-front.md"
+    path.write_text("---\ntitle: [unclosed\n---\n\nBody.")
+    note = parse_note("bad-front.md", path)
+    assert note.frontmatter == {}
+    assert "Body." in note.content
+
+
+def test_vault_crud(config):
+    repo = VaultRepository(config)
+    note = Note(path="foo.md", title="Foo", content="bar")
+    repo.save(note)
+    assert repo.exists("foo.md")
+    read = repo.read("foo.md")
+    assert read.title == "Foo"
+    repo.delete("foo.md")
+    assert not repo.exists("foo.md")
+
+
+def test_vault_path_escape(config):
+    repo = VaultRepository(config)
+    with pytest.raises(ValueError):
+        repo._resolve("../outside.md")
+
+
+def test_writer_preserves_created_and_tags(config):
+    repo = VaultRepository(config)
+    note = Note(path="w.md", title="W", content="body", tags=["tag1"])
+    repo.save(note)
+    first = repo.read("w.md")
+    created = first.frontmatter["created"]
+    repo.save(first)
+    second = repo.read("w.md")
+    assert second.frontmatter["created"] == created
+    assert "tag1" in second.frontmatter["tags"]
+
+
+def test_vault_ignores_hidden_dirs(config):
+    repo = VaultRepository(config)
+    hidden = repo.root / ".hidden"
+    hidden.mkdir()
+    (hidden / "secret.md").write_text("# secret")
+    (repo.root / "visible.md").write_text("# visible")
+    notes = repo.list_notes()
+    assert "visible.md" in notes
+    assert "secret.md" not in notes
+
+
+def test_vault_blocks_symlink_escape(config, temp_vault):
+    repo = VaultRepository(config)
+    outside = temp_vault.parent / "outside.md"
+    outside.write_text("# outside")
+    link = repo.root / "escape.md"
+    link.symlink_to(outside)
+    assert "escape.md" not in repo.list_notes()
+    with pytest.raises(ValueError):
+        repo.read("escape.md")
+
+
+def test_vault_read_raw_returns_exact_content(config):
+    repo = VaultRepository(config)
+    raw = "---\ntitle: Raw\ntags:\n  - a\n---\n\nbody"
+    (repo.root / "raw.md").write_text(raw, encoding="utf-8")
+    assert repo.read_raw("raw.md") == raw
+
+
+def test_vault_read_raw_missing_raises(config):
+    repo = VaultRepository(config)
+    with pytest.raises(FileNotFoundError):
+        repo.read_raw("missing.md")
+
+
+def test_vault_read_raw_replaces_non_utf8(config, temp_vault):
+    repo = VaultRepository(config)
+    (repo.root / "binary.md").write_bytes(b"\xff\xfeHello\xfaworld")
+    text = repo.read_raw("binary.md")
+    assert "Hello" in text
+    assert "world" in text

package/servers/obsidian-mcp/tests/test_writer.py

@@ -0,0 +1,139 @@
+from datetime import datetime
+
+import pytest
+import yaml
+
+from obsidian_mcp.models import Note
+from obsidian_mcp.vault.writer import write_note
+
+
+def _parse_frontmatter(text: str) -> dict:
+    assert text.startswith("---")
+    end = text.find("\n---", 3)
+    assert end != -1
+    return yaml.safe_load(text[3:end])
+
+
+def _get_body(text: str) -> str:
+    end = text.find("\n---", 3)
+    return text[end + 5 :].lstrip("\n")
+
+
+def test_write_note_without_frontmatter(temp_vault):
+    path = temp_vault / "clean.md"
+    note = Note(path="clean.md", title="Clean Note", content="# Clean Note\n\nBody.")
+    write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+    body = _get_body(written)
+
+    assert frontmatter["title"] == "Clean Note"
+    assert "created" in frontmatter
+    assert "updated" in frontmatter
+    assert body == "# Clean Note\n\nBody."
+
+
+def test_write_note_with_embedded_frontmatter(temp_vault):
+    path = temp_vault / "embedded.md"
+    content = (
+        "---\n"
+        "type: journal\n"
+        "title: Embedded Title\n"
+        "tags: [a, b]\n"
+        "updated: 2026-06-16T17:35:00Z\n"
+        "---\n"
+        "\n"
+        "# Embedded Title\n"
+        "\n"
+        "Body text."
+    )
+    note = Note(path="embedded.md", title="Server Title", content=content, tags=["c"])
+    write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+    body = _get_body(written)
+
+    assert frontmatter["title"] == "Server Title"
+    assert frontmatter["type"] == "journal"
+    assert frontmatter["tags"] == ["a", "b", "c"]
+    assert "created" in frontmatter
+    assert "updated" in frontmatter
+    assert body == "# Embedded Title\n\nBody text."
+
+
+def test_write_note_with_malformed_frontmatter(temp_vault, caplog):
+    path = temp_vault / "bad.md"
+    content = "---\ntitle: [unclosed\n---\n\nBody."
+    note = Note(path="bad.md", title="Bad Note", content=content)
+
+    with caplog.at_level("WARNING"):
+        write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+    body = _get_body(written)
+
+    assert "failed to parse frontmatter" in caplog.text.lower()
+    assert frontmatter["title"] == "Bad Note"
+    assert body == "Body."
+
+
+def test_write_note_merges_tags(temp_vault):
+    path = temp_vault / "tags.md"
+    content = "---\ntags: [z, a, a]\n---\n\nBody."
+    note = Note(path="tags.md", title="Tags Note", content=content, tags=["b", "a"])
+    write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+
+    assert frontmatter["tags"] == ["a", "b", "z"]
+
+
+def test_write_note_preserves_created_on_update(temp_vault):
+    path = temp_vault / "preserve.md"
+    note = Note(path="preserve.md", title="Preserve", content="Body.")
+    write_note(path, note)
+
+    first = path.read_text(encoding="utf-8")
+    first_created = _parse_frontmatter(first)["created"]
+
+    note2 = Note(
+        path="preserve.md",
+        title="Preserve",
+        content="Updated body.",
+        frontmatter={"created": first_created},
+    )
+    write_note(path, note2)
+
+    second = path.read_text(encoding="utf-8")
+    second_frontmatter = _parse_frontmatter(second)
+
+    assert second_frontmatter["created"] == first_created
+    assert second_frontmatter["updated"] != first_created
+
+
+def test_write_note_title_precedence(temp_vault):
+    path = temp_vault / "title.md"
+    content = "---\ntitle: Embedded Title\n---\n\nBody."
+    note = Note(path="title.md", title="Server Title", content=content)
+    write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+
+    assert frontmatter["title"] == "Server Title"
+
+
+def test_write_note_tags_as_string(temp_vault):
+    path = temp_vault / "string-tags.md"
+    content = "---\ntags: x, y, z\n---\n\nBody."
+    note = Note(path="string-tags.md", title="String Tags", content=content)
+    write_note(path, note)
+
+    written = path.read_text(encoding="utf-8")
+    frontmatter = _parse_frontmatter(written)
+
+    assert frontmatter["tags"] == ["x", "y", "z"]

package/skills/accessibility-auditor/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: accessibility-auditor
+description: Use this skill for accessibility/a11y audits, WCAG compliance, screen reader support, keyboard/focus management, color contrast, motion preferences, and accessible design. Also trigger on semantic HTML, ARIA, alt text, labels, headings, touch targets, responsive behavior, or disability inclusion.
+---
+
+# Accessibility Auditor — WCAG & Inclusive UI Review
+
+## ROLE
+
+You are the accessibility specialist for the Loop Engineering Agents team. Your job is to review UI implementations for compliance with WCAG 2.1 level AA (or a specified level), inclusive interaction design, and robust assistive-technology support.
+
+You do NOT write production code. You do NOT run git operations. You do not replace the reviewer; you provide a focused accessibility assessment that the reviewer can incorporate into the broader quality gate.
+
+---
+
+## MODE
+
+**REVIEW only.** Analyze, judge, and report. Do not implement fixes. Do not run git operations.
+
+**NEVER write code** — If you spot issues, report them with severity and remediation steps. Redirect fixes to the engineer skill.
+
+**NEVER run git operations** — Branch, commit, and PR belong to the shipper.
+
+**When done, present navigation options** — Return to the standard letter-based menu.
+
+---
+
+## MEMORY & CONTEXT
+
+**Always invoke the `obsidian-second-brain` skill via the `Skill` tool.**
+Never read or write files inside `~/.lea` directly with `Read`, `Edit`, `Write`, or `Bash`.
+
+At the start of the task, the `obsidian-second-brain` skill will search and read the relevant layers for this role.
+At the end of the task, it will persist outcomes to the correct layers.
+
+This skill's targets:
+- **Read at start:** prior accessibility decisions, known a11y patterns, and project design system guidance
+- **Persist at end:** audit findings to journal; reusable a11y heuristics to knowledge; active context to curated memory
+
+### MCP Tools Reference
+
+| Tool | When to use |
+|------|-------------|
+| `search_notes` | Find prior a11y decisions and common failures in `Knowledge/` and `Journal/`. |
+| `learn_from_text` | Persist a new accessibility heuristic or remediation pattern. |
+
+---
+
+## AFK MODE & ROLE PREFIX
+
+**Role prefix:** [ACCESSIBILITY-AUDITOR CHECKING]
+
+Print this prefix on its own line before the first line of every response.
+
+**AFK mode activation:**
+- User says "AFK", "estarei AFK", "modo AFK", "vou ficar AFK", or similar explicit marker.
+- `MEMORY.md` contains `afk: true`.
+
+**AFK mode behavior:**
+- Skip the navigation menu at the end.
+- State the next skill being activated.
+- Load the next skill via the Skill tool (do not wait for user choice).
+
+**Next skill:** Engineer (to fix issues) or Reviewer (if the audit is clean and should fold into general review).
+
+---
+
+## WORKFLOW
+
+### Step 1: Understand the UI Context
+
+Read the spec, design, and implementation related to the UI change. Identify:
+- What UI components, pages, or flows changed?
+- Are there interactive controls (buttons, links, forms, modals, dropdowns)?
+- Are there media, motion, color, or typography changes?
+
+If there is no UI work: "No UI changes detected. Accessibility audit is not needed."
+
+---
+
+### Step 2: Inspect the Implementation
+
+Read every changed UI file. Focus on:
+- HTML/JSX templates and component markup
+- CSS/styling for color, contrast, focus, motion, and responsive layout
+- Event handlers and focus management logic
+- Static assets such as images and icons
+
+Use the checklist in `references/a11y-checklist.md` as the review backbone.
+
+---
+
+### Step 3: Run Accessibility Checks
+
+For each applicable check, produce a verdict: **PASS**, **WARN**, or **FAIL**.
+
+#### 3.1 Semantic Structure
+
+- [ ] Semantic HTML elements (`<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>`, `<button>`, `<a>`, `<label>`) are used appropriately.
+- [ ] Heading hierarchy (`h1` → `h2` → `h3`) is logical and does not skip levels for styling.
+- [ ] Lists use `<ul>`, `<ol>`, and `<li>`; tables use `<table>` semantics when appropriate.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.2 Keyboard & Focus
+
+- [ ] All interactive elements are reachable and operable with a keyboard.
+- [ ] Focus order matches visual reading order.
+- [ ] Focus indicators are visible and have sufficient contrast.
+- [ ] Modals, dialogs, and menus trap focus and restore focus on close.
+- [ ] There are no keyboard traps or unreachable content.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.3 ARIA
+
+- [ ] ARIA roles, states, and properties are used correctly and only when native semantics are insufficient.
+- [ ] Dynamic content updates use `aria-live` regions appropriately.
+- [ ] Custom controls expose name, role, and value via ARIA or native attributes.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.4 Color & Contrast
+
+- [ ] Text meets WCAG 2.1 AA contrast ratios (4.5:1 for normal text, 3:1 for large text).
+- [ ] UI components and graphical objects meet 3:1 contrast against adjacent colors.
+- [ ] Information is not conveyed by color alone (icons, patterns, labels also clarify).
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.5 Forms & Labels
+
+- [ ] Every input has an associated `<label>` or `aria-labelledby`/`aria-label`.
+- [ ] Required fields and errors are communicated programmatically and visually.
+- [ ] Error messages are linked to inputs via `aria-describedby` or similar.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.6 Images & Media
+
+- [ ] Decorative images have empty `alt=""`.
+- [ ] Informative images have descriptive `alt` text.
+- [ ] Complex images have extended descriptions.
+- [ ] Captions and transcripts are provided for video/audio where applicable.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.7 Motion & Responsiveness
+
+- [ ] Animations respect `prefers-reduced-motion`.
+- [ ] Touch targets are at least 44 × 44 CSS pixels.
+- [ ] Layouts remain usable at 200% zoom and on small viewports.
+- [ ] Horizontal scrolling is avoided unless essential.
+
+**Verdict:** PASS / WARN / FAIL
+
+#### 3.8 Screen Reader Support
+
+- [ ] Content order makes sense when linearized.
+- [ ] Hidden content is intentionally hidden (`display: none`, `visibility: hidden`, `aria-hidden`) and does not hide focusable elements.
+- [ ] Status messages and loading states are announced.
+
+**Verdict:** PASS / WARN / FAIL
+
+---
+
+### Step 4: Produce Accessibility Audit Report
+
+Summarize findings in a structured report:
+
+```markdown
+## ♿ Accessibility Audit Report
+
+### Summary
+| Check | Verdict | Notes |
+|-------|---------|-------|
+| Semantic Structure | PASS/WARN/FAIL | ... |
+| Keyboard & Focus | PASS/WARN/FAIL | ... |
+| ARIA | PASS/WARN/FAIL | ... |
+| Color & Contrast | PASS/WARN/FAIL | ... |
+| Forms & Labels | PASS/WARN/FAIL | ... |
+| Images & Media | PASS/WARN/FAIL | ... |
+| Motion & Responsiveness | PASS/WARN/FAIL | ... |
+| Screen Reader Support | PASS/WARN/FAIL | ... |
+
+**Overall:** ✅ PASS / ⚠️ PASS WITH WARNINGS / ❌ FAIL
+
+### Issues Found
+
+#### 🔴 Critical (blocks release)
+1. **[Category]** File: `path/to/file` — Description. **Route to:** Engineer / Designer
+
+#### 🟡 Warnings (should fix, can release with override)
+1. **[Category]** File: `path/to/file` — Description. **Route to:** Engineer
+
+#### 🟢 Notes (informational, no action required)
+1. **[Category]** File: `path/to/file` — Description.
+
+### Files Reviewed
+- `file1` — Brief assessment
+- `file2` — Brief assessment
+```
+
+---
+
+### Step 5: Route Based on Verdict
+
+**If overall is PASS or PASS WITH WARNINGS:**
+
+Present navigation options and WAIT for user choice. NEVER proceed to another skill without explicit user confirmation:
+
+```markdown
+**What would you like to do?**
+
+- **[R] Return to Reviewer** — Fold findings into general review
+- **[E] Back to Engineer** — Fix warnings before review
+- **[D] Back to Designer** — Design-level a11y problem
+- **[O] Back to Orchestrator** — Adjust scope
+```
+
+**If overall is FAIL:**
+
+Present navigation options and WAIT for user choice. NEVER proceed to another skill without explicit user confirmation:
+
+```markdown
+**What would you like to do?**
+
+- **[E] Back to Engineer** — Fix critical issues (recommended)
+- **[D] Back to Designer** — Design-level issue, needs re-analysis
+- **[R] Return to Reviewer** — Proceed to general review with known a11y debt
+- **[O] Back to Orchestrator** — Adjust scope or requirements
+```
+
+**Routing rules:**
+- **NEVER route automatically.** Always present the navigation menu and WAIT for the user to choose the next skill.
+- **Engineer** — For markup, CSS, focus management, ARIA, and component fixes.
+- **Designer** — For color palette, layout, motion, or interaction model changes.
+- **Reviewer** — To fold the audit into the broader quality gate.
+- **Orchestrator** — For scope changes or requirement adjustments.
+
+---
+
+## RESPONSE RULES
+
+- **Be specific.** "The login button fails 3:1 contrast against the background" is better than "contrast is bad."
+- **Cite standards.** Reference WCAG 2.1 success criteria when applicable (e.g., 1.4.3 Contrast Minimum).
+- **Prioritize by impact.** Blockers are issues that prevent users from completing core tasks.
+- **Suggest remediation.** Give engineers concrete fixes, not just problem statements.
+- **Reference the spec and design.** Audits must verify what the spec and design define.
+- **When done, present navigation options** — Always show the menu with clear next steps.
+
+---
+
+## ANTI-PATTERNS
+
+- ❌ Writing production code to fix an accessibility issue.
+- ❌ Approving UI without inspecting the actual markup and styles.
+- ❌ Reporting vague findings without file paths, WCAG criteria, or remediation steps.
+- ❌ Ignoring keyboard navigation because "most users use a mouse."
+- ❌ Relying solely on automated tools without manual inspection.
+- ❌ Forgetting to check `prefers-reduced-motion` and responsive zoom behavior.
+- ❌ Skipping ARIA review because the component "looks fine."

package/skills/accessibility-auditor/references/a11y-checklist.md

@@ -0,0 +1,66 @@
+# Accessibility Checklist
+
+Reusable checklist for the Accessibility Auditor skill.
+
+---
+
+## Semantic HTML
+
+- [ ] Use native elements (`<button>`, `<a>`, `<input>`, `<label>`, `<select>`, `<textarea>`) before adding ARIA.
+- [ ] Headings (`h1`–`h6`) form a logical outline; do not skip levels for font size.
+- [ ] Landmarks (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`) are used once per role where appropriate.
+- [ ] Lists use `<ul>`, `<ol>`, `<li>`; definition lists use `<dl>`, `<dt>`, `<dd>`.
+- [ ] Tables use `<table>`, `<thead>`, `<tbody>`, `<th scope="...">` when the data is tabular.
+
+## Keyboard & Focus
+
+- [ ] All interactive controls are reachable with `Tab` and operable with `Enter`/`Space`/arrows.
+- [ ] Focus order matches visual order.
+- [ ] Focus indicators are visible and meet 3:1 contrast.
+- [ ] Modals trap focus and restore focus to the triggering element on close.
+- [ ] Drop-down menus close with `Esc` and arrow keys move between items.
+- [ ] No keyboard traps.
+
+## ARIA
+
+- [ ] ARIA is used only when native semantics are insufficient.
+- [ ] Required ARIA attributes are present (`aria-expanded`, `aria-controls`, `aria-labelledby`, etc.).
+- [ ] `aria-live` regions announce status updates and errors.
+- [ ] State changes are reflected in attributes, not just visual classes.
+- [ ] Custom components expose name, role, and value.
+
+## Color & Contrast
+
+- [ ] Normal text ≥ 4.5:1 contrast against background (WCAG 2.1 AA).
+- [ ] Large text (18 pt+ or 14 pt+ bold) ≥ 3:1 contrast.
+- [ ] UI components and graphical objects ≥ 3:1 against adjacent colors.
+- [ ] Information is not conveyed by color alone.
+
+## Forms & Labels
+
+- [ ] Every input has a visible and programmatically associated label.
+- [ ] Required fields are indicated visually and via `aria-required` or `required`.
+- [ ] Error messages are linked with `aria-describedby` or `aria-errormessage`.
+- [ ] Input purpose is identifiable (`autocomplete` attributes where appropriate).
+
+## Images & Media
+
+- [ ] Decorative images use `alt=""`.
+- [ ] Informative images have concise, descriptive `alt` text.
+- [ ] Complex charts/images have a text alternative nearby.
+- [ ] Video/audio has captions, transcripts, and audio descriptions where required.
+
+## Motion & Responsiveness
+
+- [ ] Animations respect `prefers-reduced-motion: reduce`.
+- [ ] Touch targets are at least 44 × 44 CSS pixels.
+- [ ] Layout is usable at 200% browser zoom.
+- [ ] Content does not require horizontal scrolling at 320 CSS pixels width.
+- [ ] Viewport meta tag is present and does not disable zoom.
+
+## Screen Reader Support
+
+- [ ] Reading order is logical when linearized.
+- [ ] Hidden content does not contain focusable elements.
+- [ ] Loading and status changes are announced via live regions.
+- [ ] Icons used alone have accessible names.

package/skills/architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: architect
-description: "Software architecture and design analysis skill. Use this skill whenever the orchestrator has gathered context — this is ALWAYS the first step after orchestrator. Every task, bug fix, feature, design, or refactor must go through architect first to create specs in the specs/ folder. Use for creating specs, architectural planning, system design, API contracts, domain modeling, refactoring strategy, or technical analysis. Trigger on ANY task after orchestrator: 'analyze', 'design', 'architecture', 'plan', 'structure', 'model', 'contract', 'spec', 'refactor plan', 'system design', 'how should I build', 'create specs', 'proceed to architect', or when proceeding from orchestrator with a structured brief. This skill creates the specs folder that designer and engineer follow. Never use for direct implementation or bug fixes — those go to engineer."
+description: "Software architecture and spec-writing skill. ALWAYS use as the first step after orchestrator. Creates specs in specs/ for every change. Trigger after orchestrator briefs or on analyze, design, architecture, plan, spec, refactor plan, system design, create specs, proceed to architect."
 ---
 
 # Architect — Design & Analysis Mode

package/skills/designer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: designer
-description: UI/UX design skill that creates distinctive, production-grade interfaces with bold aesthetic direction. Use this skill whenever the user asks to design, build, create, or improve any frontend interface, page, component, or visual experience. This skill combines bold creative vision (unique typography, unexpected layouts, atmospheric textures, choreographed motion) with essential technical guardrails (accessibility, responsive behavior, touch targets, performance). Trigger on 'design', 'build a page', 'create a landing page', 'make a dashboard', 'improve this UI', 'redesign', 'frontend', 'interface', 'component', or any visual/UI task. When implementation is needed, this skill produces design specs and hands off to the engineer skill for coding.
+description: UI/UX design skill for bold, production-grade interfaces. Use when the user asks to design, build, create, or improve any frontend interface, page, component, or visual experience. Trigger on 'design', 'frontend', 'interface', 'component', 'landing page', 'dashboard', or 'redesign'.
 ---
 
 # Designer — Bold UI/UX Design

package/skills/docs-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-writer
-description: Write or rewrite project documentation tailored to the project type and audience. Use this skill whenever the user asks to create, rewrite, update, or improve a README, module documentation, feature documentation, capability docs, or any project documentation. Trigger on 'write a README', 'rewrite README', 'create documentation', 'document this module', 'document this feature', 'docs for', 'update docs', or when the orchestrator has gathered context and the task is purely documentation with no code changes. This skill is invoked by the orchestrator only — no other skill calls it directly. If documentation requires architectural context that does not exist, route to architect first.
+description: Write or rewrite project documentation tailored to type and audience. Use for READMEs, module/feature/capability docs, or any project docs, and when orchestrator routes pure documentation tasks without code changes. Invoked by orchestrator only; route to architect if context is missing.
 ---
 
 # Docs-Writer — Documentation Authoring

package/skills/engineer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engineer
-description: Software implementation and coding skill. Use this skill whenever the user wants code written, features implemented, bugs fixed, tests written, or any hands-on programming work. Also trigger when the orchestrator skill has gathered context and determined the task is ready for direct implementation, or when the architect skill has completed analysis and the user wants to proceed to BUILD. Use for writing code, creating files, implementing algorithms, building UI components, writing tests, and verification. Trigger on 'build', 'implement', 'code', 'write the code', 'program', 'develop', 'fix this bug', 'create function', 'proceed to build', or when proceeding from architect/orchestrator. Always use this skill for execution — never write implementation code without this skill active. Never use for architectural design or analysis — those go to architect.
+description: Software implementation and coding skill. Trigger on code, features, bug fixes, tests, or hands-on programming; after orchestrator/architect handoff; or on 'build', 'implement', 'code', 'fix this bug'. Only this skill may write implementation code; never for architecture or analysis.
 ---
 
 # Engineer — Build & Implementation Mode

package/skills/maintainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintainer
-description: Use this skill whenever the conversation involves bug triage, technical debt, dependency updates, refactoring, production incidents, or long-term upkeep of a codebase. Trigger even if the user does not say "maintainer" but is asking about flaky tests, outdated libraries, performance degradation, or recurring issues. Competes with engineer on fixes but wins on diagnosis and maintenance strategy.
+description: Use this skill for bug triage, technical debt, dependency updates, refactoring, production incidents, and codebase upkeep. Trigger for flaky tests, outdated libraries, performance degradation, or recurring issues — even if the user does not say "maintainer".
 ---
 
 # Maintainer — Upkeep, Debt & Incident Triage
@@ -25,6 +25,27 @@ You do NOT write production fixes. You do NOT run git operations. You produce cl
 
 ---
 
+## MEMORY & CONTEXT
+
+**Always invoke the `obsidian-second-brain` skill via the `Skill` tool.**
+Never read or write files inside `~/.lea` directly with `Read`, `Edit`, `Write`, or `Bash`.
+
+At the start of the task, the `obsidian-second-brain` skill will search and read the relevant layers for this role.
+At the end of the task, it will persist outcomes to the correct layers.
+
+This skill's targets:
+- **Read at start:** prior incidents, debt decisions, and runbooks
+- **Persist at end:** incident/debt notes to journal; runbooks to knowledge; active context to curated memory
+
+### MCP Tools Reference
+
+| Tool | When to use |
+|------|-------------|
+| `search_notes` | Find prior runbooks and debt decisions in `Knowledge/` and incidents in `Journal/incidents*`. |
+| `learn_from_text` | Persist a root-cause analysis or maintenance decision. |
+
+---
+
 ## WORKFLOW
 
 ### Step 1: Gather Evidence
@@ -72,27 +93,6 @@ Propose a concrete next step:
 
 ---
 
-## MEMORY & CONTEXT
-
-**Always invoke the `obsidian-second-brain` skill via the `Skill` tool.**
-Never read or write files inside `~/.lea` directly with `Read`, `Edit`, `Write`, or `Bash`.
-
-At the start of the task, the `obsidian-second-brain` skill will search and read the relevant layers for this role.
-At the end of the task, it will persist outcomes to the correct layers.
-
-This skill's targets:
-- **Read at start:** prior incidents, debt decisions, and runbooks
-- **Persist at end:** incident/debt notes to journal; runbooks to knowledge; active context to curated memory
-
-### MCP Tools Reference
-
-| Tool | When to use |
-|------|-------------|
-| `search_notes` | Find prior runbooks and debt decisions in `Knowledge/` and incidents in `Journal/incidents*`. |
-| `learn_from_text` | Persist a root-cause analysis or maintenance decision. |
-
----
-
 **What would you like to do?**
 
 - **[O] Return to Orchestrator** — Main task routing