refactor: replace hardcoded workflow→skill maps with catalog-driven lookup

Skills now declare their workflow in metadata.archie.workflow.
Catalog() scans frontmatter only (lazy, Tier 1). SkillForWorkflow()
derives the skill directory from the catalog — no hardcoded maps.

Removed workflowToSkill map (agent.go) and workflowToSkillDir switch
(worker.go). Both daemon and agent use the same catalog-based lookup.

Skills renamed to archie-wf-* convention. SKILL.md files updated with
workflow metadata field.

Progressive disclosure Tier 1: Catalog() returns name+description
+workflow. Tier 2: LoadBody() loads full body on activation.
This commit is contained in:
sam committed 2026-07-22 03:44:42 +10:00
1 parent d3c843e8f5
commit 2182cc00a5
11 files changed
+312 -38

No files matched your search

@@ -1,5 +1,5 @@
---
name: tdd-bugfix
name: archie-wf-tdd
description: >
Fix bugs using test-driven development. Write a failing repro test first, prove
it captures the bug, then fix the code without touching the tests. archie-core
@@ -9,6 +9,7 @@ metadata:
archie:
tools: [go, golangci-lint]
engine: any
workflow: tdd
---
# TDD Bugfix Workflow
+5 -2
View File
@@ -36,14 +36,17 @@ func TestHandleMessageLoadsSkillsFromWorktree(t *testing.T) {
// the Mission string. HandleMessage never touches .agents/skills/.
dir := t.TempDir()
skillsDir := filepath.Join(dir, ".agents", "skills", "tdd-bugfix")
skillsDir := filepath.Join(dir, ".agents", "skills", "archie-wf-tdd")
if err := os.MkdirAll(skillsDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(skillsDir, "SKILL.md"), []byte(`---
name: tdd-bugfix
name: archie-wf-tdd
description: TDD bugfix workflow
version: 1.0.0
metadata:
archie:
workflow: tdd
---
Analyse the bug. Write repro tests. Fix.
`), 0o644); err != nil {
+9 -13
View File
@@ -73,7 +73,7 @@ func HandleMessage(ctx context.Context, msg AgentRequestMessage, log *slog.Logge
// Load the skill body from the worktree — the agent owns skill
// loading per PRD section 1. Mirrors daemon-side loadSkillBody().
if msg.Workflow != "" && msg.Workspace != "" {
body := skill.LoadBody(msg.Workspace, workflowToSkillDir(msg.Workflow))
body := skill.LoadBody(msg.Workspace, skillDirForWorkflow(msg.Workspace, msg.Workflow))
if body != "" {
msg.Request.Mission = "Follow these project-specific guidelines:\n\n" + body + "\n\n---\n\n" + msg.Request.Mission
for i := range msg.Stages {
@@ -151,19 +151,15 @@ func runStages(ctx context.Context, runner Runner, msg AgentRequestMessage, chan
}, nil
}
// workflowToSkillDir maps a workflow name to the skill directory name.
// Mirrors the mapping in internal/workflow/agent.go.
func workflowToSkillDir(workflow string) string {
switch workflow {
case "tdd":
return "tdd-bugfix"
case "implement":
return "implement"
case "feasibility":
return "feasibility"
default:
return workflow
// skillDirForWorkflow finds the skill directory for a workflow from the
// workspace catalog. Skills declare their workflow in metadata.archie.workflow.
func skillDirForWorkflow(workspace, workflow string) string {
catalog, _ := skill.Catalog(workspace)
entry := skill.SkillForWorkflow(catalog, workflow)
if entry == nil {
return ""
}
return entry.Dir
}
func decodeOne(r io.Reader, value any) error {
+211
View File
@@ -0,0 +1,211 @@
package skill
import (
"os"
"path/filepath"
"strings"
"testing"
)
// ── progressive disclosure: catalog tier ─────────────────────────────
func TestCatalogReturnsNameAndDescriptionOnly(t *testing.T) {
// Catalog tier (~100 tokens per skill): name + description loaded at
// daemon startup. Full body is Tier 2, loaded on skill activation.
// Currently Discover() returns the full Skill (frontmatter + body).
// Catalog() must return only the catalog entries without bodies.
dir := t.TempDir()
skillsDir := filepath.Join(dir, ".agents", "skills", "archie-wf-tdd")
if err := os.MkdirAll(skillsDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(skillsDir, "SKILL.md"), []byte(`---
name: archie-wf-tdd
description: TDD bugfix workflow — reproduce, prove, fix.
version: 1.0.0
metadata:
archie:
tools: [go]
engine: any
---
This is the full SKILL.md body with detailed stage instructions.
It should NOT appear in the catalog entry.
`), 0o644); err != nil {
t.Fatal(err)
}
entries, err := Catalog(dir)
if err != nil {
t.Fatal(err)
}
if len(entries) != 1 {
t.Fatalf("got %d catalog entries, want 1", len(entries))
}
e := entries[0]
if e.Name != "archie-wf-tdd" {
t.Errorf("Name = %q, want archie-wf-tdd", e.Name)
}
if e.Description == "" {
t.Error("Description is empty — catalog must include the description")
}
if strings.Contains(e.Description, "full SKILL.md body") {
t.Error("Catalog entry contains the body text. " +
"Catalog must only contain name + description (~100 tokens). " +
"The full body is Tier 2, loaded on skill activation.")
}
// The full body must still be available via LoadBody.
body := LoadBody(dir, "archie-wf-tdd")
if !strings.Contains(body, "full SKILL.md body") {
t.Error("LoadBody did not return the full body. " +
"Catalog and LoadBody must be separate tiers: " +
"Catalog = name+description (startup), LoadBody = full SKILL.md (activation).")
}
}
func TestCatalogMissingDirReturnsEmpty(t *testing.T) {
entries, err := Catalog(t.TempDir())
if err != nil {
t.Fatal(err)
}
if entries != nil {
t.Errorf("expected nil for missing dir, got %v", entries)
}
}
// ── archie-wf-* naming convention ────────────────────────────────────
func TestSkillsUseArchiewfNaming(t *testing.T) {
// PRD section 5: skills follow archie-wf-* naming convention.
// The directory name must match the workflow: tdd→archie-wf-tdd,
// implement→archie-wf-implement, feasibility→archie-wf-feasibility.
//
// Currently skill directories are named tdd-bugfix, ecosystem-node, etc.
dir := t.TempDir()
skills := map[string]string{
"archie-wf-tdd": "TDD bugfix workflow",
"archie-wf-implement": "Implement workflow",
"archie-wf-feasibility": "Feasibility workflow",
}
for name, desc := range skills {
skillDir := filepath.Join(dir, ".agents", "skills", name)
if err := os.MkdirAll(skillDir, 0o755); err != nil {
t.Fatal(err)
}
content := `---
name: ` + name + `
description: ` + desc + `
version: 1.0.0
---
Body.
`
if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644); err != nil {
t.Fatal(err)
}
}
entries, err := Catalog(dir)
if err != nil {
t.Fatal(err)
}
if len(entries) != 3 {
t.Fatalf("got %d catalog entries, want 3", len(entries))
}
for _, e := range entries {
if !strings.HasPrefix(e.Name, "archie-wf-") {
t.Errorf("skill %q does not follow archie-wf-* naming convention. "+
"Per PRD section 5, all workflow skills must use the archie-wf-* prefix.", e.Name)
}
}
}
// ── CatalogEntry type ────────────────────────────────────────────────
func TestCatalogEntryHasRequiredFields(t *testing.T) {
// CatalogEntry must have Name, Description, and a way to load the
// full body on activation.
e := CatalogEntry{Name: "archie-wf-tdd", Description: "TDD workflow"}
if e.Name == "" || e.Description == "" {
t.Error("CatalogEntry must have non-empty Name and Description")
}
}
// ── bundled plugin demo skill ────────────────────────────────────────
func TestBundledPluginSkillIsDiscoverableAndRunnable(t *testing.T) {
// A skill must be able to ship bundled Yaegi plugins in its plugins/
// directory. DiscoverPlugins finds them, Plugin.Run executes them.
dir := t.TempDir()
skillsDir := filepath.Join(dir, ".agents", "skills", "archie-wf-tdd")
pluginsDir := filepath.Join(skillsDir, "plugins")
if err := os.MkdirAll(pluginsDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(skillsDir, "SKILL.md"), []byte(`---
name: archie-wf-tdd
description: TDD bugfix workflow with security checks
version: 1.0.0
metadata:
archie:
tools: [go, golangci-lint]
engine: any
plugins:
- plugins/security-check.go
---
Full body content.
`), 0o644); err != nil {
t.Fatal(err)
}
// Write the bundled plugin.
if err := os.WriteFile(filepath.Join(pluginsDir, "security-check.go"), []byte(`package main
import "strings"
func Run(input string) string {
if strings.Contains(input, "TODO") {
return "found TODO"
}
return "clean"
}
`), 0o644); err != nil {
t.Fatal(err)
}
// Discover the skill — must include plugins.
skills, err := Discover(dir)
if err != nil {
t.Fatal(err)
}
if len(skills) != 1 {
t.Fatalf("got %d skills, want 1", len(skills))
}
s := skills["archie-wf-tdd"]
if len(s.Plugins) != 1 {
t.Fatalf("skill has %d plugins, want 1 — Discover() must populate Plugins", len(s.Plugins))
}
if s.Plugins[0].Name != "security-check" {
t.Errorf("plugin name = %q, want security-check", s.Plugins[0].Name)
}
// The plugin must be runnable.
out, err := s.Plugins[0].Run("code with TODO")
if err != nil {
t.Fatal(err)
}
if out != "found TODO" {
t.Errorf("plugin output = %q, want 'found TODO'", out)
}
// The frontmatter must declare the plugin.
if s.Frontmatter.Metadata.Archie == nil || len(s.Frontmatter.Metadata.Archie.Plugins) != 1 {
t.Error("Frontmatter.Metadata.Archie.Plugins is empty — " +
"the SKILL.md must declare bundled plugins in the metadata.archie.plugins list")
}
}
+73 -3
View File
@@ -20,13 +20,83 @@ type Frontmatter struct {
Version string `yaml:"version"`
Metadata struct {
Archie *struct {
Tools []string `yaml:"tools"`
Engine string `yaml:"engine"`
Plugins []string `yaml:"plugins,omitempty"`
Tools []string `yaml:"tools"`
Engine string `yaml:"engine"`
Plugins []string `yaml:"plugins,omitempty"`
Workflow string `yaml:"workflow,omitempty"`
} `yaml:"archie"`
} `yaml:"metadata"`
}
// CatalogEntry is a lightweight skill reference — name + description
// only (~100 tokens). Loaded at daemon startup for skill discovery.
// The full body is loaded on activation via LoadBody. agentskills.io
// progressive disclosure Tier 1.
type CatalogEntry struct {
Name string
Description string
Workflow string // from metadata.archie.workflow — which workflow this skill handles
Dir string // skill directory name
}
// Catalog scans dir/.agents/skills/*/SKILL.md and returns catalog entries
// (Tier 1: name + description + workflow only). Only the frontmatter is
// parsed — full bodies are not loaded. Missing directory returns nil.
func Catalog(dir string) ([]CatalogEntry, error) {
skillsPath := filepath.Join(dir, skillsDir)
entries, err := os.ReadDir(skillsPath)
if os.IsNotExist(err) {
return nil, nil
}
if err != nil {
return nil, fmt.Errorf("read skills dir %s: %w", skillsPath, err)
}
var names []string
for _, e := range entries {
if e.IsDir() {
names = append(names, e.Name())
}
}
sort.Strings(names)
var out []CatalogEntry
for _, name := range names {
skillPath := filepath.Join(skillsPath, name, "SKILL.md")
data, err := os.ReadFile(skillPath)
if err != nil {
continue
}
fm, _, err := Parse(data)
if err != nil || fm == nil {
continue
}
wf := ""
if fm.Metadata.Archie != nil {
wf = fm.Metadata.Archie.Workflow
}
out = append(out, CatalogEntry{
Name: fm.Name,
Description: fm.Description,
Workflow: wf,
Dir: name,
})
}
return out, nil
}
// SkillForWorkflow returns the catalog entry whose Workflow field matches
// the given workflow name, or nil if no skill declares that workflow.
// Replaces hardcoded workflow→skill lookup tables.
func SkillForWorkflow(catalog []CatalogEntry, workflow string) *CatalogEntry {
for i := range catalog {
if catalog[i].Workflow == workflow {
return &catalog[i]
}
}
return nil
}
// Skill is a parsed SKILL.md file with its frontmatter, body, and any
// bundled Yaegi plugins found in the skill's plugins/ directory.
type Skill struct {
+10 -18
View File
@@ -202,28 +202,20 @@ func missionWithSkill(tc *TaskContext, mission string) string {
return "Follow these project-specific guidelines:\n\n" + tc.SkillBody + "\n\n---\n\n" + mission
}
// workflowToSkill maps a workflow name to the skill directory name.
var workflowToSkill = map[string]string{
"tdd": "tdd-bugfix",
"implement": "implement",
"feasibility": "feasibility",
}
// loadSkillBody loads the SKILL.md body and any bundled plugins for the
// current workflow from the worktree's .agents/skills/ directory. Returns ""
// if not found. Populates tc.SkillPlugins alongside tc.SkillBody.
// loadSkillBody loads the SKILL.md body and plugins for the current
// workflow from the worktree's .agents/skills/ directory. Skills declare
// their workflow in metadata.archie.workflow — no hardcoded mapping.
func loadSkillBody(tc *TaskContext) string {
skillDir, ok := workflowToSkill[tc.Task.Workflow]
if !ok {
catalog, _ := skill.Catalog(tc.Dir)
entry := skill.SkillForWorkflow(catalog, tc.Task.Workflow)
if entry == nil {
return ""
}
body := skill.LoadBody(tc.Dir, skillDir)
body := skill.LoadBody(tc.Dir, entry.Dir)
if body != "" && tc.SkillPlugins == nil {
// Load plugins lazily on first agent stage.
plugins, err := skill.DiscoverPlugins(tc.Dir, skillDir)
if err == nil {
tc.SkillPlugins = plugins
}
plugins, _ := skill.DiscoverPlugins(tc.Dir, entry.Dir)
tc.SkillPlugins = plugins
}
return body
}
+2 -1
View File
@@ -24,7 +24,7 @@ func TestSkillPluginsAvailableDuringStageExecution(t *testing.T) {
// accessible via the TaskContext.
dir := t.TempDir()
skillsDir := filepath.Join(dir, ".agents", "skills", "tdd-bugfix")
skillsDir := filepath.Join(dir, ".agents", "skills", "archie-wf-tdd")
pluginsDir := filepath.Join(skillsDir, "plugins")
if err := os.MkdirAll(pluginsDir, 0o755); err != nil {
t.Fatal(err)
@@ -39,6 +39,7 @@ metadata:
archie:
tools: [go]
engine: any
workflow: tdd
---
Analyse the bug, write repro tests, fix.
`), 0o644); err != nil {