@event4u/agent-config 2.15.0 → 2.17.0

package/scripts/check_role_doc_links.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Verify every skill link in role-based docs resolves to a real file.
+
+Part of step-12 Phase 2. Runs in `task ci` to catch link rot when a
+skill is renamed or removed but the role docs still reference it.
+
+Scans `docs/getting-started-by-role.md` and `docs/getting-started-laravel.md`
+for markdown links of the form `../.agent-src/skills/<name>/SKILL.md`
+(relative to docs/) and checks that the target file exists on disk.
+
+Exit codes:
+  0 — every link resolves
+  1 — at least one broken link; prints the offending file:line:url tuples
+  2 — usage error (one of the role doc files missing)
+
+Usage:
+  python3 scripts/check_role_doc_links.py
+  python3 scripts/check_role_doc_links.py --quiet
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT / "docs"
+
+# (display-path, on-disk path, link-anchor) — anchor is the relative
+# prefix that identifies a skill link from inside docs/.
+ROLE_DOCS = [
+    DOCS_DIR / "getting-started-by-role.md",
+    DOCS_DIR / "getting-started-laravel.md",
+]
+
+# Markdown link: [label](path). We only check the (path) part. The
+# regex tolerates trailing #anchor fragments and ignores absolute URLs.
+LINK_RE = re.compile(r"\]\(([^)\s]+)\)")
+
+# Anchors we know how to resolve. Each tuple is (prefix, base_dir).
+ANCHORS: list[tuple[str, Path]] = [
+    ("../.agent-src/skills/", ROOT / ".agent-src" / "skills"),
+    ("../.agent-src/commands/", ROOT / ".agent-src" / "commands"),
+    ("../.agent-src/rules/", ROOT / ".agent-src" / "rules"),
+    ("../agents/", ROOT / "agents"),
+    ("contracts/", DOCS_DIR / "contracts"),
+    ("guidelines/", DOCS_DIR / "guidelines"),
+]
+
+
+def resolve(url: str, doc_path: Path) -> Path | None:
+    """Return the on-disk target path for a relative link, or None if external."""
+    if url.startswith(("http://", "https://", "mailto:")):
+        return None
+    bare = url.split("#", 1)[0]
+    if not bare:
+        return None
+    # Relative to the doc's own directory.
+    target = (doc_path.parent / bare).resolve()
+    return target
+
+
+def scan(doc_path: Path) -> list[tuple[int, str]]:
+    """Return list of (line_no, url) tuples for every non-external link."""
+    if not doc_path.is_file():
+        print(f"error: missing role doc: {doc_path}", file=sys.stderr)
+        sys.exit(2)
+    links: list[tuple[int, str]] = []
+    for i, line in enumerate(doc_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            url = m.group(1)
+            if url.startswith(("http://", "https://", "mailto:")):
+                continue
+            links.append((i, url))
+    return links
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--quiet", action="store_true", help="Suppress success summary.")
+    args = p.parse_args()
+
+    failures: list[tuple[Path, int, str]] = []
+    checked = 0
+
+    for doc in ROLE_DOCS:
+        for line_no, url in scan(doc):
+            target = resolve(url, doc)
+            if target is None:
+                continue
+            checked += 1
+            if not target.exists():
+                failures.append((doc, line_no, url))
+
+    if failures:
+        print("Broken links in role docs:", file=sys.stderr)
+        for doc, line_no, url in failures:
+            rel = doc.relative_to(ROOT)
+            print(f"  {rel}:{line_no}  -> {url}", file=sys.stderr)
+        print(f"\n{len(failures)} broken / {checked} checked", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(f"check_role_doc_links: {checked} links OK across {len(ROLE_DOCS)} files")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/compress.py

@@ -77,6 +77,11 @@ def _tool_active(tool_id: str) -> bool:
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
+# Directories (relative to SOURCE_DIR) whose .md content is data, not prose,
+# and must be copied verbatim. Ghostwriter fixtures carry voice_samples that
+# would be destroyed by caveman compression.
+COPY_AS_IS_DIRS = frozenset({"ghostwriter"})
+
 
 def _read_augment_rules_use_symlinks() -> bool:
     """Read augment.rules_use_symlinks from .agent-settings.yml.
@@ -235,6 +240,12 @@ def should_compress(filepath: Path) -> bool:
         return False
     if filepath.name in COPY_AS_IS:
         return False
+    try:
+        rel_parts = filepath.relative_to(SOURCE_DIR).parts
+    except ValueError:
+        rel_parts = filepath.parts
+    if rel_parts and rel_parts[0] in COPY_AS_IS_DIRS:
+        return False
     return True
 
 

package/scripts/ghostwriter_fixture_allowlist.txt

@@ -0,0 +1,16 @@
+# Ghostwriter fixture allowlist
+#
+# One file stem per line (without the .md extension).
+# Every file under .agent-src.uncompressed/ghostwriter/ whose stem is
+# NOT on this list will fail `task lint-ghostwriter-source`.
+#
+# Adding a new fixture requires:
+#   1. Adding the stem here.
+#   2. Setting `fictional: true` in the file's frontmatter.
+#   3. Reviewer sign-off on the allowlist change.
+#
+# README.md is exempt (the lint skips it).
+#
+# See docs/contracts/ghostwriter-schema.md § Lint enforcement.
+
+fictional-fixture-v1

package/scripts/install

@@ -44,6 +44,12 @@
 #                     for child subprocesses. All bridge content is bundled
 #                     in the package, so install itself is already offline-safe;
 #                     this flag is the explicit air-gap / CI guarantee.
+#   --minimal         Bootstrap only `.agent-settings.yml`, `agents/.gitkeep`,
+#                     and the `./agent-config` wrapper. No tool payload, no
+#                     AGENTS.md, no symlinks. Refuses to install inside an
+#                     existing agent-config project (nested-install guard).
+#                     See docs/installation.md → "Minimal init".
+#   --settings-only   Alias for --minimal.
 #   --help, -h        Show this help
 #
 # Examples:
@@ -75,12 +81,13 @@ GLOBAL=false
 SCOPE=""
 CUSTOM_PATH=""
 OFFLINE=false
+MINIMAL=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,48p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,54p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -157,6 +164,8 @@ while [[ $# -gt 0 ]]; do
         --custom-path)   CUSTOM_PATH="$2"; shift 2 ;;
         --custom-path=*) CUSTOM_PATH="${1#*=}"; shift ;;
         --offline)       OFFLINE=true; shift ;;
+        --minimal|--settings-only)
+                         MINIMAL=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -202,7 +211,7 @@ prompt_tools() {
     echo "  ✅  Selected: $TOOLS"
 }
 
-if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && [[ -t 0 && -t 1 ]]; then
+if ! $MINIMAL && ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && [[ -t 0 && -t 1 ]]; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
@@ -280,6 +289,7 @@ run_sync() {
     $DRY_RUN && args+=(--dry-run)
     $VERBOSE && args+=(--verbose)
     $QUIET   && args+=(--quiet)
+    $MINIMAL && args+=(--minimal)
     args+=(--tools="$TOOLS")
     bash "$INSTALL_SH" "${args[@]}"
 }
@@ -305,12 +315,39 @@ run_bridges() {
     [[ -n "$SCOPE" ]] && args+=(--scope="$SCOPE")
     [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
     $OFFLINE && args+=(--offline)
+    $MINIMAL && args+=(--minimal)
     args+=(--tools="$TOOLS")
     "$python_bin" "$INSTALL_PY" "${args[@]}"
 }
 
 RC=0
 
+# Minimal init runs the bridge stage *first* so its nested-install guard
+# (Step 7 Phase 2) fires before any wrapper / file is written. The
+# payload sync stage is then a no-op in minimal mode (install.sh
+# short-circuits) but is still invoked so it can install the
+# `./agent-config` wrapper on a confirmed-clean target.
+if $MINIMAL; then
+    if ! $SKIP_BRIDGES; then
+        if [[ ! -f "$INSTALL_PY" ]]; then
+            err "Missing $INSTALL_PY"
+            exit 1
+        fi
+        run_bridges || RC=$?
+    fi
+    if [[ $RC -ne 0 ]]; then
+        exit $RC
+    fi
+    if ! $SKIP_SYNC; then
+        if [[ ! -f "$INSTALL_SH" ]]; then
+            err "Missing $INSTALL_SH"
+            exit 1
+        fi
+        run_sync || RC=$?
+    fi
+    exit $RC
+fi
+
 if ! $SKIP_SYNC; then
     if [[ ! -f "$INSTALL_SH" ]]; then
         err "Missing $INSTALL_SH"

package/scripts/install.py

@@ -3223,6 +3223,31 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
             "explicit guarantee for air-gapped / CI runs."
         ),
     )
+    parser.add_argument(
+        "--minimal",
+        "--settings-only",
+        dest="minimal",
+        action="store_true",
+        help=(
+            "bootstrap only the project-local override layer: writes "
+            "agents/.gitkeep and a .agent-settings.yml stub. No tool "
+            "payload, no AGENTS.md, no symlinks. Refuses to install "
+            "inside an existing agent-config project (nested-install "
+            "guard). See docs/installation.md → Minimal init."
+        ),
+    )
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        help=(
+            "after the install completes, run a short prompt to capture "
+            "user-type / stack / verbosity and write `.agent-config.local.json` "
+            "(forward-compatible stub for step-9 user-types axis — runtime "
+            "skill filtering activates once that axis ships). TTY-only; "
+            "no-op without an interactive stdin. See "
+            "docs/contracts/universal-skills.md for the always-loaded set."
+        ),
+    )
     opts = parser.parse_args(argv)
     opts.tools = _merge_tools_aliases(opts.tools, opts.ai)
     if opts.scope == "global" and opts.custom_path:
@@ -3282,6 +3307,262 @@ def _is_tool_enabled(tools: set[str], tool_id: str) -> bool:
     return tool_id in tools
 
 
+# --- Minimal init (Step 7 Phase 2) ---
+
+
+def _minimal_templates_root() -> Path:
+    """Resolve the bundled ``templates/minimal/`` directory.
+
+    Walks up from this file looking for ``templates/minimal/``; this
+    works both in development mode (running the source tree) and from
+    an ``npm install -g`` install (the script lives under the package
+    root regardless).
+    """
+    for ancestor in (Path(__file__).resolve(), *Path(__file__).resolve().parents):
+        candidate = ancestor / "templates" / "minimal"
+        if candidate.is_dir():
+            return candidate
+    fail("Could not locate templates/minimal/ — package install is corrupt.")
+    return Path()  # unreachable
+
+
+#: Relative path of the install-mode marker file written by both the
+#: minimal short-circuit and the full install path (Step 8 A5). Read by
+#: ``doctor --context`` (and any future tooling) instead of inferring
+#: install state from filesystem heuristics like ``AGENTS.md`` presence.
+INSTALL_MODE_MARKER_REL = "agents/.agent-state/install-mode.txt"
+
+
+def _write_install_mode_marker(project_root: Path, mode: str) -> None:
+    """Write ``agents/.agent-state/install-mode.txt`` = ``mode\\n``.
+
+    Idempotent: overwrites unconditionally so re-installs flip the
+    state correctly (e.g. minimal → full upgrade). Failure to write
+    is non-fatal — install proceeds and ``doctor --context`` falls
+    back to the filesystem heuristic. ``mode`` must be ``minimal``
+    or ``full``.
+    """
+    if mode not in ("minimal", "full"):
+        return
+    marker = project_root / INSTALL_MODE_MARKER_REL
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(f"{mode}\n", encoding="utf-8")
+    except OSError:
+        # Marker is advisory; install must not abort because the
+        # state dir is unwritable (e.g. read-only mount in CI).
+        pass
+
+
+def install_minimal(target_root: Path, force: bool) -> int:
+    """Bootstrap the project-local override layer only (D2-compliant).
+
+    Writes:
+
+    * ``agents/.gitkeep`` so the folder is committable.
+    * ``.agent-settings.yml`` stub (cost_profile=balanced, version pin
+      commented out per D4).
+
+    Refuses (exit 1) when ``target_root`` is **inside** an existing
+    agent-config project (Phase-1 anchor walk above the target). The
+    in-target case is allowed and treated as idempotent — re-running
+    ``--minimal`` in a folder that already has ``.agent-settings.yml``
+    does nothing unless ``--force`` is passed.
+
+    Does **not** touch ``.gitignore`` (D2 — user owns the ignore file).
+    The ``./agent-config`` wrapper is installed by ``scripts/install.sh``
+    in its own minimal short-circuit.
+    """
+    try:
+        from scripts._lib.agent_settings import find_project_root_with_anchor  # noqa: PLC0415
+    except ImportError:  # pragma: no cover — alt sys.path layout
+        from _lib.agent_settings import find_project_root_with_anchor  # type: ignore[no-redef]  # noqa: PLC0415
+
+    target_root = target_root.resolve()
+    target_root.mkdir(parents=True, exist_ok=True)
+
+    # Nested-install guard: walk up from the *parent* of target_root.
+    # An anchor at target_root itself is allowed (re-running --minimal
+    # in the same project is idempotent); only a root *above* target
+    # blocks the install.
+    parent = target_root.parent
+    if parent != target_root:  # not filesystem root
+        existing = find_project_root_with_anchor(parent)
+        if existing is not None and existing[0] != target_root:
+            root, anchor = existing
+            fail(
+                "Refusing to nest an agent-config layer inside an existing "
+                f"project (anchor: {anchor}). Existing root: {root}. "
+                "Remove the parent layer first or run `--minimal` outside it."
+            )
+            return 1  # unreachable; fail() exits
+
+    templates = _minimal_templates_root()
+    settings_src = templates / SETTINGS_FILE
+    gitkeep_src = templates / "agents-gitkeep"
+
+    if not settings_src.is_file() or not gitkeep_src.is_file():
+        fail(f"Bundled minimal templates missing under {templates}")
+
+    info(f"Minimal init → {target_root}")
+
+    # 1. agents/.gitkeep
+    agents_dir = target_root / "agents"
+    agents_dir.mkdir(exist_ok=True)
+    gitkeep_dst = agents_dir / ".gitkeep"
+    if gitkeep_dst.exists() and not force:
+        skip(f"agents/.gitkeep already exists (use --force to overwrite)")
+    else:
+        gitkeep_dst.write_text(gitkeep_src.read_text(encoding="utf-8"), encoding="utf-8")
+        success("Wrote agents/.gitkeep")
+
+    # 2. .agent-settings.yml stub
+    settings_dst = target_root / SETTINGS_FILE
+    if settings_dst.exists() and not force:
+        skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
+    else:
+        settings_dst.write_text(settings_src.read_text(encoding="utf-8"), encoding="utf-8")
+        success(f"Wrote {SETTINGS_FILE}")
+
+    # 3. install-mode marker (Step 8 A5) — authoritative state for
+    # doctor --context and future install-aware tooling. Written even
+    # on idempotent re-runs so the marker is repaired if removed.
+    _write_install_mode_marker(target_root, "minimal")
+
+    # Stderr upgrade hint (Step 8 A5) — minimal installs are intentionally
+    # stripped; surface the upgrade path on stderr so it appears in
+    # human terminals without polluting stdout-parsed output. Suppressed
+    # under --quiet to honor scripted-install contracts.
+    if not QUIET:
+        print(
+            "ℹ️   Minimal install — run `agent-config install --force` "
+            "to add AGENTS.md, bridges, and tool integrations.",
+            file=sys.stderr,
+        )
+
+    if not QUIET:
+        print()
+        info("Next steps:")
+        info("  • Ensure `agent-config` is on $PATH: npm install -g @event4u/agent-config")
+        info("  • Add `.agent-settings.yml` and `agents/` to git (or to .gitignore — your call).")
+        info("  • Run `agent-config doctor` to verify the layer is picked up.")
+    return 0
+
+
+# --- Interactive init (step-12 Phase 3, forward-compatible stub) ---
+
+_INTERACTIVE_USER_TYPES: tuple[tuple[str, str], ...] = (
+    ("creator", "Content / writing / publishing"),
+    ("founder", "Early-stage company building"),
+    ("consultant", "Advisory / strategy / discovery"),
+    ("gtm", "Sales / marketing / revenue ops"),
+    ("finance", "Finance / FP&A / unit economics"),
+    ("ops", "Operations / incident / compliance"),
+    ("developer", "Engineering / code-heavy work"),
+)
+
+_INTERACTIVE_STACKS: tuple[tuple[str, str], ...] = (
+    ("none", "No code project / pure content"),
+    ("laravel", "PHP / Laravel"),
+    ("nextjs", "TypeScript / Next.js / React"),
+    ("python", "Python / FastAPI / Django"),
+    ("symfony", "PHP / Symfony"),
+    ("generic", "Other / mixed stack"),
+)
+
+_INTERACTIVE_VERBOSITIES: tuple[tuple[str, str], ...] = (
+    ("quiet", "Caveman / minimal output"),
+    ("normal", "Default verbosity"),
+    ("verbose", "Full intent announcements + play-by-play"),
+)
+
+_LOCAL_CONFIG_FILE = ".agent-config.local.json"
+
+
+def _interactive_prompt_choice(label: str, options: tuple[tuple[str, str], ...]) -> str:
+    """Render a numbered list and return the chosen id. Defaults to option 1 on empty input."""
+    print()
+    print(f"  {label}")
+    for idx, (key, blurb) in enumerate(options, start=1):
+        print(f"    {idx}. {key}  — {blurb}")
+    print()
+    while True:
+        try:
+            raw = input(f"  Choice [1-{len(options)}, default 1]: ").strip()
+        except EOFError:
+            return options[0][0]
+        if not raw:
+            return options[0][0]
+        if raw.isdigit():
+            i = int(raw)
+            if 1 <= i <= len(options):
+                return options[i - 1][0]
+        # Allow typing the slug directly.
+        for key, _ in options:
+            if raw.lower() == key:
+                return key
+        print(f"  ⚠️  Pick a number 1-{len(options)} or one of: {', '.join(k for k, _ in options)}.")
+
+
+def run_interactive_init(project_root: Path, force: bool) -> int:
+    """Write ``.agent-config.local.json`` based on three TTY prompts.
+
+    Forward-compatible stub for [`step-9-user-types-axis`](../agents/roadmaps/step-9-user-types-axis.md):
+    runtime skill filtering activates once that axis ships its
+    ``user-types/`` directory and ``--user-type`` flag. Until then,
+    this file is metadata-only — read by ``doctor --context`` and the
+    upcoming ``agent-config skills`` listing command.
+
+    Universal-skills allowlist (see
+    ``docs/contracts/universal-skills.md``) loads regardless of the
+    captured ``user_type`` — the contract guarantees these 15 skills
+    are never filtered out.
+
+    Returns 0 on success, 1 on collision without ``--force``. No-op
+    (returns 0) when stdin is not a TTY.
+    """
+    if not sys.stdin.isatty():
+        warn(
+            "--interactive requested but stdin is not a TTY; skipping the "
+            f"prompt. Re-run interactively or hand-edit {_LOCAL_CONFIG_FILE}."
+        )
+        return 0
+
+    target = project_root / _LOCAL_CONFIG_FILE
+    if target.exists() and not force:
+        warn(
+            f"{_LOCAL_CONFIG_FILE} already exists; re-run with --force to "
+            "overwrite. Skipping interactive init."
+        )
+        return 0
+
+    print()
+    info("Interactive init — captures user-type / stack / verbosity")
+    info("(forward-compatible stub; runtime filtering activates with step-9)")
+
+    user_type = _interactive_prompt_choice("Primary user type:", _INTERACTIVE_USER_TYPES)
+    stack = _interactive_prompt_choice("Project stack:", _INTERACTIVE_STACKS)
+    verbosity = _interactive_prompt_choice("Verbosity profile:", _INTERACTIVE_VERBOSITIES)
+
+    payload: dict[str, Any] = {
+        "$schema": "https://github.com/event4u-app/agent-config/scripts/schemas/local-config.schema.json",
+        "version": 1,
+        "user_type": user_type,
+        "stack": stack,
+        "verbosity": verbosity,
+        "universal_skills_contract": "docs/contracts/universal-skills.md",
+    }
+
+    try:
+        target.write_text(json.dumps(payload, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    except OSError as exc:
+        warn(f"Could not write {target}: {exc}")
+        return 1
+
+    success(f"Wrote {target.relative_to(project_root)} ({user_type} / {stack} / {verbosity})")
+    return 0
+
+
 # --- Main ---
 
 def main(argv: list[str]) -> int:
@@ -3302,6 +3583,17 @@ def main(argv: list[str]) -> int:
     if opts.profile not in SUPPORTED_PROFILES:
         fail(f"Unsupported profile: {opts.profile}. Supported: {', '.join(SUPPORTED_PROFILES)}")
 
+    # Minimal-init short-circuit (Step 7 Phase 2): bypass scope
+    # detection, conflict policy, and the full bridge install. Writes
+    # only the project-local override layer (agents/.gitkeep +
+    # .agent-settings.yml stub). The bash wrapper handles the
+    # `./agent-config` script; everything else is intentionally absent.
+    if opts.minimal:
+        target_root = Path(
+            opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+        ).resolve()
+        return install_minimal(target_root, opts.force)
+
     # Multi-signal scope detection (Phase 1.3) + scope resolution
     # (Phase 1.4). Order of precedence (highest first):
     #   1. --scope=<x>  — explicit user override (CI-friendly; auto = honor detection)
@@ -3337,7 +3629,13 @@ def main(argv: list[str]) -> int:
 
         project_root = custom_path or Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
         is_first_run = not (project_root / SETTINGS_FILE).exists()
-        return _main_project_install(opts, project_root, parsed_tools, is_first_run)
+        rc = _main_project_install(opts, project_root, parsed_tools, is_first_run)
+        # Interactive post-install prompt (step-12 Phase 3, forward-compatible
+        # stub). Runs only after a successful install so the local config
+        # never ships ahead of the bridge files it parameterizes.
+        if rc == 0 and getattr(opts, "interactive", False):
+            run_interactive_init(project_root, opts.force)
+        return rc
     except ConflictAbort as exc:
         warn(exc.message)
         return 1
@@ -3376,6 +3674,11 @@ def _main_project_install(
 
     ensure_agent_settings(project_root, package_root, opts.profile, opts.force)
 
+    # Install-mode marker (Step 8 A5) — full path flips any prior
+    # minimal marker to "full" so doctor --context reflects the
+    # upgraded state. Idempotent on re-runs of the same scope.
+    _write_install_mode_marker(project_root, "full")
+
     tools = parsed_tools
 
     # Per-tool merged_keys collected from JSON bridge merges (P1.5).

package/scripts/install.sh

@@ -37,6 +37,10 @@ DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_GITIGNORE=false
+# When true, skip payload sync entirely and only install the project-local
+# `./agent-config` wrapper (Step 7 Phase 2). The bridge stage (install.py)
+# handles the .agent-settings.yml stub + nested-install guard.
+MINIMAL=false
 # Comma-separated tool IDs (default: all). Set by --tools or the
 # orchestrator (scripts/install). The .augment/ substrate is always
 # synced because every other tool symlinks back into it.
@@ -75,6 +79,7 @@ parse_args() {
             --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --tools)   TOOLS="$2"; shift 2 ;;
             --tools=*) TOOLS="${1#*=}"; shift ;;
+            --minimal|--settings-only) MINIMAL=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;
         esac
@@ -726,6 +731,21 @@ install_cli_wrapper() {
 main() {
     parse_args "$@"
 
+    # Minimal-init short-circuit (Step 7 Phase 2): skip every payload-sync
+    # stage and only install the project-local `./agent-config` wrapper.
+    # The bridge stage (install.py) handles the .agent-settings.yml stub
+    # + nested-install guard. No .augment/, no AGENTS.md, no symlinks.
+    if $MINIMAL; then
+        if ! $QUIET; then
+            echo "🔧  Minimal init — installing ./agent-config wrapper only"
+            echo "    Target: $TARGET_DIR"
+            $DRY_RUN && echo "    Mode: DRY RUN"
+        fi
+        install_cli_wrapper "$TARGET_DIR"
+        $QUIET || echo "✅  Wrapper installed (payload sync skipped)."
+        return 0
+    fi
+
     # First-run detection: gate the verbose source/target banner behind the
     # absence of .agent-settings.yml. Re-runs print a single status line.
     local is_first_run=false