@rungs/cli 0.1.0

package/modules/specs/module.toml

@@ -0,0 +1,107 @@
+[module]
+name    = "specs"
+version = "1.0.0"
+rung    = 2
+summary = "Behaviour specifications with stable feature and story ids, per-story status, a mandatory scope section, and a gate against overclaiming."
+
+[requires]
+modules = []
+
+[conflicts]
+modules = []
+
+# Orthogonal to `backlog`, and installing one does not give you the other. Specs
+# answer *what is in scope*; a backlog answers *what is happening*. hexguard-templates
+# has excellent specs and cannot say what is in flight.
+
+[params.path]
+description = "Directory holding the specs"
+default     = "docs/specs"
+
+[params.feature_format]
+description = "Feature id shape, per surface prefix"
+default     = "<PREFIX>-F##"
+
+[params.story_format]
+description = "Story id shape"
+default     = "<PREFIX>-US-###"
+
+[params.split_lines]
+description = """
+Split a spec into spec.md + stories/ only past this many lines. A threshold, not a preference —
+it is what stops structure being created ahead of content.
+"""
+default     = 600
+
+[[gates]]
+id     = "specs-status-evidence"
+kind   = "declared"
+engine = "register-schema"
+table  = "gates/specs.toml"
+tier   = "fast"
+why    = """
+A story marked done must name what closed it. "Demo is not done": an endpoint that exists to
+showcase a capability in isolation is partial with a note, never complete. A spec that overclaims
+integration is worse than no spec, because it is read as verified.
+"""
+
+[[gates]]
+id     = "specs-scope-section"
+kind   = "declared"
+engine = "sections"
+table  = "gates/specs.toml"
+tier   = "fast"
+why    = "Out-of-scope is what stops an agent silently expanding a surface while implementing an unrelated story."
+
+[[gates]]
+id     = "specs-ids-unique"
+kind   = "declared"
+engine = "id-integrity"
+table  = "gates/specs.toml"
+tier   = "fast"
+why    = "Story ids are cited from commits, plans and work items; two stories sharing one make every citation ambiguous."
+
+[[gates]]
+id     = "specs-split-threshold"
+kind   = "declared"
+engine = "file-budget"
+table  = "gates/specs.toml"
+tier   = "fast"
+why    = "A spec past the threshold is one nobody reads to the end, and its later sections are where the unverified claims collect."
+
+[detect]
+paths   = ["docs/specs/**/*.md", "docs/**/spec.md", "specs/**/*.md"]
+markers = ["rungs:begin specs"]
+
+# Authority-docs-by-topic is a different way to answer "what is true", and it is
+# not a spec tree. Never auto-adopted.
+[[detect.paradigm]]
+id      = "authority-docs"
+paths   = [".ai/context/doc_ownership.md", "docs/architecture/project_scope.md"]
+compare = "docs/research/synthesis.md#37-specs-separate-tree-or-work-item-plans"
+note    = """
+axiom-mesh routes truth by topic through a doc-ownership registry rather than by surface through
+story specs. Both answer "what is in scope"; only the spec tree carries per-story status. They
+coexist — `doc-authority` is the module for the other shape — but installing specs over an
+authority tree creates a second place to look, which is the failure that registry exists to
+prevent.
+"""
+
+# An inference rule was declared here and removed after running it. It matched
+# `[A-Z]{2,8}-US-\d` and proposed `AUTH` for `story_format`, whose value is a
+# *shape* (`<PREFIX>-US-###`) — so it proposed a prefix for a parameter that
+# wants a pattern, and a repo with several surfaces has several prefixes by
+# design. Nothing in this module is inferable without judgement, so it infers
+# nothing. That is a legitimate answer, and a knob wired to a wrong value is
+# worse than no knob.
+
+[provenance]
+sources  = ["hexguard-templates", "rift-forge"]
+patterns = ["spec-ids-and-status", "mandatory-scope-section", "demo-not-done", "split-threshold", "reference-implementation-pointer", "adoption-guide"]
+incident = """
+hexguard-templates states the rule this module gates: "Some endpoints exist purely to showcase a
+package in isolation. Mark these partial with an explicit note, never complete — a spec that
+overclaims integration is worse than no spec." The rule exists because overclaiming had already
+happened, and it was enforced by review only. Its own platform spec carries the status line
+"stable, enforcement gaps noted".
+"""

package/modules/workflows/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin workflows@1.0.0 -->
+## Planning
+
+Handed something larger than one change? **`/decompose`** — split into technical concerns, decide
+reuse per concern, pick a planning tier, sequence by dependency. The decision tables are in
+[`.ai/rules/`](.ai/rules/README.md) and replace judgement rather than supplementing it.
+**Tier 0 — no document — is a real answer.**
+<!-- rungs:end workflows -->

package/modules/workflows/gates/workflows.toml

@@ -0,0 +1,65 @@
+# Gate table for the `workflows` module.
+
+# ── workflows-plan-tier-declared ──────────────────────────────────────────────
+
+[[frontmatter_schema]]
+id       = "plans"
+scan     = ["{{plan_path}}/**/*.md"]
+exclude  = ["{{plan_path}}/README.md"]
+required = ["tier", "status", "created"]
+enum     = { tier = [1, 2], status = ["draft", "active", "done", "abandoned"] }
+message  = """
+{file} has no `tier`. A plan that does not declare its tier cannot be checked against that tier's
+required sections, and tiering degrades back into "write whatever felt right" — the judgement call
+the table exists to replace. Tier 0 work has no document, so a document here is tier 1 or 2.
+"""
+
+# ── workflows-plan-sections ───────────────────────────────────────────────────
+
+[[sections]]
+when      = { tier = 1 }
+scan      = ["{{plan_path}}/**/*.md"]
+required  = ["Why", "Decisions", "Phases", "Validation", "Follow-up"]
+non_empty = true
+
+[[sections]]
+when      = { tier = 2 }
+scan      = ["{{plan_path}}/**/*.md"]
+required  = [
+  "Why", "Decisions", "Phases", "Validation", "Follow-up",
+  "Boundary decision", "Reuse table", "Proof-of-reuse gate", "Verification gate",
+  "Explicitly out of scope",
+]
+non_empty = true
+message   = """
+{file} is tier 2 and has no non-empty `{section}`. A tier-2 proposal missing its proof-of-reuse
+gate is a tier-1 plan wearing a heavier label — and the label is what other work will trust.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "workflows-plan-tier-declared"
+expect  = "fail"
+fixture = { frontmatter = { status = "active", created = "2026-01-01" } }
+
+[[self_test]]
+gate    = "workflows-plan-tier-declared"
+expect  = "pass"
+fixture = { frontmatter = { tier = 1, status = "active", created = "2026-01-01" } }
+
+[[self_test]]
+gate    = "workflows-plan-tier-declared"
+expect  = "fail"
+fixture = { frontmatter = { tier = 0, status = "active", created = "2026-01-01" } }
+# Tier 0 has no document by definition, so a tier-0 file is a contradiction rather than a plan.
+
+[[self_test]]
+gate    = "workflows-plan-sections"
+expect  = "fail"
+fixture = { tier = 2, sections = ["Why", "Decisions", "Phases", "Validation", "Follow-up"] }
+
+[[self_test]]
+gate    = "workflows-plan-sections"
+expect  = "pass"
+fixture = { tier = 1, sections = ["Why", "Decisions", "Phases", "Validation", "Follow-up"] }

package/modules/workflows/module.toml

@@ -0,0 +1,75 @@
+[module]
+name    = "workflows"
+version = "1.0.0"
+rung    = 2
+summary = "Decision procedures: how to decompose work, whether to reuse or build, and how much planning a piece of work earns."
+
+[requires]
+modules = ["instructions"]
+
+[conflicts]
+modules = []
+
+[params.path]
+description = "Where the authority document lives"
+default     = "docs/workflows"
+
+[params.upstream_repo]
+description = """
+A sibling or upstream repository this one consumes from. Enables the extend-upstream branch of the
+reuse decision. Blank means the reuse table has three branches instead of four.
+"""
+default     = ""
+
+[params.plan_path]
+description = "Where tier-1 and tier-2 plan documents land"
+default     = "docs/plans"
+
+[[gates]]
+id     = "workflows-plan-tier-declared"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/workflows.toml"
+tier   = "fast"
+why    = """
+A plan document that does not say which tier it is cannot be checked against that tier's required
+sections, and tiering silently degrades into "write whatever felt right", which is the judgement
+call the table exists to replace.
+"""
+
+[[gates]]
+id     = "workflows-plan-sections"
+kind   = "declared"
+engine = "sections"
+table  = "gates/workflows.toml"
+tier   = "fast"
+why    = "A tier-2 proposal missing its proof-of-reuse gate is a tier-1 plan wearing a heavier label."
+
+[skills.decompose]
+# No extensions. Deciding how to break work down is exactly what a model should
+# reach for unprompted when handed something larger than one change.
+
+[detect]
+paths   = ["docs/plans/**/*.md", "docs/**/plan-*.md", "docs/.ai/backlog/plan-*.md", ".github/instructions/*workflow*.md"]
+markers = ["rungs:begin workflows"]
+
+[provenance]
+sources  = ["hexguard-templates", "hexguard", "rift-forge"]
+patterns = [
+  "reuse-decision-table",
+  "second-consumer-threshold",
+  "doc-tier-selection",
+  "per-concern-decomposition",
+  "multi-story-batching",
+  "numbered-workflow-steps",
+  "phase-checklist",
+  "lifecycle-verbs",
+  "controlled-performance-comparison",
+]
+incident = """
+hexguard-templates wrote the best decision procedure in the corpus — a nine-step workflow whose
+tier table is introduced with "Use this table instead of 'use judgment'" — and shipped it with no
+invocation surface at all. Its AGENTS.md prompts table reads, verbatim: "No custom prompts or
+agents defined yet for this repo. This table is a placeholder for future additions." The procedure
+loads only when a matching file is edited, which is after the decisions it governs have been made.
+"""

package/modules/workflows/rules/planning-tiers.md

@@ -0,0 +1,46 @@
+---
+description: >-
+  How much planning a piece of work earns — tier 0 (none), tier 1 (light plan), tier 2 (heavy
+  proposal) — and the triggers that move work up a tier. Loads when writing or reviewing a plan.
+paths:
+  - "{{plan_path}}/**/*.md"
+enforcement: gated
+---
+
+# How much planning
+
+**Use this table instead of judgement.**
+
+| Tier | When | Artifact |
+| --- | --- | --- |
+| **0 — no document** | One piece of work, every concern resolves to use-as-is or one trivial hand-roll, one consumer, no cross-repo change | Implement directly. A task list is enough |
+| **1 — light plan** | Several concerns, or one extend/hand-roll branch, but bounded to one surface | `{{plan_path}}/plan-*.md` with frontmatter `tier: 1` and: **Why · Decisions · Phases · Validation · Follow-up** |
+| **2 — heavy proposal** | An upstream change is taken, or a genuinely new shared primitive is proposed | `{{plan_path}}/plan-*.md` with `tier: 2` and, additionally: **Boundary decision · Per-concern reuse table · Proof-of-reuse gate · Verification gate · Explicitly out of scope** |
+
+## Tier 0 has to exist
+
+A process that always demands a document is one people route around, and the routing is invisible —
+the work still happens, just with no record. **Tier 0 is what makes tiers 1 and 2 credible**,
+because choosing them then means something.
+
+## Triggers that move work up
+
+Any one of these is enough:
+
+- a cross-repo change (at least tier 1, usually tier 2)
+- more than about two distinct concerns
+- more than one consumer affected
+- a hand-roll that looks likely to cross the second-consumer threshold soon — **write it down now
+  rather than rediscovering it later**
+
+## Tier is declared, not inferred
+
+Every plan carries `tier:` in its frontmatter. `rungs check` reads it and checks that tier's
+required sections are present and non-empty. A plan with no tier cannot be checked, and tiering
+degrades back into "write whatever felt right" — which is the judgement call this table replaces.
+
+## Plans are not specs and not work items
+
+A plan says *how we intend to do this*. It does not define behaviour, and it does not track state.
+When a plan and a spec disagree the spec wins; when a plan and a work item's status disagree, the
+work item wins. A plan that has started carrying status is one that should have been closed.

package/modules/workflows/rules/reuse-decision.md

@@ -0,0 +1,50 @@
+---
+description: >-
+  How to decide, per technical concern, whether to use what exists, extend it locally, extend it
+  upstream, or hand-roll. Loads when planning work or writing a plan document.
+paths:
+  - "{{plan_path}}/**/*.md"
+  - "{{path}}/**/*.md"
+enforcement: review-only
+---
+
+# The reuse decision
+
+Run this **per concern, not per story.** A piece of work with four distinct technical concerns runs
+the loop four times before anything is sequenced. The most common decomposition failure is
+resolving a story against one existing capability and calling it planned.
+
+## The four branches
+
+| Branch | When | Where the work lands |
+| --- | --- | --- |
+| **Use as-is** | The existing API fully covers the concern, there is no repo-specific gap, and an existing consumer already demonstrates the same usage shape | Wiring only, in the consuming surface |
+| **Extend — locally** | The primitive exists, but the composition around it does not | Here |
+| **Extend — upstream** | The capability is genuinely missing from `{{upstream_repo}}`, not merely unconsumed here, **and** it is general-purpose rather than specific to one consumer | Upstream first, consumed here after |
+| **Hand-roll** | Nothing exists anywhere, and the need is not general enough to justify a shared primitive yet | Here, local only |
+
+*(With no `upstream_repo` configured, the third branch does not apply and the table has three.)*
+
+## The second-consumer threshold
+
+**Hand-roll once. On the second consumer, stop and extract.**
+
+The first hand-roll is cheap and correct — you do not yet know the shape. The second is the
+decision point, and the negative form matters as much as the positive one: **do not build a second
+local copy.** Two copies is where the divergence starts, and by the third nobody can tell which is
+canonical.
+
+This cuts both ways. Extracting on the *first* consumer produces a shared primitive designed
+against one use case, which is the other way to get an abstraction nobody can use.
+
+## When a concern spans a batch
+
+If several pieces of work are being planned together, run the decision across **all** of them
+first and produce **one combined concern table**. A concern shared by two stories should be caught
+once, not solved twice — and the second solution is usually a worse version of the first written
+by someone who did not know the first existed.
+
+## What this does not decide
+
+Sequencing, ownership, and whether the work is worth doing. Those come after, and a reuse decision
+that has quietly answered them is one that skipped a conversation.

package/modules/workflows/skills/decompose/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: decompose
+description: >-
+  Break a request into technical concerns, decide reuse per concern (use as-is / extend locally /
+  extend upstream / hand-roll), pick the planning tier, and sequence by dependency. Use when handed
+  something larger than a single change, when asked to "plan this", "how should we approach this",
+  "break this down", "scope this out", or before starting work whose shape is not obvious. Also use
+  across a batch of related work to catch shared concerns once. Executing a tracked item is
+  /work-item; recording an out-of-scope observation is /record-finding.
+---
+
+# Decompose
+
+Nine numbered steps. Other documents cite them by number — *"resolved at step 4 as extend-local"* —
+so the numbering is stable and worth keeping.
+
+## 1. Anchor
+
+Name the narrowest concrete thing this touches: a file, a symbol, a route, a failing test. If you
+cannot, the request is not yet a piece of work and the next move is a question, not a plan.
+
+## 2. Split into concerns
+
+List the distinct **technical** concerns, not the user-visible steps. "Persist the draft",
+"debounce the input", "authorise the caller" are three concerns; "add the editor" is one story
+containing them.
+
+**Steps 3–4 run per concern.** A story with four concerns runs them four times.
+
+## 3. Look up what exists
+
+For each concern, search before deciding: the shared primitives, the reference implementation, the
+upstream repository if there is one. **Search with the concern's vocabulary, not the story's** —
+this is where a capability that already exists gets missed and rebuilt.
+
+## 4. Decide the branch
+
+Apply the reuse decision table. Record the branch **and the reason**, per concern. A concern whose
+branch is "hand-roll" needs the second-consumer check: is this the first time, or the second?
+
+## 5. Pick the tier
+
+Apply the planning-tier table. **Tier 0 is a real answer** — if every concern resolved to
+use-as-is, write nothing and implement.
+
+## 6. Sequence
+
+Order by **dependency only**, not by size or by what is interesting. If two concerns can proceed
+independently, say so — that is a scheduling fact somebody will want.
+
+For a batch: produce one combined concern table across all the work first, so a shared concern is
+caught once.
+
+## 7. Name what this does not cover
+
+Explicitly, before starting. Out-of-scope written after the fact is a description of what you ran
+out of time for.
+
+## 8. Implement
+
+Following the repo's engineering guidance, not this skill.
+
+## 9. Close
+
+Reconcile: does the spec still describe what was built? Did any concern's branch change during
+execution, and is that recorded with its reason? A plan that silently stopped matching reality
+reads as verified.
+
+## Two failure modes to watch for
+
+- **Resolving the story instead of the concerns.** One search, one answer, four concerns
+  unexamined. This is the common one.
+- **Deciding reuse from a memory of the codebase.** Search at decision time. A recollection of what
+  exists has a shelf life, and the cost of being wrong is a duplicate primitive nobody notices for
+  months.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@rungs/cli",
+  "version": "0.1.0",
+  "description": "Installs and maintains a repository's agentic development system, composed from modules.",
+  "author": "Antoine Dancre",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThroughTheWind/rungs.git"
+  },
+  "homepage": "https://github.com/ThroughTheWind/rungs#readme",
+  "bugs": {
+    "url": "https://github.com/ThroughTheWind/rungs/issues"
+  },
+  "type": "module",
+  "bin": {
+    "rungs": "./src/cli.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "rungs": "node src/cli.ts",
+    "test": "node --test test/"
+  },
+  "files": [
+    "src",
+    "modules"
+  ],
+  "keywords": [
+    "agents",
+    "claude-code",
+    "agent-skills",
+    "scaffolding"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "smol-toml": "^1.8.0"
+  }
+}