@namch/agent-assistant 1.0.4 → 1.1.0

package/commands/test/hard.md

@@ -17,12 +17,14 @@ execution-mode: execute
 
 **LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
 
-1. ORCHESTRATION-LAWS.md
-2. ADAPTIVE-EXECUTION.md
-3. EXECUTION-PROTOCOL.md
+1. CORE.md — Identity, Laws, Routing
+2. PHASES.md — Phase Execution
+3. AGENTS.md — Tiered Execution
 
 **⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files; they override any conflicting instructions in this file.
 
+**Skills Resolution**: When delegating, load `SKILLS.md` on-demand for fitness calculation and dynamic discovery (hard/focus variants enable find-skills).
+
 ---
 
 ## 🔀 TIERED EXECUTION
@@ -95,23 +97,29 @@ option_1_clear_execute:
     1. ACKNOWLEDGE: "🚀 Context optimized. Executing test strategy."
     2. CONTEXT_DIRECTIVE: |
        ⛔ IGNORE strategy discussion and rejected approaches.
-       ✅ FINALIZED STRATEGY is SOLE SOURCE OF TRUTH.
-    3. PROCEED: Continue to test execution phases
+## 🛡️ VERIFICATION CHECKPOINT
 
-option_2_review_strategy:
-  behavior: "Clear and show summary"
-  steps:
-    1. ACKNOWLEDGE: "⏸️ Context cleared."
-    2. OUTPUT: Display strategy summary
-    3. WAIT: For user approval
+> **⛔ BLOCKING**: Load Context Gate protocol NOW before proceeding.
+>
+> **LOAD**: `rules/CONTEXT-GATE.md` — Execute HARD MODE (Test variant)
+>
+> This is a MANDATORY checkpoint. Cannot skip or bypass.
 
-option_3_continue_no_clear:
-  behavior: "Proceed with caution"
-  steps:
-    1. WARN: "⚠️ Discussion history retained."
-    2. PROCEED: Continue with existing context
+### ⚡ EXECUTION
+
+```yaml
+context_gate_execution:
+  mode: "HARD (User Choice)"
+  trigger: "After Phase 1 (Test Strategy) completes"
+  protocol: "Follow rules/CONTEXT-GATE.md § HARD MODE § test_hard_variant"
+  
+  variant_adjustments:
+    plan_source: "Finalized test strategy from Phase 1"
+    remaining_phases: "Phase 2 → 3 → 4 → 5"
 ```
 
+**DO NOT proceed to Phase 2 until user selects option.**
+
 ---
 
 ## 🎭 Phase 2: DEPENDENCY MAPPING

package/commands/test.md

@@ -16,9 +16,9 @@ execution-mode: router
 ## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS EXECUTION)
 
 **LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
-1. ORCHESTRATION-LAWS.md  
-2. ADAPTIVE-EXECUTION.md  
-3. EXECUTION-PROTOCOL.md  
+1. CORE.md — Identity, Laws, Routing  
+2. PHASES.md — Phase Execution  
+3. AGENTS.md — Tiered Execution  
 
 **⛔ Do not run any workflow phase until all are loaded.** Follow **all** rules in those files. Then run this file's ROUTING LOGIC, LOAD the chosen variant workflow, and execute it.
 

package/documents/HSOL-ASSESSMENT.md

@@ -0,0 +1,121 @@
+# HSOL (Hybrid Skill Orchestration Layer) — Production Readiness Assessment
+
+> **Purpose**: One-time evaluation of HSOL design and docs for production readiness and agent intelligence.
+> **Scope**: SKILL-DISCOVERY.md, SKILL-ORCHESTRATION.md, _index.yaml, _dynamic.yaml, find-skills SKILL, Blueprint.
+> **Project version**: 1.1.0
+
+---
+
+## Executive Summary
+
+| Dimension | Rating | Notes |
+|-----------|--------|--------|
+| **Completeness** | Strong | Resolution algorithm, decision gate, blocking/async, variant/fitness, trust, conflict, edge cases are defined. |
+| **Consistency** | Strong | Thresholds (0.75, 0.8), variant (fast/hard/focus), and flow align across Discovery, Orchestration, _index.yaml, Blueprint. |
+| **Production readiness** | Good | Clear rules for tool scope, install commands, fallbacks; a few operational gaps (see below). |
+| **Agent intelligence** | Strong | Matrix-first + dynamic enhancement, blocking when matrix insufficient so current task uses new skill; async when matrix adequate. |
+
+**Verdict**: HSOL is **sufficient for production** as a **specification and rule set** for orchestrators and agents. Implementers (or AI following the rules) have enough to resolve skills, decide when to discover, and handle install/recommend. Suggested updates below are small clarifications and one extra edge case.
+
+---
+
+## Strengths
+
+1. **Clear separation of concerns**
+   - SKILL-DISCOVERY: *what* (10-step flow, resolution algorithm, when discovery runs).
+   - SKILL-ORCHESTRATION: *how to decide* (6-step flow, decision gate, trust, conflict, config).
+   - Single source of truth for thresholds in `_index.yaml`.
+
+2. **Variant + fitness logic**
+   - Fast → no discovery (keeps fast path low-latency).
+   - Hard/Focus + fitness ≥ 0.8 → skip discovery.
+   - Hard/Focus + 0.75 ≤ fitness < 0.8 → async (recommend for next time).
+   - Hard/Focus + fitness < 0.75 → blocking (current task uses new skill). Aligns with “skill for current work” goal.
+
+3. **Tool-scoped behavior**
+   - All install/verify actions are for the **current tool only**; `-g -y` and no cross-tool install unless user asks. Reduces confusion and errors.
+
+4. **Trust and safety**
+   - Low-trust + task-critical → ask user confirm before install.
+   - Trust progression and auto-promotion criteria are defined.
+   - Conflict resolution (ID collision, domain overlap) is specified.
+
+5. **Edge cases**
+   - Network timeout → proceed with matrix, surface message.
+   - No skills found → capability gap, offer general help + `npx skills init`.
+   - Installation failure → rollback, retry command, offer matrix-only.
+
+6. **Discoverability**
+   - BOOTSTRAP and QUICK-REFERENCE point to HSOL; rules reference Blueprint and each other.
+
+---
+
+## Gaps and Improvements
+
+### 1. Principle wording (minor)
+
+**Issue**: SKILL-ORCHESTRATION says “Dynamic discovery never blocks execution.” We also have a **blocking** path when fitness < 0.75.
+
+**Fix**: Clarify that discovery **does** block only when matrix is insufficient (< 0.75) so the current task can use the new skill; otherwise it does not block. (Doc update below.)
+
+### 2. find-skills missing or unavailable (operational)
+
+**Issue**: If find-skills is not installed, or `npx skills find` fails (e.g. network, CLI not available), the blocking path cannot run. Doc does not state the fallback.
+
+**Fix**: Add edge case: “If find-skills is not available or discovery cannot run, proceed with matrix skills only and optionally surface: ‘Dynamic skill discovery is unavailable. Using built-in skills.’” (Doc update below.)
+
+### 3. BOOTSTRAP reference table (discoverability)
+
+**Issue**: BOOTSTRAP lists “Skill resolution (HSOL) → SKILL-ORCHESTRATION.md” but not SKILL-DISCOVERY.md. Implementers need both (algorithm + decision logic).
+
+**Fix**: Add one row for “Matrix resolution algorithm (HSOL)” → SKILL-DISCOVERY.md, or a note that HSOL = SKILL-ORCHESTRATION + SKILL-DISCOVERY. (Doc update below.)
+
+### 4. _dynamic.yaml writer (optional clarity)
+
+**Issue**: _dynamic.yaml says “HSOL validates and registers skill here” but does not say *who* writes it (e.g. skills CLI on `npx skills add`, or a post-install hook). For code implementations, this matters.
+
+**Suggestion**: In _dynamic.yaml or Blueprint, add one line: “Updated when user runs `npx skills add <skill> -g -y` (skills CLI or install script appends/updates this file).” No change required if the repo is doc-only and the “resolver” is the human/orchestrator.
+
+### 5. Default variant (optional)
+
+**Issue**: When user says `/cook` without `:fast` or `:hard`, the router picks a default. Discovery runs only for hard/focus. If the default is “hard”, discovery applies; if “fast”, it does not. Not ambiguous but could be explicit.
+
+**Suggestion**: In SKILL-DISCOVERY or SKILL-ORCHESTRATION, one line: “When command has no variant, use the router’s default (e.g. hard for full workflows); discovery eligibility follows that variant.” Optional.
+
+### 6. Security (optional)
+
+**Issue**: Doc does not mention malicious or low-quality skill content. We already have: low-trust → confirm; recommend trusted sources (e.g. vercel-labs/agent-skills).
+
+**Suggestion**: Short note: “Skills execute in agent context. For production, prefer skills from trusted sources; user confirmation is required for low-trust, task-critical installs.” Optional.
+
+---
+
+## What Is Already Production-Ready
+
+- **Decision logic**: Variant + fitness gates are deterministic and implementable.
+- **Install flow**: Commands, scope (current tool), and confirm rules are clear.
+- **Fallbacks**: Timeout, no skills, install failure are handled.
+- **Config**: _index.yaml has discovery on/off, thresholds, variants, promotion; per-agent overrides exist.
+- **Cross-doc alignment**: Thresholds (0.75, 0.8), variant list (hard, focus), and flow (blocking vs async) match across docs and config.
+
+---
+
+## Recommended Doc Updates (Applied)
+
+1. **SKILL-ORCHESTRATION.md**
+   - Clarify principle “non_blocking_discovery” so blocking path (fitness < 0.75) is explicit.
+   - Add edge case: “find-skills not installed or discovery unavailable → proceed with matrix only, optional message.”
+
+2. **BOOTSTRAP.md**
+   - Add SKILL-DISCOVERY.md to the reference table (or note “HSOL = SKILL-DISCOVERY + SKILL-ORCHESTRATION”) so both files are loaded when implementing HSOL.
+
+3. **Optional (not applied)**
+   - _dynamic.yaml: one line on who updates it (CLI/post-install).
+   - Default variant sentence in Discovery or Orchestration.
+   - One-sentence security note in Orchestration.
+
+---
+
+## Conclusion
+
+HSOL is **ready for production use** as a specification: logic is complete, consistent, and sufficient for agents and orchestrators to resolve skills intelligently (matrix-first, dynamic when needed, blocking when matrix is insufficient). The suggested updates are small clarifications and one extra fallback; they improve robustness and discoverability without changing behavior.