continuity-note 0.1.0__py3-none-any.whl

continuity_note/__init__.py

@@ -0,0 +1,3 @@
+"""continuity-note: install the continuity-note agent skill into your AI tools."""
+
+__version__ = "0.1.0"

continuity_note/cli.py

@@ -0,0 +1,221 @@
+"""Command-line installer for the continuity-note agent skill.
+
+The skill itself is plain Markdown (``SKILL.md``). This CLI copies it into the
+skills directory of whichever AI coding agent you use, so the agent discovers it
+the same way it discovers any other skill. We copy a physical file rather than
+symlinking on purpose: the installed skill must survive ``pip uninstall`` and
+virtualenv changes - it belongs to your agent, not to this Python package.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from importlib import resources
+from pathlib import Path
+
+from . import __version__
+
+SKILL_NAME = "continuity-note"
+
+
+def _skill_source() -> str:
+    """Return the packaged SKILL.md content."""
+    return resources.files("continuity_note").joinpath("data/SKILL.md").read_text(
+        encoding="utf-8"
+    )
+
+
+def _codex_skills_dir() -> Path:
+    """Codex honors $CODEX_HOME (default ~/.codex)."""
+    codex_home = os.environ.get("CODEX_HOME")
+    base = Path(codex_home) if codex_home else Path.home() / ".codex"
+    return base / "skills"
+
+
+# name -> (skills directory, human label). Verified against each agent's docs:
+# Claude Code reads ~/.claude/skills; Codex reads $CODEX_HOME/skills; the
+# cross-runtime ~/.agents/skills is shared by Copilot CLI and Gemini CLI.
+def _targets() -> dict[str, tuple[Path, str]]:
+    return {
+        "claude": (Path.home() / ".claude" / "skills", "Claude Code"),
+        "codex": (_codex_skills_dir(), "Codex"),
+        "agents": (Path.home() / ".agents" / "skills", "Copilot CLI / Gemini CLI"),
+    }
+
+
+def _detected(targets: dict[str, tuple[Path, str]]) -> list[str]:
+    """Targets whose skills directory (or its parent) already exists - i.e. the
+    agent looks installed, so we should offer to install there by default."""
+    found = []
+    for name, (skills_dir, _label) in targets.items():
+        if skills_dir.exists() or skills_dir.parent.exists():
+            found.append(name)
+    return found
+
+
+def _resolve_target_names(requested: list[str], targets: dict) -> list[str]:
+    if "all" in requested:
+        return list(targets)
+    unknown = [r for r in requested if r not in targets]
+    if unknown:
+        valid = ", ".join(list(targets) + ["all"])
+        raise SystemExit(
+            f"Unknown target(s): {', '.join(unknown)}. Valid targets: {valid}."
+        )
+    return requested
+
+
+def _install_one(skills_dir: Path, content: str, force: bool) -> str:
+    """Install into one skills directory. Returns a one-word status."""
+    dest_dir = skills_dir / SKILL_NAME
+    dest = dest_dir / "SKILL.md"
+    if dest.exists():
+        current = dest.read_text(encoding="utf-8")
+        if current == content:
+            return "up-to-date"
+        if not force:
+            return "differs"  # never clobber local edits silently
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest.write_text(content, encoding="utf-8")
+    return "installed"
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    content = _skill_source()
+    targets = _targets()
+
+    # Custom directory takes precedence and bypasses the known-agent registry.
+    if args.target:
+        custom = Path(args.target).expanduser().resolve()
+        status = _install_one(custom, content, args.force)
+        _report(custom / SKILL_NAME, "custom directory", status, args.force)
+        return 0
+
+    if args.targets:
+        names = _resolve_target_names(args.targets, targets)
+    else:
+        names = _detected(targets)
+        if not names:
+            # Fresh machine with no agent dirs yet: default to Claude Code and
+            # create the directory, rather than failing on a clean install.
+            names = ["claude"]
+            print(
+                "No agent skills directory detected; defaulting to Claude Code.\n"
+                "Pass target names (claude codex agents all) or --target DIR to choose.\n"
+            )
+
+    any_blocked = False
+    for name in names:
+        skills_dir, label = targets[name]
+        status = _install_one(skills_dir, content, args.force)
+        any_blocked |= status == "differs"
+        _report(skills_dir / SKILL_NAME, label, status, args.force)
+    return 1 if any_blocked else 0
+
+
+def _report(dest_dir: Path, label: str, status: str, force: bool) -> None:
+    dest = dest_dir / "SKILL.md"
+    if status == "installed":
+        print(f"  ok    {label}: {dest}")
+    elif status == "up-to-date":
+        print(f"  ok    {label}: already up to date ({dest})")
+    elif status == "differs":
+        print(
+            f"  skip  {label}: {dest} exists and differs from this version.\n"
+            f"        Re-run with --force to overwrite (this discards local edits)."
+        )
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    targets = _targets()
+    if args.target:
+        dirs = [(Path(args.target).expanduser().resolve(), "custom directory")]
+    else:
+        names = _resolve_target_names(args.targets, targets) if args.targets else list(targets)
+        dirs = [(targets[n][0], targets[n][1]) for n in names]
+
+    removed = False
+    for skills_dir, label in dirs:
+        dest = skills_dir / SKILL_NAME / "SKILL.md"
+        skill_dir = skills_dir / SKILL_NAME
+        if dest.exists():
+            dest.unlink()
+            # Remove the skill folder if we left it empty.
+            try:
+                skill_dir.rmdir()
+            except OSError:
+                pass
+            print(f"  removed  {label}: {dest}")
+            removed = True
+    if not removed:
+        print("Nothing to remove; continuity-note was not installed in any target.")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    targets = _targets()
+    print(f"continuity-note {__version__}\n")
+    for name, (skills_dir, label) in targets.items():
+        dest = skills_dir / SKILL_NAME / "SKILL.md"
+        if dest.exists():
+            same = dest.read_text(encoding="utf-8") == _skill_source()
+            state = "installed (current)" if same else "installed (outdated/edited)"
+        else:
+            state = "not installed"
+        print(f"  {name:8} {label:28} {state}\n           {dest}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="continuity-note",
+        description="Install the continuity-note agent skill into your AI coding tools.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_install = sub.add_parser(
+        "install",
+        help="Copy the skill into agent skills directories (default: detected agents).",
+    )
+    p_install.add_argument(
+        "targets",
+        nargs="*",
+        help="Which agents: claude, codex, agents, or all. Omit to auto-detect.",
+    )
+    p_install.add_argument(
+        "--target",
+        metavar="DIR",
+        help="Install into a custom skills directory instead of a known agent.",
+    )
+    p_install.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing SKILL.md even if it was edited locally.",
+    )
+    p_install.set_defaults(func=cmd_install)
+
+    p_uninstall = sub.add_parser("uninstall", help="Remove the skill from agent skills directories.")
+    p_uninstall.add_argument("targets", nargs="*", help="Which agents (default: all known).")
+    p_uninstall.add_argument("--target", metavar="DIR", help="A custom skills directory.")
+    p_uninstall.set_defaults(func=cmd_uninstall)
+
+    p_status = sub.add_parser("status", help="Show where the skill is installed.")
+    p_status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

continuity_note/data/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: continuity-note
+description: >-
+  Write a self-contained continuity note (a handoff document) so another agent,
+  a teammate, or your future self can resume work WITHOUT replaying the
+  conversation. Use whenever work is being passed on - the user says "write a
+  continuity note", "write a handoff", "hand this off",
+  "pass this to another agent/session", "summarize this for the next session",
+  "I'm switching to Codex/another tool", "document where we are so I can continue
+  tomorrow", "context is running out, save state", or when a long session is
+  ending with work still in progress. Trigger even if the user doesn't say the
+  word "handoff" - any time the goal is to transfer in-progress work to a fresh
+  context, this skill applies. Do NOT use it for normal in-session context
+  compaction (the harness already handles that) - handoff is for crossing a
+  boundary into a new context that has none of this conversation's history.
+---
+
+# Continuity Note
+
+A continuity note (a handoff document) lets a **fresh context** resume your work. The
+reader has none of this conversation: not the goal, not the decisions, not the
+dead ends you already ruled out. They might be a different agent (a new Claude
+session, Codex, DeepSeek, anything), a human teammate, or you tomorrow. The
+whole value is that they can pick up and act *without asking you a single
+question*. Optimize for that.
+
+## When this is the right tool
+
+Use it when work crosses a context boundary: ending a session with work unfinished,
+switching to another agent or tool, handing to a colleague, or saving state
+because the context window is about to be lost. The reader starts cold.
+
+Do **not** use it for ordinary in-session compaction. The harness already
+summarizes long conversations so the same agent keeps going. Handoff earns its
+cost only when the next reader has zero history.
+
+## What goes in (and what stays out)
+
+The reader needs **state and direction**, not a transcript. Two failure modes,
+both fatal:
+
+- **Too little**: "continue the refactor." The reader has no idea what refactor,
+  why, how far, or what's next. Useless.
+- **Too much**: pasting whole files, full logs, the entire chat. The reader
+  drowns and can't find the signal. Also re-pastes data that already lives in
+  files - stale the moment you write it.
+
+The rule that resolves both: **reference, don't duplicate**. Point to artifacts
+by path or URL (files, PRDs, ADRs, issues, commits, diffs, dashboards). Carry
+across only the things that exist *nowhere but your head*: why you chose A over
+B, the trap that isn't obvious from the code, what to do next.
+
+## Document structure
+
+Write the document in this order. Lead with the parts a reader needs in the
+first ten seconds; push detail down. Drop a section if it's genuinely empty -
+don't pad.
+
+```markdown
+# Handoff: <short topic> (<YYYY-MM-DD>)
+
+## Goal
+One or two sentences. What are we ultimately trying to achieve, and why.
+
+## Current state
+Where things stand right now. What works, what's broken, what's half-done.
+Be honest about confidence: mark what you VERIFIED versus what you ASSUME.
+A reader who trusts an assumption as fact will waste hours.
+
+## Done
+- Concrete things already completed, terse bullets.
+
+## Next steps
+The most important section. Ordered, concrete, actionable - each step
+something the reader can just do. Not "improve performance" but "add an index
+on orders.created_at; the slow query is in reports/daily.py:88".
+
+## Key decisions and why
+Choices already made and the reasoning, so the reader doesn't relitigate them
+or accidentally undo them. "Chose Postgres over SQLite because the test suite
+needs concurrent writes."
+
+## Gotchas and constraints
+Traps, surprises, environment quirks. Things that look wrong but are
+intentional. The stuff that would cost the reader an hour of confusion.
+
+## Files and artifacts
+Paths and URLs, each with one line on what it is and why it matters.
+NOT the contents. "src/auth/jwt.py - token logic, the bug is here."
+
+## How to verify
+Commands or checks that confirm the current state, and how the reader will
+know future work succeeded. "Run `pytest tests/auth/`; all green = done."
+
+## Open questions
+Unknowns and decisions that need the user. Be explicit that these are blockers
+versus nice-to-knows.
+```
+
+## Rules that make a handoff trustworthy
+
+**Redact secrets.** Never carry API keys, tokens, passwords, connection strings,
+or personal data into the document. Point to where the credential lives ("token
+in ~/.config/foo/key") - never the value. A handoff often gets pasted into
+another tool or committed to a repo; treat it as if it will be read by someone
+who shouldn't see secrets.
+
+**Be portable across agents.** The reader may not share your tooling. Don't
+write "run the /deploy skill" or "use the foo MCP" - the next agent may not have
+either. Describe the *capability* in plain terms ("deploy with the project's
+helm chart under deploy/") so any competent agent or human can act. If you do
+know the next reader is the same setup, naming a specific tool as a shortcut is
+fine - but always also say what it does.
+
+**Distinguish verified from assumed.** This is what separates a handoff that
+saves time from one that wastes it. If you ran the tests and they passed, say
+so. If you only *think* the fix works, say "untested - needs verification". The
+reader inherits your uncertainty either way; hiding it just moves the cost
+downstream.
+
+**Keep it lean.** Every line should earn its place. If a detail lives in a file
+the reader will open anyway, link the file instead of restating it. Length is
+not thoroughness - precision is.
+
+## Where to save it
+
+Default: write the document to the current working directory as
+`handoff-<short-topic>-<YYYY-MM-DD>.md`, then tell the user the exact path so
+they can move, commit, or send it. A handoff buried in an OS temp directory
+tends to vanish before anyone reads it - keep it where it'll be found.
+
+If the user names a destination (a docs folder, a ticket, a shared drive), use
+that instead. If they explicitly want it throwaway, a temp path is fine - but
+that's their call, not the default.
+
+Adapt the language of the document to the user's working language.

continuity_note-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: continuity-note
+Version: 0.1.0
+Summary: Install the continuity-note agent skill: write a self-contained handoff so a fresh context can resume work.
+Project-URL: Homepage, https://github.com/mauriziomocci/continuity-note
+Project-URL: Repository, https://github.com/mauriziomocci/continuity-note
+Project-URL: Changelog, https://github.com/mauriziomocci/continuity-note/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mauriziomocci/continuity-note/issues
+Author-email: Maurizio Mocci <mauriziomocci64@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,claude-code,codex,continuity,handoff,llm,skill
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# continuity-note
+
+*Read this in [Italiano](README.it.md).*
+
+Install the **continuity-note** agent skill into your AI coding tools.
+
+A continuity note is a self-contained handoff document: it lets a *fresh
+context* — another agent, a teammate, or you tomorrow — resume in-progress work
+**without replaying the conversation**. The skill teaches your agent to write
+one well: a fixed structure (goal, current state, next steps, key decisions,
+gotchas, files, how to verify, open questions), references to artifacts instead
+of pasted copies, redacted secrets, and an honest split between what was
+verified and what was only assumed.
+
+This package is a small installer. The skill itself is plain Markdown; the CLI
+copies it into the skills directory your agent already reads.
+
+## Install
+
+```bash
+pip install continuity-note      # or: pipx install continuity-note
+continuity-note install          # copies the skill into detected agents
+```
+
+`install` with no arguments auto-detects which agents are present and installs
+into each. Choose explicitly with target names:
+
+```bash
+continuity-note install claude          # Claude Code  (~/.claude/skills)
+continuity-note install codex           # Codex        ($CODEX_HOME/skills)
+continuity-note install agents          # Copilot CLI / Gemini CLI (~/.agents/skills)
+continuity-note install all             # all of the above
+continuity-note install --target ~/my/skills   # a custom directory
+```
+
+The skill is copied as a physical file (not a symlink), so it keeps working
+after you `pip uninstall continuity-note` or switch virtualenvs.
+
+## Use
+
+Once installed, restart your agent so it picks up the new skill, then just ask:
+
+> write a continuity note for what we did today
+
+or "hand this off", "save state, context is running out", "document where we are
+so I can continue tomorrow". The agent writes the note to your working directory
+as `continuity-note-<topic>-<date>.md` and tells you the path.
+
+## Manage
+
+```bash
+continuity-note status           # show where it's installed and whether current
+continuity-note install --force  # update after upgrading the package
+continuity-note uninstall        # remove from all known agents
+```
+
+## Supported agents
+
+| Target   | Agent(s)                  | Skills directory        |
+|----------|---------------------------|-------------------------|
+| `claude` | Claude Code               | `~/.claude/skills`      |
+| `codex`  | Codex                     | `$CODEX_HOME/skills` (default `~/.codex/skills`) |
+| `agents` | Copilot CLI, Gemini CLI   | `~/.agents/skills`      |
+
+Any other agent that reads a skills directory of `SKILL.md` files works too —
+point `--target` at it.
+
+## License
+
+MIT. The skill is derived from the original "handoff" skill by Matt Pocock
+(also MIT); see [LICENSE](LICENSE).

continuity_note-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+continuity_note/__init__.py,sha256=aciDxhS0JrBW1IHXrUrimQQdPlEwbvL2FPYkzS8H8Qw,106
+continuity_note/cli.py,sha256=YUow7rxe_RJyIOQu4EfLIdsIMe5CXumdxVxRMl3xNnE,7915
+continuity_note/data/SKILL.md,sha256=0uj9zlfrL5VaYFeJwHvUu9erPqgDzPuxyJNo4Yl4cog,6195
+continuity_note-0.1.0.dist-info/METADATA,sha256=iDaZDxuKoXZzbhwm6w1rwLSyUGw_eKBuyoo2kG4-7kI,4149
+continuity_note-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+continuity_note-0.1.0.dist-info/entry_points.txt,sha256=Nn7dwSxSZFWmicORNMQisTjmIu26tB-S-AF04LzhmBw,61
+continuity_note-0.1.0.dist-info/licenses/LICENSE,sha256=MIsovsKjm5cI7eAfTj-a4ReofekqBB1XL5Bm5Fe-jXk,1187
+continuity_note-0.1.0.dist-info/RECORD,,

continuity_note-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

continuity_note-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+continuity-note = continuity_note.cli:main

continuity_note-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Maurizio Mocci
+Portions copyright (c) 2026 Matt Pocock (original "handoff" skill, from which
+the continuity-note skill is derived)
+
+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.