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/3] 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/3] 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/3] 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