code-puppy-core-plugins 0.0.91__tar.gz → 0.0.92__tar.gz

{code_puppy_core_plugins-0.0.91 → code_puppy_core_plugins-0.0.92}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.91
+Version: 0.0.92
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins
@@ -108,6 +108,13 @@ player can play it. Linux uses `notify-send` for desktop notifications when it
 is installed; Windows uses a best-effort PowerShell toast. No external Python
 dependencies are required.
 
+## pstack
+
+The `pstack` plugin bundles poteto's [pstack](https://github.com/cursor/plugins/tree/main/pstack)
+skill pack (MIT, Lauren Tan), adapted from Cursor to Code Puppy. It is disabled
+by default. `/pstack` describes it and `/pstack on` enables it. Details are in
+[`code_puppy_core_plugins/pstack/README.md`](code_puppy_core_plugins/pstack/README.md).
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

{code_puppy_core_plugins-0.0.91 → code_puppy_core_plugins-0.0.92}/README.md

@@ -63,6 +63,13 @@ player can play it. Linux uses `notify-send` for desktop notifications when it
 is installed; Windows uses a best-effort PowerShell toast. No external Python
 dependencies are required.
 
+## pstack
+
+The `pstack` plugin bundles poteto's [pstack](https://github.com/cursor/plugins/tree/main/pstack)
+skill pack (MIT, Lauren Tan), adapted from Cursor to Code Puppy. It is disabled
+by default. `/pstack` describes it and `/pstack on` enables it. Details are in
+[`code_puppy_core_plugins/pstack/README.md`](code_puppy_core_plugins/pstack/README.md).
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

code_puppy_core_plugins-0.0.92/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,127 @@
+# Third-Party Notices
+
+This package includes material derived from the third-party projects listed
+below. Each remains under its own license; the full license text is either
+reproduced here or shipped next to the derived code, as noted.
+
+## jg
+
+- Source: https://github.com/remotehostai/jg (version 1.0.1, commit
+  `e4f464467130da8b60ee46f93bc6732f5c9bd196`)
+- License: MIT
+- Used in `code_puppy_core_plugins/jev_grep/`:
+  - `chunks.py`: ported from `src/chunks.mjs` (line windows, Python AST
+    partitioning, merging of short adjacent declarations)
+  - `retrieve.py`: ported from `src/retrieve.mjs` (BM25 ranking, identifier
+    term splitting, synonym groups)
+  - `search.py`: adapted from `src/search.mjs` (overlapping-window
+    de-duplication, narrower evidence block selection)
+
+```
+MIT License
+
+Copyright (c) 2026 Remotehost
+
+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.
+```
+
+## DeepSeek Harness
+
+- Source: https://github.com/deepseek-ai/DeepSeek-Harness
+- License: MIT, Copyright (c) 2026 DeepSeek
+- Used in `code_puppy_core_plugins/spill/`: ported spill design. The full
+  license text ships alongside it in `code_puppy_core_plugins/spill/LICENSE.deepseek`.
+
+## llxprt-code
+
+- Source: https://github.com/vybestack/llxprt-code
+- License: Apache-2.0
+- Used in `code_puppy_core_plugins/theme/`: the Green Screen theme's phosphor
+  color values. Attribution only; no llxprt-code source code is included.
+
+## pstack
+
+- Source: https://github.com/cursor/plugins/tree/main/pstack (version 0.15.23,
+  commit `c86f349b102feb91f1966f8a6a60882a4e601b50`)
+- Author: Lauren Tan (poteto)
+- License: MIT
+- Vendored verbatim in `code_puppy_core_plugins/pstack/vendor/pstack/`: `skills/`,
+  `agents/`, `automations/`, the markdown of `docs/guide/`, `README.md`,
+  `plugin.json`, and `LICENSE`. Per-file SHA-256 hashes are recorded in
+  `code_puppy_core_plugins/pstack/vendor/UPSTREAM.json`. Code Puppy specific
+  translation happens at load time in `code_puppy_core_plugins/pstack/adapter.py`;
+  no vendored file is modified.
+
+```
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+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.
+```
+
+## cursor-team-kit (three skills)
+
+- Source: https://github.com/cursor/plugins/tree/main/cursor-team-kit (same
+  commit `c86f349b102feb91f1966f8a6a60882a4e601b50`)
+- Author: Cursor
+- License: MIT
+- Vendored verbatim in `code_puppy_core_plugins/pstack/vendor/cursor-team-kit/`: the
+  `deslop`, `control-ui` and `control-cli` skills that pstack invokes by name,
+  and `LICENSE`. Hashes are recorded in the same `UPSTREAM.json`.
+
+```
+MIT License
+
+Copyright (c) 2026 Cursor
+
+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.
+```

code_puppy_core_plugins-0.0.92/code_puppy_core_plugins/pstack/README.md

@@ -0,0 +1,81 @@
+# pstack for Code Puppy
+
+[pstack](https://github.com/cursor/plugins/tree/main/pstack) is poteto's
+(Lauren Tan) agent skill pack for Cursor: playbooks for features, bug fixes,
+perf work and reviews, plus 24 one-rule engineering principles. This plugin
+vendors it at a pinned commit and adapts it to Code Puppy at load time.
+
+## Turning it on
+
+The plugin ships with the core bundle but is **off by default**: no skills,
+agents, tools or prompt text until you opt in.
+
+```text
+/pstack          # what it adds, and whether it is on
+/pstack on       # same as /set pstack=true
+/pstack off
+```
+
+The switch takes effect on the next prompt; no restart. `/plugins` can still
+disable the plugin outright, which also removes `/pstack`.
+
+## What you get
+
+| Piece | Code Puppy surface |
+|---|---|
+| 28 skills (`poteto-mode`, `how`, `why`, `architect`, `tdd`, `interrogate`, `unslop`, ...) | `register_skills`; each is also a `/<name>` slash command |
+| `deslop`, `control-ui`, `control-cli` from Cursor's `cursor-team-kit` | Registered the same way, because pstack's playbooks call them by name |
+| `create-skill` (written for this plugin; Cursor's is an editor built-in) | Draft, validate, test and tune skills. `python -m code_puppy_core_plugins.pstack.skill_validator <dir>` checks a skill with Code Puppy's own loader |
+| 24 `principle-*` leaves | One `pstack-principles` index skill; leaves are read on demand |
+| `poteto-agent`, `comment-sicko` | `register_agents` (invokable via `invoke_agent`, selectable with `/agent`) |
+| Routing rules (when to reach for which skill) | `load_prompt`, about 350 tokens |
+| `/setup-pstack` model roles | `~/.code_puppy/pstack/pstack-models.md`, injected into the prompt |
+| Per-role models | `list_available_models` + `invoke_agent_with_model` added to `code-puppy` |
+| `/pstack [on\|off]` | The switch, plus pin, skill groups and model-role file status |
+
+Skills carry `pstack*` tags, so `namespace_skill_search` lists the pack as five
+groups (`pstack`, `pstack-understand`, `pstack-design`, `pstack-verify`,
+`pstack-write`) instead of 33 lines.
+
+Start with `/poteto-mode <task>`. `/poteto-help` explains the rest.
+
+## How the adaptation works
+
+Vendored files under `vendor/` mirror the cursor/plugins layout (`pstack/`, plus the three `cursor-team-kit/` skills) and are
+byte-identical to upstream. `adapter.py` does all translation while rendering:
+
+- **Rewrites** of unambiguous names: `~/.cursor/rules/pstack-models.mdc`,
+  `.cursor/skills/`, `AskQuestion`, "the Task tool".
+- **A glossary** prepended to each skill, containing only the entries its body
+  needs: `Task`/`subagent_type` to `invoke_agent`, a per-spawn `model` to
+  `invoke_agent_with_model`, `run_in_background` to `background=True`,
+  transcripts to Code Puppy's autosave dirs, the bundled `cursor-team-kit`
+  skills to `activate_skill`, and the remaining Cursor-only extras (Bugbot,
+  cloud VMs, other team-kit skills) to "use an installed equivalent or skip".
+- **An absolute path anchor**, because Code Puppy materializes only `SKILL.md`
+  into its skill cache. Relative `references/`, `playbooks/` and
+  `../<skill>/SKILL.md` links resolve against the vendored directory.
+
+Not registered: `make-bot-ui` (drives Cursor's Grok Bot webhook routines) and
+the dormant `automations/benny` pack (Cursor Automations). Both stay vendored
+for reference. The `docs/guide` images were dropped (2+ MB of screenshots).
+
+## Updating upstream
+
+```bash
+python scripts/refresh_pstack_upstream.py --commit <sha>
+uv run pytest tests/pstack --no-cov
+```
+
+The script fetches `pstack/` and `cursor-team-kit/` at that commit, replaces
+the vendor tree, and rewrites `vendor/UPSTREAM.json`
+(commit, version, per-file SHA-256). The integrity test fails until every new
+upstream skill is classified in `catalog.py`, and the glossary tests flag new
+Cursor vocabulary that no glossary entry covers.
+
+## License
+
+The plugin code is MIT, like the rest of the bundle. pstack is MIT, Copyright (c) 2026
+Lauren Tan; its license ships in `vendor/pstack/LICENSE` and
+the bundle's `THIRD_PARTY_NOTICES.md`. The three `cursor-team-kit` skills are MIT,
+Copyright (c) 2026 Cursor, with their license in `vendor/cursor-team-kit/LICENSE`.

code_puppy_core_plugins-0.0.92/code_puppy_core_plugins/pstack/__init__.py

@@ -0,0 +1,8 @@
+"""pstack for Code Puppy: poteto's skills and engineering principles.
+
+The upstream pack is vendored verbatim under ``vendor/pstack`` (see
+``vendor/UPSTREAM.json`` for the pinned commit). Everything Code Puppy
+specific, from frontmatter normalization to the Cursor-to-Code-Puppy tool
+glossary, is applied at registration time in ``adapter.py`` so a refresh never
+has to hand-edit vendored files.
+"""

code_puppy_core_plugins-0.0.92/code_puppy_core_plugins/pstack/adapter.py

@@ -0,0 +1,269 @@
+"""Translate vendored pstack markdown into Code Puppy skills and prompts.
+
+Vendored files stay byte-identical to upstream. Everything Cursor-specific is
+handled here at render time, in two layers:
+
+1. ``REWRITES``: exact-substring swaps for paths and tool names whose Code
+   Puppy equivalent is unambiguous.
+2. A glossary prepended to every rendered skill and agent prompt for the
+   primitives that need judgment (subagent spawns, per-call models, todo
+   lists, transcripts, Cursor-only products).
+
+Bundled files are never copied into the skill cache, so each preamble names
+the absolute vendored directory that relative paths resolve against.
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from dataclasses import dataclass
+from pathlib import Path
+
+from code_puppy import config as cp_config
+from code_puppy_core_plugins.pstack.catalog import (
+    COMPANION_SKILLS,
+    CORE_NAMESPACE,
+    PRINCIPLES_INDEX_NAME,
+    VendoredSkill,
+    namespace,
+    principles,
+)
+from code_puppy_core_plugins.pstack.upstream import PSTACK, SKILLS_DIR, Origin, load_pin
+
+MODELS_FILE_NAME = "pstack-models.md"
+# The orchestrator reads playbooks and sibling skills raw, so it gets every
+# glossary entry rather than only those its own body triggers.
+FULL_GLOSSARY = frozenset({"poteto-mode"})
+USER_SKILLS_DIR = "~/.code_puppy/skills/"
+PROJECT_SKILLS_DIR = ".code_puppy/skills/"
+
+
+def models_file() -> Path:
+    """Code Puppy's stand-in for Cursor's always-applied ``pstack-models.mdc``."""
+    return Path(cp_config.CONFIG_DIR) / "pstack" / MODELS_FILE_NAME
+
+
+def _rewrites() -> tuple[tuple[str, str], ...]:
+    # Longest match first: shorter keys are suffixes of longer ones.
+    return (
+        ("~/.cursor/rules/pstack-models.mdc", str(models_file())),
+        ("pstack-models.mdc", MODELS_FILE_NAME),
+        ("~/.cursor/skills/", USER_SKILLS_DIR),
+        (".cursor/skills/", PROJECT_SKILLS_DIR),
+        ("the Task tool", "`invoke_agent`"),
+        ("`AskQuestion`", "`ask_user_question`"),
+        ("AskQuestion", "`ask_user_question`"),
+        # Cursor's built-in create-skill is replaced by this plugin's own.
+        ("Cursor's built-in `create-skill` skill", "the `create-skill` skill"),
+        ("Cursor's built-in `create-skill`", "the `create-skill` skill"),
+        (" (Cursor's built-in for authoring SKILL.md files)", ""),
+        (
+            "`/loop` and `/create-skill` are Cursor built-ins.",
+            "`/loop` is a Cursor built-in; `/create-skill` ships with this plugin.",
+        ),
+        # Native skills run plugin modules with Code Puppy's own interpreter.
+        ("$CODE_PUPPY_PYTHON", sys.executable),
+    )
+
+
+def translate(text: str) -> str:
+    """Apply the unambiguous Cursor-to-Code-Puppy substring rewrites."""
+    for old, new in _rewrites():
+        text = text.replace(old, new)
+    return text
+
+
+@dataclass(frozen=True)
+class GlossaryEntry:
+    """One Cursor primitive, the body substrings that mention it, its mapping."""
+
+    triggers: tuple[str, ...]
+    text: str
+
+
+def _entries() -> tuple[GlossaryEntry, ...]:
+    sessions = Path(cp_config.DATA_DIR) / "subagent_sessions"
+    return (
+        GlossaryEntry(
+            ("Task", "subagent", "spawn"),
+            "Spawning a subagent (a `Task` call): `invoke_agent(agent_name, "
+            'prompt)`. `subagent_type: "poteto-agent"` means `agent_name='
+            '"poteto-agent"`; `generalPurpose` means `agent_name="code-puppy"`. '
+            '"In one message" means start the calls together (in code mode, '
+            "`asyncio.gather` in one `run_code`).",
+        ),
+        GlossaryEntry(
+            ("`model`", "grok-", "claude-", "inherit-parent"),
+            "A per-spawn `model`: pick the closest alias from "
+            "`list_available_models()` and call `invoke_agent_with_model("
+            "agent_name, prompt, model_name)`. Use plain `invoke_agent` for "
+            "`inherit-parent`, `auto`, a missing role line, or when no alias "
+            "matches or that tool is unavailable.",
+        ),
+        GlossaryEntry(
+            ("run_in_background", "readonly", "environment", "cloud"),
+            "`run_in_background: true`: `invoke_agent(..., background=True)`. "
+            "`readonly: true` has no flag; tell the subagent not to edit files. "
+            '`environment: "cloud"` runs locally; give each parallel writer its '
+            "own `git worktree`.",
+        ),
+        GlossaryEntry(
+            ("AskQuestion", "`Read`", "Glob", "Shell"),
+            "`AskQuestion`: `ask_user_question`. Read, Grep, Glob, Shell: "
+            "`read_file`, `grep`, `list_files`, `shell`.",
+        ),
+        GlossaryEntry(
+            ("pstack-models", "setup-pstack"),
+            f"The `pstack-models.mdc` rule is `{models_file()}`; it is injected "
+            "into the system prompt when present, and `/setup-pstack` writes it.",
+        ),
+        GlossaryEntry(
+            (".cursor/skills", "create-skill"),
+            f"Skill dirs `.cursor/skills/` and `~/.cursor/skills/` are "
+            f"`{PROJECT_SKILLS_DIR}` and `{USER_SKILLS_DIR}`. Author or edit "
+            "skills there with the bundled `create-skill` skill.",
+        ),
+        GlossaryEntry(
+            ("disable-model-invocation",),
+            "Code Puppy has no `disable-model-invocation`; every enabled skill "
+            "is listed. Make the description trigger only on the skill's name "
+            "or `/<name>` instead.",
+        ),
+        GlossaryEntry(
+            ("principle",),
+            "Principle skills are not registered one by one. "
+            f'`activate_skill("{PRINCIPLES_INDEX_NAME}")` lists them; each leaf '
+            f"is `{SKILLS_DIR}/principle-<name>/SKILL.md`.",
+        ),
+        GlossaryEntry(
+            ("transcript",),
+            "Chat transcripts (`agent-transcripts/`): "
+            f"`{cp_config.AUTOSAVE_DIR}` and `{sessions}`.",
+        ),
+        GlossaryEntry(
+            ("todo", "Todo"),
+            "The todo list: a checklist you keep current in your replies, or in "
+            "a scratch markdown file on long runs.",
+        ),
+        GlossaryEntry(
+            ("/loop",),
+            "`/loop`: `/goal <predicate>` when the wiggum plugin is installed; "
+            "otherwise keep working in-turn and poll with `shell`.",
+        ),
+        GlossaryEntry(
+            ("cursor-team-kit", "deslop", "control-"),
+            "The `cursor-team-kit` skills pstack calls ship with this plugin: "
+            + ", ".join(f"`{name}`" for name in COMPANION_SKILLS)
+            + ". Load them with `activate_skill` (or `/deslop`).",
+        ),
+        GlossaryEntry(
+            ("Bugbot", "bugbot", "cursor-team-kit", "verify-this", "Cursor"),
+            "Other Cursor-only extras (Bugbot, cloud agents, team-kit skills "
+            "not listed above such as `verify-this`): use an installed "
+            "equivalent if `list_or_search_skills` finds one; otherwise skip "
+            "that step and say so.",
+        ),
+    )
+
+
+def glossary(body: str | None = None) -> str:
+    """Glossary bullets for the primitives ``body`` mentions (all if ``None``)."""
+    bullets = [
+        f"- {entry.text}"
+        for entry in _entries()
+        if body is None or any(trigger in body for trigger in entry.triggers)
+    ]
+    if not bullets:
+        return ""
+    return "### Cursor terms, read as Code Puppy\n" + "\n".join(bullets)
+
+
+def attribution(origin: Origin = PSTACK) -> str:
+    if not origin.vendored:
+        return (
+            "> **pstack for Code Puppy.** Written for this plugin to stand in "
+            "for a Cursor built-in that pstack calls."
+        )
+    pin = load_pin()
+    return (
+        f"> **pstack for Code Puppy.** Vendored from {origin.title} "
+        f"({pin.repository}/tree/{pin.short_commit}/{origin.path}, MIT)."
+    )
+
+
+def preamble(source: Path, body: str | None = None, origin: Origin = PSTACK) -> str:
+    """Attribution, path anchor, and the glossary ``body`` needs."""
+    anchor = (
+        f" This file is `{source}`. Resolve its relative paths (`references/`, "
+        f"`playbooks/`, `scripts/`, `../<skill>/SKILL.md`) against "
+        f"`{source.parent}`, and read those files only when a step needs them."
+    )
+    terms = glossary(body)
+    return (
+        attribution(origin) + anchor + (f"\n\n{terms}" if terms else "") + "\n\n---\n\n"
+    )
+
+
+def _frontmatter(
+    name: str, description: str, group: str, author: str = PSTACK.author
+) -> str:
+    folded = textwrap.fill(
+        description,
+        width=78,
+        initial_indent="  ",
+        subsequent_indent="  ",
+        break_on_hyphens=False,
+        break_long_words=False,
+    )
+    tags = [group] if group == CORE_NAMESPACE else [group, CORE_NAMESPACE]
+    tag_lines = "\n".join(f"  - {tag}" for tag in tags)
+    return (
+        f"---\nname: {name}\ndescription: >-\n{folded}\ntags:\n{tag_lines}\n"
+        f"author: {author}\nversion: {load_pin().version}\n---\n\n"
+    )
+
+
+def render_skill(skill: VendoredSkill) -> str:
+    """Full ``SKILL.md`` text Code Puppy materializes for a vendored skill."""
+    body = None if skill.name in FULL_GLOSSARY else skill.body
+    return (
+        _frontmatter(
+            skill.name, skill.description, namespace(skill.name), skill.origin.author
+        )
+        + preamble(skill.skill_md, body, skill.origin)
+        + translate(skill.body)
+    )
+
+
+def principles_index_description() -> str:
+    return (
+        f"Index of pstack's {len(principles())} one-rule engineering principles "
+        "(laziness protocol, fix root causes, prove it works, model the domain, "
+        "and more). Use when poteto-mode or the user names a principle, or "
+        "before a design, debugging, or verification call."
+    )
+
+
+def render_principles_index() -> str:
+    """Generated skill that lists principle leaves for on-demand reading."""
+    entries = "\n".join(
+        f"- **{leaf.name}**: {leaf.description} `{leaf.skill_md}`"
+        for leaf in principles()
+    )
+    body = (
+        "# pstack principles\n\n"
+        "One-rule principles from poteto's pstack; `poteto-mode` cites them in "
+        "its Principles section. Pick the leaves whose trigger matches the "
+        "decision in front of you, read each in full with `read_file` before "
+        "you apply or cite it, and name the choice it changed.\n\n"
+        f"{entries}\n"
+    )
+    return (
+        _frontmatter(
+            PRINCIPLES_INDEX_NAME, principles_index_description(), CORE_NAMESPACE
+        )
+        + attribution()
+        + "\n\n"
+        + body
+    )

code_puppy_core_plugins-0.0.92/code_puppy_core_plugins/pstack/agents.py

@@ -0,0 +1,83 @@
+"""Code Puppy agents built from pstack's vendored ``agents/*.md`` files."""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from code_puppy.agents.base_agent import BaseAgent
+from code_puppy_core_plugins.pstack.adapter import preamble, translate
+from code_puppy_core_plugins.pstack.upstream import AGENTS_DIR, split_frontmatter
+
+_READ_TOOLS = ["list_files", "read_file", "grep", "shell"]
+_SKILL_TOOLS = ["activate_skill", "list_or_search_skills"]
+_EDIT_TOOLS = ["create_file", "replace_in_file", "delete_snippet", "delete_file"]
+
+
+@cache
+def _parsed(path: Path) -> tuple[dict[str, str], str]:
+    return split_frontmatter(path.read_text(encoding="utf-8"))
+
+
+class VendoredAgent(BaseAgent):
+    """An agent whose identity and prompt come from one vendored markdown file."""
+
+    SOURCE: Path
+    DISPLAY_NAME: str
+    TOOLS: tuple[str, ...]
+
+    @property
+    def name(self) -> str:
+        return _parsed(self.SOURCE)[0]["name"]
+
+    @property
+    def display_name(self) -> str:
+        return self.DISPLAY_NAME
+
+    @property
+    def description(self) -> str:
+        return _parsed(self.SOURCE)[0]["description"]
+
+    def get_available_tools(self) -> list[str]:
+        return list(self.TOOLS)
+
+    def get_system_prompt(self) -> str:
+        # Delegates read playbooks and sibling skills raw, so they get every
+        # glossary entry, not just the ones their own prompt mentions.
+        return preamble(self.SOURCE) + translate(_parsed(self.SOURCE)[1])
+
+
+class PotetoAgent(VendoredAgent):
+    """poteto-mode's delegate for code-writing and helper steps."""
+
+    SOURCE = AGENTS_DIR / "poteto-agent.md"
+    DISPLAY_NAME = "Poteto Agent"
+    TOOLS = (
+        "list_agents",
+        "invoke_agent",
+        "list_available_models",
+        "invoke_agent_with_model",
+        *_READ_TOOLS,
+        *_EDIT_TOOLS,
+        "ask_user_question",
+        *_SKILL_TOOLS,
+        "load_image_for_analysis",
+    )
+
+
+class CommentSickoAgent(VendoredAgent):
+    """The ``no-comments`` skill's reviewer: deletes comments, flags workarounds."""
+
+    SOURCE = AGENTS_DIR / "comment-sicko.md"
+    DISPLAY_NAME = "Comment Sicko"
+    TOOLS = (*_READ_TOOLS, "replace_in_file", "delete_snippet", *_SKILL_TOOLS)
+
+
+AGENT_CLASSES: tuple[type[VendoredAgent], ...] = (PotetoAgent, CommentSickoAgent)
+
+
+def agent_registrations() -> list[dict[str, object]]:
+    """``register_agents`` payload, keyed by each file's frontmatter name."""
+    return [
+        {"name": _parsed(cls.SOURCE)[0]["name"], "class": cls} for cls in AGENT_CLASSES
+    ]