release(beta): add target-repo-first bootstrap path

Author: xronocode

CHANGELOG.md

@@ -4,6 +4,20 @@ This changelog tracks the clean VIBE / vibestart root surface.
 
 Legacy vibestart v3 history remains preserved in `legacy/vibestart-v3/CHANGELOG.v3.md`.
 
+## 0.1.0-beta.2 - 2026-04-03
+
+Target-repo-first bootstrap increment.
+
+### Added
+
+- `bootstrap-from-git.sh` wrapper for fetching vibestart from git and bootstrapping the current target repository in place
+- `tests/test_bootstrap_from_git.py`
+- canonical release story updated around the target-repo-first acquisition model
+
+### Changed
+
+- the intended prerelease adoption path is now target-repo-first instead of requiring a separate long-lived local framework checkout as the main workflow
+
 ## 0.1.0-beta.1 - 2026-04-03
 
 First public core-first beta candidate for the new VIBE / vibestart root surface.
@@ -13,6 +27,7 @@ First public core-first beta candidate for the new VIBE / vibestart root surface
 - clean public root surface for VIBE and vibestart
 - quarantined legacy and internal boundaries
 - active `vibestart` bootstrap entrypoint
+- target-repo-first `bootstrap-from-git.sh` acquisition wrapper
 - explicit `--core` and `--deep` profile selection
 - deterministic first-run contract
 - VIBE-native beta readiness note

README.md

@@ -8,8 +8,10 @@ It is an agent-agnostic methodology for intent-driven engineering, designed to r
 
 The clean methodology surface:
 - `CHANGELOG.md`
+- `bootstrap-from-git.sh`
 - `vibestart`
 - `tests/test_vibestart.py`
+- `tests/test_bootstrap_from_git.py`
 - `vibe.toml`
 - `docs/requirements.xml`
 - `docs/development-plan.xml`
@@ -45,17 +47,20 @@ It is intended to install and adapt one VIBE methodology through two product pro
 At the methodology level, `VIBE` remains one standard.
 `core` and `deep` are product profiles, not separate frameworks.
 
-Current active entrypoint:
+Current active entrypoints:
 
 - `./vibestart --core --target /path/to/project`
 - `./vibestart --deep --target /path/to/project`
+- from inside a target repository:
+  `bash <(curl -fsSL <bootstrap-from-git.sh-url>) --repo <git-url> --ref v0.1.0-beta.2 --core --target .`
 
 Current beta posture:
 
 - `core` is the recommended beta path for one-project adoption
 - `deep` remains explicit and supported, but its richer adapters are still draft-level
 - `docs/vibe/operator-guide.md` describes the normal first project loop after bootstrap
-- prerelease git path starts at `v0.1.0-beta.1`
+- current prerelease git path is `v0.1.0-beta.2`
+- intended adoption UX is target-repo-first: fetch vibestart from git into the current repository context, then write the VIBE surface into that repository
 
 ## Repository structure
 

bootstrap-from-git.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Bootstrap VIBE into the current or target repository by fetching vibestart from git.
+
+Usage:
+  bootstrap-from-git.sh --repo <git-url-or-path> --ref <tag-or-branch> (--core | --deep) [--target <path>] [--force] [--dry-run]
+
+Options:
+  --repo    Git URL or local git repository path containing vibestart.
+  --ref     Git tag or branch to fetch. Defaults to v0.1.0-beta.1.
+  --core    Bootstrap the core profile.
+  --deep    Bootstrap the deep profile.
+  --target  Target repository path. Defaults to the current directory.
+  --force   Allow overwrite of existing VIBE surfaces in the target.
+  --dry-run Show what would be installed without writing files.
+  --keep-clone  Keep the temporary fetched vibestart checkout for inspection.
+  -h, --help    Show this help message.
+
+Environment:
+  VIBESTART_REPO_URL may be used instead of --repo.
+EOF
+}
+
+die() {
+  printf '%s\n' "$1" >&2
+  exit 1
+}
+
+repo_url="${VIBESTART_REPO_URL:-}"
+ref="v0.1.0-beta.1"
+target="."
+profile=""
+force=0
+dry_run=0
+keep_clone=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      [[ $# -ge 2 ]] || die "--repo requires a value."
+      repo_url="$2"
+      shift 2
+      ;;
+    --ref)
+      [[ $# -ge 2 ]] || die "--ref requires a value."
+      ref="$2"
+      shift 2
+      ;;
+    --target)
+      [[ $# -ge 2 ]] || die "--target requires a value."
+      target="$2"
+      shift 2
+      ;;
+    --core)
+      profile="core"
+      shift
+      ;;
+    --deep)
+      profile="deep"
+      shift
+      ;;
+    --force)
+      force=1
+      shift
+      ;;
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --keep-clone)
+      keep_clone=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "Unknown argument: $1"
+      ;;
+  esac
+done
+
+[[ -n "$repo_url" ]] || die "A git source is required. Use --repo <git-url-or-path> or set VIBESTART_REPO_URL."
+[[ -n "$profile" ]] || die "Explicit profile selection is required. Use --core or --deep."
+
+tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/vibestart-fetch.XXXXXX")"
+clone_dir="$tmpdir/repo"
+
+cleanup() {
+  if [[ "$keep_clone" -eq 0 ]]; then
+    rm -rf "$tmpdir"
+  fi
+}
+trap cleanup EXIT
+
+printf 'Fetching vibestart from git source: %s\n' "$repo_url"
+printf 'Using ref: %s\n' "$ref"
+
+git clone --depth 1 --branch "$ref" "$repo_url" "$clone_dir" >/dev/null 2>&1 \
+  || die "Failed to fetch vibestart from git source '$repo_url' at ref '$ref'."
+
+cmd=(python3 "$clone_dir/vibestart" "--$profile" "--target" "$target")
+if [[ "$force" -eq 1 ]]; then
+  cmd+=("--force")
+fi
+if [[ "$dry_run" -eq 1 ]]; then
+  cmd+=("--dry-run")
+fi
+
+"${cmd[@]}"

docs/decisions.xml

@@ -738,6 +738,47 @@
         <notes>Also constrains beta messaging to keep deep explicit but not overclaimed while the richer adapter layer is still future work.</notes>
       </review>
     </D-017>
+
+    <D-018 DATE="2026-04-03" STATUS="approved">
+      <summary>Make target-repo-first git acquisition the supported prerelease bootstrap path instead of requiring a separate long-lived framework checkout as the main user workflow.</summary>
+      <context>
+        <problem>The working root bootstrap entrypoint already exists, but the main user story would still force adopters to keep a separate framework checkout around if there were no supported git acquisition wrapper.</problem>
+        <constraints>The acquisition path must keep git source, ref, profile, and target path explicit, and it must remain a thin wrapper over the existing deterministic bootstrap contract rather than becoming a second methodology surface.</constraints>
+      </context>
+      <options>
+        <option-1 name="Keep separate local checkout as the main path">
+          <description>Require users to clone or install the framework repo first, then invoke vibestart from that checkout into a target repository.</description>
+          <pros>Minimal extra implementation work.</pros>
+          <cons>Adds friction, weakens the target-repo-first mental model, and makes adoption feel tool-centric instead of project-centric.</cons>
+          <score>4/10</score>
+        </option-1>
+        <option-2 name="Support target-repo-first git acquisition">
+          <description>Let users enter the target repository, fetch vibestart from git, and bootstrap in place through a thin acquisition wrapper.</description>
+          <pros>Matches the intended adoption UX and keeps the target repository as the active working context.</pros>
+          <cons>Introduces one more entrypoint surface that must stay aligned with the main bootstrap contract.</cons>
+          <score>9/10</score>
+        </option-2>
+      </options>
+      <decision>
+        <chosen>Support target-repo-first git acquisition</chosen>
+        <rationale>The main prerelease bootstrap path should be project-centric. A thin wrapper around the existing bootstrap command is enough to support that path without splitting the product semantics.</rationale>
+      </decision>
+      <impacts>
+        <module>M-010</module>
+      </impacts>
+      <consequences>
+        <positive>Users can bootstrap directly from inside a target repository using a git source and ref.</positive>
+        <negative>Maintainers must keep the acquisition wrapper aligned with the main bootstrap contract and release docs.</negative>
+      </consequences>
+      <links>
+        <ref doc="development-plan.xml" id="M-010" />
+      </links>
+      <review>
+        <date>2026-04-03</date>
+        <outcome>still-valid</outcome>
+        <notes>Also keeps the acquisition story tied to explicit prerelease refs instead of vague latest-from-main behavior.</notes>
+      </review>
+    </D-018>
   </Decisions>
 
   <Categories>
@@ -749,10 +790,10 @@
   </Categories>
 
   <Statistics>
-    <total>17</total>
+    <total>18</total>
     <by-status>
       <proposed>0</proposed>
-      <approved>17</approved>
+      <approved>18</approved>
       <rejected>0</rejected>
       <superseded>0</superseded>
     </by-status>

docs/development-plan.xml

@@ -14,6 +14,7 @@
     <risk-8>Copying repository-specific framework truth into a bootstrapped project instead of generating project-generic starting surfaces would install the wrong semantic center.</risk-8>
     <risk-9>Claiming beta usability without VIBE-native operator guidance would push adopters back toward quarantined legacy GRACE playbooks.</risk-9>
     <risk-10>Leaving bootstrap scaffolds too skeletal would keep the product path documentary instead of making it usable for the first real project loop.</risk-10>
+    <risk-11>Requiring a separate long-lived framework checkout as the main adoption path would add friction and weaken the target-repo-first bootstrap model.</risk-11>
   </ArchitectureNotes>
 
   <Modules>
@@ -328,6 +329,41 @@
         <note-4>The git-visible prerelease path and human-readable changelog must stay aligned with the current beta scope.</note-4>
       </notes>
     </M-009>
+
+    <M-010 NAME="GitBootstrapAcquisition" TYPE="ENTRY_POINT" LAYER="2" ORDER="5" STATUS="done">
+      <contract>
+        <purpose>Provide a target-repo-first wrapper that fetches vibestart from git and runs bootstrap against the current or specified repository without requiring a separate long-lived local framework checkout as the main user path.</purpose>
+        <inputs>
+          <param name="git-source" type="repo-url-or-path" />
+          <param name="bootstrap-entrypoint" type="M-008" />
+        </inputs>
+        <outputs>
+          <param name="git-bootstrap-wrapper" type="target-repo-first-bootstrap-entry" />
+        </outputs>
+        <errors>
+          <error code="ERR_GIT_SOURCE_REQUIRED" />
+          <error code="ERR_GIT_FETCH_FAILED" />
+          <error code="ERR_TARGET_REPO_CONTEXT_DRIFT" />
+        </errors>
+      </contract>
+      <interface>
+        <export-gitBootstrap PURPOSE="Expose a target-repo-first bootstrap path that acquires vibestart from git and applies it to the active repository." />
+      </interface>
+      <depends>M-008, M-009</depends>
+      <target>
+        <source>bootstrap-from-git.sh</source>
+        <tests>tests/test_bootstrap_from_git.py</tests>
+      </target>
+      <observability>
+        <log-prefix>[VIBE][GitBootstrapAcquisition]</log-prefix>
+        <critical-block>BLOCK_FETCH_AND_BOOTSTRAP</critical-block>
+      </observability>
+      <verification-ref>V-M-010</verification-ref>
+      <notes>
+        <note-1>The intended adoption UX is target-repo-first: enter the new repository, fetch vibestart from git, and bootstrap in place.</note-1>
+        <note-2>The wrapper may remain thin, but it must keep git ref selection, source identity, and target path explicit.</note-2>
+      </notes>
+    </M-010>
   </Modules>
 
   <DataFlow>
@@ -394,13 +430,18 @@
       <goal>Make the core path usable for one real project through explicit beta scope, operator guidance, and stronger generated starting surfaces.</goal>
       <step-1 module="M-009" status="done" verification="V-M-009">Define the beta boundary, publish the operator loop, and confirm that the generated scaffolds support the first real project slice.</step-1>
     </Phase-6>
+
+    <Phase-7 name="Git Bootstrap Acquisition" status="done">
+      <goal>Make target-repo-first bootstrap practical by fetching vibestart from git and applying it directly to the active repository.</goal>
+      <step-1 module="M-010" status="done" verification="V-M-010">Implement the git acquisition wrapper and verify that a target repository can bootstrap from a git source without a separate long-lived framework checkout.</step-1>
+    </Phase-7>
   </ImplementationOrder>
 
   <ExecutionPolicy>
     <default-profile>guided-single</default-profile>
     <experimental-surfaces>auto, multi, calibrate-apply</experimental-surfaces>
     <experimental-guard>Experimental surfaces are allowed but non-normative until deterministic guards and stronger verification are in place.</experimental-guard>
-    <controller-owns>README.md, CHANGELOG.md, vibestart, tests/test_vibestart.py, docs/requirements.xml, docs/development-plan.xml, docs/verification-plan.xml, docs/knowledge-graph.xml, docs/decisions.xml, docs/technology.xml, vibe.toml, docs/vibe/*.toml, docs/vibe/beta-readiness.md, docs/vibe/operator-guide.md, docs/vibe/release-path.md</controller-owns>
+    <controller-owns>README.md, CHANGELOG.md, bootstrap-from-git.sh, vibestart, tests/test_vibestart.py, tests/test_bootstrap_from_git.py, docs/requirements.xml, docs/development-plan.xml, docs/verification-plan.xml, docs/knowledge-graph.xml, docs/decisions.xml, docs/technology.xml, vibe.toml, docs/vibe/*.toml, docs/vibe/beta-readiness.md, docs/vibe/operator-guide.md, docs/vibe/release-path.md</controller-owns>
     <worker-owns>Scoped implementation surfaces inside the approved write scope; no worker owns the canonical shared artifacts globally.</worker-owns>
   </ExecutionPolicy>