skill-brain 2.1.0__py3-none-any.whl

skill_brain/__init__.py

@@ -0,0 +1,3 @@
+"""skill-brain -- Multi-agent engineering skill system."""
+
+__version__ = "2.1.0"

skill_brain/cli.py

@@ -0,0 +1,185 @@
+"""Entry point: skill-brain CLI -- dispatches to subcommands."""
+
+import argparse
+import sys
+
+from skill_brain import __version__
+from skill_brain import installer, doctor as doctor_mod, indexer
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="skill-brain",
+        description="Multi-agent engineering skill system CLI",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"skill-brain {__version__}"
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    # --- init ---
+    p_init = sub.add_parser("init", help="Install skill-brain into current project")
+    p_init.add_argument(
+        "--agents",
+        default="all",
+        help="Comma-separated agents: all|claude,codex,antigravity,gemini,cursor",
+    )
+    p_init.add_argument(
+        "--legacy-agent-dir",
+        action="store_true",
+        help="Also write .agent/skills/ (legacy single-agent dir)",
+    )
+
+    # --- update ---
+    sub.add_parser("update", help="Update skill files (preserves user edits)")
+
+    # --- add ---
+    p_add = sub.add_parser("add", help="Add a local skill to .agents/skills/")
+    p_add.add_argument("path", help="Path to skill directory")
+
+    # --- list ---
+    sub.add_parser("list", help="List all installed skills")
+
+    # --- show ---
+    p_show = sub.add_parser("show", help="Show a skill's SKILL.md")
+    p_show.add_argument("name", help="Skill name")
+
+    # --- search ---
+    p_search = sub.add_parser("search", help="Search skills by keyword")
+    p_search.add_argument("query", help="Search query")
+
+    # --- doctor ---
+    sub.add_parser("doctor", help="Validate skill directory health")
+
+    # --- uninstall ---
+    sub.add_parser("uninstall", help="Remove files installed by skill-brain")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "init":
+        agents_arg = args.agents
+        if agents_arg == "all":
+            agents = ["claude", "codex", "antigravity", "gemini", "cursor"]
+        else:
+            agents = [a.strip() for a in agents_arg.split(",")]
+        installer.init(agents=agents, legacy_agent_dir=args.legacy_agent_dir)
+
+    elif args.command == "update":
+        installer.update()
+
+    elif args.command == "add":
+        installer.add_skill(args.path)
+
+    elif args.command == "list":
+        _cmd_list()
+
+    elif args.command == "show":
+        _cmd_show(args.name)
+
+    elif args.command == "search":
+        _cmd_search(args.query)
+
+    elif args.command == "doctor":
+        errors = doctor_mod.run()
+        sys.exit(1 if errors else 0)
+
+    elif args.command == "uninstall":
+        installer.uninstall()
+
+
+# ---------------------------------------------------------------------------
+# list / show / search -- thin wrappers that read index.json
+# ---------------------------------------------------------------------------
+
+def _cmd_list() -> None:
+    import json
+    from pathlib import Path
+
+    index_path = Path.cwd() / ".agents" / "brain" / "index.json"
+    if not index_path.exists():
+        print("ERROR: .agents/brain/index.json not found. Run `skill-brain init` first.")
+        sys.exit(1)
+
+    index = json.loads(index_path.read_text(encoding="utf-8"))
+    by_cat: dict[str, list] = {}
+    for skill in index.values():
+        cat = skill.get("category", "uncategorized")
+        by_cat.setdefault(cat, []).append(skill)
+
+    total = 0
+    for cat in sorted(by_cat):
+        skills = sorted(by_cat[cat], key=lambda s: s["name"])
+        print(f"\n  [{cat.upper()}]")
+        for s in skills:
+            aliases = ", ".join(s.get("aliases", [])[:2])
+            print(f"    {s['name']:<32}  {aliases}")
+            total += 1
+    print(f"\n  Total: {total} skills")
+
+
+def _cmd_show(name: str) -> None:
+    import json
+    from pathlib import Path
+
+    index_path = Path.cwd() / ".agents" / "brain" / "index.json"
+    if not index_path.exists():
+        print("ERROR: .agents/brain/index.json not found. Run `skill-brain init` first.")
+        sys.exit(1)
+
+    index = json.loads(index_path.read_text(encoding="utf-8"))
+    skill = index.get(name)
+    if not skill:
+        print(f"ERROR: Skill '{name}' not found.")
+        sys.exit(1)
+
+    skill_path = Path.cwd() / skill["path"]
+    if not skill_path.exists():
+        print(f"ERROR: SKILL.md not found at {skill_path}")
+        sys.exit(1)
+
+    print(skill_path.read_text(encoding="utf-8"))
+
+
+def _cmd_search(query: str) -> None:
+    import json
+    from pathlib import Path
+
+    index_path = Path.cwd() / ".agents" / "brain" / "index.json"
+    if not index_path.exists():
+        print("ERROR: .agents/brain/index.json not found. Run `skill-brain init` first.")
+        sys.exit(1)
+
+    index = json.loads(index_path.read_text(encoding="utf-8"))
+    terms = query.lower().split()
+
+    scored: list[tuple[int, dict]] = []
+    for skill in index.values():
+        score = 0
+        name_l = skill["name"].lower()
+        desc_l = skill.get("description", "").lower()
+        aliases_l = " ".join(skill.get("aliases", [])).lower()
+        for term in terms:
+            if term in name_l:
+                score += 4
+            if term in aliases_l:
+                score += 2
+            if term in desc_l:
+                score += 1
+        if score > 0:
+            scored.append((score, skill))
+
+    scored.sort(key=lambda x: -x[0])
+    if not scored:
+        print("No skills matched your query.")
+        return
+
+    print(f"\n  Results for '{query}':\n")
+    for score, skill in scored:
+        print(f"  {skill['name']:<32}  (score: {score})")
+        print(f"    {skill.get('description', '')[:100]}...")
+        print()

skill_brain/data/brain/config.json

@@ -0,0 +1,3 @@
+{
+  "confirm": "always"
+}

skill_brain/data/brain/decisions/anti-ai-sop.md

@@ -0,0 +1,22 @@
+# Anti-AI SOP Skills — Decision Making Matrix
+
+This document dictates how the agent monitors, purges, and audits AI tells across prose, visual design, vectors, and code.
+
+---
+
+## 1. Zero Tolerance Mandate
+
+Before ANY response, code snippet, SVG, or UI is returned to the user, run the anti-slop check.
+If an output contains synthetic tells, rewrite it before sending.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| Content Being Produced | Selected Skills | Enforced Restrictions |
+|---|---|---|
+| **Plan an Anti-AI audit before fixing** | `anti-slop-planner` (`$plan-anti-slop`) | Catalogs all AI tells across 6 dimensions with file:line citations; drafts surgical remediation plan. |
+| **Formal quality gate audit of repo/PR** | `agents/anti-ai-sop-agent` (`$anti-slop`) | Produces formal 6-category scorecard (PASS / WARN / FAIL) with concrete citations and optional `--fix` mode. |
+| **Text, explanations, answers, PRs** | `text-tone-enforcer` + `anti-slop-enforcer` | No sycophantic openers, no filler transitions ("Furthermore"), no bullet-point abuse; direct senior engineer cadence. |
+| **Frontend UI (CSS, Tailwind, JSX, HTML)** | `ui-tells-eliminator` + `anti-slop-enforcer` | No cream/terracotta Anthropic clone, no pill badges above headlines, no tracked uppercase eyebrows, no 3-card centered icon grids. |
+| **SVG Icons and Vector Graphics** | `svg-icon-craftsman` (`$icon`) | No wandering bezier curves, standard 24×24 viewBox, uniform 1.5px/2.0px stroke, integral pixel snapping. |

skill_brain/data/brain/decisions/architecture.md

@@ -0,0 +1,35 @@
+# Architecture Skills — Decision Making Matrix
+
+This document dictates how the agent handles system design, workspace isolation, sub-agent dispatch, and large project planning.
+
+---
+
+## 1. Mandatory Baseline
+
+Before structural or multi-module changes:
+- Evaluate workspace isolation: if a feature branch or worktree is appropriate, activate `git-isolator`.
+- Keep the main branch clean and unpolluted with in-progress experiments.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| Architectural Goal | Selected Skills | Why This Combination |
+|---|---|---|
+| **Isolate workspace for feature work** | `git-isolator` | Creates native worktree (`git worktree add -b feature/...`), verifies isolation, keeps main tree clean. |
+| **Dispatch parallel task execution** | `subagent-executor` | Dispatches fresh sub-agents with isolated prompts per task; reviews each task output before merging. |
+| **Map huge project spanning sessions** | `large-task-mapper` | Deconstructs big goals into decision tickets (blocking forks in the road) before implementation tickets. |
+| **Research API / library from sources** | `research-agent` | Restricts investigation strictly to primary sources (official docs, repo source); cites URLs and file lines. |
+| **Human credential / dashboard setup** | `setup-wizard` | Generates idempotent, color-coded interactive bash wizard for human-only secrets, dashboards, or DNS steps. |
+| **Author or optimize an agent skill** | `skill-creator` | Benchmarks trigger descriptions, runs eval matrices, refines procedural instructions. |
+
+---
+
+## 3. Sub-Agent vs. Single Pass Decision
+
+- **Use `subagent-executor` when:**
+  - Tasks are embarrassingly parallel (e.g. 5 independent UI components or 4 separate API endpoints).
+  - Context window would be overwhelmed by reviewing all implementations at once.
+- **Use single pass when:**
+  - Tasks are tightly coupled sequentially (e.g. database schema change followed immediately by dependent query update).
+

skill_brain/data/brain/decisions/backend.md

@@ -0,0 +1,27 @@
+# Backend Skills — Decision Making Matrix
+
+This document dictates how the agent selects, combines, and sequences backend skills.
+
+---
+
+## 1. Mandatory Baseline (Always Active in Backend)
+
+Every backend implementation task **must** honor:
+1. `karpathy-coder` (minimal blast radius, zero speculative code, no unrequested abstractions).
+2. `tdd-implementer` (write test first, watch it fail, write minimal code to pass).
+3. `responsive-contract-enforcer` (all endpoints serving UI must declare responsive aspect ratios, multi-res srcsets, and zero fixed pixel widths).
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| User Goal | Selected Skills | Why This Combination |
+|---|---|---|
+| **Plan backend architecture before coding** | `backend-planner` (`$plan-backend`) | Defines domain models, responsive API contracts, tracer-bullet ticket graph, and TDD plan. |
+| **Surgical bugfix or minimal tweak** | `karpathy-coder` + `tdd-implementer` | Touches only failing lines, adds a targeted regression test, leaves surrounding code pristine. |
+| **Build new feature from spec** | `spec-implementer` | Follows ticket dependency graph in strict order, committing after each ticket. |
+| **Design deep module / API boundary** | `codebase-designer` + `domain-modeler` | Maximizes information hiding (Ousterhout deep modules) and aligns naming to GLOSSARY.md. |
+| **Enforce responsive UI API contract** | `responsive-contract-enforcer` | Validates that payloads contain responsive layout hints, aspect ratios, and zero hardcoded pixel widths. |
+| **Modern Swift 6 / Apple backend** | `swift-writer` | Strict concurrency (@MainActor, actors, Sendable), value-type modeling, Swift Testing. |
+| **Build MCP tool server** | `mcp-builder` | FastMCP or TypeScript MCP SDK; clean tool schemas, error handling, deterministic outputs. |
+| **Write pull request description** | `pr-writer` | Generates summary, testing steps, before/after evidence, and reviewer checklist. |

skill_brain/data/brain/decisions/debugging.md

@@ -0,0 +1,45 @@
+# Debugging Skills — Decision Making Matrix
+
+This document dictates how the agent handles bugs, test failures, crashes, and regressions.
+
+---
+
+## 1. The Debugging Iron Law (Planning First)
+
+**When the user says "debug", NEVER edit code immediately.**
+1. Formulate a systematic diagnostic plan using debugging skills.
+2. State the observed symptom, reproduction steps, and candidate hypotheses.
+3. Ask the user for confirmation: *"Here is my diagnostic plan. Shall I proceed with isolating the root cause?"*
+4. Only after finding the root cause with verifiable evidence may a fix be designed.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| Problem Type | Selected Skills | Why This Combination |
+|---|---|---|
+| **Exception, crash, or clear error** | `root-cause-debugger` | Enforces the 5-step protocol: state symptom, gather evidence, form ONE falsifiable hypothesis, test hypothesis, isolate cause. |
+| **Intermittent bug / "works on my machine"** | `bug-diagnoser` | Systematically bisects problem space, instruments minimal logging, and isolates minimal reproduction. |
+| **Performance regression / slow API** | `bug-diagnoser` (perf mode) | Measures CPU/memory bottlenecks, queries profilers, identifies O(n²) or N+1 query patterns. |
+| **Validating a fix or claiming "done"** | `test-verifier` | Evidence before claims: runs actual test/lint commands and pastes raw terminal output before declaring success. |
+| **Reviewing branch / PR for flaws** | `code-reviewer` | Runs parallel reviews: Standards compliance (clean code) vs. Spec compliance (did we build what was asked?). |
+| **Triaging bug reports from users** | `issue-triager` | Moves issues through triage state machine (RAW → VERIFYING → CATEGORIZED → READY) and produces agent-ready briefs. |
+
+---
+
+## 3. Diagnostic Plan Template
+
+Before touching code, present this plan to the user:
+
+```markdown
+### 🔍 Diagnostic Plan
+1. **Symptom:** [Exact error message or unexpected behavior observed]
+2. **Reproduction:** [Exact command or steps to reproduce]
+3. **Hypothesis:** [What mechanism is suspected of causing this]
+4. **Investigation Steps:**
+   - [ ] Inspect stack trace / logs at [file:line]
+   - [ ] Run isolated regression test
+   - [ ] Verify root cause before proposing edits
+5. **Next Step:** Confirm to begin investigation.
+```
+

skill_brain/data/brain/decisions/frontend.md

@@ -0,0 +1,38 @@
+# Frontend Skills — Decision Making Matrix
+
+This document dictates how the agent selects, combines, and sequences frontend skills.
+
+---
+
+## 1. Mandatory Baseline Bundle (`frontend-baseline`)
+
+Every frontend task **must** load `frontend-baseline` (≤ 4 KB), which condenses:
+1. **Art Direction:** `design-taste-frontend` + `ui-taste-enforcer` (Taste Kill v2, 247-site study, subject palette).
+2. **Anti-AI SOP:** `ui-tells-eliminator` + `anti-slop-enforcer` (kills pill badges, eyebrows, 3-card grids).
+3. **Dynamic Responsive Sizing:** `phone-layout-master` + `desktop-ui-architect` + `dynamic-ui-engine` (flawless adaptation from 320px phone to 2560px desktop).
+
+Full skills can be loaded on demand from references when deeper guidance is required.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| User Goal | Selected Skills | Why This Combination |
+|---|---|---|
+| **Plan UI architecture before building** | `frontend-planner` (`$plan-frontend`) | Creates complete blueprint: subject inventory, fluid tokens, phone layout, desktop layout, anti-slop check. |
+| **Build new component or page** | `design-taste-frontend` + `dynamic-ui-engine` + `typography-master` | Directs composition, token ratios, fluid clamp scales, and tailored typography. |
+| **Phone / Mobile layout perfection** | `phone-layout-master` + `mobile-native-feel` | 320px–480px optimization: 100svh, 44px touch targets, bottom sheets, safe-area insets. |
+| **Desktop / Wide-screen UI workstation** | `desktop-ui-architect` + `design-engineering` | 768px–2560px optimization: multi-pane hierarchy, container queries (`@container`), max-width bounds. |
+| **Typography & font archetype selection**| `typography-master` (`$typography`) | Selects Swiss, Editorial, Mono, or Humanist font stacks; establishes mathematical clamp scales. |
+| **Craft SVG icons or glyphs** | `svg-icon-craftsman` (`$icon`) | Snaps vector paths to 24×24 grid, 1.5px/2.0px stroke, eliminates AI curve spaghetti. |
+| **Add micro-interactions & polish** | `design-engineering` + `animation-builder` | Emil Kowalski polish standard: 9 interactive states, physical spring curves. |
+| **Fix dropped frames or janky UI** | `animation-performance` | Keeps animations on composite-only GPU properties (transform, opacity); 16.6ms frame budget. |
+| **Stress-test layout breaks** | `ui-stress-tester` | Feeds extreme strings, non-Latin text, negative numbers, empty arrays behind a demo toggle. |
+| **Compare multiple UI directions** | `ui-prototyper` | Generates 3 genuinely different compositions behind a live switcher. |
+
+---
+
+## 3. The Baseline Bundle + 3 Task Skills Rule
+
+- Rule 7 standard: Load `frontend-baseline` plus up to **3 specialized task skills** at the same time (e.g. `svg-icon-craftsman`, `animation-builder`, `webapp-tester`).
+- Respect `.agents/brain/config.json` confirmation settings before executing.

skill_brain/data/brain/decisions/git.md

@@ -0,0 +1,59 @@
+# Git Skills — Decision Making Matrix
+
+This document dictates how the agent handles version control operations, atomic commits, branch lifecycle management, and virtual memory phase commit synchronization.
+
+---
+
+## 1. Mandatory Baseline
+
+Before executing any git operations:
+- Never commit broken code, syntax errors, or unverified changes.
+- Never dump massive, unrelated multi-domain changes into a single generic commit.
+- Inspect `git status --porcelain` and `git diff --stat` before staging files.
+- Enforce Conventional Commits standard: `<type>(<scope>): <imperative summary>` (<= 72 chars), followed by a concise body and verification evidence footer.
+- When working within Virtual Memory (`.agents/memory/phases/`), every phase transition to `FINISHED` must trigger an atomic phase commit.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| Git Operational Goal | Selected Skills | Why This Combination |
+|---|---|---|
+| **User commands: `$commit`, `commit:`, or code ready to commit** | `git-atomic-committer` | Analyzes staged/unstaged changes, evaluates domain blast radius, splits into 2 or more atomic commits if changes span multiple domains, crafts Conventional Commit message with verification evidence. |
+| **User commands: `$branch`, `branch:`, or creating/syncing branches** | `git-branch-manager` | Enforces strict naming conventions (`feat/`, `fix/`, `phase/`, `refactor/`, `chore/`), checks working tree hygiene, performs rebase sync (`git pull --rebase origin main`), and handles branch cleanup. |
+| **A Virtual Memory Phase completes (`[VERIFY]` → `[FINISH]`)** | `git-phase-committer` | Hooks into Step 4 of `phase-planner`. Stages and splits phase code, test fixtures, and memory updates into atomic phase commits, recording verification proof in the commit body. |
+| **Feature isolation in separate workspace** | `git-branch-manager` + `git-isolator` | Creates an isolated worktree branch (`git worktree add ../feature-work -b feature/...`), keeping main branch unpolluted. |
+| **Preparing Pull Request / Merge readiness** | `git-atomic-committer` + `pr-writer` | Validates clean atomic commit history and synthesizes high-fidelity PR description from the commit log. |
+
+---
+
+## 3. Commit Splitting Decision Rule
+
+When analyzing workspace diffs:
+
+```
+Total Changed Files & Domains?
+│
+├── 1 domain, <= 3 tightly coupled files ──► SINGLE ATOMIC COMMIT
+│   └── Example: feat(auth): implement token refresh rotation
+│
+└── Multiple domains OR > 3 loosely coupled files ──► SPLIT INTO 2+ ATOMIC COMMITS
+    ├── Commit 1 (Core Domain / Backend): feat(...) or fix(...)
+    ├── Commit 2 (Tests & Verification Fixtures): test(...)
+    ├── Commit 3 (UI / Styling / Components): feat(ui) or style(...)
+    └── Commit 4 (Memory Phases / Config / Docs): chore(phase-N) or docs(...)
+```
+
+---
+
+## 4. Anti-AI SOP Commit Standard
+
+- **FORBIDDEN:**
+  - ❌ "Update files"
+  - ❌ "WIP" / "misc fixes" / "make code better"
+  - ❌ "Refactor code for improved readability and maintainability" (AI fluff)
+  - ❌ Monolithic 500-line commits combining UI, backend, tests, and config together.
+- **MANDATORY:**
+  - ✅ Imperative present tense in header ("add", "fix", "refactor", not "added" or "adds").
+  - ✅ Explicit scope in header: `feat(api): ...`, `fix(layout): ...`, `test(auth): ...`.
+  - ✅ Verification evidence in footer: `Verified: pytest passed (14 tests)`.

skill_brain/data/brain/decisions/memory.md

@@ -0,0 +1,48 @@
+# Memory Skills — Decision Making Matrix
+
+This document dictates how the Virtual Memory system is invoked, controlled, and cleaned.
+
+---
+
+## 1. The User Control Gate (Strict Policy)
+
+**The agent does NOT write every casual turn or trivial task into memory.**
+- Virtual memory is disk-backed and persistent (`.agents/memory/plans/` and `.agents/memory/phases/`).
+- **Trigger Condition:** The agent activates `phase-planner` ONLY when:
+  1. The user explicitly requests: *"add to memory"*, *"save this in memory"*, or *"make a plan for this"*.
+  2. The user initiates a large multi-phase feature and explicitly approves creating a master plan and phase breakdown.
+- If the user has NOT requested memory tracking, execute in-context without cluttering memory folders.
+
+---
+
+## 2. Specialized Skill Selection Matrix
+
+| Memory Need | Selected Skills | Why This Combination |
+|---|---|---|
+| **User commands: "add to memory" / multi-phase plan** | `phase-planner` | Creates `.agents/memory/plans/main-plan.md`, breaks it into `.agents/memory/phases/phase-NN-[name].md`, pre-assigns skills, and prints chat dashboard. |
+| **User resumes session: "where were we?"** | `session-continuity` | Inspects `.agents/memory/plans/` and `phases/`, reconstructs active phase status, and renders the dashboard. |
+| **Context window near limit / session handoff** | `context-handoff` | Compacts session deltas, decisions, open blockers, and git diff states into `.agents/memory/handoff-[date].md`. |
+| **Phase completed & verified** | `git-phase-committer` (`$phase-commit`) | Automatically stages and commits phase code, tests, and memory phase files in atomic sequence with verification evidence. |
+| **Task completed & verified** | `phase-planner` (cleanup mode) | Moves `main-plan.md` and all phase files to `.agents/memory/archive/[Date]-[Task]/`, clearing active phase folder. |
+
+---
+
+## 3. The Live Chat Status Dashboard Protocol
+
+When memory mode is active, the agent **must** prepend the live status widget at the top of every response:
+
+```markdown
+┌─────────────────────────────────────────────────────────────┐
+│ 🚀 PHASE STATUS DASHBOARD                                   │
+├─────────────────────────────────────────────────────────────┤
+│ Task: [Feature Name]                                        │
+│ Phase 1: [Scaffold]         -> [FINISHED ✓]                 │
+│ Phase 2: [Core Logic]       -> [IN PROGRESS ⚙️]              │
+│ Phase 3: [UI & Polish]      -> [PENDING ⏳]                 │
+├─────────────────────────────────────────────────────────────┤
+│ Active Phase: Phase 2                                       │
+│ Active Skills: [skill-a] + [skill-b]                        │
+│ Stage: [APPLY] -> [EXECUTE 👈] -> [VERIFY] -> [FINISH]      │
+└─────────────────────────────────────────────────────────────┘
+```
+