Adding "Stealth Mode" for External Repositories

[jdugarte]

🏷️ Type of Change

• 🚀 New Feature
• 🐛 Bug Fix
• 🧹 Refactor / Cleanup
• ⚡ Performance Optimization
• 📚 Documentation Update
• 🛠️ CI/CD / Build System

📝 Summary

This PR introduces Stealth Mode, a structural configuration that allows developers to run agentic:guild inside external, locked-down, or team-owned repositories without leaving visible traces or forcing the AI's preferred structure onto the rest of the development team.

When initialized with sync.sh --stealth, the Operating System fundamentally shifts how its skills operate. It relies on local exclusions (.git/info/exclude instead of .gitignore), heavily restricts automatic documentation mutations, and suppresses internal compliance trackers like [REQ-ID] tags that would otherwise pollute a team's clean git workflow.

✨ Key Changes

• sync.sh: Added the --stealth installation flag. Installer now securely registers internal directories strictly to .git/info/exclude, skips Git Hook installation, and conditionally avoids scaffolding the heavy docs/* directory trees to prevent dirtying external filesystems.
• update-agentic-guild: The updater skill is now entirely stealth-aware. It registers new upstream files directly to .git/info/exclude, skips merging conflicts on team-tracked files (e.g., PR templates), and now automatically disposes of the tmp_update repository clone after summarizing the newest upstream changelog.
• start-task & audit-compliance: Conditioned the Construction-by-Contract (CbC) instructions and IV&V Audit checks to ignore [REQ-ID] traceability entirely when in stealth mode, ensuring external repos remain clean of internal metadata tags.
• finish-branch: Conditioned the final PR phase to entirely skip executing the sync-docs and harvest-rules skills in stealth mode, and explicitly prevents the AI from attempting to modify or check docs/ROADMAP.md or CHANGELOG.md.
• pr-description: Updated the drafting prompt to generate a standard, open-source style PR description if in stealth mode, stripping any mention of agentic:guild's internal structures.
• README.md: Added a thorough documentation section explaining what Stealth Mode is, why it was built, and how it behaves.

📸 Screenshots / Videos (if applicable)

N/A

🧪 Verification Plan

Automated Tests

• scripts/check.sh (Shellcheck execution passes cleanly on sync.sh logic)

Manual Verification

1. Run sync.sh --stealth in a clean directory and confirm .git/info/exclude contains the accurate exclusions without a !.agenticguild/.gitkeep un-exclude.
2. Confirm sync.sh executed cleanly without the --stealth flag and resets .agenticguild/config.json to false.
3. Validate update-agentic-guild correctly skips creating .cursorrules if it doesn't already exist and appropriately adds it to stealth exclusions if it does.
4. Verify skills correctly identify <phase id="0" name="Stealth Check"> during execution runs.

🛡️ Impact Assessment

• Security: No impact
• Performance: No impact
• Accessibility: No impact

🧠 Anti-Drift Checklist

To prevent "drift" between the codebase and our AI context, please attest that you have updated the authoritative documentation:

• Docs: I have run sync-docs and updated any docs that require changes (SPEC, schema, DATA_FLOW_MAP, ADRs, etc.).
• Roadmap: If this PR completes a roadmap item, docs/ROADMAP.md has been updated (finish-branch does this automatically).
• Architecture (ADR): I have created/updated ADRs in docs/core/ADRs/ if new paradigms were introduced.
• AI Rules: I have updated .cursorrules or approved a harvest-rules run if developer protocols changed.
• Boundaries: I have updated docs/core/SYSTEM_ARCHITECTURE.md if the tech stack, libraries, or core patterns shifted.

🔍 Reviewer Focus Areas

Special attention on the ensure_dir exclusion refactor in sync.sh. We transitioned from a wildcard directory paradigm (which was overwriting valid team files) to a rigorous file-by-file exclusion model.

🔜 Follow-ups / PENDING

None.

[cursor]

PR Summary

Medium Risk
Changes install/update behavior and multiple workflow skills to conditionally skip writing tracked files, which could affect onboarding/update flows if the stealth detection or exclude logic misfires.

Overview
Adds a Stealth Mode path that keeps agentic:guild usage local for work/external repos by persisting .agenticguild/config.json and having skills read it to adjust behavior.

sync.sh now supports --stealth, writes ignores to .git/info/exclude (instead of .gitignore), avoids creating/updating repo-visible folders/files (e.g. docs/, .github) when possible, skips overwriting existing tracked files, and skips installing git hooks; it also excludes .cursorrules when created.

Core skills (start-task, finish-branch, audit-compliance, pr-description, update-agentic-guild) add a stealth check phase and conditional logic to skip [REQ-ID] traceability enforcement, avoid auto-updating docs/rules/roadmap/changelog, and generate “clean” PR descriptions without internal agentic metadata; README documents the new mode and its tradeoffs.

^{Written by Cursor Bugbot for commit d1dea43. This will update automatically on new commits. Configure here.}

[cursor]

Stealth ensure_dir skips exclude for pre-existing directories

Low Severity

The ensure_dir function only adds a directory wildcard pattern (e.g. docs/core/*) to .git/info/exclude when the directory is being newly created. In company repos where directories like docs/core/, .cursor/skills/, or .github/ already exist, no wildcard exclusion is added. While individually synced files get per-file exclusions, any additional files the AI creates later in those directories during development won't be covered.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}