Contributing to Star Trek: Syndicate

Garak, handing over a file with no markings

"The best operatives don't need to be told what to do. They need to be told what the job is. Then they figure out the rest themselves."

This guide shows you how to contribute content to Star Trek: Syndicate so that your work lands in the right place, fits the project's voice, and clears review without friction.

When to use this: Before writing a single word of new content — or when you're unsure where something belongs.
You will need: A text editor, a GitHub account, and a working copy of the repository.
Time required: Read this once before your first contribution. Refer back to the Compass Rule every time after that.

Fan work — no commercial use

Star Trek: Syndicate is a fan supplement. All Star Trek IP belongs to Paramount Global. Modiphius Entertainment holds the STA RPG license. This project is not affiliated with or endorsed by either. All contributions must remain non-commercial and within fan-work norms.

1. Check the Implementation Plan

Before starting anything, read implementation-plan.md. It lists current priorities by phase and flags what's blocked, in progress, or open.

Picking up a task that's already in progress wastes both your time and a reviewer's. If a task has no assignee, claim it by opening an issue or dropping a note in the relevant PR.

If the implementation plan has no current task that fits what you want to write, raise it as an issue first. Unsolicited content that doesn't align with current priorities may not be merged.

2. Decide Where Your Content Belongs — The Compass Rule

This project uses the Diátaxis framework with Syndicate-flavoured quadrant names. Every piece of content belongs in exactly one quadrant. Getting this wrong is the most common reason content gets sent back in review.

Ask two questions:

Action or Cognition? — Does this show how to do something, or describe what is true?
Acquisition or Application? — Is the reader learning a new skill, or using an existing skill to get a job done?

	Acquisition (learning)	Application (working)
Action (doing)	→ The Induction	→ The Playbook
Cognition (knowing)	→ The Briefing Room	→ The Dossier

If your content answers both "how do I do this?" and "what is the complete specification?", it belongs in two separate documents — a Playbook guide that links to a Dossier entry. Write them separately.

3. Know Your Quadrants

Syndicate Name	Diátaxis Type	Directory	Tagline
The Induction	Tutorial	`docs/the-induction/`	Learn the trade by working the trade.
The Playbook	How-to Guide	`docs/the-playbook/`	Step-by-step plays for every job.
The Dossier	Reference	`docs/the-dossier/`	Accurate intel wins jobs. Bad intel gets you killed.
The Briefing Room	Explanation	`docs/the-briefing-room/`	Before you can work the angles, you need to understand the table.

The Induction — Tutorial

For readers encountering the system for the first time. Structured as a single linear path — one task, one outcome, no branching. Write in "we" voice. The reader should be able to follow along without stopping to make decisions. No design rationale, no complete reference lists — just enough to get through the first job.

Write here if: You're guiding a first-time player through character creation, their first Heat check, or their first Favor Bank transaction.

The Playbook — How-to Guide

For competent readers who know what they want to accomplish. Starts with the goal, ends when the job is done. Allows for branches. Links to The Dossier for all mechanical data — never reproduces it inline. Title every guide in "How to..." form.

Write here if: You're writing step-by-step procedures for running an operation, managing campaign mechanics, or handling specific scene types.

The Dossier — Reference

For readers who need accurate, complete data at the table or during prep. No instruction, no rationale, no prose padding. Every stat, threshold, table, and mechanic definition lives here. Structure is rigid and consistent — use the established entry format for the content type.

Write here if: You're defining a mechanic, writing a stat block, building a faction entry, or documenting a canonical rule.

Canonical mechanics

The following mechanics have canonical Dossier entries. Never redefine them in passing — always link to their entry:

Heat → the-dossier/mechanics/heat.md
Reputation → the-dossier/mechanics/reputation.md
Flair, Contacts, and The Favor Bank — entries in progress; link once available.

The Briefing Room — Explanation

For readers who want to understand why — design rationale, setting context, tone guidance, thematic framing. Discursive but bounded to a single topic. Does not instruct; does not define. Links out to The Playbook for procedures and The Dossier for definitions.

Write here if: You're explaining why a mechanic works the way it does, discussing the thematic intent of a Flair, or unpacking the project's approach to moral complexity.

4. Use the Right Agent

This project has four AI writing agents matched one-to-one with the quadrants. Using the wrong agent for your quadrant produces content that fails the tone and structure requirements. Don't improvise.

You are writing…	Use this agent	Key rule
A tutorial (learn by doing)	`Induction Writer`	Walk one line. No choices. Use "we".
A task guide (how to accomplish X)	`Playbook Writer`	Goal first. Link to Dossier for data. Allow branches.
A mechanic, NPC, or stat block	`Dossier Writer`	Dry, complete, consistent structure. No instruction.
Design rationale, setting context, "why" content	`Briefing Room Writer`	Discursive. Topic-bounded. Link out rather than reproduce.

Agents are defined in .github/agents/ and are invoked via GitHub Copilot in agent mode. Open Copilot Chat, select the relevant agent from the dropdown (or @agent-name), and provide your content goal. The agent will ask clarifying questions before writing.

Agent mode vs. ask mode

Use agent mode (with the agent selected) when you are generating new content. Use ask mode when you want to discuss placement, check against the Compass Rule, or troubleshoot tone.

5. Create Your File

Create your file in the correct directory for its quadrant. Use lowercase, hyphenated filenames matching the format of existing files.

Every new page must:

Begin with a single # Heading 1 (the page title)
Open with a flavour quote (!!! quote) if it is a guide or explanation
State its goal or purpose in the first body paragraph — no preamble, no throat-clearing
Cross-reference rather than reproduce: if a step requires mechanical data, link to The Dossier
Never repeat STA 2e rules verbatim — reference them with 📖 **See STA Core Rulebook, Chapter X**

New mechanic or system?

If you're introducing a new mechanic, write the Dossier entry first. Then write any Playbook or Induction content that references it. Playbook guides that reference undefined mechanics will be held in review.

6. Run the Tone Checklist

Before opening a PR, read your content against this checklist. Issues caught here take seconds to fix. Issues caught in review take days.

Voice — Required

Check	Criterion
☐	Titles use "How to..." form (Playbook) or a noun phrase (Dossier/Briefing Room)
☐	First paragraph states the goal or subject without preamble
☐	Sentences are direct: subject + verb + object
☐	Action steps use imperative voice: "Increment the Heat track" not "The Heat track should be incremented"
☐	No Starfleet idealism presented as the default moral baseline
☐	No "boldly goes", "make it so", or TNG-era phrases used un-ironically

Structure — Required

Check	Criterion
☐	Content belongs in exactly one quadrant — confirmed by the Compass Rule
☐	Mechanical data links to The Dossier rather than being reproduced inline
☐	STA 2e rules are referenced, not repeated
☐	Canonical mechanic names are used exactly: Heat, Reputation, Flair, Contacts, The Favor Bank
☐	Tables used for structured comparisons; numbered lists used for sequential steps only

Prohibited — None of These

Padding phrases: "In this section, we will cover...", "As you can see...", "It is important to note..."
Moralising at players about their characters' choices
Exhaustive option lists that belong in The Dossier
Background explanation inline in a Playbook guide (link to The Briefing Room instead)
Tutorial content mixed into a reference entry

7. Submit a Pull Request

Push your branch and open a PR against main.
Give the PR a title in the form: [Quadrant] Title of content — for example, [Playbook] How to track Heat during an operation.
In the PR description, answer three questions:
- What quadrant is this? (Confirmed by the Compass Rule)
- What user goal or query does this serve?
- What existing content does it link to or replace?
If the content replaces or consolidates something from docs/core-rules/, identify the source file and section.

8. What Reviewers Look For

Review focuses on four things, in this order:

Priority	Check	Why it matters
1	Correct quadrant placement	Wrong quadrant means the content is unreachable to the reader who needs it
2	Tone compliance	Voice drift is contagious — one off-tone page pulls the whole section down
3	No STA rule duplication	Legal and practical: repeat verbatim content creates maintenance burden and IP risk
4	Proper cross-references	Broken or missing links undermine The Dossier as the canonical source of truth

Reviewers will not comment on stylistic preferences beyond what the tone guide specifies. If your content passes all four checks, it merges.

First contribution?

Pick a task marked good first contribution in the implementation plan. These are scoped, well-defined, and have clear acceptance criteria. Avoid tackling mechanic consolidation tasks (Phase 1) until you have at least one merged contribution — those tasks require cross-chapter context that takes time to build.

Common Complications

If this happens…	Do this
Content spans two quadrants (procedural and explanatory)	Split it. One Playbook guide + one Briefing Room entry. Link between them.
A mechanic doesn't have a Dossier entry yet	Write the Dossier entry first, then reference it. Flag in your PR that the Dossier entry is new.
You're not sure which Flair a piece of content belongs under	Leave it quadrant-generic. Flair-specific content can be tagged later once the Flair system is fully migrated.
The implementation plan doesn't mention your content type	Open an issue before writing. Don't guess at priority.
A core-rules chapter already covers the topic	Check Phase 2/3 of the implementation plan. The chapter may be scheduled for migration. Coordinate rather than duplicate.