@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/skills/obk-arch/NOTICE.md

@@ -0,0 +1,134 @@
+<!-- Attribution for the sources this skill was built from. Kept out of
+     SKILL.md so it is not read into context on every use; it travels with
+     the skill directory, which is what the licences require. -->
+
+# Sources and licences
+
+The skill `obk-arch` was consolidated for this kit from these, all MIT, with
+thanks:
+
+- **Cursor pstack**, `architect` with its `runner-prompt`, `design-red-flags`
+  and `rationale-template` references. Writing the caller's usage and two or
+  three real call sites before the types, with the usage as the specification
+  and the sketch reconciled to it; data structures first with every dominant
+  access pattern traced through the proposed shape, and "we'll add an index
+  later" meaning the shape is wrong now; designing it twice with at least two
+  structurally distinct whole-shape candidates before synthesis; comparing on
+  interface depth; the red flags (callers coordinating several methods for one
+  operation, options exposing internal stages, learning the interface not
+  saving you from learning the implementation, information leakage, temporal
+  decomposition, pass-through methods); the rationale in the form "we accept X
+  in exchange for Y" with at least one alternative and why it lost, or "the
+  only viable shape, because..." where the constraints forced it (from its
+  `rationale-template`); keeping candidates genuinely apart rather than
+  converging on a safe middle (from `runner-prompt`); naming
+  anything a later reader might take for an oversight; and the scrap tells (the
+  repeated workaround, unrelated edge cases each needing a branch, escape
+  hatches in the types, the lock reflex where nothing was meant to be shared,
+  callers needing the internal rules), with deviations treated as signal and a
+  few edge cases not condemning a design.
+- **Cursor pstack**, `architect`'s `runner-prompt` further to the above.
+  Grounding the design in what the code actually touches before sketching, and
+  what a sketch is (types and signatures with unimplemented bodies, a reader
+  able to trace input to output from the signatures alone); encoding invariants
+  in types ahead of runtime checks ahead of comments; validating at boundaries
+  and trusting types inside; one source of truth per invariant, derived rather
+  than kept in step; and asking what happens if an operation runs twice or
+  crashes halfway.
+- **Cursor pstack**, `figure-it-out` further to the above. Capturing the
+  baseline before the change so the check reads as the old value against the
+  new; verdicts of verified, not verified or inconclusive with inconclusive not
+  being a pass; inspecting the artefact rather than a report of it; and
+  suspecting the observation method when something passes too easily.
+- **Cursor pstack**, `blast-radius` further to the above. Looking where a
+  symbol search stops: the library's own source and its pinned version, when
+  things run, the shape of what an interface returns, a column, a wire format,
+  another language reading the same bytes, a feature flag; giving each risk a
+  real likelihood and a real cost; and listing separately what was checked and
+  cleared, since a search that finds nothing is still a result.
+- **Cursor pstack**, `create-verification-skill`. The whole of making a thing
+  runnable and drivable, which the owner asked to live inside this skill rather
+  than have one of its own: interviewing the repository rather than the user
+  about surface, how it starts and how you know it is ready, how to drive it
+  without a person, what evidence can be captured, and whether two can run side
+  by side; the read-only check that says whether an instance is worth driving;
+  the proof standards (the real user path rather than an internal setter or a
+  test-only endpoint, the action and the resulting state rather than the final
+  screen, side effects verified alongside what is visible, stand-ins only where
+  a production boundary already isolates the thing); finding out what a dry run
+  actually skips by observing rather than trusting its name; cleanup that
+  removes what the run started and never the evidence, killing what you started
+  rather than by name; and running the instructions once end to end, because
+  something never executed is a draft rather than a deliverable. Also fixing,
+  or saying precisely what stopped, a checkout that does not build or start
+  before writing the recipe against it,
+  preferring stable handles over positions and coordinates, and the feature map
+  (a short list of what the thing does for someone, one entry per feature),
+  which that skill's own users praised most because an agent stops searching
+  the codebase for where things are. Kept here in that reduced form rather than
+  as its own generated directory.
+- **Cursor pstack**, `principle-sequence-verifiable-units`, `figure-it-out`,
+  `blast-radius`, `principle-foundational-thinking`, `principle-model-the-domain`,
+  `principle-exhaust-the-design-space` and the `poteto-mode` planning playbooks.
+  Ordering work as small units each ending in a state you can check and not
+  advancing until it is green, with the reason (a break caught at the unit that
+  caused it is cheap, one caught after a batch is buried); done as a falsifiable
+  predicate stated before the run and never relaxed to declare victory (the
+  last from the `autonomous-run` playbook);
+  sequencing the riskiest unknown first; every box naming the evidence that
+  checks it, ticked only when that evidence exists; skipping the plan when the
+  change is one or two files with an obvious approach; settling an open
+  question by prototype before writing; data structures first with types and
+  data converging; a structure that carries the domain (a state machine, a
+  lookup table, a typed object) making invalid states impossible and deleting
+  branches, and the other side, not forcing an abstraction that removes no
+  branch, no duplicated rule and no invalid state, with the tell that the
+  modelling was skipped; the cases where exploring the design space is not worth it; and the
+  blast-radius ladder (said so, pointed at the line, showed the bad case
+  cannot happen, ran it, reproduced it) with "listing the callers is not the
+  job", the one fact a change is safe because of, and anything short of
+  running it said rather than written up as settled.
+- **mattpocock/skills**, `codebase-design` with `DEEPENING` and
+  `DESIGN-IT-TWICE`, `domain-modeling` with its `ADR-FORMAT`, `prototype` and
+  `to-tickets`. The three questions to put to an interface (fewer ways in,
+  simpler arguments, more hidden behind it) and the interface as everything a
+  caller must know; the three conditions that must all hold before a decision
+  earns a lasting record of its own
+  (hard to reverse, surprising without the context, and the result of a real
+  trade-off) with what each one rules out; from `domain-modeling`, sharpening
+  a term that is doing too much work, forcing a boundary open with a concrete
+  scenario, and checking a claim about the domain against the code; from
+  `prototype`, being trivial to start, keeping nothing between runs, showing
+  the state after every action, and keeping only the decision it produced;
+  from `DESIGN-IT-TWICE`, combining the best of the candidates; the deletion
+  test,
+  the interface being the test surface, and one adapter meaning a hypothetical
+  seam against two meaning a real one; designing for testability by accepting
+  dependencies rather than creating them, returning results rather than causing
+  effects, and keeping the surface small; the four constraints that make
+  candidates genuinely different; how the dependency decides the way you test
+  across a seam, and "replace, don't layer" with the old shallow tests deleted
+  once tests exist at the deeper interface; vertical slices that cut a narrow
+  but complete path through every layer, each demoable on its own and sized to
+  one fresh context, with prefactoring first; expand, migrate and contract as
+  the exception for a change that has to happen everywhere; and a prototype
+  being throwaway code that answers a question, with the polish skipped on
+  purpose.
+
+Left behind on purpose: the multi-model arena and its runners, fixed model
+choices, the phase todolist and its ceremony, tracker and pull-request
+machinery, the generated report formats, and the trigger that fires a design
+review on any change crossing a function boundary. This skill is reached for
+when there is a shape to get wrong, not on every change.
+
+What the owner said, and how it shaped this: he asked for a very light part on
+what is wanted and on dividing the work, leaving the details and the tracking
+to the user (research-pack dialogue, 2026-09-19 19:09). The five items of the
+note are the proposal he was given then; three further items that had been
+added since, with no source behind them, are gone. He wanted the design to
+include a clear effort on the big test step so the app is runnable and
+testable (2026-09-19 18:54, and 2026-09-20 02:21), which is why that part stays in full. He agreed
+that the source's strict vocabulary be dropped for plain words (18:50), so the
+list of defined terms is gone and the ideas stay. He did not want a
+blast-radius skill of its own (18:08), so what is kept of it is a short part.
+A small reshaping being part of the change follows PRD 7.3.

package/skills/obk-arch/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: obk-arch
+description: >-
+  Shaping a piece of work before building it: a short note of what is wanted
+  and what done means, deciding the shape from the usage and the data with
+  more than one candidate, making the thing runnable and testable so anyone
+  can find out whether it works, and cutting the work into pieces that each
+  end in a check. Use when starting something new, planning a feature, adding
+  a public interface or a new data shape, making a choice that is hard to
+  undo, or when a change is big enough that jumping into the code would settle
+  the shape by accident.
+---
+
+# Shaping work before you build it
+
+Four things: say what is wanted, decide the shape, make sure the thing can be
+started and driven so anyone can tell whether it works, and cut the work into
+pieces that each end in a check. The third is what makes the rest real.
+
+None of this needs a particular document, tracker or format. Where a project
+has one, use it; where it does not, a few lines in the right place do the job.
+
+Reach for this when there is a shape to get wrong: something new, a public
+interface, a new data shape, a choice that will be expensive to undo. Not for
+work where the pattern is already set, a bug fix with a clear target, or a
+change the constraints leave only one way to make. When it is one or two files
+and the approach is obvious, say so and go and do it. A plan longer than the
+work it plans is a cost with no return.
+
+These are defaults for work where nothing says otherwise. A user who asks for
+something else gets what they asked for; say which of these you left and why.
+
+## Say what is wanted
+
+A very light note: short enough to be read, long enough that someone else could
+act on it. It says:
+
+- **The problem.** What is wrong or missing now, not the solution wearing a
+  problem's clothes.
+- **Who it is for.** The person who has that problem, which is often not the
+  person asking.
+- **What they can do once it is finished**, as behaviour someone could observe
+  from outside.
+- **How we will know it works**, written as checkable statements. These are the
+  ones that matter most: they become the acceptance tests when the work starts
+  and the "what was asked" a reviewer reads it against, so write them as
+  something you could be wrong about, and never loosen one to declare victory.
+- **What we are not doing.** The things nobody said aloud are the things that
+  get built by accident.
+
+No format and no home: an issue, a file, a message, a page in whatever the
+project already uses. And if a proper note already exists, use that one rather
+than writing a second.
+
+## Decide the shape
+
+### Sharpen the words while you are at it
+
+When a term keeps doing heavy lifting ("account", "active", "ready"), say what
+it means here and what it does not; where that stays vague, a concrete scenario
+forces the boundary open. Check a claim about how things work against the code
+rather than accepting it.
+
+### Ground it first
+
+Before sketching anything, build a real model of what the new code touches: the
+modules it will sit between, how data reaches them now, what already owns the
+rules you are about to write. Naming a file is not grounding. Trace it.
+Skipping this is what produces a design that is elegant and does not fit.
+
+Where the design redefines who owns what, find out why the current shape is
+the way it is first, so the reason becomes a constraint you are choosing to
+overrule rather than one you never saw. Greenfield with nothing around it is
+the one case to skip.
+
+### What a sketch is
+
+Types, signatures and module boundaries with nothing implemented: bodies that
+say "not implemented", a comment where the tricky logic will go, and a line on
+each saying what it is for and what it must keep true. The test of a good one
+is that a reader can follow the data from input to output by reading the
+signatures alone.
+
+That is what you compare, argue about and throw away, cheaply, which is the
+point of doing it before the code.
+
+### Usage first, then the data, then the types
+
+Write the calls before the types: two or three real call sites, and how
+someone would use it if they were reading about it for the first time. The
+usage is the specification. When the sketch and the usage disagree, change the
+sketch.
+
+Then the data. Get the shape of it right before the logic, and trace every way
+it will be read and written through the shape you are proposing. If the answer
+to one of those is "we can add an index or a cache for that later", the shape
+is wrong now, not later.
+
+Types and data converge. Three similar lines still beat an abstraction
+invented before there was anything to abstract.
+
+Five things worth deciding while the shape is still cheap to change:
+
+- **Let a structure carry the domain.** A state machine rather than scattered
+  flags, a lookup table rather than branches spread across files, a typed
+  object rather than loose parameters: the right structure makes invalid
+  states impossible to write and deletes branches.
+
+- **Put the rules in the types where you can.** A type that cannot be misused
+  beats a check at runtime, which beats a comment asking people to be careful.
+- **Check at the edges and trust inside.** Validate where data enters, then let
+  the inside assume it is good. Scattering the same check through the middle
+  means no one place is responsible for it.
+- **One home per rule.** Derive the rest rather than keeping two copies in
+  step; two copies of one fact is a bug with a delay on it.
+- **Ask what happens if it runs twice, or stops halfway.** If the answer
+  depends on what the last attempt left behind, something is missing that puts
+  it back in order, and that is a design question, not an operational one.
+
+### Design it twice
+
+Produce at least two structurally different candidates before you choose, even
+when the first looks sufficient. Whole shapes, not variations inside one shape.
+Two ways to arrange the same idea teach you nothing.
+
+A cheap way to get real difference is to give each candidate a constraint of
+its own and see what it forces:
+
+- the smallest possible interface, one to three ways in, as much behind each as
+  will fit;
+- the one that bends to the widest range of uses;
+- the one that makes the most common case trivial and lets the rest be awkward;
+- the one that puts whatever varies behind a port with adapters either side.
+
+Keep them genuinely apart while you make them; a safe middle drafted early
+defeats the point. Then compare on how much each hides, prefer the shape that
+puts more behaviour behind a smaller surface (that is what a caller is buying),
+and take the best parts of the others into it where they combine.
+
+### Judging an interface
+
+The interface is everything a caller has to know to use a piece correctly: not
+only the signature, but the order things must happen in, what errors come out,
+what it needs and what it costs. A good one gives a caller a lot of behaviour
+for a little of that. Three questions do most of the work: can it have fewer
+ways in, can the arguments be simpler, and can more be hidden behind it?
+
+### Three tests that settle most of it
+
+- **The deletion test.** Imagine the module gone. If the complexity goes with
+  it, it was a pass-through. If the complexity reappears in every caller, it
+  was earning its place.
+- **The interface is the test surface.** Callers and tests cross at the same
+  place. If you find yourself wanting to test past the interface, the shape is
+  probably wrong.
+- **One adapter is a hypothetical port; two is a real one.** This one is about
+  pluggability, not about whether a module should exist. Before putting an
+  interchangeable boundary in (a port with adapters either side), ask what the
+  second adapter is; production plus a test double is the usual honest pair. If
+  there is only ever one, you have added a layer to swap something that never
+  gets swapped. Pure computation needs no adapter at all: merge it and test it
+  through its interface.
+
+  Whether a module earns its place is a different question, answered by the
+  deletion test and by how much it hides. A module with one caller can be
+  entirely right, hiding an invariant, a rule or a state machine that would
+  otherwise sit in the middle of something else. One caller is not one adapter,
+  and counting callers is not this test.
+
+### Signs the shape is wrong
+
+- A caller has to call several things in the right order to do one thing.
+- The options expose the stages inside rather than what the caller wants.
+- Learning the interface does not save you from learning the implementation.
+- Several modules depend on the same decision made inside one of them.
+- Modules named after the order things happen rather than what they know. The
+  same rule then gets repeated in each step.
+- A function that passes the same arguments on to something with the same
+  shape, adding a layer and hiding nothing.
+
+And the other way: do not force it. Boring, local and clear is right where the
+thing is unlikely to grow, and an abstraction that removes no branch, no
+repeated rule and no impossible state is just indirection. The tell that this
+step got skipped is the next feature adding one more branch to an if-else
+chain, or a second flag that has to be kept in step with the first.
+
+### Write down what you chose
+
+One short paragraph, where the next person will find it: the problem, how it
+is used, the shape, the trade-offs accepted (in the form *we accept X in
+exchange for Y*), at least one other shape you considered with a line on why
+it lost, and anything still open.
+
+Where the constraints left only one shape, say that instead: "the only viable
+shape, because...". Name anything a later reader might mistake for an
+oversight.
+
+A lasting record of its own, kept beyond the change, earns its place when all
+three are true: it is hard to reverse, it is surprising without the context,
+and it came out of a genuine trade-off. Miss one and the paragraph is enough.
+
+### When to build a throwaway instead of arguing
+
+A prototype answers one question and is then deleted. No question, no
+prototype: "let's try something" is not a question.
+
+Skip the polish deliberately: no tests, no error handling beyond what makes it
+run, no abstractions. Say out loud that it is throwaway, so nobody tries to
+harden it or ship it.
+
+Three things make one actually useful. It has to be trivial to start: one
+command, or a file someone double-clicks; anything that needs explaining will
+not get run by the person whose opinion you wanted. It should keep nothing
+between runs, because persistence is usually the thing being questioned rather
+than something to lean on. And it should show its state after every action, so
+what changed is visible rather than inferred.
+
+The observation is the result, not the code. Keep the decision it produced,
+throw the prototype away or park it somewhere clearly marked, and write the
+real thing from the beginning, test first.
+
+## Make it runnable and testable
+
+This is the part that makes an agent able to check its own work at any size
+above a single function, and it belongs in the design rather than after it.
+When a whole application is designed, or a feature is planned, the end-to-end
+test work is planned at the same time and with the same care, and written, like
+any other test, by someone other than the implementer.
+
+Answer these about the thing you are shaping, from the code where you can
+rather than by asking:
+
+- **Surface**. What does a person actually touch? A screen, a command, an
+  endpoint, a library. If there are several, pick the main one and name the
+  rest.
+- **Start**. How does it come up, and how do you know it is ready? A log line,
+  a port answering, a prompt appearing. Guessing with a pause is not knowing.
+- **Drive**. How can something interact with it with nobody watching?
+  Whatever the project already has first; a general harness only after that.
+- **Observe**. What evidence can be captured? Output, an exit status, a file,
+  a stored row, a message sent, a picture of the screen.
+- **Isolate**. Can two of these run side by side, with their own ports and
+  data? If not, say so plainly, because refusing to drive a shared instance is
+  better than corrupting the one someone is using.
+
+If the thing does not build or start as it stands, either fix that first or say
+precisely what stopped it: which command, which failure, what was missing.
+A recipe written against a broken checkout and presented as working teaches the
+next reader the wrong steps, confidently. A recipe written against one and
+marked as not yet run is still worth having: it says what the proof will be
+once someone can get the thing up, which is most of the value. What it must not
+do is claim to have been proven. And repairing whatever is broken is its own
+piece of work, not something to absorb quietly into this one.
+
+Prefer handles that survive: the name of a thing, a label, a route, a prompt
+the program prints. Positions, orders and coordinates all drift, and a recipe
+pinned to them fails for reasons that have nothing to do with the code.
+
+Worth writing beside the recipe: a short list of what the thing actually does
+for someone, one entry per feature (how to reach it, how to drive it, and what
+state proves it worked). It is the part people find most useful later, because a
+proof that exercises whichever entry point was convenient is incomplete when
+the list names others. Start with the few that matter and let it grow.
+
+Worth having beside that: one read-only check that answers "is this instance
+worth driving at all" (is it up, is it the build I think, is that port ours).
+Run it first whenever something looks strange, before debugging the thing
+underneath.
+
+What a proof has to do, which is where most of them fail:
+
+- drive the path a person would actually take, not an internal setter or a
+  door that exists only for tests;
+- capture the action and the state it produced, not only the final screen;
+- check the effects as well as what is visible: what was written, sent,
+  recorded;
+- stand in for something only where a real boundary already separates it.
+
+Where the safe path is a dry run, find out what it genuinely skips by watching
+what happens (files, network, state) rather than trusting its name.
+
+Clean up what a run started, and never by name: stop what you started. Cleanup
+takes the instance away and leaves the evidence where it said it would be.
+
+Whatever you write down so that the next agent can do this, run it once, end to
+end, before you hand it over. Instructions nobody has executed are a draft.
+
+Where the work is about changing a number rather than adding a behaviour, take
+the measurement before you start, so the check reads as the old value against
+the new one rather than as a number with nothing to compare it to.
+
+And be strict about what counts. A check comes back verified, not verified, or
+inconclusive. And inconclusive is not a pass. Read the artefact rather than a
+report about it. When something passes more easily than you expected, suspect
+the way you are observing before you believe the result: that is the shape of a
+check that is not actually looking.
+
+### Designing so this is possible
+
+Accept what you depend on rather than building it inside. Return results
+instead of reaching out and changing things. Keep the surface small: fewer ways
+in means less to set up.
+
+How you test across a boundary follows what is behind it. Pure computation:
+no boundary needed, test through the interface. Something with a good local
+stand-in: use the stand-in and keep the boundary inside. Your own service
+across a network: a port at the boundary, a real adapter for production and an
+in-memory one for tests. Something you do not own at all: a port, and a
+stand-in for it.
+
+Once behaviour is covered through the interface above, tests against the pieces
+inside it prove the same thing twice; retiring them, like any change to
+tests, is for whoever wrote them.
+
+## Cut the work into pieces
+
+Each piece ends in a state you can check, and a piece that depends on it does
+not start until it is green. A break found at the step that caused it is cheap; the
+same break found five steps later is buried under everything built on top of
+it.
+
+- **Each piece is a narrow but complete path** through every layer it touches,
+  not one layer done across the whole feature. A finished piece can be shown
+  or checked on its own.
+- **Sized to what one fresh context can hold**, because a piece that does not
+  fit gets done half-remembered.
+- **Ordered by what you will learn.** The riskiest unknown first, so that
+  being wrong about it is cheap.
+- **Prefactor where it helps.** Make the change easy, then make the easy
+  change. A small reshaping is part of the change; a large one is a piece of
+  its own, before the feature.
+- **The first piece gets the thing running and testable as a whole**, even if
+  it does almost nothing yet. That is where the end-to-end test work lands, and
+  everything after it is checked through what it puts in place.
+- **Each piece names the evidence** that says it is done: a test run, a file, a
+  line of output, a command. It is done when the evidence exists, not when it
+  feels done.
+- **Say which pieces depend on which, and which can run side by side.** Two
+  people, or two sessions, can take independent pieces at once; a dependency
+  nobody wrote down turns into two people editing the same thing.
+
+The exception is a change that has to happen everywhere at once. Sequence it as
+expand, migrate, contract: add the new form beside the old so nothing breaks,
+move the callers over in batches sized by what each batch touches, then delete
+the old form once nothing calls it. If a piece deliberately leaves something
+broken in between, say which piece and for how long.
+
+## Before you build on it
+
+Find out what the shape breaks elsewhere. Listing the callers is not the job;
+the breakage a search does not show is (a changed order, a new precondition, an
+assumption two things shared). Most plans that look risky are safe because of
+one fact: find it, since if it holds most of the risky cases clear at once.
+
+Look where a symbol search stops, because that is where the surprises are: the
+library you call, at the version actually pinned; when things run, not only
+what calls what; and what two things agree on without naming each other (the
+shape of what an interface returns, a stored column, a wire format, something
+in another language reading the same bytes, a setting that turns a path on).
+Give each risk you keep a real likelihood and a real cost.
+
+Then say how far you proved it: you said so, you pointed at the line, you
+walked the bad case through, you ran something that would have failed if you
+were wrong, or you saw it in the running thing. Short of running it, say so
+rather than writing it up as settled, and list what you checked and cleared as
+well as what you kept.
+
+## When the shape turns out to be wrong
+
+Deviations from the sketch are signal, not friction to absorb quietly. A
+function that needs a parameter the sketch did not anticipate is asking a
+question: was the sketch wrong, was the requirement missed, or is the
+implementation reaching for something that is not its business?
+
+The signal is a pattern rather than a single instance:
+
+- the same shape of workaround appearing in unrelated places;
+- several unrelated edge cases that each need their own special branch;
+- types needing escape hatches to compile at all;
+- reaching for a lock where the sketch said nothing was shared;
+- callers having to know the rules inside to use it correctly.
+
+A few edge cases do not condemn a design; some problems really are knotty, and
+complexity in the problem is not complexity in the design. But when the pattern
+is there, say so and redesign, rather than paying it off one branch at a time.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-bot-building/LICENSES.md

@@ -0,0 +1,21 @@
+<!-- The licences of the sources this skill was consolidated from. They travel
+     with the skill directory because the licences require it of anyone who
+     distributes the material. NOTICE.md says what was taken from each source;
+     this file carries the permission notices themselves. -->
+
+# Licences of the sources
+
+`obk-bot-building` names its sources in [NOTICE.md](NOTICE.md).
+
+## Sources that need no third-party notice
+
+This skill reproduces no third-party text. It was written from this kit's own
+PRD and ADRs, from the owner's own words in the research pack, and from ideas
+restated in our own words.
+
+Those ideas came from material that carries no licence: a knowledge base and a
+hosted bot product's own marketplace and documentation pages, gathered in the
+research pack's `grok-bot-lessons.md`. Because no licence is attached to them,
+nothing of theirs is copied here, and there is accordingly no permission notice
+to reproduce. Credit for the ideas is given in NOTICE.md instead, which is
+where it belongs.

package/skills/obk-bot-building/NOTICE.md

@@ -0,0 +1,113 @@
+<!-- Attribution for the sources this skill was built from. Kept out of
+     SKILL.md so it is not read into context on every use; it travels with
+     the skill directory, which is what the licences require. -->
+
+# Sources and licences
+
+`obk-bot-building` reproduces no third-party text. What it took from outside
+this kit, it took as an idea and wrote again in its own words, for the reason
+given under "Ideas taken from material with no licence" below.
+
+## The owner's own words
+
+The charter is three questions because he settled it at three. His word on the
+proposal that the interview happens once at a bot's creation and asks what the
+bot owns, what good work looks like, and what it must ask about first, in the
+research pack's session dialogue: "looks good for charter interview."
+
+Two other lines of his shape this skill. On what a bot is allowed to do: he is
+"building bot to allow agency by itself but in the boundary and contract we are
+creating, not freely", which is why the limits section here reads as a boundary
+to act inside rather than as a leash. His one-liner remark ("I expect to have
+one liner the user can send to LLM, and then the rest is done by AI") was about
+setup, not the interview, and is no longer used for it; the interview follows
+his own grilling instruction instead (below).
+
+On bringing in a session they already run: "yes the session history shall be
+able to resume, i.e., resume an external session, the rest is best effort
+migrated with llm capability", and, correcting a restatement of it, "as the
+setup is done via llm, including future setup via the bot manager, the llm does
+best effort to help user migrate". That is where "best effort, and say so
+plainly" comes from.
+
+## This kit's own design
+
+The PRD and the ADRs carry the rest: the line-up suggestions and the
+role-to-skills guidance (PRD 6.8, ADR 0009, which puts that table in the
+management skill), a session's settings and the rule that the kit never
+hardcodes a model id, the approval levels and that the widest one is used only
+when the user asks for it in plain words, the two plain defaults that no
+silent fallback happens and that a role limit such as "read-only, does not
+modify" is a normal part of a charter (PRD 6.4 and 6.6), and pinning an online
+skill source to a version with a word about what a source carrying scripts or
+hooks means (PRD 6.7).
+
+## Ideas taken from material with no licence
+
+The research pack's `grok-bot-lessons.md` gathers how one hosted bot product is
+run. Its material comes from a knowledge base and from that product's own
+marketplace and documentation pages. No licence is attached to those pages, and
+the pack's own caution records that the marketplace entries were summarised by
+a fetch tool rather than read verbatim. So no text of theirs is reproduced
+here, and none of it was read as text worth copying. What was taken is the
+idea, restated:
+
+- that a bot is a job somebody holds rather than a prompt that came out well,
+  and is named after a job a person could hold;
+- that the thing worth writing down is what it owns, what good looks like, and
+  what it must not do without asking;
+- that an interview at creation is what writes that down;
+- that a bot an existing one could own the work of should not be created;
+- that a role needing several unrelated verbs is more than one role, that the
+  split goes by domain rather than by how much work there is, and that a
+  specialist is worth adding only when a real bottleneck has shown up: a noisy
+  shared context, a bot that cannot review its own work, or permissions that
+  have diverged;
+- that instructions have three lifetimes, the durable role, the one assignment
+  and the reusable procedure, and that a one-off correction must not quietly
+  become a rule.
+
+## What was deliberately not taken
+
+That source's creation interview fills a fixed list of about ten fields. This
+skill asks three questions and stops. The owner settled the charter at three,
+and the rest of what a bot needs is settings, which are not an interview.
+
+Its bot-classification vocabulary is not here either; reviewing a fleet that
+already exists is a different job and lives in `obk-fleet-review`.
+
+## Sources that need no third-party notice
+
+Everything above is either this kit's own design, the owner's own words, or an
+idea restated in our own words from material that carries no licence. Nothing
+in this skill reproduces a third party's text, so there is no permission notice
+to pass on. See [LICENSES.md](LICENSES.md).
+
+## What the re-validation changed (#156)
+
+- The charter questions are asked together, each with a drafted answer, not
+  one at a time: the owner asked to be asked three questions at a time with a
+  recommended answer (research-pack dialogue, 2026-09-19 13:24, with matt's
+  grilling loaded), and
+  his usage review complains of one question per turn.
+- The answer handed back is the roster card PRD 6.8 decides (name, harness,
+  model and effort, a two-line charter, one hard limit).
+- The skills for each role are named, since ADR 0009 puts that choice in the
+  management skill.
+- What the command line does and does not do, checked against `obk --help`:
+  `obk skills fetch` was missing; a charter, settings or list change is an
+  edit plus `obk rules build` or `obk skills build`; pausing or retiring has
+  no command. Each management action is committed (PRD 6.10). Issue #158 later
+  gave changing, pausing and retiring their commands, and the hand edit is
+  left for the special case, said so.
+- A change of model, effort or approval reaches a session only by `obk
+  restart`, on the user's word, and a whole-fleet restart is done from the ops
+  tab (PRD 6.5).
+- Bringing in a session: the outside id goes into the book by hand, and a
+  resume across folders is to be tried before it is promised.
+- Cut: a paragraph restating the opening, and two sentences of framing.
+- Memory per bot is the owner's decision of 2026-09-23 (issue #211): a bot may
+  turn on its harness's memory for itself, since the owner's global setting is
+  off. The three Claude Code keys, and that without `autoMemoryDirectory` every
+  bot in the repo shares one memory, were measured live and are in the tech
+  notes; Codex's memories are the user's and cannot be one bot's.