finos/morphir-scala / .claude/skills/kb
Manages the Morphir knowledge base under kb/ — OKF bundles and concept documents. Use when adding content to a bundle, creating a new bundle, checking the knowledge base for conformance or provenance drift, building or querying its SQLite index, managing intent through its lifecycle, recording or reading architectural decisions as Decision Records, or navigating, searching and listing its bundles, concepts and links.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 180 B |
| .mill-version | other | 19 B |
| KbCheck.scala | other | 19.7 KB |
| KbDecision.scala | other | 12.6 KB |
| KbIndex.scala | other | 21.9 KB |
| KbIntent.scala | other | 14.0 KB |
| KbIntentEdit.scala | other | 10.9 KB |
| KbModel.scala | other | 11.7 KB |
| KbRefresh.scala | other | 8.9 KB |
| KbRender.scala | other | 9.0 KB |
| KbScaffold.scala | other | 9.5 KB |
| KbStore.scala | other | 12.0 KB |
| KbSync.scala | other | 46.9 KB |
| KbTests.scala | other | 71.5 KB |
| SKILL.md | skill md | 10.8 KB |
| kbexecutable | script | 459 B |
| kb.bat | script | 485 B |
| kb.scala | other | 43.3 KB |
| millexecutable | script | 6.5 KB |
| mill.bat | script | 9.7 KB |
| references/authoring.md | markdown | 4.7 KB |
| references/checks.md | markdown | 12.0 KB |
| references/commands.md | markdown | 12.8 KB |
| references/decisions.md | markdown | 7.4 KB |
| references/divergence.md | markdown | 3.4 KB |
| references/index-db.md | markdown | 5.2 KB |
| references/sync.md | markdown | 16.7 KB |
| test-resources/META-INF/services/kyo.test.Test | other | 503 B |
KbScaffold.scala
View on GitHub//| scalaVersion: 3.9.0
//| moduleDeps: [KbStore.scala]
//| mvnDeps:
//| - io.getkyo::kyo-core:1.0.0-RC7
/** Creating bundles and concepts, and keeping indexes and logs in step.
*
* Scaffolding writes the frontmatter skeleton and wires the concept into its index and log. It deliberately does not
* write prose — that is the agent's job, and a stub that reads as finished is worse than an obvious stub.
*/
import kyo.*
import java.time.LocalDate
case class ScaffoldResult(created: Seq[Path], updated: Seq[Path], notes: Seq[String])
object KbScaffold:
/** kebab-cases a free-form name into a slug usable as a directory or filename. */
def slugify(s: String): String =
s.trim.toLowerCase.replaceAll("[^a-z0-9]+", "-").replaceAll("^-+|-+$", "")
private def yamlStr(s: String): String =
val needsQuote = s.exists(c => ":#{}[]&*!|>'\"%@`,".contains(c)) || s.startsWith(" ") || s.endsWith(" ")
if needsQuote then "\"" + s.replace("\\", "\\\\").replace("\"", "\\\"") + "\"" else s
private def descend(base: Path, relPath: String): Path =
relPath.split('/').filter(_.nonEmpty).foldLeft(base)(_ / _)
// ------------------------------------------------------------- new bundle
def newBundle(
kbRoot: Path,
name: String,
group: Option[String],
title: String,
description: String,
okfVersion: String,
today: LocalDate
): Either[String, ScaffoldResult] < (Sync & Abort[Throwable]) =
Path.run {
val slug = slugify(name)
val dir = group.map(g => descend(kbRoot / "bundles", g) / slug).getOrElse(kbRoot / "bundles" / slug)
dir.exists.map {
case true => Left(s"${KbPath.render(dir)} already exists")
case false =>
val index = dir / "index.md"
val log = dir / "log.md"
val groupDir = group.map(g => descend(kbRoot / "bundles", g))
for
_ <- index.write(indexTemplate(okfVersion, title, description))
_ <- log.write(logTemplate(today))
groupReadmeMissing <- groupDir match
case None => (false: Boolean < (Sync & Abort[Throwable]))
case Some(g) => (g / "README.md").exists.map(!_)
yield Right(ScaffoldResult(
created = Seq(index, log),
updated = Nil,
notes =
Option.when(groupReadmeMissing)(s"grouping directory has no README.md yet: ${groupDir.map(KbPath.render).getOrElse("")}").toSeq ++
Seq(s"add the bundle to the Bundles table in ${KbPath.render(kbRoot / "README.md")}")
))
}
}
private def indexTemplate(okfVersion: String, title: String, description: String): String =
s"""---
|okf_version: "$okfVersion"
|title: ${yamlStr(title)}
|description: ${yamlStr(description)}
|---
|
|# $title
|
|$description
|
|## Orientation
|
|""".stripMargin
private def logTemplate(today: LocalDate): String =
s"""# Log
|
|## $today
|
|* **Creation**: Bundle created.
|""".stripMargin
// ------------------------------------------------------------ add concept
def addConcept(
bundle: Bundle,
relPath: String,
conceptType: String,
title: String,
description: String,
tags: Seq[String],
status: Option[String],
sources: Seq[(Option[String], String, Option[String])],
section: String,
generatedBy: Option[String],
today: LocalDate
): Either[String, ScaffoldResult] < (Sync & Abort[Throwable]) =
Path.run {
val raw = if relPath.endsWith(".md") then relPath else relPath + ".md"
val relSegs = raw.split('/').filter(_.nonEmpty).toSeq
val leaf = relSegs.lastOption.getOrElse("")
// A concept path names a location *inside* the bundle. Without this, `--path ../escaped.md` writes outside it
// while still adding a bundle-relative index entry pointing at nothing.
if raw.startsWith("/") || relSegs.exists(seg => seg == ".." || seg == ".") then
(Left(s"`$relPath` must stay inside the bundle — no leading /, `.` or `..` segments"): Either[String, ScaffoldResult] < (Sync & Abort[Throwable]))
else if relSegs.isEmpty then
(Left("give a path within the bundle"): Either[String, ScaffoldResult] < (Sync & Abort[Throwable]))
else if leaf == "index.md" || leaf == "log.md" then
(Left(s"$leaf is a reserved OKF filename"): Either[String, ScaffoldResult] < (Sync & Abort[Throwable]))
else
val target = relSegs.foldLeft(bundle.root)(_ / _)
target.exists.map {
case true => Left(s"${KbPath.render(target)} already exists")
case false =>
val bundlePath = relSegs.mkString("/", "/", "")
// A concept in a subdirectory belongs in that subdirectory's index when one exists.
val idxDoc = bundle.subIndexes
.find(i => relSegs.length > 1 && i.rel.dropRight(1) == relSegs.dropRight(1))
.getOrElse(bundle.index)
for
_ <- target.write(conceptTemplate(conceptType, title, description, tags, status, sources, generatedBy, today))
_ <- insertIndexEntry(idxDoc.file, section, title, bundlePath, description)
_ <- bundle.log match
case None => ((): Unit < (Sync & Abort[Throwable]))
case Some(l) => appendLogEntry(l.file, today, s"**Creation**: Added [$title]($bundlePath).")
yield Right(ScaffoldResult(
created = Seq(target),
updated = Seq(idxDoc.file) ++ bundle.log.map(_.file),
notes = Option.when(bundle.log.isEmpty)("bundle has no log.md — creation was not recorded").toSeq
))
}
}
private def conceptTemplate(
conceptType: String,
title: String,
description: String,
tags: Seq[String],
status: Option[String],
sources: Seq[(Option[String], String, Option[String])],
generatedBy: Option[String],
today: LocalDate
): String =
val sb = StringBuilder()
sb ++= "---\n"
sb ++= s"type: ${yamlStr(conceptType)}\n"
sb ++= s"title: ${yamlStr(title)}\n"
sb ++= s"description: ${yamlStr(description)}\n"
if tags.nonEmpty then sb ++= s"tags: [${tags.map(slugify).mkString(", ")}]\n"
status.foreach(s => sb ++= s"status: $s\n")
if sources.nonEmpty then
sb ++= "sources:\n"
sources.foreach { (id, resource, srcTitle) =>
sb ++= " - "
id.foreach(i => sb ++= s"id: $i\n ")
sb ++= s"resource: $resource\n"
srcTitle.foreach(t => sb ++= s" title: ${yamlStr(t)}\n")
}
generatedBy.foreach { by =>
sb ++= "generated:\n"
sb ++= s" by: $by\n"
sb ++= s" at: ${today}T00:00:00Z\n"
}
sb ++= "---\n\n"
sb ++= s"# $title\n\n"
sb ++= s"$description\n\n"
sb ++= "<!-- TODO: write the concept body. Delete this comment when done. -->\n"
sb.toString
/** Adds `* [title](path) - description` under `## section`, creating the section if it is absent. */
def insertIndexEntry(index: Path, section: String, title: String, bundlePath: String, description: String): Unit < (Sync & Abort[Throwable]) =
Path.run {
index.read.map { text =>
val entry = s"* [$title]($bundlePath) - ${description.trim}"
val lines = text.replace("\r\n", "\n").linesIterator.toVector
val headIdx = lines.indexWhere(_.trim.equalsIgnoreCase(s"## $section"))
val updated =
if headIdx < 0 then
lines.reverse.dropWhile(_.trim.isEmpty).reverse ++ Vector("", s"## $section", "", entry)
else
// Append after the last bullet of that section, before the next heading.
val nextHead = lines.indexWhere(_.startsWith("## "), headIdx + 1) match
case -1 => lines.length
case n => n
val body = lines.slice(headIdx + 1, nextHead)
val lastBullet = body.lastIndexWhere(l => l.trim.startsWith("*") || l.trim.startsWith("-"))
// With no bullets yet, land at the end of the section so the blank line after the heading survives.
val at = if lastBullet < 0 then nextHead else headIdx + 1 + lastBullet + 1
lines.take(at) ++ Vector(entry) ++ lines.drop(at)
index.write(updated.mkString("\n").stripTrailing() + "\n")
}
}
/** Adds a bullet under `## <today>`, creating that date section at the top (newest first) when absent. */
def appendLogEntry(log: Path, today: LocalDate, entry: String): Unit < (Sync & Abort[Throwable]) =
Path.run {
log.read.map { text =>
val lines = text.replace("\r\n", "\n").linesIterator.toVector
val bullet = s"* $entry"
val dateHead = s"## $today"
val idx = lines.indexWhere(_.trim == dateHead)
val updated =
if idx >= 0 then
val nextHead = lines.indexWhere(_.startsWith("## "), idx + 1) match
case -1 => lines.length
case n => n
val lastBullet = lines.slice(idx + 1, nextHead).lastIndexWhere(_.trim.startsWith("*"))
val at = if lastBullet < 0 then nextHead else idx + 1 + lastBullet + 1
lines.take(at) ++ Vector(bullet) ++ lines.drop(at)
else
val firstHead = lines.indexWhere(_.startsWith("## "))
val at = if firstHead < 0 then lines.length else firstHead
val prefix = lines.take(at).reverse.dropWhile(_.trim.isEmpty).reverse
prefix ++ Vector("", dateHead, "", bullet, "") ++ lines.drop(at)
log.write(updated.mkString("\n").stripTrailing() + "\n")
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |