segmently-ai/segmently-modules

Makes Segmently Modules read a module registry and module docs that another tool or team already wrote, without changing them. Runs adopt to infer the team config (paths, roles, fields, statuses, a code-map rule), explains each inference and its evidence, asks only what adopt never guesses, writes the config and shows the lint report grouped by code. Use when a repository already has a registry and wants Segmently Modules to work with it, or the user asks to adopt, import or take over an existing registry.

The module system's assistant. Sets Segmently Modules up in a repository, explains how to do something with the module docs in plain words and does it on the user's OK, turns what the repository needs now into a short plan and carries it out, and plans goals that take several module skills. Use when the user asks what to do next with the module docs, how to do something in Segmently Modules, to set it up, or for a plan.

Creates a new module, or a child of an existing one, with its docs and registry entry through create. Gathers the name, a one-sentence description, at least five keywords, the roles and the parent, shows a dry run and waits for a yes, then creates it, fills the scaffolded docs from what the user knows, routes its code and checks lint. Use when the user says "add a module", "create a module for X", "register this area", or when work lands in code that no module owns.

Maps a confirmed task, or a change on a branch, to the modules it touches before planning or review, read-only. Runs discover to list each module as modify or reference with the docs to read and to update, lists the code files of every module to modify, and names the files that belong to no module. Can save the result as JSON at a path the user gives. Use when the user asks which modules or files a task will touch, says "do discovery", after a plan is agreed, or when a pipeline needs the touch-set of a change.

Starts Segmently Modules from an existing codebase that has no module registry yet. Maps the code into candidate modules and stops for the user to confirm them, has one writer per module document its code (subagents, or itself one module at a time), reconciles the registry, measures how well tasks route, and stops again before anything lands in the repository. Use when the user asks to set up, bootstrap or generate module docs for an existing repository, or to continue an interrupted init.

Runs the module-system gate with ci (or lint when there is no base), explains every finding from its code, fixes what is safe to fix with the CLI verbs, leaves judgement calls to the user and runs the gate again until it is green or only judgement calls are left. Use when the user says "fix lint", "make ci pass", "why does the module check fail", or after a skill or a person reports module lint findings.

Answers one question about one or more modules in depth, from their docs and their code, read-only. Reads every role doc, the module's links in both directions, the code files Segmently Modules maps to it and its lint findings, then writes a brief with file:line evidence that names every place where the docs and the code disagree. Use for "how does X really work", "is the doc of X still true", "explain module X in depth", or before a risky change to X.

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.

Quick, read-only context on the modules a task is about, while the task is still being discussed. Asks the CLI what each named module is, which docs to read and which modules it is linked to, reads those docs and reports a short brief. No plan, no edits. Use when the user says "look at module X", "load the context for", "what do we know about", or describes a change and names modules before a plan exists.

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".

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.