skill2framework 0.3.1__py3-none-any.whl

skill2framework/__init__.py

@@ -0,0 +1,19 @@
+"""skill2framework — the chapter rung of the ladder (the skill2framework chain's deterministic glue).
+
+A FRAMEWORK is a chapter: Blog 1 (narrative) + Blog 2 (deep dive) + a plugin +
+the {aios}-volume index skill, folded into the author's SkillTome. The LLM
+stages are the six `skills/skill2framework/*` prompt-skills; this package is
+the deterministic machinery they run:
+
+    journey.JourneyCore + render_blog1   — the Blog-1 model + renderer (fill, never hand-write)
+    chapter.assemble_chapter             — blogs → self-contained chapter dir (links/CTAs/manifest)
+    plugin.package_plugin                — framework skill + chapter → installable plugin dir
+    fold.fold_into_tome                  — the terminal bind (delegates to skilltree.tome.fold)
+"""
+from .chapter import assemble_chapter
+from .fold import fold_into_tome
+from .journey import JourneyCore, render_blog1
+from .plugin import package_plugin
+
+__all__ = ["JourneyCore", "render_blog1", "assemble_chapter", "package_plugin",
+           "fold_into_tome"]

skill2framework/chapter.py

@@ -0,0 +1,73 @@
+"""chapter.py — assemble a framework CHAPTER from two rendered blog posts.
+
+A chapter = Blog 1 (narrative) + Blog 2 (deep dive), copied VERBATIM into one
+self-contained dir, wired with relative cross-links + CTAs, plus a `chapter.md`
+manifest (what the framework skill and the tome point at). The blogs' prose is
+never rewritten — only the link/CTA block and the manifest are added.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# "## Chapter links", not "## Links": render_blog1 already emits a "## Links" section
+# when the core carries URLs — the first dogfood produced a doubled heading. Distinct
+# heading = no collision, and the chapter block stays a pure addition.
+def _links_block(entries: list[str], cta: str) -> str:
+    return "\n\n## Chapter links\n\n" + "\n".join(f"- {e}" for e in entries) + f"\n\n> **{cta}**\n"
+
+
+def assemble_chapter(blog1_path: str | Path, blog2_path: str | Path, *,
+                     chapter_dir: str | Path, framework_name: str,
+                     plugin_url: str = "", skill_links: list[str] | None = None,
+                     abstract: str = "") -> dict:
+    """Copy blog1/blog2 into `chapter_dir`, append the cross-link/CTA block to
+    each, and write the `chapter.md` manifest. Returns a report of what was
+    written. Idempotent: re-running overwrites the chapter dir's three files.
+    `skill_links` entries are "Name|url" pairs.
+    """
+    b1, b2 = Path(blog1_path), Path(blog2_path)
+    if not b1.is_file():
+        return {"ok": False, "error": f"blog1 not found: {b1}"}
+    if not b2.is_file():
+        return {"ok": False, "error": f"blog2 not found: {b2}"}
+    out = Path(chapter_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    skills = skill_links or []
+
+    def skill_entries() -> list[str]:
+        entries = []
+        for pair in skills:
+            name, _, url = pair.partition("|")
+            entries.append(f"Skill — {name.strip()}: {url.strip() or '(link pending)'}")
+        return entries
+
+    blog1 = b1.read_text(encoding="utf-8").rstrip()
+    blog1 += _links_block(
+        ["Deep dive — how it works: ./blog2.md"]
+        + ([f"Get the plugin: {plugin_url}"] if plugin_url else [])
+        + skill_entries(),
+        cta=f"Install the plugin and run it yourself: {plugin_url or './blog2.md'}")
+    (out / "blog1.md").write_text(blog1 + "\n", encoding="utf-8")
+
+    blog2 = b2.read_text(encoding="utf-8").rstrip()
+    blog2 += _links_block(
+        ["The story — why this exists: ./blog1.md"]
+        + ([f"Get the plugin: {plugin_url}"] if plugin_url else []),
+        cta=f"Read the story, then install: {plugin_url or './blog1.md'}")
+    (out / "blog2.md").write_text(blog2 + "\n", encoding="utf-8")
+
+    manifest = [f"# {framework_name} — chapter", ""]
+    if abstract:
+        manifest += [abstract, ""]
+    manifest += ["## Contents", "",
+                 "1. The narrative: ./blog1.md",
+                 "2. The deep dive: ./blog2.md", ""]
+    if plugin_url:
+        manifest += [f"Plugin: {plugin_url}", ""]
+    if skills:
+        manifest += ["## Skills", ""] + [f"- {e}" for e in skill_entries()] + [""]
+    (out / "chapter.md").write_text("\n".join(manifest), encoding="utf-8")
+
+    return {"ok": True, "chapter_dir": str(out),
+            "files": ["blog1.md", "blog2.md", "chapter.md"]}

skill2framework/fold.py

@@ -0,0 +1,29 @@
+"""fold.py — the terminal stage: fold a framework into the author's SkillTome.
+
+Delegates to skilltree's Move-1 bind op (`skilltree.tome.fold`, agent-skilltree
+>= 0.3.0): the tome is a SkillTree whose volume nodes carry `frameworks` rows in
+the manifest, rendered as the generated `## Frameworks` table. Folding is a CODE
+op — idempotent, one row per framework, the manifest is the source of truth —
+not an LLM hand-editing a table. ("nomicon" is the legacy alias for the
+SkillVolume/SkillTome this folds into.)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from skilltree.tome import fold as _tome_fold
+
+
+def fold_into_tome(framework_skill_dir: str | Path, *, volume: str,
+                   tome_root: str | Path, what_for: str | None = None,
+                   name: str | None = None, relative: bool = True) -> dict:
+    """Register a framework's skill dir as a row on a tome volume node.
+
+    framework_skill_dir  the framework skill dir (holds SKILL.md — the {aios}-volume)
+    volume               the volume node in the tome tree (name or coord)
+    tome_root            the materialized tome SkillTree root (holds skilltree.json)
+    relative             default True: rows are stored holder-relative so a
+                         repo-committed tome validates/projects from any checkout
+    """
+    return _tome_fold(framework_skill_dir, into=volume, tree_root=tome_root,
+                      what_for=what_for, name=name, relative=relative)

skill2framework/journey.py

@@ -0,0 +1,65 @@
+"""journey.py — the JourneyCore model + the deterministic Blog-1 renderer.
+
+The BLOG ORGAN law: the narrative blog is never hand-written — an agent FILLS
+this model from the AIOS's real journey (its CLAUDE.md / README / dev log) and
+runs `render_blog1`, so the output shape is deterministic and every datum
+renders exactly once. This is the DIY (dependency-free) renderer; the fields
+are the Hero-arc set the skill2framework pipeline fills.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class JourneyCore:
+    journey_name: str                 # the AIOS/framework this is the journey OF
+    domain: str                       # free-form domain label ("publishing", "health", …)
+    hook: str                         # AUTHORED opening sentence (never string-derived)
+    status_quo: str                   # "I was …" — the painful state BEFORE
+    obstacle: str                     # "I identified … when …" — the blocker + the moment seen
+    overcome: str                     # "I finally … and tried …" — the shift + what was built
+    accomplishment: str               # "… and now …" — the result as feeling + proof
+    the_boon: str                     # the ONE transferable reframe (not the artifact)
+    demo_description: str             # what a demo would show
+    why_this_matters: str             # the meta-level
+    universal_application: str        # how a reader applies it to THEIR domain
+    github_url: str = ""              # the code
+    plugin_url: str = ""              # the installable face
+    deep_dive_url: str = ""           # Blog 2, when known (the chapter step wires it later)
+    skill_urls: list[str] = field(default_factory=list)   # "Name|url" pairs
+    hashtags: list[str] = field(default_factory=list)
+
+
+def render_blog1(core: JourneyCore) -> str:
+    """Render Blog 1 (the narrative chapter-opener) from a filled JourneyCore.
+
+    Deterministic template: the authored hook opens, each field renders once, the
+    links/CTA block closes. Optional fields render only when present.
+    """
+    lines: list[str] = [f"# {core.journey_name} — the story", ""]
+    lines += [f"*{core.hook}*", ""]
+    lines += ["## Where I was", "", core.status_quo, ""]
+    lines += ["## The wall", "", core.obstacle, ""]
+    lines += ["## The turn", "", core.overcome, ""]
+    lines += ["## Where I am now", "", core.accomplishment, ""]
+    lines += ["## The boon — what transfers", "", core.the_boon, ""]
+    lines += ["## See it", "", core.demo_description, ""]
+    lines += ["## Why this matters", "", core.why_this_matters, ""]
+    lines += ["## Take action", "", core.universal_application, ""]
+
+    links: list[str] = []
+    if core.deep_dive_url:
+        links.append(f"- Deep dive — how it works: {core.deep_dive_url}")
+    if core.plugin_url:
+        links.append(f"- Get the plugin: {core.plugin_url}")
+    if core.github_url and core.github_url != core.plugin_url:
+        links.append(f"- The code: {core.github_url}")
+    for pair in core.skill_urls:
+        name, _, url = pair.partition("|")
+        links.append(f"- Skill — {name.strip()}: {url.strip() or '(link pending)'}")
+    if links:
+        lines += ["## Links", ""] + links + [""]
+    if core.hashtags:
+        lines += [" ".join(f"#{h.lstrip('#')}" for h in core.hashtags), ""]
+    return "\n".join(lines)

skill2framework/plugin.py

@@ -0,0 +1,62 @@
+"""plugin.py — package a framework as a Claude Code plugin (its operational face).
+
+A framework package is ALWAYS a plugin. This assembles a valid plugin dir from
+the generated framework skill (the {aios}-volume index/router) + its chapter,
+and repaths the skill's chapter links to the bundled copy so the plugin is
+self-contained. Only the chapter link paths are rewritten — never the prose.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+
+def package_plugin(framework_skill_path: str | Path, chapter_dir: str | Path, *,
+                   out_dir: str | Path, name: str, author: str = "",
+                   description: str = "", version: str = "0.1.0") -> dict:
+    """Build `<out_dir>/` as a plugin: plugin.json + skills/<name>/SKILL.md +
+    the chapter bundled under resources/chapter/, chapter links repathed to the
+    bundle. Returns a report with the repath count and a resolution check."""
+    skill_src = Path(framework_skill_path)
+    chap = Path(chapter_dir)
+    if not skill_src.is_file():
+        return {"ok": False, "error": f"framework skill not found: {skill_src}"}
+    if not (chap / "chapter.md").is_file():
+        return {"ok": False, "error": f"no chapter.md in chapter dir: {chap}"}
+
+    out = Path(out_dir)
+    skill_dir = out / "skills" / name
+    res_dir = skill_dir / "resources" / "chapter"
+    res_dir.mkdir(parents=True, exist_ok=True)
+
+    for f in ("blog1.md", "blog2.md", "chapter.md"):
+        if (chap / f).is_file():
+            shutil.copy2(chap / f, res_dir / f)
+
+    # repath: any PATH that ends in a chapter file — a token containing a "/" before
+    # the filename, or a bare-filename markdown link TARGET — becomes the bundled
+    # relative reference. Bare filenames in display text (e.g. the "[blog1.md]" label
+    # of a link) are NOT paths and stay untouched (the first dogfood's repath mangled
+    # them). Nothing else in the body changes.
+    body = skill_src.read_text(encoding="utf-8")
+    body, n1 = re.subn(r"[^\s()`\[\]]*/(blog1\.md|blog2\.md|chapter\.md)\b",
+                       r"./resources/chapter/\1", body)
+    body, n2 = re.subn(r"\((blog1\.md|blog2\.md|chapter\.md)\)",
+                       r"(./resources/chapter/\1)", body)
+    n = n1 + n2
+    (skill_dir / "SKILL.md").write_text(body, encoding="utf-8")
+
+    manifest = {"name": name, "version": version,
+                "description": description or f"The {name} framework plugin.",
+                "author": author}
+    (out / "plugin.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    # resolution check: every bundled reference in the written skill must exist
+    dead = [m.group(0) for m in
+            re.finditer(r"\./resources/chapter/(?:blog1|blog2|chapter)\.md",
+                        (skill_dir / "SKILL.md").read_text(encoding="utf-8"))
+            if not (skill_dir / m.group(0)).is_file()]
+    return {"ok": not dead, "plugin_dir": str(out), "repathed": n,
+            "dead_refs": dead}

skill2framework-0.3.1.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: skill2framework
+Version: 0.3.1
+Summary: The chapter rung: blogs → chapter → plugin → fold into the SkillTome (the skill2framework chain's deterministic glue)
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-skilltree>=0.4.0
+Dynamic: license-file
+
+# skill2framework — the chapter rung: a finished agent turned into a chapter of a SkillTome
+
+`skill2framework` is the chapter rung of [ChainCompiler](https://github.com/sancovp/chaincompiler), a compiler-compiler for
+cognition. It is the deterministic part of turning a finished agent into a chapter of its author's SkillTome. The
+`skill2framework` skills the ChainCompiler plugin ships write two posts about the agent — a narrative post and a deep
+dive — and this package does everything after them:
+
+- `assemble_chapter(blog1, blog2, chapter_dir=…, framework_name=…)` makes the two posts one self-contained chapter folder,
+  its links, calls to action and manifest included;
+- `package_plugin(framework_skill, chapter_dir, out_dir=…, name=…)` packages the framework's skill and its chapter as an
+  installable plugin, repathing the chapter's links into the bundle and checking that each resolves;
+- `fold_into_tome(framework_skill_dir, volume=…, tome_root=…)` folds the framework into the tome, through
+  `agent-skilltree`'s `tome.fold`;
+- `JourneyCore` and `render_blog1` are the narrative post's model and its renderer, so the post is filled in and never
+  written by hand.
+
+## Install
+
+```bash
+pip install skill2framework
+```
+
+It brings `agent-skilltree` from PyPI. To work on it, clone the [repository](https://github.com/sancovp/chaincompiler)
+and run `./install.sh`, which installs all fifteen packages editable.
+
+## Use
+
+```python
+from skill2framework import assemble_chapter, fold_into_tome, package_plugin
+```
+
+Each call takes the files the one before it wrote; the `skill2framework` skills in the plugin run them in order.
+
+## Its design
+
+The repository's [`DESIGN.md`](https://github.com/sancovp/chaincompiler/blob/main/DESIGN.md) §13.
+
+## License
+
+MIT.

skill2framework-0.3.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+skill2framework/__init__.py,sha256=PZNkeovCG3hnjgQHC2HKTgLdMtwlz2Zto-F2qI7HDDI,1040
+skill2framework/chapter.py,sha256=DLXvQZ86rFykTlwJjfmbs5CzGYE37IOBKN4v-DwpgPU,3312
+skill2framework/fold.py,sha256=b4zyVdrR5ywz13n0_N3poaeesdHFCssVABpT_jNZ4OY,1481
+skill2framework/journey.py,sha256=Q9WOsewWKeTzqb2NO_2Qug9R_kqQ_M3XZGAQQBCQP6U,3383
+skill2framework/plugin.py,sha256=J2bkauvkEEvoqh6GPagB1jTaIYkudz9glQYFi-JQXW0,3019
+skill2framework-0.3.1.dist-info/licenses/LICENSE,sha256=ffOw8Kmv_QBeCF_DLeFnCZ-t36WSZJ7ePU8nsibXqZ8,1064
+skill2framework-0.3.1.dist-info/METADATA,sha256=cOebxZb7zHCPFTZMFYeFc19eZSD--6sJcPaCSK6HFX8,2149
+skill2framework-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+skill2framework-0.3.1.dist-info/top_level.txt,sha256=dGGUD8JzKiOreZcYUpJmEU69HFogxulL--jqPblfv30,16
+skill2framework-0.3.1.dist-info/RECORD,,

skill2framework-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

skill2framework-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sancovp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skill2framework-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+skill2framework