Skip to content

docs(install): rewrite install docs as a literal, audience-scoped step-by-step - #48

Merged
costezki merged 1 commit into
developfrom
feature/step-by-step-install-guide
Jul 24, 2026
Merged

docs(install): rewrite install docs as a literal, audience-scoped step-by-step#48
costezki merged 1 commit into
developfrom
feature/step-by-step-install-guide

Conversation

@costezki

Copy link
Copy Markdown
Contributor

Summary

  • Single install hierarchy: README.mddocs/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).
  • Separated audiences that had drifted together: mapping.md, compatibility.md, body-agnosticism-audit.md are labeled contributor-facing (not install docs); dual-cli/README.md reframed as that contributor annex instead of a competing install entry point.
  • New 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 from environment-setup.md.
  • Fixed factual gaps found while writing this: stream-coding had no install command anywhere (now: real upstream + clone/copy commands); superpowers/ponytail were documented as a .claude/skills/ copy on opencode when both now ship native opencode plugins (fixed in compatibility.md and setup-opencode.md); setup-opencode.md was missing the mandatory-external-dependencies step entirely (added, matching the Claude side).
  • setup-opencode.md's verify step now uses the real skillery-opencode status command (and mentions --dry-run) instead of a vague "ask the agent to list its skills" — cross-checked against Grzegorz's skillery-opencode CLI implementation to make sure every command/flag referenced actually exists.
  • Archives the driving OpenSpec change (step-by-step-install-guide) and syncs the dual-cli-distribution spec's "Per-CLI documentation split" requirement to match what shipped.

Test plan

  • Manual top-to-bottom read of both runbooks — no forward references, one action per step, ends in a verification step.
  • Scripted check that every relative markdown link/anchor across the touched docs resolves.
  • openspec validate --changes step-by-step-install-guide --strict and openspec validate --all --strict both pass.
  • make validate (needs a local .venv, not available in this environment — please run in CI).

🤖 Generated with Claude Code

…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>
@costezki
costezki merged commit 17127a8 into develop Jul 24, 2026
5 checks passed
@costezki
costezki deleted the feature/step-by-step-install-guide branch July 24, 2026 06:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant