From 39bec5c7976f46cf3f268400576ec34bf7138139 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sat, 25 Jul 2026 19:37:52 -0700 Subject: [PATCH 1/4] Complete local operating contract positioning --- .github/copilot-instructions.md | 9 ++--- AGENTS.md | 4 ++- CONTRIBUTING.md | 4 ++- FAQ.md | 4 +-- docs/README.md | 8 ++++- docs/base-bash-libs.md | 3 +- docs/presentations/README.md | 3 +- .../base-newcomer-orientation.md | 21 ++++++++---- docs/technical-overview.md | 34 ++++++++++++------- skills.md | 5 +-- 10 files changed, 64 insertions(+), 31 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5da25dc0..9ccd622f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -5,10 +5,11 @@ exist to point Copilot at the same repository-owned rules used by other coding agents; they do not replace `AGENTS.md`, `CONTRIBUTING.md`, `STANDARDS.md`, or the `.ai-context/` orientation files. -Keep Base focused as the shared developer workspace control plane. Project -application code, project-specific setup, service behavior, and one-off local -machine preferences belong in the owning project unless Base is explicitly the -right shared layer. +Keep Base focused as the local operating contract for deterministic readiness +and handoff across independent Git repositories. Its durable loop is inventory +-> prepare -> verify -> trust -> onboard -> hand off. Project application code, +project-specific setup, service behavior, and one-off local machine preferences +belong in the owning project unless Base is explicitly the right shared layer. For implementation work, use Base's issue-backed workflow: diff --git a/AGENTS.md b/AGENTS.md index c3bbc605..4f73efa1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,9 @@ them. ## Working Agreement - Follow `CONTRIBUTING.md` for workflow and `STANDARDS.md` for code standards. -- Keep Base focused as the shared developer workspace control plane. +- Keep Base focused as the local operating contract for deterministic readiness + and handoff across independent Git repositories. Its durable loop is + inventory -> prepare -> verify -> trust -> onboard -> hand off. - Keep project-specific setup, service code, and application behavior in the owning project repository unless Base is explicitly the right shared layer. - Adopt external agent workflow ideas only after translating them into diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b3b2a02..b2d0c65a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,9 @@ # Contributing to Base Base is a developer tooling repository. Contributions should keep the project -opinionated, testable, and useful as a shared workspace control plane. +opinionated, testable, and useful as a local operating contract for deterministic +readiness and handoff across independent Git repositories. The durable product +loop is inventory -> prepare -> verify -> trust -> onboard -> hand off. ## AI-Assisted Development diff --git a/FAQ.md b/FAQ.md index aa30b8fb..1d4af604 100644 --- a/FAQ.md +++ b/FAQ.md @@ -148,8 +148,8 @@ while `base_cli` answers "how should a Base Python CLI behave?" See the Base's reusable Bash helpers live in the standalone `basefoundry/base-bash-libs` repository so other scripts can reuse the logging, -command execution, filesystem, and Git conventions without depending on the -full Base workspace control plane. +command execution, filesystem, and Git conventions without depending on Base's +full local operating contract for multi-repository readiness and handoff. That separation also keeps the Homebrew packaging path cleaner: `base-bash-libs` can mature as its own formula, and a future Homebrew/core Base formula can diff --git a/docs/README.md b/docs/README.md index be9435ed..aa7021a8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,11 @@ see [Release Process](release-process.md). For self-guided or live walkthrough material, see [Presentations](presentations/README.md). +Base's product outcome is a local operating contract for deterministic readiness +and handoff across independent Git repositories. The durable loop is +inventory -> prepare -> verify -> trust -> onboard -> hand off. See [Why Base](why-base.md) +for the concise product framing; the map below links to the deeper references. + ## Internal Planning Artifacts The `docs/superpowers/` directory contains agent-written planning artifacts @@ -104,7 +109,8 @@ reference. The filename should answer "what is this about?" - [Base Presentations](presentations/README.md) documents the presentation source-of-truth and export policy. - [Base Newcomer Orientation](presentations/base-newcomer-orientation.md) - introduces Base as a workspace control plane for multi-repo development. + introduces Base as a local operating contract for deterministic readiness and + handoff across independent repositories. ## Feature And Boundary Documents diff --git a/docs/base-bash-libs.md b/docs/base-bash-libs.md index 5e01d53b..f396fd8c 100644 --- a/docs/base-bash-libs.md +++ b/docs/base-bash-libs.md @@ -4,7 +4,8 @@ Base's reusable Bash libraries live in the standalone [`basefoundry/base-bash-libs`](https://github.com/basefoundry/base-bash-libs) repository. That repository lets scripts use Base's Bash logging, argument parsing, command execution, filesystem, Git, GitHub CLI, list, and string helper -conventions without adopting the full Base workspace control plane. +conventions without adopting Base's full local operating contract for +multi-repository readiness and handoff. This page documents the Base-side consumption and post-migration contract. Library APIs and standalone examples live in the `base-bash-libs` repository. diff --git a/docs/presentations/README.md b/docs/presentations/README.md index f4d661d8..cd444b21 100644 --- a/docs/presentations/README.md +++ b/docs/presentations/README.md @@ -8,7 +8,8 @@ of duplicating the reference text. ## Decks - [Base Newcomer Orientation](base-newcomer-orientation.md) introduces Base as - a workspace control plane for multi-repo development. + a local operating contract for deterministic readiness and handoff across + independent repositories. ## Source Of Truth diff --git a/docs/presentations/base-newcomer-orientation.md b/docs/presentations/base-newcomer-orientation.md index e38b744e..05344fc9 100644 --- a/docs/presentations/base-newcomer-orientation.md +++ b/docs/presentations/base-newcomer-orientation.md @@ -5,7 +5,8 @@ paginate: true # Base Newcomer Orientation -Workspace control plane for multi-repo development +Local operating contract for deterministic readiness and handoff +across independent repositories Canonical product details live in the README and focused docs. This deck is an orientation path for GitHub readers and live walkthroughs. @@ -24,17 +25,25 @@ A developer may need: - diagnostics that explain what is missing - shell activation without copying private dotfile logic into every repo -Base gives that workspace a common operating layer. +Base gives that workspace a common, inspectable operating contract. --- ## What Base Is -Base is a workspace control plane. +Base is a local operating contract for deterministic readiness and handoff +across independent Git repositories. -It discovers participating repositories, reads their Base contracts, and gives -the developer one command surface for setup, diagnostics, tests, demos, -activation, release support, and CI. +It makes the repo set understandable, locally ready, explicitly trusted, +onboardable, and transferable. Its durable loop is: + +```text +inventory -> prepare -> verify -> trust -> onboard -> hand off +``` + +The `basectl` command surface supports setup, diagnostics, tests, demos, +activation, release support, and CI while project repositories retain ownership +of their application behavior. It does not turn sibling repositories into a monorepo. diff --git a/docs/technical-overview.md b/docs/technical-overview.md index 1a1e19d0..3fc9123a 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -2,11 +2,20 @@ ## What It Is -**Base** is a macOS-first workspace control plane for developers who keep multiple -Git repositories checked out side by side under a shared directory (typically -`~/work/`). Rather than forcing unrelated codebases into a monorepo, Base provides -a single CLI — `basectl` — that orchestrates setup, diagnostics, project discovery, -shell activation, test execution, and releases across all of them. +**Base** is a macOS-first local operating contract for developers who work across +multiple independent Git repositories checked out side by side under a shared +directory (typically `~/work/`). Rather than forcing unrelated codebases into a +monorepo, Base makes the repo set understandable, locally ready, explicitly +trusted, onboardable, and transferable through one inspectable CLI contract. + +Its durable product loop is: + +```text +inventory -> prepare -> verify -> trust -> onboard -> hand off +``` + +The `basectl` CLI provides the execution surface for that loop, including setup, +diagnostics, project discovery, shell activation, test execution, and releases. > The repo you check out once per workspace so all other repos become easier to > set up, test, and run. @@ -18,13 +27,14 @@ bootstrap story, and the glue between projects — shared env vars, shared tools consistent shell environments — lives in fragile ad-hoc dotfiles or one-off scripts. Base formalizes that glue without absorbing project-specific logic. -It solves exactly three things: +It gives the repo set a common, inspectable operating contract: -1. **Umbrella setup and test** — one command to set up or test any project -2. **Shell environment management** — one managed, inspectable shell layer across - the whole workspace -3. **Shared Bash/Python libraries** — consistent CLI execution patterns for all - project scripts +1. **Inventory** — identify participating repositories and their declarations. +2. **Prepare** — reconcile the tools and environments those declarations need. +3. **Verify and trust** — report readiness and require explicit consent before + running project-owned commands. +4. **Onboard and hand off** — guide first use and preserve local evidence for the + next implementer without taking project behavior away from its owner. ## Target Workspace Shape @@ -84,7 +94,7 @@ Spawns a Bash runtime shell, sets `BASE_PROJECT`, applies the project runtime route, runs `activate.source` scripts declared in the manifest, and updates the prompt to `[project: branch] ~/path $`. Python projects activate their selected project venv. Shell-only setup/check/doctor work does not create one solely for -Base's control plane. Exit that shell to return to the original environment - +Base's runtime. Exit that shell to return to the original environment - no deactivation logic needed. **Design choice — no `cd`-triggered activation:** switching directories does not diff --git a/skills.md b/skills.md index d5568e3c..672f8378 100644 --- a/skills.md +++ b/skills.md @@ -98,8 +98,9 @@ public workflow docs. - For docs-only or configuration-only changes, `git diff --check` is usually enough unless the change affects CI validation or generated output. - Evaluate review feedback against Base's product boundaries before - implementing it. Base is the workspace control plane; project-specific - application behavior belongs in the owning project. + implementing it. Base is the local operating contract for deterministic + readiness and handoff; project-specific application behavior belongs in the + owning project. - If feedback suggests a larger design or product shift, stop and surface the decision instead of hiding it inside a small PR. From 2446e8212dd8d41fc8750e2ba1b4f906e6f42f89 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sat, 25 Jul 2026 19:40:55 -0700 Subject: [PATCH 2/4] Clarify Base positioning in FAQ --- FAQ.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/FAQ.md b/FAQ.md index 1d4af604..203a90a2 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,18 @@ # Base FAQ +## What Is Base? + +Base is a local operating contract for deterministic readiness and handoff +across independent Git repositories. Its durable loop is: + +```text +inventory -> prepare -> verify -> trust -> onboard -> hand off +``` + +Base makes a participating repo set understandable and locally ready while +projects keep ownership of their application behavior, services, and +project-specific setup. + ## First-Time Installation ### What should I run on a blank macOS machine? From a82c0614c9719a5940cc59dc638296cafa07bf7f Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sat, 25 Jul 2026 19:42:15 -0700 Subject: [PATCH 3/4] Update Copilot guidance contract --- tests/test_github_workflows.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_github_workflows.py b/tests/test_github_workflows.py index fa7105a5..fe3572dc 100644 --- a/tests/test_github_workflows.py +++ b/tests/test_github_workflows.py @@ -642,7 +642,7 @@ def test_copilot_repository_instructions_stay_anchored_to_base_guidance() -> Non assert "STANDARDS.md" in text assert ".ai-context/" in text assert "issue-backed" in text - assert "Base focused as the shared developer workspace control plane" in text + assert "Keep Base focused as the local operating contract for deterministic readiness" in text assert "Do not require GitHub Copilot" in text From f1a4666a6b78feca578008ed5d7515c52fc1598e Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sat, 25 Jul 2026 19:40:00 -0700 Subject: [PATCH 4/4] Standardize core document maintenance metadata --- docs/README.md | 2 ++ docs/architecture.md | 3 +++ docs/command-reference.md | 3 +++ docs/execution-model.md | 3 +++ docs/runtime-environment.md | 3 +++ docs/stability-tiers.md | 3 +++ docs/technical-overview.md | 3 +++ docs/tool-boundaries.md | 5 ++++- docs/why-base.md | 3 +++ 9 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index aa7021a8..84ce8e9c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -55,6 +55,8 @@ reference. The filename should answer "what is this about?" skill evidence. - [Command Quick Reference](command-reference.md) is the one-page lookup table for the current `basectl` command surface and important flags. +- [Output Formats](output-formats.md) defines the shared text and machine-readable + report format contract used by `basectl` inspection commands. - [Stability Tiers](stability-tiers.md) defines which command, JSON, finding ID, generated artifact, and helper surfaces are stable, experimental, or internal. - [Inspection JSON](inspection-json.md) defines the shared stable envelope and diff --git a/docs/architecture.md b/docs/architecture.md index 613b4a8c..8acb2f6d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,5 +1,8 @@ # Base Architecture +Status: maintained architecture reference +Last reviewed: 2026-07-25 + ## Overview Base is an opinionated macOS-primary implementation of a local operating diff --git a/docs/command-reference.md b/docs/command-reference.md index 87026e53..d310de65 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -1,5 +1,8 @@ # basectl Quick Reference +Status: maintained command reference +Last reviewed: 2026-07-25 + This page is a compact lookup table for the current `basectl` command surface. Run `basectl help ` or append `--help` to that path for the same leaf-specific usage. Run `basectl --help` for the journey-oriented command map. diff --git a/docs/execution-model.md b/docs/execution-model.md index 56f96848..8269ed60 100644 --- a/docs/execution-model.md +++ b/docs/execution-model.md @@ -1,5 +1,8 @@ # Base Execution Model +Status: maintained runtime reference +Last reviewed: 2026-07-25 + This document describes the current `basectl` execution contract. It is about what happens after a user invokes Base, not the future project-discovery or Python orchestration layers. diff --git a/docs/runtime-environment.md b/docs/runtime-environment.md index b88639ad..10d60b0e 100644 --- a/docs/runtime-environment.md +++ b/docs/runtime-environment.md @@ -1,5 +1,8 @@ # Base Runtime Environment +Status: maintained runtime contract +Last reviewed: 2026-07-25 + This page is the canonical reference for Base-managed shell environment variables. It covers variables that are part of the runtime contract, command dispatch, project activation, and user-facing configuration knobs. diff --git a/docs/stability-tiers.md b/docs/stability-tiers.md index d6d384bd..c65f3d32 100644 --- a/docs/stability-tiers.md +++ b/docs/stability-tiers.md @@ -1,5 +1,8 @@ # Base Stability Tiers +Status: maintained compatibility reference +Last reviewed: 2026-07-25 + Base exposes several surfaces that users and automation can depend on: CLI commands, JSON payloads, finding IDs, manifest schemas, generated files, and internal helper APIs. This page defines the stability vocabulary for those diff --git a/docs/technical-overview.md b/docs/technical-overview.md index 3fc9123a..c88ee264 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -1,5 +1,8 @@ # Base — Technical and Product Overview +Status: maintained product and technical reference +Last reviewed: 2026-07-25 + ## What It Is **Base** is a macOS-first local operating contract for developers who work across diff --git a/docs/tool-boundaries.md b/docs/tool-boundaries.md index dc7fbee1..c2aac9c6 100644 --- a/docs/tool-boundaries.md +++ b/docs/tool-boundaries.md @@ -1,11 +1,14 @@ # Base Ecosystem Boundaries +Status: maintained ecosystem boundary reference +Last reviewed: 2026-07-25 + This document captures how Base should relate to other popular developer tools. Its purpose is not to compete with everything in the ecosystem. Its purpose is to help Base stay sharp about what it owns, what it can orchestrate, and what it should leave alone. -Evidence checked: 2026-07-14 +Evidence checked: 2026-07-25 When we evaluate another tool, we record five separate decisions: diff --git a/docs/why-base.md b/docs/why-base.md index 4514b394..542aab01 100644 --- a/docs/why-base.md +++ b/docs/why-base.md @@ -1,5 +1,8 @@ # Why Base +Status: maintained product entry point +Last reviewed: 2026-07-25 + Base is a local operating contract for developers and platform engineers whose work spans multiple independent Git repositories. It makes a participating repo set understandable and locally ready without forcing a monorepo or taking