Enhancement: Create a /docs/security.md for corporate security #945

Activity

1. bradygaster commented on Apr 12, 2026

   

   bradygaster

   on Apr 12, 2026

   Collaborator

   More actions

   Proposed Outline: docs/security.md — Corporate Security Guide

   Here's a proposed outline for this doc. The goal is to give non-technical stakeholders (security reviewers, compliance officers, IT leadership) a clear, jargon-light explanation of what Squad is and isn't, so they can make informed approval decisions.

   ---

   1. Executive Summary

   • One-paragraph plain-language description: "Squad is a configuration layer for GitHub Copilot that organizes AI-assisted development work into named roles."
   • Key takeaway: Squad does not introduce new AI models, external services, or data pipelines. It runs entirely within GitHub Copilot, which your organization already evaluates separately.

   2. What Squad Is (and Isn't)

   	Squad	What it's NOT
   Runtime	GitHub Copilot (already in your environment)	A standalone AI service or SaaS product
   Data storage	.squad/ directory in your repo (markdown files)	A database, cloud service, or external state store
   Network calls	Zero — all orchestration is local prompt routing	An API that phones home or sends data externally
   Models	Uses whatever models your Copilot license provides	A custom or fine-tuned model
   Agents	Named task assignments within a single Copilot session	Autonomous programs running independently

   3. Architecture & Data Flow

   • Diagram showing: User → GitHub Copilot → Squad coordinator (prompt routing) → Copilot agents (same session) → repo files
   • Emphasize: no new network boundaries crossed, no data leaves the Copilot session boundary
   • All state is plain-text markdown committed to the repository — fully auditable via git history

   4. Data Handling

   • What Squad reads: Source code in the repo, .squad/ configuration files (team roster, decisions, agent history)
   • What Squad writes: Only .squad/ directory files (decisions, logs, agent history) and source code changes the developer requests
   • What Squad never touches: Credentials, secrets, environment variables, .env files, external APIs
   • PII policy: Squad explicitly prohibits storing email addresses or other PII in committed files

   5. Access Control & Permissions

   • Squad inherits GitHub Copilot's permission model — no additional permissions required
   • File-level access: agents can only read/write files the Copilot session has access to
   • No elevated privileges, no admin access, no repository settings changes
   • Branch protection, PR reviews, and CI gates all apply normally to Squad-generated code

   6. Compliance & Audit Trail

   • All decisions logged in .squad/decisions.md (append-only, git-tracked)
   • All agent activity logged in .squad/orchestration-log/ (append-only, git-tracked)
   • Session logs in .squad/log/ — full traceability of who requested what
   • Every code change goes through standard PR workflow — no direct commits to protected branches

   7. Common Concerns Addressed

   Concern	Answer
   "Does this send our code to external AI?"	No. Squad uses your existing GitHub Copilot instance. Code handling follows your Copilot agreement.
   "Can agents act autonomously without developer oversight?"	No. Agents run within a developer's Copilot session and produce PRs that go through normal review.
   "Does this install third-party dependencies?"	No. Squad is an npm package with zero runtime dependencies beyond Node.js built-ins.
   "Can agents access production systems?"	No. Agents operate on source code in the repository. They have no network access beyond what Copilot provides.
   "Is this like [autonomous AI agent framework X]?"	No. Squad is a prompt-routing layer for GitHub Copilot, not an autonomous agent framework. There is no persistent process, no background daemon, no independent decision-making.

   8. Comparison with Existing Approved Tools

   • If your org approved GitHub Copilot, Squad adds no new risk surface — it's a configuration layer on top of it
   • Similar to: ESLint configs, PR templates, CODEOWNERS files — they shape how developers work but don't introduce new capabilities

   9. Removal & Offboarding

   • Delete .squad/ directory and .github/agents/squad.agent.md — Squad is fully removed
   • No residual processes, no cleanup scripts, no external state to decommission
   • npm uninstall @bradygaster/squad-cli removes the CLI tool

   10. References

   • Link to GitHub Copilot's own security documentation
   • Link to GitHub Copilot's enterprise data handling policies
   • Link to this repo's SECURITY.md for vulnerability reporting

   ---

   Tone note: This should read like a compliance FAQ, not a marketing document. Short sentences, concrete claims, no hyperbole. Every statement should be independently verifiable by examining the source code.

   Happy to help draft the full doc if this outline looks right. Great issue — this will help a lot of teams get past the "but AI agents!" reflex. 👍

   ❤️React with ❤️1Reacted by Matthew Morrow
2. Omzig commented on Apr 13, 2026

   

   Omzig

   on Apr 13, 2026

   ContributorAuthor

   More actions

   @bradygaster, epic! i already knew all that but to see it in words..... just makes me all warm and fuzzy. Yes, this 'should' yes i know i used the should word, help with these difficult conversations. TY for all your work in this.
3. bradygaster

   added

   close:staleCandidate for closing as staleCandidate for closing as stale

   triagedIssue has been triagedIssue has been triaged

   on Jun 24, 2026
4. bradygaster commented on Jun 24, 2026

   

   bradygaster

   on Jun 24, 2026

   Collaborator

   More actions

   Closing candidate — stale issue with no activity in 4+ months and unclear current relevance. Reopen if this is still needed.
5. Omzig commented on Jun 26, 2026

   

   Omzig

   on Jun 26, 2026

   Last edited by Omzig

   ContributorAuthor

   More actions

   Closing candidate — stale issue with no activity in 4+ months and unclear current relevance. Reopen if this is still needed.

   yes, we still need this. this is good stuff, and the draft was really good, i am unable to change the labels. @bradygaster
6. Omzig commented on Jun 30, 2026

   

   Omzig

   on Jun 30, 2026

   ContributorAuthor

   More actions

   @bradygaster, can we bump this? automation must have put the close:stale label on it.
7. bradygaster commented on Jun 30, 2026

   

   bradygaster

   on Jun 30, 2026

   Collaborator

   More actions

   Closing as stale — security documentation can be revisited as a fresh issue if needed.
8. bradygaster

   closed this as completedon Jun 30, 2026