|
1 | | -# Squad Documentation |
2 | | - |
3 | | -Public-facing documentation for Squad. GitHub Pages ready. |
4 | | - |
5 | | -## Guides |
6 | | - |
7 | | -- [Product Guide](guide.md) — Complete reference for all Squad features |
8 | | -- [Sample Prompts](sample-prompts.md) — Ready-to-use prompts showing what Squad can do |
9 | | - |
10 | | -## Feature Reference |
11 | | - |
12 | | -### Core |
13 | | -- [Team Setup](features/team-setup.md) — Init mode, first session, team creation |
14 | | -- [Work Routing](features/routing.md) — How work gets assigned to agents |
15 | | -- [Parallel Execution](features/parallel-execution.md) — Background vs sync, fan-out |
16 | | -- [Response Modes](features/response-modes.md) — Tiered response speed/depth |
17 | | -- [Memory System](features/memory.md) — How agents learn and remember |
18 | | -- [Directives](features/directives.md) — Capturing team rules and preferences |
19 | | -- [Reviewer Protocol](features/reviewer-protocol.md) — Rejection lockout and revision routing |
20 | | - |
21 | | -### Workflow |
22 | | -- [GitHub Issues Mode](features/github-issues.md) — GitHub issue-driven development |
23 | | -- [GitLab Issues Mode](features/gitlab-issues.md) — 🧪 *Experimental* — GitLab issue-driven development |
24 | | -- [PRD Mode](features/prd-mode.md) — Product requirements decomposition |
25 | | -- [Labels & Triage](features/labels.md) — go:/release:/type:/priority: taxonomy |
26 | | -- [Ralph — Work Monitor](features/ralph.md) — Autonomous backlog processing |
27 | | -- [Project Boards](features/project-boards.md) — GitHub Projects V2 integration |
28 | | - |
29 | | -### Team |
30 | | -- [Human Team Members](features/human-team-members.md) — Mixed AI/human teams |
31 | | -- [@copilot Coding Agent](features/copilot-coding-agent.md) — Autonomous issue agent |
32 | | -- [Skills System](features/skills.md) — Earned knowledge with confidence lifecycle |
33 | | -- [Ceremonies](features/ceremonies.md) — Team meetings and rituals |
34 | | -- [Notifications](features/notifications.md) — Ping via Teams/MCP |
35 | | - |
36 | | -### Infrastructure |
37 | | -- [Per-Agent Model Selection](features/model-selection.md) — Cost-first model routing |
38 | | -- [Git Worktrees](features/worktrees.md) — Multi-branch team state |
39 | | -- [Export & Import](features/export-import.md) — Portable team snapshots |
40 | | - |
41 | | -## Walkthroughs |
42 | | - |
43 | | -- [First Session](tour-first-session.md) — Your first time using Squad |
44 | | -- [GitHub Issues](tour-github-issues.md) — GitHub issue-driven development walkthrough |
45 | | -- [GitLab Issues](tour-gitlab-issues.md) — 🧪 *Experimental* — GitLab issue-driven development walkthrough |
46 | | - |
47 | | -## Scenarios |
48 | | - |
49 | | -### Getting Started |
50 | | -- [Starting a New Project](scenarios/new-project.md) — Greenfield setup |
51 | | -- [Adding to an Existing Repo](scenarios/existing-repo.md) — Drop Squad into existing code |
52 | | -- [Mid-Project Onboarding](scenarios/mid-project.md) — Adding Squad halfway through |
53 | | -- [Upgrading Squad](scenarios/upgrading.md) — Update to the latest version |
54 | | - |
55 | | -### Team Management |
56 | | -- [Solo Developer](scenarios/solo-dev.md) — Is Squad overkill for one person? |
57 | | -- [Mixed Human + AI Team](scenarios/team-of-humans.md) — Humans and agents working together |
58 | | -- [Keeping Your Squad](scenarios/keep-my-squad.md) — Persistence across projects |
59 | | -- [Combining Old Squads](scenarios/multiple-squads.md) — Cherry-picking from multiple teams |
60 | | - |
61 | | -### Project Types |
62 | | -- [Large Codebases](scenarios/large-codebase.md) — Will Squad choke on a big repo? |
63 | | -- [Monorepos](scenarios/monorepo.md) — Multiple services, one squad |
64 | | -- [Open Source Projects](scenarios/open-source.md) — Triage, contributors, community |
65 | | - |
66 | | -### Operations |
67 | | -- [Client Compatibility Matrix](scenarios/client-compatibility.md) — What works on CLI, VS Code, JetBrains, GitHub.com |
68 | | -- [Issue-Driven Development](scenarios/issue-driven-dev.md) — End-to-end issue workflow |
69 | | -- [CI/CD Integration](scenarios/ci-cd-integration.md) — Squad + GitHub Actions |
70 | | -- [Moving a Team](scenarios/team-portability.md) — Export and import between repos |
71 | | -- [Team State Storage](scenarios/team-state-storage.md) — Gitignore, submodules, branches, and more |
72 | | -- [Model Selection Strategies](scenarios/switching-models.md) — Budget vs quality tradeoffs |
73 | | -- [Privacy & Security](scenarios/private-repos.md) — What stays private |
74 | | -- [Disaster Recovery](scenarios/disaster-recovery.md) — When things go wrong |
| 1 | +# Squad Docs |
| 2 | + |
| 3 | +The documentation site for Squad, built with [Astro](https://astro.build/), [Tailwind CSS](https://tailwindcss.com/), and [Pagefind](https://pagefind.app/) for search. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Node.js 22+ |
| 8 | +- Run `npm install` from the `docs/` directory |
| 9 | + |
| 10 | +## Commands |
| 11 | + |
| 12 | +All commands are run from the `docs/` directory, or from the repo root using the `docs:` prefix. |
| 13 | + |
| 14 | +| From `docs/` | From repo root | Description | |
| 15 | +|---|---|---| |
| 16 | +| `npm run dev` | `npm run docs:dev` | Start dev server with hot reload | |
| 17 | +| `npm run build` | `npm run docs:build` | Production build (Astro + Pagefind) | |
| 18 | +| `npm run preview` | `npm run docs:preview` | Preview the production build | |
| 19 | + |
| 20 | +## Development |
| 21 | + |
| 22 | +```bash |
| 23 | +npm run dev |
| 24 | +``` |
| 25 | + |
| 26 | +Starts a local dev server at `http://localhost:4321/squad/` with hot module reloading. Changes to markdown content, layouts, and components are reflected immediately. |
| 27 | + |
| 28 | +> **Note:** Search does not work in dev mode. Pagefind indexes are only generated during `build`, so the search modal will not return results. Use `build` + `preview` to test search. |
| 29 | +
|
| 30 | +## Build |
| 31 | + |
| 32 | +```bash |
| 33 | +npm run build |
| 34 | +``` |
| 35 | + |
| 36 | +Runs two steps: |
| 37 | + |
| 38 | +1. **`astro build`** — Compiles all pages to static HTML in `dist/` |
| 39 | +2. **`npx pagefind --site dist`** — Indexes the HTML output to generate the search index at `dist/pagefind/` |
| 40 | + |
| 41 | +The output in `dist/` is what gets deployed to GitHub Pages. |
| 42 | + |
| 43 | +## Preview |
| 44 | + |
| 45 | +```bash |
| 46 | +npm run preview |
| 47 | +``` |
| 48 | + |
| 49 | +Serves the `dist/` directory locally so you can verify the production build, including working search. |
| 50 | + |
| 51 | +## Search |
| 52 | + |
| 53 | +Search is powered by [Pagefind](https://pagefind.app/), a static search library that indexes the built HTML. |
| 54 | + |
| 55 | +- **Dev mode:** Search UI appears but returns no results (no index exists). |
| 56 | +- **Build + Preview:** Search works fully. The build step generates the Pagefind index, and preview serves it. |
| 57 | +- **Only pages with `data-pagefind-body`** are indexed. This attribute is set on the `<article>` element in `DocsLayout.astro` and the blog post template. |
| 58 | + |
| 59 | +## Project Structure |
| 60 | + |
| 61 | +``` |
| 62 | +docs/ |
| 63 | +├── astro.config.mjs # Astro configuration (site, base path, plugins) |
| 64 | +├── package.json # Docs-specific dependencies |
| 65 | +├── src/ |
| 66 | +│ ├── components/ # Astro components (Header, Sidebar, Search, etc.) |
| 67 | +│ ├── content/ |
| 68 | +│ │ ├── blog/ # Blog posts (markdown) |
| 69 | +│ │ └── docs/ # Documentation articles (markdown) |
| 70 | +│ │ ├── concepts/ |
| 71 | +│ │ ├── cookbook/ |
| 72 | +│ │ ├── features/ |
| 73 | +│ │ ├── get-started/ |
| 74 | +│ │ ├── guide/ |
| 75 | +│ │ ├── reference/ |
| 76 | +│ │ └── scenarios/ |
| 77 | +│ ├── layouts/ # Page layouts (BaseLayout, DocsLayout) |
| 78 | +│ ├── navigation.ts # Sidebar navigation structure |
| 79 | +│ ├── pages/ # Astro page routes |
| 80 | +│ ├── plugins/ # Remark plugins (link rewriting) |
| 81 | +│ └── styles/ # Global CSS (Tailwind) |
| 82 | +├── public/ # Static assets (images) |
| 83 | +└── dist/ # Build output (gitignored) |
| 84 | +``` |
| 85 | + |
| 86 | +## Adding a Doc Page |
| 87 | + |
| 88 | +1. Create a markdown file under `src/content/docs/{section}/your-page.md` |
| 89 | +2. Add a sidebar entry in `src/navigation.ts` under the appropriate `NAV_SECTIONS` section |
| 90 | +3. Run the docs build test to verify: `npx vitest run test/docs-build.test.ts` (from repo root) |
| 91 | + |
| 92 | +## Adding a Blog Post |
| 93 | + |
| 94 | +Create a markdown file under `src/content/blog/` with frontmatter: |
| 95 | + |
| 96 | +```markdown |
| 97 | +--- |
| 98 | +title: "Your Post Title" |
| 99 | +date: 2026-03-08 |
| 100 | +--- |
| 101 | + |
| 102 | +Post content here. |
| 103 | +``` |
| 104 | + |
| 105 | +Blog posts are automatically discovered and listed on the blog index page. |
0 commit comments