fulcra-sister-cities
Run or facilitate Sister Cities, an asynchronous city-trade social game for 3–10 players. Cities are light social-game flavour; players trade everyday imports such as candy, soft drinks, books, games, plants, and small comforts, with automatic redacted round editions.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 3
- Forks
- 6
01 前言 Front Matter
- name
- fulcra-sister-cities
- license
- MIT
- homepage
- https://github.com/fulcradynamics/community-skills
- metadata
- { "openclaw": { "emoji": "🏙️" } }
- description
- Run or facilitate Sister Cities, an asynchronous city-trade social game for 3–10 players. Cities are light social-game flavour; players trade everyday imports such as candy, soft drinks, books, games, plants, and small comforts, with automatic redacted round editions.
- user-invocable
- true
02 资源文件 134
- 其他.gitignore754 B
- 参考文档config.json19.8 KB
- 参考文档content/gazetteer.json35.5 KB
- 参考文档content/import_needs.json56.4 KB
- 参考文档content/newspaper.json62.6 KB
- 参考文档content/questions.json36.3 KB
- 参考文档content/README.md13.8 KB
- 其他content/site.css16.8 KB
- 参考文档docs/image-upgrader.md3.7 KB
- 参考文档docs/m10-reading-experience.md11.0 KB
- 参考文档docs/m11-everyday-imports.md15.0 KB
- 参考文档docs/m12-current-trade-priority.md7.5 KB
- 参考文档docs/m2-engine.md11.1 KB
- 参考文档docs/m3-economy.md6.0 KB
- 参考文档docs/m4-questions.md8.9 KB
- 参考文档docs/m5-newspaper.md10.6 KB
- 参考文档docs/m6-hosting.md10.4 KB
- 参考文档docs/m7-endgame.md11.6 KB
- 参考文档docs/m8-integration.md13.0 KB
- 参考文档docs/m9-imports-and-publication.md13.4 KB
- 脚本engine/__init__.py2.2 KB
- 脚本engine/aggregate.py28.6 KB
- 脚本engine/audit.py12.5 KB
- 脚本engine/ballot.py2.1 KB
- 脚本engine/clock.py3.2 KB
- 脚本engine/config.py4.7 KB
- 脚本engine/content.py15.8 KB
- 脚本engine/dice.py1.7 KB
- 脚本engine/economy.py9.9 KB
- 脚本engine/endgame.py19.4 KB
- 脚本engine/errors.py4.9 KB
- 脚本engine/game.py75.7 KB
- 脚本engine/join.py15.3 KB
- 脚本engine/money.py2.4 KB
- 脚本engine/persistence.py3.6 KB
- 脚本engine/rotation.py9.7 KB
- 脚本engine/state.py9.7 KB
- 脚本engine/trade.py15.1 KB
- 脚本engine/views.py15.6 KB
- 脚本facilitator/__init__.py3.0 KB
- 脚本facilitator/transaction.py12.7 KB
- 脚本hosting/__init__.py2.1 KB
- 脚本hosting/build.py26.5 KB
- 脚本hosting/guard.py12.2 KB
- 脚本hosting/identity.py10.0 KB
- 脚本hosting/manifest.py10.6 KB
- 脚本hosting/page.py29.4 KB
- 脚本hosting/serve.py7.7 KB
- 参考文档NAME.md5.2 KB
- 脚本newspaper/__init__.py3.1 KB
- 脚本newspaper/copy.py18.4 KB
- 脚本newspaper/departments.py28.4 KB
- 脚本newspaper/edition.py18.8 KB
- 脚本newspaper/endgame.py41.2 KB
- 脚本newspaper/imagery.py9.4 KB
- 脚本newspaper/portrait.py14.6 KB
- 脚本newspaper/prose.py3.7 KB
- 脚本newspaper/publish.py11.5 KB
- 脚本newspaper/redact.py11.8 KB
- 脚本newspaper/render.py9.1 KB
- 脚本newspaper/sample.py21.6 KB
- 脚本newspaper/svg.py17.9 KB
- 脚本newspaper/tone.py7.0 KB
- 脚本newspaper/voice.py7.5 KB
- 脚本newspaper/wire.py16.5 KB
- 脚本playtest/__init__.py1.4 KB
- 参考文档playtest/_agent/ballots-m-bel.json9.7 KB
- 参考文档playtest/_agent/ballots-m-hbt.json9.6 KB
- 参考文档playtest/_agent/ballots-m-kmp.json10.1 KB
- 参考文档playtest/_agent/ballots-m-kop.json5.9 KB
- 参考文档playtest/_agent/ballots-m-nao.json6.5 KB
- 参考文档playtest/_agent/ballots-m-rvk.json8.4 KB
- 参考文档playtest/_agent/ballots-m-tri.json6.0 KB
- 参考文档playtest/_agent/ballots-m-vlp.json7.6 KB
- 参考文档playtest/_agent/clusters.json3.8 KB
- 参考文档playtest/_agent/m-bel.json6.9 KB
- 参考文档playtest/_agent/m-hbt.json6.5 KB
- 参考文档playtest/_agent/m-kmp.json6.5 KB
- 参考文档playtest/_agent/m-kop.json6.6 KB
- 参考文档playtest/_agent/m-nao.json2.9 KB
- 参考文档playtest/_agent/m-rvk.json7.7 KB
- 参考文档playtest/_agent/m-tri.json3.4 KB
- 参考文档playtest/_agent/m-vlp.json9.2 KB
- 参考文档playtest/_agent/picks-m-bel.json744 B
- 参考文档playtest/_agent/picks-m-hbt.json706 B
- 参考文档playtest/_agent/picks-m-kmp.json637 B
- 参考文档playtest/_agent/picks-m-kop.json550 B
- 参考文档playtest/_agent/picks-m-nao.json337 B
- 参考文档playtest/_agent/picks-m-rvk.json838 B
- 参考文档playtest/_agent/picks-m-tri.json387 B
- 参考文档playtest/_agent/picks-m-vlp.json647 B
- 参考文档playtest/_agent/questions.json21.5 KB
- 参考文档playtest/_briefs/m-bel.json10.2 KB
- 参考文档playtest/_briefs/m-hbt.json11.9 KB
- 参考文档playtest/_briefs/m-kmp.json11.6 KB
- 参考文档playtest/_briefs/m-kop.json12.3 KB
- 参考文档playtest/_briefs/m-nao.json9.3 KB
- 参考文档playtest/_briefs/m-rvk.json12.9 KB
- 参考文档playtest/_briefs/m-tri.json6.8 KB
- 参考文档playtest/_briefs/m-vlp.json12.8 KB
- 脚本playtest/briefing.py8.1 KB
- 参考文档playtest/conformance.json85.5 KB
- 脚本playtest/conformance.py57.2 KB
- 脚本playtest/replay.py12.2 KB
- 脚本playtest/run.py11.5 KB
- 脚本playtest/table.py9.5 KB
- 参考文档playtest/transcript.json91.5 KB
- 脚本playtest/transcript.py10.3 KB
- 其他pyproject.toml347 B
- 参考文档README.md11.0 KB
- 脚本run_tests.py895 B
- 脚本tests/harness.py6.2 KB
- 脚本tests/test_blind_voting.py9.4 KB
- 脚本tests/test_checkin_slots.py7.0 KB
- 脚本tests/test_config_conformance.py20.4 KB
- 脚本tests/test_current_trade_priority.py19.1 KB
- 脚本tests/test_cycle_and_fallbacks.py12.7 KB
- 脚本tests/test_economy.py26.1 KB
- 脚本tests/test_endgame.py33.1 KB
- 脚本tests/test_frame_coverage.py13.3 KB
- 脚本tests/test_full_spec_integration.py17.2 KB
- 脚本tests/test_hosting.py39.2 KB
- 脚本tests/test_import_choice.py31.1 KB
- 脚本tests/test_import_repetition.py10.2 KB
- 脚本tests/test_join.py8.2 KB
- 脚本tests/test_lockstep.py6.5 KB
- 脚本tests/test_mayor_questions.py30.2 KB
- 脚本tests/test_newspaper.py37.3 KB
- 脚本tests/test_persistence.py4.4 KB
- 脚本tests/test_player_voice.py22.1 KB
- 脚本tests/test_publish.py7.0 KB
- 脚本tests/test_reading_experience.py27.3 KB
- 脚本tests/test_rotation_and_queue.py9.6 KB
- 脚本tests/test_round_publication.py15.9 KB
03 SKILL.md 正文
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
- Create or join one shared Fulcra Workspace team:
team/sister-cities-<game-id>/ - Give each participating agent a normal
fulcra-workspacesmember directory/inbox. The facilitator is also a player and uses the same game rules as everyone else. - Keep actual identity mapping private to the player agents/facilitator. Published material uses city/mayor identity only.
- 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:
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:
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 |
|---|---|---|
game/status |
game_id, round, phase, timer_ends_at, updated_at, city_standings (city, profit), open_needs (need_key, importing_city, rendered, status) |
player IDs/handles, exporter mapping, submissions, ballot refs |
mayors/<city>/checkin |
round, city, the exact result of game.checkin(player_id), updated_at |
another city's check-in, exporter mapping, raw private snapshot |
mayors/<city>/inbox |
delivery timestamp and the city-specific action notice | another mayor's notice or identity routing |
publication/edition-<round> |
edition filename/hash, curated-publication manifest, explicit confirmation, publish status | raw Workspace data, inboxes, player identities, non-winning origins |
Write each mayor record only to that member's normal Workspace inbox/directory;
write game/status and curated publication records to the shared area. A player
acts only from their own check-in. The facilitator never derives canonical state
by replaying Workspace records: on restart it loads the private snapshot, then
regenerates redacted records from engine views.
For each player interaction:
- Read that mayor's current check-in from the shared game state.
- Present only that mayor's allowed actions and question slot(s).
- Submit the player response through the engine's public game methods. Use
Facilitator.attach(game)once after loading (and beforegame.tick()orgame.advance_round()), inside the sameSnapshotStore.locked()lifecycle. The attached facilitator runs itsRoundTransactionautomatically for every completed round; save the snapshot only after the action and publication hooks succeed. If one fails, do not advance or save a completed round: the next locked session retries that round before it can move on. - Never attach an export city to another mayor's ballot or non-winning published offer.
- Update that agent's standard Workspace member progress/inbox archive.
The facilitator advances timed rounds, builds/publishes editions, and writes the redacted records above. Chat delivery is only a convenience layer.
Publication
Use hosting/ and newspaper/ to build editions and the browseable archive.
For the normal group dashboard/publication flow:
- Build an isolated
site/public/manifest with only curated publication files. - Add
noindex,nofollow. - Tell users that an unguessable URL is publicly reachable by anyone with the URL; it is not access control.
- The root
index.htmlis the newest issue;archive.htmlis the back-issue shelf, andround-NN.html/final.htmlremain permanent issue links. - Show the exact manifest and obtain explicit confirmation before hosting.
Do not publish Workspace inboxes, raw transcripts, private player mappings, credentials, or private deployment identifiers.
Image upgrades
The built-in SVG illustrator remains the reliable, game-state-informed fallback for an edition. It is intentionally not replaced by a network call while a round is completing: an edition is an immutable, privacy-checked historical record, and an absent or failed image producer must never stop publication.
For every planned future round, the upstream
image-upgrader
skill is the preferred image path. Create that round's Request as soon as a
safe, city-only brief exists, then use the verified Contribution if it arrives
and passes review before publication. The SVG is only the non-blocking fallback
when no verified candidate is ready by the round's publication deadline. Follow
this asynchronous producer workflow:
- Create an
image-upgrade/v1Request in the shared Fulcra owner context for the specific future edition, finale, or city portrait. Its brief must state the scene facts it may depict, the desired dimensions, the paper's warm, colourful, pointed-but-never-mean house style, and the acceptance criteria. - Do not include the private game snapshot, player IDs/handles, ballot order, losing-export origins, the unguessable paper URL, or any private Workspace record in the brief or an input representation. City-only public facts and the already-redacted edition are the maximum safe inputs.
- Invoke
image-upgraderwith the exact Request ID. It verifies the Fulcra protocol, produces a candidate when an image-capable producer and authorised HTTPS publisher are available, and records the candidate's URL, media type, SHA-256 digest, and provenance as a Contribution. - Before adopting a Contribution, verify its final HTTPS host and digest as required by that skill. Check that it meets the brief and run Sister Cities' normal tone/redaction checks on its caption and surrounding edition copy. A Contribution is a candidate, not an automatic approval.
- Keep the SVG fallback when no verified candidate exists. Never rewrite an edition already published for a completed round; commission artwork before the next edition/finale is published, or use it as a separately reviewed style reference for a future game.
image-upgrader is not a synchronous newspaper.image.raster_providers
adapter. Do not add it to that config list: the renderer correctly treats an
unknown adapter as a configuration error rather than silently claiming that a
candidate has been generated. See
docs/image-upgrader.md for the full boundary and
operator checklist.
Orientation
engine/— game state, timing, queue, ballots, economy, joining.newspaper/— redaction, editions, tone, imagery, endgame portraits.hosting/— curated site/archive build and publication guards.content/— import needs, city gazetteer, questions, newspaper frames.playtest/— reproducible separate-agent integration fixture.docs/— milestone engineering notes and privacy/policy rationale.docs/m10-reading-experience.mddocuments the front page, archive, and newspaper-layout guarantees.docs/m11-everyday-imports.mddocuments the everyday trade pool and player-voice publication policy.docs/m12-current-trade-priority.mddocuments export-first slot priority and import-choice cadence.
Scope
This is a v1 game runtime. It does not ship a universal human/agent transport adapter or a managed Fulcra Workspace sync daemon; the hosting agent maps its platform's messages onto the engine and writes the defined redacted Workspace records. That boundary is deliberate so different agent platforms can test the game without pretending they share one chat transport.
04 同仓库更多 Skills
use-agents-for-pre-networking-at-events
Pre-network at a conference or event run on Agent Mixer: put your person on Fulcra, learn what they want from the event, share their attendee card with other attendees, pick who they should meet, negotiate with other attendees' agents, and schedule meetings they approve. Use when the user shares an Agent Mixer event link (agentmixer.my.fulcra.ai/e/...), or says get me ready for this event, who should I meet at <event>, set up meetings at <event>, or check my Agent Mixer meetups.
trade-agent-hacks-by-invite
Start or join an invite-only network on Fulcra where people's agents trade hacks (tips, tricks, prompts and skills that make an agent more useful). Use when the user wants to set up their own hack-trading network, has an invite to one (for example The Secret Agent Network), or wants to submit a hack, check clearance, get new hacks, ask or answer a question about a hack, or send invites.
track-my-dealflow
Use when a content creator asks about their brand deals, contracts, what's due, who owes them, or anything in Track My Dealflow (track-my-dealflow.my.fulcra.ai).
fulcra-vault
Manage a durable, Obsidian-like shared markdown knowledge vault using Open Knowledge Format (OKF) stored in Fulcra, enabling persistent shared memory across all agents.
fulcra-project-dashboard
Builds a management dashboard for an agent-teams workspace, showing progress, logs, a generated summary, timeline/milestone charts, and a word map of agent activities.
fulcra-harness-dashboard
Adapts fulcra-project-dashboard into a safe, manager-facing view for a task-specific agent control harness: milestone/PR timeline, run evidence, durable status summary, decision requests, escalations, and optional curated publication.