feat(#1113): skills overhaul + .agents/ namespace adoption by nextlevelshit · Pull Request #1136 · re-cinq/wave

nextlevelshit · 2026-04-18T00:49:23Z

Summary

Two coupled moves per specs/1113-skills-agents-folder/plan.md:

Drop tessl-coupled skills system. Delete classifier, lockfile, publisher, and the tessl/bmad/openspec/speckit/github/url source adapters. Rebuild wave skills as four minimal subcommands (list/check/add/doctor) that scan the cross-tool detection paths and let each adapter lazy-load via its native skill tool.
Rename .wave/ → .agents/. Stake the orchestrator subfolder namespace (pipelines/personas/contracts/workspaces/output/artifacts/skills) under the .agents/ standard already used natively by opencode/gemini/codex.

Net delta: ~−7000 LoC (8 internal/skill files + 1000-LoC skills.go + 2 docs guides + 14 tessl test files removed; replaced by ~440 LoC minimal CLI + 100 LoC adapter helper + 4 smoke pipelines).

Pre-1.0 per versioning policy: no migration shim, no back-compat.

Milestone commits

refactor(layout): rename .wave/ → .agents/ for cross-tool convention
refactor(skills): drop singular wave skill alias
refactor(skills): drop tessl/lockfile/publish/classify, rebuild CLI minimal
feat(adapter): native skill provisioning for all 4 adapters
feat(pipeline): step-level skills declaration
test(skills): smoke pipelines + step-level integration tests
docs(skills): rewrite for adapter-native lazy-loading model

Adapter native loading

Adapter	Workspace target	Native invocation
claude	`<ws>/.claude/skills/<name>/`	`Skill` tool
opencode	`<ws>/.agents/skills/<name>/`	`skill` tool
gemini	`<ws>/.agents/skills/<name>/`	`activate_skill` tool
codex	`<ws>/.agents/skills/<name>/`	`/skills` command

Shared internal/adapter/ProvisionSkills enforces workspace-scope panic guard, drops .wave-managed sentinel, only removes sentinel-tagged dirs on re-provision (preserves user-committed skills in worktrees).

CLI surface

wave skills list     # scan all detection paths, show name+desc+source+used-by
wave skills check    # validate one skill, show pipelines using it
wave skills add      # install from local path or file:// (+ --project flag)
wave skills doctor   # diagnose duplicates, malformed, deprecated .wave/skills/

Detection: .agents/skills/, .claude/skills/, .opencode/skills/, .gemini/skills/ then ~/.agents/skills/, ~/.claude/skills/, ~/.config/opencode/skills/, ~/.gemini/skills/. First match wins per name.

Pipeline integration

Step-level skills: declaration is now first-class:

```yaml
steps:

id: implement
persona: craftsman
skills: [golang, gh-cli]
```

Preflight aggregates union of pipeline.Skills + steps[].skills, validates each against the discovery store, and emits a hint suggesting wave skills add for any missing reference.

Test plan

Out of scope (per plan)

Onboarding wizard ecosystem cleanup (drops tessl/bmad/openspec/speckit) — follow-up, current ecosystem entries dead-code but compile-clean
wave migrate — not needed (single-user repo, pre-1.0)
Upstream RFC at agentsmd/agents.md — file after merge

Closes #1113.
Closes #1118.
Closes #1120.

Stake claim on .agents/ orchestrator subfolder namespace before competitors. .agents/skills/ already de facto standard via opencode, gemini, codex. Wave moves first on pipelines/personas/contracts/ workspaces/output/artifacts. Upstream RFC to follow. Mechanical rename: - .wave/{pipelines,personas,contracts,skills,docs,prompts,schemas, bench/results} via git mv (committed assets) - .wave/{workspaces,output,artifacts,chat,logs,retros,traces, bench/{datasets,workspaces},state.db*,wave.db*} as ignored runtime - All literals .wave/ → .agents/ across go/md/yaml/yml/json/html/css/js - .gitignore patterns updated - Bare ".wave" string literals updated where present wave.yaml stays at project root. ~/.config/wave/ user-global config unchanged (not project-level concern). Pre-1.0 per versioning policy: no migration shim, no back-compat detection. Refs #1113

All routes go through plural `wave skills` per clig.dev collection convention. Part of #1113 skills overhaul.

…inimal Delete tessl/bmad/openspec/speckit/github/url source adapters and the classifier, lockfile, and publish subsystems they fed. Trim NewDefaultRouter to file-only (the remaining install path). Replace `wave skills` (8 subcommands) with the minimal four: list — scan all detection paths, show name+desc+source+used-by check — validate one skill, show resolved path + pipelines using it add — install from local path or file:// URL (default ~/.agents/skills/, --project for .agents/skills/) doctor — diagnose duplicates, malformed frontmatter, deprecated .wave/ Detection paths now cover the cross-tool standard: project: .agents/skills, .claude/skills, .opencode/skills, .gemini/skills user: ~/.agents/skills, ~/.claude/skills, ~/.config/opencode/skills, ~/.gemini/skills Net delta: cmd/wave/commands/skills.go 1000→440 LoC, internal/skill -2200 LoC. Part of #1113 skills overhaul.

Wave now provisions resolved skills into the path each adapter natively scans, so all four agents (claude, opencode, gemini, codex) lazy-load skills via their built-in skill tool — no Wave-side prompt injection. Targets per adapter: - claude → <workspace>/.claude/skills/<name>/ - opencode → <workspace>/.agents/skills/<name>/ - gemini → <workspace>/.agents/skills/<name>/ - codex → <workspace>/.agents/skills/<name>/ Shared helper `internal/adapter/ProvisionSkills` enforces: - workspace-scope assertion (panic if target resolves outside workspace, guards against config tampering or path traversal) - `.wave-managed` sentinel file written alongside each provisioned skill - only sentinel-tagged dirs removed on re-provision; user-committed skills in worktree checkouts are preserved Replaces the previous opencode/gemini/codex stderr WARN that skills were declared but not injected (#1120 closed by this). Closes #1120. Part of #1113.

Steps may now declare `skills: [name, ...]` to scope skills at the agent run granularity (in addition to global, persona, and pipeline scopes). Step-level skills take highest precedence in the resolved skill set and are provisioned into the adapter workspace at step start. Preflight aggregates the union of pipeline.Skills and steps[].skills, validates each against the configured skill store, and emits a hint suggesting `wave skills add` for any missing reference. Part of #1113.

Ship four wave-smoke-skills-* pipelines (one per adapter) that exercise adapter-native skill provisioning end-to-end: - wave-smoke-skills-claude (Skill tool) - wave-smoke-skills-opencode (skill tool) - wave-smoke-skills-gemini (activate_skill tool) - wave-smoke-skills-codex (/skills command) Each declares step-level `skills: [wave-smoke-test]` and instructs the agent to activate the fixture skill and emit the sentinel string SMOKE_TEST_OK_4f7a2b1c. Pipelines are nightly/manual — they require real adapter binaries and API keys. Add fixture skill .agents/skills/wave-smoke-test/SKILL.md. PR-gated coverage: - TestSkillProvisioningIntegration/step_level_skills_propagate_to_adapter_config asserts step.Skills reach AdapterRunConfig.ResolvedSkills via mock adapter. - TestSkillProvisioningIntegration/step_level_skills_fail_preflight_when_missing asserts preflight fails with `wave skills add` hint when a step references an unknown skill. Part of #1113.

- docs/reference/cli.md: replace `wave skill` (singular) section with the new `wave skills` four-subcommand surface (list/check/add/doctor) plus detection-path reference. - docs/guide/skills.md: drop tessl-era install instructions, document per-adapter workspace targets, sentinel file behavior, and the new step-level `skills:` declaration. - docs/guide/skill-ecosystems.md: deleted (tessl/bmad/openspec/speckit ecosystems removed in this PR). - docs/guide/skill-configuration.md: deleted (tessl-coupled requires.skills install/check schema removed). - docs/.vitepress/config.ts: prune the deleted guide entries. - docs/reference/manifest-schema.md: drop `skill_publish_seconds`. - README.md: collapse two skill-command rows into the single new entry. - internal/webui/handlers_test.go: refresh fixture from `wave skill install` to `wave skills add`. Part of #1113.

PR #1136 renamed the project config dir .wave/ → .agents/ but missed inline path strings inside pipeline YAML (schema_path, path:, hook commands, embedded bash heredocs), contract criteria, a docs example, and the schema_path field on contract blocks across ~80 files. Symptom: ops-hello-world (and every pipeline using json_schema contracts) failed with: contract validation failed [json_schema]: failed to read schema file: .wave/contracts/smoke-review.schema.json open .wave/contracts/smoke-review.schema.json: no such file Fix: bulk sed `\.wave/` → `.agents/` across *.yaml, *.yml, *.json, *.go, *.md under .agents/pipelines/, .agents/contracts/, internal/, cmd/, docs/. Excluded .agents/output/ (historical artifacts/logs). Preserved two intentional `.wave/` mentions in cmd/wave/commands/skills.go where `wave skills doctor` detects a leftover `.wave/skills/` dir and reports a migration hint; tests updated accordingly. Verified: `go test ./...` green.

nextlevelshit added 8 commits April 18, 2026 02:04

refactor(skills): drop singular wave skill alias

e8c11bf

All routes go through plural `wave skills` per clig.dev collection convention. Part of #1113 skills overhaul.

fix(skills): drop wastedassign in runSkillsAdd target init

a73886d

nextlevelshit merged commit 139e3ab into main Apr 18, 2026
4 checks passed

nextlevelshit deleted the feat/1113-skills-and-agents-folder branch April 18, 2026 01:57

This was referenced Apr 18, 2026

refactor(onboarding): drop tessl-coupled skill wizard step #1137

Merged

fix(smoke): adapter-portable wave-smoke-skills-* contracts #1138

Merged

nextlevelshit mentioned this pull request Apr 18, 2026

fix: replace leftover .wave/ references with .agents/ #1139

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(#1113): skills overhaul + .agents/ namespace adoption#1136

feat(#1113): skills overhaul + .agents/ namespace adoption#1136
nextlevelshit merged 8 commits intomainfrom
feat/1113-skills-and-agents-folder

nextlevelshit commented Apr 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

nextlevelshit commented Apr 18, 2026

Summary

Milestone commits

Adapter native loading

CLI surface

Pipeline integration

Test plan

Out of scope (per plan)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant