git-intent 0.3.1__py3-none-any.whl

git_intent-0.3.1.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: git-intent
+Version: 0.3.1
+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 | [简体中文](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
+itt init
+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
+```
+
+## 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
+
+```bash
+pip install git-intent
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/dozybot001/Intent.git && cd Intent
+pip install -e .
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `itt init` | Initialize `.intent/` in a Git repo |
+| `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 adopt [id]` | Adopt a candidate snap |
+| `itt revert` | Revert the latest snap |
+
+## Documentation
+
+- [CLI spec](docs/cli.EN.md) — objects, commands, JSON output contract
+- [Agent integration](docs/agent-integration.md) — copy-paste snippets for Claude Code, Cursor, AGENTS.md

git_intent-0.3.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+git_intent-0.3.1.dist-info/licenses/LICENSE,sha256=XWjTStLaoDw-UgLwMecejVxeaHH8JibnSFYARGzRc6I,1068
+intent_cli/__init__.py,sha256=NvlYQNTOg7avKt8eRLOpsHudf6iMkkCFc6VvQ3fPbeM,766
+intent_cli/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+intent_cli/cli.py,sha256=LIrUjS4vWA2b1HXZdp1O_HzCYU8HjF_y3lhR3gK2c0c,4773
+intent_cli/constants.py,sha256=yOFDntL9kUqoB6ByKjUe5U6kcSVPn17nI2ywKWuuukM,301
+intent_cli/core.py,sha256=9f8R0czttENL_sxxcBONMm3-yR-psWAcC5aH-06VFHI,12269
+intent_cli/errors.py,sha256=ZmfE5cf07vjoHNSKvjEqxQN0YQ_09nXD9KB3W82-xu8,892
+intent_cli/git.py,sha256=79eTLQoelp7X44nDam4l4gLmh73M7hcrofIWmG_VVfc,2402
+intent_cli/helpers.py,sha256=b1MWHFv3BGLO99SNq-ejNLuwtHbxy9p3rlYJRjXrzI4,718
+intent_cli/store.py,sha256=AUz1oJmZTZFgzWFubo13ZNXq4P_p9BbiTFjf-7BTNlA,3766
+git_intent-0.3.1.dist-info/METADATA,sha256=mO7iQkBsi6G4zX-6myCQ076NV8XpUvNtebpQhfOQUJ0,4673
+git_intent-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+git_intent-0.3.1.dist-info/entry_points.txt,sha256=Y1kziqgaGUgTHg3CCfc2Su1XoDvIMJ2vi-dPEDZfuTo,44
+git_intent-0.3.1.dist-info/top_level.txt,sha256=jkyOMCXA-G6FlEj69GA4SKn3RoO1KNL9w2iit7OUpuU,11
+git_intent-0.3.1.dist-info/RECORD,,

git_intent-0.3.1.dist-info/WHEEL

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

git_intent-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+itt = intent_cli.cli:main

git_intent-0.3.1.dist-info/licenses/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.

git_intent-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+intent_cli

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 = "git-intent"
+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.3.1"

intent_cli/__main__.py

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

intent_cli/cli.py

@@ -0,0 +1,146 @@
+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")
+
+    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"])
+
+    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 == "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)
+            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/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",
+}

intent_cli/core.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .constants import EXIT_OBJECT_NOT_FOUND, EXIT_STATE_CONFLICT, SCHEMA_VERSION
+from .errors import IntentError
+from .git import build_git_context, ensure_git_worktree
+from .helpers import object_sort_key, utc_now
+from .store import IntentStore
+
+
+class IntentRepository:
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = cwd
+        self.store = IntentStore(cwd)
+
+    # --- guards ---
+
+    def ensure_git(self) -> None:
+        ensure_git_worktree(self.cwd)
+
+    def ensure_initialized(self) -> None:
+        self.store.ensure_initialized()
+
+    # --- init ---
+
+    def init_workspace(self) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        self.ensure_git()
+        return self.store.init_workspace()
+
+    # --- state helpers ---
+
+    def _load_state(self) -> Dict[str, Any]:
+        return self.store.load_state()
+
+    def _save_state(self, state: Dict[str, Any]) -> None:
+        self.store.save_state(state)
+
+    def _active_intent(self, state: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        state = state or self._load_state()
+        return self.store.load_object("intent", state.get("active_intent_id"))
+
+    def _require_active_intent(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        intent = self._active_intent(state)
+        if not intent:
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                "No active intent.",
+                suggested_fix='itt start "Describe the problem"',
+            )
+        return intent
+
+    def _candidate_snaps(self, intent_id: str) -> List[Dict[str, Any]]:
+        return sorted(
+            [
+                s for s in self.store.list_objects("snap")
+                if s.get("intent_id") == intent_id and s.get("status") == "candidate"
+            ],
+            key=object_sort_key,
+        )
+
+    def _latest_adopted(self, intent_id: str) -> Optional[Dict[str, Any]]:
+        adopted = [
+            s for s in self.store.list_objects("snap")
+            if s.get("intent_id") == intent_id and s.get("status") == "adopted"
+        ]
+        if not adopted:
+            return None
+        return sorted(adopted, key=object_sort_key, reverse=True)[0]
+
+    def _derive_workspace_status(self, state: Dict[str, Any]) -> str:
+        intent = self._active_intent(state)
+        if not intent:
+            return "idle"
+        candidates = self._candidate_snaps(intent["id"])
+        if len(candidates) > 1:
+            return "conflict"
+        return "active"
+
+    # --- intent lifecycle ---
+
+    def create_intent(self, title: str) -> Tuple[Dict[str, Any], List[str]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+
+        current = self._active_intent(state)
+        if current and current.get("status") == "open":
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                f"Intent '{current['id']}' is still open.",
+                suggested_fix="itt done",
+            )
+
+        intent_id = self.store.next_id("intent")
+        now = utc_now()
+        intent = {
+            "id": intent_id,
+            "object": "intent",
+            "schema_version": SCHEMA_VERSION,
+            "created_at": now,
+            "updated_at": now,
+            "title": title,
+            "status": "open",
+        }
+        self.store.save_object("intent", intent)
+
+        state["active_intent_id"] = intent_id
+        state["workspace_status"] = "active"
+        self._save_state(state)
+        return intent, []
+
+    def close_intent(self, intent_id: Optional[str] = None) -> Tuple[Dict[str, Any], List[str]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+
+        if intent_id:
+            intent = self.store.require_object("intent", intent_id)
+        else:
+            intent = self._require_active_intent(state)
+
+        if intent.get("status") == "done":
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                f"Intent '{intent['id']}' is already done.",
+            )
+
+        intent["status"] = "done"
+        intent["updated_at"] = utc_now()
+        self.store.save_object("intent", intent)
+
+        if intent["id"] == state.get("active_intent_id"):
+            state["active_intent_id"] = None
+            state["workspace_status"] = "idle"
+            self._save_state(state)
+
+        return intent, []
+
+    # --- snap lifecycle ---
+
+    def create_snap(
+        self,
+        title: str,
+        rationale: Optional[str] = None,
+        candidate: bool = False,
+    ) -> Tuple[Dict[str, Any], List[str]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+        intent = self._require_active_intent(state)
+
+        git_payload, warnings = build_git_context(self.cwd)
+        snap_id = self.store.next_id("snap")
+        now = utc_now()
+        status = "candidate" if candidate else "adopted"
+        snap = {
+            "id": snap_id,
+            "object": "snap",
+            "schema_version": SCHEMA_VERSION,
+            "created_at": now,
+            "updated_at": now,
+            "title": title,
+            "rationale": rationale or "",
+            "status": status,
+            "intent_id": intent["id"],
+            "git": git_payload,
+        }
+        self.store.save_object("snap", snap)
+
+        state["workspace_status"] = self._derive_workspace_status(state)
+        self._save_state(state)
+        return snap, warnings
+
+    def adopt_snap(
+        self,
+        snap_id: Optional[str] = None,
+        rationale: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], List[str]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+        intent = self._require_active_intent(state)
+
+        candidates = self._candidate_snaps(intent["id"])
+
+        if snap_id:
+            snap = self.store.require_object("snap", snap_id)
+            if snap.get("intent_id") != intent["id"]:
+                raise IntentError(
+                    EXIT_STATE_CONFLICT,
+                    "STATE_CONFLICT",
+                    "Snap does not belong to the active intent.",
+                    details={"snap_id": snap_id, "intent_id": intent["id"]},
+                )
+            if snap.get("status") != "candidate":
+                raise IntentError(
+                    EXIT_STATE_CONFLICT,
+                    "STATE_CONFLICT",
+                    f"Snap '{snap_id}' is not a candidate.",
+                )
+        elif len(candidates) == 1:
+            snap = candidates[0]
+        elif len(candidates) == 0:
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                "No candidate snaps to adopt.",
+                suggested_fix='itt snap "Describe the step" --candidate',
+            )
+        else:
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                "Multiple candidates exist. Specify which one to adopt.",
+                details={
+                    "candidates": [{"id": c["id"], "title": c["title"]} for c in candidates],
+                },
+                suggested_fix=f"itt adopt {candidates[-1]['id']}",
+            )
+
+        snap["status"] = "adopted"
+        if rationale:
+            snap["rationale"] = rationale
+        snap["updated_at"] = utc_now()
+        self.store.save_object("snap", snap)
+
+        state["workspace_status"] = self._derive_workspace_status(state)
+        self._save_state(state)
+        return snap, []
+
+    def revert_snap(self, rationale: Optional[str] = None) -> Tuple[Dict[str, Any], List[str]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+        intent = self._require_active_intent(state)
+
+        latest = self._latest_adopted(intent["id"])
+        if not latest:
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                "No adopted snap to revert.",
+                suggested_fix='itt snap "Describe the step"',
+            )
+
+        latest["status"] = "reverted"
+        if rationale:
+            latest["rationale"] = rationale
+        latest["updated_at"] = utc_now()
+        self.store.save_object("snap", latest)
+
+        state["workspace_status"] = self._derive_workspace_status(state)
+        self._save_state(state)
+        return latest, []
+
+    # --- read ---
+
+    def inspect(self) -> Dict[str, Any]:
+        self.ensure_git()
+        self.ensure_initialized()
+        state = self._load_state()
+        intent = self._active_intent(state)
+        git_payload, git_warnings = build_git_context(self.cwd)
+
+        latest_snap = None
+        candidate_snaps: List[Dict[str, Any]] = []
+        if intent:
+            latest_snap = self._latest_adopted(intent["id"])
+            candidate_snaps = [
+                {"id": c["id"], "title": c["title"]}
+                for c in self._candidate_snaps(intent["id"])
+            ]
+
+        workspace_status = self._derive_workspace_status(state)
+        if workspace_status != state.get("workspace_status"):
+            state["workspace_status"] = workspace_status
+            self._save_state(state)
+
+        def brief(obj: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+            if not obj:
+                return None
+            return {k: obj[k] for k in ("id", "title", "status", "rationale") if k in obj}
+
+        action = self._next_action(intent, candidate_snaps)
+
+        return {
+            "ok": True,
+            "schema_version": SCHEMA_VERSION,
+            "workspace_status": workspace_status,
+            "intent": brief(intent),
+            "latest_snap": brief(latest_snap),
+            "candidate_snaps": candidate_snaps,
+            "suggested_next_action": action,
+            "git": {
+                "branch": git_payload["branch"],
+                "head": git_payload["head"],
+                "working_tree": git_payload["working_tree"],
+            },
+            "warnings": git_warnings,
+        }
+
+    def list_objects(self, object_name: str) -> List[Dict[str, Any]]:
+        self.ensure_git()
+        self.ensure_initialized()
+        if object_name not in ("intent", "snap"):
+            raise IntentError(
+                EXIT_STATE_CONFLICT,
+                "STATE_CONFLICT",
+                f"Unknown object type: {object_name}",
+                suggested_fix="Use 'intent' or 'snap'.",
+            )
+        return sorted(self.store.list_objects(object_name), key=object_sort_key, reverse=True)
+
+    def show_object(self, object_id: str) -> Dict[str, Any]:
+        self.ensure_git()
+        self.ensure_initialized()
+        object_name = self._type_from_id(object_id)
+        return self.store.require_object(object_name, object_id)
+
+    # --- internal ---
+
+    def _type_from_id(self, object_id: str) -> str:
+        if object_id.startswith("intent-"):
+            return "intent"
+        if object_id.startswith("snap-"):
+            return "snap"
+        raise IntentError(
+            EXIT_OBJECT_NOT_FOUND,
+            "OBJECT_NOT_FOUND",
+            f"Cannot determine type for id '{object_id}'.",
+            suggested_fix="Use a valid id like 'intent-001' or 'snap-001'.",
+        )
+
+    def _next_action(
+        self,
+        intent: Optional[Dict[str, Any]],
+        candidates: List[Dict[str, Any]],
+    ) -> Optional[Dict[str, Any]]:
+        if not intent or intent.get("status") != "open":
+            return {"command": "itt start 'Describe the problem'", "reason": "No active intent."}
+        if len(candidates) > 1:
+            return {
+                "command": f"itt adopt {candidates[-1]['id']}",
+                "reason": "Multiple candidates — pick one to adopt.",
+            }
+        if len(candidates) == 1:
+            return {
+                "command": f"itt adopt {candidates[0]['id']}",
+                "reason": "One candidate ready for adoption.",
+            }
+        return {"command": "itt snap 'Describe the step'", "reason": "Intent is active."}

intent_cli/errors.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class IntentError(Exception):
+    def __init__(
+        self,
+        exit_code: int,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        suggested_fix: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        self.suggested_fix = suggested_fix
+
+    def to_json(self) -> Dict[str, Any]:
+        payload = {
+            "ok": False,
+            "error": {
+                "code": self.code,
+                "message": self.message,
+                "details": self.details,
+            },
+        }
+        if self.suggested_fix:
+            payload["error"]["suggested_fix"] = self.suggested_fix
+        return payload

intent_cli/git.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .constants import EXIT_GENERAL_FAILURE
+from .errors import IntentError
+
+
+def run_git(cwd: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=str(cwd),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def ensure_git_worktree(cwd: Path) -> None:
+    result = run_git(cwd, "rev-parse", "--is-inside-work-tree")
+    if result.returncode != 0 or result.stdout.strip() != "true":
+        raise IntentError(
+            EXIT_GENERAL_FAILURE,
+            "GIT_STATE_INVALID",
+            "Intent requires a Git repository",
+            suggested_fix="git init",
+        )
+
+
+def git_branch(cwd: Path) -> str:
+    result = run_git(cwd, "branch", "--show-current")
+    if result.returncode == 0:
+        value = result.stdout.strip()
+        if value:
+            return value
+    result = run_git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    return "unknown"
+
+
+def git_head(cwd: Path, ref: str = "HEAD") -> Optional[str]:
+    result = run_git(cwd, "rev-parse", "--short", ref)
+    if result.returncode == 0:
+        value = result.stdout.strip()
+        return value or None
+    return None
+
+
+def git_working_tree(cwd: Path) -> str:
+    result = run_git(cwd, "status", "--porcelain")
+    if result.returncode != 0:
+        return "unknown"
+    return "clean" if not result.stdout.strip() else "dirty"
+
+
+def build_git_context(cwd: Path) -> Tuple[Dict[str, Any], List[str]]:
+    branch = git_branch(cwd)
+    working_tree = git_working_tree(cwd)
+    warnings: List[str] = []
+
+    head = git_head(cwd)
+    if head and working_tree == "clean":
+        linkage_quality = "stable_commit"
+    else:
+        linkage_quality = "working_tree_context"
+        if not head:
+            warnings.append("Git HEAD could not be resolved; recording working tree context only.")
+
+    if working_tree == "dirty":
+        warnings.append("Git working tree is dirty; recording working tree context.")
+
+    return (
+        {
+            "branch": branch,
+            "head": head,
+            "working_tree": working_tree,
+            "linkage_quality": linkage_quality,
+        },
+        warnings,
+    )

intent_cli/helpers.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Tuple
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    return json.loads(path.read_text())
+
+
+def write_json(path: Path, payload: Dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+
+
+def object_sort_key(item: Dict[str, Any]) -> Tuple[str, int]:
+    object_id = item.get("id", "")
+    suffix = object_id.rsplit("-", 1)[-1]
+    number = int(suffix) if suffix.isdigit() else 0
+    return (item.get("created_at", ""), number)

intent_cli/store.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .constants import DIR_NAMES, EXIT_GENERAL_FAILURE, EXIT_OBJECT_NOT_FOUND, ID_PREFIXES, SCHEMA_VERSION
+from .errors import IntentError
+from .helpers import read_json, utc_now, write_json
+
+
+class IntentStore:
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = cwd
+        self.intent_dir = cwd / ".intent"
+        self.config_path = self.intent_dir / "config.json"
+        self.state_path = self.intent_dir / "state.json"
+
+    def is_initialized(self) -> bool:
+        return self.intent_dir.exists() and self.config_path.exists() and self.state_path.exists()
+
+    def ensure_initialized(self) -> None:
+        if not self.is_initialized():
+            raise IntentError(
+                EXIT_GENERAL_FAILURE,
+                "NOT_INITIALIZED",
+                "Intent is not initialized in this repository.",
+                suggested_fix="itt init",
+            )
+
+    def object_dir(self, object_name: str) -> Path:
+        return self.intent_dir / DIR_NAMES[object_name]
+
+    def init_workspace(self) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        if self.intent_dir.exists():
+            raise IntentError(
+                EXIT_GENERAL_FAILURE,
+                "ALREADY_EXISTS",
+                "Intent is already initialized in this repository.",
+            )
+
+        self.intent_dir.mkdir()
+        for dir_name in DIR_NAMES.values():
+            (self.intent_dir / dir_name).mkdir()
+
+        config: Dict[str, Any] = {"schema_version": SCHEMA_VERSION}
+        state: Dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "active_intent_id": None,
+            "workspace_status": "idle",
+            "updated_at": utc_now(),
+        }
+        write_json(self.config_path, config)
+        write_json(self.state_path, state)
+        return config, state
+
+    def load_state(self) -> Dict[str, Any]:
+        self.ensure_initialized()
+        return read_json(self.state_path)
+
+    def save_state(self, state: Dict[str, Any]) -> None:
+        state["updated_at"] = utc_now()
+        write_json(self.state_path, state)
+
+    def next_id(self, object_name: str) -> str:
+        directory = self.object_dir(object_name)
+        prefix = ID_PREFIXES[object_name]
+        max_index = 0
+        for path in directory.glob(f"{prefix}-*.json"):
+            suffix = path.stem[len(prefix) + 1:]
+            if suffix.isdigit():
+                max_index = max(max_index, int(suffix))
+        return f"{prefix}-{max_index + 1:03d}"
+
+    def save_object(self, object_name: str, payload: Dict[str, Any]) -> None:
+        path = self.object_dir(object_name) / f"{payload['id']}.json"
+        write_json(path, payload)
+
+    def load_object(self, object_name: str, object_id: Optional[str]) -> Optional[Dict[str, Any]]:
+        if not object_id:
+            return None
+        path = self.object_dir(object_name) / f"{object_id}.json"
+        if not path.exists():
+            return None
+        return read_json(path)
+
+    def require_object(self, object_name: str, object_id: str) -> Dict[str, Any]:
+        payload = self.load_object(object_name, object_id)
+        if payload is None:
+            raise IntentError(
+                EXIT_OBJECT_NOT_FOUND,
+                "OBJECT_NOT_FOUND",
+                f"{object_name.capitalize()} '{object_id}' was not found.",
+                details={"id": object_id, "object": object_name},
+            )
+        return payload
+
+    def list_objects(self, object_name: str) -> List[Dict[str, Any]]:
+        directory = self.object_dir(object_name)
+        if not directory.exists():
+            return []
+        return [read_json(path) for path in directory.glob("*.json")]