support existing-project mode in guide_me.py

README.md

@@ -44,6 +44,7 @@ Run these commands from the repository root.
 - This repository supports only Python 3 bootstrap workflows.
 - Command entrypoint: `python3 python3/guide_me.py`.
 - No additional language bootstrap layers are planned in this repository.
+- `python3 python3/guide_me.py` supports two project modes: `new` (bootstrap a brand new repository) and `existing` (retrofit AWB docs/workflow files into a repository that already exists). Existing-project mode never overwrites files already present in the target repository and requires the target directory to already exist.
 
 ## Responsibility Model
 
@@ -56,7 +57,7 @@ Run these commands from the repository root.
 - workflows: `document`, `review`, `changelog`, `linear`, `mcp-linear-planner`, `mcp-linear-sync`, `plan-to-blueprint`
 - skills: review the official AWB skills catalog and capture the skill IDs or directories that match the project scope and selected workflows
 - runbooks: `document-review-changelog.md`, `linear-mcp.md`, `mcp-linear-sync.md`, `plan-to-blueprint.md`
-- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
+- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `embed-aihero-radioactive`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
 - additional runbooks observed upstream: `iac-delivery.md`, `network-change.md`, `os-hardening-patching.md`
 
 If upstream names/contracts change, update this guide repo before the next bootstrap run.
@@ -69,7 +70,7 @@ Any agent must run the full protocol in `agentic_workflow_blueprint_guidance.md`
 
 1. Update and review the official blueprint repository as source of truth.
 2. Read `python3/README.md` before running anything.
-3. Run the entrypoint: `python3 python3/guide_me.py`.
+3. Run the entrypoint: `python3 python3/guide_me.py` and choose the project mode (`new` for a brand new repository, `existing` to retrofit AWB docs into a repository you already have).
 4. If the report shows `[FAIL]`/`[WARN]`, stop, fix those items, and rerun `python3 python3/guide_me.py` until the audit passes.
 5. Open the target project repository in VS Code.
 6. Review the generated input outputs from `python3/guide_me.py` and refine your answers by rerunning `python3 python3/guide_me.py` until the inputs are correct.

agentic_workflow_blueprint_guidance.md

@@ -128,7 +128,7 @@ Track these official examples and keep naming aligned:
 - workflows: `document`, `review`, `changelog`, `linear`, `mcp-linear-planner`, `mcp-linear-sync`, `plan-to-blueprint`
 - skills: review the official AWB skills catalog and capture the skill IDs or directories that match the project scope and selected workflows
 - runbooks: `document-review-changelog.md`, `linear-mcp.md`, `mcp-linear-sync.md`, `plan-to-blueprint.md`
-- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
+- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `embed-aihero-radioactive`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
 - additional runbooks observed upstream: `iac-delivery.md`, `network-change.md`, `os-hardening-patching.md`
 
 If upstream naming or contracts change, update this guide before the next bootstrap.

blue_print_used_on_creation.md

@@ -31,7 +31,7 @@ Record the values used for:
 - workflows: `document`, `review`, `changelog`, `linear`, `mcp-linear-planner`, `mcp-linear-sync`, `plan-to-blueprint`
 - skills: record the official skill names or directories selected for this project
 - runbooks: `document-review-changelog.md`, `linear-mcp.md`, `mcp-linear-sync.md`, `plan-to-blueprint.md`
-- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
+- additional workflows observed upstream: `analyzing-kubernetes-audit-logs`, `brainstorming`, `c4-architecture`, `changelog-generator`, `embed-aihero-radioactive`, `html-manual`, `iac`, `implementing-devsecops-security-scanning`, `implementing-network-policies-for-kubernetes`, `implementing-pod-security-admission-controller`, `implementing-rbac-hardening-for-kubernetes`, `implementing-syslog-centralization-with-rsyslog`, `infra-operations`, `network-engineering`, `os-platform`, `performing-container-image-hardening`, `performing-container-security-scanning-with-trivy`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `performing-vulnerability-scanning-with-nessus`, `plan-writing`, `radioactive`, `remediating-s3-bucket-misconfiguration`, `remotion-video-motion`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-github-actions-workflows`, `securing-kubernetes-on-cloud`, `thermo-fix`, `thermo-nuclear-code-quality-review`, `triaging-vulnerabilities-with-ssvc-framework`, `ui-ux-pro-max`
 - additional runbooks observed upstream: `iac-delivery.md`, `network-change.md`, `os-hardening-patching.md`
 
 If official naming/contracts change, this snapshot must be updated.

bootstrap_checklist.md

@@ -18,6 +18,7 @@ Use this checklist at the start of every new project to reduce setup drift.
 ## B. Input Capture
 
 - [ ] I ran the Python 3 entrypoint (`python3 python3/guide_me.py`).
+- [ ] I confirmed the correct project mode (`new` or `existing`) for this run.
 - [ ] I reviewed generated input outputs and reran the Python 3 entrypoint to refine answers until inputs were correct.
 - [ ] I confirmed the latest generated inputs are the source that will feed AWB scaffolding decisions.
 - [ ] I reviewed and validated core constraints.

python3/README.md

@@ -25,6 +25,8 @@ pip install -r requirements.txt
 python3 guide_me.py
 ```
 
+The first prompt selects the project mode: `new` (bootstrap a brand new repository) or `existing` (apply this guide's docs/workflow files to a repository that already exists). Existing-project mode never overwrites files already present in the target repository and requires the target directory to already exist before copying.
+
 ## Tests
 
 ```bash

python3/guide_me.py

@@ -21,11 +21,13 @@
     DEFAULT_WORKFLOWS,
     GENERATED_BLUEPRINTS_DIR,
     KNOWN_WORKFLOWS,
+    PROJECT_MODE_EXISTING,
     copy_bootstrap_assets,
     extract_audit_findings,
     prompt,
     prompt_csv_list,
     prompt_multiline,
+    prompt_project_mode,
     prompt_yes_no,
     recommended_runbooks,
     resolve_official_awb_dir,
@@ -38,6 +40,7 @@ def print_input_guidance() -> None:
     print("Input guidance (what you are about to provide):")
     print("- Official AWB: agentic-workflow-blueprint")
     print("- Official AWB repo: https://github.com/devton/agentic-workflow-blueprint")
+    print("- projectMode: new (bootstrap a new repo) or existing (retrofit docs into a current repo)")
     print("- projectSlug: short repo identifier in kebab-case (example: billing-api)")
     print("- baseBranch: integration branch name (example: main or develop)")
     print("- existingRootDoc: root instruction file used by the project (example: AGENTS.md)")
@@ -65,6 +68,7 @@ def bullet(lines: List[str]) -> str:
             f"- Collected at (UTC): {data.collected_at_utc}",
             "",
             "## Required Inputs",
+            f"- projectMode: {data.project_mode}",
             f"- projectSlug: {data.project_slug}",
             f"- baseBranch: {data.base_branch}",
             f"- existingRootDoc: {data.existing_root_doc}",
@@ -102,10 +106,15 @@ def bullet(lines: List[str]) -> str:
 def to_creation_template(data: BlueprintInputs) -> str:
     workflow_list = ", ".join(data.workflows_wanted)
     runbooks = recommended_runbooks(data.workflows_wanted)
+    is_existing = data.project_mode == PROJECT_MODE_EXISTING
+    title = "# Blueprint Applied to Existing Project" if is_existing else "# Blueprint Used on Creation"
+    target_repo_label = "existing project repository" if is_existing else "target project repository"
 
     return "\n".join(
         [
-            "# Blueprint Used on Creation",
+            title,
+            "",
+            f"Project mode: `{data.project_mode}`",
             "",
             "Official AWB source: `https://github.com/devton/agentic-workflow-blueprint`",
             "",
@@ -114,7 +123,7 @@ def to_creation_template(data: BlueprintInputs) -> str:
             "- Before start, update `agentic-workflow-blueprint` repo.",
             "- Run `make pre-bootstrap-audit` in this guide repository and proceed only if it passes.",
             "- Review official blueprint files in `agentic-workflow-blueprint`.",
-            "- Open the target project repository in VS Code.",
+            f"- Open the {target_repo_label} in VS Code.",
             "- Ask the LLM to review the current blueprint changes and this guidance repo.",
             "",
             "## Initial Input Snapshot",
@@ -145,7 +154,7 @@ def to_creation_template(data: BlueprintInputs) -> str:
             "",
             "## Migration Checklist to New Repo",
             "",
-            "- Create/open the target project repository directory.",
+            f"- Create/open the {target_repo_label} directory.",
             "- Move generated input snapshot files (`blueprint_inputs_*.json` and `blueprint_inputs_*.md`) into `bootstrap/inputs/` in the target repo.",
             "- Keep this file as `blue_print_used_on_creation.md` at the target repo root.",
             "- Copy files created during the initial inputs phase.",
@@ -190,6 +199,10 @@ def default_target_project_dir(project_slug: str) -> str:
     return str((Path("~/Documents/GitHub").expanduser() / project_slug).resolve())
 
 
+def default_existing_project_dir() -> str:
+    return str(Path.cwd())
+
+
 def run_pre_bootstrap_audit() -> bool:
     guide_dir = Path(__file__).resolve().parent.parent
     cmd = ["make", "pre-bootstrap-audit"]
@@ -256,6 +269,8 @@ def run() -> int:
     print()
     print_input_guidance()
 
+    project_mode = prompt_project_mode()
+
     while True:
         try:
             project_slug = validate_slug(
@@ -316,6 +331,7 @@ def run() -> int:
         stack_specific_rules=stack_specific_rules,
         notes=notes,
         collected_at_utc=collected_at_utc,
+        project_mode=project_mode,
     )
 
     json_path, md_path, creation_template_path = write_outputs(data)
@@ -328,6 +344,7 @@ def run() -> int:
     print("- (all files are written under generated_blueprints/)")
     print()
     print("What to do now (recommended):")
+    print(f"- Project mode: {data.project_mode}")
     print(f"1. Create/open target repo directory: ../{data.project_slug}")
     print("2. In target repo, create: bootstrap/inputs/")
     print(f"3. Move snapshots to target repo: {json_path.name}, {md_path.name}")
@@ -343,11 +360,17 @@ def run() -> int:
     print("6. Continue implementation only in the target repository")
 
     print()
-    if prompt_yes_no(
-        "I can copy everything needed from this guide and from official AWB to a new project directory. Do it now",
-        default_yes=False,
-    ):
-        default_target = default_target_project_dir(data.project_slug)
+    copy_prompt = (
+        "I can copy everything needed from this guide and from official AWB into this existing project. Do it now"
+        if data.project_mode == PROJECT_MODE_EXISTING
+        else "I can copy everything needed from this guide and from official AWB to a new project directory. Do it now"
+    )
+    if prompt_yes_no(copy_prompt, default_yes=False):
+        default_target = (
+            default_existing_project_dir()
+            if data.project_mode == PROJECT_MODE_EXISTING
+            else default_target_project_dir(data.project_slug)
+        )
         target_dir_text = prompt("Target project directory", default_target)
         resolved_target = str(Path(target_dir_text).expanduser().resolve())
         print(f"Resolved target directory: {resolved_target}")

python3/helpers.py

@@ -10,6 +10,9 @@
 
 DEFAULT_WORKFLOWS = ["document", "review", "changelog"]
 GENERATED_BLUEPRINTS_DIR = "generated_blueprints"
+PROJECT_MODE_NEW = "new"
+PROJECT_MODE_EXISTING = "existing"
+PROJECT_MODES = {PROJECT_MODE_NEW, PROJECT_MODE_EXISTING}
 DOC_CHAIN_WORKFLOWS = {"document", "review", "changelog"}
 MCP_SYNC_WORKFLOWS = {"mcp-linear-planner", "mcp-linear-sync"}
 KNOWN_WORKFLOWS = {
@@ -57,6 +60,7 @@ class BlueprintInputs:
     stack_specific_rules: List[str]
     notes: List[str]
     collected_at_utc: str
+    project_mode: str = PROJECT_MODE_NEW
 
 
 def prompt(text: str, default: str | None = None) -> str:
@@ -67,6 +71,18 @@ def prompt(text: str, default: str | None = None) -> str:
     return default or ""
 
 
+def prompt_project_mode(default_mode: str = PROJECT_MODE_NEW) -> str:
+    print("Project mode:")
+    print("  1) new - bootstrap a brand new project repository")
+    print("  2) existing - apply this guide's docs/workflow files to an existing project")
+    raw = prompt("Select project mode (new/existing)", default_mode).strip().lower()
+    if raw in {"1", PROJECT_MODE_NEW}:
+        return PROJECT_MODE_NEW
+    if raw in {"2", PROJECT_MODE_EXISTING}:
+        return PROJECT_MODE_EXISTING
+    return default_mode
+
+
 def prompt_yes_no(text: str, default_yes: bool = True) -> bool:
     default = "Y/n" if default_yes else "y/N"
     answer = input(f"{text} [{default}]: ").strip().lower()
@@ -149,6 +165,15 @@ def validate_target_dir(guide_dir: Path, target_dir: Path) -> None:
         )
 
 
+def validate_existing_target_dir(target_dir: Path) -> None:
+    if not target_dir.is_dir():
+        raise ValueError(
+            "Existing project mode requires the target directory to already exist: "
+            f"{target_dir}. Create or open the existing project repository first, "
+            "then rerun this guide."
+        )
+
+
 def copy_file_if_missing(
     src: Path, dst: Path, copied: List[str], skipped: List[str], warnings: List[str]
 ) -> None:
@@ -197,7 +222,10 @@ def copy_bootstrap_assets(
     skipped: List[str] = []
     warnings: List[str] = []
 
-    target_dir.mkdir(parents=True, exist_ok=True)
+    if data.project_mode == PROJECT_MODE_EXISTING:
+        validate_existing_target_dir(target_dir)
+    else:
+        target_dir.mkdir(parents=True, exist_ok=True)
     inputs_dir = target_dir / "bootstrap" / "inputs"
     inputs_dir.mkdir(parents=True, exist_ok=True)