packwright 0.1.0__tar.gz

packwright-0.1.0/.github/ISSUE_TEMPLATE/adapter_request.yml

@@ -0,0 +1,45 @@
+name: Adapter request
+description: Propose a runtime after checking its official file and extension contracts.
+title: "[adapter] "
+labels: [adapter]
+body:
+  - type: input
+    id: runtime
+    attributes:
+      label: Runtime
+      placeholder: Runtime and current version
+    validations:
+      required: true
+  - type: textarea
+    id: documentation
+    attributes:
+      label: Official documentation
+      description: Link the runtime's official instructions, rules, skills, or extension documentation.
+      placeholder: One URL per line
+    validations:
+      required: true
+  - type: textarea
+    id: layout
+    attributes:
+      label: Native file layout
+      description: Where does this runtime expect instructions, reusable skills, memory routing, and project rules?
+    validations:
+      required: true
+  - type: textarea
+    id: boundaries
+    attributes:
+      label: Known projection boundaries
+      description: What Packwright state or behavior cannot be represented in this runtime?
+    validations:
+      required: true
+  - type: dropdown
+    id: testing
+    attributes:
+      label: Real-runtime testing
+      description: Can you test generated packs in an actual installation?
+      options:
+        - Yes, I can test locally
+        - I can help review but not run it
+        - No
+    validations:
+      required: true

packwright-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Report a reproducible Packwright defect using synthetic data.
+title: "[bug] "
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Packwright version
+      placeholder: Output of packwright --version
+    validations:
+      required: true
+  - type: dropdown
+    id: adapter
+    attributes:
+      label: Adapter
+      options: [codex, claude-code, cursor, not adapter-specific]
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Include commands and sanitized output. Never attach real memory or credentials.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true

packwright-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and usage help
+    url: https://github.com/pioneerjeff-labs/packwright/discussions/categories/q-a
+    about: Ask how to build, install, migrate, diagnose, or score a Packwright target.

packwright-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Propose a focused improvement to the public v0.1 workflow.
+title: "[feature] "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user problem should Packwright solve?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+    validations:
+      required: true

packwright-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+Describe the user-visible change and its v0.1 scope.
+
+## Verification
+
+- [ ] `scripts/release-gate.sh --quick`
+- [ ] Tests cover the changed behavior
+- [ ] No real memory, credentials, private paths, or build artifacts are included
+- [ ] Migration changes preserve dry-run, confirmation, and receipt semantics

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

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  PACKWRIGHT_PUBLIC_AUDIT_REVISION: ${{ github.event.pull_request.head.sha }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Fetch pull request head for public audit
+        if: github.event_name == 'pull_request'
+        run: git fetch --no-tags origin "pull/${{ github.event.number }}/head"
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[test]'
+      - run: scripts/release-gate.sh --quick
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Fetch pull request head for public audit
+        if: github.event_name == 'pull_request'
+        run: git fetch --no-tags origin "pull/${{ github.event.number }}/head"
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - run: python -m pip install -e '.[test]'
+      - run: scripts/release-gate.sh --output-dir "$RUNNER_TEMP/packwright-dist"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: packwright-0.1.0
+          path: |
+            ${{ runner.temp }}/packwright-dist/*.whl
+            ${{ runner.temp }}/packwright-dist/*.tar.gz
+            ${{ runner.temp }}/packwright-dist/release-artifacts.json

packwright-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Deploy Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/pages.yml"
+      - "site/**"
+      - "assets/fonts/**"
+      - "assets/social-preview.png"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+      - name: Stage static site
+        run: |
+          mkdir -p _site/assets/fonts
+          cp -R site/. _site/
+          cp -R assets/fonts/. _site/assets/fonts/
+          cp assets/social-preview.png _site/assets/social-preview.png
+          sed -i 's#../assets/fonts/#assets/fonts/#g' _site/*.html
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

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

@@ -0,0 +1,50 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Verify release tag matches package version
+        run: |
+          PACKAGE_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$GITHUB_REF_NAME" = "v$PACKAGE_VERSION"
+      - run: python -m pip install -e '.[test]'
+      - run: scripts/release-gate.sh --output-dir "$RUNNER_TEMP/packwright-dist"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: |
+            ${{ runner.temp }}/packwright-dist/*.whl
+            ${{ runner.temp }}/packwright-dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/packwright
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

packwright-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes are documented here. Packwright follows Semantic Versioning.
+
+## [0.1.0] - 2026-07-14
+
+### Added
+
+- Stable public release for Codex, Claude Code, and Cursor pack generation, installation, migration, diagnosis, and scoring.
+- Artifact-lock verification and deterministic repair for Packwright-managed projections.
+- First-class `draft-character` and `adopt` creation paths for custom and existing agents.
+
+### Changed
+
+- `build` now refuses to overwrite existing pack artifacts unless `--force` is explicit.
+- `install --force` preserves portable user state under `memory/`, `workspace/`, `knowledge/`, and `sources/`.
+- Emotion Engine sidecar installation is explicit instead of being implied by the default light mode.
+- Distributable metadata no longer records build-machine absolute source paths.
+- Public starter presets are now nameless `code`, `work`, and `companion` starting roles; users supply the character name with `--name` and can customize responsibilities, capabilities, voice, boundaries, and emotional feedback.
+
+### Security
+
+- Reject path traversal, absolute paths, source-root escapes, and destination symlink escapes across build, install, migration, doctor, and scoring paths.
+- Keep `doctor --fix` limited to reproducible managed artifacts while excluding portable and live state.
+
+## [0.1.0rc1] - 2026-07-11
+
+### Added
+
+- Six-command public CLI: `init`, `build`, `install`, `migrate`, `doctor`, and `score`.
+- Native projections for Codex, Claude Code, and Cursor.
+- Read-only migration plans with path-level generated, carried, rewritten, and excluded receipts.
+- Self-contained installed-target metadata and pre/post-install scoring.
+- Static zero-network audit, local release gate, packaging checks, and CI.
+
+[0.1.0]: https://github.com/pioneerjeff-labs/packwright/releases/tag/v0.1.0
+[0.1.0rc1]: https://github.com/pioneerjeff-labs/packwright/releases/tag/v0.1.0rc1

packwright-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Packwright welcomes focused bug fixes, tests, documentation corrections, and adapter improvements. The project values receipts over broad claims: show the behavior, the command, and the verification.
+
+## Development setup
+
+```bash
+git clone https://github.com/pioneerjeff-labs/packwright.git
+cd packwright
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+## Verification
+
+Run the quick gate while iterating:
+
+```bash
+scripts/release-gate.sh --quick
+```
+
+Before opening a pull request, run the complete gate:
+
+```bash
+scripts/release-gate.sh
+```
+
+Every user-visible behavior change needs a test or a concise explanation of why automated coverage is not practical.
+
+## Adapter work
+
+New adapters land when they pass the checker. Open an [adapter request](https://github.com/pioneerjeff-labs/packwright/issues/new?template=adapter_request.yml) first and include:
+
+- the runtime's official instructions, rules, or skills documentation;
+- the native file locations and formats;
+- whether you can test a real local installation;
+- known features that cannot be projected.
+
+An adapter is not complete when it renders files. It must build, install, migrate in both directions where applicable, expose exclusions honestly, and pass the checker.
+
+## Public-data rule
+
+Use synthetic fixtures. Never include real agent memory, credentials, private paths, private launch material, or generated build artifacts. Migration changes must preserve the dry-run-before-write contract and report every generated, carried, rewritten, and excluded path.
+
+## Documentation voice
+
+State what Packwright does and what was tested. Avoid claims such as “seamless,” “magical,” or support for runtimes that do not have a passing adapter. A `100.0` structure score is not a runtime guarantee.

packwright-0.1.0/LICENSE

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

packwright-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include README.md
+include README.zh-CN.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *
+recursive-include assets *.css *.svg *.png *.woff2 *.otf *.txt
+recursive-include site *.html *.css *.svg *.js
+recursive-include specs *.yaml
+recursive-include tests *.py
+recursive-include scripts *.py *.sh
+recursive-include .github *.yml *.yaml *.md
+global-exclude *.py[cod]
+global-exclude .DS_Store

packwright-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: packwright
+Version: 0.1.0
+Summary: Build, install, and migrate portable agent packs across Codex, Claude Code, and Cursor.
+Author: pioneerjeff-labs
+License-Expression: MIT
+Project-URL: Homepage, https://pioneerjeff-labs.github.io/packwright/
+Project-URL: Documentation, https://github.com/pioneerjeff-labs/packwright#readme
+Project-URL: Issues, https://github.com/pioneerjeff-labs/packwright/issues
+Project-URL: Changelog, https://github.com/pioneerjeff-labs/packwright/blob/main/CHANGELOG.md
+Keywords: agents,codex,claude-code,cursor,migration
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: twine>=5.1; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/mark-light.svg">
+    <img alt="Packwright dovetail mark" src="assets/mark-light.svg" width="88" height="88">
+  </picture>
+</p>
+
+<h1 align="center">Packwright</h1>
+
+<p align="center"><strong>Build your agent once. Carry it everywhere.</strong></p>
+
+<p align="center">
+  Compile one agent definition—rules, memory, skills, and workspace—into native packs<br>
+  for Codex, Claude Code, and Cursor. Build, install, migrate, and verify with plain files.
+</p>
+
+<p align="center">
+  <strong><a href="https://pioneerjeff-labs.github.io/packwright/">Explore the live product website →</a></strong><br>
+  Watch the animated CLI, follow a Claude Code → Codex migration, and switch the Quickstart between Claude Code, Codex, and Cursor.<br>
+  <a href="https://pioneerjeff-labs.github.io/packwright/">English</a> · <a href="https://pioneerjeff-labs.github.io/packwright/zh-CN.html">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://pioneerjeff-labs.github.io/packwright/">
+    <img alt="Open the Packwright live product website" src="assets/social-preview.png" width="800">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pioneerjeff-labs.github.io/packwright/"><img alt="Packwright website" src="https://img.shields.io/badge/website-live-9C4F16?style=flat-square"></a>
+  <a href="https://github.com/pioneerjeff-labs/packwright/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/pioneerjeff-labs/packwright/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-5C5245?style=flat-square"></a>
+  <a href="README.zh-CN.md"><img alt="中文 README" src="https://img.shields.io/badge/README-中文-B87333?style=flat-square"></a>
+</p>
+
+<p align="center"><strong>Native packs. Portable state. Preview every migration before any files are written.</strong></p>
+
+> [!NOTE]
+> Packwright itself makes no network requests and sends no telemetry. Your coding runtime may still send files it reads to its own model provider; its data policy continues to apply.
+
+## Start with your coding agent
+
+The shortest interface is a conversation. Install Packwright, then paste the operating prompt into Codex, Claude Code, or Cursor:
+
+```bash
+python -m pip install packwright==0.1.0
+```
+
+**[Open the paste-ready agent prompt →](docs/USE_WITH_YOUR_AGENT.md)**
+
+For a new agent, describe what it should do and choose its name. The prompt makes your coding agent draft a canonical intake, confirm it with you, build the pack, and verify the installed target. For migration, it previews the receipt and waits for approval before writing.
+
+## Create your own
+
+Generate Packwright's interviewer contract, then let your coding agent turn the conversation into a confirmed `character_intake.yaml`:
+
+```bash
+packwright draft-character \
+  --user-name Morgan \
+  --prompt-out work/character-interviewer.md
+```
+
+After the agent saves the confirmed intake, create editable source and build it:
+
+```bash
+packwright init work/nova-intake.yaml -o work/nova
+packwright build work/nova --adapter claude-code -o pack/nova-claude
+packwright install pack/nova-claude --adapter claude-code --target project/nova-claude
+```
+
+Already have an agent or workspace? Inventory it before importing anything:
+
+```bash
+packwright adopt --from existing-agent --dry-run
+```
+
+## Or use a nameless starter
+
+Three presets cover common starting points. Customize responsibilities, capabilities, voice, boundaries, and emotional feedback; the preset shapes how the agent works, while you always choose its name.
+
+| Preset | Starting role |
+|---|---|
+| `code` | Expert engineer — builds, reviews, debugs, tests, and ships technical work |
+| `work` | Versatile assistant — plans projects, drafts deliverables, clarifies decisions, and keeps execution moving |
+| `companion` | Personal secretary — supports daily routines, life decisions, travel planning, and emotional support |
+
+Choose a preset, answer a few simple questions, and supply the character name yourself.
+
+```bash
+packwright init --template code --name Nova --user-name Morgan -o work/nova
+packwright build work/nova --adapter claude-code -o pack/nova-claude
+packwright install pack/nova-claude --adapter claude-code --target project/nova-claude
+```
+
+`Nova` is only an example of a user-chosen name. Edit the generated name, relationship, voice, and boundaries whenever you need.
+
+Preview a move from Claude Code to Codex. The destination is not created during this step:
+
+```bash
+packwright migrate project/nova-claude \
+  --to codex \
+  --target project/nova-codex --dry-run
+```
+
+The plan names four kinds of paths:
+
+| Receipt section | Meaning |
+|---|---|
+| `generated` | Files compiled for the destination runtime |
+| `carried` | Portable user files copied and SHA-256 verified |
+| `rewritten` | Packwright-managed routing lines changed for the destination |
+| `excluded` | Runtime-specific files deliberately left behind |
+
+After reviewing the receipt, apply that exact move and verify the result:
+
+```bash
+packwright migrate project/nova-claude \
+  --to codex \
+  --target project/nova-codex --yes
+packwright doctor project/nova-codex
+packwright score project/nova-codex
+```
+
+Add `--json` to the dry run and confirmed run for a machine-readable `packwright-migration/v1` receipt. Packwright refuses to overwrite an existing target unless you separately opt into `--force`.
+
+## Why not just prompts?
+
+A working coding agent is more than its top-level instructions, and each runtime expects a different native layout:
+
+| Runtime | Native entry | Reusable procedures |
+|---|---|---|
+| Codex | `AGENTS.md` | `.agents/skills/<name>/SKILL.md` |
+| Claude Code | `CLAUDE.md` | `.claude/skills/<name>/SKILL.md` |
+| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/rules/<name>-save-context.mdc` |
+
+Packwright treats those files as compiled projections. Your editable source owns the behavior; adapters own the runtime layout; migration carries portable state and reports the seams instead of hiding them.
+
+## Build once, carry everywhere
+
+```text
+editable source
+  identity · memory contract · skills · workspace rules
+         │
+         ├── packwright build --adapter codex       → AGENTS.md + .agents/skills/
+         ├── packwright build --adapter claude-code → CLAUDE.md + .claude/skills/
+         └── packwright build --adapter cursor      → .cursor/rules/*.mdc
+```
+
+Every pack and installed target includes self-contained `.packwright/` metadata: the canonical source snapshot, artifact lock, and checker receipt. You can relocate a target and still run `migrate`, `doctor`, and `score` without its original build directory.
+
+## Move a working agent
+
+`migrate` recompiles runtime-native files and carries portable state into the destination. It reports what cannot carry before it writes, then waits for an explicit `--yes`. The receipt is the proof behind “carry it everywhere,” not a promise that unlike runtimes have no seams.
+
+## What the checks prove
+
+- `score` evaluates the public pack structure and artifact contract. `100.0` is a structural pass, not a promise that a runtime will behave perfectly.
+- `doctor` verifies Packwright-managed projection hashes and can repair reproducible drift without treating portable user state as generated output.
+- Migration verifies carried and rewritten files by hash and records planned and installed scores.
+- Packwright ships six directed migration paths across the three current adapters. New adapters land when they pass the checker.
+
+## Current release boundary
+
+`0.1.0` is Packwright's first stable release. The supported destination adapters are Codex, Claude Code, and Cursor. Packwright is local tooling, not cloud sync, and its plain-file structure score is separate from real runtime compatibility.
+
+## Documentation
+
+- [Live product website](https://pioneerjeff-labs.github.io/packwright/) · [简体中文](https://pioneerjeff-labs.github.io/packwright/zh-CN.html)
+- [CLI contract](docs/CLI.md)
+- [Use Packwright with your coding agent](docs/USE_WITH_YOUR_AGENT.md)
+- [Character drafting](docs/CHARACTER_DRAFTING.md)
+- [Agent archetypes](docs/AGENT_ARCHETYPES.md)
+- [Optional Emotion Engine sidecar](docs/EMOTION_ENGINE.md)
+- [0.1.0 release notes](docs/releases/0.1.0.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+Packwright is open source under the [MIT License](LICENSE).