[codex] Add README image and polish skill docs#7
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
The new README image improves the first impression, but the surrounding Markdown needed cleanup so the rendered page keeps its list wrapping, table spacing, and final newline intact. Constraint: Preserve the user-added image and README-centered scope Rejected: Rewrite the image section again | the current asset already establishes the visual lead-in Confidence: high Scope-risk: narrow Reversibility: clean Tested: git diff --check; bash -n install.sh; copy install into temporary Codex and Claude homes; symlink install into temporary Codex home Not-tested: Browser-rendered GitHub README image preview
The PR branch needed the latest master base, and the only conflict was README.md. The branch README is intentionally the source of truth here because it contains the image placement and expanded visitor-facing documentation. Constraint: User explicitly requested accepting our README Rejected: Take master README | it would drop the PR branch documentation and image work Confidence: high Scope-risk: narrow Reversibility: clean Directive: Preserve assets/handoff.png and the expanded README unless replacing the visual/docs direction intentionally Tested: Conflict resolution staged cleanly with no unmerged paths Not-tested: Post-merge installer validation before this merge commit
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
assets/handoff.pngimage to the README hero area.masterfocused on the skill distribution shape withinstall.shandskills/.Why
The README should quickly communicate what portable-handoff is, when to use it, and how to install it. The image gives the page a stronger first impression, while the surrounding documentation explains the purpose and common handoff scenarios for new visitors.
Validation
git diff --checkbash -n install.sh./install.sh both --home "$tmp" --mode copy./install.sh codex --home "$tmp" --mode symlinkgit show --check --stat --oneline HEADNotes
This is a new PR branch created from the current image commit. The earlier draft PR branch
codex/skill-branch-docsremains unchanged.