{"_id":"@by-sixteen/project-squad","_rev":"3-5013016a248a46540ed9b5125927a802","name":"@by-sixteen/project-squad","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@by-sixteen/project-squad","version":"1.0.0","keywords":["design-sprint","claude","ai","framework","workshop"],"author":{"name":"By Sixteen"},"license":"MIT","_id":"@by-sixteen/project-squad@1.0.0","maintainers":[{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"}],"homepage":"https://github.com/bysixteen/project-squad#readme","bugs":{"url":"https://github.com/bysixteen/project-squad/issues"},"bin":{"project-squad":"bin/cli.js"},"dist":{"shasum":"745e0d11a5f47cedc0adb1e8d24ebd02aa736e96","tarball":"https://registry.npmjs.org/@by-sixteen/project-squad/-/project-squad-1.0.0.tgz","fileCount":12,"integrity":"sha512-khOEBYO09hrHSi8jMEIGPi7xwEXOHx1zf3JOVLhm5sp9ntZCBI6sNeiHcgNT5rMO+cqcxRjQYtRzWR8HmJpI9g==","signatures":[{"sig":"MEQCIBxZIFkfGKaXG+XS4XBfa33+ZmuJvFic5reDdAoEjDZ8AiAzq0A+TBpudsHj76TK9PcXxCdoYkF1GhdHSBQbncMQtw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":87295},"engines":{"node":">=18.0.0"},"gitHead":"6bf15569c7c07105f590d15203189820f5d56adf","_npmUser":{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"},"repository":{"url":"git+https://github.com/bysixteen/project-squad.git","type":"git"},"_npmVersion":"11.6.2","description":"A portable framework for running structured design sprints, workshops, and technical spikes with Claude","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/project-squad_1.0.0_1772645986270_0.3260299602086427","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@by-sixteen/project-squad","version":"1.1.0","keywords":["design-sprint","claude","ai","framework","workshop"],"author":{"name":"By Sixteen"},"license":"MIT","_id":"@by-sixteen/project-squad@1.1.0","maintainers":[{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"}],"homepage":"https://github.com/bysixteen/project-squad#readme","bugs":{"url":"https://github.com/bysixteen/project-squad/issues"},"bin":{"project-squad":"bin/cli.js"},"dist":{"shasum":"c6b8c1c32a04bc4d2ea1d1a688a79be5c31e9c21","tarball":"https://registry.npmjs.org/@by-sixteen/project-squad/-/project-squad-1.1.0.tgz","fileCount":12,"integrity":"sha512-DaDjBpE7+9gN+bWZXtdkDtWFFmytRj1O3AqhxFktiZkR499kdLGsr6hytud/lBw2K3ZgZTdr7onOf+1FKjfxug==","signatures":[{"sig":"MEQCIHbkfRXOsYHIsHXBa10Dhi8etzQEvyIYR6o7GdjG+4Q9AiB6F4CoamUWsavMr13od/GcJG+21+Fdcn1lXczDZBUavg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106818},"engines":{"node":">=18.0.0"},"_npmUser":{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"},"repository":{"url":"git+https://github.com/bysixteen/project-squad.git","type":"git"},"_npmVersion":"11.6.2","description":"A portable framework for running structured design sprints, workshops, and technical spikes with Claude","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/project-squad_1.1.0_1772655645009_0.213031374331486","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@by-sixteen/project-squad","version":"1.2.0","description":"A portable framework for running structured design sprints, workshops, and technical spikes with Claude","publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"keywords":["design-sprint","claude","ai","framework","workshop"],"author":{"name":"By Sixteen"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bysixteen/project-squad.git"},"bin":{"project-squad":"bin/cli.js"},"engines":{"node":">=18.0.0"},"_id":"@by-sixteen/project-squad@1.2.0","bugs":{"url":"https://github.com/bysixteen/project-squad/issues"},"homepage":"https://github.com/bysixteen/project-squad#readme","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-VZL5gjsZ2oWX6K2pGQuVnHueSDUfb9EetLlCtv1W3zB606tgn7EiOV6DCR/tvwcHpXEP1+M/oQpbuuKzwnKYZQ==","shasum":"6f347057a1fe7f18cf12ffa0ed55b14d474cff89","tarball":"https://registry.npmjs.org/@by-sixteen/project-squad/-/project-squad-1.2.0.tgz","fileCount":14,"unpackedSize":143965,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICYk3elKjPMjaTlTj/hqCxxsLTb5miLwhYl5KHwT+m9kAiEAoYHccQRdKqGo695cYPBL3WswwbNzoe296dXqtBEDfvU="}]},"_npmUser":{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"},"directories":{},"maintainers":[{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/project-squad_1.2.0_1772704911181_0.7846544249350351"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-04T17:39:46.197Z","modified":"2026-03-05T10:01:51.474Z","1.0.0":"2026-03-04T17:39:46.404Z","1.1.0":"2026-03-04T20:20:45.199Z","1.2.0":"2026-03-05T10:01:51.341Z"},"bugs":{"url":"https://github.com/bysixteen/project-squad/issues"},"author":{"name":"By Sixteen"},"license":"MIT","homepage":"https://github.com/bysixteen/project-squad#readme","keywords":["design-sprint","claude","ai","framework","workshop"],"repository":{"type":"git","url":"git+https://github.com/bysixteen/project-squad.git"},"description":"A portable framework for running structured design sprints, workshops, and technical spikes with Claude","maintainers":[{"name":"by-sixteen","email":"daniel@bysixteen.co.uk"}],"readme":"# Project Squad Framework\n\nA portable toolkit for running structured design sprints, workshops, and technical spikes with AI assistance. Built for use with Claude.\n\n---\n\n## What This Is\n\nThe Project Squad Framework is a set of Claude commands, persona definitions, and living document templates that enable any project to run structured, synthesis-friendly sprints and spikes. It is designed to be:\n\n- **Portable** — set up in any project with a single command.\n- **Context-efficient** — every output is structured so an LLM can extract key decisions from the first 20 lines without reading the full document.\n- **Persona-driven** — nine named archetypes provide diverse perspectives and prevent groupthink.\n- **Lift-and-shift ready** — the Portable Toolkit travels unchanged between projects; only the Project Context is project-specific.\n\n---\n\n## Quick Start\n\n### Option A: Copy into an existing project\n\n1. Copy `.squad/` and `.claude/commands/` into your project root.\n2. Open Claude Code in your project directory.\n3. Create `_meta/PROJECT_CONTEXT.md` using `examples/project-context-template.md`.\n4. Run `/init-project-squad` — it reads your context file and scaffolds everything.\n5. If you have existing personas, run `/import-personas` before your first sprint.\n6. Run `/create-sprint` to start Sprint 000 (Foundation).\n\n### Option B: Manual setup\n\n1. Copy `.squad/` and `.claude/commands/` into your project root.\n2. Copy `examples/` contents to the appropriate locations:\n   - `examples/sprints/` → `research/sprints/`\n   - `examples/spikes/` → `research/spikes/`\n   - `examples/decisions/` → `docs/decisions/`\n3. Create the living documents manually (see templates in `init-project-squad.md`).\n\n---\n\n## The Five Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/init-project-squad` | Bootstrap the framework in a new project. Reads `_meta/PROJECT_CONTEXT.md` and scaffolds all living documents. Run once per project. |\n| `/create-sprint` | Run a Full or Lite Design Sprint. Supports Guided Wizard, Paste, and Link input modes. |\n| `/create-workshop` | Run a compressed 2–3 hour sprint for time-pressured decisions. |\n| `/create-spike` | Run a time-boxed investigation to reduce excess uncertainty. Includes a Spike Qualification Test. |\n| `/import-personas` | Import externally-created client personas into `research/PERSONAS.md`. |\n\nNot sure which command to use? See `docs/DECISION-GUIDE.md` for a command comparison, decision flow, and ROI framing.\n\n---\n\n## The File Structure\n\nOnce initialised, your project will have:\n\n```\n_meta/\n└── PROJECT_CONTEXT.md            ← Your project seed (written before init)\n\n.squad/\n└── project-squad.md              ← Portable Constant: 9 persona definitions\n\n.claude/commands/\n├── init-project-squad.md         ← Scaffolding command\n├── create-sprint.md              ← Sprint command\n├── create-workshop.md            ← Workshop command\n├── create-spike.md               ← Spike command\n└── import-personas.md            ← Persona import command\n\nresearch/                         ← Project Context (project-specific)\n├── PRINCIPLES.md                 ← Design & technical principles\n├── PERSONAS.md                   ← Project user personas (client personas live here)\n├── DECISIONS.md                  ← Decision log\n├── sprint-status.md              ← Sprint history\n├── sprint-backlog.md             ← Upcoming sprint candidates\n├── dissent-register.md           ← Dissent log with review triggers\n├── sprints/\n│   └── sprint-NNN-[topic]/\n│       ├── brief.md\n│       ├── sketches.md\n│       ├── decision.md\n│       ├── synthesis.md\n│       └── summary.json          ← Machine-readable summary\n├── workshops/\n│   └── workshop-NNN-[topic]/\n│       ├── workshop.md\n│       └── summary.json          ← Machine-readable summary\n└── spikes/\n    └── spike-NNN-[topic]/\n        ├── brief.md\n        ├── output.md\n        └── summary.json          ← Machine-readable summary\n\ndocs/\n├── decisions/\n│   └── NNN-[topic].md            ← Architecture Decision Records (ADRs)\n└── VALIDATION-BOUNDARY.md        ← Where the framework ends and delivery begins\n```\n\n---\n\n## The Two-Layer Architecture\n\n### Layer 1: Portable Toolkit (project-agnostic)\n\nThe files in `.squad/` and `.claude/commands/` are the portable constant. They travel unchanged between projects. **Do not modify them per-project.**\n\n### Layer 2: Project Context (project-specific)\n\nThe files in `research/` and `docs/decisions/` are project-specific. They start empty (or from templates) and are populated as sprints, workshops, and spikes run.\n\n---\n\n## The Project Squad Personas\n\nNine portable archetypes. They travel unchanged between projects.\n\n| # | Name | Role | Signature Question |\n|---|------|------|-------------------|\n| 1 | Leo Finch | Visual Designer | \"Does this feel like us?\" |\n| 2 | Dr. Lena Petrova | Design Engineer | \"How will we build, test, and maintain this?\" |\n| 3 | Marcus Thorne | Senior Developer | \"What are we NOT building here?\" |\n| 4 | Kira Sharma | Developer | \"What does the implementation actually look like?\" |\n| 5 | Dr. Aris Thorne | Strategist | \"What is the real problem we are trying to solve?\" |\n| 6 | Rowan Vale | Craftsman | \"What is the feeling we want to create?\" |\n| 7 | Elias Vance | Client (External) | \"Does this solve a real problem for my users?\" |\n| 8 | Nara Shin | UX Researcher | \"What does the evidence say?\" |\n| 9 | Ines Alvarez | UX Designer | \"Where will users get stuck?\" |\n\nThe backstory format — role + signature question + motivations, fears, and protective instincts — is what produces consistent, distinctive voice across phases. Most multi-agent frameworks define agents by role and goal only. The added backstory creates a concentrated character model that fits within a single context window pass, giving each persona a stable perspective from Map through Synthesise without drift.\n\nNara Shin (UX Researcher) addresses the user-blindness gap identified in comparable multi-agent frameworks — the tendency to produce technically coherent outputs that no real user would want. Her signature question (\"What does the evidence say?\") is a structural check on the squad's assumptions at every phase. She is not optional.\n\n**The Mandatory Dissent Rule:** Elias Vance must always be included in the Decide phase. His dissent — even if overruled — must be recorded in `research/dissent-register.md` with a review trigger condition.\n\n---\n\n## Client Personas\n\nThe framework distinguishes between two types of personas:\n\n| Type | Location | Purpose |\n|---|---|---|\n| **Project Squad Personas** | `.squad/project-squad.md` | Portable archetypes that *think about* the product. |\n| **Client Personas** | `research/PERSONAS.md` | Real users of *this* product. Project-specific. |\n\nIf you already have research-backed personas, use `/import-personas` rather than recreating them. Elias Vance speaks on behalf of the imported client personas during the Decide phase. See `examples/client-personas-template.md` for the import format.\n\n---\n\n## Workshop Trigger Conditions\n\nUse `/create-workshop` (not `/create-sprint`) when at least two of the following are true:\n\n1. A decision is needed within 24–48 hours.\n2. The team already has a leading option — the workshop stress-tests it.\n3. A stakeholder, client, or deadline is forcing a decision before a full sprint is practical.\n4. The question is well-defined but the team has not formally aligned.\n5. A previous sprint raised a follow-up question that needs a quick answer.\n\n---\n\n## Sprint Input Modes\n\nThe `/create-sprint` command supports four input modes:\n\n| Mode | When to Use |\n|------|------------|\n| **(A) Guided Wizard** | You want structured questions based on Jake Knapp's Monday Questions |\n| **(B) Paste Content** | You have a brief, notes, Slack thread, or document to share |\n| **(C) Link** | You have a URL to a document — Claude fetches and extracts the key inputs |\n| **(D) Revisit** | Re-run a sprint on a topic with prior context; pre-populates fields from the existing brief |\n\n---\n\n## Spike Qualification Test\n\nBefore every spike, the `/create-spike` command runs a three-question test:\n\n1. **Can you confidently estimate the effort?** (If YES → regular task, not a spike)\n2. **Is this uncertainty actively blocking a decision?** (If NO → not urgent enough)\n3. **Is the primary goal knowledge, not a feature?** (If NO → it's a feature, not a spike)\n\n---\n\n## The Validation Boundary\n\nThe framework ends at a decision and a synthesis document. What happens after — prototyping, usability testing, stakeholder review — is a delivery concern. The sprint's acceptance criteria become the validation checklist for whatever is built next.\n\nSee `docs/VALIDATION-BOUNDARY.md` for the full pattern.\n\n---\n\n## Output Synthesis Rules\n\nAll sprint, workshop, and spike outputs follow these rules:\n\n1. YAML frontmatter is mandatory on every file.\n2. TL;DR or Answer is always the first body section.\n3. Tables over prose for structured data.\n4. Appendices below a `---` horizontal rule.\n5. Explicit null values — \"Blockers: None\" not an omitted section.\n6. Past tense for decisions — signals finality.\n7. ADR references inline for significant decisions.\n8. Bidirectional links in frontmatter (`feeds-into`, `depends-on`).\n9. One question per spike.\n10. < 700 lines per file — split if longer.\n\n### The \"First 20 Lines\" Rule\n\nEvery output file is designed so an LLM reading only the first 20 lines can determine relevance, extract the key decision, and know where to find detail.\n\n---\n\n## Deploying to a New Project\n\n### Quick deploy\n\n```bash\n# From your project root\ncp -r /path/to/project-squad/.squad .\nmkdir -p .claude/commands\ncp /path/to/project-squad/.claude/commands/create-sprint.md .claude/commands/\ncp /path/to/project-squad/.claude/commands/create-spike.md .claude/commands/\ncp /path/to/project-squad/.claude/commands/create-workshop.md .claude/commands/\ncp /path/to/project-squad/.claude/commands/import-personas.md .claude/commands/\ncp /path/to/project-squad/.claude/commands/init-project-squad.md .claude/commands/\n```\n\nThen create `_meta/PROJECT_CONTEXT.md` (use `examples/project-context-template.md`) and run `/init-project-squad`.\n\n### What to customise\n\nAfter deploying, the only files you need to customise are:\n\n1. **`_meta/PROJECT_CONTEXT.md`** — Your project seed. The better this is, the better the init output.\n2. **`research/PERSONAS.md`** — Add your project's user personas, or use `/import-personas`.\n3. **`research/PRINCIPLES.md`** — Add your project's design and technical principles.\n4. **`research/DECISIONS.md`** — Add any existing technical decisions.\n\nThe first sprint should always be Sprint 000 (Foundation) to establish the baseline context.\n\n---\n\n## References\n\n- [The Sprint Book — Jake Knapp](https://www.thesprintbook.com/the-design-sprint)\n- [Spikes — Mountain Goat Software](https://www.mountaingoatsoftware.com/blog/spikes)\n- [Live Documentation Site](https://bysixteen.github.io/project-squad/)\n","readmeFilename":"README.md"}