@goondocks/myco 0.17.2 → 0.18.1

package/dist/src/agent/definitions/tasks/skill-evolve.yaml

@@ -1,18 +1,18 @@
 name: skill-evolve
 displayName: Skill Evolution
 description: >-
-  Evaluate and evolve existing Myco-managed skills based on new
-  vault knowledge. Only assesses skills with new knowledge since
-  their last assessment, throttled to once per assess_interval_hours.
+  Evaluate and evolve existing Myco-managed skills. Assesses content
+  freshness, identifies merge and narrowness opportunities, and
+  autonomously consolidates the skill inventory.
 agent: myco-agent
 prompt: >-
-  Assess and update skills that have new knowledge since their last
-  assessment. The instruction contains pre-filtered skills with their
-  current content and new spore IDs.
+  Assess and evolve skills that have new knowledge or structural
+  overlap. The instruction contains pre-filtered skills with their
+  content, new spore IDs, and pre-computed similarity analysis.
 isDefault: false
 model: claude-sonnet-4-6
-maxTurns: 40
-timeoutSeconds: 1200
+maxTurns: 48
+timeoutSeconds: 1800
 schedule:
   enabled: false
   intervalSeconds: 900
@@ -21,75 +21,161 @@ schedule:
   preCondition: has-active-skills
 params:
   assess_interval_hours: 24
-  max_skills_per_run: 5
+  max_skills_per_run: 8
 phases:
-  - name: assess
+  - name: inventory
+    model: claude-haiku-4-5-20251001
     prompt: |
-      The instruction contains skills that have new knowledge since
-      their last assessment. For each skill listed:
-
-      1. Read the new spores: fetch each ID from new_spore_ids via
-         vault_spores. Understand what changed.
-
-      2. Verify code references: use vault_search_fts to check 3-5
-         key file paths and function names from the skill content.
-         Are they still valid? This is bounded — check specific
-         claims, do not search broadly.
+      The instruction contains pre-computed structural analysis of
+      all active skills. Two mechanical signals are provided:
+
+      1. **Narrow skills** — skills with <2 H2 sections are flagged
+         as mechanically narrow. These are NOT broad enough for
+         standalone domain status.
+
+      2. **Overlap pairs** — skill pairs with similar descriptions
+         OR overlapping H2 headings are flagged with scores.
+
+      ## Your job: validate and assign targets
+
+      For each **mechanically narrow** skill:
+      - Confirm it is genuinely narrow (not a false positive, e.g.,
+        a debugging playbook with one long section is not narrow).
+      - Identify which broader skill it should be absorbed into.
+        Look at the heading lists to find the best domain match.
+
+      For each **overlap pair**:
+      - Confirm the overlap is real (not just shared vocabulary).
+      - If real, decide merge direction: which skill is the target
+        (broader, higher generation) and which is the source.
+
+      If no skills are flagged as narrow and no overlap pairs exist,
+      skip to storing an empty analysis.
+
+      ## Store results
+
+      Store via vault_set_state (key: skill-evolve-inventory) as:
+      {
+        "merge_candidates": [
+          { "source": "skill-name-a", "target": "skill-name-b",
+            "reason": "..." }
+        ],
+        "narrow_candidates": [
+          { "skill": "skill-name", "absorb_into": "broader-skill",
+            "reason": "..." }
+        ]
+      }
+
+      Only override the mechanical signals when you have clear
+      evidence that the flag is wrong. The default is to act on
+      the mechanical flags, not to find reasons to keep everything.
 
-      3. Classify:
-         - CURRENT — new knowledge doesn't affect this skill's procedures
-         - STALE — new knowledge changes a specific step, path, or gotcha.
-           Note exactly WHAT is new.
-         - DEPRECATED — key code references are gone or the procedure
-           is no longer relevant. Note what's missing.
-
-      Bias toward CURRENT. A skill that is 90% accurate is better
-      left alone than rewritten with the risk of losing detail.
+      If the instruction says "No skills need assessment", report
+      skip via vault_report and finish.
+    tools:
+      - vault_skill_records
+      - vault_set_state
+      - vault_report
+    maxTurns: 8
+    required: true
+    readOnly: true
 
-      4. Update the skill's properties with the new watermark:
+  - name: assess
+    model: claude-sonnet-4-6
+    prompt: |
+      Read the inventory analysis from vault_state
+      (key: skill-evolve-inventory).
+
+      There are TWO sources of skills to assess:
+
+      **A. Skills with new knowledge** — listed in the instruction
+      with descriptions and new spore IDs (full content is NOT in
+      the instruction — read it on-demand). For each:
+      1. Read new spores via vault_spores. Understand what changed.
+      2. Only if the new spores suggest a procedural change, read
+         the skill's full content via vault_skill_records (action:
+         get, id: "<name>") and verify 2-3 code references via
+         vault_search_fts. Skip content reads for skills where
+         the new spores are clearly unrelated.
+      3. Check the inventory analysis: is this skill also flagged
+         for merge or narrowness?
+
+      **B. Inventory-flagged skills** — merge_candidates and
+      narrow_candidates from the inventory analysis. These may NOT
+      appear in the instruction (they may have no new knowledge).
+      For each flagged skill not already covered above:
+      1. Read its content via vault_skill_records (action: get).
+      2. Verify the inventory's merge/narrow recommendation by
+         reading both skills' content.
+
+      For ALL skills from both sources, classify with one of:
+         - CURRENT — still accurate, no changes needed.
+         - STALE — new knowledge changes specific steps, paths,
+           or gotchas. Note exactly WHAT is new.
+         - DEPRECATED — key code references are gone or the
+           procedure is no longer relevant. Note what's missing.
+         - MERGE — overlaps significantly with another skill
+           (from inventory analysis). Note the TARGET skill to
+           merge into.
+         - NARROW — too specific for standalone status (from
+           inventory analysis). Note the BROADER skill to absorb
+           into.
+
+         Bias toward CURRENT. A skill that is 90% accurate is
+         better left alone than rewritten with risk of losing detail.
+         Only classify MERGE/NARROW when the inventory analysis
+         supports it AND you agree after reading the content.
+
+      5. Update the skill's properties with the new watermark:
          vault_skill_records (action: update, id: <skill_id>,
-         properties: '{"last_assessed_at": <now>, "knowledge_watermark": <now>, "last_classification": "<classification>"}')
+         properties: '{"last_assessed_at": <now>,
+         "knowledge_watermark": <now>,
+         "last_classification": "<classification>"}')
 
-      5. Store classifications via vault_set_state
-         (key: skill-evolve-classifications) as JSON.
+      6. Store classifications via vault_set_state
+         (key: skill-evolve-classifications) as JSON:
+         [{ "skill_id": "...", "name": "...",
+            "classification": "...",
+            "target_skill": "..." (for MERGE/NARROW),
+            "details": "..." }]
 
       Report via vault_report.
 
-      If the instruction says "No skills need assessment", report
-      skip via vault_report and finish immediately.
+      If the instruction says "No skills need assessment" AND the
+      inventory has no merge/narrow candidates, report skip via
+      vault_report and finish.
     tools:
       - vault_spores
       - vault_search_fts
       - vault_skill_records
       - vault_set_state
       - vault_report
-    maxTurns: 20
+    maxTurns: 18
     required: true
+    dependsOn:
+      - inventory
 
-  - name: evolve
+  - name: act
+    model: claude-haiku-4-5-20251001
     prompt: |
       Read classifications from vault_state
       (key: skill-evolve-classifications). Parse the JSON.
 
-      For each skill classified as STALE or DEPRECATED:
+      For each classified skill, take the appropriate action:
+
+      ## CURRENT — No action. Skip.
 
       ## STALE — Targeted update
 
       1. Read the current skill content from vault_skill_records
          (action: get).
-
       2. START from the existing content as-is. Copy it verbatim.
-         Then make ONLY the specific changes needed — insert new
-         sections, update incorrect facts, add missing steps.
-
+         Then make ONLY the specific changes needed.
          The diff between old and new should be MINIMAL.
-
-         Protected frontmatter rules (vault_write_skill enforces
-         these and will REJECT writes that violate them):
+         Protected frontmatter rules (enforced by vault_write_skill):
          - user-invocable: copy EXACT value from existing skill
          - allowed-tools: copy EXACT value from existing skill
          - description: do not shorten (>10% reduction is rejected)
-
       3. Write via vault_write_skill with a rationale explaining
          what specifically changed.
 
@@ -98,17 +184,45 @@ phases:
       1. vault_skill_records (action: update, status: retired)
       2. vault_skill_records (action: delete)
 
-      ## CURRENT — No action. Skip.
+      ## MERGE — Absorb into target skill
+
+      1. Read BOTH skills' full content from vault_skill_records
+         (action: get) — the source and the target.
+      2. Write MERGED content to the TARGET skill via
+         vault_write_skill. The merged skill should:
+         - Keep the target skill's name and frontmatter
+         - Incorporate the source skill's procedures as new sections
+         - Preserve all concrete file paths, code patterns, and
+           gotchas from both skills
+         - Have a coherent structure (not just concatenation)
+         Protected frontmatter rules apply to the target.
+      3. Rationale should explain: "Merged <source> into <target>:
+         <what was added>."
+      4. Delete the SOURCE skill: vault_skill_records (action: delete)
+         This cascades (lineage, usage, linked candidates).
+
+      ## NARROW — Absorb into broader skill
+
+      Same as MERGE: read both, write merged content to the broader
+      skill, delete the narrow one. The narrow skill becomes a section
+      within the broader skill.
+
+      ## Important
+
+      - Process MERGE/NARROW actions AFTER STALE updates, so you're
+        merging already-refreshed content.
+      - If vault_write_skill rejects a merge (e.g., dedup gate trips),
+        check the error and adjust content. If truly blocked, skip
+        and report the issue.
 
       Report all actions via vault_report.
     tools:
       - vault_write_skill
       - vault_skill_records
       - vault_skill_candidates
-      - vault_state
       - vault_search_fts
       - vault_report
-    maxTurns: 20
+    maxTurns: 18
     required: true
     dependsOn:
       - assess

package/dist/src/agent/definitions/tasks/skill-generate.yaml

@@ -33,34 +33,40 @@ phases:
       ---
       name: myco:kebab-case-name
       description: |
-        One paragraph that serves as the PRIMARY triggering mechanism.
-        Be explicit about when this skill activates. Include concrete
-        keywords, file names, and scenarios. Be somewhat pushy to
-        counter undertriggering — include "even if the user doesn't
-        explicitly ask for [topic]" language when appropriate.
+        One paragraph serving as the PRIMARY triggering mechanism.
+        Cover the full procedural domain — mention all the major
+        procedures this skill covers. Be explicit about when this
+        activates. Include "even if the user doesn't explicitly
+        ask for [topic]" language when appropriate.
       managed_by: myco
       user-invocable: true
       allowed-tools: Read, Edit, Write, Bash, Grep, Glob
       ---
 
-      # Skill Title
+      # Domain Title
 
-      Brief context paragraph (2-3 sentences) explaining what this
-      procedure accomplishes and when you'd use it.
+      Brief context paragraph (2-3 sentences) explaining the
+      procedural domain and when you'd use this skill.
 
       ## Prerequisites
 
-      What must be true before starting.
+      What must be true before starting any procedure in this domain.
 
-      ## Steps
+      ## Procedure A: [Name]
 
-      Numbered, concrete steps with file paths and code examples.
-      Each step should reference specific files in this project.
+      Steps for the first major procedure in this domain.
 
-      ## Common Pitfalls
+      ## Procedure B: [Name]
 
-      Inline with the steps where possible, or as a short section
-      at the end for cross-cutting gotchas.
+      Steps for the second major procedure.
+
+      ## Procedure C: [Name]
+
+      Steps for the third major procedure.
+
+      ## Cross-Cutting Gotchas
+
+      Pitfalls that span multiple procedures in this domain.
       ```
 
       ## Frontmatter Fields
@@ -79,21 +85,27 @@ phases:
 
       ## Writing Principles
 
+      - **This candidate represents a procedural domain** — a family
+        of related tasks that share prerequisite knowledge. The skill
+        should cover the full domain, not just a single procedure.
+      - **A well-scoped skill has 3-6 major sections**, each describing
+        a distinct procedure within the domain. If the candidate maps
+        to fewer than 2 sections, note this in the rationale — it may
+        be too narrow.
       - **Explain reasoning, not rigid rules.** "Because X, do Y"
-        is better than "ALWAYS do Y." Use theory of mind — the agent
-        using this skill is smart enough to understand WHY.
-      - **Stay under 500 lines.** Be concise but complete.
-      - **Use concrete file paths** from this project, not generic examples.
+        is better than "ALWAYS do Y." The agent using this skill
+        understands WHY.
+      - **Stay under 800 lines.** Be concise but complete.
+      - **Use concrete file paths** from this project.
       - **Include code patterns** where they help (inline code blocks).
       - **Include examples** — show input/output or before/after where
         it makes the procedure clearer.
-      - **Reference gotchas inline** where the developer would encounter
-        them, not in a separate section.
+      - **Reference gotchas inline** where the developer would
+        encounter them, not in a separate section.
       - **The description is the trigger.** An agent reading just the
-        description should know whether this skill applies to their task.
+        description should know whether this skill applies.
       - **Be general enough to survive change.** The skill should teach
-        the pattern, not just document the current state. If a file path
-        changes, the procedure should still make sense.
+        the pattern, not just document the current state.
 
       ## Tool Call
 
@@ -143,14 +155,19 @@ phases:
          function names, and code patterns from this project?
          Generic advice ("add a config file") is not enough.
 
-      4. **Length:** Under 500 lines?
+      4. **Length:** Under 800 lines?
+
+      5. **Domain scope:** Does this skill cover a procedural domain
+         (multiple related procedures as sections) or just a single
+         procedure? If single, flag as potentially too narrow. Count
+         the ## headings — expect 3-6 for a well-scoped domain skill.
 
-      5. **Conflicts:** Does it overlap with existing skills?
+      6. **Conflicts:** Does it overlap with existing skills?
          Use vault_skill_records (action: list) to check. The
          staging path's dedup gate already ran on your description;
          this is a sanity check on the procedural content itself.
 
-      6. **Accuracy:** Spot-check 2-3 specific claims against the
+      7. **Accuracy:** Spot-check 2-3 specific claims against the
          vault. Use vault_search_fts to verify file paths and
          function names mentioned in the skill.