Reference

The modules

scrumia-core — the kernel

Fills no slot and does nothing on its own. It describes the composition and makes it legible to agents. The only non-optional module.

scrumia-rules — no slot

Sits beside scrumia-core: the rules-hierarchy format itself — index, guides, decisions — that lets a module's knowledge skill, or a project's own conventions, load only the guide a task routes to instead of one growing file. Fills no slot. Assumes nothing beyond scrumia-core. Costs one more layer to author correctly — a section is overhead below three distinct concerns.

scrumia-specs — slot specs

Per-feature specs, TDD-oriented. A contextual file catalogue rather than one document. Assumes specs live in the repo next to the code. Costs more judgement when writing than a fixed template.

scrumia-github-project — slot tracker

Issues, sub-issues, GitHub Projects columns, branches and PRs. A PreToolUse hook blocks stateful files in the repo. Assumes an authenticated gh. Costs a hard GitHub dependency and nothing offline.

scrumia-teams — slot team

Each boundary is a line of refusal — without it, the three collapse into one generalist and the split stops paying for itself. Three isn't a magic number: roles are enabled, disabled and added by config. Turning one off is a documented trade-off, not a downgrade.

scrumia-discovery — slot discovery

scrumia-impl-rust — slot implementation

Invalid states made unrepresentable, Result at the boundaries, typed errors per layer. Refuses unwrap() in production, clones that appease the borrow checker, single-implementer traits.

scrumia-impl-solidjs — slot implementation

Fine-grained reactivity without React reflexes, behaviour-first component tests, structure by feature. Refuses destructured props, effects used as derivations, components that fetch.

scrumia-impl-reactjs — slot implementation

Server Components by default, Actions for mutations, derived state during render, behaviour-first component tests. Refuses useEffect for derived state, imperative DOM, effects where event handlers belong, unnecessary "use client".

scrumia-tdd — no slot

Refines one point of the implementation contract: how we test. The cycle operationalized for an agent, the mock boundary, AC-to-test mapping.

scrumia-solid-principles — no slot

Refines one point of the implementation contract: which design principles. The five principles, each with its application limit — over-application is audited on equal footing with violations.

scrumia-tanstack-query — no slot

Refines one point of the implementation contract: how the app talks to the server and caches what it gets back — query keys, invalidation, optimistic updates, the boundary against client-only state. Ported from real monorepo use: 9 guides, 13 decisions. Assumes a stack TanStack Query ships for (React, Solid, Vue, Svelte). Costs a caching model to learn — the audit and refactor skills that would measure and close the gap aren't built yet.

scrumia-rhf — no slot

Declarative form management for React apps using React Hook Form. Refuses a form without a resolver, useState + onChange where register() already covers it, and state read through the DOM. Scoped to scrumia-impl-reactjs; a SolidJS app pays no cost.

scrumia-compound-design — no slot

The compound component pattern, framework-agnostic. A parent exposes its parts through a single API, children reach the parent through context (or the framework's equivalent — provide/inject, signals, a service), and sub-components travel with the parent rather than being scattered across module paths. Documented side by side for React, Vue, Solid and Angular, in each framework's idiom.

scrumia-design — slot design

Identity, tokens and components live in the repo; a Claude Design project is the review surface, not the source of truth. One rule underneath: a value the tokens don't carry is a finding, never an inlined exception. Ships the designer standing role — the only module that does so from outside the team slot, because a role with no design system to guard would judge on taste.

scrumia-zod — no slot

Runtime validation at the trust boundary. The type is derived from the schema rather than hand-written beside it, parsing happens where untrusted data enters rather than on every internal call, and a schema whose failure a user reads carries a field-targeted message. Cited against Zod pinned to v4.

scrumia-html-css — no slot

The HTML, CSS and accessibility capability for a covered app. Three refusal rules and one audit skill: a semantic element when both express the same intent, an interactive widget that uses the element whose contract matches the action, and a test that queries what an assistive technology would meet. Scoped to React and SolidJS by default; a project running neither pays no cost.

scrumia-gradle — no slot

Gradle the build tool, stated in Gradle's terms. Eight refusals or norms: Kotlin DSL over Groovy, version catalog as the one place versions live, the shape of a convention plugin (precompiled script plugin in a build-logic composite), lazy task configuration, the build and configuration caches, composite builds for local siblings, pluginManagement, and documentation tasks wired into the lifecycle. The Kotlin Multiplatform-specific application of these rules belongs to scrumia-kotlin-multiplatform-mobile, cited here only as where the shape is applied.

scrumia-material3 — no slot

Material 3 the UI system, stated in Material 3's terms. Eight refusals or norms: Compose as the default toolkit and Views as an explicit choice with a stated justification; tokens from MaterialTheme.colorScheme, Typography, Shapes, elevation, and the state-layer system — never from hex literals; components from androidx.compose.material3.* — never built from primitives; dynamic color as the default on Android 12+; touch targets of 48dp × 48dp; contrast ratios of 4.5:1 for body text and 3:1 for large text; and contentDescription on every icon-only control.

scrumia-kotlin-multiplatform-mobile — slot implementation

The Kotlin Multiplatform Mobile composition preset. Six refusals: expect/actual stays in commonMain for the contract and in the platform source set for the implementation; source-set layout keeps platform code in its own source set; platform tests and shared dependencies live where they compile for every target; a Cocoapods pod is declared once across the KMP module and the iOS project; the target list is the one in the Gradle DSL, not the one an IDE invents; Gradle wiring goes through the Kotlin Multiplatform plugin's source-set DSL.

scrumia-ktor — no slot

HTTP server and client rules for a Ktor codebase. Nine refusals or norms: the application's surface is one routing {} block split into nested route extension functions; ContentNegotiation is installed once per application and per client; one HttpClient per remote dependency, built once and closed once; authentication is install(Authentication) { name -> ... } with named providers; route tests run on testApplication {}; ports, hosts, secrets and URLs come from environment.config; a streaming route states whether it is WebSocket or SSE; request logging is install(CallLogging) with a filter; and an HTTP non-2xx is converted into a domain error in one named place.

scrumia-kotlin — slot implementation

Idiomatic Kotlin language rules. Six refusals or norms: var only when val cannot carry the invariant; !! only with a stated local proof and never on a platform type (T!) read as Kotlin; structured concurrency with explicit scopes, no GlobalScope.launch outside the bootstrap, no swallowed CancellationException; data class for values, sealed interface for closed taxonomies, value class for type-safe wrappers; top-level functions for stateless utilities, object expressions only for true singletons; internal as the module boundary (not package-private), public only on a surface meant to cross a published boundary.

scrumia-effect — no slot

Effects as values, not exceptions — the typed-effect discipline. Six refusals: every rule names the approach it informs (Result, Either, IO/suspend, effect.website, or discipline-level); the four approaches are layered, never substituted; effect.website is cited by URL and never wrapped; recoverable failures travel the value path, not the throw path; retry is data on the failure composed as a function on the effect, not a try/catch loop; environments and layers (where they apply) replace service-locator-style dependencies at the effect boundary.

scrumia-functional-programming — no slot

The Functional Programming paradigm, language-neutral. Six refusals: impurity smuggled past an unnamed boundary; a partial function whose signature accepts an input it cannot produce an output for; an expression whose value depends on something its syntactic form does not name (a referential-transparency violation); mutation defaulting where an immutable value would have read the same and written less; inheritance as the primary reuse mechanism where composition would have read as the smaller, more local choice; effects described at the moment they run rather than as values the program composes before execution.

Configuration

.scrumia/config.yaml describes the project and its tooling — never its state.

project:
  name: "my-project"
  repo: "tibs245/my-project"

modules:
  "tibs245/scrumia:scrumia-specs": {}
  "tibs245/scrumia:scrumia-github-project": {}
  "tibs245/scrumia:scrumia-teams": {}
  "tibs245/scrumia:scrumia-discovery": {}
  "tibs245/scrumia:scrumia-design": {}

apps:
  - name: web
    path: apps/web
    type: frontend
    modules:
      "tibs245/scrumia:scrumia-impl-solidjs": {}
      "tibs245/scrumia:scrumia-tdd": {}
  - name: api
    path: apps/api
    type: backend
    modules:
      "tibs245/scrumia:scrumia-impl-rust": {}
      "tibs245/scrumia:scrumia-tdd": {}
      "tibs245/scrumia:scrumia-solid-principles": {}

settings:
  autonomy:
    level: guided
    auto_merge: none
  specs:
    root: "features"
  tracker:
    columns: [Backlog, Ready for dev, To dev, In progress, In review, Done]
  team:
    roles: [manager, business, tech]
    sprint:
      max_tickets: 5

Two conventions that matter: the mapping names what is present, so a capability you go without carries no key at all — and where the difference between "not chosen yet" and "deliberately without" matters, it is said as a comment standing in the key's place. And every module documents the keys it reads under settings: an implicit setting is one you can't change.

Implementation modules and the modules that refine them

The most personal choice. An app lists the modules it draws on — its implementation module, and any number of others that sharpen one point of what that module says. Two competent developers can hold opposite views here and neither is wrong, which is exactly why these are replaceable modules rather than kernel rules.

The contract

A skill the agent loads before writing code in that app, covering four things:

1. How you test — which level for which change, what gets stubbed and what doesn't, how an AC-n becomes a test
2. Which design principles — named and situated. "We apply SOLID" guides nobody; a principle without a boundary becomes a reflex, and reflexes produce needless abstraction
3. How code is laid out — precise enough that an agent places a new file without hesitating
4. What is refused — the most useful part, and the most often skipped. An agent that knows what's rejected self-corrects

How they compose

A module can refine one named point of that contract — scrumia-tdd refines "how you test", scrumia-solid-principles refines "which design principles" — and ship the reference, the audit and the refactor skills that go with it. The implementation module situates each for its stack. One precedence rule: specific beats generic — the implementation module over the module refining it, the project override over both.

Overriding without forking

Every module documents what it reads under its own params:, plus an optional project override file (.scrumia/modules/<module>.md) whose content it honours over its own rules. A module offering neither gets forked at the first disagreement — and that fork never sees an update.

Rules hierarchy

Each knowledge skill becomes a routing index instead of one fat file: 00-index.md loaded first and always, guides/NN-topic.md loaded only on demand, decisions/D-NN-slug.md opened only when a rule is challenged. A section.json declares the globs a section governs. In a monorepo, an app's path in apps[] anchors which sections apply where — the same specific beats generic precedence, one level down. See scrumia-rules above and ADR-0011.

Writing a module

Three rules, no more:

1. Fill a slot — an existing one, or a new one you define and document
2. Document your settings under settings.<slot>
3. Provide your CLAUDE.md line — the sentence that tells an agent what it needs without reading you

And one prohibition: never assume another module is present. If a capability is missing, say so and propose the next step rather than failing.

# validate before publishing
claude plugin validate ./plugins/scrumia-core
claude plugin validate .

# try without installing
claude --plugin-dir ./plugins/scrumia-core

A new slot is warranted when a real project would fill it differently. Otherwise it's one more skill in an existing module.