Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLITeam
AssigneesNone

Relationships

#1103 Architecture guide decision tree omits partial-match extend and package-granularity guidance

Opened by jeremy · 7/12/2026

Problem

In practice, a multi-component automation pipeline ended up split across five separate extensions when two would have sufficed. Root cause: nothing in swamp's guidance addresses extension package granularity — whether a new capability should join an extension already being built, or become its own package. The default instinct, with no guidance either way, is "new capability -> new package," even when swamp itself supports bundling multiple models and workflows into one package.

Separately, references/architecture/guide.md's decision tree treats "does an existing type cover this?" as binary (yes -> use it, no -> build new), with no branch for "partially covers it, missing one method" -- even though the swamp-repo-init-scaffolded CLAUDE.md/AGENTS.md template's own rule (search before you build) already prioritizes extending an existing type over building a new one. The decision tree and the always-loaded rule set are inconsistent with each other.

Both gaps are only caught after the fact -- once several packages already exist, unwinding the fragmentation costs a multi-step migration rather than a five-minute decision made up front.

Proposed solution

  1. Add a rule to the swamp-repo-init-scaffolded CLAUDE.md/AGENTS.md template: "Bundle by default, split deliberately. A single extension package can contain both models and workflows together. Splitting a workflow into its own package is a deliberate choice justified by genuine independent utility -- not the default move just because you're adding a new capability. When in doubt, add to the extension you're already touching."

  2. Update references/architecture/guide.md's decision tree:

    • Add a partial-match branch under "Automate a single external action": "Existing type partially covers it, missing a method? -> extend it (see design/models.md)."
    • Add a package-granularity branch/row to the primitives table: "New capability for a domain you're already touching -> fold into that extension's package. New, independently-useful domain -> new package."

Alternatives considered

Leaving this as tacit knowledge learned through trial and error -- rejected because the failure is only visible after publish, and unwinding a fragmented extension set is expensive compared to making the right call up front.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

7/12/2026, 10:34:16 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.