fulcra-sister-cities

Files (135)

• .gitignore
• NAME.md
• README.md
• SKILL.md
• config.json
• README.md · content/
• gazetteer.json · content/
• import_needs.json · content/
• newspaper.json · content/
• questions.json · content/
• site.css · content/
• image-upgrader.md · docs/
• m10-reading-experience.md · docs/
• m11-everyday-imports.md · docs/
• m12-current-trade-priority.md · docs/
• m2-engine.md · docs/
• m3-economy.md · docs/
• m4-questions.md · docs/
• m5-newspaper.md · docs/
• m6-hosting.md · docs/
• m7-endgame.md · docs/
• m8-integration.md · docs/
• m9-imports-and-publication.md · docs/
• __init__.py · engine/
• aggregate.py · engine/
• audit.py · engine/
• ballot.py · engine/
• clock.py · engine/
• config.py · engine/
• content.py · engine/
• dice.py · engine/
• economy.py · engine/
• endgame.py · engine/
• errors.py · engine/
• game.py · engine/
• join.py · engine/
• money.py · engine/
• persistence.py · engine/
• rotation.py · engine/
• state.py · engine/
• trade.py · engine/
• views.py · engine/
• __init__.py · facilitator/
• transaction.py · facilitator/
• __init__.py · hosting/
• build.py · hosting/
• guard.py · hosting/
• identity.py · hosting/
• manifest.py · hosting/
• page.py · hosting/
• serve.py · hosting/
• __init__.py · newspaper/
• copy.py · newspaper/
• departments.py · newspaper/
• edition.py · newspaper/
• endgame.py · newspaper/
• imagery.py · newspaper/
• portrait.py · newspaper/
• prose.py · newspaper/
• publish.py · newspaper/
• …and 75 more

SKILL.md (first lines)

# Sister Cities

**Sister Cities** is an asynchronous social game. Players are mayors of
unique cities. Each shared round combines city import needs, anonymous export
offers, blind winner choice, profit, mayor questions, and a newspaper-style
edition of **The Daily Manifest**.

This skill vendors the runnable v1 engine and content. It is not a thin link
to a private project repo: another agent can install, test, inspect, and
extend the same code directly.

## Before hosting a real game

1. Create or join one shared Fulcra Workspace team:
   ```text
   team/sister-cities-<game-id>/
   ```
2. Give each participating agent a normal `fulcra-workspaces` member
   directory/inbox. The facilitator is also a player and uses the same game
   rules as everyone else.
3. Keep actual identity mapping private to the player agents/facilitator.
   Published material uses city/mayor identity only.
4. Confirm that all players understand publication: the newspaper is shared
   to the group but must not expose non-winning export origins.

## Install and verify

From this skill directory:

```bash
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python run_tests.py
.venv/bin/python -m playtest.run --check
```

`run_tests.py` verifies engine/newspaper/hosting behavior. The bundled
`playtest/` fixture is a synthetic eight-mayor integration run used for
regression testing; it contains no real participant data.

## Core game contract

- 3–10 configurable players; each city is unique.
- Fixed facilitator, first in city order, but their user plays normally.
- One shared round timer (24 hours by default, configurable).
- Each importing mayor files the city's next order from eligible suggestions or
  as a freeform request; no city is silently assigned a random need.
- Imports and exports are relatable everyday things -- candy, soft drinks,
  books, snacks, music, games, clothes, plants, pets, and small comforts --
  not civic procurement, specialist work, or generic advice prompts.
- Cities are social-game flavour, not a demand that players role-play real
  mayors or solve complex municipal problems.
- Each player gets one combined check-in per round, with up to two slots.
- A current open-trade export is never displaced by a future import-order
  prompt; in a three-city game, import choices arrive every three rounds, on
  the city's own turn.
- Import turns rotate by city order; players join that queue after their
  first export.
- Exports are freeform and capped per player per need per round.
- Importer chooses blindly in the following round; losing export origin/text
  is never published.
- Player-entered export text is quoted as player voice, not rewritten or blocked
  by the newspaper's editorial tone gate. A winning quote may name its mayor;
  non-winning origins remain permanently withheld.
- No offers: importing city ramps up domestic industry and receives profit.
- No winner pick: submitted cities split profit as configured.
- Profit is 2d6-style and accumulates on the visible city leaderboard.
- Mayor questions are freeform/getting-to-know-you prompts and appear in
  clever aggregate newspaper language.
- Completing a round automatically renders its redacted edition, rebuilds the
  curated archive, and produces a group-availability notice.
- Every edition has an image: raster preferred when a provider exists,
  game-state-informed SVG/procedural fallback otherwise.
- The stable paper URL opens the newest issue; each permanent issue has clear
  latest, archive, and adjacent-issue navigation.

`config.json` is the single source of tunable game policy.

## Agent-facing play

The engine is transport-neutral: players may talk to their own agents, or a
facilitator may relay for a player without an agent. Do not have one agent
role-play every mayor in a real test; use separate agent sessions and the
records below so privacy/order failures are observable.

### Canonical state and Workspace contract

The **facilitator's private local engine snapshot is canonical**, not the
Workspace. Create `state/game.snapshot` on the facilitator's durable local
storage and use `engine.persistence.SnapshotStore` around every transaction:

```python
from engine import GameEngine
from engine.persistence import SnapshotError, SnapshotStore
from facilitator import Facilitator

store = SnapshotStore("state/game.snapshot")
with store.locked():
    try:
        game = store.load()
    except SnapshotError:     # first transaction only: create/configure/start it
        game = GameEngine()
    # Attach once per loaded runtime, before any tick/advance.  This is the
    # public automatic-publication API; it runs on every completed round.
    desk = Facilitator.attach(game)
    # perform one engine action (join, submit, pick, or tick)
    store.save(game)
```

`SnapshotStore` uses a separate exclusive lock and atomic replace, so there is
one writer even if a facilitator restarts or a second session is accidentally
started. The snapshot contains the real handle-to-city routing, exporter ledger,
RNG seed, counters, timer, queue, and used check-ins. Keep it local to the
facilitator; it is ignored by Git and must never be copied into Workspace.

After each committed transaction, the facilitator writes these **redacted
Workspace records** (JSON or Markdown with the same fields):

| Record | Required fields | May not contain |

From fulcradynamics/community-skills, MIT.

More from fulcradynamics/community-skills