@heytherevibin/skillforge 0.2.1

package/python/app/route_cli.py

@@ -0,0 +1,117 @@
+"""Terminal routing — same pipeline as MCP ``route_skills`` (for scripting and parity checks)."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import time
+from pathlib import Path
+
+from app.db_paths import resolve_orchestrator_db
+from app.main import build_router_and_skills, init_db, run_route_turn
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Route a prompt through Skillforge (stdio: skill bodies + metadata).")
+    p.add_argument(
+        "prompt_parts",
+        nargs="*",
+        help="Prompt text (whitespace-joined). Prefer this or use --prompt.",
+    )
+    p.add_argument("--prompt", "-p", default="", help="Prompt string (alternative to positional words).")
+    p.add_argument(
+        "--project-root",
+        default="",
+        help="Repo root — uses .skillforge/orchestrator.db; else SKILLFORGE_PROJECT_ROOT or global DB.",
+    )
+    p.add_argument("--session-id", default="", help="Stable session id (reuse across turns for reroute stats).")
+    p.add_argument("--user-id", default="", help="Logical user id for weights/sessions/events.")
+    p.add_argument("--json-meta", action="store_true", help="Print routing metadata as JSON on stderr after output.")
+    return p.parse_args(argv)
+
+
+async def _run(args: argparse.Namespace) -> int:
+    text = " ".join(args.prompt_parts).strip() or args.prompt.strip()
+    if not text:
+        print("skillforge route: provide a prompt (positional words or --prompt).", file=sys.stderr)
+        return 2
+
+    pr = (args.project_root or "").strip() or None
+    db_path = resolve_orchestrator_db(pr)
+    con = init_db(db_path)
+
+    router, skills = await asyncio.to_thread(build_router_and_skills, log=True, log_prefix="[skillforge-route]")
+    session_id = args.session_id.strip() or None
+    user_id = args.user_id.strip()
+
+    try:
+        result = await run_route_turn(
+            con,
+            router,
+            text,
+            conversation=[],
+            user_id=user_id,
+            session_id=session_id,
+        )
+    finally:
+        con.close()
+
+    picked_names = result["picked_names"]
+    reasoning = result["reasoning"]
+    sid = result["session_id"]
+
+    if pr:
+        try:
+            d = Path(pr).expanduser().resolve() / ".skillforge"
+            d.mkdir(parents=True, exist_ok=True)
+            snap = {
+                "ts": time.time(),
+                "session_id": sid,
+                "picked": picked_names,
+                "reasoning": reasoning,
+                "route_ms": round(result["route_ms"], 1),
+                "user_id": user_id,
+                "source": "cli_route",
+            }
+            (d / "last_route.json").write_text(json.dumps(snap, indent=2), encoding="utf-8")
+        except OSError:
+            pass
+
+    blocks = [
+        f"# Skillforge — routed {len(picked_names)} skill(s)",
+        f"_DB:_ `{db_path}`",
+        f"_Reasoning: {reasoning}_" if reasoning else "",
+        "",
+    ]
+    for n in picked_names:
+        s = skills.get(n)
+        if s:
+            blocks.append(f"---\n## Skill: {s.name}\n\n{s.body}\n")
+    if not picked_names:
+        blocks.append("_No skills matched this prompt closely enough to load._")
+    print("\n".join(b for b in blocks if b is not None))
+
+    if args.json_meta:
+        meta = {
+            "picked": picked_names,
+            "reasoning": reasoning,
+            "session_id": sid,
+            "user_id": user_id,
+            "rerouted": result["rerouted"],
+            "change_pct": round(result["change"] * 100, 1),
+            "route_ms": round(result["route_ms"], 1),
+            "orchestrator_db": str(db_path),
+        }
+        print(json.dumps(meta, indent=2), file=sys.stderr)
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parse_args(argv)
+    raise SystemExit(asyncio.run(_run(args)))
+
+
+if __name__ == "__main__":
+    main()

package/python/requirements-dev.txt

@@ -0,0 +1 @@
+pytest>=8,<9

package/python/requirements.txt

@@ -0,0 +1,7 @@
+fastapi>=0.110
+uvicorn[standard]>=0.27
+anthropic>=0.39
+sentence-transformers>=2.7
+numpy>=1.26
+pydantic>=2.6
+httpx>=0.27

package/python/tests/test_db_paths.py

@@ -0,0 +1,41 @@
+"""Lightweight tests (stdlib + app.db_paths only)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from app.db_paths import global_db_path, resolve_orchestrator_db
+
+
+def test_resolve_orchestrator_db_empty_uses_global(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    global_db = tmp_path / "global.db"
+    monkeypatch.delenv("SKILLFORGE_PROJECT_ROOT", raising=False)
+    monkeypatch.setenv("SKILLFORGE_DB_PATH", str(global_db))
+    assert resolve_orchestrator_db("") == global_db
+    assert resolve_orchestrator_db(None) == global_db
+    assert resolve_orchestrator_db("  ") == global_db
+
+
+def test_resolve_orchestrator_db_project_root(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.delenv("SKILLFORGE_PROJECT_ROOT", raising=False)
+    monkeypatch.setenv("SKILLFORGE_DB_PATH", str(tmp_path / "ignored.db"))
+    proj = tmp_path / "myrepo"
+    proj.mkdir()
+    expected = proj / ".skillforge" / "orchestrator.db"
+    assert resolve_orchestrator_db(str(proj)) == expected
+
+
+def test_resolve_orchestrator_db_env_fallback(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("SKILLFORGE_DB_PATH", str(tmp_path / "global.db"))
+    proj = tmp_path / "w"
+    proj.mkdir()
+    monkeypatch.setenv("SKILLFORGE_PROJECT_ROOT", str(proj))
+    assert resolve_orchestrator_db("") == proj / ".skillforge" / "orchestrator.db"
+
+
+def test_global_db_path_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    p = tmp_path / "x.db"
+    monkeypatch.setenv("SKILLFORGE_DB_PATH", str(p))
+    assert global_db_path() == p

package/skills/accessibility/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: accessibility
+description: Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA
+  standards. Use this skill to generate semantic ARIA for Web and accessibility traits for Web and Native platforms (iOS/Android).
+---
+
+# Accessibility (WCAG 2.2)
+
+This skill ensures that digital interfaces are Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those using screen readers, switch controls, or keyboard navigation. It focuses on the technical implementation of WCAG 2.2 success criteria.
+
+## When to Use
+
+- Defining UI component specifications for Web, iOS, or Android.
+- Auditing existing code for accessibility barriers or compliance gaps.
+- Implementing new WCAG 2.2 standards like Target Size (Minimum) and Focus Appearance.
+- Mapping high-level design requirements to technical attributes (ARIA roles, traits, hints).
+
+## Core Concepts
+
+- **POUR Principles**: The foundation of WCAG (Perceivable, Operable, Understandable, Robust).
+- **Semantic Mapping**: Using native elements over generic containers to provide built-in accessibility.
+- **Accessibility Tree**: The representation of the UI that assistive technologies actually "read."
+- **Focus Management**: Controlling the order and visibility of the keyboard/screen reader cursor.
+- **Labeling & Hints**: Providing context through `aria-label`, `accessibilityLabel`, and `contentDescription`.
+
+## How It Works
+
+### Step 1: Identify the Component Role
+
+Determine the functional purpose (e.g., Is this a button, a link, or a tab?). Use the most semantic native element available before resorting to custom roles.
+
+### Step 2: Define Perceivable Attributes
+
+- Ensure text contrast meets **4.5:1** (normal) or **3:1** (large/UI).
+- Add text alternatives for non-text content (images, icons).
+- Implement responsive reflow (up to 400% zoom without loss of function).
+
+### Step 3: Implement Operable Controls
+
+- Ensure a minimum **24x24 CSS pixel** target size (WCAG 2.2 SC 2.5.8).
+- Verify all interactive elements are reachable via keyboard and have a visible focus indicator (SC 2.4.11).
+- Provide single-pointer alternatives for dragging movements.
+
+### Step 4: Ensure Understandable Logic
+
+- Use consistent navigation patterns.
+- Provide descriptive error messages and suggestions for correction (SC 3.3.3).
+- Implement "Redundant Entry" (SC 3.3.7) to prevent asking for the same data twice.
+
+### Step 5: Verify Robust Compatibility
+
+- Use correct `Name, Role, Value` patterns.
+- Implement `aria-live` or live regions for dynamic status updates.
+
+## Accessibility Architecture Diagram
+
+```mermaid
+flowchart TD
+  UI["UI Component"] --> Platform{Platform?}
+  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
+  Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
+  Platform -->|Android| Compose["Semantics + ContentDesc"]
+
+  ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
+  SwiftUI --> AT
+  Compose --> AT
+```
+
+## Cross-Platform Mapping
+
+| Feature            | Web (HTML/ARIA)          | iOS (SwiftUI)                        | Android (Compose)                                           |
+| :----------------- | :----------------------- | :----------------------------------- | :---------------------------------------------------------- |
+| **Primary Label**  | `aria-label` / `<label>` | `.accessibilityLabel()`              | `contentDescription`                                        |
+| **Secondary Hint** | `aria-describedby`       | `.accessibilityHint()`               | `Modifier.semantics { stateDescription = ... }`             |
+| **Action Role**    | `role="button"`          | `.accessibilityAddTraits(.isButton)` | `Modifier.semantics { role = Role.Button }`                 |
+| **Live Updates**   | `aria-live="polite"`     | `.accessibilityLiveRegion(.polite)`  | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
+
+## Examples
+
+### Web: Accessible Search
+
+```html
+<form role="search">
+  <label for="search-input" class="sr-only">Search products</label>
+  <input type="search" id="search-input" placeholder="Search..." />
+  <button type="submit" aria-label="Submit Search">
+    <svg aria-hidden="true">...</svg>
+  </button>
+</form>
+```
+
+### iOS: Accessible Action Button
+
+```swift
+Button(action: deleteItem) {
+    Image(systemName: "trash")
+}
+.accessibilityLabel("Delete item")
+.accessibilityHint("Permanently removes this item from your list")
+.accessibilityAddTraits(.isButton)
+```
+
+### Android: Accessible Toggle
+
+```kotlin
+Switch(
+    checked = isEnabled,
+    onCheckedChange = { onToggle() },
+    modifier = Modifier.semantics {
+        contentDescription = "Enable notifications"
+    }
+)
+```
+
+## Anti-Patterns to Avoid
+
+- **Div-Buttons**: Using a `<div>` or `<span>` for a click event without adding a role and keyboard support.
+- **Color-Only Meaning**: Indicating an error or status _only_ with a color change (e.g., turning a border red).
+- **Uncontained Modal Focus**: Modals that don't trap focus, allowing keyboard users to navigate background content while the modal is open. Focus must be contained _and_ escapable via the `Escape` key or an explicit close button (WCAG SC 2.1.2).
+- **Redundant Alt Text**: Using "Image of..." or "Picture of..." in alt text (screen readers already announce the role "Image").
+
+## Best Practices Checklist
+
+- [ ] Interactive elements meet the **24x24px** (Web) or **44x44pt** (Native) target size.
+- [ ] Focus indicators are clearly visible and high-contrast.
+- [ ] Modals **contain focus** while open, and release it cleanly on close (`Escape` key or close button).
+- [ ] Dropdowns and menus restore focus to the trigger element on close.
+- [ ] Forms provide text-based error suggestions.
+- [ ] All icon-only buttons have a descriptive text label.
+- [ ] Content reflows properly when text is scaled.
+
+## References
+
+- [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/)
+- [iOS Accessibility Programming Guide](https://developer.apple.com/documentation/accessibility)
+- [iOS Human Interface Guidelines - Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+- [Android Accessibility Developer Guide](https://developer.android.com/guide/topics/ui/accessibility)
+
+## Related Skills
+
+- `frontend-patterns`
+- `design-system`
+- `liquid-glass-design`
+- `swiftui-patterns`

package/skills/agent-architecture-audit/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: agent-architecture-audit
+description: Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature.
+origin: oh-my-agent-check
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Agent Architecture Audit
+
+A diagnostic workflow for agent systems that hide failures behind wrapper layers, stale memory, retry loops, or transport/rendering mutations.
+
+## When to Activate
+
+**MANDATORY for:**
+- Releasing any agent or LLM-powered application to production
+- Shipping features with tool calling, memory, or multi-step workflows
+- Agent behavior degrades after adding wrapper layers
+- User reports "the agent is getting worse" or "tools are flaky"
+- Same model works in playground but breaks inside your wrapper
+- Debugging agent behavior for more than 15 minutes without finding root cause
+
+**Especially critical when:**
+- You've added new prompt layers, tool definitions, or memory systems
+- Different agents in your system behave inconsistently
+- The model was fine yesterday but is hallucinating today
+- You suspect hidden repair/retry loops silently mutating responses
+
+**Do not use for:**
+- General code debugging — use `agent-introspection-debugging`
+- Code review — use language-specific reviewer agents
+- Security scanning — use `security-review` or `security-review/scan`
+- Agent performance benchmarking — use `agent-eval`
+- Writing new features — use the appropriate workflow skill
+
+## The 12-Layer Stack
+
+Every agent system has these layers. Any of them can corrupt the answer:
+
+| # | Layer | What Goes Wrong |
+|---|-------|----------------|
+| 1 | System prompt | Conflicting instructions, instruction bloat |
+| 2 | Session history | Stale context injection from previous turns |
+| 3 | Long-term memory | Pollution across sessions, old topics in new conversations |
+| 4 | Distillation | Compressed artifacts re-entering as pseudo-facts |
+| 5 | Active recall | Redundant re-summary layers wasting context |
+| 6 | Tool selection | Wrong tool routing, model skips required tools |
+| 7 | Tool execution | Hallucinated execution — claims to call but doesn't |
+| 8 | Tool interpretation | Misread or ignored tool output |
+| 9 | Answer shaping | Format corruption in final response |
+| 10 | Platform rendering | Transport-layer mutation (UI, API, CLI mutates valid answers) |
+| 11 | Hidden repair loops | Silent fallback/retry agents running second LLM pass |
+| 12 | Persistence | Expired state or cached artifacts reused as live evidence |
+
+## Common Failure Patterns
+
+### 1. Wrapper Regression
+
+The base model produces correct answers, but the wrapper layers make it worse.
+
+**Symptoms:**
+- Model works fine in playground or direct API call, breaks in your agent
+- Added a new prompt layer, existing behavior degraded
+- Agent sounds confident but is confidently wrong
+- "It was working before the last update"
+
+### 2. Memory Contamination
+
+Old topics leak into new conversations through history, memory retrieval, or distillation.
+
+**Symptoms:**
+- Agent brings up unrelated past topics
+- User corrections don't stick (old memory overwrites new)
+- Same-session artifacts re-enter as pseudo-facts
+- Memory grows without bound, degrading response quality over time
+
+### 3. Tool Discipline Failure
+
+Tools are declared in the prompt but not enforced in code. The model skips them or hallucinates execution.
+
+**Symptoms:**
+- "Must use tool X" in prompt, but model answers without calling it
+- Tool results look correct but were never actually executed
+- Different tools fight over the same responsibility
+- Model uses tool when it shouldn't, or skips it when it must
+
+### 4. Rendering/Transport Corruption
+
+The agent's internal answer is correct, but the platform layer mutates it during delivery.
+
+**Symptoms:**
+- Logs show correct answer, user sees broken output
+- Markdown rendering, JSON parsing, or streaming fragments corrupt valid responses
+- Hidden fallback agent quietly replaces the answer before delivery
+- Output differs between terminal and UI
+
+### 5. Hidden Agent Layers
+
+Silent repair, retry, summarization, or recall agents run without explicit contracts.
+
+**Symptoms:**
+- Output changes between internal generation and user delivery
+- "Auto-fix" loops run a second LLM pass the user doesn't know about
+- Multiple agents modify the same output without coordination
+- Answers get "smoothed" or "corrected" by invisible layers
+
+## Audit Workflow
+
+### Phase 1: Scope
+
+Define what you're auditing:
+
+- **Target system** — what agent application?
+- **Entrypoints** — how do users interact with it?
+- **Model stack** — which LLM(s) and providers?
+- **Symptoms** — what does the user report?
+- **Time window** — when did it start?
+- **Layers to audit** — which of the 12 layers apply?
+
+### Phase 2: Evidence Collection
+
+Gather evidence from the codebase:
+
+- **Source code** — agent loop, tool router, memory admission, prompt assembly
+- **Logs** — historical session traces, tool call records
+- **Config** — prompt templates, tool schemas, provider settings
+- **Memory files** — SOPs, knowledge bases, session archives
+
+Use `rg` to search for anti-patterns:
+
+```bash
+# Tool requirements expressed only in prompt text (not code)
+rg "must.*tool|必须.*工具|required.*call" --type md
+
+# Tool execution without validation
+rg "tool_call|toolCall|tool_use" --type py --type ts
+
+# Hidden LLM calls outside main agent loop
+rg "completion|chat\.create|messages\.create|llm\.invoke"
+
+# Memory admission without user-correction priority
+rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts
+
+# Fallback loops that run additional LLM calls
+rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts
+
+# Silent output mutation
+rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts
+```
+
+### Phase 3: Failure Mapping
+
+For each finding, document:
+
+- **Symptom** — what the user sees
+- **Mechanism** — how the wrapper causes it
+- **Source layer** — which of the 12 layers
+- **Root cause** — the deepest cause
+- **Evidence** — file:line or log:row reference
+- **Confidence** — 0.0 to 1.0
+
+### Phase 4: Fix Strategy
+
+Default fix order (code-first, not prompt-first):
+
+1. **Code-gate tool requirements** — enforce in code, not just prompt text
+2. **Remove or narrow hidden repair agents** — make fallback explicit with contracts
+3. **Reduce context duplication** — same info through prompt + history + memory + distillation
+4. **Tighten memory admission** — user corrections > agent assertions
+5. **Tighten distillation triggers** — don't compress what shouldn't be compressed
+6. **Reduce rendering mutation** — pass-through, don't transform
+7. **Convert to typed JSON envelopes** — structured internal flow, not freeform prose
+
+## Severity Model
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| `critical` | Agent can confidently produce wrong operational behavior | Fix before next release |
+| `high` | Agent frequently degrades correctness or stability | Fix this sprint |
+| `medium` | Correctness usually survives but output is fragile or wasteful | Plan for next cycle |
+| `low` | Mostly cosmetic or maintainability issues | Backlog |
+
+## Output Format
+
+Present findings to the user in this order:
+
+1. **Severity-ranked findings** (most critical first)
+2. **Architecture diagnosis** (which layer corrupted what, and why)
+3. **Ordered fix plan** (code-first, not prompt-first)
+
+Do not lead with compliments or summaries. If the system is broken, say so directly.
+
+## Quick Diagnostic Questions
+
+When auditing an agent system, answer these:
+
+| # | Question | If Yes → |
+|---|----------|----------|
+| 1 | Can the model skip a required tool and still answer? | Tool not code-gated |
+| 2 | Does old conversation content appear in new turns? | Memory contamination |
+| 3 | Is the same info in system prompt AND memory AND history? | Context duplication |
+| 4 | Does the platform run a second LLM pass before delivery? | Hidden repair loop |
+| 5 | Does the output differ between internal generation and user delivery? | Rendering corruption |
+| 6 | Are "must use tool X" rules only in prompt text? | Tool discipline failure |
+| 7 | Can the agent's own monologue become persistent memory? | Memory poisoning |
+
+## Anti-Patterns to Avoid
+
+- Avoid blaming the model before falsifying wrapper-layer regressions.
+- Avoid blaming memory without showing the contamination path.
+- Do not let a clean current state erase a dirty historical incident.
+- Do not treat markdown prose as a trustworthy internal protocol.
+- Do not accept "must use tool" in prompt text when code never enforces it.
+- Keep findings direct, evidence-backed, and severity-ranked.
+
+## Report Schema
+
+Audits should produce structured reports following this shape:
+
+```json
+{
+  "schema_version": "skillforge.agent-architecture-audit.report.v1",
+  "executive_verdict": {
+    "overall_health": "high_risk",
+    "primary_failure_mode": "string",
+    "most_urgent_fix": "string"
+  },
+  "scope": {
+    "target_name": "string",
+    "model_stack": ["string"],
+    "layers_to_audit": ["string"]
+  },
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "title": "string",
+      "mechanism": "string",
+      "source_layer": "string",
+      "root_cause": "string",
+      "evidence_refs": ["file:line"],
+      "confidence": 0.0,
+      "recommended_fix": "string"
+    }
+  ],
+  "ordered_fix_plan": [
+    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
+  ]
+}
+```
+
+## Related Skills
+
+- `agent-introspection-debugging` — Debug agent runtime failures (loops, timeouts, state errors)
+- `agent-eval` — Benchmark agent performance head-to-head
+- `security-review` — Security audit for code and configuration
+- `autonomous-agent-harness` — Set up autonomous agent operations
+- `agent-harness-construction` — Build agent harnesses from scratch