agent-doc 0.1.0__tar.gz

agent_doc-0.1.0/.claude/skills/agent-doc/SKILL.md

@@ -0,0 +1,92 @@
+# agent-doc run
+
+Interactive document session — respond to user edits in a markdown document.
+
+## Invocation
+
+```
+/agent-doc <FILE>
+```
+
+Arguments: `FILE` — path to the session document (e.g., `plan.md`)
+
+## Core Principles
+
+- **Document is the UI** — the user's edits ARE the prompt; respond in the document AND the console
+- **Preserve user edits** — never overwrite; read the file fresh before writing
+- **Show progress** — stream your response in the console so the user sees real-time feedback
+- **Maintain session** — the document is a living conversation, not a one-shot
+
+## Workflow
+
+### 1. Read the document and snapshot
+
+- Read `<FILE>` to get current content
+- Read the snapshot at `.agent-doc/snapshots/<hash>.md` where `<hash>` is SHA256 of the canonical file path
+  - If no snapshot exists, treat this as the first run (entire document is new)
+
+### 2. Compute the diff
+
+- Compare snapshot (previous state) against current content
+- The diff represents what the user changed since the last run
+- If no diff (content unchanged), tell the user nothing changed and stop
+
+### 3. Respond
+
+- Address the user's changes naturally in the console (this gives real-time streaming feedback)
+- Respond to:
+  - New `## User` blocks
+  - Inline annotations (blockquotes, comments, edits to previous responses)
+  - Structural changes (deletions, reorganization)
+- Your console response IS the document response — they should be the same content
+
+### 4. Write back to the document
+
+After responding, update the document file:
+
+1. **Re-read the file** (user may have edited during your response)
+2. Append your response as:
+   ```
+   ## Assistant
+
+   <your response>
+
+   ## User
+
+   ```
+3. Use the Edit tool to append (not Write — preserves user edits made during response)
+4. Update the snapshot to match the new document state
+
+### 5. Git integration (optional)
+
+If the document is in a git repo:
+- Before responding: `git add -f <FILE> && git commit -m "agent-doc: <timestamp>" --no-verify`
+- After writing response: do NOT commit (leave as uncommitted for diff gutters)
+
+## Document Format
+
+Session documents use YAML frontmatter:
+
+```yaml
+---
+session: <uuid or null>
+agent: <name or null>
+model: <model or null>
+branch: <branch or null>
+---
+```
+
+The body alternates `## User` and `## Assistant` blocks. Inline annotations (blockquotes, comments) within any block are valid prompts.
+
+## Snapshot Storage
+
+- Location: `.agent-doc/snapshots/` relative to CWD
+- Filename: `sha256(canonical_path) + ".md"`
+- Contains the full document content after the last run
+
+## Success Criteria
+
+- User sees streaming response in the Claude console
+- Document is updated with the response (user can see it in their editor)
+- User edits made during response are preserved (not overwritten)
+- Snapshot is updated for the next run's diff computation

agent_doc-0.1.0/.github/workflows/book.yml

@@ -0,0 +1,22 @@
+name: Book
+on:
+  push:
+    branches: [main]
+permissions:
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: taiki-e/install-action@mdbook
+      - run: mdbook build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: book
+      - id: deployment
+        uses: actions/deploy-pages@v4

agent_doc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - run: cargo clippy -- -D warnings
+
+      - run: cargo test

agent_doc-0.1.0/.github/workflows/mdbook.yml

@@ -0,0 +1,60 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.36
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: mdbook build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

agent_doc-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,78 @@
+name: PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+          - target: x86_64-apple-darwin
+            os: macos-13
+          - target: aarch64-apple-darwin
+            os: macos-latest
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: auto
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

agent_doc-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            use_cross: false
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            use_cross: true
+          - target: x86_64-apple-darwin
+            os: macos-14
+            use_cross: false
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            use_cross: false
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            use_cross: false
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install cross
+        if: matrix.use_cross
+        run: cargo install cross --version 0.2.5
+
+      - name: Build (cross)
+        if: matrix.use_cross
+        run: cross build --release --target ${{ matrix.target }}
+        env:
+          CROSS_CONTAINER_ENGINE: docker
+
+      - name: Build (cargo)
+        if: "!matrix.use_cross"
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Package (Unix)
+        if: runner.os != 'Windows'
+        run: tar czf agent-doc-${{ matrix.target }}.tar.gz -C target/${{ matrix.target }}/release agent-doc
+
+      - name: Package (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: Compress-Archive -Path target/${{ matrix.target }}/release/agent-doc.exe -DestinationPath agent-doc-${{ matrix.target }}.zip
+
+      - name: Upload artifact (Unix)
+        if: runner.os != 'Windows'
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-doc-${{ matrix.target }}
+          path: agent-doc-${{ matrix.target }}.tar.gz
+
+      - name: Upload artifact (Windows)
+        if: runner.os == 'Windows'
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-doc-${{ matrix.target }}
+          path: agent-doc-${{ matrix.target }}.zip
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          tag="${GITHUB_REF#refs/tags/}"
+          gh release create "$tag" \
+            --title "agent-doc $tag" \
+            --generate-notes \
+            artifacts/*

agent_doc-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.idea/
+*.iml
+.agent-doc/
+CLAUDE.local.md
+AGENTS.local.md
+plan.md
+research.md
+tmp/
+
+# Rust
+target/
+.bin/

agent_doc-0.1.0/CLAUDE.md

@@ -0,0 +1,43 @@
+# agent-doc
+
+Interactive document sessions with AI agents.
+
+## Conventions
+
+- Use `clap` derive for CLI argument parsing
+- Use `serde` derive for all data types
+- Use `serde_yaml` for frontmatter parsing
+- Use `similar` crate for diffing (pure Rust, no shell `diff` dependency)
+- Use `serde_json` for agent response parsing
+- Use `std::process::Command` for git operations (not `git2`)
+- Use `toml + serde` for config file parsing
+- No async — sequential per-run
+- Use `anyhow` for application errors
+
+## Module Layout
+
+Use this layout when adding modules. Add new subcommands in their own file, wired through `main.rs`.
+
+```
+src/
+  main.rs           # CLI entry point (clap derive)
+  submit.rs         # Core loop: diff, send, merge-safe write, snapshot, git
+  init.rs           # Scaffold session document
+  reset.rs          # Clear session + snapshot
+  diff.rs           # Preview diff (dry run)
+  clean.rs          # Squash git history
+  frontmatter.rs    # YAML frontmatter parse/write
+  snapshot.rs       # Snapshot path/read/write
+  git.rs            # Commit, branch, squash
+  config.rs         # Global config (~/.config/agent-doc/config.toml)
+  agent/
+    mod.rs          # Agent trait
+    claude.rs       # Claude backend
+  audit_docs.rs     # Audit instruction files (CLAUDE.md, AGENTS.md, SKILL.md)
+```
+
+## Agent Backend Contract
+
+Each agent backend implements: take a prompt string, return (response_text, session_id).
+The prompt includes the diff and full document. The agent backend handles CLI
+invocation, JSON parsing, and session flags.