Team playbook — MMS (Linkly MMS)¶
Vietnamese: Sổ tay team (tiếng Việt)
Context: How the MMS team uses this Obsidian vault together with GitLab, Figma, and OpenProject. Read this once when joining; owners keep it current.
Owners: Martin, Loi Truong
What each tool is for¶
| Tool | Role | MMS link |
|---|---|---|
| This vault | Durable knowledge: specs, ADRs, meetings, features, traceability to raw/ PDFs |
projects/mms/ |
| OpenProject | Day-to-day work: tasks, assignee, due dates, sprint flow | MMS project |
| GitLab BE | Backend code, MRs, CI | cloudbanking |
| GitLab FE | Frontend code, MRs, CI | mms-fe |
| Figma | UI/UX source of truth for screens | Linkly MMS |
| Slack / chat | Fast coordination only — not the system of record | — |
Rule of thumb: If someone asks “why did we build it this way?” six months from now, the answer should live in the vault (spec + ADR + links). If they ask “who is doing what this week?”, use OpenProject.
Two iron rules (non-negotiable)¶
- Never edit
raw/. Drop originals inraw/specs/,raw/designs/,raw/meetings/,raw/emails/. Wrong file? Add a correction page in the processed folder; do not change the original. - Always update
index.mdandlog.mdafter adding, renaming, or removing a wiki page (project + vault root if cross-project).
Full vault rules: AGENTS.md / CLAUDE.md.
Folder map (MMS)¶
projects/mms/
├── README.md ← landing page, key links
├── team-playbook.md ← English (this file)
├── team-playbook-vi.md ← Vietnamese
├── index.md ← table of contents (keep current)
├── log.md ← project change log
├── raw/ ← immutable sources only
├── specs/ ← processed specs (one page per source)
├── designs/ ← design notes → Figma / raw exports
├── meetings/ ← cleaned meeting notes
├── decisions/ ← ADRs
├── features/ ← one page per feature
├── bugs/ ← one page per bug
└── dev-notes/ ← spikes, journals, technical notes
Cross-project standards (EMV, PCI, shared vendor docs): _shared/ — not under mms/ unless MMS-only.
Team Lead flow (customer request → delivery)¶
Role: Dung Pham (Team Lead) — receives requirements, defines scope, creates tasks, signs off ship. Project owners: Martin, Loi Truong.
1. Receive customer (client) input¶
| Step | Action | Where |
|---|---|---|
| 1 | Receive PDF / email / brief from client | Outside vault |
| 2 | Drop immutable source | raw/specs/ (or raw/meetings/, raw/emails/) |
| 3 | Ingest / summarize | specs/<slug>.md + PDF page refs |
| 4 | Internal meeting + decisions | meetings/YYYY-MM-DD-<topic>.md |
Outcome: team understands what the client wants (spec + meeting).
2. Break down into features (wiki = product source of truth)¶
| Step | Action | Where |
|---|---|---|
| 1 | Map request → existing or new feature | features/<slug>.md (one file per capability) |
| 2 | Write Why, What, Out of scope | Same feature file |
| 3 | Split AC: Product (E2E) + Frontend + Backend + Done together | feature template |
| 4 | Assign people when known | assignees.fe / be / qa → [[_people/...]] |
| 5 | Set release when applicable | target_release: |
| 6 | Update index | index + log for major changes |
Outcome: one page everyone reads for scope and done criteria.
3. Create OpenProject work packages (parent / children)¶
Parent (Epic / Feature WP)
Wiki: projects/mms/features/<slug>.md
Version: MMS-2026.06-R1 (when using releases)
├── Child FE → FE assignee (e.g. Loc Le)
├── Child BE → BE assignee (e.g. Vu Nguyen)
└── Child QA → QA assignee (e.g. Hao Le) (optional)
Each child description:
Do not create separate features/fe-* and features/be-* wiki pages — one feature page, multiple OP tasks.
4. Day-to-day / sprint (Team Lead)¶
- Standup by wiki feature name, not isolated MRs.
- Review MRs: wiki link + correct FE/BE layer.
- Client scope change → update feature/spec (processed), not
raw/; adjust OP tasks; log in log. - Ship → tick Product + Done together AC; close parent + children; update feature
status:.
Lead cheat line: raw → spec/feature → OP (parent + FE/BE/QA) → assign → review MR → E2E → shipped + log
Developer flow (team members)¶
Audience: Fullstack (Duc, An, Phat), FE (Loc), BE (Vu), QA (Hao).
One line: OP → read wiki → code (app MR) → update wiki (mmswiki PR) → close OP
Rule: One feature = one file features/<slug>.md. Your OP task = one layer (FE / BE / QA). No separate fe-* / be-* wiki pages.
Steps (per task)¶
| # | Step | Do |
|---|---|---|
| 1 | Pick up | Open child OP → read Wiki: projects/mms/features/<slug>.md + Layer: FE / BE / QA |
| 2 | Read wiki | Why/What (do not edit). Your layer AC. Delivery map / Figma |
| 3 | Coordinate | FE↔BE API contract if needed; disputes → Team Lead |
| 4 | Code | MR on mms-fe (FE) or cloudbanking (BE). Body: Wiki: … + OP: #id |
| 5 | Wiki PR | Branch mms/wiki-<slug>-fe-<desc> (or -be-) → edit feature → MR on mmswiki → reviewer Lead |
| 6 | Close OP | Staging OK + app MR merged + wiki PR merged → close child task |
Wiki PR — edit only: your Frontend / Backend AC, Delivery map, Open questions; add dev-notes/ / bugs/ / _glossary/ when needed.
Wiki — do not edit (ping Lead): Why/What/Out of scope, Product & Done together AC, status: shipped, another layer’s AC, raw/, index.md, log.md.
cd mmswiki && git pull origin develop
git checkout -b mms/wiki-<slug>-fe-<desc>
# edit projects/mms/features/<slug>.md
git commit -m "mms: <slug> — tick FE AC, add route …"
git push -u origin HEAD # MR → develop → reviewer: Team Lead
Fullstack: may do FE+BE — still two OP tasks (or team agrees on one); one wiki file.
Quick comparison: Lead vs Dev¶
| Team Lead | Developer | |
|---|---|---|
| Input | Client reqs, priority, release | OP task + feature wiki |
| Wiki | Create/edit features, specs, meetings; review wiki PRs | Read + edit layer AC / Delivery map; PR to mmswiki |
| OpenProject | Parent + FE/BE/QA, assignees, version | Execute & close child tasks |
| GitLab | Review MRs | MRs with wiki/OP links |
| “Feature done” | Product AC + E2E + shipped |
Layer AC complete |
Example: new change on Bulk Changes¶
- Lead: Client asks for new filter → update
features/bulk-changes.md(FE/BE AC) → OP parent + FE task (Loc) + BE task (Vu). - FE dev: Read wiki → Figma → MR on
mms-fe+ wiki PR onmmswiki(tick FE AC, routes) → close FE task. - BE dev: API → MR on
cloudbanking+ wiki PR onmmswiki(tick BE AC, endpoints) → close BE task. - Lead / QA: E2E on staging → tick Product AC → close parent → log.
Rituals¶
After every significant meeting¶
- Save recording/transcript to
raw/meetings/(if you have one). - Create
meetings/YYYY-MM-DD-<topic>.mdfrom meeting template. - List decisions and action items with owners and due dates.
- If architecture changed → new ADR in
decisions/and link from the meeting note. - Add a row to index and an entry in log.
Rotating scribe: agree in standup who writes the note within 24h.
New client spec, RFP, or formal PDF¶
- Drop file in
raw/specs/(keep original filename when possible). - Ask the assistant: “Ingest
projects/mms/raw/specs/<file>.pdf” — review the proposal before confirming. - Processed page lands in
specs/with PDF page numbers in frontmatter and under the H1. - Create or update
features/pages for impacted scope; link both ways.
New Figma scope or export¶
- Export or link evidence in
raw/designs/. - Processed note in
designs/referencing Figma frame(s) and design-review template if useful. - Link related
features/.
Architecture or product decision¶
decisions/<slug>.mdfrom decision template.status:proposed→ team review →acceptedorrejected.- Link from affected
features/,specs/, and OpenProject tickets.
Shipping a feature¶
- Update
features/<slug>.md→status: shipped(and status history). - Log in log.
- OpenProject tickets closed; MRs merged in GitLab BE/FE.
Bugs¶
- OpenProject — reproduction, assignee, fix verification.
- Vault
bugs/— use when the bug needs a durable write-up (regression, spec mismatch, cross-team RCA). Link feature/spec/ADR.
OpenProject ↔ vault linking¶
On every non-trivial OpenProject work package, add in the description:
Paths are Obsidian wiki-links from the vault root perspective; in plain text for non-Obsidian users, paste the relative path: projects/mms/features/<slug>.md.
Do not paste entire specs into OpenProject — link to the vault page instead.
Git workflow (vault repo)¶
git pullbefore you start.- Small commits with clear messages, e.g.
mms: ingest merchant-onboarding spec,mms: ADR-002 api versioning. - Prefer one person per ingest batch to avoid
index.md/log.mdconflicts. - Open a MR/PR when your team uses review for docs (recommended for large ingests).
Large PDFs: agree as a team whether all binaries live in Git or only “official” versions (avoid committing duplicate drafts).
Working with the AI assistant¶
Good prompts
- Ingest
projects/mms/raw/specs/foo.pdf - Create feature
merchant-onboardinglinked to spec X and Figma; acceptance criteria from pages 12–18 - Summarize decisions from the last three meetings about settlements
- What pages link to
[[merchant-onboarding]]?
Assistant will
- Propose placement before writing (ingest workflow).
- Maintain
index.mdandlog.md. - Ask when categorization is unclear.
You must
- Review ingested requirements against the PDF.
- Confirm before large multi-page splits.
Naming and status¶
- Filenames:
lowercase-hyphenated.md - Meetings:
YYYY-MM-DD-<topic>.md - Status values: only those in AGENTS.md (e.g. feature
proposed→shipped, specdraft→approved) - People: _people/ —
first-last.md(e.g.loi-truong.md)
New member checklist¶
- [ ] Open vault in Obsidian; enable
[[wikilinks]], Templates →_templates/ - [ ] Read README, this playbook, and log (last 10 entries)
- [ ] Get access: GitLab BE/FE, Figma, OpenProject MMS, vault Git remote
- [ ] Skim index for active specs and features
- [ ] Join standup; know who is scribe this week
Anti-patterns¶
- Editing files under
raw/ - Decisions only in Slack, never in
meetings/ordecisions/ - Duplicate spec text in OpenProject instead of vault links
- Feature
status:in vault contradicting reality with no log entry - Creating pages without updating index or log