Developer Experience & Documentation

Quick ref

Mission: Maintain the skills-based Waymark and its tooling so every session triggers the right department and tools with minimal context. Rules: tool names live only in skill-map.json (registry is generated) · run sync.mjs after any skill/MCP change · install skills only with an explicit yes · new stacks/architectures/departments/project skills start from templates/ · ask before writing to ~/.claude or a repository from a project task Skills by default: skill-creator · update-config · init · agent claude-code-guide · library-docs DoD: templates followed, sizes within limits, registry regenerated, trigger descriptions concrete, no contradictory instructions.

Entry

Guest (no Waymark block in context) → ../waymark/references/coexistence.md §3. Reads:

• Learnings: ~/.waymark/learnings/dept-devex.md if it exists.
• When the task is Waymark itself, the "project" is Waymark source repository (or <skills-dir>/waymark/).

Brief questions

1. What is changing: a skill, a department, the registry, an MCP, settings, CLAUDE.md, docs, memory?
2. Why / for whom: which recurring friction or missing capability does it fix, for this user or for one project?
3. Where does it live: core (skills/waymark), a department (skills/dept-*), the private layer (~/.waymark/), a project (<project>/<project-skills-dir>/) or global settings?
4. How will it trigger — which exact user phrases, in which language?
5. Does it need a new dependency (skill, MCP server) and did the user approve it?
6. Does it contradict anything in CLAUDE.md, the core protocol or another department?
7. What does done look like: sync clean, skill listed, trigger tested with a real phrase?

Scope

• Owns: the waymark plugin (core, departments, skill-map.json, sync, stacks, architectures, templates), project skills, the private layer, CLAUDE.md, Claude Code settings, MCP availability, memory, documentation structure.
• Does not own: product code conventions → dept-frontend, dept-backend · CI pipelines → dept-devops · secret policy → dept-security · architecture content decisions → dept-architecture.

Procedures

In procedures.md (same folder), one section per task:

• Layout of Waymark
• Write a trigger description (any skill)
• Registry: skill-map.json + sync
• Install a missing skill or MCP
• Generate a project skill
• Private layer maintenance
• Add a stack, architecture or department
• Add an agent
• CLAUDE.md hygiene
• Settings, MCP and memory
• Documentation (Diátaxis)

Rules

• Keep skill-map.json the single source of tool names and regenerate the registry with sync.
• Start every new profile, department or project skill from templates/.
• Install skills or MCP servers only after an explicit yes.
• Ask before modifying the agent config folder or a repository from within a project task.
• Keep the waymark core skill as the single protocol; others reference it, never redefine levels.
• Prefer: keep department SKILL.md ≤ ~8,000 characters (procedures in procedures.md), tool skills ≤ ~11,000, and the instructions block ≤ ~6,500 (it quotes every testigo that blocks).
• Never write contradictory instructions across CLAUDE.md, the core skill and departments.
• Never put stack-specific commands in department skills; they belong in stacks/.

Tools

Definition of Done

• Changed files follow their template's section order and size limits
• sync.mjs run; no unreviewed auto: true or Unassigned entries left
• Every referenced name exists in the registry or session listing
• Trigger descriptions tested with a real phrase
• No contradictions between CLAUDE.md, core skill and departments
• Docs classified by Diátaxis type

Hand-offs

• To dept-architecture: a new architecture profile needs design decisions.
• To dept-qa: gate definitions or the Definition of Done change.
• To dept-devops: tooling that must also run in CI.
• To dept-security: settings or MCP touching permissions, secrets or network.
• To dept-product: Waymark roadmap or scope.
• To any dept-*: its content needs domain review.

Learned rules

Grows with use (../waymark/references/learning.md).