Adding "Stealth Mode" for External Repositories

README.md

@@ -77,6 +77,7 @@ If you've ever thought *"I need this AI to follow the same rules my team follows
 - Every new conversation starts from scratch.
 
 ### After agentic:guild
+- **It actively intercepts vibe coding**, catching unstructured requests (e.g., "build a login page") and redirecting you to the proper planning process.
 - The AI **classifies** every task before it touches anything.
 - It **writes a traceable implementation plan** you approve before the first line of code changes.
 - It uses **Test-Driven Development** by default, enforced by a Correct-by-Construction gate.
@@ -116,6 +117,8 @@ agentic:guild syncs into any existing or new project in seconds.
 curl -s https://raw.githubusercontent.com/jdugarte/agentic-guild/main/sync.sh | bash
 ```
 
+> **Note:** Installing agentic:guild in a company or external repository? Use **[Stealth Mode](#stealth-mode-for-workexternal-repos)** to benefit from the disciplined AI workflow locally, without imposing agentic:guild's file structure and processes on the rest of your team.
+
 The script will:
 - Create a git-ignored `.agenticguild/` memory directory for AI task state
 - Install all skills into `.cursor/skills/`
@@ -136,6 +139,7 @@ These are the documents your AI will be required to consult and obey. Think of t
 Once installed, you trigger skills through your AI assistant naturally:
 
 ```
+"Who are you?"                 → triggers hello (onboarding & system check)
 "Let's start this task"        → triggers start-task
 "Let's explore this feature"   → triggers explore-task
 "Let's finish this branch"     → triggers finish-branch
@@ -146,6 +150,32 @@ The AI handles the rest — structured, gated, auditable.
 
 ---
 
+## Stealth Mode (For Work/External Repos)
+
+It is entirely possible—and recommended—to use agentic:guild in "Stealth Mode" when working on company repositories or external projects where you may not want or need to introduce the full agentic:guild file structure to your teammates.
+
+In Stealth Mode, you get the full benefit of a disciplined AI pair programmer enforcing code quality and architecture locally, without affecting the remote repository or company CI pipelines.
+
+### How to install in Stealth Mode
+
+Append `--stealth` to the standard sync script:
+
+```bash
+curl -s https://raw.githubusercontent.com/jdugarte/agentic-guild/main/sync.sh | bash -s -- --stealth
+```
+
+### What Stealth Mode does:
+
+- **Local Git Ignores:** Instead of modifying `.gitignore` (which your team would see), it silently maps all agentic:guild files into your local `.git/info/exclude`. It dynamically contours itself to any folder structures (like `docs/` or `.cursor/skills/`) that might already exist in the repo.
+- **Relaxes Internal Traceability:** The AI drops requirements for `[REQ-ID]` tags in tests or code comments, preventing your codebase from being cluttered with internal metadata.
+- **Suppresses Internal Reminders:** Workflow skills like `finish-branch` will skip reminding you to commit internal state files like `docs/ROADMAP.md` or `CHANGELOG.md`.
+- **Clean PR Drafts:** The `pr-description` skill will formulate standard Open Source-style PRs (using your team's template if one exists) instead of referencing internal agentic documentation.
+- **Skips Git Hooks:** It skips the installation of pre-commit git hooks, ensuring it never interferes with company pipeline tools.
+
+*(Note: If you already have a `.cursorrules` file, the script will append the agentic:guild routing block to it. Be sure to manually omit this block from your commits).*
+
+---
+
 ## The engineering standards agentic:guild enforces
 
 agentic:guild ships with battle-tested templates for the standards that improve code quality and maintainability:

skills/audit-compliance/SKILL.md

@@ -26,14 +26,26 @@
   </pre_flight>
 
   <workflow>
+    <phase id="0" name="Stealth Check">
+      <step id="0.1">
+        <action>
+          Use the `view_file` tool to quietly read `.agenticguild/config.json`. If it exists and contains `"stealth_mode": true`, remember that you are operating in stealth mode. Do not announce this to the user.
+        </action>
+        <yield>[AUTO-TRANSITION TO 1.1]</yield>
+      </step>
+    </phase>
+
     <phase id="1" name="IV&V Analysis">
       <step id="1.1">
         <action>
           Assume the persona of an Independent Auditor. You have no knowledge of the brainstorming process.
           Use the `view_file` tool to read `docs/core/deterministic_coding_standards.md` to establish the strict rules.
           Read the `git diff` of the branch against the default branch (e.g. `main`). Use the repository's default branch unless the project uses a different convention.
-          Scan test files for `[REQ-ID]` traceability against `SPEC.md`.
-          Scan all new or modified files for domain concepts represented as raw primitive types (String, Integer, raw object/hash). A "domain concept" is any value with business meaning: identifiers (user ID, order ID), contact data (email, phone), measurements (age, quantity, price/currency), or status enums. Flag any that should be a Value Object (Ruby) or Branded Type (TypeScript).
+
+          If NOT in Stealth Mode: Scan test files for `[REQ-ID]` traceability against `SPEC.md`.
+          If in Stealth Mode: Skip the `[REQ-ID]` traceability check entirely to avoid cluttering external repos with internal tags.
+
+          Scan all new or modified files for domain concepts represented as raw primitive types (String, Integer, raw object/hash). A "domain concept" is any value with business meaning: identifiers, contact data, measurements, or status enums. Flag any that should be a Value Object (Ruby) or Branded Type (TypeScript).
 
           Generate a strict Compliance Report using the exact format specified below:
 

skills/finish-branch/SKILL.md

@@ -28,6 +28,15 @@
   </pre_flight>
 
   <workflow>
+    <phase id="0" name="Stealth Check">
+      <step id="0.1">
+        <action>
+          Use the `view_file` tool to quietly read `.agenticguild/config.json`. If it exists and contains `"stealth_mode": true`, remember that you are operating in stealth mode. Do not announce this to the user.
+        </action>
+        <yield>[AUTO-TRANSITION TO 1.1]</yield>
+      </step>
+    </phase>
+
     <phase id="1" name="Interactive Local Review">
       <step id="1.1">
         <action>Use the `view_file` tool to read and follow `.cursor/skills/code-review/SKILL.md` until it yields. Execute the full skill with its own PAUSEs; then return to finish-branch.</action>
@@ -43,17 +52,19 @@
           1. **Complexity & Length**: Cyclomatic complexity > 10 or functions > 60 lines.
           2. **Traceability**: New test blocks missing `[REQ-ID]` tags referencing `docs/core/SPEC.md`.
           3. **Domain Primitives (CbC)**: New or modified code using raw primitive types (String, Integer, raw object/hash) for domain concepts — any value with business meaning such as identifiers, contact data, measurements, or status enums. These should be Value Objects (Ruby) or Branded Types (TypeScript).
+          If NOT in Stealth Mode: Check all 3 categories (Complexity, Traceability, Domain Primitives).
+          If in Stealth Mode: Skip checking for Traceability (`[REQ-ID]`) entirely. Only check Complexity and Domain Primitives.
         </action>
         <yield>
           [PAUSE - REPORT FINDINGS]
-          Conversationally present the findings of the audit across all three checks. Explicitly ask the user if they want you to fix any violations — missing `[REQ-ID]` tags, complexity issues, or domain primitive usages — before proceeding.
+          Conversationally present the findings of the audit. Explicitly ask the user if they want you to fix any violations before proceeding. (Remember: if in stealth mode, you should not be reporting or offering to fix `[REQ-ID]` tags).
           AWAIT COMMAND TO FIX OR PROCEED.
         </yield>
       </step>
       <step id="2.2">
         <action>
           If the user requested fixes in Step 2.1, implement the necessary changes:
-          - Add missing `[REQ-ID]` tags to test blocks.
+          - (If NOT in Stealth Mode) Add missing `[REQ-ID]` tags to test blocks.
           - Refactor functions exceeding 60 lines or cyclomatic complexity > 10.
           - Wrap domain concepts in Value Objects (Ruby) or Branded Types (TypeScript) to replace raw primitive usage.
           Run local tests to verify all changes pass.
@@ -94,20 +105,34 @@
 
     <phase id="4" name="Final Spackle & PR">
       <step id="4.1">
-        <action>Use the `view_file` tool to read and follow `.cursor/skills/sync-docs/SKILL.md` until it yields. The skill analyzes the branch diff and updates any docs that need changes.</action>
+        <action>
+          If NOT in Stealth Mode: Use the `view_file` tool to read and follow `.cursor/skills/sync-docs/SKILL.md` until it yields. The skill analyzes the branch diff and updates any docs that need changes.
+          If in Stealth Mode: Skip `sync-docs` entirely, as automatically modifying architectural documents violates stealth mode constraints.
+        </action>
         <yield>[PAUSE - AWAIT CONFIRMATION TO PROCEED]</yield>
       </step>
       <step id="4.2">
-        <action>Use the `view_file` tool to read and follow `.cursor/skills/harvest-rules/SKILL.md` until it yields. Then return to finish-branch.</action>
+        <action>
+          If NOT in Stealth Mode: Use the `view_file` tool to read and follow `.cursor/skills/harvest-rules/SKILL.md` until it yields. Then return to finish-branch.
+          If in Stealth Mode: Skip `harvest-rules` entirely, as writing tracking rules inferred from Git diffs into tracked files violates stealth mode constraints.
+        </action>
         <yield>[PAUSE - AWAIT CONFIRMATION TO PROCEED]</yield>
       </step>
       <step id="4.3">
-        <action>Check if user-facing changes exist; if so, ensure `CHANGELOG.md` is updated. Use the `view_file` tool to read the active session file (if any) for `<roadmap_item>`. If this branch corresponds to a roadmap item, update `docs/ROADMAP.md`: move the item to Done, add today's date. If unclear, ask the user which roadmap item (if any) this branch completes. Then use the `view_file` tool to read and follow `.cursor/skills/pr-description/SKILL.md` until it yields. Remind the user to commit `docs/ROADMAP.md` if it was updated.</action>
+        <action>
+          If NOT in Stealth Mode: Check if user-facing changes exist; if so, ensure `CHANGELOG.md` is updated. Use the `view_file` tool to read the active session file (if any) for `<roadmap_item>`. If this branch corresponds to a roadmap item, update `docs/ROADMAP.md`: move the item to Done, add today's date. If unclear, ask the user which roadmap item (if any) this branch completes. Remind the user to commit `docs/ROADMAP.md` and `CHANGELOG.md` if they were updated.
+          If in Stealth Mode: Do NOT modify or remind the user about `CHANGELOG.md` or `docs/ROADMAP.md` to avoid altering the external team's tracked documentation.
+
+          Then (in all modes): use the `view_file` tool to read and follow `.cursor/skills/pr-description/SKILL.md` until it yields.
+        </action>
         <yield>[PAUSE - AWAIT CONFIRMATION]</yield>
       </step>
       <step id="4.4">
         <action>
-          The branch is finished and task knowledge has been synced to the docs (sync-docs and harvest-rules). Conversationally tell the user that and ask: "Would you like me to clear the active task from memory? I'll set the active task to none and archive the session file to `.agenticguild/completed_sessions/` so it's no longer the current task — you can delete that folder or file later if you don't need the record. Reply yes to clear and archive, or no to leave it as-is for now."
+          If NOT in Stealth Mode: The branch is finished and task knowledge has been synced to the docs (sync-docs and harvest-rules). Conversationally tell the user that.
+          If in Stealth Mode: Conversationally tell the user the PR is ready (remember sync-docs and harvest-rules were intentionally skipped).
+
+          Then (in all modes): Ask: "Would you like me to clear the active task from memory? I'll set the active task to none and archive the session file to `.agenticguild/completed_sessions/` so it's no longer the current task — you can delete that folder or file later if you don't need the record. Reply yes to clear and archive, or no to leave it as-is for now."
         </action>
         <yield>[PAUSE - AWAIT USER CONFIRMATION TO CLEAR TASK FROM MEMORY]</yield>
       </step>

skills/pr-description/SKILL.md

@@ -32,12 +32,25 @@
   </hard_constraints>
 
   <workflow>
+    <phase id="0" name="Stealth Check">
+      <step id="0.1">
+        <action>
+          Use the `view_file` tool to quietly read `.agenticguild/config.json`. If it exists and contains `"stealth_mode": true`, remember that you are operating in stealth mode. Do not announce this to the user.
+        </action>
+        <yield>[AUTO-TRANSITION TO 1.1]</yield>
+      </step>
+    </phase>
+
     <phase id="1" name="Context & Drafting">
       <step id="1.1">
         <action>
           Determine the default branch (e.g. main, master, develop) from the project. Run git log and git diff of the current branch against that default branch to gather absolute facts (e.g. `git log <default>..HEAD --oneline` and `git diff <default>...HEAD --name-only`).
-          Use the `view_file` tool to read `.github/PULL_REQUEST_TEMPLATE.md` if it exists.
-          Draft the PR description. If this PR likely completes a roadmap item (check branch name or session metadata), add a helpful reminder: "If this closes a roadmap item, ensure `docs/ROADMAP.md` was updated (finish-branch does this) and mention it in the PR."
+          Use the `view_file` tool to check for existing PR templates (e.g. `.github/PULL_REQUEST_TEMPLATE.md` or similar common locations).
+
+          If you are in Stealth Mode: Draft a standard open-source style PR description based entirely on the diffs and commits. Do NOT include or mention `docs/core/`, `ROADMAP.md`, `[REQ-ID]` tags, ADRs, or internal agentic:guild structures. If the team provides a PR template, fill it out cleanly without agentic:guild metadata.
+
+          If NOT in Stealth Mode: Draft the structured PR description. If this PR likely completes a roadmap item (check branch name or session metadata), add a helpful reminder: "If this closes a roadmap item, ensure `docs/ROADMAP.md` was updated (finish-branch does this) and mention it in the PR."
+
           Output the draft in a markdown code block directly in the chat (do not write to a file or copy to clipboard) and pleasantly let the user know it's ready for them to copy.
         </action>
         <yield>[PAUSE - PR DESCRIPTION READY. USER MAY COPY FROM CODE BLOCK. SKILL COMPLETE]</yield>

skills/start-task/SKILL.md

@@ -32,6 +32,15 @@
   </pre_flight>
 
   <workflow>
+    <phase id="0" name="Stealth Check">
+      <step id="0.1">
+        <action>
+          Use the `view_file` tool to quietly read `.agenticguild/config.json`. If it exists and contains `"stealth_mode": true`, remember that you are operating in stealth mode. Do not announce this to the user.
+        </action>
+        <yield>[AUTO-TRANSITION TO 1.1]</yield>
+      </step>
+    </phase>
+
     <phase id="1" name="Context Initialization">
       <step id="1.1">
         <action>
@@ -114,7 +123,10 @@
         <action>
           You MUST use the `view_file` tool to physically read the `.agenticguild/active_sessions/task_[name].md` file from disk. Do NOT rely on memory. Find the next step with `status="pending"`.
           Write the failing test for this step only.
-          Tag the test with the appropriate [REQ-ID] from `docs/core/SPEC.md` (format: `REQ-[DOMAIN]-[NNN]`, e.g. `REQ-AUTH-001`; projects may customize).
+
+          If NOT in Stealth Mode: Tag the test with the appropriate [REQ-ID] from `docs/core/SPEC.md` (format: `REQ-[DOMAIN]-[NNN]`, e.g. `REQ-AUTH-001`; projects may customize).
+          If in Stealth Mode: Do NOT add `[REQ-ID]` tags, keeping the tests clean for the external repo.
+
           If the test involves a domain concept, use the Value Objects / Branded Types approved in Step 3.0 — never raw primitives.
           Show the user the failing test and ask if they're ready to proceed and make it pass.
         </action>
@@ -124,14 +136,14 @@
         <action>
           Use the `view_file` tool to read `.cursor/templates/CbC_GENERATION_PROMPT.md`.
           Before writing any implementation code, apply the CbC generation protocol:
-          1. Fill the `<context>` block with the relevant REQ-ID from `docs/core/SPEC.md` and the current step description from the active session file.
+          1. Fill the `<context>` block. If NOT in Stealth Mode, include the relevant REQ-ID from `docs/core/SPEC.md`. In all cases, include the current step description from the active session file.
           2. Apply all `<constraints>` from the template to your generation:
              - No function over 60 lines.
              - No unbounded loops.
              - Pre-condition and Post-condition assertions on all data mutations and service calls.
              - No raw primitive types for domain concepts — use Value Objects (Ruby) or Branded Types (TypeScript).
              - Cyclomatic complexity ≤ 10.
-             - Every new public method must be traceable to a REQ-ID from `docs/core/SPEC.md`.
+             - Every new public method must be traceable to a REQ-ID from `docs/core/SPEC.md` (Unless in Stealth Mode, then skip traceability requirements).
           3. REFLECTION GATE: Before outputting the code, you MUST execute the `<reflection>` step from the template — critique your own proposed implementation against each constraint. If any violation is found, fix the code first. Follow the `<output_format>` rule in the template: show the reflection block only if violations were found and corrected. If everything passes, output only the corrected code with no reflection commentary.
           Write the minimum application code required to make the failing test pass.
           Ensure you do not violate `docs/core/SYSTEM_ARCHITECTURE.md`.