@woopsy/ai-agent-skills 1.0.0

package/skills/secondary-brain/reference/deep-mode.md

@@ -0,0 +1,90 @@
+# Reference Architecture Protocol — "Deep Mode"
+
+This is the authoritative, full-ceremony ruleset for the SecondaryBrain. The everyday loop (read → reuse → update) lives in the `connect` command. Apply the rules below when working in **deep mode** (large refactors, new project bootstrapping, periodic graph cleanup).
+
+## 1. Neural Graph Model
+
+Every project, module, file, and skill is a **NODE**. Three layers are maintained:
+
+1. **Logical graph** — Obsidian `[[wikilinks]]` between node files.
+2. **Visual graph** — Mermaid diagrams inside nodes and in `GLOBAL-PROJECT-MEMORY.md`.
+3. **Temporal graph** — the evolution timeline (per project + global index).
+
+## 2. Node Anatomy (Deep Mode)
+
+Each node file should carry this metadata block:
+
+```
+## GRAPH METADATA
+- cluster:
+- node_type:
+- importance_level:
+- hub_node: true/false
+- tags:
+```
+
+And a scoring block:
+
+```
+- importance_score: 0.0–1.0
+- hub_score:
+- reuse_score:
+- stability_score:
+- dependency_weight:
+```
+
+Plus a Mermaid graph showing its dependencies:
+
+```mermaid
+graph TD
+  A[This Node] --> B[Dependency]
+  A --> C[Module]
+```
+
+## 3. The Update Pipeline (run on ANY deep-mode change)
+
+1. Update nodes
+2. Update `[[links]]`
+3. Update Mermaid graph
+4. Re-run importance scoring (see scoring-guide.md)
+5. Run pruning (see §4)
+6. Run self-healing (see §5)
+7. Run refactor engine (see §6)
+8. Run future-architecture prediction (see §7)
+9. Update evolution timeline
+10. Update `GLOBAL-PROJECT-MEMORY.md`
+
+## 4. Pruning
+
+A node is **dead** when `importance_score < 0.15` AND it has no inbound links AND it has not been used recently. Action: mark deprecated → move to the Deprecated Nodes section of `GLOBAL-PROJECT-MEMORY.md` → remove from the active graph. Never hard-delete history; archive it.
+
+## 5. Self-Healing
+
+The graph must never stay broken: fix broken `[[links]]`, merge duplicate nodes, resolve circular dependencies, and unify conflicting architecture versions.
+
+## 6. Refactor Engine (Graph Density)
+
+- Node with too many connections → split it.
+- Node with too few connections → merge or remove it.
+- Duplicate patterns across nodes → extract a shared skill node into `Ai - skills/`.
+- Repeated logic → abstract into a core module node.
+
+## 7. Future-Architecture Prediction (run BEFORE designing any system)
+
+Generate three sections:
+
+- **Next-state architecture** — how it evolves at scale; new modules; needed abstraction layers.
+- **Future node map** — missing nodes, likely future services, required refactor points.
+- **Failure prediction** — first bottlenecks, scaling issues, coupling risks, collapse points.
+
+## 8. Evolution Timeline (Per Project)
+
+- Phase 1: Initial build
+- Phase 2: Growth pressure
+- Phase 3: System expansion
+- Phase 4: Optimization
+- Phase 5: Neural maturity
+
+## 9. Authority
+
+In deep mode you may design full systems, restructure architecture, merge projects, deprecate dead nodes, and refactor entire graphs — then document every assumption inside the affected nodes and reflect the result in `GLOBAL-PROJECT-MEMORY.md`.

package/skills/secondary-brain/reference/mermaid-cheatsheet.md

@@ -0,0 +1,81 @@
+# Mermaid Diagram Cheatsheet for Graph Nodes
+
+Standard patterns used across SecondaryBrain nodes.
+
+## Basic Node Graph
+
+```mermaid
+graph TD
+  A[Node Name] --> B[Dependency]
+  A --> C[Module]
+  B --> D[Skill]
+  C --> E[(Database)]
+```
+
+## Subgraphs (Clusters)
+
+```mermaid
+graph TD
+  subgraph Discord
+    Bot[[Himawari-Bot]]
+  end
+  subgraph Minecraft
+    Mod[[Himawari-SMP]]
+  end
+  Bot <-->|"@supabase/sdk"| DB[(Shared DB)]
+  Mod <-->|"REST + WS"| DB
+```
+
+## Styling
+
+```mermaid
+graph TD
+  A[Important] --> B[Regular]
+  A --> C[External]
+  style A fill:#e1f5fe,stroke:#01579b
+  style C fill:#fce4ec,stroke:#c62828
+  classDef hub fill:#e8f5e9,stroke:#2e7d32
+  class A hub
+```
+
+## Link to Obsidian Notes
+
+```mermaid
+graph TD
+  A[This Node] --> B[Node Name]
+  class B internal-link;
+```
+
+The `internal-link` class makes Mermaid nodes clickable in Obsidian — they link to `Node Name.md`.
+
+## Edge Styles
+
+| Syntax | Meaning |
+|---|---|
+| `A --> B` | Directed edge |
+| `A --- B` | Undirected edge |
+| `A -.-> B` | Dotted edge (weak/async relationship) |
+| `A ==> B` | Thick edge (strong dependency) |
+| `A <--> B` | Bidirectional |
+| `A -->\|"label"\| B` | Labeled edge |
+| `A --x B` | X head (blocked by) |
+| `A --o B` | Circle head (optional dependency) |
+
+## Node Shapes
+
+| Syntax | Shape |
+|---|---|
+| `A[Text]` | Rectangle |
+| `A(Text)` | Rounded rectangle |
+| `A((Text))` | Circle |
+| `A{Text}` | Diamond (decision) |
+| `A>Text]` | Asymmetric (flag) |
+| `A[(Text)]` | Cylinder (database) |
+| `A[[Text]]` | Obsidian internal link |
+
+## Best Practices
+
+- Keep graphs focused — max 10-15 nodes per diagram. Split large systems into sub-diagrams.
+- Use subgraphs for bounded contexts or deployment boundaries.
+- Use `internal-link` class for nodes that correspond to actual Obsidian note files.
+- Add a title comment above each graph explaining what it shows.

package/skills/secondary-brain/reference/platform-adapters.md

@@ -0,0 +1,74 @@
+# Platform Adapters — Manual Installation
+
+If the auto-installer does not support your agent platform, use these manual instructions.
+
+## Prerequisites
+
+- An Obsidian vault with `SecondaryBrain/` and `GLOBAL-PROJECT-MEMORY.md`
+- The `skills/secondary-brain/` directory from this repository
+
+## Claude Code
+
+```bash
+# Copy the skill to Claude Code's skill directory
+mkdir -p ~/.claude/skills/secondary-brain
+cp -r skills/secondary-brain/* ~/.claude/skills/secondary-brain/
+
+# Or use skills-manager if available
+mkdir -p ~/.skills-manager/skills/secondary-brain
+cp -r skills/secondary-brain/* ~/.skills-manager/skills/secondary-brain/
+```
+
+Then add to `~/.claude/settings.json`:
+```json
+{
+  "enabledPlugins": {
+    "secondary-brain@local": true,
+    "obsidian@obsidian-skills": true
+  }
+}
+```
+
+## opencode
+
+```bash
+mkdir -p ~/.config/opencode/skills/secondary-brain
+cp -r skills/secondary-brain/* ~/.config/opencode/skills/secondary-brain/
+```
+
+OpenCode auto-discovers all `SKILL.md` files under `~/.config/opencode/skills/`. No config changes needed.
+
+## Cursor
+
+Create `~/.cursor/rules/secondary-brain.mdc`:
+
+```yaml
+---
+description: SecondaryBrain — persistent project memory via Obsidian vault
+globs: "**/*"
+---
+```
+
+Then append the contents of `skills/secondary-brain/SKILL.md` below the frontmatter.
+
+## Codex
+
+```bash
+mkdir -p ~/.codex/skills/secondary-brain
+cp -r skills/secondary-brain/* ~/.codex/skills/secondary-brain/
+```
+
+## GitHub Copilot
+
+Add this section to `.github/copilot-instructions.md` in your repository:
+
+> ## SecondaryBrain Protocol
+> Before starting any task, read `SecondaryBrain/GLOBAL-PROJECT-MEMORY.md` and the relevant project cluster. After changes, update the project nodes and GLOBAL-PROJECT-MEMORY.md.
+
+## Gemini Code Assist
+
+Create `~/.gemini/instruction/secondary-brain.md` with the contents of `skills/secondary-brain/SKILL.md`.
+
+## Any Other Agent
+
+Use the handoff template (`templates/handoff.md`) to transfer context between agents. Copy the filled template and paste it as context before starting work.

package/skills/secondary-brain/reference/scoring-guide.md

@@ -0,0 +1,63 @@
+# Node Importance Scoring Guide
+
+Each node in the SecondaryBrain carries five scores that determine its role in the graph. Scores are 0.0–1.0 (float).
+
+## Score Definitions
+
+### importance_score (0.0–1.0)
+How critical this node is to the project. Analogous to PageRank.
+
+| Range | Meaning |
+|---|---|
+| 0.00–0.14 | Low value — candidate for pruning |
+| 0.15–0.39 | Supporting node — referenced occasionally |
+| 0.40–0.69 | Important node — core to a subsystem |
+| 0.70–0.89 | Hub node — central to the project |
+| 0.90–1.00 | Critical node — project-defining |
+
+**Formula:** `inbound_links_weight + recency_weight + content_size_weight`
+
+### hub_score (0.0–1.0)
+How many other nodes connect through this one. High hub_score = many outbound edges.
+
+### reuse_score (0.0–1.0)
+How often this node's patterns are referenced across projects. High = extracted to `Ai - skills/` or frequently linked.
+
+### stability_score (0.0–1.0)
+How stable the node's content is. High = rarely changed, well-established. Low = in active development, likely to change.
+
+### dependency_weight (0.0–1.0)
+How many things break if this node changes. High = many downstream dependents.
+
+## When to Recalculate
+
+- After any deep-mode change (run step 4 of the pipeline)
+- After adding a new node
+- After pruning/archiving a node
+- When `GLOBAL-PROJECT-MEMORY.md` is updated
+
+## Pruning Threshold
+
+A node is **dead** when ALL three conditions are met:
+1. `importance_score < 0.15`
+2. No inbound `[[links]]` from other nodes
+3. Not modified or referenced in the last 30 days
+
+Action: mark deprecated → archive in GLOBAL-PROJECT-MEMORY.md Deprecated Nodes section → remove from active graph.
+
+## Example
+
+```yaml
+## GRAPH METADATA
+- cluster: himawari
+- node_type: system-hub
+- importance_level: critical
+- hub_node: true
+- tags: [minecraft, discord, supabase]
+
+- importance_score: 0.92
+- hub_score: 0.85
+- reuse_score: 0.30
+- stability_score: 0.75
+- dependency_weight: 0.90
+```

package/skills/secondary-brain/templates/00-project-node.md

@@ -0,0 +1,41 @@
+# {{PROJECT_NAME}} — {{NODE_TYPE}}
+
+Hub node for the {{PROJECT_NAME}} system.
+
+## GRAPH METADATA
+- cluster: {{CLUSTER_ID}}
+- node_type: {{NODE_TYPE}}
+- importance_level: {{LEVEL}}
+- hub_node: {{IS_HUB}}
+- tags: [{{TAGS}}]
+
+- importance_score: {{SCORE}}
+- hub_score: {{SCORE}}
+- reuse_score: {{SCORE}}
+- stability_score: {{SCORE}}
+- dependency_weight: {{WEIGHT}}
+
+## Architecture
+
+```mermaid
+graph TD
+  A[{{PROJECT_NAME}}] --> B[Dependency 1]
+  A --> C[Dependency 2]
+  B --> D[Sub-module]
+  class A internal-link;
+```
+
+{{DESCRIPTION}}
+
+## Sub-nodes
+
+- [[node-1]] — description
+- [[node-2]] — description
+
+## Build / Deploy
+
+{{BUILD_NOTES}}
+
+## Docs
+
+{{DOCS_NOTES}}

package/skills/secondary-brain/templates/01-feature-node.md

@@ -0,0 +1,39 @@
+# {{FEATURE_NAME}}
+
+{{ONE_LINE_DESCRIPTION}}
+
+## GRAPH METADATA
+- cluster: {{CLUSTER_ID}}
+- node_type: feature
+- importance_level: {{LEVEL}}
+- hub_node: false
+- tags: [{{TAGS}}]
+
+- importance_score: {{SCORE}}
+- hub_score: {{SCORE}}
+- reuse_score: {{SCORE}}
+- stability_score: {{SCORE}}
+- dependency_weight: {{WEIGHT}}
+
+```mermaid
+graph TD
+  A[{{FEATURE_NAME}}] --> B[Dependency]
+  A --> C[Service]
+  class A internal-link;
+```
+
+## Behavior
+
+{{BEHAVIOR}}
+
+## Commands / API
+
+{{COMMANDS}}
+
+## Database
+
+{{DB_NOTES}}
+
+## Edge Cases
+
+{{EDGE_CASES}}

package/skills/secondary-brain/templates/handoff.md

@@ -0,0 +1,47 @@
+# Project Handoff
+
+> Paste this into a new AI agent after the system prompt to hand off a single project with full context.
+
+---
+
+## Project: {{PROJECT_NAME}}
+
+**Cluster:** {{CLUSTER_ID}}
+**Status:** {{STATUS}}
+**Last updated:** {{DATE}}
+
+### One-line summary
+{{SUMMARY}}
+
+### Current architecture (hub nodes)
+- `SecondaryBrain/{{PROJECT}}/00-overview.md` — overview
+- `SecondaryBrain/{{PROJECT}}/02-architecture.md` — architecture
+- {{ADDITIONAL_HUBS}}
+
+### Tech stack
+{{TECH_STACK}}
+
+### What works right now
+- {{DONE_FEATURES}}
+
+### Current task / next steps
+1. {{NEXT_TASK}}
+2. {{FOLLOW_UP}}
+
+### Open questions / decisions pending
+- {{OPEN_QUESTIONS}}
+
+### Reusable patterns already extracted
+- `Ai - skills/{{PATTERN}}.md` — {{PATTERN_DESC}}
+
+### Constraints / gotchas
+- {{CONSTRAINTS}}
+
+### Where to read first
+1. `GLOBAL-PROJECT-MEMORY.md` → find the `{{CLUSTER_ID}}` cluster
+2. `SecondaryBrain/{{PROJECT}}/00-overview.md`
+3. {{ADDITIONAL_READING}}
+
+---
+
+> After completing work, update the project's nodes and `GLOBAL-PROJECT-MEMORY.md`, then regenerate this handoff so the next agent starts current.