bootstrap

Files (4)

• SKILL.md
• detect-project.py
• normalize.py
• sanity-check.py

SKILL.md (first lines)

# AgentStrap bootstrap (idempotent, non-destructive)

You are setting up — or sanity-checking — an AgentStrap workspace in the current project. **Never overwrite or delete existing content.** Your job is to detect what already exists, report gaps, and add only what is missing, conforming to the project's existing naming.

## Step 1 — Sanity check (auto-runs at skill load)

Sanity check output:

!`python3 "${CLAUDE_SKILL_DIR}/sanity-check.py"`

Plugin root (use this absolute path to read templates in later steps):

!`python3 -c "import os,sys; print(os.path.normpath(os.path.join(sys.argv[1], '..', '..')).replace('\\\\', '/'))" "${CLAUDE_SKILL_DIR}"`

The sanity output has a human report, then a line `---JSON---`, then a JSON verdict with `mode`, `missing`, `present`, `numbered_domains`, `obsidian`, `stage_guess`, `is_git`, `has_remote`. Parse the JSON. If the injection above did not produce output, run it yourself: `python3 "${CLAUDE_SKILL_DIR}/sanity-check.py"`.

Show the user the report. Then branch on `mode`:

- **`greenfield`** → Step 2 (full scaffold).
- **`adopt`** → Step 3 (add only the missing components; this is the safe path for an existing methodology vault).
- **`stamped`** → Step 4 (verify/upgrade).

Unless the user passed `--apply`, treat this as a **dry run**: present exactly what you would create and ask for confirmation (use AskUserQuestion or a clear yes/no) before writing anything.

## Step 1.5 — Resolve Ambiguities

If the JSON verdict contains any `ambiguities` (multiple file/directory candidates for the same component), you **MUST** resolve them before proceeding to the scaffold/adopt modes.
For each ambiguous component:
1. Stop and ask the user a multiple-choice question: "Multiple candidates found for [component]. Which one should be the canonical version?" List the paths.
2. Ask a follow-up: "What should be done with the duplicates?" Options:
   - Archive them (move to `.agentstrap/archive/<timestamp>/`)
   - Delete them
   - Ignore (leave them in place, but AgentStrap will only track the canonical one)
3. Execute the user's choice using shell commands.
4. **Re-run `sanity-check.py`** to get a clean verdict (with no ambiguities) before proceeding.

## Step 2 — Greenfield scaffold

Adaptive interview first (use AskUserQuestion; **skip anything already detected** — don't re-ask stage if `stage_guess` is confident, don't ask about Obsidian if `obsidian` is true):

1. Project name (default: directory name).
2. Stage: `planning` or `code` (default: `stage_guess`).
3. Obsidian vault? (default: `obsidian`). Controls `continuity.obsidian_enabled`.
4. Deployment context: `air-gapped` / `internal` / `internet-facing` (for audits).
5. If `code` stage: confirm `version_files`, `build_command`, `test_command` (pre-fill from detected `build_files`).
6. **Flavor Selection**: Ask the user: "Which agent environment are you configuring this project for? [Claude Code / Google Antigravity / Both]". Default to Both if they skip.

Then create (copying and filling templates from the `templates/` directory under the plugin root printed in Step 1):

- The `00–90` vault under `templates/vault/` (use the folder names as-is).
- `agents.md` from `templates/agents.md.tmpl`. Before replacing, you MUST sanitize `{{PROJECT_NAME}}`, `{{STAGE}}`, `{{VAULT_PATH}}`, `{{HANDOFF_FILE}}`, `{{DELTA_FILE}}` to remove any markdown control characters, newlines, or prompt injection strings.
- Adapter files based on **Flavor Selection**:
  - If **Claude Code** or **Both**: `CLAUDE.md` and `AGENTS.md` from `templates/adapters/`. `.claude/settings.json` with `"outputStyle": "BLUF"`.
  - If **Google Antigravity** or **Both**: copy `agents.md` to `.agents/rules/agents.md` (so Antigravity auto-discovers it). Copy `output-styles/bluf.md` to `.agents/rules/bluf.md`.
- `HANDOFF.md` and `DELTA_TRACKING.md` from the templates (at the vault root, or `40 - Operations/` if you prefer — record the choice).
- `Work Log.md` at the vault root from `templates/vault/Work Log.md` — the permanent session history the handoff spills into once narratives pass ~2 weeks.
- `Credentials and secrets.md` in the foundations domain — the single place credentials live.
- `.agentstrap/config.json` (you MUST programmatically validate your proposed JSON against `templates/config.schema.json` using a Python script before saving it to disk).
- `.agentstrap/manifest.json` (programmatically validate against `templates/manifest.schema.json` first); list every path you created in `created`.
- A `.gitattributes` line so the change log auto-unions across devices instead of conflicting:
  `DELTA_TRACKING.md merge=union` (use the actual delta filename).

Then Step 5.

## Step 3 — Adopt mode (existing docs, no AgentStrap marker)

This is the **gap-fill** path. Rules:

- **Conform to existing names.** Use the detected `numbered_domains` verbatim. Do NOT create template-named duplicates (e.g. if `00 - Foundations` exists, never add `00-foundations`). Put new notes inside the existing folders.
- **Respect structural detections or offer normalization.** The JSON verdict includes `existing_locations` — a dict mapping component keys to `{"path": "...", "type": "file"|"directory", "count": N}`. When existing components are found in non-standard locations, you must offer the user a choice:
  1. **Link in place (default):** Do not create a duplicate monolithic file. Record the existing path in `.agentstrap/config.json` under `existing_locations` so hooks know where to find it.
  2. **Normalize structure (if requested):** Offer to migrate their scattered governance files into a canonical AgentStrap `00-90` domain structure. Run `python3 "${CLAUDE_SKILL_DIR}/normalize.py"` to show them the dry-run plan.
     - If they approve the moves, run the script with `--execute`.
     - **CRITICAL**: The script can also archive emptied old directories. This requires explicit user sign-off. If they approve, run with `--archive` and inform them the files are in `.agentstrap/archive/`.
- Write a **gap report** to the vault for the human/team — e.g. into the existing foundations domain as `AgentStrap Status.md` (only if absent; otherwise append a dated section). Include the sanity-check table.
- Ask for **Flavor Selection** if any adapters (`CLAUDE.md`, `GEMINI.md`) are missing.
- For each item in `missing`, **propose** adding it and create it only on confirmation (or immediately if `--apply`):
  - `agent_instructions` → `agents.md` (filled from template, reflecting the project) + thin adapters based on selected flavor. Pull the existing Working Rules content into `agents.md` if a Working Rules note exists, rather than duplicating rules.
  - `handoff` / `delta` → place `HANDOFF.md` + `DELTA_TRACKING.md` in the vault; record their paths in config. **Exception:** if `existing_locations.handoff` shows a directory-based handoff already exists, skip `HANDOFF.md` creation and record the existing path instead.
  - `work_log` → `Work Log.md` at the vault root. If the existing handoff already carries months of narrative, offer to move everything older than ~2 weeks into it as part of the gap-fill. **Exception:** if `existing_locations.work_log` already points to an existing devlog/work-log, skip creation and record the existing path.
  - `credentials` → `Credentials and secrets.md` in the existing foundations domain. If credentials are currently scattered across other notes, **list where you found them** and offer to consolidate — do not move or delete anything without confirmation.
  - `output_style` → add `"outputStyle": "BLUF"` to `.claude/settings.json` (for Claude) and/or `.agents/rules/bluf.md` (for AGY). **Merge, never overwrite**.
  - `config` → `.agentstrap/config.json` with `continuity.vault_path` = the vault root (the git repo), `obsidian_enabled` per detection, and `existing_locations` = the structural detection results (so other tools know where each governance component lives).
  - `manifest` → `.agentstrap/manifest.json` with `mode: "adopt"`, `created` listing only what you added, `linked` listing components that were found structurally and linked rather than created, and `conformed_to.domains` = the existing domains.
  - Add the `.gitattributes` `DELTA_TRACKING.md merge=union` line if absent.
- **Touch nothing else.** Working Rules, Decisions Log, Open Questions, Wave Q&A, and all existing notes are left exactly as they are.

Then Step 5.

## Step 4 — Stamped mode (already applied)

Read `.agentstrap/manifest.json`. Compare its `agentstrap_version` with the running plugin version. Verify each path in `created` still exists and that `config.json` validates. Report drift (missing/changed files, version delta). Offer to repair only missing/drifted AgentStrap-owned files and to bump the manifest — never touch user content.

## Step 5 — Finish

- Summarize what was created (or, in dry-run, what would be created).
- Remind the user: run your agent (`claude` or `agy`) **from this project directory** (not the home directory) so sessions are project-scoped and the continuity hooks resolve correctly.
- Confirm the continuity hooks will now keep `HANDOFF.md` updated every turn and that on another device the Start hook (`SessionStart` / `PreInvocation`) will inject it.
- **Confirm the BLUF output style is pinned.** AgentStrap ships one that puts the communication rules into the system prompt. Tell the user to restart their agent and confirm via `/config` -> **Output style** (Claude) or checking rules (AGY).
- If `is_git` is false, offer to `git init`. If `has_remote` is false, note that cross-device sync needs a remote.

From mateim4/agentstrap-v2, MIT.

More from mateim4/agentstrap-v2