AGENT SKILL

module-roles

Adds a new role's doc to every existing module, or marks a module that does not need the role. Declares the role when it is undeclared, shows the plan with roles add --dry-run, writes the docs, fills each one from that module's code and docs, then checks lint and next. Use when the user says "add a role", "a new role for every module", "the upgrade brought a role", "this module does not need that role", or when next names roles add.

License 许可
MIT
最近更新
2026-10-21
Stars
★ 1
Forks
0

01 前言 Front Matter

name
module-roles
description
Adds a new role's doc to every existing module, or marks a module that does not need the role. Declares the role when it is undeclared, shows the plan with roles add --dry-run, writes the docs, fills each one from that module's code and docs, then checks lint and next. Use when the user says "add a role", "a new role for every module", "the upgrade brought a role", "this module does not need that role", or when next names roles add.

03 SKILL.md 正文

module-roles

When to use

  • The team (or a newer Segmently Modules) added a role, and the existing modules lack its doc.
  • The user asks to add a role to every module, or segmently-modules next --json names roles add for a role.
  • The user says a module does not need a role, or needs it after all.

When not to use

  • A code change made the docs stale: use module-sync.
  • The work needs a new module: use module-create.
  • Only lint findings need fixing: use module-lint.

Scope

Writes: one roles/<role>.md doc per registered module (a split module's children inherit the parent's: roles add --all writes none for them; never over an existing doc), a not-needed mark in the registry for a module the user says needs no doc, and the role's declaration in the team config when it is undeclared. It never edits a *.legacy.md file, never edits code, never commits; ask the user to review and commit. Temporary files go outside the repository.

If segmently-modules is not found, tell the user how to install it — the segmently-modules plugin for Claude Code, uv tool install git+https://github.com/segmently-ai/segmently-modules.git, or pipx install git+https://github.com/segmently-ai/segmently-modules.git — and stop until it runs.

Steps

When the team (or a newer Segmently Modules) adds a role, the existing modules lack its doc.

When segmently-modules next --json names the roles add command with --all for a role (the upgrade brought the role), the role is declared already — start at step 1.

If segmently-modules roles list --json does not list the role, declare it first: a [roles.ROLE] table with order, standard = true (every module gets the doc) and a one-line description in the team config, .segmently-modules/config.toml, or in a pack the team owns — ask the user what the role is for when unclear. Then continue with step 1.

  1. segmently-modules roles add ROLE --all --dry-run — show the user the docs it would create or register and the registered ones missing on disk.
  2. segmently-modules roles add ROLE --all --json — writes them, never over an existing doc; --recreate only for a registered doc whose file is gone.
  3. Fill each new doc with what that role needs for that module, from its code and docs — one module at a time, never inventing components; then index its rules.
  4. segmently-modules lint --json — fix what the new docs caused.
  5. segmently-modules next --json — report what is left.

A module that does not need the role

Some modules give a role nothing to say — a build tool and a product-owner role, a backend module and a designer role. When step 1's plan lists such modules, name them and ask the user whether they need the doc at all; before step 2, mark each one the user names: segmently-modules roles skip ROLE MODULE… --note "<why>" --dry-run, then the same with --json instead of --dry-run (the why in the user's words, one line). Step 2 then leaves those modules alone and next stops asking for their doc. A module that has the doc is refused: delete the doc first, after the user's OK.

The module needs the role after all: segmently-modules roles add ROLE MODULE --json writes the doc in place of the mark; fill it as in step 3.

Gates

Autonomous by default: it declares, writes and fills. It stops and asks only when the role is undeclared and what it is for is unclear (the user says what the role covers, then it declares the role), and before it marks a module as not needing the role (the user names the modules). Never fill a doc with a claim the module's code and docs do not support.

Exit codes

0 ok · 1 = findings left (lint) or a role that cannot be added: read the result and act · 2 = a usage or config error or a refused write: read stderr, fix the input, run again once.

04 同仓库更多 Skills

segmently-ai
segmently-ai/segmently-modules

${skill}

${description}

★ 1
segmently-ai
segmently-ai/segmently-modules

designer

Designs user interface work and reviews it against the designer docs of the modules it touches. Prototype — a brief and standalone HTML mocks from the team's tokens, then it waits for approval before any code; rework-audit — an existing flow's dead ends and what must survive, before a redesign; review — screenshots of the running app checked against every UX invariant and the flow patterns, always written with a PASS or BLOCKED verdict. Use for any task that adds or changes screens, dialogs, layouts or styling, or when the user asks for a mockup, prototype, design, UI or UX review.

★ 1
segmently-ai
segmently-ai/segmently-modules

qa-acceptance

Writes the acceptance criteria of one task before any code is written. Finds the touched modules with discover, reads their qa and qa_acceptance docs, flags problems in the task itself, splits it into sub-tasks, applies equivalence partitioning, boundary values, decision tables or state transitions, and writes prerequisites PRE-NNN and criteria AC-NNN in Given, When, Then form, reusing existing baseline criteria by id. Shows them in the conversation; a file only at a path the user names. Use when the user asks for acceptance criteria, a test plan or a definition of done for a task.

★ 1
segmently-ai
segmently-ai/segmently-modules

qa-acceptance-baseline

Creates or refreshes a module's acceptance baseline, the qa_acceptance role doc that says what must never break, as P0, P1 and P2 criteria with stable AC-NNN ids in Given, When, Then form. Reads every doc and the code of the module through Segmently Modules, confirms its understanding, the requirements and the criteria with the user block by block, continues from the highest existing id and never renumbers. Use when the user asks for a module's acceptance baseline, regression criteria, or to refresh them after the module changed.

★ 1
segmently-ai
segmently-ai/segmently-modules

module-sync

Brings module docs and registry fields in line with a work session — what it decided, rejected, discovered and changed. Takes the session's knowledge first and the code change second, asks sync-instructions which docs to update, prints findings and a proposal per module, edits docs, keywords and links, runs the sync hooks and checks with ci. Autonomous, it asks only in four ambiguous cases and never commits. Use at the end of a session that changed module code or revealed module knowledge, when the user says "sync the session", "sync the docs", or a CI drift check fails.

★ 1
segmently-ai
segmently-ai/segmently-modules

module-split

Splits an oversized module into two to six child modules. Analyses the module's docs section by section, proposes the children with a section-to-child table per doc and what stays in the parent, and stops for confirmation. Then freezes each split doc as a legacy copy, creates the children with create, moves the sections word for word, rewrites the parent as an index, routes the code and validates with lint. Use when lint reports a module doc over its size budget, or the user says "split this module", "too big", "break X into submodules".

★ 1