@jstxn/agentdir-pi 0.7.3

package/LICENSE

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

package/README.md

@@ -0,0 +1,358 @@
+# AgentDir
+
+<p align="center">
+  <img src="docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
+</p>
+
+<p align="center">
+  <strong>Local-first memory and evidence for agentic engineering.</strong>
+</p>
+
+AgentDir is a flight recorder for coding agents. It lets agents record what
+happened during a software task, then gives engineers a clean way to inspect,
+replay, search, and audit that work later.
+
+The goal is simple: AgentDir should be nearly invisible while you work.
+
+Engineers should not have to manually start sessions, wrap commands, collect
+evidence, or maintain agent memory by hand. Once a repository is adopted, the
+agent operates AgentDir in the background and leaves behind a useful trail.
+
+## Why AgentDir Exists
+
+Agentic engineering has a trust gap.
+
+Agents can edit code, run tools, and summarize results, but their work often
+ends up scattered across chat history, terminal scrollback, temporary files, and
+unverified final claims. That makes it hard to answer basic questions:
+
+- What did the agent actually do?
+- Which commands support the final answer?
+- Were tests, builds, lint, or release checks really run?
+- What context did the agent retrieve and rely on?
+- Can a future agent learn from this session?
+- Can the index or memory layer be rebuilt if it breaks?
+
+AgentDir gives those answers a local, durable home.
+
+## What You Get
+
+| Capability | What it means |
+| --- | --- |
+| Invisible agent workflow | Agents run AgentDir commands during normal work, so engineers keep using their coding assistant normally. |
+| Evidence-backed claims | Test, build, lint, typecheck, doctor, and release claims can be checked against recorded tool results. |
+| Replayable sessions | Inspect the task, decisions, commands, outputs, blockers, summaries, and handoffs after the fact. |
+| Local-first storage | Records live in the repo-local `.agentdir` directory by default. No hosted service is required. |
+| Rebuildable memory | Raw event files are the source of truth. SQLite search and memory indexes can be rebuilt. |
+| Context lineage | Agents can emit context packs, then record which retrieved sources were consumed or cited. |
+| Cross-repo memory | Explicitly registered AgentDir roots can be searched together without moving canonical records. |
+| Secret-aware persistence | Common secret-like patterns are redacted before storage, with scan and cleanup commands for older records. |
+
+## The Invisible Workflow
+
+AgentDir is designed around a small separation of responsibility.
+
+| Human does | Agent does |
+| --- | --- |
+| Install AgentDir once. | Start and finish AgentDir sessions. |
+| Run `agentdir adopt` once per repo. | Capture evidence-bearing commands with `agentdir run`. |
+| Ask the coding agent to do work. | Record decisions, blockers, context, and handoffs. |
+| Inspect evidence only when needed. | Audit session quality and final claims before reporting. |
+
+In day-to-day use, the human workflow stays the same:
+
+```text
+Ask the agent to do the task.
+Review the result.
+Use AgentDir only when you want the trail.
+```
+
+The agent handles the recording surface:
+
+```bash
+agentdir work start "fix checkout failure" --emit-context
+agentdir run -- pytest -q
+agentdir audit session
+agentdir work finish --json
+```
+
+## Install
+
+AgentDir is distributed through GitHub Releases. For the private
+`jstxn/agentdir` repo, authenticate GitHub CLI first:
+
+```bash
+gh auth login
+```
+
+Install the latest release:
+
+```bash
+gh api -H "Accept: application/vnd.github.raw" \
+  'repos/jstxn/agentdir/contents/scripts/install.sh?ref=v0.7.3' | bash
+```
+
+The installer uses `pipx` when available. Otherwise it creates a self-contained
+virtual environment under `~/.local/share/agentdir` and links the CLI into
+`~/.local/bin`.
+
+Verify:
+
+```bash
+agentdir --version
+agentdir --help
+```
+
+## Pi Package
+
+Pi users can install this repository as a Pi package so the AgentDir skill is
+available automatically during coding tasks:
+
+```bash
+pi install npm:@jstxn/agentdir-pi@0.7.3
+# or install directly from a local checkout / release tag:
+pi install /absolute/path/to/agentdir
+pi install git:github.com/jstxn/agentdir@<tag-or-commit>
+```
+
+The package exposes `skills/agentdir/SKILL.md`; it teaches Pi to start AgentDir
+sessions, wrap evidence-bearing commands, use local memory/context packs, and
+produce evidence-aware handoffs. See [AgentDir Pi Package](docs/PI_PACKAGE.md)
+for details.
+
+## Adopt A Repository
+
+Run once from a git repository:
+
+```bash
+agentdir adopt
+```
+
+This is intentionally boring setup. It prepares the repository once, then agents
+operate AgentDir during normal coding work:
+
+- creates the repo-local `.agentdir` store
+- installs AgentDir-managed git hook shims
+- installs the Codex skill into the user skill directory
+- writes managed project guidance for common agent tools
+- asks interactive users whether `.agentdir/` should be added to the project or
+  user-level Git ignore file
+- runs `doctor` to confirm the store is healthy
+
+After that, agents have the guidance they need to use AgentDir without the
+engineer manually operating it during normal work.
+
+Preview setup without writing anything:
+
+```bash
+agentdir adopt --dry-run --json
+```
+
+If you want generated integration files to stay inside the AgentDir store
+instead of project instruction files:
+
+```bash
+agentdir adopt --install-skill store --install-generic store --integration-target store
+```
+
+For non-interactive installs, choose the ignore destination explicitly:
+
+```bash
+agentdir adopt --gitignore project  # write <repo>/.gitignore
+agentdir adopt --gitignore user     # write the user-level Git excludes file
+agentdir adopt --gitignore none     # leave ignore files unchanged
+```
+
+Undo managed setup while keeping the `.agentdir` evidence store:
+
+```bash
+agentdir unadopt          # dry-run
+agentdir unadopt --apply  # remove managed hooks and guidance
+```
+
+## What Gets Written
+
+Default adoption writes only local files:
+
+```text
+<repo>/.agentdir/                         # evidence, artifacts, indexes, state
+<repo>/.git/hooks/*                       # managed hook shims with backups
+<repo>/AGENTS.md                          # generic / Codex-readable guidance
+<repo>/CLAUDE.md                          # Claude Code guidance
+<repo>/.github/copilot-instructions.md    # Copilot guidance
+<repo>/.cursor/rules/agentdir.mdc         # Cursor guidance
+<repo>/.windsurf/rules/agentdir.md        # Windsurf guidance
+~/.codex/skills/agentdir/SKILL.md         # Codex skill, by default
+```
+
+Managed guidance is wrapped in AgentDir markers. Existing unmanaged content is
+preserved where the target format supports managed blocks.
+
+## Inspect A Session
+
+Most users will not need these commands every day, but they are the reason
+AgentDir exists.
+
+```bash
+agentdir status
+agentdir evidence --brief
+agentdir timeline
+agentdir report final --format json
+agentdir replay
+agentdir memory search "checkout failure"
+```
+
+For final-answer support:
+
+```bash
+agentdir audit session
+agentdir audit claims --text final-response.md
+```
+
+Audits are advisory by default. Use `--strict` when unsupported or contradicted
+claims should fail a check.
+
+## How AgentDir Works
+
+AgentDir has one source of truth and several rebuildable views:
+
+```text
+raw envelopes -> SQLite index -> memory/search/audit/report
+                    ^
+                    |
+             rebuilt from envelopes
+```
+
+1. **Raw envelopes**
+   Each meaningful event is stored as an immutable file in a Maildir-inspired
+   directory layout. These files are the source of truth.
+2. **Derived indexes**
+   SQLite indexes, search tables, memory passages, context packs, and audit
+   views are derived from the raw event files and can be rebuilt.
+
+Default project layout:
+
+```text
+<repo>/.agentdir/
+  sessions/
+  actors/
+  artifacts/
+  archives/
+  indexes/agentdir.sqlite3
+  state/
+  integrations/
+```
+
+The important property is recoverability: deleting the derived index does not
+destroy the session. AgentDir can rebuild from the envelope store.
+
+The agent-facing report surface is JSON. `agentdir report final --format json`
+and `agentdir work finish --json` include an `agent_handoff` object with
+verification evidence, failed evidence, claim support, context lineage, known
+gaps, and recommended next agent actions.
+
+## Unique Capabilities
+
+### Claims-To-Evidence Checks
+
+AgentDir can compare final-response claims such as "tests passed" or "build
+passed" against the latest recorded tool results. It does this with
+deterministic heuristics, not an LLM.
+
+Supported claim families:
+
+- test
+- lint
+- typecheck
+- build
+- doctor
+- release
+
+### Context Packs
+
+Agents can package retrieved context into auditable source manifests:
+
+```bash
+agentdir context build "checkout failure" --emit
+agentdir context consume --pack <pack-id> --source <source-id> --purpose plan
+agentdir context cite --pack <pack-id>
+agentdir audit context --pack <pack-id>
+```
+
+This does not prove a model paid attention, but it does make cooperative agent
+behavior visible.
+
+### Local Agent Memory
+
+AgentDir builds searchable local memory from prior sessions. Agents can search
+similar work, explain why a memory hit matched, and include relevant history in
+new context packs.
+
+```bash
+agentdir memory search "release evidence"
+agentdir memory explain "release evidence"
+agentdir context build "release evidence" --emit
+```
+
+Optional semantic extras exist, but the default path does not require a vector
+database or external embedding service.
+
+### Federated Memory
+
+For multi-repo work, AgentDir can search explicitly registered roots:
+
+```bash
+agentdir roots register ../other-repo --name other-repo
+agentdir memory search --federated "release evidence"
+```
+
+Each repository remains the canonical owner of its own `.agentdir` store.
+
+## Safety Model
+
+AgentDir is local-first and advisory by design.
+
+- It records what agents choose to record.
+- It does not replace code review or CI.
+- It does not send data to a hosted AgentDir service.
+- It treats raw envelopes as the source of truth.
+- It redacts common secret-like patterns before persistence.
+- It provides `secrets scan` and `secrets redact --apply` for cleanup.
+
+Useful commands:
+
+```bash
+agentdir doctor
+agentdir secrets scan
+agentdir secrets redact
+agentdir secrets redact --apply
+```
+
+## Upgrade And Rollback
+
+Upgrade an existing install and refresh current repo adoption:
+
+```bash
+agentdir --upgrade
+```
+
+Rollback to the previous stable release:
+
+```bash
+gh api -H "Accept: application/vnd.github.raw" \
+  'repos/jstxn/agentdir/contents/scripts/rollback.sh?ref=v0.7.3' | bash
+```
+
+## Learn More
+
+- [Install Guide](docs/INSTALL.md)
+- [Agentic Coding Guide](docs/AGENTIC_CODING.md)
+- [Technical Brief](docs/TECH_BRIEF.md)
+- [Release Guide](docs/RELEASING.md)
+- [PRD](docs/PRD.md)
+
+## Project Status
+
+AgentDir is beta software for local-first agentic engineering workflows. The
+core model is stable: agents operate the recorder, engineers get the evidence,
+and raw local envelopes remain the recoverable source of truth.

package/docs/PI_PACKAGE.md

@@ -0,0 +1,64 @@
+# AgentDir Pi Package
+
+AgentDir ships a Pi package so Pi can load AgentDir guidance as an Agent Skill.
+The package currently exposes one skill:
+
+```text
+skills/agentdir/SKILL.md
+```
+
+The skill teaches Pi to start AgentDir sessions, wrap evidence-bearing shell
+commands, use local memory/context packs, and produce evidence-aware handoffs.
+It does not install the `agentdir` CLI; install AgentDir separately first.
+
+## Install
+
+From a local checkout:
+
+```bash
+pi install /absolute/path/to/agentdir
+```
+
+Temporarily for one Pi run:
+
+```bash
+pi -e /absolute/path/to/agentdir
+```
+
+From git, pin a tag or commit that contains the Pi package files:
+
+```bash
+pi install git:github.com/jstxn/agentdir@<tag-or-commit>
+```
+
+If the npm package has been published:
+
+```bash
+pi install npm:@jstxn/agentdir-pi@0.7.3
+```
+
+Use `pi config` to enable or disable the bundled skill after installation.
+
+## Package Manifest
+
+The root `package.json` declares the Pi resources:
+
+```json
+{
+  "keywords": ["pi-package"],
+  "pi": {
+    "skills": ["./skills"],
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.3/docs/assets/agentdir-overview.png"
+  }
+}
+```
+
+The `pi-package` keyword makes the package discoverable by the Pi package
+gallery, `pi.skills` points Pi at the skill directory, and `pi.image` gives the
+gallery a preview image from this repository.
+
+## Release Notes
+
+- Keep the npm package version aligned with the AgentDir release version.
+- Before publishing, run `npm pack --dry-run` and confirm the tarball includes
+  `package.json`, `skills/agentdir/SKILL.md`, `README.md`, and `LICENSE`.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jstxn/agentdir-pi",
+  "version": "0.7.3",
+  "description": "Pi package for AgentDir local-first coding-agent memory and evidence capture.",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "agentdir",
+    "agent-skills",
+    "coding-agent",
+    "evidence",
+    "local-first"
+  ],
+  "homepage": "https://github.com/jstxn/agentdir#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jstxn/agentdir.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jstxn/agentdir/issues"
+  },
+  "files": [
+    "skills",
+    "docs/PI_PACKAGE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.3/docs/assets/agentdir-overview.png"
+  }
+}

package/skills/agentdir/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: agentdir
+description: Use AgentDir as a local-first flight recorder for non-trivial coding-agent work in software repositories. Load at the start of coding tasks, before tests/lint/build/typecheck, and when asked about AgentDir evidence, audits, session replay, memory, context packs, adoption, or handoffs.
+license: MIT
+compatibility: Requires the agentdir CLI on PATH; works best inside a git repository.
+---
+
+# AgentDir for Pi
+
+AgentDir is local-first memory and evidence capture for agentic engineering. Use it as agent-owned background instrumentation: the engineer should not have to start sessions, wrap checks, collect evidence, or maintain memory by hand during normal coding work.
+
+This Pi package teaches Pi how to operate AgentDir. It does not install the `agentdir` CLI. If `agentdir` is not on `PATH`, tell the user AgentDir needs to be installed and continue without recording unless they ask you to set it up.
+
+## Safety Rules
+
+- Do not record secrets, private keys, raw environment dumps, or credential-bearing command output.
+- If `agentdir doctor` reports secret-like persisted bodies, do not print those bodies. Use `agentdir secrets scan` for path-only triage and `agentdir secrets redact --apply` only when cleanup is approved.
+- Use Pi's normal file tools for reading and editing files. `agentdir run --` wraps shell commands only; it does not wrap Pi `read`, `edit`, or `write` tool calls.
+
+## Start Work
+
+At the start of a non-trivial coding task in a software repository:
+
+1. If `.agentdir` is missing, run `agentdir adopt` once before work begins.
+2. Start the session with `agentdir work start "<short task>" --emit-context`.
+3. Keep any returned context pack id/source ids if you plan to cite or consume retrieved context later.
+
+Use `agentdir status` when you need one compact view of the active session, evidence, memory, context, registered roots, and doctor health.
+
+## Evidence-Bearing Commands
+
+Run evidence-bearing shell commands through AgentDir:
+
+```bash
+agentdir run -- pytest -q
+agentdir run -- npm test
+agentdir run -- npm run lint
+agentdir run -- npm run typecheck
+agentdir run -- npm run build
+```
+
+Evidence-bearing commands include tests, lint, typecheck, build, release checks, reproduced failures, doctor checks, and diagnostics used to support final claims.
+
+Do not wrap routine exploration commands such as `rg`, `sed`, `nl`, `cat`, `ls`, `find`, or quick read-only `git status` checks. Use plain shell commands for reading files, mapping code, and gathering low-level context.
+
+Use `agentdir evidence --brief` and `agentdir timeline` to skim what has been recorded.
+
+## Context And Memory
+
+- `agentdir work start "<task>" --emit-context` is the normal entry point.
+- Use `agentdir context build "<task>" --emit` when retrieved context should become an auditable context pack.
+- Use `agentdir context consume --pack <pack-id> --source <source-id> --purpose plan|tool|answer|handoff` when you rely on retrieved context.
+- Use `agentdir context cite --pack <pack-id>` or `agentdir audit context --pack <pack-id>` when reporting source lineage.
+- Use `agentdir memory search "<task, error, or subsystem>"` and `agentdir memory explain "<same query>"` when prior local work may help.
+- Use `agentdir roots suggest` and `agentdir roots doctor` to inspect cross-repo memory. Register roots only when cross-repo memory is explicitly requested or clearly part of the task.
+
+Emit important plans, blockers, diffs, review decisions, and final handoffs as immutable events when they matter for future replay or audit.
+
+## Finish Work
+
+Before the final response, run `agentdir work finish --json` when practical. Read the `agent_handoff` object before making final verification claims.
+
+If you need to preview the final handoff without ending the active session, run `agentdir report final --format json` instead.
+
+Before claiming tests, builds, lint, typecheck, hooks, release checks, or doctor checks passed, verify the latest recorded evidence with `agentdir evidence --brief`.