Skip to content

Commit 8e5bc61

Browse files
MartenAngnerclaude
andauthored
fix(skills): remove Agent Space references + sync WDS May improvements
- Remove hardcoded Supabase URLs from start.md, wrap.md, handoff.md Handoffs now write to progress/[target_agent].md (file-based, no external dependency). Resumption via /[agent] progress/[agent].md. - Add src/data/wds-glossary.md — locked terminology for all agents - Add src/data/agent-contracts.md — domain boundaries, handoff rules, prerequisites, quality rules, out-of-scope per agent - Add src/data/shared-activation.md — common startup steps referenced by all agents instead of repeated inline - Fix src/tools/memory/SKILL.md: rename to wds-memory, remove WDS-E and external storage references Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 302a6d4 commit 8e5bc61

7 files changed

Lines changed: 276 additions & 98 deletions

File tree

src/data/agent-contracts.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# WDS Agent Contracts
2+
3+
Defines what each agent owns, what they explicitly do not own, and how they hand off to each other.
4+
All agents load this file at activation. These rules are non-negotiable.
5+
6+
---
7+
8+
## Domain Boundaries
9+
10+
| Agent | Owns | Does NOT own |
11+
|-------|------|--------------|
12+
| **Saga** | Phases 0–2: Alignment, Product Brief, Trigger Mapping | Any design work. Any code. Scenarios (Phase 3+). |
13+
| **Freya** | Phases 3–4: UX Scenarios, UX Design. Phases 6–7: Asset Generation, Design System. | Discovery (Phases 1–2). Any code. PRDs. |
14+
| **Mimir** | Phase 5: Tech Audit, PRD, Build. Phase 8: Product Evolution. | Discovery. Design. Writing specs without a Work Order. |
15+
16+
**If a user asks an agent to do work outside its domain:** name the right agent and offer to hand off. Never attempt the work yourself.
17+
18+
---
19+
20+
## Prerequisites
21+
22+
Each agent requires the following before starting core work:
23+
24+
| Agent | Required | Blocks |
25+
|-------|----------|--------|
26+
| Saga | Nothing ||
27+
| Freya | `A-Product-Brief/product-brief.md` + `B-Trigger-Map/00-trigger-map.md` | Cannot design without strategic foundation |
28+
| Mimir | At least one Work Order from Freya | Cannot build without a WO. Cannot PRD without a WO. |
29+
| Mimir (existing codebase) | `E-Development/000-tech-audit.md` | Cannot PRD without knowing the codebase |
30+
31+
---
32+
33+
## Handoff Rules
34+
35+
**Saga → Freya**
36+
Trigger: Product Brief and Trigger Map are complete and aligned.
37+
Action: Saga runs `/wrap freya`. Freya picks up with `/freya progress/freya.md`.
38+
Never: Saga does not write scenarios or design anything before handing off.
39+
40+
**Freya → Mimir**
41+
Trigger: Work Order written, page spec complete, ready for implementation.
42+
Action: Freya runs `/wrap mimir` or `/handoff mimir`. Mimir picks up the Work Order.
43+
Never: Freya does not write code. Freya does not write PRDs.
44+
45+
**Mimir → Freya**
46+
Trigger: Implementation complete, browser-verified. Or: blocked on design decision.
47+
Action: Mimir runs `/handoff freya` with the specific question or completion note.
48+
Never: Mimir does not modify specs or Work Orders. He implements what they say.
49+
50+
---
51+
52+
## Quality Rules (all agents)
53+
54+
- **One task at a time.** Complete and verify before moving on.
55+
- **No plausible-looking wrong output.** If you cannot follow the template exactly, stop and say so. Wrong-but-plausible output breaks every downstream phase.
56+
- **Read the template before writing.** Every artifact has a template. Load it, follow it.
57+
- **Decisions are documented.** Any deviation from a template or unexpected choice goes in the design log.
58+
59+
---
60+
61+
## Out-of-Scope (explicit)
62+
63+
Things no WDS agent does, ever:
64+
65+
- Produce output in a custom format when a WDS template exists
66+
- Write to `progress/` without going through the memory tool
67+
- Commit without a meaningful message (conventional commits required)
68+
- Force push, skip hooks, or bypass git safety
69+
- Start a new phase without the prerequisite documents
70+
- Write code without a PRD (Mimir only)
71+
- Mark a requirement done without browser verification (Mimir only)
72+
- Design without a Trigger Map (Freya only)

src/data/shared-activation.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# WDS Shared Activation Steps
2+
3+
Common startup sequence for all WDS agents (Saga, Freya, Mimir).
4+
Each agent's SKILL.md references this file instead of repeating these steps.
5+
6+
---
7+
8+
## Step: state
9+
10+
Check for session state via the memory tool.
11+
Read `~/.claude/wds/src/tools/memory/SKILL.md` and follow the `load` operation for the current agent_id.
12+
If state found: show resume prompt. Wait for user response before continuing.
13+
14+
---
15+
16+
## Step: scan
17+
18+
Scan workspace for WDS projects:
19+
- Find repos with `_progress/wds-project-outline.yaml` or `_progress/00-design-log.md`
20+
- Skip system repos (bmad-method-wds-expansion, whiteport-design-studio)
21+
- For each project: read design log, note phase status and in-progress work
22+
- Also check current directory for design process folders (A-Product-Brief/ through E-Development/) and any context documents at repo root
23+
24+
---
25+
26+
## Step: select
27+
28+
IF multiple projects found with open work:
29+
List them, ask which to work on.
30+
IF single project:
31+
Continue to agent-specific activation.
32+
33+
---
34+
35+
## Step: brownfield-detect
36+
37+
Check if the project has a codebase (src/, backend/, storefront/, app/, or similar code folders at repo root).
38+
IF codebase found → go to agent-specific brownfield handling.
39+
IF no codebase → continue to agent-specific greenfield flow.

src/data/wds-glossary.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# WDS Glossary
2+
3+
Locked terminology for all WDS agents. One definition per term — no synonyms, no aliases.
4+
Agents load this file once at activation. Do not redefine these terms locally.
5+
6+
---
7+
8+
## Phases
9+
10+
| Phase | Name | Owner |
11+
|-------|------|-------|
12+
| 0 | Alignment & Signoff | Saga |
13+
| 1 | Product Brief | Saga |
14+
| 2 | Trigger Mapping | Saga |
15+
| 3 | UX Scenarios | Freya |
16+
| 4 | UX Design | Freya |
17+
| 5 | Agentic Development | Mimir |
18+
| 6 | Asset Generation | Freya |
19+
| 7 | Design System | Freya |
20+
| 8 | Product Evolution | Mimir |
21+
22+
---
23+
24+
## Output Folder Structure
25+
26+
```
27+
{output_folder}/
28+
├── A-Product-Brief/ Phase 1 — strategic foundation
29+
├── B-Trigger-Map/ Phase 2 — user research & personas
30+
├── C-UX-Scenarios/ Phase 3 — journey flows
31+
├── D-UX-Design/ Phase 4 — page specifications & design assets
32+
└── E-Development/ Phase 5 — technical requirements, work orders, code
33+
```
34+
35+
Progress files (machine-local, not committed):
36+
```
37+
progress/
38+
├── [agent].md Session state per agent
39+
└── project-index.md Living artifact index, updated on wrap
40+
```
41+
42+
---
43+
44+
## Artifacts
45+
46+
### Strategy (Phase 1)
47+
- **Product Brief**`A-Product-Brief/product-brief.md`. Strategic foundation: vision, goals, constraints, target users. Required before any design work.
48+
- **Content Language**`A-Product-Brief/content-language.md`. Tone, vocabulary, brand voice.
49+
- **Visual Direction**`A-Product-Brief/visual-direction.md`. Aesthetic references, colour, typography intent.
50+
51+
### Research (Phase 2)
52+
- **Trigger Map**`B-Trigger-Map/00-trigger-map.md`. User psychology mapped to business goals. Required before UX Scenarios.
53+
- **Business Goals**`B-Trigger-Map/01-business-goals.md`. Measurable outcomes, KPIs.
54+
- **Persona**`B-Trigger-Map/NN-persona-[firstname]-the-[archetype].md`. Alliterative names required (e.g. Harriet the Hairdresser).
55+
- **Feature Impact**`B-Trigger-Map/feature-impact.md`. Feature × persona × trigger mapping.
56+
57+
### Design (Phases 3–4)
58+
- **UX Scenarios**`C-UX-Scenarios/00-ux-scenarios.md`. User journey flows derived from Trigger Map.
59+
- **Page Spec**`D-UX-Design/[page-name].md`. Per-page specification: layout, content, interactions, acceptance criteria.
60+
- **Design Tokens** — Extracted progressively during Phase 4, not upfront.
61+
62+
### Development (Phase 5)
63+
- **Tech Audit**`E-Development/000-tech-audit.md`. Living architecture document. Required before any PRD on an existing codebase.
64+
- **Master PRD**`E-Development/000-PRD.md`. Platform requirements, written once, updated as project evolves.
65+
- **Feature PRD**`E-Development/NNN-[feature].xml`. One per Work Order.
66+
- **Change Order**`E-Development/NNN-NN-[slug].xml`. Feedback/change against a parent PRD.
67+
- **Work Order**`E-Development/WO-NNN-[slug].md`. Task written by Freya for Mimir. Contains: objective, scope, files, acceptance criteria.
68+
- **Mimir Brief** — Narrative handoff document from Freya to Mimir when handing off design work.
69+
70+
### Progress (machine-local)
71+
- **Design Log**`_progress/00-design-log.md`. Project-wide progress, updated each session.
72+
- **Project Outline**`_progress/wds-project-outline.yaml`. Phase status, project metadata.
73+
- **Session State**`progress/[agent].md`. Agent-specific session state. Loaded by `/start`, written by `/wrap`.
74+
- **Project Index**`progress/project-index.md`. Living index of all artifacts, updated by `/wrap`.
75+
76+
---
77+
78+
## Patterns
79+
80+
- **Design Loop** — Freya's per-page cycle: discuss → spec → wireframe → approve → iterate → update spec → implement → browser review → extract tokens.
81+
- **Dream Up Mode** — Three modes for artifact generation: Dialog (collaborative), Suggest (agent proposes), Dream (agent generates fully). Selected at session start.
82+
- **Brownfield** — Project with an existing codebase. Triggers gap-map assessment before new work begins.
83+
- **Greenfield** — Project with no existing codebase. Follows standard phase progression.
84+
- **Gap Map** — Freya's cross-reference of what is designed vs what is built vs what has a Work Order.
85+
86+
---
87+
88+
## Model Selection
89+
90+
| Task type | Model |
91+
|-----------|-------|
92+
| Any code, build, deploy, implement | Opus |
93+
| High-stakes / production / compliance | Opus |
94+
| Long or complex multi-step tasks | Opus |
95+
| Strategy, spec, dialog, UX, analysis | Sonnet |
96+
| Simple, low-stakes, short | Haiku |
97+
98+
Default: lightest model that fits. Prefix Next actions with `MODEL:[Haiku|Sonnet|Opus]`.

src/skills/handoff.md

Lines changed: 27 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@ Pass a specific piece of work to another WDS agent. This is NOT a session wrap
55
**Usage:** `/handoff [target-agent]`
66
**Example:** `/handoff mimir`
77

8-
> **Handoffs go through Agent Space — never as files on disk.**
9-
> Agent Space is the single source of truth for cross-agent communication. If it's not available, fix connectivity — do not fall back to writing files.
10-
118
---
129

1310
<handoff-steps>
@@ -16,7 +13,7 @@ Pass a specific piece of work to another WDS agent. This is NOT a session wrap
1613
- Derive everything from the conversation. Do NOT ask questions.
1714
- Do NOT summarize this session. That is a wrap, not a handoff.
1815
- Focus only on what the receiving agent needs to start the specific task immediately.
19-
- The sub-agent handles Agent Space delivery. You only compile and show.
16+
- Handoff is written to `progress/[target_agent].md` — the receiving agent picks it up via `/start`.
2017
</constraints>
2118

2219
<step id="1-compile">
@@ -52,49 +49,43 @@ Pass a specific piece of work to another WDS agent. This is NOT a session wrap
5249
Then proceed immediately to step 3.
5350
</step>
5451

55-
<step id="3-subagent">
52+
<step id="3-write">
5653
Spawn a sub-agent with this exact prompt — substitute the bracketed values:
5754

5855
---
59-
You are a delivery agent. Your only job is to post a handoff to Agent Space and return the token.
60-
61-
Send this request:
62-
63-
```bash
64-
curl -s -X POST "https://uztngidbpduyodrabokm.supabase.co/functions/v1/agent-messages" \
65-
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InV6dG5naWRicGR1eW9kcmFib2ttIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI1MTc3ODksImV4cCI6MjA4ODA5Mzc4OX0.FNnTd5p9Qj3WeD0DxQORmNf2jgaVSZ6FU1EGy0W7MRo" \
66-
-H "Content-Type: application/json" \
67-
-d '{
68-
"action": "send",
69-
"from_agent": "[from_agent]",
70-
"to_agent": "[target_agent]",
71-
"project": "[project]",
72-
"message_type": "handoff",
73-
"title": "[one-line task description]",
74-
"content": "[full handoff content — escaped for JSON]"
75-
}'
56+
You are a handoff writer. Your only job is to save a handoff file via the memory tool.
57+
58+
**Step A — Save handoff via memory tool:**
59+
Read `~/.claude/wds/src/tools/memory/SKILL.md` and follow the `save` operation:
60+
- agent_id: [target_agent]
61+
- data:
7662
```
63+
## Wrapped
64+
[current date and time]
7765

78-
If the call succeeds: extract the `id` field. Return ONLY the first 6 characters. Nothing else.
79-
If the call fails or returns an error: return ONLY: FAILED: [error message or HTTP status]
80-
---
66+
## Context
67+
[task content from step 1]
8168

82-
Wait for the sub-agent response.
69+
## Next
70+
[next line from step 1]
8371

84-
**If sub-agent returns 6 characters:** print EXACTLY this — nothing before, nothing after:
85-
```
86-
/[target_agent] [6chars]
87-
```
72+
## Learned
73+
None
8874

89-
**If sub-agent returns FAILED:** stop and warn the user:
75+
## Spec Sync
76+
None
9077
```
91-
⚠️ Agent Space unreachable — handoff not sent.
92-
Check that Agent Space credentials are active (open Bitwarden → verify Agent Space API key).
9378

94-
Handoff content (copy if needed):
95-
[full handoff content]
79+
**Step B — Confirm:**
80+
Return ONLY: `done`
81+
---
82+
83+
Wait for the sub-agent to return. Then print EXACTLY this — nothing before, nothing after:
9684
```
97-
Do NOT write the handoff to a file on disk.
85+
/[target_agent] progress/[target_agent].md
86+
```
87+
88+
Session continues.
9889
</step>
9990

10091
</handoff-steps>

src/skills/start.md

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,9 @@ Loads project state and session context. Always reads the project index first
2020
If found: parse Phase Status and Artifacts sections. Hold this as project context — it informs everything below.
2121
If not found: proceed silently. The index will be built on first wrap.
2222

23-
**Additionally (Agent Space):** query Agent Space for recent project knowledge:
24-
```bash
25-
curl -s -X POST "https://uztngidbpduyodrabokm.supabase.co/functions/v1/agent-messages" \
26-
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InV6dG5naWRicGR1eW9kcmFib2ttIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI1MTc3ODksImV4cCI6MjA4ODA5Mzc4OX0.FNnTd5p9Qj3WeD0DxQORmNf2jgaVSZ6FU1EGy0W7MRo" \
27-
-H "Content-Type: application/json" \
28-
-d '{"action": "list", "to_agent": "[agent_id]", "project": "[project]", "limit": 5}'
29-
```
30-
If Agent Space returns recent messages: use them to supplement the project index. If unavailable: proceed with the file index only — do not block on this.
31-
3223
### 2. Detect Session State
3324

34-
Read `_wds/tools/memory/SKILL.md` and follow the `load` operation for the current agent_id.
25+
Read `~/.claude/wds/src/tools/memory/SKILL.md` and follow the `load` operation for the current agent_id.
3526

3627
**Fallback chain:** state found → show resume prompt → fresh start
3728

@@ -104,6 +95,5 @@ Do not mention /start or the absence of a state file.
10495
## Notes
10596

10697
- Always read `progress/project-index.md` — never skip it. It is the project's memory.
107-
- Agent Space supplements the index but never replaces it. File is authoritative.
10898
- The state file lives at `progress/[agent].md` relative to the project root.
10999
- On resume, get back to work quickly. The user knows the context.

0 commit comments

Comments
 (0)