@sleepy_panda_srl/portulan 0.1.0

package/core/templates/gate-policy.md

@@ -0,0 +1,76 @@
+# Template — Gate policy
+
+> A **gate policy** binds this team's concrete actions to the engine's tiers — Auto / Propose / Gated /
+> Prohibited — in machine-readable form, so the gate map stops being prose and starts being enforcement.
+> `compile` reads it and emits host hooks and permissions, plus a repository-ruleset export for the
+> platform floor. Copy the skeleton below into `gates.json` and fill it. (Placeholders are in `{braces}`.)
+> _(Provenance: the safety culture inherited from the predecessor practice — gates classified by
+> undoability; 12-Factor Agents — compact, auditable policy. Tier semantics are fixed by
+> [`../operating/autonomy.md`](../operating/autonomy.md), which is the authority.)_
+>
+> **Write the `why` before you write a rule.** A policy with no rationale is taste, and the `reason` on
+> each rule is what an agent reads when it is refused — a refusal whose reason is a rule id is
+> indistinguishable from a bug.
+>
+> **The compiler adds restriction only.** It emits `ask` and `deny` and never `allow`, so `auto` rules
+> compile to nothing by design: an action nobody restricted is already permitted, and emitting a grant
+> would let a policy widen what a host allows. That asymmetry is the whole safety property — read it
+> before concluding a rule "did not work".
+>
+> **A compiled gate matches a spelling, not an intent.** A command reaching a gated action by another
+> route escapes it, and one wrapper level is peeled and no more. What is indifferent to spelling is the
+> **platform floor** beneath — branch protection, required checks, PR-as-gate — which is why the floor is
+> a separate block below and not a rule among the others.
+
+---
+
+```json
+{
+  "portulan": { "gates": "1.0" },
+
+  "why": "{Why this team gates what it gates — the sentence a new agent reads first. Name the blast radius you are protecting, not the tools you are restricting.}",
+
+  "floor": {
+    "branch": "{default branch}",
+    "require_pull_request": true,
+    "block_force_push": true,
+    "checks": []
+  },
+
+  "rules": [
+    {
+      "id": "{rule-id}",
+      "tier": "prohibited",
+      "action": { "write": "{path that must never be machine-edited}" },
+      "reason": "{Why, and what to do instead. Prohibited means no yes makes this acceptable — if a human could approve it, it is Gated, not Prohibited.}"
+    },
+    {
+      "id": "{rule-id}",
+      "tier": "gated",
+      "action": { "shell": "{command prefix}" },
+      "reason": "{Why a human must approve each time. Prefer the undoability test: what does it cost if this was wrong and nobody noticed for a week?}"
+    },
+    {
+      "id": "{rule-id}",
+      "tier": "propose",
+      "action": { "write": "{path}" },
+      "reason": "{Why this lands as a proposal rather than a direct change.}"
+    }
+  ]
+}
+```
+
+> **`checks: []` is deliberate and you should probably leave it that way at first.** A floor requiring a
+> status check that no workflow job reports is a red nobody caused — a fresh repository reports no checks,
+> and a real one reports something else, so any name guessed here fails on the first run. Add the check
+> once it exists and you know its exact context name. The consequence, stated because it is not obvious:
+> with no checks declared, every `propose` rule compiles to nothing in the floor backend.
+>
+> **Which tiers compile depends on the backend, and there are two.** For a host-hook backend, `gated`
+> prompts and `prohibited` refuses, while `auto` and `propose` emit nothing. For the **floor** backend the
+> partition inverts: `propose` is exactly what a repository ruleset enforces. Run `compile --matrix` to
+> print every rule against both rather than reasoning about it — the refusals are printed, never silent.
+>
+> **Start with the rules that destroy rather than create.** A ref deletion and a force-push are the two
+> the floor backend can express, they are the two whose damage is hardest to undo, and they are a policy's
+> honest first pair.

package/core/templates/handoff.md

@@ -0,0 +1,29 @@
+# Template — Handoff
+
+> A **handoff** records a decision and its *why*, so the next agent — or the next context window —
+> inherits the reasoning and not just the result. Write one **at the close of every session** — that part
+> is not conditional, and short is fine — and also when compacting, when hitting an iteration cap, or when
+> passing work across a persona boundary. Decisions without their why get silently re-litigated or
+> reversed. **Drop any section that has nothing to say** — the date and the decisions-with-why are the
+> only irreducible parts, and a handoff of five lines is a valid handoff. The date lives in the
+> **filename**, leading, in ISO form — `YYYY-MM-DD-{slug}.md` — not in a field inside the document: that
+> is what a gate checks and what makes the series sort chronologically. That is what keeps the
+> every-session rule from becoming ceremony: it scales down here, inside the artifact, rather than by
+> being skipped. _(Provenance: Cognition — handoffs record decisions and rationale. The every-session rule
+> and why it is binary rather than discretionary are in `../operating/loop.md`.)_
+
+---
+
+# Handoff — {task / thread}
+
+**State.** {where things actually are right now — done, in-progress, blocked — in a few lines.}
+
+**Decisions + why.** {each decision taken and the reason it was taken; the reasons are the payload.}
+- {decision} — because {why}; alternatives considered: {…}.
+
+**Open questions.** {what is undecided, and who decides it — flag the human-owned ones.}
+
+**Next action.** {the single next step, concrete enough to start from cold.}
+
+**Recoverability.** {anything left in a partial state, and how to make it safe; see
+`../operating/safety.md`.}

package/core/templates/memory-entry.md

@@ -0,0 +1,44 @@
+# Template — Memory entry
+
+> A **memory** is one durable fact with its provenance, written so the right one can be recalled later
+> without loading them all. One fact per entry; agents draft, humans accept into the curated layer.
+> _(Provenance: Letta — per-agent memory; compounding engineering — provenance on every rule; ETH Zurich
+> — curated beats generated. See `../operating/memory.md`.)_
+
+---
+
+**type:** rule | decision | reference | glossary
+**scope:** {the persona / repo / workspace this belongs to — memory is per-agent, not global}
+**provenance:** {one of the two forms below — a rule carrying neither is taste, and `doctor` rejects it}
+
+**Which types this binds.** `doctor` *requires* a two-form stamp on `type: rule` and reports it on the
+others, because thesis 4 and the mandate it comes from are rule-scoped. Write one on every entry anyway:
+a decision you cannot trace is no easier to retire than a rule you cannot trace, and the difference is
+only in what a machine is willing to fail you for.
+
+Provenance takes one of exactly two forms, and the Workspace Definition
+(`../../spec/workspace.schema.json`, `$defs/provenance`) makes both machine-checkable:
+
+**provenance:** `form=link` `href={ticket | PR | postmortem | commit}`
+— the incident is public, or at least visible to everyone who can read this rule.
+
+**provenance:** `form=sealed` `owner={who can re-validate}` `date={YYYY-MM-DD}` `shape={the de-identified failure}`
+— for an incident that cannot leave its owner's layer. The chain stays in the owner's workspace; what
+travels is the stamp and the mechanism, never the episode. `shape` must carry the inputs, the wrong
+outcome, and why the obvious guard misses — the bar is that someone who never saw the incident can still
+write the rule's test. _(Sealed is the weaker form and is meant to look it: `doctor` reports what
+proportion of a workspace's rules are sealed, because a workspace where everything is sealed has opted
+out of retirement altogether. What no machine checks is whether a stamp is **true** — a fabricated one
+passes exactly as a real one does, which is why the bar in `../skills/codify/SKILL.md` step 1 and human
+review are what actually guard the content. See also `../operating/memory.md`.)_
+
+The stamp is parsed out of backticked `key=value` tokens on this line, so annotation prose may follow it
+freely — and should: the fields carry what a machine needs, the sentence after them carries what a reader
+does.
+
+{The fact, in one or two sentences. If it is a rule, state the rule and — on their own lines — **why**
+it holds and **when to apply** it. Link related memories so recall can follow the thread.}
+
+**Retire when:** {for a rule, the condition under which it stops being true — e.g. "the generated client
+is deleted" — so the librarian can demote it instead of it living forever.} _(`doctor` reports an entry
+that states none — a record no condition can demote is how a store only grows.)_

package/core/templates/pack.md

@@ -0,0 +1,94 @@
+# Template — Pack
+
+> A **pack** is the cascade's middle layer — `core < pack < workspace < repo card < task` — and its
+> manifest declares what it contributes to that cascade: skills, personas, verify recipes, and
+> gate-policy fragments. It is an **index, not a container**: the content lives in the files the paths
+> point at. Copy the skeleton below into `pack.json` at the pack's root and fill it. (Placeholders are in
+> `{braces}`.) _(Provenance: platform engineering — golden paths for packs. The binding contract is
+> [`../../spec/pack.schema.json`](../../spec/pack.schema.json), which is the authority; this template is
+> a starting point and does not restate its rules.)_
+>
+> **Three things this template cannot decide for you, and each has bitten somebody.**
+>
+> **The category is not decorative.** A `stacks` pack profiles a language or framework, a `tools` pack
+> integrates a tool or MCP server and ships the gate classification for each, and a `rituals` pack
+> carries a repeatable procedure that composes onto the loop. It is spelled as the directory that holds
+> the pack, so the canonical `category/name` reference and the tree agree by construction rather than by
+> discipline.
+>
+> **`contributes` is required even when it is empty of a given kind** — a pack contributing nothing is a
+> plugin, not a pack, and the manifest should say which it is rather than leaving it to be inferred from
+> four absences.
+>
+> **A gate fragment may only ever ADD restriction.** It may raise a tier or add a prohibition and may
+> never demote another layer's classification, and a fragment naming an id a lower layer already carries
+> must keep that rule's `action` **unaltered** — raising the tier while replacing the matcher passes
+> every tier comparison, is reported as a tightening, and removes the gate. That was measured on a real
+> policy, not imagined. `auto` is absent from the tier enum for the same reason: it is the absence of
+> restriction, so a pack declaring it could only be attempting a demotion.
+
+---
+
+```json
+{
+  "portulan": {
+    "pack": "1.0",
+    "version": "0.1.0"
+  },
+
+  "name": "{kebab-case-name}",
+  "category": "{stacks | tools | rituals}",
+  "summary": "{One line an agent can read before loading anything else.}",
+  "doc": "README.md",
+
+  "contributes": {
+    "skills": ["skills/"]
+  }
+}
+```
+
+> **Why `personas`, `verify` and `gates` are absent from the skeleton above rather than present as placeholders.**
+> A scaffold has to **validate on the run after it is written**. An id placeholder like `{recipe-id}`
+> fails `$defs/slug`, and `{propose | gated | prohibited}` fails the tier enum — so a manifest carrying
+> them is red the first time anybody checks it, on a workspace the tool just created. `personas` joins
+> them for the same reason found one layer along: a `personas/{role}.md` placeholder *passes* the schema,
+> because it is a well-formed relative path — and then fails the check that **opens** it, which the same
+> change that wrote this template also added. Validating the shape and forgetting the opening is the
+> narrower version of the very mistake this paragraph is about. That is a red the
+> author did not cause and cannot act on except by deleting what was handed to them, and it is the exact
+> shape this project has already shipped once and had to fix. Add the three keys below when you have real
+> values for them; an absent key contributes nothing of that kind, which is the honest state until then.
+>
+> ```json
+> "personas": ["personas/my-role.md"],
+>
+> "verify": [
+>   {
+>     "id": "my-recipe",
+>     "run": "{the command, as it would be typed from the ADOPTER's repository root}",
+>     "requires": ["bash"],
+>     "doc": "README.md"
+>   }
+> ],
+>
+> "gates": [
+>   {
+>     "id": "my-rule",
+>     "tier": "gated",
+>     "action": { "shell": "{command prefix}" },
+>     "reason": "{Why the rule exists, in your own words, and what the agent should do instead. This sentence is what an adopter reads when a pack they installed refuses something — a refusal whose reason is a pack name is indistinguishable from a bug.}"
+>   }
+> ]
+> ```
+
+> **Delete the keys you do not contribute.** Every one is optional, and an empty array is not the same as
+> an absent key: `minItems: 1` refuses the empty array, so a pack that declares `"verify": []` fails
+> validation rather than declaring nothing. Say nothing instead.
+>
+> **What a composed recipe may and may not do**, because it is the part that can be got wrong silently:
+> composition is **additive only** — a pack may add a recipe and may never redefine, remove or replace
+> one the workspace declares, nor become the workspace's `verify.default` — and a composed recipe is
+> namespaced by its pack, so a collision is impossible rather than resolved. These limits are **not a
+> security boundary** and should not be read as one: a recipe's `run` is arbitrary shell, and a workspace
+> that lists your pack has already consented to running your code. What they prevent is narrower and is
+> the thing worth preventing — a pack silently changing what the adopting workspace's **green means**.

package/core/templates/persona.md

@@ -0,0 +1,69 @@
+# Template — Persona
+
+> A **persona** is a role an agent takes, packaged as a **context firewall**: its own attention window,
+> its own memory, and a `tools:` allow-list that grants only what the role needs. The parent loop fans
+> work out to a persona and gets back a conclusion, not the persona's whole transcript. Copy the skeleton
+> below and fill it. (Placeholders are in `{braces}`.) _(Provenance: HumanLayer — subagents as context
+> firewalls; Cognition — read-parallel / write-isolated; Letta — per-agent memory.)_
+>
+> **The five-part contract is fixed by [`../personas/README.md`](../personas/README.md)**, which is the
+> authority — this template is a starting point and deliberately does not restate the rule, for the
+> reason [`../operating/evolution.md`](../operating/evolution.md) gives: one carrier, and the others
+> reach it. All five parts are required: a persona missing one is not a lighter persona, it is an
+> unenforceable one.
+>
+> **Prohibited is never a reach.** It is the one tier no role may act in, so a persona declaring it
+> claims a permission that does not exist for anyone. Stated here, above the skeleton, rather than inside
+> the *Autonomy reach* section — a scaffold whose reach section contains the word is a scaffold that
+> `doctor` has to distinguish from a persona actually claiming it, and the cheapest way to keep that
+> distinction clean is for the generated file not to say it at all. The rule is enforced by `doctor`, not
+> by this sentence.
+>
+> **Two things worth knowing before you write the `tools:` line.** It is a set of **capability classes**,
+> not one host's tool names — binding classes to a host's vocabulary happens in that host's adapter, and
+> writing tool names here is what makes a persona stop being portable. And the binding is **lossy**: some
+> charters survive translation into a tool grant and some do not. A charter that says *does not edit the
+> code under review* becomes a rail; one that says *drafts everything, accepts nothing* is a constraint
+> on what the role may conclude, which no tool list can express. Say which yours is, rather than letting
+> a reader take the frontmatter for the gate.
+
+---
+---
+name: {kebab-case-name}
+description: {The role in one line — what it is for, and what it must not do.}
+tools: {capability classes, comma-separated — default-deny, least privilege for this role}
+---
+
+# Persona — {Name}
+
+## Charter
+
+{What this role is for. Then, just as load-bearing, what it must **not** do — the boundary is the half
+that makes a firewall a firewall. Name the neighbouring role this is easiest to confuse with.}
+
+## Autonomy reach
+
+{The highest tier this role may act in, in **tier vocabulary** — Auto / Propose / Gated — never concrete
+actions. The gate map that binds actions to tiers is workspace policy, and naming an action here would
+move policy into a role. There are only three reaches, and the fourth tier is not one of them; see
+[`core/personas/README.md`](../personas/README.md) for why.}
+
+## Memory scope
+
+{What this role remembers, and where it lands — a directory in the **adopting workspace's own layer**,
+never in the pack or in core. Storage follows ownership. Declared here rather than in a pack manifest
+because the scope is the persona's own field, and a pack distributing per-persona material its adopter
+does not own is the one direction the cascade does not run. Empty until earned is the correct state: a
+scope is a place for facts, not a claim that facts exist.}
+
+## Read / write posture
+
+{Most personas read in parallel; writes are isolated to one place so two agents never clobber the same
+file. Say which this is, and — if it writes — the one place it writes.}
+
+## What this persona's tool grant does NOT enforce
+
+{Required. The half of the charter that is a constraint on judgement rather than on capability, and is
+therefore held by the workspace's gate map and the platform floor rather than by the list above. A
+persona whose limits section is empty is claiming its frontmatter is the gate, which is the one reading
+[`../personas/README.md`](../personas/README.md) exists to prevent.}

package/core/templates/proposal.md

@@ -0,0 +1,27 @@
+# Template — Rule-change proposal
+
+> A **proposal** is how the curated layer changes: agent-drafted, human-owned, merged only through a
+> reviewed (and where possible eval-gated) PR. No rule enters core, a pack, or a workspace except through
+> one of these. _(Provenance: compounding engineering — codify incidents into rules; spec-driven — the
+> human-owned constitution; see `../operating/evolution.md`.)_
+
+---
+
+# Proposal — {the rule, in one line}
+
+**Incident.** {what went wrong, or the recurring friction that motivates this — with a link. A proposal
+without a triggering incident is usually taste, not a rule.}
+
+**Proposed rule.** {the rule as it would read in core / pack / workspace, at the right altitude.}
+
+**Enforcement.** {how it earns its place: hook / compiled gate / Stop-gate / eval — or, if none, the
+argument for why it is worth context-window tokens as prose. Rules that enforce or measure themselves
+beat rules you must remember.}
+
+**Provenance.** {the source or precedent, carried into the rule so it can later be retired — in one of
+the two forms the Workspace Definition defines (`../../spec/workspace.schema.json`, `$defs/provenance`):
+`form=link href={…}` when the incident is visible to everyone who can read the rule, or
+`form=sealed owner={…} date={YYYY-MM-DD} shape={the de-identified failure}` when it cannot leave its
+owner's layer. Neither form present means the proposal is taste; see `../templates/memory-entry.md`.}
+
+**Decision.** {human owner} — accepted | rejected | revised, on {date} — because {…}.

package/core/templates/repo-card.md

@@ -0,0 +1,28 @@
+# Template — Repo card
+
+> A **repo card** is the per-repo layer of the resolution cascade (`core < pack < workspace < repo card
+> < task`): the small, high-value facts an agent needs to work in *this* repository and cannot infer
+> safely. Keep it short — it is loaded often. Copy the skeleton below into a repo and fill it; delete
+> lines that don't apply rather than leaving them blank. (Placeholders are in `{braces}`.)
+
+---
+
+# Repo — {name}
+
+**What it is.** {one or two sentences: the repo's job and its blast radius.}
+
+**Build / test / run.**
+- build: `{command}`
+- test: `{command}`   ← the verify recipe the Stop-gate runs (see `../operating/verification.md`)
+- run:  `{command}`
+
+**Gates.** {actions here that deviate from the workspace gate map — e.g. "migrations require a DBA
+review." Leave empty to inherit the workspace default; see `../operating/autonomy.md`.}
+
+**Layout.** {the 3–6 paths a newcomer agent most needs — not a full tree.}
+
+**Quirks.** {the non-obvious facts that cause wrong changes: the flaky test to rerun, the generated file
+never to hand-edit, the module that looks dead but isn't.}
+
+**Provenance.** {link the card, or any rule in it, back to the incident that earned it — so it can be
+retired when it no longer applies.}

package/core/templates/skill.md

@@ -0,0 +1,57 @@
+# Template — Skill
+
+> A **skill** is a procedure the engine pulls into context on demand, in `SKILL.md` form. Skills are how
+> the engine stays small while still knowing a lot: the kernel is always loaded, a skill costs nothing
+> until its trigger fires. Copy the skeleton below and fill it; delete lines that don't apply rather than
+> leaving them blank. (Placeholders are in `{braces}`.) _(Provenance: AAIF — `SKILL.md` as the
+> distribution plane; HumanLayer — skills-first progressive disclosure. The contract this template obeys
+> is fixed by [`../skills/README.md`](../skills/README.md), which is the authority; this file is a
+> starting point, not a second statement of the rule.)_
+>
+> **The bar, before you write anything.** A skill earns its place only if it **enforces** something,
+> **measures** something, or is worth the tokens it costs when loaded. A procedure that is really a
+> standing rule belongs in [`../operating/`](../operating/) as doctrine; a one-off belongs in a task. A
+> skill nobody triggers is demoted by the librarian, so a trigger you cannot describe concretely is the
+> signal to stop and write something else.
+>
+> **`name` and `description` are the contract, not decoration.** They are the only two fields a host
+> reads before deciding whether to load the body, so `description` has to carry the trigger — the
+> circumstances under which this skill is the right thing to reach for. A description that summarises the
+> body instead of naming its trigger produces a skill that is never selected and then demoted for it.
+
+---
+---
+name: {kebab-case-name}
+description: {What this does, AND when to use it — the trigger belongs here, because this line is what a host reads before loading anything else. One or two sentences.}
+---
+
+# Skill — {Name}
+
+> {One line: what this procedure is for, and the one thing it is not for.}
+
+## When to use it
+
+{The concrete trigger. Prefer something machine-produced — a rail went red, a budget was breached, a
+command exited non-zero — over a judgement call, because a trigger that depends on noticing is a trigger
+that gets missed. If it genuinely is a judgement call, say what the judgement is.}
+
+**When not to use it.** {The neighbouring case this is easy to confuse with, and what to reach for
+instead. Skipping this line is how two skills end up competing for the same trigger.}
+
+## The pass
+
+1. {Step. Imperative, and specific enough that two people following it produce the same artifact.}
+2. {Step.}
+3. {Step.}
+
+## What it produces
+
+{The artifact, and where it lands. If the skill changes no file, say so — a skill whose output is a
+conclusion in the caller's context is legitimate, and leaving it implied is how it acquires an imagined
+side effect.}
+
+## Honest limits
+
+{What this skill does NOT check, cover, or guarantee. Required rather than optional: a procedure that
+lists only what it catches reads as covering everything, and the gap is discovered by whoever trusted it.
+If you cannot name a limit, you have not found it yet.}

package/core/templates/task.md

@@ -0,0 +1,26 @@
+# Template — Task
+
+> A **task** is the atomic unit of work and the atomic unit of context: everything an agent needs to do
+> one thing, and nothing it doesn't. Self-contained, so it can be handed to a fresh window or a subagent
+> without the surrounding conversation. _(Provenance: BMAD — the story file as atomic context unit;
+> spec-driven — testable acceptance criteria; verification-first — the failing test as spec.)_
+
+---
+
+# Task — {title}
+
+**Goal.** {the outcome in one or two sentences — what is true when this is done.}
+
+**Acceptance criteria.** {testable, EARS-style — "when {trigger}, the system shall {response}." Each
+line must map to an observable check.}
+- [ ] …
+
+**Verify.** {the failing test or command that is red now and green when the task is met — this is the
+definition of done, not a description of it. See `../operating/verification.md`.}
+
+**Constraints.** {the gates in the way, the files that must not change, the altitude to match.}
+
+**Context.** {the few links that matter: the repo card, related memory, the incident or ticket. Not a
+document dump — the point of the task file is that it stays small.}
+
+**Lane.** full | triage   {see `../operating/loop.md`.}

package/core/templates/workspace.md

@@ -0,0 +1,81 @@
+# Template — Workspace
+
+> A **workspace** is the per-team layer of the resolution cascade: identity, principles, gate map, verify
+> recipes, definition of done, memory. Core and packs carry the universal best practice; the workspace is
+> where a team's own specifics live, and **they live only here** — core and packs never absorb them.
+> Copy the skeleton below into `workspace.json` at the workspace root and fill it. (Placeholders are in
+> `{braces}`.) _(The binding contract is
+> [`../../spec/workspace.schema.json`](../../spec/workspace.schema.json), with per-slot rationale in
+> [`../../spec/slots.md`](../../spec/slots.md). Those are the authority; this template is a starting
+> point.)_
+>
+> **`init` versus this template.** `init` onboards a **repository** — it asks where that repository's
+> workspace resides, scans the tree, and drafts a workspace shaped by what it found. This template is for
+> the case `init` does not cover: authoring a workspace by hand, or one that governs from outside a
+> repository (a feed-side workspace, a portfolio workspace covering several products). If you are
+> onboarding a repository, run `init` and curate what it drafts; you will get more than this skeleton.
+>
+> **A slot must be a whole file.** Not a fragment, not a heading inside a larger document — because a
+> fragment-addressed slot cannot be link-checked, and a slot nothing can validate is a slot that drifts.
+> That constraint did most of the design work in the Workspace Definition and it binds your workspace too.
+>
+> **`kind` decides what else is required.** A `repository` workspace must declare `tree` — the path to
+> the repository whose claims its repo cards describe — because without it the claims lint has no ground
+> to check against and degrades an entire check class to notes. A `pointer` workspace declares
+> `governed_by` instead and materialises nothing: **one repository is governed by exactly one workspace**,
+> and a pointer is how a repository says which one.
+
+---
+
+```json
+{
+  "portulan": { "spec": "2.7" },
+
+  "name": "{kebab-case-name}",
+  "summary": "{One line: whose workspace this is and what it governs.}",
+  "kind": "{repository | demo | portfolio | pointer}",
+  "tree": "../",
+
+  "slots": {
+    "identity": "identity.md",
+    "principles": "principles.md",
+    "gates": "gate-map.md",
+    "dod": "dod.md",
+    "memory": "memory/",
+    "repos": "repos/",
+    "tasks": "tasks/",
+    "handoffs": "handoffs/",
+    "proposals": "proposals/"
+  },
+
+  "gates": "gates.json",
+
+  "verify": {
+    "default": "{recipe-id}",
+    "recipes": [
+      {
+        "id": "{recipe-id}",
+        "run": "{the command, as it would be typed from the repository root}",
+        "requires": ["{tool}"],
+        "doc": "verify/README.md"
+      }
+    ]
+  },
+
+  "packs": []
+}
+```
+
+> **Delete the optional slots you do not have**, rather than pointing them at empty directories — a slot
+> that resolves to nothing is a promise the tree cannot keep, and `doctor` fails a slot pointing at
+> something absent. Add them back when the directory has content.
+>
+> **The `verify.default` is the recipe the Stop-gate runs**, so it is the one that decides what *done*
+> means here. Two properties it must have, both learned the expensive way: it must exit **2** rather than
+> 0 when it could not run — a recipe that cannot run must never look like one that ran and passed — and
+> it must not be a stub that exits 0 while you decide, because that puts a false green under every gate
+> from the day the workspace was created.
+>
+> **`packs` is a list of `category/name` references, and declaring one is what composes it.** A pack you
+> list can add gate restriction and verify recipes to this workspace, so list only packs whose code you
+> are willing to run.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sleepy_panda_srl/portulan",
+  "version": "0.1.0",
+  "description": "Portulan — an agentic-engineering framework whose product is its files. The CLI wraps the file-based mechanics for hosts beyond Claude Code.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "portulan": "cli/portulan.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "cli/",
+    "core/",
+    "spec/",
+    "packs/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "!cli/*.test.mjs",
+    "!cli/fixtures",
+    "!cli/eval-bundle.mjs",
+    "!cli/eval-license.template.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sleepy-panda-srl/portulan.git"
+  },
+  "homepage": "https://github.com/sleepy-panda-srl/portulan",
+  "bugs": {
+    "url": "https://github.com/sleepy-panda-srl/portulan/issues"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "agentic-engineering",
+    "claude-code",
+    "workspace"
+  ]
+}

package/packs/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "portulan-checkpoints",
+  "displayName": "Portulan checkpoints",
+  "version": "0.2.1",
+  "description": "The supervised-build checkpoint ritual as a pack: session-open, pre-commit and milestone-close, each graded by a context that has not seen the implementation, in a fixed verdict vocabulary.",
+  "author": {
+    "name": "Sleepy Panda SRL",
+    "url": "https://sleepypanda.ro"
+  },
+  "repository": "https://github.com/sleepy-panda-srl/portulan",
+  "license": "Apache-2.0",
+  "keywords": [
+    "portulan",
+    "pack",
+    "rituals",
+    "supervision"
+  ],
+  "skills": [
+    "./rituals/checkpoints/skills/"
+  ]
+}