Skip to content

Add docs/landscapes/vaultctl/ with design decision records #42

Description

@f3rdy

Description

Promote vaultctl to its own landscape with a structured place for design decisions. The tool has accumulated several cross-cutting design choices that should be discoverable outside of code comments and PR descriptions:

  • Python over Go/Rust (sprachlicher Stack)
  • CUE schema validation via subprocess (no native Python binding)
  • Project-local `.vaultctl/` directory layout
  • Schema inference via Python walker, not `cue import`
  • Baseline + constraints split for hand-edited rules

Why a Landscape (and not just docs/decisions/)

Per the global Claude Code convention, landscapes are typically used to group cross-repo work for client engagements. Tool repos historically don't have landscapes. Deviation: vaultctl is now mature enough (v1.0.0) and has enough cross-cutting decisions to benefit from the same structure — LANDSCAPE.md + decisions/ + (eventual) patterns/ — even though it's a single-repo tool.

If the convention should win and we'd rather use `docs/decisions/` flat, easy to rename later.

Scope (this issue)

  • Create `docs/landscapes/vaultctl/LANDSCAPE.md` — minimal entry point, lists current decisions.
  • Create `docs/landscapes/vaultctl/decisions/` directory.
  • First ADR: schema inference via Python walker vs `cue import` (the immediate motivation).
  • Reference the landscape from project `CLAUDE.md` (per global pattern).

Subsequent ADRs (Python vs Go, CUE subprocess, .vaultctl/ layout) can be backfilled in follow-up PRs as they become relevant.

Files

  • `docs/landscapes/vaultctl/LANDSCAPE.md` (new)
  • `docs/landscapes/vaultctl/decisions/0001-schema-inference-via-python-walker.md` (new)
  • `CLAUDE.md` (add landscape reference)

Priority

P3

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions