Skip to content

Re-cut the roadmap; Phase 9: agent interface - #5

Merged
tweinmann merged 2 commits into
mainfrom
roadmap-recut
Oct 27, 2026
Merged

tweinmann merged 2 commits into
mainfrom
roadmap-recut

Conversation

@tweinmann

Copy link
Copy Markdown
Owner

Two commits:

  1. Roadmap re-cut (docs only). shelf is repositioned as a platform for parallel coding-agent branches as isolated, verified previews. The core thesis comes before the host: 9 agent interfa
    ce, 10 branch previews, 11 verification chain, 12 hardening, 13 host (macOS and Linux), 14 service and installer, 15 operations, 16 eject. The wizard is deferred, and the reference apps become
    acceptance criteria. Updates openspec/config.yaml, CLAUDE.md (three new guardrails) and the README, and turns the phases into draft changes.
  2. Phase 9, openspec/changes/phase-9-agent-interface.
    • --json on the read-only commands: versioned documents with golden files.
    • shelf app status <app> --wait --commit <sha> returns a verdict with exit status 0/1/2.
    • shelf app status shows the commit the running artifact was built from.
    • shelf app open forwards to Traefik through the API server, listening on 127.0.0.1 only.
    • examples/tenant gets a Claude Code skill and a CLAUDE.md.
    • just smoke-agent is new and in the CI matrix.

Worth a look

  • How --wait knows the release caught up (design.md, decision 4). The first, timestamp-based version gave a fixed commit the verdict Failed: after a broken upgrade, both the failure and
    the rollback are newer than the fix. A spike on the dev cluster recorded the HelmRelease timeline, which is now in design.md. The verdict now compares helm-controller's configDigest with a d
    igest shelf computes the same way. A unit test pins that computation to a digest helm-controller wrote.
  • go.mod. client-go's port-forward adds three indirect modules from client-go's own dependency graph; no new direct dependency.

Checks

  • just test passes.
  • just smoke-agent passed against the dev cluster, including a fixed commit after a broken one.
  • Still open: tasks 6.1 and 6.2 (smoke-agent on a fresh cluster in CI) are checked by this PR's cluster (smoke-agent) job. Expect about 10 minutes per run, because Helm times out the broke
    n upgrade first.
  • After that: the maintainer's acceptance (an agent in a copy of examples/tenant, shelf app open in the Mac's browser), then /opsx:archive.

🤖 Generated with Claude Code

tweinmann and others added 2 commits October 27, 2026 20:27
shelf is repositioned as a self-hosted GitOps platform for running
parallel coding-agent branches as isolated, verified previews, with a
path to production through eject. The core thesis comes before the host:
9 agent interface, 10 branch previews, 11 verification chain,
12 hardening, 13 host (macOS and Linux), 14 service and installer,
15 operations, 16 eject. The wizard moves to "Later"; the reference apps
become the acceptance of previews and eject.

New guardrails: exposure is an operator decision, agent-facing commands
offer --json, and the runtime output depends on no shelf-specific CRD.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase 9. Coding agents in tenant repositories get a machine-readable
contract, and people get browser access to private apps:

- --json on app status, app tags, connection list and version: one
  versioned document (shelf.dev/v1alpha1, a kind) per command, errors
  as Error documents, golden files per kind. No JSON for secrets.
- shelf app status <app> --wait [--commit <sha>]: waits until the app
  runs the artifact built from that commit and every stage caught up
  with it, then prints a verdict; exit 0 Ready, 1 Failed, 2 TimedOut.
  Read-only. The commit comes from the artifact's revision annotation,
  and whether the Helm release holds the current values from
  helm-controller's configDigest, reproduced exactly (timestamps were
  wrong after a failed upgrade and its rollback; see design.md).
- shelf app status shows the commit of the running artifact.
- shelf app open <app>: a client-go port-forward to Traefik behind a
  local proxy on 127.0.0.1 that sets the app's Host header.
- examples/tenant: a Claude Code skill and CLAUDE.md for the loop.
- just smoke-agent, also in the CI matrix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tweinmann
tweinmann merged commit 35848bb into main Oct 27, 2026
6 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