@archznn/crewloop-skills 0.2.0 → 0.3.0

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

package/skills/obsidian-second-brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: obsidian-second-brain
-description: Use this skill whenever the user is working with the loop-engineering-agents bundle and there is a local Obsidian vault at ~/.lea connected via the obsidian-mcp server. Trigger aggressively on tasks involving knowledge retrieval, memory, RAG, second brain, Obsidian, prior decisions in Knowledge/ or Journal/, durable knowledge in Knowledge/, session outcomes in Journal/, user profile facts in Memory/, temporary drafts in Notes/, summaries, dashboards, or anything where persisted context would improve the answer. Even if the user does not explicitly mention the vault, Obsidian, or MCP, use this skill when the answer may depend on previously saved notes, decisions, or concepts. This skill ensures the agent searches the vault, reads relevant notes, learns from new information, persists learnings and decisions automatically, and generates dashboards when asked.
+description: Memory and RAG skill for the loop-engineering-agents bundle. Use when a local Obsidian vault at ~/.lea is connected via obsidian-mcp. Trigger on knowledge retrieval, prior decisions, durable knowledge, session outcomes, user profiles, summaries, dashboards, or any task needing persisted context.
 ---
 
 # Obsidian Second Brain — Layered Memory & RAG
@@ -52,7 +52,7 @@ The vault at `~/.lea` uses a three-layer memory model. Every read and write must
 ~/.lea/
 ├── AGENT.md              # Entry point: read first
 ├── MEMORY.md             # Curated memory: read at task start
-├── memory/               # Working memory: raw session logs
+├── logs/                 # Working logs: raw session logs
 ├── Memory/               # Durable user profile and preferences
 ├── Knowledge/            # Long-lived technical guides and decisions
 ├── Journal/              # Important session logs and dashboards
@@ -60,6 +60,8 @@ The vault at `~/.lea` uses a three-layer memory model. Every read and write must
 └── _Inbox/               # Agent proposals before promotion
 ```
 
+> **Note:** `logs/` (lowercase) holds raw, short-lived session logs. `Memory/` (capital M) holds curated, durable user profile facts and preferences. `logs/` is created automatically when the first log note is written, so it may not exist in a freshly initialized vault.
+
 ### Layer Selection Decision Tree
 
 ```
@@ -97,7 +99,7 @@ User asks...
   │   → confirm path
   │
   ├─ Current conversation log / raw context
-  │   → append to memory/YYYY-MM-DD-HHMM.md
+  │   → append to logs/YYYY-MM-DD-HHMM.md
   │
   ├─ "dashboard/status/summary of project"
   │   → read_note("MEMORY.md")
@@ -115,7 +117,7 @@ User asks...
 |-------|------|------------|----------------|----------|
 | Agent entry | `AGENT.md` | Low | Once per session | Navigation rules for the vault. |
 | Curated memory | `MEMORY.md` | Medium | Every major task | Distilled user/project context, ~500 words. |
-| Working memory | `memory/` | High | Last 1-2 days | Raw session logs (`YYYY-MM-DD-HHMM.md`). |
+| Working logs | `logs/` | High | Last 1-2 days | Raw session logs (`YYYY-MM-DD-HHMM.md`). |
 | User profile | `Memory/` | Low | On demand | User facts, preferences, goals. |
 | Knowledge | `Knowledge/` | Low | On demand | Technical guides, decisions, reusable docs. |
 | Journal | `Journal/` | Medium | On demand | Session outcomes, briefs, dashboards. |
@@ -126,7 +128,7 @@ User asks...
 
 Every 2-4 sessions, or at the end of a significant task:
 
-1. Read recent files in `memory/`.
+1. Read recent files in `logs/`.
 2. Identify durable facts and short-term context.
 3. Update `MEMORY.md` (keep under ~500 words).
 4. Promote `_Inbox/` notes to `Memory/`, `Knowledge/`, `Journal/`, or `Notes/`.
@@ -138,15 +140,22 @@ Every 2-4 sessions, or at the end of a significant task:
 
 | Tool | When to use |
 |------|-------------|
-| `sync_from_bundle` | Once per session, before first search. |
+| `sync_from_bundle` | Re-indexes the skill bundle and local vault; call once per session before the first search. |
 | `read_note` | Read `AGENT.md`, `MEMORY.md`, or a specific note. |
 | `search_notes` | Before answering substantive questions. Prefer `mode: "hybrid"`. |
 | `learn_from_text` | After a new concept or decision emerges. Review target layer. |
 | `create_note` | Create a new note in the correct layer. |
-| `update_note` | Append or replace content. Use `append` for working memory and `MEMORY.md`. |
+| `update_note` | Append or replace content. Use `append` for working logs (`logs/`) and `MEMORY.md`. |
 | `get_related_notes` | Explore links and graph relationships. |
 | `list_notes` | Discover existing note collections or build dashboards. |
 
+### Definitions
+
+- `sync_from_bundle`: re-indexes the skill bundle and the local vault. Call once per session before the first substantive search. Takes no arguments.
+- Search score: a normalized relevance score returned by `search_notes`. Matches above `0.3` are usually worth reading; lower scores are typically noise.
+- Major task: any task involving specs, architecture, implementation, durable knowledge, or multi-step reasoning.
+- Heartbeat: a distillation routine run every 2-4 sessions (or at the end of a significant task) to promote raw logs into `MEMORY.md` and structured layers.
+
 ---
 
 ## RESPONSE RULES
@@ -168,10 +177,11 @@ Every 2-4 sessions, or at the end of a significant task:
 ### Example 1 — retrieve a decision
 User: "What did we decide about the vault path?"
 Agent:
-1. `read_note("MEMORY.md")`
-2. `search_notes("vault path", mode="hybrid")` targeting `Knowledge/`
-3. `read_note("Knowledge/vault-local-path.md")` if it exists.
-4. Answer: "We kept the vault local at `~/.lea` with SQLite for the index. (Source: `Knowledge/vault-local-path.md`)"
+1. `read_note("AGENT.md")`
+2. `read_note("MEMORY.md")`
+3. `search_notes("vault path", mode="hybrid")` targeting `Knowledge/`
+4. `read_note("Knowledge/vault-local-path.md")` if it exists.
+5. Answer: "We kept the vault local at `~/.lea` with SQLite for the index. (Source: `Knowledge/vault-local-path.md`)"
 
 ### Example 2 — persist a concept
 User: "Graph RAG combines vector search with navigation through Obsidian links."
@@ -205,12 +215,35 @@ Agent:
 
 ### Example 5 — heartbeat distillation
 Agent (during heartbeat):
-1. `list_notes("memory/")`
-2. Read last 1-2 `memory/YYYY-MM-DD-HHMM.md` files.
+1. `list_notes("logs/")`
+2. Read last 1-2 `logs/YYYY-MM-DD-HHMM.md` files.
 3. Update `MEMORY.md` with distilled active context.
 4. Process `_Inbox/` notes and promote durable ones.
 5. Answer: "Heartbeat complete. Updated `MEMORY.md` and promoted 2 notes from `_Inbox/`."
 
+### Example 6 — persist a user preference
+User: "I prefer Portuguese for conversation but English for vault notes."
+Agent:
+1. Privacy check (safe).
+2. Decide layer: user profile → `Memory/`.
+3. `create_note("Memory/user-language-preferences.md", content)`.
+4. Answer: "Preference saved to `Memory/user-language-preferences.md`."
+
+### Example 7 — temporary research scratchpad
+User: "Collect articles about vector databases for now."
+Agent:
+1. Privacy check (safe).
+2. Decide layer: temporary → `Notes/`.
+3. `create_note("Notes/vector-database-research.md", content)`.
+4. Answer: "Scratchpad created at `Notes/vector-database-research.md`."
+
+### Example 8 — propose a canonical note
+Agent:
+1. Privacy check (safe).
+2. Decide layer: uncertain → `_Inbox/`.
+3. `create_note("_Inbox/proposed-decision-2026-06-24.md", content)`.
+4. Answer: "Proposal saved to `_Inbox/proposed-decision-2026-06-24.md` for review during the next heartbeat."
+
 ---
 
 ## Dashboard Schema
@@ -259,5 +292,7 @@ Before calling `learn_from_text`, `create_note`, or `update_note`, verify the co
 
 - **[O] Return to Orchestrator** — Main task routing
 - **[A] Return to Architect** — Design or spec questions
+- **[D] Return to Designer** — Visual/UI design direction
 - **[E] Return to Engineer** — Implementation work
 - **[R] Return to Reviewer** — Quality review
+- **[S] Return to Shipper** — Commit, branch, push, PR

package/skills/orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: Context discovery and requirement gathering orchestrator for software development tasks. Use this skill whenever the user asks to build, create, modify, fix, refactor, change, design, or implement anything in a codebase — even if they don't explicitly ask for 'requirements gathering' or 'context'. This skill MUST run FIRST on any task. It collects project context, goals, constraints, UI/UX preferences, animation style, design patterns, and architecture preferences, then produces a structured brief and ALWAYS routes to architect to create specs. There are NO exceptions — every task, bug fix, feature, design, or refactor goes to architect first. The architect then routes to designer (if UI/frontend) or engineer (if backend). Never route directly to designer or engineer from orchestrator. Trigger on 'build', 'create', 'make', 'add', 'fix', 'refactor', 'change', 'implement', 'update', 'modify', 'design', 'redesign', 'landing page', 'dashboard', 'frontend', 'UI', or any task that involves code changes. Also trigger when the user has a vague idea and needs help scoping it.
+description: Context discovery orchestrator for software tasks. Run FIRST for build, create, modify, fix, refactor, design, or implement requests. Gathers context and routes to architect for specs. Trigger: build, create, fix, refactor, design, implement, UI, frontend, dashboard, landing page, or code changes.
 ---
 
 # Orchestrator — Context Discovery & Requirement Gathering

package/skills/product-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-manager
-description: Use this skill whenever the conversation involves prioritization, success metrics, user stories, product decisions, roadmap, feature scope, or measurable outcomes. Trigger even if the user does not say "product manager" but is debating what to build, why to build it, or how to measure success. Competes with orchestrator on requirement discovery but wins on business value framing and prioritization.
+description: Use this skill for prioritization, success metrics, user stories, product decisions, roadmap, scope, or measurable outcomes. Trigger it when the user debates what to build, why to build it, or how to measure success, even without saying 'product manager'.
 ---
 
 # Product Manager — Prioritization & Value Framing
@@ -25,6 +25,27 @@ You do NOT write specs. You do NOT write code. You feed clear, value-oriented in
 
 ---
 
+## 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 product decisions, success metrics, and user feedback
+- **Persist at end:** product decisions and metrics to knowledge or journal; active context to curated memory
+
+### MCP Tools Reference
+
+| Tool | When to use |
+|------|-------------|
+| `search_notes` | Find prior product decisions and success metrics in `Knowledge/` and user feedback in `Journal/`. |
+| `learn_from_text` | Persist a product decision or success metric. |
+
+---
+
 ## WORKFLOW
 
 ### Step 1: Identify the Goal
@@ -68,27 +89,6 @@ Suggest what to build now, later, or not at all. Use frameworks like:
 
 ---
 
-## 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 product decisions, success metrics, and user feedback
-- **Persist at end:** product decisions and metrics to knowledge or journal; active context to curated memory
-
-### MCP Tools Reference
-
-| Tool | When to use |
-|------|-------------|
-| `search_notes` | Find prior product decisions and success metrics in `Knowledge/` and user feedback in `Journal/`. |
-| `learn_from_text` | Persist a product decision or success metric. |
-
----
-
 **What would you like to do?**
 
 - **[O] Return to Orchestrator** — Main task routing