[codex] Polish skill-only handoff docs#6
Merged
Conversation
Add a dedicated handoff-install command that installs the handoff and get-handoff skill folders into Codex or Claude. Local checkout installs default to symlinks for iterative testing, while packaged installs copy bundled skill assets. Constraint: Runtime handoff UX remains skill-first; CLI is only for installation Rejected: Reintroduce handoff runtime commands | would blur the approved /handoff and /get-handoff product surface Confidence: high Scope-risk: narrow Directive: Keep handoff-install focused on skill installation only Tested: python -m unittest discover -s tests -p 'test_install.py' -v Tested: PYTHONPATH=src python -m unittest discover -s tests -v Tested: python -m compileall src tests Tested: pip --prefix smoke install followed by handoff-install codex --mode copy Not-tested: Published package marketplace installation
The skill files are the current product surface, so master no longer needs to carry the Python package, library tests, or internal superpowers planning docs. Those artifacts remain available on the python-package-docs branch while master ships a small bash installer and shell-only CI validation. Constraint: Skills execute as agent instructions and do not depend on the Python package Rejected: Keep Python installer on master | it makes the public branch look like a Python package when the intended surface is skill installation Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep Python/library experiments on python-package-docs or another feature branch unless master intentionally becomes a package again Tested: bash -n install.sh; copy install into temporary Codex and Claude homes; symlink install into temporary Codex home; skill metadata grep checks; git diff --check Not-tested: Real Codex or Claude runtime reload after install
The repository now presents portable-handoff as a skill-first handoff protocol, so the README needs to explain the purpose, use cases, workflow, storage model, and install modes before a visitor has to inspect the skill files. Constraint: Master intentionally ships only skills plus a shell installer Rejected: Add a separate docs site | too much surface for a compact skill distribution branch Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep the README aligned with the skill-only master branch unless Python packaging returns to master Tested: bash -n install.sh; copy install into temporary Codex and Claude homes; symlink install into temporary Codex home; git diff --check Not-tested: Rendered GitHub markdown in browser
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
masterfocused on the skill-only distribution surface:skills/,install.sh, README, and lightweight GitHub metadata.python-package-docsbranch.Why
The skills do not depend on the Python package at runtime. This makes
mastereasier for visitors to understand: it now presents portable-handoff as a compact skill distribution repo rather than a Python library.Validation
bash -n install.sh./install.sh both --home "$tmp" --mode copy./install.sh codex --home "$tmp" --mode symlinkgit show --check --stat --oneline HEADNotes
gh auth statusreports an invalid local GitHub CLI token, so the branch was pushed withgitand this PR was opened with the GitHub connector.