Skip to main content

Use case — Onboarding by role

Asking a newly arrived developer to read the manual's 15 chapters before making the first commit is, in practice, asking them not to read them. Effective onboarding is the opposite: it starts small, with what that role does in the next two weeks, and grows with the work.

The get_guide_by_role was designed precisely for this. It receives the risk level and the role — developer, appsec-engineer, devops-sre, qa, any of the 13 canonical ones — and returns only the practices that the manual assigns to that person, organised by SDLC phase. The agent composes a personalised guide from there: what is expected of this role in each phase — plan, design, develop, test, operate, … — with user stories already linked, ready to become acceptance criteria.

The canonical phases are plan, design, develop, build, test, deploy, operate and govern. The old names still resolve as aliases (requirements→plan, implement→develop, governance→govern), but the examples on this page use the canonical form.

Prior requirements​

  • MCP installed, skill loaded.
  • Project risk level known.
  • Role of the new member defined (one of the 13 canonical roles).

Flow​

1. Discovery — how many assignments exist?​

Call without role/phase to see counts:

get_guide_by_role({"risk_level": "L2"})

Returns role_summary{} + phase_summary{} — how many practice assignments exist per role and per phase.

2. Detail — assignments of the target role​

get_guide_by_role({"risk_level": "L2", "role": "developer"})

Output: assignments[] (slim) + joined user stories.

Each assignment has:

  • practice_id, chapter_id, phase
  • associated user stories (text + acceptance criteria)

3. Detail by phase​

For a "first sprint" guide, filter by the first relevant phase:

get_guide_by_role({"risk_level": "L2", "role": "developer", "phase": "develop"})

→ only assignments in the develop phase.

4. Structure the guide​

Recommended model:

# Onboarding — <Role> @ <Projecto>

> **Risk level:** L2
> **Role:** developer
> **Gerado a partir de:** SbD-ToE MCP v<versão>

## Como o role contribui em cada fase

### Fase: plan
- Practice <ID>: <texto> (cap. <chapterId>)
  - User story: <texto>
  - Acceptance criteria: <texto>

### Fase: design
...

### Fase: develop
...

### Fase: test
...

### Fase: deploy
...

### Fase: operate
...

## Roles com quem mais interages
<inferir do output — ex.: developer interage com appsec em design/test, devops em deploy>

## Próximos passos
- Ler capítulos: <chapters_ids do output, ordenados por número de practice_assignments>
- Setup do ambiente: `setup_sbd_toe_agent(riskLevel="L2", projectRole="<role>")` em cada sessão
- Skill no cliente AI: ver [Skills e agentes](../04-skills-agentes.md)

5. Customise with the repo​

Add:

  • Direct link to the repo's artefacts (created via governance bootstrap)
  • Pointers to the project's CLAUDE.md / AGENTS.md
  • Operational checklist for the first 30 days

Output discipline​

  • Always pass role or phase — without either of them, the output is only counts.
  • Cite exact practice_id and chapter_id.
  • If assignments: [] for a (role, phase) → write "Manual-grounded: this role has no direct assignments in this phase" — do not invent to "fill in".

Skill / subagent — Claude Code​

.claude/agents/sbd-toe-onboarding.md:

---
name: sbd-toe-onboarding
description: Gera guia de onboarding SbD-ToE personalizado por role + risk_level.
tools: Read, Write, mcp__sbd-toe__*
---

# Workflow

1. Perguntar role + risk_level se não explícitos.
2. Chamar get_guide_by_role(risk_level) sem role para ver contagens.
3. Chamar get_guide_by_role(risk_level, role) para detalhe.
4. Estruturar guia por fase (plan → govern).
5. Para cada assignment vazio: marcar "sem atribuições directas — não inventar".
6. Acrescentar pointers ao repo (governance/, CLAUDE.md, AGENTS.md) se existirem.

Useful combinations​

For a role that spans many phases (developer, arquitetos-software), iterate phase by phase to keep the output within the context:

get_guide_by_role(L2, "developer", "plan")
get_guide_by_role(L2, "developer", "design")
get_guide_by_role(L2, "developer", "develop")
get_guide_by_role(L2, "developer", "test")
get_guide_by_role(L2, "developer", "operate")

Concatenate the outputs into the guide.

Anti-patterns​

  • ❌ Calling get_guide_by_role(L2) without role/phase and trying to extract detail — only counts come back.
  • ❌ Manual aliasing of roles (e.g.: "engineer" → "developer") instead of letting the server resolve them — use the documented canonical form.
  • ❌ Inventing acceptance criteria for user stories that were not returned.

Related​