docs(install): rewrite install docs as a literal, audience-scoped step-by-step - #48
Merged
Merged
Conversation
…p-by-step Turn the scattered install path (README + environment-setup + per-CLI runbooks) into a single, followable hierarchy: README points to environment-setup.md as the sole CLI-agnostic canon, which links into setup-claude.md/setup-opencode.md — each a strict numbered checklist (one command or link per step, ending in a verify step using the real skillery-opencode status/plugin commands where applicable). Also separates audiences that had drifted together: mapping.md, compatibility.md, and body-agnosticism-audit.md are contributor-facing contract docs, not install docs, and are now labeled as such; dual-cli/README.md is reframed as that contributor annex instead of a competing install entry point. Fixes several factual gaps found along the way: stream-coding had no install command anywhere, superpowers/ponytail were documented as a .claude/skills/ copy on opencode when both now ship native opencode plugins, and setup-opencode.md was missing the mandatory-dependencies step entirely. Adds a step-by-step mcp-setup.md covering all 7 referenced MCP servers with real package-install commands, not just config templates. Archives the driving OpenSpec change and syncs the dual-cli-distribution spec's "Per-CLI documentation split" requirement to match. Co-Authored-By: Claude Sonnet 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
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.
Summary
README.md→docs/environment-setup.md(CLI-agnostic canon) →setup-claude.md/setup-opencode.md(literal numbered steps, one command/link each, ending in a real verify step).mapping.md,compatibility.md,body-agnosticism-audit.mdare labeled contributor-facing (not install docs);dual-cli/README.mdreframed as that contributor annex instead of a competing install entry point.docs/dual-cli/mcp-setup.md: step-by-step for all 7 referenced MCP servers (GitNexus, Atlassian, Google Workspace, Odoo, Neo4j, MongoDB, context7) with real package-install commands, not just config templates. Linked fromenvironment-setup.md.stream-codinghad no install command anywhere (now: real upstream + clone/copy commands);superpowers/ponytailwere documented as a.claude/skills/copy on opencode when both now ship native opencode plugins (fixed incompatibility.mdandsetup-opencode.md);setup-opencode.mdwas missing the mandatory-external-dependencies step entirely (added, matching the Claude side).setup-opencode.md's verify step now uses the realskillery-opencode statuscommand (and mentions--dry-run) instead of a vague "ask the agent to list its skills" — cross-checked against Grzegorz'sskillery-opencodeCLI implementation to make sure every command/flag referenced actually exists.step-by-step-install-guide) and syncs thedual-cli-distributionspec's "Per-CLI documentation split" requirement to match what shipped.Test plan
openspec validate --changes step-by-step-install-guide --strictandopenspec validate --all --strictboth pass.make validate(needs a local.venv, not available in this environment — please run in CI).🤖 Generated with Claude Code