Add a getting-started guide and beginner path

[AbanoubGhadban]

Why

The repository has extensive reference documentation but no supported path from “I cloned this” to “I ran a workflow and saw it work.” New users meet advanced coordination details before they have installed the pack or completed one workflow.

Refs #394.

What changed

• Adds docs/getting-started.md, a beginner path covering prerequisites, flat and plugin installation, one-repository adoption, $verify, a first single-target $pr-batch, PR review, upgrades, and common failures.
• Adds a leading Start here entry to docs/README.md and links the guide from the root Quick Start.
• Trims ShakaCode-specific stack detail from the generic Quick Start while retaining links to its canonical documentation.
• Links the source-pack and batch-coordination glossaries in both directions.
• Aligns the multi-PR guidance with the current throughput policy: issue-authored semantic dependencies and active reservations order work; file overlap is advisory.

Changelog classification: deferred_to_update_changelog.

Verification

• markdownlint-cli2@0.23.2 on all five changed Markdown files: PASS, 0 issues.
• Local Markdown target check on all five changed files: PASS.
• git diff --check: PASS.
• Full exact-head bin/validate at 96e4cdbe50bdab400286194f7a5d273b30585895: PASS, exit 0; no surviving validator process group, writer, or Git lock.

Follow-ups

Issue #394 should remain open for its independent follow-ups, including a human-facing per-skill reference and simplifying the advanced adoption checklist. The lint-toolchain documentation item is being handled separately by PR #594.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ec85def8-8fb5-4046-812f-874368e310c4

📥 Commits

Reviewing files that changed from the base of the PR and between bdb534f and 124f652.

📒 Files selected for processing (2)

• CHANGELOG.md
• docs/getting-started.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CHANGELOG.md

---

Walkthrough

Added a beginner-oriented getting-started guide with installation, repository adoption, verification, contribution, review, lifecycle, and troubleshooting instructions. Updated README navigation, Quick Start guidance, glossary links, and the changelog.

Changes

Onboarding documentation

Layer / File(s)	Summary
Getting-started setup and adoption docs/getting-started.md	Adds prerequisites, installation, repository adoption, command detection, trust defaults, and wrapper validation instructions.
Verification and contribution workflows docs/getting-started.md	Documents verification, issue-to-PR, review, coordination, testing, and post-merge workflows.
Pack lifecycle and troubleshooting docs/getting-started.md	Documents upgrades, rollback, status, exit codes, and troubleshooting.
Documentation navigation and terminology README.md, docs/README.md, CONTEXT.md, docs/source-pack-glossary.md, CHANGELOG.md	Links the new guide and glossary references from repository documentation, simplifies Quick Start guidance, and records the changes.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 124f6

This documentation change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Possibly related issues

• Docs: no beginner path — add getting-started guide, prerequisites, and a worked end-to-end example #394 — Covers the beginner onboarding, Quick Start, glossary, and documentation navigation objectives implemented here.

Possibly related PRs

• shakacode/agent-workflows#71 — Introduced glossary content that this PR cross-links.
• shakacode/agent-workflows#91 — Introduced the agent-stack sync workflow documented in the updated setup guidance.
• shakacode/agent-workflows#107 — Introduced seam initialization behavior documented by the new guide.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a beginner-oriented getting-started guide and path.
Description check	✅ Passed	The description includes the problem, scope of changes, verification results, changelog classification, references, and follow-ups. It uses a Verification heading instead of the template's How to revi…

Full details: Description check

Explanation

The description includes the problem, scope of changes, verification results, changelog classification, references, and follow-ups. It uses a Verification heading instead of the template's How to review and verify and Test plan headings, but it provides the required review and test information.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch 394-docs-no-beginner-path-add-getting-started

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 394-docs-no-beginner-path-add-getting-started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Reviewed this docs-only PR (code quality, correctness, security, performance lens).

Verification performed:

• Confirmed every anchor link resolves: installation-and-upgrades.md#install, #full-stack-contributor-setup, #full-stack-doctor all match their actual ##/### headings.
• Confirmed all referenced binaries/behavior exist and match documented output verbatim: bin/install-agent-workflows printed-instructions block, agent-workflows-status UP_TO_DATE version=... revision=... delivery_mode=... target=... format string, agent-workflow-seam-doctor's PASS agent workflow seam is complete string, its JS-lockfile/script auto-detection logic (exactly one of package-lock.json/pnpm-lock.yaml/yarn.lock + matching validate/test scripts), and the trust-config defaults (trusted_users/trusted_bots/trusted_teams empty, trusted_metadata_bots: [github-actions]).
• Confirmed the Git 2.41+ claim for the pinned-copy drift checker matches docs/adoption.md's stated requirement.
• Confirmed /scw:verify naming and the "reads seam → runs checks in order → PASS/FAIL per command, stop on first failure" reporting contract match docs/installation-and-upgrades.md and skills/verify/SKILL.md.
• Confirmed the Ruby-based CLIs (agent-workflow-seam-doctor, agent-workflows-status) only require stdlib (optparse, yaml, json, etc, fileutils, open3, shellwords, rbconfig), supporting the "plain Ruby only — no gems" prerequisite claim.
• Checked docs/README.md's "first six sections" count against the actual heading list — accurate after the new "Start here" section.
• Checked the README Quick Start trim: the removed signing-key/trust-anchor and agent-stack doctor paragraphs' substance is present at the linked #install/#full-stack-doctor anchors (one exact phrase, "human waivers," isn't reproduced verbatim at #install, but this is already disclosed as a reviewed NIT in the PR's own checker notes, and the substantive content — no signing keys/trust anchors/receipts required — is preserved).

No bugs, broken links, security issues, or performance concerns found — this is a documentation-only change with no executable/runtime surface. Nice level of self-verification already baked into the PR description (byte-for-byte checker replay of captured output blocks).

One small thing worth a maintainer glance rather than a blocking issue: the PR's own open question about whether #394 should stay open for items 4–7 is still unresolved — worth deciding before merge so the issue doesn't go stale.

[claude]

Review Summary

Reviewed the diff (gh pr diff 416) against the actual implementation in this checkout. This is a documentation-only PR (docs/getting-started.md new + 4 supporting edits), so I focused on factual accuracy rather than logic bugs, since inaccurate onboarding docs are worse than no docs.

Verification performed

Cross-checked essentially every concrete claim in docs/getting-started.md against the actual code:

• All referenced binaries exist and support the exact flags shown: bin/install-agent-workflows (--host, --target, --delivery-mode flat|plugin-companion, DELIVERY_MODE_CONFLICT), bin/agent-workflow-seam-doctor (--init, --validate-command, --test-command, --shared), bin/agent-workflows-status (--fetch, and the exact UP_TO_DATE/UPGRADE_AVAILABLE/NOT_INSTALLED/CHECK_FAILED output strings + exit codes), bin/upgrade-agent-workflows (--consumer-root, --dry-run, --no-fetch, UPGRADE_COMPLETE/ROLLBACK_COMPLETE).
• The literal installer output block ("Installed ShakaCode agent workflows into:", "Add this to PATH if needed:", etc.) matches bin/install-agent-workflows source verbatim.
• trusted_metadata_bots defaulting to ["github-actions"] on --init is accurate (bin/agent-workflow-seam-doctor:1505).
• The merge_authority: ask walkthrough behavior described in Step 4 (auto-start $pr-walkthrough, restart/stop on diff-identity change, single final merge question) matches skills/pr-batch/SKILL.md almost verbatim.
• The "file overlap is advisory, issue-authored semantic dependencies order work" claim matches skills/plan-pr-batch/SKILL.md:869.
• All 15+ internal links (including anchored ones like installation-and-upgrades.md#full-stack-doctor, adoption.md#configure-project-writing-style) resolve to real headings.
• All referenced skills (verify, pr-batch, pr-walkthrough, adversarial-pr-review, untrusted-contributor-intake, spec, tdd, etc.) exist under skills/.
• The docs/README.md "first six sections" count matches the actual section count after adding "Start here".
• The UTF-8/locale troubleshooting entry matches recent test coverage in bin/agent-workflows-status-test.rb / bin/agent-workflow-seam-doctor-test.rb.

I did not find any broken links, misstated flags/output, or behavior claims that diverge from the code.

Code quality / style

• No blocking issues found.
• Minor, non-blocking nit: docs/getting-started.md uses Title-Case headings (## Step 1 — Install The Pack Into One Host), which matches installation-and-upgrades.md's style but differs from docs/README.md's sentence-case headings (## Understand the project). Pre-existing inconsistency in the repo, not introduced by this PR — not worth blocking on.
• The Quick Start trim in README.md (replacing the inline agent-stack doctor command block with two links) is a clean simplification; the target anchors (#full-stack-contributor-setup, #full-stack-doctor) still contain the full detail, so no information is lost.

Security

No security implications — this PR touches only Markdown documentation, no executable code, workflow files, or trust configuration.

Test coverage / CI

The PR description states markdownlint-cli2 and a local Markdown-target check both passed on all 5 changed files, and git diff --check passed. That's the appropriate verification bar for a docs-only change; nothing further needed.

Overall: well-scoped, unusually well-verified documentation addition. Approve.

[claude]

Review

Overview: Adds docs/getting-started.md, a beginner on-ramp (prerequisites → install → adopt → run $verify → run $pr-batch single-lane → review a PR), links it from README.md and docs/README.md, trims ShakaCode-specific stack detail out of the root Quick Start in favor of a pointer, cross-links the two glossaries (CONTEXT.md ↔ docs/source-pack-glossary.md), and aligns the multi-PR overlap guidance with current policy (semantic dependencies/reservations order work; file overlap is advisory).

Verification performed

I fact-checked the new guide's concrete claims against the actual repo state rather than taking them on faith:

• All referenced skills exist (verify, pr-batch, pr-walkthrough, adversarial-pr-review, untrusted-contributor-intake, address-review, spec, evaluate-issue, plan-review, tdd, verify-pr-fix, replicate-ci, update-changelog, post-merge-audit).
• All referenced bin commands exist (install-agent-workflows, agent-workflow-seam-doctor, agent-workflows-status, upgrade-agent-workflows).
• All internal doc anchors resolve (installation-and-upgrades.md#troubleshooting, #upgrade, #full-stack-contributor-setup, #full-stack-doctor, #native-plugin-paths; adoption.md#configure-project-writing-style).
• DELIVERY_MODE_CONFLICT, plugin-companion, and the native-plugin commands (/plugin marketplace add, codex plugin add) match installation-and-upgrades.md.
• The seam-doctor --init lockfile-detection logic (npm/pnpm/yarn, validate/test scripts) and the trusted_metadata_bots: ["github-actions"] fail-closed default match bin/agent-workflow-seam-doctor.
• The reworded multi-PR overlap policy ("semantic dependencies and active reservations order work; file overlap is advisory... ordinary documentation is advisory") matches skills/plan-pr-batch/SKILL.md.
• The Ruby "this repo's CI pins 3.4" claim matches .github/workflows/{lint,validate,downstream-seam-audit}.yml.
• The docs/README.md "first six sections" edit correctly counts the six user-path sections (Start here, Understand, Install and adopt, Run workflows, Operate safely, Troubleshoot) before the reference section.

I did not find any factual inaccuracies, broken links, or internal inconsistencies in the new content.

Code quality / style

• The guide is well-structured: numbered steps build linearly, each "plain-word definition" callout is genuinely necessary (source pack, policy seam, lane, worker, coordinator, merge authority) rather than padding.
• Good discipline around honesty: every synthetic transcript is explicitly labeled "example rather than a captured run," and real command output is distinguished from illustrative output — consistent with the PR's own "never present constructed output as a real run" principle stated later in the doc.
• The security framing is correctly threaded through (issue/PR bodies as untrusted evidence, not instructions) rather than bolted on as an afterthought.
• Minor: the doc is long (626 lines) for a "getting started" guide. It's well-sectioned with a "Getting The Best Results" grab-bag near the end that arguably belongs in a separate follow-on doc rather than the first-run guide, since a first-time reader's goal (steps 1–5) is done by line ~440. Not blocking — just flagging for a possible future split per the PR's own "Follow-ups" note about issue Docs: no beginner path — add getting-started guide, prerequisites, and a worked end-to-end example #394's remaining items.

Potential issues / risks

• None functional — this is docs-only, no code/behavior changes, so risk is limited to documentation drift if referenced commands/output formats change later (e.g., exact agent-workflows-status token format, exact seam-doctor generated file list). That's an inherent maintenance cost of "real output" walkthroughs, not a defect in this PR.
• Nit: README.md's trimmed full-stack-setup paragraph condenses several sentences (doctor ownership, degraded-vs-failed dashboard semantics, contract details) into a single pointer to installation-and-upgrades.md#full-stack-contributor-setup and #full-stack-doctor. Confirmed those anchors do carry the removed detail, so this is a legitimate move-not-loss, not an information cut.

Test coverage

Docs-only change; the PR body's verification section (markdownlint, local Markdown target check, git diff --check) is an appropriate verification scope for this kind of PR. No code paths to unit test.

Security considerations

No security-relevant code changes. The new guide reinforces (rather than weakens) the existing trust model — it explicitly frames PR/issue content as untrusted evidence in Steps 4 and 5, matches the documented untrusted-contributor-intake and adversarial-pr-review skill behavior, and doesn't introduce any new command examples that bypass the fail-closed trusted-github-actors.yml defaults.

Overall: a solid, accurate, well-cross-referenced addition that closes a real gap (no beginner path). No blocking issues found.