From 2182cc00a5b5f0397bec58b237bdfd6633dd8145 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 22 Jul 2026 03:44:42 +1000 Subject: [PATCH] =?UTF-8?q?refactor:=20replace=20hardcoded=20workflow?= =?UTF-8?q?=E2=86=92skill=20maps=20with=20catalog-driven=20lookup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../SKILL.md | 0 .../SKILL.md | 0 .../SKILL.md | 0 .../SKILL.md | 0 .../{tdd-bugfix => archie-wf-tdd}/SKILL.md | 3 +- internal/agentexec/skill_test.go | 7 +- internal/agentexec/worker.go | 22 +- internal/skill/catalog_test.go | 211 ++++++++++++++++++ internal/skill/skill.go | 76 ++++++- internal/workflow/agent.go | 28 +-- internal/workflow/plugin_test.go | 3 +- 11 files changed, 312 insertions(+), 38 deletions(-) rename .agents/skills/{go-quality-gate => archie-wf-go-gate}/SKILL.md (100%) rename .agents/skills/{ecosystem-node => archie-wf-node}/SKILL.md (100%) rename .agents/skills/{ecosystem-python => archie-wf-python}/SKILL.md (100%) rename .agents/skills/{security-audit => archie-wf-security}/SKILL.md (100%) rename .agents/skills/{tdd-bugfix => archie-wf-tdd}/SKILL.md (98%) create mode 100644 internal/skill/catalog_test.go diff --git a/.agents/skills/go-quality-gate/SKILL.md b/.agents/skills/archie-wf-go-gate/SKILL.md similarity index 100% rename from .agents/skills/go-quality-gate/SKILL.md rename to .agents/skills/archie-wf-go-gate/SKILL.md diff --git a/.agents/skills/ecosystem-node/SKILL.md b/.agents/skills/archie-wf-node/SKILL.md similarity index 100% rename from .agents/skills/ecosystem-node/SKILL.md rename to .agents/skills/archie-wf-node/SKILL.md diff --git a/.agents/skills/ecosystem-python/SKILL.md b/.agents/skills/archie-wf-python/SKILL.md similarity index 100% rename from .agents/skills/ecosystem-python/SKILL.md rename to .agents/skills/archie-wf-python/SKILL.md diff --git a/.agents/skills/security-audit/SKILL.md b/.agents/skills/archie-wf-security/SKILL.md similarity index 100% rename from .agents/skills/security-audit/SKILL.md rename to .agents/skills/archie-wf-security/SKILL.md diff --git a/.agents/skills/tdd-bugfix/SKILL.md b/.agents/skills/archie-wf-tdd/SKILL.md similarity index 98% rename from .agents/skills/tdd-bugfix/SKILL.md rename to .agents/skills/archie-wf-tdd/SKILL.md index f087b41f2..e0729df9b 100644 --- a/.agents/skills/tdd-bugfix/SKILL.md +++ b/.agents/skills/archie-wf-tdd/SKILL.md @@ -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 diff --git a/internal/agentexec/skill_test.go b/internal/agentexec/skill_test.go index f33a1772b..9daf927f5 100644 --- a/internal/agentexec/skill_test.go +++ b/internal/agentexec/skill_test.go @@ -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 { diff --git a/internal/agentexec/worker.go b/internal/agentexec/worker.go index 8226b4ab8..45e816bd5 100644 --- a/internal/agentexec/worker.go +++ b/internal/agentexec/worker.go @@ -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 { diff --git a/internal/skill/catalog_test.go b/internal/skill/catalog_test.go new file mode 100644 index 000000000..63d2d268e --- /dev/null +++ b/internal/skill/catalog_test.go @@ -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") + } +} diff --git a/internal/skill/skill.go b/internal/skill/skill.go index 588eca6ba..692157403 100644 --- a/internal/skill/skill.go +++ b/internal/skill/skill.go @@ -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 { diff --git a/internal/workflow/agent.go b/internal/workflow/agent.go index e01a53dfa..a03724389 100644 --- a/internal/workflow/agent.go +++ b/internal/workflow/agent.go @@ -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 } + diff --git a/internal/workflow/plugin_test.go b/internal/workflow/plugin_test.go index b853a1af7..37f5e4264 100644 --- a/internal/workflow/plugin_test.go +++ b/internal/workflow/plugin_test.go @@ -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 {