Skip to content

docs: add .squad directory explainer to first-session guide#290

Closed
diberry wants to merge 1 commit intobradygaster:mainfrom
diberry:squad/new-customer-docs-3
Closed

docs: add .squad directory explainer to first-session guide#290
diberry wants to merge 1 commit intobradygaster:mainfrom
diberry:squad/new-customer-docs-3

Conversation

@diberry
Copy link
Copy Markdown
Collaborator

@diberry diberry commented Mar 8, 2026

What this PR does

Adds a 'What's inside .squad/?' section to the First Session guide, giving new users a quick reference for the files and directories Squad creates.

Changes

After the line where Squad creates the .squad/\ directory, a new subsection explains:

File/Directory Purpose
\ eam.md\ Team roster — who's on the squad and their roles
\
outing.md\ Work routing rules — how tasks get assigned
\decisions.md\ Shared decision log — the team's institutional memory
\�gents/\ Agent charters and histories — each member's identity and learnings
\ceremonies.md\ Team ceremony definitions — standups, retros, design reviews
\casting/\ Name registry — persistent agent-to-name mappings

Also confirms that users can and should edit these files, and that they should be committed to version control.

Context

New users weren't sure what the .squad/\ directory contained or whether they should touch it. This explainer builds confidence right at the moment the directory is created.

Closes #289

Suggested reviewers: @diberry, @bradygaster

Closes bradygaster#289

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 8, 2026

@bradygaster — PR is ready for review. Adds a quick-reference table to the first-session guide explaining what's inside .squad/ and confirming users can edit + commit those files.

@bradygaster
Copy link
Copy Markdown
Owner

Thank you @diberry! 🎉 Your '.squad/ directory explainer' table and ownership guidance have been ported into the new Astro docs site (merged via PR #293). The content is now live at docs/src/content/docs/get-started/first-session.md. This is a huge improvement — new users will immediately understand what .squad/ contains and that they own those files.

@bradygaster bradygaster closed this Mar 9, 2026
bradygaster added a commit that referenced this pull request Mar 9, 2026
…post

- Port @diberry's installation decision tree (PR #288) and .squad/ explainer (PR #290) into Astro docs
- Apply Brady's review fixes: sidebar scroll-to-active, CLI text updates, logo fix, Copilot CLI callouts, CI/CD cron safety warning
- Update CONTRIBUTORS.md with @IEvangelist (Astro docs rewrite) and @diberry (4 PRs)
- Add blog post 028: New Docs Site — Built by the Community

Merges community work from:
- PR #293 by @IEvangelist (Astro docs rewrite)
- PR #286, #288, #290, #292 by @diberry (docs improvements)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 9, 2026
- Add David Pine (@IEvangelist) to Code Contributors — PRs #293, #298
- Add Dina Berry (@diberry) to Code Contributors — PRs #286, #288, #290, #292
- Update Tamir Dresher with recent PRs #278-280, #283
- Add Dale Kirby to Code Contributors — PR #243

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 9, 2026
* docs(ai-team): session log and orchestration records

Session: 2026-03-09-docs-push-contributors
Requested by: Brady

Changes:
- Logged PAO orchestration: blog 028 update, CONTRIBUTORS.md refresh
- Logged FIDO orchestration: test baseline verification (22 passing)
- Logged session summary: docs push workflow with PR #300 merge
- No decisions inbox entries to merge

* docs: credit Pine, Dina, Tamir, Kirby on docs contributor page

- Add David Pine (@IEvangelist) to Code Contributors — PRs #293, #298
- Add Dina Berry (@diberry) to Code Contributors — PRs #286, #288, #290, #292
- Update Tamir Dresher with recent PRs #278-280, #283
- Add Dale Kirby to Code Contributors — PR #243

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry pushed a commit to diberry/squad that referenced this pull request Mar 10, 2026
…gaster#307)

* docs(ai-team): session log and orchestration records

Session: 2026-03-09-docs-push-contributors
Requested by: Brady

Changes:
- Logged PAO orchestration: blog 028 update, CONTRIBUTORS.md refresh
- Logged FIDO orchestration: test baseline verification (22 passing)
- Logged session summary: docs push workflow with PR bradygaster#300 merge
- No decisions inbox entries to merge

* docs: credit Pine, Dina, Tamir, Kirby on docs contributor page

- Add David Pine (@IEvangelist) to Code Contributors — PRs bradygaster#293, bradygaster#298
- Add Dina Berry (@diberry) to Code Contributors — PRs bradygaster#286, bradygaster#288, bradygaster#290, bradygaster#292
- Update Tamir Dresher with recent PRs bradygaster#278-280, bradygaster#283
- Add Dale Kirby to Code Contributors — PR bradygaster#243

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Add 'What's in .squad/?' explainer to first-session.md

2 participants