@namch/agent-assistant 1.0.3 → 1.1.0

package/documents/business/business-glossary.md

@@ -57,19 +57,19 @@ A **concrete output** produced by an agent during workflow execution. Deliverabl
 
 ---
 
-### Matrix Skill Discovery
+### Matrix Skill Discovery (HSOL)
 
-A **centralized system** that automatically resolves and injects relevant skills into agents based on their declared profile. Replaces hardcoded skill lists with dynamic resolution.
+A **Hybrid Skill Orchestration Layer (HSOL)** that combines static matrix-skills with dynamic community skills. Skills are resolved by agent profile and request context; dynamic discovery runs only for `hard`/`focus` variants when matrix fitness < 0.8 (blocking when < 0.75 so the current task uses the new skill; async when 0.75–0.8 for recommendations only). See `rules/SKILL-DISCOVERY.md` and `rules/SKILL-ORCHESTRATION.md`.
 
 **Resolution Flow**:
 ```
-Agent Profile → _index.yaml → Domain Files → Skill Selection → Injection
+Agent Profile → _index.yaml → Domain Files + _dynamic.yaml → Fitness → Inject; optionally discover (find-skills) by variant
 ```
 
 **Benefits**:
-- Single source of truth
-- Add skill = update 1 file
-- Consistent skill-agent mapping
+- Single source of truth (matrix + dynamic manifest)
+- Variant-aware: fast skips discovery; hard/focus use blocking/async by fitness
+- Current task can use newly installed skill when matrix insufficient (< 0.75)
 
 ---
 

package/documents/knowledge-architecture.md

@@ -174,7 +174,86 @@ Example:
     Injects: skills into agent context
 ```
 
-### 2.6 Rule Engine
+### 2.6 Hybrid Skill Orchestration Layer (HSOL) ⚡
+
+**NEW (v1.1)**: Intelligent system that bridges static matrix-skills with dynamic community skills via the **find-skills** skill. Discovery runs only for `hard`/`focus` variants; when no variant is set, the router chooses by task assessment.
+
+**Dynamic Discovery Interface:**
+- **Skill Path**: `{SKILLS_PATH}/find-skills/SKILL.md`
+- **Browse**: https://skills.sh/
+- **Commands**:
+  - `npx skills find [query]` — Search for skills
+  - `npx skills add <owner/repo@skill> -g -y` — Install globally
+  - `npx skills check` — Check for updates
+
+```
+HSOL Resolution Strategy:
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         SKILL REQUEST                                    │
+│                              │                                           │
+│              ┌───────────────┴───────────────┐                          │
+│              ▼                               ▼                          │
+│     ┌─────────────────┐            ┌─────────────────┐                  │
+│     │  MATRIX LOOKUP  │            │ DYNAMIC SEARCH  │                  │
+│     │   (< 10ms)      │            │ (find-skills)   │                  │
+│     │  Synchronous    │            │  Non-blocking   │                  │
+│     └────────┬────────┘            └────────┬────────┘                  │
+│              │                              │                           │
+│              ▼                              ▼                           │
+│     ┌─────────────────┐            ┌─────────────────┐                  │
+│     │ Fitness Score   │            │ Fitness Score   │                  │
+│     │ (Pre-computed)  │            │ (Calculated)    │                  │
+│     └────────┬────────┘            └────────┬────────┘                  │
+│              │                              │                           │
+│              └───────────────┬──────────────┘                           │
+│                              ▼                                          │
+│                    ┌─────────────────┐                                  │
+│                    │ DECISION ENGINE │                                  │
+│                    │  Apply Formula  │                                  │
+│                    └────────┬────────┘                                  │
+│                              │                                          │
+│        ┌─────────────────────┼─────────────────────┐                   │
+│        ▼                     ▼                     ▼                   │
+│  ┌───────────┐        ┌───────────┐        ┌───────────┐               │
+│  │ USE MATRIX│        │  ENHANCE  │        │USE DYNAMIC│               │
+│  │  (≥0.80)  │        │  (delta)  │        │  (better) │               │
+│  └───────────┘        └───────────┘        └───────────┘               │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Fitness Scoring Formula:**
+```
+SKILL_FITNESS = (0.35 × SEMANTIC_MATCH) +
+                (0.25 × SPECIFICITY) +
+                (0.20 × TRUST_SCORE) +
+                (0.10 × FRESHNESS) +
+                (0.10 × SUCCESS_RATE)
+```
+
+**Decision Thresholds:**
+| Condition | Action |
+|-----------|--------|
+| Matrix fitness ≥ 0.80 | Use matrix skill immediately |
+| Matrix fitness 0.75-0.79 + dynamic superior by ≥0.15 | Consider dynamic enhancement (async) |
+| Matrix fitness < 0.75 | Search dynamic skills (blocking; use for current task) |
+| Dynamic skill superior | Surface as enhancement option |
+
+**Trust Progression (Dynamic Skills):**
+```
+new → evaluating → validated → promoted
+0.3      0.5          0.7         1.0
+         │            │           │
+         │            │           └── Promoted to matrix-skills
+         │            └── 10+ successful uses, user validation
+         └── 3 uses without failure
+```
+
+**Key Files:**
+- `rules/SKILL-ORCHESTRATION.md` — Full protocol
+- `matrix-skills/_dynamic.yaml` — Dynamic skill manifest
+- `matrix-skills/_index.yaml` — HSOL configuration
+
+### 2.7 Rule Engine
 
 Enforces orchestration laws and protocols.
 
@@ -183,6 +262,7 @@ Enforces orchestration laws and protocols.
 | `ORCHESTRATION-LAWS.md` | 10 inviolable laws | CRITICAL |
 | `EXECUTION-PROTOCOL.md` | Phase execution details | CRITICAL |
 | `ADAPTIVE-EXECUTION.md` | Tier 1/2 decisions | CRITICAL |
+| `SKILL-ORCHESTRATION.md` | HSOL decision logic | CRITICAL |
 | `AGENT-RULES.md` | Agent behavior guidelines | Reference |
 | `SKILL-DISCOVERY.md` | Matrix resolution algorithm | Reference |
 | `ERROR-RECOVERY.md` | Error handling protocols | Reference |

package/documents/knowledge-domain.md

@@ -124,11 +124,11 @@ execution-mode: string          # "execute" | "router"
 | Command | Description | Variants | Category |
 |---------|-------------|----------|----------|
 | `/cook` | Implement features | `:fast`, `:hard`, `:focus` | development |
-| `/code` | Write code snippets | `:fast`, `:hard` | development |
+| `/code` | Write code snippets | `:fast`, `:hard`, `:focus` | development |
 | `/fix` | Fix bugs and refactor | `:fast`, `:hard`, `:focus` | development |
-| `/test` | Generate tests | `:fast`, `:hard` | quality |
+| `/test` | Generate tests | `:fast`, `:hard`, `:focus` | quality |
 | `/review` | Code review | `:fast`, `:hard` | quality |
-| `/debug` | Systematic debugging | `:fast`, `:hard` | quality |
+| `/debug` | Systematic debugging | `:fast`, `:hard`, `:focus` | quality |
 | `/plan` | Implementation planning | `:fast`, `:hard`, `:focus` | planning |
 | `/report` | Create/update reports, summaries | `:fast`, `:hard`, `:focus` | documentation |
 | `/brainstorm` | Requirements discovery | `:fast`, `:hard` | planning |
@@ -144,6 +144,7 @@ execution-mode: string          # "execute" | "router"
 |---------|---------|-------------|---------------|
 | `:fast` | Quick execution | 2-3 agents | Minimal |
 | `:hard` | Full workflow | 5-8 agents | All 5 gates |
+| `:focus` | Full workflow with clear context | 5-8 agents | All 5 gates |
 | `:core` | Core documentation | scouter, docs-manager | — |
 | `:business` | Business documentation | researcher, business-analyst, docs-manager | — |
 | `:audit` | Security/compliance audit | security-engineer, docs-manager | — |

package/documents/knowledge-overview.md

@@ -9,7 +9,7 @@
 | Property       | Value                                              |
 | -------------- | -------------------------------------------------- |
 | **Name**       | Agent Assistant                                    |
-| **Version**    | 1.0.0                                              |
+| **Version**    | 1.1.0                                              |
 | **Type**       | Multi-agent orchestration framework                |
 | **Author**     | NamCH                                              |
 | **License**    | MIT                                                |

package/documents/knowledge-source-base.md

@@ -323,7 +323,7 @@ assets/
 All tool entry points follow the same pattern:
 
 ```markdown
-# ⚡ AGENT ASSISTANT v3.0
+# ⚡ AGENT ASSISTANT v2.0
 
 > **LOAD**: `{HOME}/.cursor/skills/agent-assistant/rules/BOOTSTRAP.md`
 > **This file is the ENTRY POINT. BOOTSTRAP.md contains all orchestration rules.**
@@ -386,19 +386,24 @@ node cli/install.js uninstall copilot
 node cli/install.js list
 ```
 
-### 4.2 Matrix Skill Discovery (`matrix-skills/_index.yaml`)
+### 4.2 Matrix Skill Discovery (HSOL: `matrix-skills/_index.yaml` + `_dynamic.yaml`)
 
-**Purpose**: Central registry for skill resolution.
+**Purpose**: Central registry for skill resolution and HSOL (Hybrid Skill Orchestration Layer). Combines static matrix domains with dynamic skills; discovery runs only for `hard`/`focus` variants when matrix fitness < 0.8 (blocking when < 0.75). See `rules/SKILL-DISCOVERY.md` and `rules/SKILL-ORCHESTRATION.md`.
 
 **Key Sections**:
 
 ```yaml
-version: "1.0"
-total_skills: 310
+version: "1.1"
+total_matrix_skills: 310
+
+hsol:                            # HSOL config (discovery, thresholds 0.75/0.8, apply_for_variants: [hard, focus])
+  enabled: true
+  dynamic_manifest: "_dynamic.yaml"
+  discovery: { apply_for_variants: [hard, focus], ... }
+  thresholds: { matrix_sufficient: 0.8, matrix_adequate: 0.75, ... }
 
 domains:                         # 19 domain registrations
   backend: { file: "backend.yaml", ... }
-  frontend: { file: "frontend.yaml", ... }
   # ...
 
 agent_profiles:                  # 21 agent-to-domain mappings
@@ -410,7 +415,6 @@ agent_profiles:                  # 21 agent-to-domain mappings
 
 resolution:                      # Resolution rules
   precedence: [direct_agent_match, profile_match, domain_inheritance]
-  wildcards: { "*:orchestration": "...", "backend:*": "..." }
   thresholds: { minimum_priority: 5, core_priority: 7, critical_priority: 9 }
 ```
 
@@ -456,7 +460,8 @@ handoffs: [agent1, agent2, ...]
 
 | File | Purpose |
 |------|---------|
-| `_index.yaml` | Central matrix registry |
+| `_index.yaml` | Central matrix registry + HSOL config |
+| `_dynamic.yaml` | Dynamic skill manifest (updated when agents run `npx skills add ... -g -y`) |
 | `AGENT-TEMPLATE.md` | Agent creation template |
 | `README.md` | Public documentation |
 | `LICENSE` | MIT license file |
@@ -473,8 +478,8 @@ handoffs: [agent1, agent2, ...]
 ```json
 {
   "name": "agent-assistant",
-  "version": "1.0.0",
-  "description": "Multi-agent orchestration framework for AI coding assistants",
+  "version": "1.1.0",
+  "description": "Multi-agent orchestration framework for AI coding assistants (with HSOL)",
   "main": "cli/install.js",
   "bin": {
     "agent-assistant": "./cli/install.js"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@namch/agent-assistant",
-  "version": "1.0.3",
-  "description": "Multi-agent orchestration framework for AI coding assistants (Cursor, Copilot, Antigravity, Claude Code).",
+  "version": "1.1.0",
+  "description": "Multi-agent orchestration framework for AI coding assistants (Cursor, Copilot, Antigravity, Claude Code) with Hybrid Skill Orchestration Layer (HSOL).",
   "main": "cli/install.js",
   "bin": {
     "agent-assistant": "./cli/install.js"
@@ -44,7 +44,9 @@
     "skills/",
     "documents/",
     "code-assistants/",
-    "LICENSE"
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package/rules/AGENTS.md

@@ -0,0 +1,187 @@
+# 🤖 AGENTS
+
+> **LOAD**: When delegating to agents | **PURPOSE**: Agent handling protocol
+
+---
+
+## TIERED EXECUTION
+
+### TIER 1: Sub-agent (MANDATORY when tool exists)
+
+```yaml
+1. Prepare handoff:
+   include: requirements, task, acceptance criteria, constraints
+   exclude: internal reasoning, failed attempts
+
+2. Skills analysis: (output required)
+   "🎯 Skills Analysis: {simple|complex} → {using X | skipping}"
+
+3. Invoke: runSubagent(agent_name, context)
+
+4. Verify: format matches, criteria met
+
+5. On error: fallback to TIER 2, log reason
+```
+
+### TIER 2: EMBODY (Fallback only)
+
+```yaml
+permitted_when:
+  - Tool Discovery found NO sub-agent tools
+  - Sub-agent tool returned system error
+
+forbidden_reasons:
+  - Task seems "simple"
+  - "Save tokens"
+  - "Efficiency"
+
+execution:
+  1. Log: "⚠️ TIER 2: {reason}"
+  2. READ agent file COMPLETELY
+  3. EXTRACT: Directive, Protocol, Constraints, Format
+  4. ANNOUNCE embodiment (see format below)
+  5. EXECUTE as agent (follow THEIR protocol)
+  6. EXIT embodiment, continue as orchestrator
+```
+
+**Embodiment Announcement Format**:
+```markdown
+📋 EMBODIED: `{agent}`
+**Directive**: {core directive verbatim}
+**Protocol**: {thinking protocol summary}
+**Constraints**: {key constraints}
+```
+
+---
+
+## TOOL DISCOVERY (First delegation only)
+
+```markdown
+## 🔍 Tool Discovery
+| Check | Result |
+|-------|--------|
+| Sub-agent tool | ✅ / ❌ |
+| Execution tier | TIER 1 / TIER 2 |
+```
+
+**Cache**: Tool discovery result is cached for session. Do not re-check.
+
+---
+
+## CONTEXT MODEL COMPARISON
+
+| Aspect | TIER 1: Sub-agent | TIER 2: EMBODY |
+|--------|-------------------|----------------|
+| Priority | ⭐ MANDATORY | 🔄 Fallback |
+| Context | Fresh, isolated | Shared with parent |
+| Quality | ✅ Optimal | ⚠️ Risk of pollution |
+| Parallel | Yes | No (sequential) |
+| Availability | Platform-dependent | Always available |
+
+---
+
+## COMPLETION GUARANTEE
+
+```yaml
+rule: "EVERY delegation request WILL be fulfilled"
+
+mechanism:
+  - TIER 1 is primary when available
+  - TIER 2 is fallback when TIER 1 fails
+  - EMBODY always works (read + transform)
+
+result:
+  - NO task is ever skipped
+  - NO delegation ever fails completely
+  - System is future-proof
+```
+
+---
+
+## AGENT CATEGORIES
+
+| Category | Agents | Purpose |
+|----------|--------|---------|
+| **meta** | tech-lead, planner | Coordinate, never implement |
+| **execution** | backend-engineer, frontend-engineer, mobile-engineer, game-engineer, database-architect | Implementation |
+| **validation** | tester, reviewer, security-engineer, performance-engineer, debugger | QA |
+| **research** | researcher, scouter, brainstormer, designer | Investigation |
+| **support** | docs-manager, devops-engineer, business-analyst, project-manager, reporter | Support |
+
+---
+
+## TASK → AGENT MAPPING
+
+| Task | Agent |
+|------|-------|
+| API, backend logic | `backend-engineer` |
+| UI, components | `frontend-engineer` |
+| Database schema | `database-architect` |
+| Security | `security-engineer` |
+| Testing | `tester` |
+| Code review | `reviewer` |
+| Debugging | `debugger` |
+| Planning | `planner` |
+| Research | `researcher` |
+| Codebase analysis | `scouter` |
+| Documentation | `docs-manager` |
+| Deployment | `devops-engineer` |
+| Reports | `reporter` |
+| Project management | `project-manager` |
+| Business analysis | `business-analyst` |
+| Design | `designer` |
+| Brainstorming | `brainstormer` |
+| Game development | `game-engineer` |
+| Mobile development | `mobile-engineer` |
+| Technical leadership | `tech-lead` |
+
+---
+
+## CONTEXT ISOLATION (Clean Handoffs)
+
+```
+INCLUDE:
+  - Original requirements (verbatim)
+  - Decisions from prior phases
+  - Concrete deliverables
+  - Current state
+
+EXCLUDE:
+  - Internal reasoning
+  - Failed attempts
+  - Alternatives not selected
+```
+
+---
+
+## RECURSIVE DELEGATION
+
+```
+IF agent.category == "meta" OR agent.handoffs.length > 0:
+  → This is a MANAGER agent
+  → MUST delegate to specialists
+  → NEVER implement directly
+```
+
+---
+
+## ANTI-LAZY FALLBACK DETECTION
+
+```yaml
+detection:
+  - Choosing TIER 2 without attempting TIER 1
+  - Justifying EMBODY with "task is simple"
+  - Mentioning "efficiency" when choosing EMBODY
+
+correction:
+  1. STOP
+  2. Log: "⚠️ LAZY FALLBACK DETECTED"
+  3. Attempt TIER 1 first
+  4. Only use TIER 2 if TIER 1 actually fails
+
+strict_rules:
+  ❌ NEVER assess task as "too simple" for sub-agent
+  ❌ NEVER prioritize tokens over context isolation
+  ✅ ALWAYS use sub-agent when tool exists
+  ✅ ALWAYS log sub-agent attempt before any EMBODY
+```