HTML explainers for work items + provider-agnostic publish#2
Merged
Conversation
- New shared reference html-explainer.md + explainer-template.html: create-* skills render refs/explainer.html and auto-open it in the user's browser as the alignment surface before the Socratic gate. - publish-work-item.md reframed: GitHub-only (marker comments) is the default; an artifact host is a per-project CLAUDE.md provider opt-in. - notion skill: page body is a high-level summary; item.md + refs attach to the database Files property; raw/ sub-pages kept for reliable pull. - templates/CLAUDE.md documents the provider: opt-in. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
tbrownio
force-pushed
the
atlantic-confidence
branch
from
July 12, 2026 19:46
dd65880 to
133bc2f
Compare
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
Plans produced by
/create-feature,/create-epic, and/create-issuenow come with a visual HTML explainer, and the publish path no longer hardcodes Notion.references/html-explainer.md+references/explainer-template.html— shared procedure and skeleton. Each create-* skill renders./tmp/<id>/refs/explainer.html(self-contained, light/dark themed) right after draftingitem.mdand opens it in the user's browser automatically. This page — before/after, proposed direction with locked decisions, scope, ACs, open questions — is the alignment surface;item.mdstays the machine-facing contract/doexecutes against.references/publish-work-item.md— provider-agnostic: GitHub-only (artifacts asORCHESTRA-ARTIFACTmarker comments) is the default; a richer artifact host is opted into per project via theCLAUDE.mdWork-item trackingsection (provider: notion). GitHub issue attachments have no API/CLI upload path, hence the marker-comment baseline.notionskill — page body is now a high-level summary (board card, not a mirror);item.md+ allrefs/(including the explainer) attach to the database's Files property (files: "Files"inconfig.yaml, page-body fallback);raw/code-block sub-pages kept since attachment URLs expire andpulldepends on them.templates/CLAUDE.md— documents theprovider:opt-in.Why
Aligning on a plan against raw
item.md/Notion markdown was hard; the explainer gives the user a two-minute visual read of the change and the implementation direction, and travels through the existingrefs/pipeline so/dogets it too.Notes
/do's Step 0 wording still names the notion skill directly; functionally it degrades correctly without a provider. Follow-up issue tracks making provider references fully generic.🤖 Generated with Claude Code