From 9b56e974a1c8aab3090cb6d59915fe90b4fa097b Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 16 Apr 2026 12:26:32 -0500 Subject: [PATCH 1/4] Closes #986: emphasize human-led productivity in docs Reframe the docs landing page and README around human-led productivity, strengthen the responsible AI callouts and feature messaging, and fix the garbled docs search UI text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 22 ++-- docs/src/components/Search.astro | 22 ++-- docs/src/pages/index.astro | 179 ++++++++++++++++--------------- test/docs-build.test.ts | 1 + 4 files changed, 118 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index 78136d05c..95c88cc5e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [English](README.md) | [中文](README.zh.md) -**AI agent teams for any project.** One command. A team that grows with your code. +**Human-led AI agent teams for any project.** One command. A team that helps you move faster with your code. [![Status](https://img.shields.io/badge/status-alpha-blueviolet)](#status) [![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad) @@ -13,9 +13,13 @@ ## What is Squad? -Squad gives you an AI development team through GitHub Copilot. Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and get better the more you use them. +Squad gives you a human-directed AI development team through GitHub Copilot. Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and help you move faster without giving up oversight. -It's not a chatbot wearing hats. Each team member runs in its own context, reads only its own knowledge, and writes back what it learned. +Squad is a productivity tool for humans, not a replacement for engineers, reviewers, or decision-makers. People stay accountable for priorities, approvals, and final changes; Squad helps with coordination, repetition, and parallel execution. + +It's not a chatbot wearing hats. Each team member runs in its own context, reads only its own knowledge, and writes back what it learned so the work stays inspectable. + +> **Responsible AI stance** — Squad is built to amplify a human operator with GitHub Copilot, not to remove humans from the loop. Use it to delegate faster, review better, and keep governance close to the code. --- @@ -117,9 +121,9 @@ Use `--force` to re-apply updates even when your installed version already match --- -## Watch Mode — Ralph's Autonomous Polling +## Watch Mode — Ralph's Automated Polling -Ralph continuously polls for work and dispatches agents to handle it. Watch mode is perfect for unmanned squad operations — let agents work while you're away. +Ralph continuously polls for work and dispatches agents to handle it. Watch mode helps a human team stay responsive — Ralph automates triage, execution handoffs, and monitoring, then escalates back to people when judgment or approval is needed. ### Quick Start @@ -171,7 +175,7 @@ Ralph uses an **agent-delegated selection pattern**: 5. The agent **decides which issue to work on** and **how** 6. Ralph monitors execution, logs results, updates issue status -This design gives **agents full autonomy** over issue selection while keeping the polling loop lean. +This design keeps the polling loop lean while letting agents handle issue selection automatically under the team's rules, review gates, and escalation policy. ### Issue Selection & Escalation @@ -339,9 +343,9 @@ Eight working examples from beginner to advanced — casting, governance, stream --- -## Agents Work in Parallel— You Catch Up When You're Ready +## Agents Work in Parallel — You Stay in Control -Squad doesn't work on a human schedule. When you give a task, the coordinator launches every agent that can usefully start — simultaneously. +Squad helps one human coordinate more work at once. When you give a task, the coordinator launches every agent that can usefully start — simultaneously — while you keep priorities, review, and final decisions. ``` You: "Team, build the login page" @@ -353,7 +357,7 @@ You: "Team, build the login page" 📋 Scribe — logging everything... ⎦ ``` -When agents finish, the coordinator immediately chains follow-up work. If you step away, a breadcrumb trail is waiting when you get back: +When agents finish, the coordinator records follow-up work and leaves a breadcrumb trail so you can review what happened with full context: - **`decisions.md`** — every decision any agent made - **`orchestration-log/`** — what was spawned, why, and what happened diff --git a/docs/src/components/Search.astro b/docs/src/components/Search.astro index c2ec77cc7..dde08a210 100644 --- a/docs/src/components/Search.astro +++ b/docs/src/components/Search.astro @@ -11,9 +11,9 @@ const base = import.meta.env.BASE_URL; - + @@ -30,7 +30,7 @@ const base = import.meta.env.BASE_URL; @@ -39,7 +39,7 @@ const base = import.meta.env.BASE_URL;
- Start typing to search… + Start typing to search...
@@ -48,7 +48,7 @@ const base = import.meta.env.BASE_URL;