Skip to content

Phase 5 onboarding - #6

Merged
tweinmann merged 7 commits into
mainfrom
phase-5-onboarding
Oct 29, 2026
Merged

tweinmann merged 7 commits into
mainfrom
phase-5-onboarding

Conversation

@tweinmann

Copy link
Copy Markdown
Owner

Phase 5 (v0.5): onboarding. A first-time user can install siding from a release, prepare a repository, and start a new worktree with its skill, env files and data, by following the README.

These are the gaps found when reviewing the user journey, each closed:

Releases

  • just dist <version> builds static binaries for macOS and Linux, arm64 and amd64, plus SHA256SUMS.
  • .github/workflows/release.yml runs on v*.*.* tags. It runs just test and just dist inside the devcontainer, then publishes a GitHub Release with gh. Only this job gets contents: write.
  • The README explains how to install: checksum, chmod, PATH, and macOS's quarantine flag. The binaries are not signed yet.

The skill for any harness

  • siding skill --install writes .claude/skills/siding/SKILL.md at the worktree's top and says to commit it. A new worktree only has committed files.
  • --dir <skills dir> installs into any other harness, and --dir ~/.claude/skills installs for every repository.
  • It prints a section for AGENTS.md and the permissions for siding's reading commands (up, status, logs, ps), as a Claude Code entry and as a plain list. siding never writes either file.
  • The skill's text names no harness.

Env files of the main worktree

  • Without .env, Compose starts a stack with blank values and only a warning. So in a linked worktree, siding up now fails with the new code EnvFileMissing when it lacks .env, or a required env_file, that the main worktree has untracked. The hint gives the cp command.
  • siding lint warns MissingEnvFile for the same files.
  • siding never copies the files itself, because they hold secrets.

LocalhostURL

  • siding lint warns about environment values pointing at localhost:<port>, 127.0.0.1:<port> or [::1]:<port>. Behind the proxy, these reach the service's own container.
  • The finding names the variable and the host:port, never the rest of the value. A test pins that a password in a URL does not leak.

The snapshot default

  • A stack's first up without --seed seeds from the repository's snapshot named default, if there is one, and says so on stderr. An agent's first up in a new worktree gets the data without knowing about snapshots.
  • --seed none starts empty. none is a reserved snapshot name.

README

  • New "Why siding": the problem, what siding does about it, an example verdict, and what siding is not.
  • "Using siding" is now "Get started", six steps in the order of the user journey, followed by "Reference".

Specs

  • New: releases.
  • Updated: agent-skill, cli-contract, compose-lint, seeding, snapshots, stack-lifecycle.
  • The change is archived as openspec/changes/archive/2026-10-29-phase-5-onboarding.

Verification

  • just test passes, golangci-lint reports 0 issues.
  • just smoke-stacks passes. It includes a new end-to-end onboarding test:
    • a linked worktree without .env is refused, then is Ready after the cp from the hint;
    • it is seeded from default, and GREETING comes from .env;
    • --seed none starts empty;
    • skill --install writes the skill.
  • The README's "Get started" was walked on macOS with Docker Desktop, with v0.5.0-rc1 binaries from just dist, without problems or gaps.
  • The release workflow itself runs for the first time with the tag v0.5.0 after this merge.

🤖 Generated with Claude Code

tweinmann and others added 7 commits October 29, 2026 19:47
Releases, siding skill --install with the permission snippet,
EnvFileMissing, the lint rule LocalhostURL and a default snapshot,
as agreed after reviewing the user journey.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Releases with just dist, siding skill --install for any harness with
the AGENTS.md and permission snippets, EnvFileMissing for env files of
the main worktree, the lint rule LocalhostURL, the snapshot default,
and a README that follows the user journey.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hostURL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New spec releases; agent-skill, cli-contract, compose-lint, seeding,
snapshots and stack-lifecycle updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tweinmann
tweinmann merged commit eab7716 into main Oct 29, 2026
4 checks passed
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