intent-cli-python 0.5.0__tar.gz

intent_cli_python-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeng Deyang
+
+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.

intent_cli_python-0.5.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: intent-cli-python
+Version: 0.5.0
+Summary: Semantic history for agent-driven development. Records what you did and why.
+Author: Zeng Deyang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dozybot001/Intent
+Project-URL: Repository, https://github.com/dozybot001/Intent
+Keywords: agent,git,semantic-history,intent,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+English | [简体中文](https://github.com/dozybot001/Intent/blob/main/README.CN.md)
+
+# Intent
+
+> Git records code changes. Intent records why.
+
+## The Problem
+
+Agent-driven development produces code fast, but reasoning disappears between sessions. Every new session starts from zero — the agent doesn't know what problem was being solved, what was tried, or why a path was chosen.
+
+## What's Missing
+
+Git records *what* changed. Commit messages and comments add some context. But three things consistently fall through:
+
+**Goal continuity.** Commits are isolated snapshots. There's no structure connecting five commits to one task, or saying "this is what we're trying to accomplish."
+
+**Decision rationale.** Why JWT over cookies? Why 15-minute expiry? This rarely makes it into commit messages — and when it does, it's unstructured text that agents must parse and guess from.
+
+**Work state.** `git status` can be clean while a task is half-done. The next session has no signal that work was interrupted or what comes next.
+
+## The Solution
+
+Intent adds a `.intent/` directory to your repository — structured, machine-readable metadata that captures semantic history alongside code history.
+
+```
+.git/    ← how code changed
+.intent/ ← what you were doing and why
+```
+
+Two objects: **intent** (the goal) and **snap** (a step taken, with rationale). All JSON. Any agent platform can read it.
+
+### What changes
+
+**Without `.intent/`** — new agent session opens. It reads `git log` and source code. Understands what the code does *now*, but doesn't know the JWT migration was for compliance (might revert it), doesn't know the refresh token is intentionally incomplete, can't tell there's unfinished work. Asks: *"What would you like me to do?"*
+
+**With `.intent/`** — new agent session opens. Runs `itt inspect`. Sees an active intent ("Migrate auth to JWT"), last snap ("Add refresh token — incomplete"), and rationale ("token rotation not done, security priority"). Says: *"I'll implement the token rotation next."*
+
+The difference: 10 seconds of reading structured metadata vs. minutes of re-explaining context.
+
+## Core Loop
+
+```
+start → snap → done
+```
+
+- `start` — open an intent (what problem you're solving)
+- `snap` — record a snap (what you did and why)
+- `done` — close when complete
+
+## Example
+
+```bash
+pipx install intent-cli-python
+itt init                    # creates .intent/
+itt start "Fix login timeout"
+itt snap "Increase timeout to 30s" -m "5s too short for slow networks"
+git add . && git commit -m "fix timeout"
+itt done
+```
+
+## Why Not Just…
+
+| Approach | What it does well | What falls through |
+| --- | --- | --- |
+| **Git commit messages** | Records what changed per commit | No goal structure across commits; rationale is afterthought; no work-in-progress state |
+| **CLAUDE.md / .cursorrules** | Gives agents project-level instructions | Static — doesn't track active tasks, decisions, or progress; must be manually maintained |
+| **TODO comments** | Marks incomplete work in-place | Scattered across files; no lifecycle; no rationale; agents must grep and guess priority |
+| **Notion / Linear / Jira** | Rich project tracking for humans | External to the repo; agents can't read them without API integration; overhead is high for solo/agent workflows |
+| **Agent memory** (e.g. Claude Code memory) | Persists user preferences across sessions | Tied to one platform; not versioned with code; not shareable across agents or teammates |
+| **Ad-hoc context files** (e.g. `context.md`) | Quick, zero-tooling setup | No schema — every project invents its own format; no lifecycle management; grows stale silently |
+
+**Intent occupies a specific gap**: structured, versioned, task-scoped context that lives *in the repo* and works across any agent platform.
+
+- **Structured** — JSON objects with defined schema, not free text an agent must interpret
+- **Task-scoped** — an intent has a lifecycle (`open → done`); snaps are ordered steps, not a pile of notes
+- **Versioned** — `.intent/` is committed alongside code; `git blame` works on your decisions too
+- **Platform-agnostic** — any agent that reads JSON can use it; no vendor lock-in
+- **Minimal** — two objects (intent, snap), one CLI, zero dependencies; adds seconds to a workflow, not minutes
+
+The closest alternative is writing a `context.md` by hand. Intent trades that flexibility for consistency: a schema agents can rely on without per-project prompt engineering.
+
+## Where This Is Going
+
+`.intent/` is a protocol, not just a tool.
+
+1. **Agent memory** — agents read `.intent/` on startup, recover last session's context in seconds
+2. **Context exchange** — `.intent/` becomes the standard way to hand off work between agent platforms
+3. **Network effects** — when enough repos contain `.intent/`, new tooling emerges: intent-aware review, decision archaeology, semantic dashboards
+
+## Install
+
+**Users:**
+
+```bash
+pipx install intent-cli-python
+```
+
+**Configure your agent:** Install the Intent skill so your agent knows the workflow:
+
+```bash
+npx skills add dozybot001/Intent
+```
+
+**Contributors:**
+
+```bash
+git clone https://github.com/dozybot001/Intent.git
+cd Intent
+python3 ./itt   # dev entry point, no install needed
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `itt init` | Initialize `.intent/` |
+| `itt start <title>` | Open an intent |
+| `itt snap <title> [-m why]` | Record a snap |
+| `itt done` | Close the active intent |
+| `itt inspect` | Machine-readable workspace snapshot |
+| `itt list <intent\|snap>` | List objects |
+| `itt show <id>` | Show a single object |
+| `itt suspend` | Suspend the active intent |
+| `itt resume [id]` | Resume a suspended intent |
+| `itt adopt [id]` | Adopt a candidate snap |
+| `itt revert` | Revert the latest snap |
+
+## Documentation
+
+- [CLI spec](https://github.com/dozybot001/Intent/blob/main/docs/cli.EN.md) — objects, commands, JSON output contract
+- [Dogfooding](https://github.com/dozybot001/Intent/blob/main/docs/dogfooding.md) — how we built Intent with Intent

intent_cli_python-0.5.0/README.md

@@ -0,0 +1,131 @@
+English | [简体中文](https://github.com/dozybot001/Intent/blob/main/README.CN.md)
+
+# Intent
+
+> Git records code changes. Intent records why.
+
+## The Problem
+
+Agent-driven development produces code fast, but reasoning disappears between sessions. Every new session starts from zero — the agent doesn't know what problem was being solved, what was tried, or why a path was chosen.
+
+## What's Missing
+
+Git records *what* changed. Commit messages and comments add some context. But three things consistently fall through:
+
+**Goal continuity.** Commits are isolated snapshots. There's no structure connecting five commits to one task, or saying "this is what we're trying to accomplish."
+
+**Decision rationale.** Why JWT over cookies? Why 15-minute expiry? This rarely makes it into commit messages — and when it does, it's unstructured text that agents must parse and guess from.
+
+**Work state.** `git status` can be clean while a task is half-done. The next session has no signal that work was interrupted or what comes next.
+
+## The Solution
+
+Intent adds a `.intent/` directory to your repository — structured, machine-readable metadata that captures semantic history alongside code history.
+
+```
+.git/    ← how code changed
+.intent/ ← what you were doing and why
+```
+
+Two objects: **intent** (the goal) and **snap** (a step taken, with rationale). All JSON. Any agent platform can read it.
+
+### What changes
+
+**Without `.intent/`** — new agent session opens. It reads `git log` and source code. Understands what the code does *now*, but doesn't know the JWT migration was for compliance (might revert it), doesn't know the refresh token is intentionally incomplete, can't tell there's unfinished work. Asks: *"What would you like me to do?"*
+
+**With `.intent/`** — new agent session opens. Runs `itt inspect`. Sees an active intent ("Migrate auth to JWT"), last snap ("Add refresh token — incomplete"), and rationale ("token rotation not done, security priority"). Says: *"I'll implement the token rotation next."*
+
+The difference: 10 seconds of reading structured metadata vs. minutes of re-explaining context.
+
+## Core Loop
+
+```
+start → snap → done
+```
+
+- `start` — open an intent (what problem you're solving)
+- `snap` — record a snap (what you did and why)
+- `done` — close when complete
+
+## Example
+
+```bash
+pipx install intent-cli-python
+itt init                    # creates .intent/
+itt start "Fix login timeout"
+itt snap "Increase timeout to 30s" -m "5s too short for slow networks"
+git add . && git commit -m "fix timeout"
+itt done
+```
+
+## Why Not Just…
+
+| Approach | What it does well | What falls through |
+| --- | --- | --- |
+| **Git commit messages** | Records what changed per commit | No goal structure across commits; rationale is afterthought; no work-in-progress state |
+| **CLAUDE.md / .cursorrules** | Gives agents project-level instructions | Static — doesn't track active tasks, decisions, or progress; must be manually maintained |
+| **TODO comments** | Marks incomplete work in-place | Scattered across files; no lifecycle; no rationale; agents must grep and guess priority |
+| **Notion / Linear / Jira** | Rich project tracking for humans | External to the repo; agents can't read them without API integration; overhead is high for solo/agent workflows |
+| **Agent memory** (e.g. Claude Code memory) | Persists user preferences across sessions | Tied to one platform; not versioned with code; not shareable across agents or teammates |
+| **Ad-hoc context files** (e.g. `context.md`) | Quick, zero-tooling setup | No schema — every project invents its own format; no lifecycle management; grows stale silently |
+
+**Intent occupies a specific gap**: structured, versioned, task-scoped context that lives *in the repo* and works across any agent platform.
+
+- **Structured** — JSON objects with defined schema, not free text an agent must interpret
+- **Task-scoped** — an intent has a lifecycle (`open → done`); snaps are ordered steps, not a pile of notes
+- **Versioned** — `.intent/` is committed alongside code; `git blame` works on your decisions too
+- **Platform-agnostic** — any agent that reads JSON can use it; no vendor lock-in
+- **Minimal** — two objects (intent, snap), one CLI, zero dependencies; adds seconds to a workflow, not minutes
+
+The closest alternative is writing a `context.md` by hand. Intent trades that flexibility for consistency: a schema agents can rely on without per-project prompt engineering.
+
+## Where This Is Going
+
+`.intent/` is a protocol, not just a tool.
+
+1. **Agent memory** — agents read `.intent/` on startup, recover last session's context in seconds
+2. **Context exchange** — `.intent/` becomes the standard way to hand off work between agent platforms
+3. **Network effects** — when enough repos contain `.intent/`, new tooling emerges: intent-aware review, decision archaeology, semantic dashboards
+
+## Install
+
+**Users:**
+
+```bash
+pipx install intent-cli-python
+```
+
+**Configure your agent:** Install the Intent skill so your agent knows the workflow:
+
+```bash
+npx skills add dozybot001/Intent
+```
+
+**Contributors:**
+
+```bash
+git clone https://github.com/dozybot001/Intent.git
+cd Intent
+python3 ./itt   # dev entry point, no install needed
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `itt init` | Initialize `.intent/` |
+| `itt start <title>` | Open an intent |
+| `itt snap <title> [-m why]` | Record a snap |
+| `itt done` | Close the active intent |
+| `itt inspect` | Machine-readable workspace snapshot |
+| `itt list <intent\|snap>` | List objects |
+| `itt show <id>` | Show a single object |
+| `itt suspend` | Suspend the active intent |
+| `itt resume [id]` | Resume a suspended intent |
+| `itt adopt [id]` | Adopt a candidate snap |
+| `itt revert` | Revert the latest snap |
+
+## Documentation
+
+- [CLI spec](https://github.com/dozybot001/Intent/blob/main/docs/cli.EN.md) — objects, commands, JSON output contract
+- [Dogfooding](https://github.com/dozybot001/Intent/blob/main/docs/dogfooding.md) — how we built Intent with Intent

intent_cli_python-0.5.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "intent-cli-python"
+version = "0.5.0"
+description = "Semantic history for agent-driven development. Records what you did and why."
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Zeng Deyang" },
+]
+keywords = ["agent", "git", "semantic-history", "intent", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/dozybot001/Intent"
+Repository = "https://github.com/dozybot001/Intent"
+
+[project.scripts]
+itt = "intent_cli.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

intent_cli_python-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

intent_cli_python-0.5.0/src/intent_cli/__init__.py

@@ -0,0 +1,29 @@
+"""Intent CLI package."""
+
+from importlib import metadata
+from pathlib import Path
+import re
+from typing import Optional
+
+
+PACKAGE_NAME = "intent-cli-python"
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PYPROJECT_PATH = REPO_ROOT / "pyproject.toml"
+VERSION_PATTERN = re.compile(r'^version\s*=\s*"([^"]+)"\s*$', re.MULTILINE)
+
+
+def version_from_checkout() -> Optional[str]:
+    if not PYPROJECT_PATH.exists():
+        return None
+    match = VERSION_PATTERN.search(PYPROJECT_PATH.read_text(encoding="utf-8"))
+    if not match:
+        return None
+    return match.group(1)
+
+
+__version__ = version_from_checkout()
+if __version__ is None:
+    try:
+        __version__ = metadata.version(PACKAGE_NAME)
+    except metadata.PackageNotFoundError:
+        __version__ = "0.4.0"

intent_cli_python-0.5.0/src/intent_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

intent_cli_python-0.5.0/src/intent_cli/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from . import __version__
+from .constants import EXIT_GENERAL_FAILURE, EXIT_SUCCESS
+from .core import IntentRepository
+from .errors import IntentError
+
+
+def emit(payload: Dict[str, Any]) -> None:
+    print(json.dumps(payload, indent=2))
+
+
+def ok(action: str, result: Any, **extra: Any) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {"ok": True, "action": action, "result": result}
+    payload.update(extra)
+    return payload
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="itt",
+        description="Intent CLI — semantic history for agents.",
+    )
+    parser.add_argument("--version", action="version", version=f"intent-cli {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, title="commands")
+
+    sub.add_parser("version", help="Show version")
+
+    sub.add_parser("init", help="Initialize Intent in the current Git repository")
+
+    start_p = sub.add_parser("start", help="Create and activate an intent")
+    start_p.add_argument("title")
+
+    snap_p = sub.add_parser("snap", help="Record a snap (adopted by default)")
+    snap_p.add_argument("title")
+    snap_p.add_argument("-m", "--message", help="Rationale for this snap")
+    snap_p.add_argument("--candidate", action="store_true", help="Record as candidate without adopting")
+
+    adopt_p = sub.add_parser("adopt", help="Adopt a candidate snap")
+    adopt_p.add_argument("snap_id", nargs="?")
+    adopt_p.add_argument("-m", "--message", help="Rationale for adoption")
+
+    revert_p = sub.add_parser("revert", help="Revert the latest adopted snap")
+    revert_p.add_argument("-m", "--message", help="Rationale for revert")
+
+    sub.add_parser("suspend", help="Suspend the active intent")
+
+    resume_p = sub.add_parser("resume", help="Resume a suspended intent")
+    resume_p.add_argument("intent_id", nargs="?")
+
+    done_p = sub.add_parser("done", help="Close the active intent")
+    done_p.add_argument("intent_id", nargs="?")
+
+    sub.add_parser("inspect", help="Machine-readable workspace snapshot")
+
+    list_p = sub.add_parser("list", help="List objects")
+    list_p.add_argument("type", choices=["intent", "snap"])
+    list_p.add_argument("--intent", dest="intent_id", help="Filter snaps by intent ID")
+
+    show_p = sub.add_parser("show", help="Show a single object by ID")
+    show_p.add_argument("id")
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    repo = IntentRepository(Path.cwd())
+
+    try:
+        if args.command == "version":
+            emit(ok("version", {"version": __version__}))
+            return EXIT_SUCCESS
+
+        if args.command == "init":
+            repo.ensure_git()
+            config, state = repo.init_workspace()
+            emit(ok("init", {"config": config, "state": state}))
+            return EXIT_SUCCESS
+
+        if args.command == "start":
+            intent, warnings = repo.create_intent(args.title)
+            emit(ok("start", intent, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "snap":
+            snap, warnings = repo.create_snap(
+                args.title,
+                rationale=args.message,
+                candidate=args.candidate,
+            )
+            emit(ok("snap", snap, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "adopt":
+            snap, warnings = repo.adopt_snap(
+                snap_id=args.snap_id,
+                rationale=args.message,
+            )
+            emit(ok("adopt", snap, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "revert":
+            snap, warnings = repo.revert_snap(rationale=args.message)
+            emit(ok("revert", snap, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "suspend":
+            intent, warnings = repo.suspend_intent()
+            emit(ok("suspend", intent, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "resume":
+            intent, warnings = repo.resume_intent(intent_id=args.intent_id)
+            emit(ok("resume", intent, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "done":
+            intent, warnings = repo.close_intent(intent_id=args.intent_id)
+            emit(ok("done", intent, warnings=warnings))
+            return EXIT_SUCCESS
+
+        if args.command == "inspect":
+            emit(repo.inspect())
+            return EXIT_SUCCESS
+
+        if args.command == "list":
+            items = repo.list_objects(args.type, intent_id=getattr(args, "intent_id", None))
+            emit(ok("list", items, count=len(items)))
+            return EXIT_SUCCESS
+
+        if args.command == "show":
+            obj = repo.show_object(args.id)
+            emit(ok("show", obj))
+            return EXIT_SUCCESS
+
+        parser.error("unknown command")
+        return 2
+
+    except IntentError as error:
+        emit(error.to_json())
+        return error.exit_code
+    except Exception as error:
+        emit({
+            "ok": False,
+            "error": {
+                "code": "INTERNAL_ERROR",
+                "message": str(error),
+                "details": {},
+            },
+        })
+        return EXIT_GENERAL_FAILURE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

intent_cli_python-0.5.0/src/intent_cli/constants.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+SCHEMA_VERSION = "0.2"
+
+EXIT_SUCCESS = 0
+EXIT_GENERAL_FAILURE = 1
+EXIT_INVALID_INPUT = 2
+EXIT_STATE_CONFLICT = 3
+EXIT_OBJECT_NOT_FOUND = 4
+
+DIR_NAMES = {
+    "intent": "intents",
+    "snap": "snaps",
+}
+
+ID_PREFIXES = {
+    "intent": "intent",
+    "snap": "snap",
+}