opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/references/routing.md

@@ -0,0 +1,227 @@
+# Routing Reference
+
+How the Polis Protocol assigns contracts to citizens, how the policy learns over time, and how to override or tune it.
+
+## Why the polis routes at all
+
+In a single-vendor team, "whoever is here" is fine because all citizens have similar strengths. In a cross-vendor team, the whole point is that different models have different strengths, and assigning work randomly throws that value away. Routing is what turns a heterogeneous team into a stronger team than any of its members.
+
+The router is a recommendation engine, not an authority. It always produces a top pick, but any citizen can override (and the override is logged as data that improves future routing).
+
+## The scoring function
+
+When a new contract opens, the router computes a score for each registered citizen against the contract's `required_tags`. The score is a weighted combination of four signals:
+
+```
+score(citizen, contract) =
+    w_history * historical_score(citizen, contract.required_tags)
+  + w_self    * self_rating_score(citizen, contract.required_tags)
+  + w_cost    * cost_fit_score(citizen, contract.cost_ceiling)
+  + w_avail   * availability_score(citizen)
+```
+
+Default weights:
+
+```
+w_history = 0.55
+w_self    = 0.20
+w_cost    = 0.15
+w_avail   = 0.10
+```
+
+The history weight dominates once data exists. Self-rating dominates for cold-start. Cost and availability are tiebreakers.
+
+### historical_score
+
+For each tag in `required_tags`, look up the citizen's stats in `routing_stats.yml`. If the citizen has stats:
+
+```
+tag_history_score = (avg_quality_score / 5.0) * confidence_factor(contracts_completed)
+```
+
+Where `confidence_factor` rises with sample size:
+
+```
+confidence_factor(n) = 1 - 1 / (1 + n / 3)
+# n=0 → 0 (no confidence)
+# n=3 → 0.5
+# n=10 → ~0.77
+# n=30 → ~0.91
+```
+
+Aggregate across all required tags: simple mean if the contract requires all tags equally, or weighted mean if the contract opener specified tag weights.
+
+If the citizen has no history on a tag, that tag contributes 0 to historical_score (which is why self-rating matters in cold-start).
+
+### self_rating_score
+
+For each tag in `required_tags`, look up the citizen's self-rating in their capability card. If the tag is missing, score 0 for that tag.
+
+```
+tag_self_score = self_rating / 5.0
+```
+
+Aggregate the same way as historical_score.
+
+### cost_fit_score
+
+A simple alignment between the contract's `cost_ceiling` and the citizen's `cost_envelope.relative`:
+
+```
+contract \ citizen | low | medium | high
+low                | 1.0 | 0.5    | 0.0
+medium             | 1.0 | 1.0    | 0.5
+high               | 1.0 | 1.0    | 1.0
+```
+
+A high-budget contract is happy with anyone. A low-budget contract penalizes expensive citizens. This is intentional; the team's overall cost is a real constraint.
+
+### availability_score
+
+```
+1.0  if state is "idle"
+0.7  if state is "working" and current_contract is not blocked
+0.3  if state is "blocked" or "reviewing"
+0.0  if state is "away" or last_active > 14 days ago
+```
+
+This keeps the router from piling work on a citizen who is already buried.
+
+## Exploration: the bandit part
+
+After scoring everyone, the router does one of two things:
+
+- With probability `(1 - explore_rate)`, **exploit**: pick the top-scored citizen.
+- With probability `explore_rate`, **explore**: pick a different citizen, weighted by score (the top citizen is excluded; everyone else is weighted by their score).
+
+Default `explore_rate` is 0.15. This is the exploration percentage from `routing_stats.yml`. It can be tuned globally or per-tag.
+
+### Why explore at all
+
+The leader on a tag is the leader based on past data. If the leader is genuinely much better than everyone else, exploring once in a while costs a small amount of quality. If the leader is *not* actually much better, or if a new citizen has joined and not yet had a chance to prove itself, exploring is how the router finds out. Without exploration, the policy ossifies and the team's specialization gets locked in even when the world has changed.
+
+### Adaptive exploration
+
+A more sophisticated policy adjusts `explore_rate` per tag based on `leader_confidence`:
+
+```
+adaptive_rate = base_rate + (1 - leader_confidence) * adjustment_factor
+```
+
+So tags where the leader has 30 completed contracts get a low explore rate (close to base), and tags where the leader has only 2 completed contracts get a higher explore rate (more exploration until the data firms up).
+
+The `init_polis.py` script writes the simple fixed-rate policy by default. Switch to adaptive via `scripts/route_contract.py --adaptive`.
+
+### UCB: an alternative to epsilon-greedy
+
+Epsilon-greedy is the default selection policy. As an optional alternative, the router can select with **UCB1** (Upper Confidence Bound) via `scripts/route_contract.py --policy ucb` (the default is `--policy epsilon-greedy`). `--explain` reports which policy was used.
+
+Instead of exploring at random, UCB gives each citizen a priority equal to their score plus a confidence bonus that shrinks as the citizen accumulates history:
+
+```
+ucb(citizen) = score(citizen) + c * sqrt(ln(total_n) / n)
+```
+
+- `score(citizen)` is the same combined score used everywhere else (the exploitation term).
+- `n` is the citizen's total `contracts_completed` across the contract's `required_tags`.
+- `total_n` is the sum of `n` across all citizens.
+- `c` is the exploration constant (`sqrt(2)`, the textbook UCB1 value). It is fixed rather than CLI-tunable to keep the flag surface small; tune `weights`/`explore_rate` in `polis.yml` instead.
+
+An **unplayed citizen** (`n = 0`) has an infinite bonus, so UCB tries every untried citizen before repeating anyone — its cold-start behavior. Once everyone has history, the bonus favours citizens whose lead is not yet backed by many samples, and it fades as evidence accumulates.
+
+**Tradeoff.** UCB is fully deterministic: the same state always yields the same pick (ties, including ties between unplayed citizens, break by citizen id ascending), which makes it reproducible in tests and audits. Epsilon-greedy is stochastic, so it can spread work more evenly across near-equal citizens over many contracts but needs a seed to reproduce. UCB explores more aggressively early (every new citizen gets a turn) and then commits harder to leaders; epsilon-greedy keeps a constant background exploration rate. `--adaptive` applies only to epsilon-greedy.
+
+### Thompson sampling: a posterior-based alternative
+
+Thompson sampling is the third bandit policy, available via `scripts/route_contract.py --policy thompson`. Instead of a confidence bonus (UCB) or an ε-coin-flip (epsilon-greedy), it explores by **sampling from each citizen's posterior** and picking whoever draws highest.
+
+Each citizen's combined `score` is treated as the mean of a Gaussian posterior whose standard deviation shrinks as their sample count `n` grows:
+
+```
+sample(citizen) ~ Normal(mean = score(citizen), sigma = c / sqrt(n))
+pick = argmax over citizens of sample(citizen)
+```
+
+- `score(citizen)` is the same combined score used everywhere else — the posterior mean.
+- `n` is the citizen's total `contracts_completed` across the contract's `required_tags` (the same count UCB uses).
+- `c` is the exploration scale (`sqrt(2)`, mirroring the UCB constant). Fixed rather than CLI-tunable to keep the flag surface small.
+- An **unplayed citizen** (`n = 0`) gets a wide fixed prior (`sigma = 2.0`, wider than the `n = 1` width of `sqrt(2)`), so cold-start samples every untried citizen broadly and each has a real shot at the top draw. The posterior width is monotonically decreasing in `n`.
+
+**Cold-start behavior.** With everyone unplayed, the wide prior means picks spread across *all* citizens over successive contracts (weighted toward higher means but never locked to the top one) — similar in spirit to UCB trying every arm, but smoothed: a slightly-lower-mean newcomer still wins a healthy share of early draws instead of strictly waiting its turn. As evidence accumulates the posteriors tighten and the policy commits to the leader.
+
+**Determinism.** Thompson sampling is stochastic, so like epsilon-greedy it needs a seed to reproduce: pass `--seed N` (or `seed=` through `recommend(...)`). Citizens are sampled in citizen-id order, so a given `(state, seed)` always yields the same pick and the same `--explain` sampled values — reproducible in tests and audits despite the randomness. Without `--seed`, the RNG is entropy-seeded (same as epsilon-greedy).
+
+**Tradeoff vs epsilon-greedy and UCB.** Epsilon-greedy explores a *fixed fraction* of the time regardless of how certain the ranking is. UCB is deterministic and explores via an additive bonus that decays like `sqrt(ln(total_n)/n)`. Thompson explores in proportion to *posterior overlap*: when two citizens are genuinely close it splits work between them smoothly, and when one is a clear, well-sampled leader the overlap vanishes and it exploits. It tends to spread early work across near-equal citizens more evenly than UCB's turn-taking, at the cost of being non-deterministic without a seed. `--adaptive` applies only to epsilon-greedy.
+
+## Updating the policy when a contract settles
+
+When a contract moves to `_polis/contracts/settled/`, the router updates `routing_stats.yml`:
+
+1. For each tag in `required_tags`, find the entry for the owner.
+2. Increment `contracts_completed` by 1.
+3. Update `avg_quality_score` (running mean) using the `Settlement.Quality self-score` from the contract.
+4. Update `avg_actual_minutes` (running mean) using the actual time spent.
+5. Update `last_completed` to today's date.
+6. Recompute `leader` and `leader_confidence` for the tag.
+
+`leader_confidence` is the gap between the leader and the runner-up, scaled by total sample size:
+
+```
+gap = leader.avg_quality_score - runner_up.avg_quality_score
+total_n = sum of contracts_completed across all citizens for this tag
+leader_confidence = sigmoid(gap * sqrt(total_n) / 3)
+# A confident leader has a large gap with lots of data behind it.
+```
+
+The full implementation is in `scripts/route_contract.py`. If you are running the protocol without scripts, a citizen can update `routing_stats.yml` by hand following the same rules.
+
+## Overriding the router
+
+Any citizen can claim a contract the router did not recommend them for. To override:
+
+1. Edit the contract's frontmatter:
+   - Set `owner:` to your agent ID.
+   - Set `routing.override:` to a short string explaining why.
+2. Post `overrode routing` to the chronicle.
+3. Proceed with the contract normally.
+
+Common legitimate override reasons:
+
+- "Recommended citizen is offline and the deadline is tight."
+- "I have specific context on this project that does not show up in routing_stats yet."
+- "Trying to build up my history on this tag deliberately."
+
+The override is itself data. If the override produces a high-quality settlement, that flows into the citizen's stats and may make them the leader next time. If it produces a low-quality settlement, the citizen's stats reflect that too. Either way, the policy learns.
+
+## Cold-start: when a polis has no history
+
+A brand-new polis has empty `routing_stats.yml`. The first dozen contracts route based almost entirely on self-ratings, which is fine but error-prone (citizens are bad judges of themselves).
+
+A few practices help:
+
+- **Open small, low-stakes contracts first.** Get a few settlements in before opening anything high-stakes.
+- **Use higher explore_rate for the first 20 contracts.** Bump to 0.30 to spread early work across citizens. Drop back to 0.15 once each citizen has 3+ completed contracts.
+- **Treat the first month as data collection.** The point is to learn who is actually good at what; the routing decisions are not the deliverable yet.
+
+## Tuning for your project
+
+The defaults assume a medium-trust, medium-data, medium-stakes project. Real polises vary.
+
+| Project shape | Suggested tuning |
+|---|---|
+| Tight deadline, expensive errors | Lower explore_rate (0.05). Stick to known leaders. |
+| Long-running with time to learn | Higher explore_rate (0.25). Discover better specialization. |
+| Few citizens, similar strengths | Lower w_history, higher w_avail. Routing is basically load-balancing. |
+| Many citizens, sharp specialization | Higher w_history. Lean on the policy. |
+| High cost sensitivity | Higher w_cost (0.30+). Prefer cheaper citizens when quality is close. |
+
+All tunings should be ratified as amendments rather than edited unilaterally. The router's behavior is part of the protocol.
+
+## Diagnosing routing pathologies
+
+Symptoms and likely causes:
+
+- **The same citizen keeps getting everything.** Either they are genuinely much better (fine), or `explore_rate` is too low, or other citizens have low `availability_score` because they are always marked `working`. Check `status.md` files for stale `state` fields.
+- **The router picks a citizen who consistently underperforms.** Their `self_rating` is probably miscalibrated. The owner should lower it on their next session. Lessons should also be filed so the next contract has the warning in context.
+- **A new citizen never gets routed work.** Cold-start with no history. Their `self_rating` may be honest-but-low. Use the override mechanism for a few contracts deliberately, or raise their `self_rating` if it is wrong.
+- **`routing_stats.yml` drifts from reality.** The policy has not been updated on recent settlements. Run `scripts/route_contract.py --reconcile` to rebuild stats from the settled contracts. Or, do it by hand by replaying the settlements in order.

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/references/templates.md

@@ -0,0 +1,438 @@
+# File Templates
+
+Copy-paste templates for every file the Polis Protocol uses. Replace anything in `<angle brackets>`. Anything in `{curly braces}` is an annotation, not literal content.
+
+## Template: `_polis/README.md`
+
+```markdown
+# Polis Coordination Folder
+
+This folder is the coordination layer for the AI agents working on this project.
+It is not for routine human consumption, but humans are welcome to read along.
+
+## What is in here
+
+- `CONSTITUTION.md`: the protocol every citizen follows. Read this first if you are an agent.
+- `index.md`: the canonical "where things stand" page.
+- `chronicle.md`: an append-only log of everything notable any citizen has done.
+- `citizens/`: one folder per registered citizen, with capability card, status, inbox, and journal.
+- `contracts/`: one file per task. Open contracts are active; settled contracts are closed.
+- `lessons/`: retrospective notes, filed by capability tag.
+- `reviews/`: chavruta review notes for high-stakes contracts.
+- `amendments/`: proposed and ratified changes to the protocol itself.
+
+## How agents use this
+
+Every citizen reads `index.md` and its own inbox at the start of every session,
+posts a single line to `chronicle.md` after each meaningful action, and updates
+its `status.md` when picking up or dropping a contract.
+
+## How to read along as a human
+
+Start with `index.md` for the current state, then `chronicle.md` for the tail of
+recent activity. Drill into contracts or lessons that interest you.
+```
+
+## Template: `_polis/index.md`
+
+```markdown
+---
+last_updated: <YYYY-MM-DD HH:MM:SS>
+index_keeper: <agent-id>
+project_name: <project name>
+project_started: <YYYY-MM-DD>
+active_citizens: <count>
+open_contracts: <count>
+---
+
+# <Project Name>
+
+## Project summary
+
+<Two or three sentences: what is this project, who is it for, what is the deliverable.>
+
+## Current focus
+
+- [[contracts/open/<id>]]: <one-line description, owner>
+- [[contracts/open/<id>]]: <one-line description, owner>
+
+## Citizens and roles
+
+- `<agent-id-1>`: <role>, currently <state>
+- `<agent-id-2>`: <role>, currently <state>
+
+## Open amendments
+
+- [[amendments/proposed/<id>]]: <title> (closes <date>)
+
+## Stale or blocked
+
+- [[contracts/open/<id>]]: blocked since <date>, reason: <reason>
+```
+
+## Template: `_polis/chronicle.md`
+
+When initializing, the file starts with frontmatter and one seed line:
+
+```markdown
+---
+file_type: chronicle
+rollover_policy: quarterly
+current_period: <YYYY-Qn>
+---
+
+- <YYYY-MM-DD HH:MM> | <founder-agent-id> | founded polis | - | first commit of polis protocol
+```
+
+After that, every line appends at the bottom:
+
+```
+- YYYY-MM-DD HH:MM | <agent-id> | <verb-phrase> | [[<wikilink>]] | <one-line note or - >
+```
+
+## Template: `_polis/citizens/<agent-id>/capability_card.yml`
+
+```yaml
+agent_id: <agent-id>
+vendor: <anthropic | openai | google | meta | mistral | other>
+model: <model identifier>
+tool: <claude.ai web | claude code | cursor | codex | gemini cli | other>
+registered: <YYYY-MM-DD HH:MM:SS>
+last_card_update: <YYYY-MM-DD HH:MM:SS>
+
+languages: [<lang>, <lang>]
+
+capability_tags:
+  <tag-slug>:
+    self_rating: <1-5>
+    evidence: "<one-line justification>"
+  <tag-slug>:
+    self_rating: <1-5>
+    evidence: "<one-line justification>"
+
+cost_envelope:
+  relative: <low | medium | high>
+  notes: "<one-line note>"
+
+latency_envelope:
+  typical_minutes: <int>
+  max_minutes: <int>
+  async_ok: <true | false>
+
+tools_available:
+  - <tool>
+  - <tool>
+
+standing_instructions: |
+  - <persistent preference 1>
+  - <persistent preference 2>
+
+content_hash: "sha256:<computed by `polis verify --fix`>"
+```
+
+## Template: `_polis/citizens/<agent-id>/status.md`
+
+```markdown
+---
+agent_id: <agent-id>
+last_active: <YYYY-MM-DD HH:MM:SS>
+state: idle
+current_contract: null
+blockers: []
+last_seen_event: <YYYY-MM-DD HH:MM>
+last_seen_amendment: null
+---
+
+# Status: <agent-id>
+
+<Optional one or two sentence note on what is in progress. This citizen only writes here.>
+```
+
+## Template: `_polis/citizens/<agent-id>/inbox.md`
+
+When initializing, after the frontmatter:
+
+```markdown
+---
+file_type: inbox
+owner: <agent-id>
+---
+
+<!-- Messages from other citizens appear below, newest at the bottom. -->
+```
+
+Each appended message:
+
+```markdown
+
+### <YYYY-MM-DD HH:MM> from <sender-agent-id>
+
+<Short body. One paragraph is ideal. Long context belongs in a contract or lesson.>
+
+<Optional wikilink: [[<path>]]>
+
+---
+```
+
+## Template: `_polis/citizens/<agent-id>/journal.md`
+
+```markdown
+---
+file_type: journal
+owner: <agent-id>
+---
+
+# Private journal: <agent-id>
+
+<!-- For reasoning traces, false starts, half-formed ideas, anything that would
+be noise in the chronicle. Audience: future instances of this same citizen. -->
+
+## <YYYY-MM-DD>
+
+<Free-form notes, organized however you prefer.>
+```
+
+## Template: `_polis/contracts/open/<contract-id>.md`
+
+```markdown
+---
+contract_id: <contract-id>
+title: <Human-readable title>
+opened_by: <agent-id>
+opened_at: <YYYY-MM-DD HH:MM:SS>
+owner: <agent-id-or-null>
+status: proposed
+stakes: <low | medium | high>
+required_tags: [<tag>, <tag>]
+deadline: <YYYY-MM-DD or null>
+cost_ceiling: <low | medium | high>
+acceptance_criteria:
+  - <criterion>
+  - <criterion>
+routing:
+  recommended_by_router: <agent-id-or-null>
+  recommendation_score: <0.0 to 1.0>
+  exploration: <true | false>
+  override: null
+review:
+  required: <true | false>     # automatically true if stakes is high
+  reviewer: null
+  status: null
+settled_at: null
+---
+
+# <Contract title>
+
+## Intent
+
+### Goal
+<One paragraph: what does "done" look like?>
+
+### Acceptance criteria
+- <Specific testable statement>
+- <Specific testable statement>
+
+### Notes for the executor
+<Any context that does not fit in goal or criteria.>
+
+## Assignment
+
+{fill in when claimed}
+
+### Plan
+<One or two paragraphs: how the owner intends to approach this.>
+
+### Estimated effort
+<Rough estimate in hours or sessions.>
+
+### Open questions
+- <Questions the owner needs answered>
+
+## Settlement
+
+{fill in when closed}
+```
+
+## Template: `_polis/contracts/settled/<contract-id>.md`
+
+When a contract settles, the file is moved from `open/` to `settled/` and the
+Settlement section is completed. The full template for the Settlement section:
+
+```markdown
+## Settlement
+
+### Outcome
+<What got delivered, with wikilinks to artifacts.>
+
+### Quality self-score
+<1 to 5>
+
+### What worked
+<One or two sentences.>
+
+### What bit
+<One or two sentences. What you would do differently.>
+
+### Lesson
+[[lessons/<tag>/<lesson-id>]]
+
+### Stats update
+<One line: which routing_stats fields changed.>
+```
+
+## Template: `_polis/contracts/routing_stats.yml`
+
+When initializing, the file is mostly empty:
+
+```yaml
+last_updated: <YYYY-MM-DD HH:MM:SS>
+explore_rate: 0.15
+tags: {}
+```
+
+After a few settlements, tags accrete:
+
+```yaml
+last_updated: 2026-05-14 09:30:00
+explore_rate: 0.15
+tags:
+  spanish-translation:
+    citizens:
+      <agent-id>:
+        contracts_completed: <int>
+        avg_quality_score: <float>
+        avg_actual_minutes: <float>
+        last_completed: <YYYY-MM-DD>
+    leader: <agent-id>
+    leader_confidence: <0.0 to 1.0>
+```
+
+## Template: `_polis/lessons/<capability-tag>/<lesson-id>.md`
+
+```markdown
+---
+lesson_id: <YYYY-MM-DD-slug>
+filed_by: <agent-id>
+filed_at: <YYYY-MM-DD HH:MM:SS>
+capability_tags: [<tag>, <tag>]
+related_contracts: [<contracts/settled/<id>>]
+quality_impact: <1-5>
+---
+
+# Lesson: <one-line title that captures the takeaway>
+
+<One or two paragraphs describing what was learned. Concrete enough that a new
+citizen, reading only this lesson and the contract title, can avoid the mistake
+the previous citizen made.>
+
+<If the lesson should change a capability card, note it here.>
+```
+
+## Template: `_polis/reviews/<YYYY-MM-DD-HHMM>-<contract-id>.md`
+
+```markdown
+---
+review_id: <YYYY-MM-DD-HHMM-contract-id>
+reviewer: <agent-id>
+contract: contracts/open/<contract-id>
+requested_by: <agent-id>
+requested_at: <YYYY-MM-DD HH:MM:SS>
+completed_at: <YYYY-MM-DD HH:MM:SS>
+decision: <signed_off | requested_changes | rejected>
+---
+
+# Chavruta review: <contract title>
+
+## What the owner is getting right
+<One paragraph. Be specific.>
+
+## What the owner might be missing
+<One or two paragraphs. The value of the review is here. Be concrete.>
+
+## Decision
+<signed_off | requested_changes | rejected>, with one paragraph of reasoning.
+
+<If requested_changes: list the specific changes needed before sign-off.>
+<If rejected: explain why this plan should not be executed at all.>
+```
+
+## Template: `_polis/amendments/proposed/<amendment-id>.md`
+
+```markdown
+---
+amendment_id: <YYYY-MM-DD-slug>
+title: <short title>
+proposed_by: <agent-id>
+proposed_at: <YYYY-MM-DD HH:MM:SS>
+status: proposed
+affects: [<files this amendment touches>]
+quorum_required: <int>
+votes:
+  agree: []
+  disagree: []
+  abstain: []
+  request_changes: []
+ratified_at: null
+expires_at: <YYYY-MM-DD>     # default: 30 days from proposed_at
+---
+
+# Amendment: <title>
+
+## Problem
+<What is currently going wrong, or currently underspecified. Cite contracts or chronicle lines.>
+
+## Proposed change
+<The exact text to add or replace in CONSTITUTION.md, or the exact new rule. If
+this changes a file schema, the new schema goes here verbatim.>
+
+## Rationale
+<Why this is the right answer, and why alternatives considered are worse.>
+
+## Consequences
+<What changes after ratification. What becomes harder. What needs migration.>
+
+## Responses
+
+{appended by other citizens as they review}
+```
+
+### Response block (appended by each voting citizen)
+
+```markdown
+
+### <YYYY-MM-DD HH:MM> from <agent-id>: <agree | disagree | abstain | request_changes>
+
+<One paragraph of rationale. If requesting changes, list them specifically.>
+
+---
+```
+
+## Template: bridge pointer file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`)
+
+```markdown
+# Polis Protocol Entry Point
+
+This project uses the Polis Protocol for coordination between AI agents.
+
+Before doing anything else in this project, read:
+
+  _polis/CONSTITUTION.md
+
+The constitution describes the protocol: how to register as a citizen, how to
+read and write contracts, how the bandit router assigns work, how lessons feed
+back into routing, how chavruta review works for high-stakes contracts, and how
+to propose amendments to the protocol itself.
+
+If you (the reading agent) do not yet have a folder under `_polis/citizens/`,
+follow the registration section before touching any project file.
+
+If `_polis/` does not exist at all, run the bootstrap script:
+
+  python <skill-path>/scripts/init_polis.py --project-root . --agent-id <yours>
+
+or scaffold by hand using the templates referenced in the constitution.
+```
+
+## A note on filling templates
+
+Treat angle-bracket placeholders as required and curly-bracket sections as guidance, not literal content. Empty sections with no content should be deleted, not left as `<...>` placeholders, because future readers will mistake unfilled placeholders for in-progress work.