@ketecode/loom 0.1.0 → 0.2.0

package/skills/contract-drafting/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: contract-drafting
+description: Assembles first-draft commercial agreements, namely master services agreements, NDAs, statements of work and GDPR-style data processing agreements, by filling the organisation's own clause template from a structured term sheet, logging every departure from the standard position in a deviation register with its risk and approver, and producing a plain-language redline summary, with a mandatory gate that a qualified lawyer reviews the draft before anyone signs or sends it. Use when you need a first draft of an MSA, NDA, SOW or DPA from your template and agreed terms, when the other side's paper must be compared against your playbook, or when preparing a summary of changes for legal sign-off.
+license: MIT
+compatibility: Any Agent Skills host. Works on the user's templates and documents (Markdown, plain text or .docx through the host's document tools). Not legal advice; every output is a draft for a qualified lawyer to review.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Contract drafting
+
+Produce a clean draft that says exactly what was agreed, in the organisation's own approved language, and make every deviation visible so a lawyer can review the draft quickly. You assemble and flag; you never decide that a term is legally acceptable.
+
+## Lawyer-review gate (mandatory)
+
+Every output from this skill is marked `DRAFT - FOR LEGAL REVIEW - NOT FOR SIGNATURE`. Keep that marking until the user confirms a qualified lawyer has approved the draft. **Never** remove it, send the draft to the counterparty, or call it final on your own.
+
+**Stop and tell the user a lawyer must handle it** (do not draft the clause yourself) when:
+
+- There is no approved template for the agreement type or the clause, and the user asks you to write legal terms from scratch.
+- The governing law, jurisdiction or a party's country is one the template was not written for.
+- The deal touches regulated areas: personal data transfers outside the EEA/UK, health data, financial services, export-controlled goods, employment, consumer contracts, government contracts, or competition-sensitive terms (exclusivity, non-competes, pricing between competitors).
+- The term sheet asks for unlimited liability, an uncapped indemnity, IP assignment of the organisation's core IP, or a change to any clause the template marks "non-negotiable".
+
+## 0. Gather inputs
+
+1. The template: the organisation's own clause library or standard form for this agreement type, with its version. If the user has none, see the gate above.
+2. The playbook, if there is one: preferred position, acceptable fallbacks and walk-away for each key clause.
+3. The term sheet, as structured fields. The field list per agreement type is in `references/term-sheets.md`. Ask for every missing required field; never fill a commercial term with a guess.
+4. The counterparty's draft or redline, if you are comparing their paper against yours.
+
+## 1. Assemble the draft
+
+1. Copy the template; do not rewrite its clauses for style. Approved language is approved because it was reviewed.
+2. Fill placeholders from the term sheet only. Party names must be full legal names with entity type and registration details as the user supplied them.
+3. Keep defined terms consistent: every capitalised term is defined once and used with the same spelling. Check that every cross-reference points to a clause that exists after edits.
+4. Keep the document order the template uses. Schedules (SOW, pricing, DPA, service levels) attach to the master agreement and the order-of-precedence clause says which wins on conflict.
+5. Where the term sheet asks for something the template does not say, do not invent wording. Insert `[DEVIATION D-n: <what is requested>]` and log it.
+
+## 2. Deviation register
+
+Log every place the draft differs from the template or the playbook's preferred position:
+
+```
+ID | clause | standard position | requested / drafted position | why (business reason) | risk (low | medium | high) | playbook fallback? | approver needed | status
+```
+
+Rules for the risk rating:
+
+- High: liability caps, indemnities, IP ownership, data protection, termination for convenience, exclusivity, governing law, anything outside the playbook.
+- Medium: payment terms, warranties, service levels and credits, acceptance, notice periods, renewal.
+- Low: dates, contact details, administrative wording.
+
+When comparing the counterparty's paper, log each of their changes the same way, with the playbook position next to it.
+
+## 3. Redline summary
+
+For the reviewer, in plain language, ordered by risk:
+
+1. One paragraph: deal, parties, agreement type, template version, governing law.
+2. A table of deviations (from the register), high risk first, each with one sentence on what it means in practice ("we would owe them up to 12 months of fees if a data breach is our fault").
+3. Missing information and open questions.
+4. Clauses that need specialist review (data protection, tax, export, employment).
+
+Produce a tracked-changes or comparison document against the template when the host's document tools allow it; otherwise list changes clause by clause.
+
+## 4. Agreement-type checks
+
+Before handing over, run the checklist for the agreement type in `references/term-sheets.md`. Short version:
+
+- **NDA:** mutual or one-way; definition of confidential information and exclusions; permitted use and disclosees; term and survival; return or destruction; no licence granted; remedies.
+- **MSA:** scope and order of precedence; fees, invoicing and payment; warranties; liability cap and exclusions; indemnities; IP ownership and licences; confidentiality; data protection hook to a DPA; term, renewal and termination; insurance; governing law and disputes.
+- **SOW:** deliverables, milestones, acceptance criteria and process, assumptions, dependencies, change control, fees per milestone, named contacts; nothing in the SOW silently overrides the MSA.
+- **DPA (GDPR Article 28):** the Article 28(3) contents must be present: subject matter, duration, nature and purpose, types of personal data and data subjects, and the processor obligations (documented instructions, confidentiality, security, sub-processors, assistance with data subject rights and with security and impact assessments, deletion or return, audit). International transfers need a transfer mechanism such as the EU Standard Contractual Clauses (2021) or the UK addendum; route those to a privacy lawyer and the `privacy-compliance` skill.
+
+## Rules
+
+- Never remove the draft marking or send the draft outside the organisation without the user confirming lawyer approval.
+- Never invent a commercial term, party detail or legal clause that is not in the template, playbook or term sheet.
+- Never silently change approved template language; every change is a logged deviation.
+- Do not give an opinion on whether a clause is enforceable; say it needs a lawyer.
+- Keep counterparty documents confidential; do not paste them into external services the user has not approved.
+
+## Report
+
+```
+Draft: <file> | type <NDA | MSA | SOW | DPA> | template <name, version> | status DRAFT - FOR LEGAL REVIEW
+Parties: <legal names>   Governing law: <law>
+Deviations: <n high, n medium, n low>  (register attached)
+Missing inputs: <list>
+Specialist review needed: <data protection, tax, export, employment, none>
+Next step: lawyer review by <name or role, if the user named one>
+```

package/skills/contract-drafting/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Use our MSA template and this term sheet to draft the agreement with Acme Logistics, and flag anything that differs from our standard",
+    "Draft a mutual NDA for talks with a potential acquirer using the clause library in legal/templates",
+    "The customer sent back our SOW with their changes, compare it to our playbook and write a redline summary for legal",
+    "We need a data processing agreement with our new email vendor based on our DPA template, fill in the processing details",
+    "Build a deviation register for this services agreement showing every change from our standard liability and indemnity clauses"
+  ],
+  "should_not_trigger": [
+    "Map the personal data our signup flow collects and set retention periods for each field",
+    "Check whether our invention is novel before we spend money on a patent application",
+    "Generate invoices with the right VAT fields for our customers in Germany",
+    "Explain in two sentences the difference between an MSA and a SOW",
+    "Negotiate better rates with our truckload carriers on the Midwest lanes"
+  ]
+}

package/skills/contract-drafting/references/term-sheets.md

@@ -0,0 +1,68 @@
+# Term sheet fields and pre-review checklists
+
+Read this when collecting inputs for a draft (section 0) or running the agreement-type checks (section 4). Required fields are marked `*`. Ask for every missing required field.
+
+## Common to all agreements
+
+- `*` Parties: full legal name, entity type, jurisdiction of incorporation, registered address, company number where used.
+- `*` Effective date, and signatories (name, title).
+- `*` Governing law and dispute forum (courts or arbitration, seat, rules).
+- Notices: addresses and email for formal notice.
+- Template name and version used.
+
+## NDA
+
+- `*` Mutual or one-way; who discloses.
+- `*` Purpose (the permitted use of the information).
+- `*` Term of the agreement and how long confidentiality obligations survive; any trade secrets carve-out to last longer.
+- Permitted disclosees (employees, affiliates, advisers, financing sources).
+- Exclusions: public, already known, independently developed, received from a third party lawfully; compelled disclosure process.
+- Return or destruction on request, with a backup-copy carve-out.
+- Non-solicitation or standstill (high risk; often belongs in a separate agreement).
+
+## MSA
+
+- `*` Services or products in scope; how orders or SOWs are created.
+- `*` Fees, currency, invoicing schedule, payment terms, late payment, price changes, taxes.
+- `*` Liability cap (amount or formula, for example fees paid in the prior 12 months) and exclusions from the cap.
+- `*` Term, renewal (auto-renew and notice), termination for cause and for convenience, effects of termination.
+- Indemnities: who indemnifies whom, for what (IP infringement, data breach, third-party claims), procedure.
+- Warranties and disclaimers; service levels and credits as a schedule.
+- IP: background IP stays with its owner; ownership of deliverables; licences granted.
+- Data protection: whether a DPA is needed; security schedule.
+- Insurance types and minimums.
+- Subcontracting, assignment and change of control.
+- Order of precedence between MSA, SOW, schedules and purchase orders.
+
+## SOW
+
+- `*` Reference to the governing MSA and its date.
+- `*` Deliverables with descriptions; milestones and dates.
+- `*` Acceptance criteria, acceptance period, and what happens on rejection.
+- `*` Fees per milestone or rate card, expenses policy.
+- Assumptions and customer dependencies; change-request process.
+- Named contacts and governance meetings.
+- Checks: the SOW must not change liability, IP or payment terms set in the MSA unless the MSA allows it, and then the change is a logged deviation.
+
+## DPA
+
+- `*` Roles: controller and processor (or processor and sub-processor).
+- `*` Subject matter, duration, nature and purpose of processing.
+- `*` Types of personal data, special categories if any, categories of data subjects.
+- `*` Security measures (usually an annex).
+- `*` Sub-processors: list, approval method (specific or general with notice and objection).
+- Breach notice period from processor to controller.
+- Assistance with data subject requests, security, impact assessments and prior consultation.
+- Deletion or return at end of services.
+- Audits and information rights.
+- International transfers: destinations and mechanism (EU SCCs 2021 module, UK IDTA or addendum). Route to a privacy lawyer.
+
+Check each DPA against the processor terms of GDPR Article 28(3) and the law of the user's jurisdiction; other data protection laws have their own processor contract requirements.
+
+## Final pre-review checks (all types)
+
+- Every placeholder filled or logged as a deviation; no `[ ]` left unexplained.
+- Defined terms defined once and used consistently; cross-references valid.
+- Dates, amounts and currencies match the term sheet exactly (amounts in words and figures agree if both are used).
+- Signature blocks match the party names.
+- Draft marking present on every page or in the header.

package/skills/contract-first-development/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: contract-first-development
+description: Coordinates frontend and backend teams, or two services, around one machine-checked interface contract in OpenAPI, AsyncAPI, protobuf or JSON Schema that is reviewed and merged before code, then drives generated clients and server stubs, mock servers for parallel work, CI gates for breaking changes with oasdiff and buf breaking, and Pact consumer-driven contract tests with can-i-deploy checks. Use when two teams or services must build against the same interface at the same time, a spec keeps drifting from the implementation, or a provider change broke a consumer that nobody tested against.
+license: MIT
+compatibility: Any Agent Skills host. Uses the contract tooling the repo already has (for example oasdiff, buf, Prism, openapi-generator, Pact); network access only for a Pact Broker.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Contract-first development
+
+One contract file is the source of truth for an interface. Both sides generate from it or test against it, CI blocks breaking edits to it, and nobody codes against a Slack message or a screenshot of a JSON payload.
+
+For designing the API itself (resource naming, status codes, pagination, versioning policy) use the `api-design` skill if installed; this skill is about the workflow around the contract once its shape is being agreed.
+
+## 0. Pick the format and the owner
+
+| Interface | Contract format |
+|---|---|
+| HTTP/REST | OpenAPI 3.x (3.1 aligns schemas with JSON Schema 2020-12) |
+| Events, queues, WebSockets | AsyncAPI 3.x, payloads in JSON Schema or Avro |
+| gRPC / internal RPC | protobuf with buf |
+| A data file or message without a transport | JSON Schema |
+
+1. Use the format already in the repo. If there are several, ask the user which is authoritative; never keep two hand-written sources of the same interface.
+2. Decide where the contract lives: in the provider repo, or a shared contracts repo/package. Record the owner who approves changes (a `CODEOWNERS` entry is ideal).
+3. **Stop and ask** if the implementation exists and the spec is generated from code: switching to spec-first is a team decision.
+
+## 1. Write and review the contract before code
+
+1. Draft the change as a pull request that touches only the contract (plus examples).
+2. Every operation or message has: request and response schemas, required vs optional fields, error responses, at least one realistic example, and an `operationId` (OpenAPI) so generated code has stable names.
+3. Lint it: `redocly lint` or `spectral lint` for OpenAPI, `asyncapi validate` for AsyncAPI, `buf lint` for protobuf, and validate examples against the schemas.
+4. Both sides review. A consumer approval is required for anything they will call.
+5. Merge, then tag or version the contract so both sides pin the same revision.
+
+## 2. Work in parallel from the contract
+
+- **Consumer side**: generate a typed client and start against a mock server built from the contract (`prism mock openapi.yaml` for OpenAPI; buf/connect or a generated stub for protobuf; AsyncAPI generators or a test broker for events). Never hand-write request types that the generator can produce.
+- **Provider side**: generate server interfaces or stubs, or validate requests and responses against the spec at runtime in tests, so the implementation can't silently diverge.
+- Commit generated code or regenerate in the build; follow whichever the repo already does, and make CI fail when the committed output is stale. Tools and commands: `references/tooling.md`.
+
+## 3. Block breaking changes in CI
+
+On every PR that touches a contract, compare with the base branch:
+
+- OpenAPI: `oasdiff breaking --fail-on ERR origin/main:openapi.yaml HEAD:openapi.yaml`; `oasdiff changelog` for the PR description.
+- protobuf: `buf breaking --against '.git#branch=main'` (default rule set `FILE`; set `breaking.use` in `buf.yaml`).
+- JSON Schema / AsyncAPI: run the repo's diff tool, or treat removed properties, newly required fields, narrowed types and removed enum values as breaking in review.
+
+A breaking change needs one of: a new version (path, package, or message type), an additive alternative plus deprecation, or written agreement from every consumer. **Stop and ask the user** before merging any breaking change.
+
+Common breaking edits: removing or renaming a field, endpoint, message or enum value; making an optional request field required; changing a type or format; tightening validation; reusing a protobuf field number. Also breaking for many consumers: adding a value to a response enum (strict clients and exhaustive switches fail) and changing default values. Usually safe: adding optional request fields, adding response fields (only if consumers ignore unknown fields), adding endpoints.
+
+## 4. Consumer-driven contract tests (Pact)
+
+Use when consumers depend on behaviour a schema can't express (which fields they actually read, state-dependent responses), or when providers deploy independently.
+
+1. Consumer tests run against the Pact mock and write a pact file describing only the interactions the consumer uses.
+2. Publish pacts to a Pact Broker (or PactFlow) tagged with the consumer's git SHA and branch.
+3. The provider verifies pacts in its CI with provider states set up through a test hook, never against shared staging data.
+4. Before each deploy: `pact-broker can-i-deploy --pacticipant <name> --version <sha> --to-environment <env>`; after it: `pact-broker record-deployment --pacticipant <name> --version <sha> --environment <env>`.
+5. Pact does not replace schema checks; run both.
+
+## Never
+
+- Never edit generated code by hand; change the contract or the generator config.
+- Never let the mock server drift from the spec (generate it from the spec, don't hand-write fixtures).
+- Never disable a breaking-change check to get a PR green.
+- Never reuse a deleted protobuf field number or name; `reserved` them.
+
+## Report
+
+```
+## Contract: <interface> (<format>, <path>@<revision>)
+Owner: <team/person>
+Lint: <command> -> pass/fail
+Breaking-change check: <command> -> <n breaking> (<list>)
+Generated: client <tool/path>, server <tool/path>, stale: yes/no
+Mock: <command or none>
+Consumer contracts: <Pact status, can-i-deploy result, or not used>
+Needs agreement: <breaking changes and which consumers must approve>
+```

package/skills/contract-first-development/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "The mobile team and the backend team keep disagreeing about payload shapes. Set us up so both build from one OpenAPI spec with a mock server.",
+    "Add a CI check that fails the PR if someone makes a breaking change to our protobuf files",
+    "A provider deploy broke the checkout frontend again. Set up Pact consumer tests and can-i-deploy before releases.",
+    "Our openapi.yaml has drifted from what the Go service actually returns. Generate the server interfaces from the spec so they can't diverge.",
+    "We're about to start a new order-events topic. Agree the AsyncAPI contract first so both services can start in parallel."
+  ],
+  "should_not_trigger": [
+    "Design the REST endpoints and status codes for our new invoicing API",
+    "Write a typed client for the Shopify Admin API with retries and pagination",
+    "Write Playwright end-to-end tests for the signup flow",
+    "Which packages in our monorepo depend on the shared validation library?",
+    "Add a migration that renames the orders.total column"
+  ]
+}

package/skills/contract-first-development/references/tooling.md

@@ -0,0 +1,46 @@
+# Contract tooling
+
+Prefer tools already in the repo. Check flags with `--help` for the installed version.
+
+## OpenAPI
+
+| Job | Tool and command |
+|---|---|
+| Lint | `npx @redocly/cli lint openapi.yaml`, or `spectral lint openapi.yaml` with a `.spectral.yaml` ruleset |
+| Breaking changes | `oasdiff breaking --fail-on ERR <base> <revision>`; bases can be files, URLs or `<git-ref>:<path>`; `--fail-on WARN` is stricter |
+| Changelog | `oasdiff changelog <base> <revision>` |
+| Mock server | `npx @stoplight/prism-cli mock openapi.yaml` (serves examples; `-d` for dynamic data) |
+| Validating proxy | `prism proxy openapi.yaml <upstream-url>` reports requests and responses that violate the spec |
+| TypeScript types | `npx openapi-typescript openapi.yaml -o src/api/schema.d.ts`, with `openapi-fetch` for a typed client |
+| Clients and stubs, many languages | `openapi-generator-cli generate -i openapi.yaml -g <generator> -o <dir>` |
+| Go | `oapi-codegen` with a config file selecting client, server or types |
+| Property-based API tests | Schemathesis, run against a provider test instance |
+
+## protobuf (buf)
+
+| Job | Command |
+|---|---|
+| Lint | `buf lint` |
+| Breaking changes | `buf breaking --against '.git#branch=main'` (or a BSR module, or a tag) |
+| Generate | `buf generate` with `buf.gen.yaml` listing plugins |
+| Format | `buf format -w` |
+
+Rules: never change a field number or type; `reserved` removed numbers and names; add fields as optional.
+
+## AsyncAPI
+
+- Validate: `asyncapi validate asyncapi.yaml` (AsyncAPI CLI).
+- Generate code or docs: `asyncapi generate fromTemplate asyncapi.yaml <template>`.
+- Payload schemas can be JSON Schema or Avro; keep Avro schemas in a schema registry with compatibility mode set (for example BACKWARD) if the platform has one.
+
+## JSON Schema
+
+- Validate examples and fixtures in tests with the language's validator (Ajv for JS/TS, `jsonschema` for Python).
+- Declare `$schema` so tools pick the right draft.
+
+## Pact
+
+- Consumer libraries: pact-js, pact-python, pact-jvm, pact-go, pact-net and others; consumer tests write pact files to `pacts/`.
+- Publish: `pact-broker publish pacts/ --consumer-app-version <sha> --branch <branch> --broker-base-url <url>`.
+- Provider verification runs in the provider's test suite with a provider-states setup endpoint or hook.
+- Gate deploys: `pact-broker can-i-deploy --pacticipant <name> --version <sha> --to-environment <env>`; then `pact-broker record-deployment --pacticipant <name> --version <sha> --environment <env>`.

package/skills/decision-council/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: decision-council
+description: Runs a council of independent viewpoints on one hard call, giving several role-played advisers or separate models (or providers) the same brief in isolation so none sees another's answer, then cross-examining their positions and synthesising a single recommendation that records the strongest dissent, the confidence level and what evidence would change the outcome. Use when facing an ambiguous or contested choice, a go/no-go or launch call, a build-versus-buy or vendor pick, or whenever the user asks for a second opinion, a devil's advocate, a panel or a debate before committing.
+license: MIT
+compatibility: Any Agent Skills host. Works with role-played perspectives in one session; independent subagents or a second model or provider give stronger independence where the host supports them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Decision council
+
+One model asked once tends to agree with the framing it was given. A council gets several independent answers to the same brief, then weighs them openly, so the decision shows its disagreements instead of hiding them.
+
+Use it for decisions, not for tasks with a checkable answer (run the test instead), and not for code review (use a reviewer agent or `/dual-review`). To write up the outcome as a permanent record, hand the result to `architecture-decision-records`.
+
+## 1. Frame the decision
+
+Write a brief of at most one page and show it to the user before convening anyone:
+
+- **Question**: one sentence, phrased as a choice ("Ship v2 on 1 March, or slip to April?").
+- **Options**: two to four concrete options, including "do nothing" or "delay" where real.
+- **Criteria**: what matters, in priority order (cost, risk, time, reversibility, user impact, compliance).
+- **Facts**: the evidence available, with sources. Mark assumptions as assumptions.
+- **Constraints**: deadlines, budgets, non-negotiables.
+- **Reversibility**: how hard the choice is to undo. Easily reversible decisions rarely need a council; say so and stop if this is one.
+
+Keep the brief neutral. Don't state your own lean, and don't order options so the preferred one comes first or last every time.
+
+If the question or the options are unclear, stop and ask the user rather than guessing.
+
+## 2. Choose the members
+
+Pick three to five members. Choose perspectives that would genuinely disagree:
+
+- **Roles**, for example: the operator who must run it, the customer, the finance owner, the security or compliance reviewer, the skeptic whose job is to argue against the leading option, the engineer who builds it.
+- **Different models or providers**, where available, to reduce shared blind spots. Note the model name for each member.
+- Always include one member assigned to argue the strongest case against whatever looks like the default option.
+
+For regulated, legal, medical or financial decisions, a role-played expert is not a qualified opinion. Say this in the result and name who must actually review it.
+
+## 3. Keep them independent
+
+Independence is the whole point; protect it:
+
+1. Give every member the same brief, word for word, plus their role. Don't pass any member another's answer in this round.
+2. Run members in separate contexts (separate subagents, separate sessions or separate model calls) when the host allows. If only one context is available, write each member's answer in full before starting the next, and don't revise earlier answers.
+3. Ask each member for the same fixed format:
+
+```
+Position: <option>
+Confidence: low | medium | high
+Top 3 reasons: ...
+Biggest risk of my position: ...
+What would change my mind: ...
+```
+
+4. Don't let members search for or cite each other. Facts they introduce must come with a source; unsourced claims are flagged in synthesis.
+
+## 4. Cross-examine
+
+One round only, to stop the council drifting into consensus by attrition:
+
+- Show each member the other positions, anonymised (Member A, B, C).
+- Ask each: which argument against your position is strongest, and does it change your position? Record any change and why.
+- Ask the assigned skeptic to attack the current majority view.
+
+## 5. Synthesise
+
+You, as chair, write the recommendation. Rules:
+
+- Weigh arguments against the criteria from the brief, not by headcount. A single member with a decisive fact beats a majority without one.
+- Check that every factual claim the recommendation relies on is in the brief or sourced. Drop or flag the rest.
+- Keep dissent visible. Never smooth a real disagreement into "all members broadly agree".
+- Confidence is about the decision, not the members: high only if the main arguments survived cross-examination and the facts are solid.
+- If the council splits evenly or confidence is low, say so and name the one piece of evidence that would settle it, instead of forcing a pick.
+
+## Never
+
+- Never present the council's output as the user's decision; the user decides.
+- Never invent expert credentials, data or quotes for a member.
+- Never rerun the council until you get the answer you or the user wanted; if new facts arrive, revise the brief and say what changed.
+
+## Report
+
+```
+## Decision: <question>
+Recommendation: <option>   Confidence: low | medium | high
+Why: <three bullet points tied to the criteria>
+Members: <role or model> → <position> (<confidence>), one line each; mark changes after cross-examination
+Strongest dissent: <argument, who holds it, why it did not prevail>
+Key risks and mitigations: <bullets>
+Would change the call: <specific evidence or event>
+Assumptions: <list>
+Needs qualified review: <who, or "none">
+```

package/skills/decision-council/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We can't agree whether to launch the new pricing on Monday or wait a month. Get me a few independent perspectives and a recommendation",
+    "Should we build our own auth or buy Auth0? I want a panel of viewpoints, including a devil's advocate",
+    "Ask two different models separately whether we should sunset the legacy API this quarter, then reconcile their answers",
+    "Give me a go/no-go call on the Ghana market expansion with the dissenting view recorded",
+    "Convene a council: rewrite the billing service in Go, or keep patching the Rails one?"
+  ],
+  "should_not_trigger": [
+    "Write an ADR recording that we chose Postgres over MongoDB last week",
+    "Have two reviewers check my pull request until both approve it",
+    "Compare three monolith versus microservice architectures for our new platform and design the module boundaries",
+    "Estimate how long the payments migration will take and break it into tasks",
+    "Score these model outputs with an LLM judge and give me a pass rate"
+  ]
+}

package/skills/design-brainstorming/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: design-brainstorming
+description: Collaborative design session that turns a rough idea into an approved design before any code is written. Reads the project first, asks one question per message (multiple choice where possible) to settle purpose, users, constraints and success criteria, offers two or three approaches with trade-offs and a recommendation, walks the design through in short sections approved one at a time, cuts anything not needed now, and saves a dated design doc in the repo for the implementation-plans skill to pick up. Use when someone has an idea, feature or change they want to build but the what and why are not pinned down yet, or says "let's think this through before we code".
+license: MIT
+compatibility: Any Agent Skills host. Reads the repository and writes one Markdown design doc.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Design brainstorming
+
+Find out what the user actually wants, and why, before anything gets built. The output is an approved design doc, not code. Don't write, scaffold or edit source files during this skill.
+
+Neighbours: `prd-writing` is for a full product requirements document for stakeholders; the `architect` agent compares system-level structures; `planner` and `implementation-plans` turn an approved design into steps. This skill sits before them.
+
+## 0. Size the ceremony
+
+Decide how much process the request needs before you start:
+
+| Request | What to do |
+|---|---|
+| Fully specified and tiny ("make the button label say Save") | Skip this skill. Do it, say what you did. |
+| Small change, one or two open points | Ask those questions, state the design in a few lines, get a yes, go. No doc unless asked. |
+| A feature, a new module, anything touching data shape, APIs or several files | The full flow below, with a design doc. |
+| Several independent subsystems ("build a marketplace with chat, payments and reviews") | Stop and propose splitting it into separate designs. Agree which one goes first, then run the flow on that one. |
+
+Always tell the user they can say "skip the questions and just start". If they do, state the one or two big choices you're making (language, storage, where it lives) in a line each and hand over to the normal workflow.
+
+## 1. Read before you ask
+
+Look at the project before the first question so you don't ask what the repo already answers:
+
+- README, `AGENTS.md` or similar, existing design docs and ADRs (`docs/`, `docs/adr/`, `docs/designs/`).
+- The code nearest the idea: where similar features live, the data models, the frameworks in use.
+- Recent commits in that area.
+
+Note what you learned in two or three lines in your first message, so the user can correct a wrong assumption early.
+
+## 2. Ask, one question per message
+
+Work through these in roughly this order, skipping any the request or the code already answers:
+
+1. **Purpose**: what problem it solves, the moment someone wishes it existed.
+2. **Users**: who uses it, how often, how technical.
+3. **Scope**: the one thing it must do on day one; what is explicitly out.
+4. **Constraints**: deadlines, platforms, performance, compliance, budget, things that must not change.
+5. **Success**: how we'll know it works (an observable behaviour or a number).
+
+Rules:
+
+- **One question per message.** Never a list of questions.
+- Prefer multiple choice: 2 to 4 labelled options plus "something else". Open questions only where options would lead the answer.
+- Use the user's words. No process jargon.
+- If an answer is vague, ask a follow-up that offers concrete examples, rather than filling the gap yourself.
+- Stop asking when you could explain the design to a new teammate without guessing. Usually 3 to 8 questions.
+
+## 3. Offer approaches
+
+Present **two or three** genuinely different approaches, then recommend one:
+
+```
+A. <name>: <how it works in 1-2 lines>. Good: ... Costs: ...
+B. ...
+C. ...
+Recommendation: B, because <the constraint or goal it serves best>.
+```
+
+Ground them in this codebase (reuse what exists), not generic patterns. If one approach is clearly right, say so and offer a single alternative only for contrast. Wait for the user to pick.
+
+When the choice is visual (a screen layout, a flow, a dashboard), show it instead of describing it: offer static HTML mockups of each option the user can open in a browser, following `references/visual-mockups.md`.
+
+## 4. Walk the design through in sections
+
+Present the chosen design in short sections, each a few sentences to a short list, and **get a yes on each before the next**. Pick the sections that apply:
+
+1. Overview: what it is and what it isn't.
+2. Components and where each lives (existing files to extend, new files and why).
+3. Data: shapes, storage, migrations.
+4. Interfaces: API routes, function signatures, UI screens, events.
+5. Flow: the main path step by step, then failure and edge cases.
+6. Testing: how each behaviour will be proved.
+7. Rollout: flags, migration order, backwards compatibility.
+
+When the user changes something, revise that section and re-confirm it. Go back to an earlier section if a later answer breaks it.
+
+**Cut ruthlessly.** For every element ask "is this needed for the first version?" Remove configuration, extension points, generalisations and "nice to have" items nobody asked for, and list them under "Not now" so the decision is visible.
+
+## 5. Write the design doc
+
+1. Save it to the folder the project already uses for designs. If there is none, use `docs/designs/YYYY-MM-DD-<topic>.md` with today's date, and say where you put it.
+2. Use this layout:
+
+```markdown
+# <Topic> design
+Date: YYYY-MM-DD    Status: approved
+## Problem and users
+## Goals / success criteria
+## Out of scope / not now
+## Chosen approach (and alternatives considered)
+## Components, data, interfaces
+## Main flow and edge cases
+## Testing
+## Rollout and risks
+## Open questions
+```
+
+3. Re-read it once: no placeholders, no contradictions between sections, every success criterion testable, nothing in it the user didn't approve.
+4. Ask the user to read the file and confirm. Commit it only if they agree (or the project's workflow says design docs are committed).
+
+## 6. Hand off
+
+Once the doc is approved, offer the next step: the `implementation-plans` skill (or the `planner` agent) to turn it into tasks. Don't start implementing inside this skill.
+
+## Stop and ask
+
+- The idea conflicts with something in the codebase or an earlier decision (an ADR, a documented constraint).
+- It touches regulated data, payments, security or irreversible data changes: flag it and suggest the matching review (`threat-modeling`, `privacy-compliance`, `payments-reviewer`).
+- The user's answers contradict each other.
+
+## Never
+
+- Never write implementation code, scaffolding or migrations during brainstorming.
+- Never ask more than one question in a message.
+- Never present a single option as if it were a choice, or hide a trade-off.
+- Never pad the design with features to look thorough.
+
+## Report
+
+At the end, reply with: the design doc path, the chosen approach in one line, the "not now" list, open questions, and the suggested next step.

package/skills/design-brainstorming/evals/behavior.json

@@ -0,0 +1,55 @@
+{
+  "scenarios": [
+    {
+      "name": "jump straight to code",
+      "prompt": "I want users to be able to export their data. Let's go, just start coding it, I'll figure out details as we go.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Does not write implementation code in the reply",
+        "Asks exactly one question in the message, ideally multiple choice (for example format or scope)",
+        "Mentions the user can say 'skip the questions and just start'",
+        "If skipping, states the one or two big choices being made instead of silently deciding"
+      ],
+      "forbid": [
+        "Writes or scaffolds export code",
+        "Asks a list of several questions in one message"
+      ]
+    },
+    {
+      "name": "offer approaches with trade-offs",
+      "prompt": "We've agreed: admins need an audit log of who changed billing settings, kept 1 year, viewable in the admin panel. What are our options?",
+      "files": {
+        "src/models/billing.js": "const db = require('../db');\nasync function updateSettings(orgId, patch, userId) {\n  return db('billing_settings').where({ org_id: orgId }).update(patch);\n}\nmodule.exports = { updateSettings };\n"
+      },
+      "expect": [
+        "Presents two or three genuinely different approaches, each with what is good and what it costs",
+        "Gives one recommendation with a reason tied to the stated constraints",
+        "Grounds the approaches in the existing code (for example updateSettings in src/models/billing.js)",
+        "Waits for the user to pick before detailing the design"
+      ],
+      "forbid": [
+        "Presents a single approach as the only option",
+        "Starts writing a migration or code"
+      ]
+    },
+    {
+      "name": "too big, split it",
+      "prompt": "Design me a marketplace with seller onboarding, buyer chat, Stripe payments and a review system. My manager wants the full design doc today.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expect": [
+        "Proposes splitting it into separate designs per subsystem",
+        "Asks which subsystem to design first",
+        "Flags payments as needing a matching security or payments review"
+      ],
+      "forbid": [
+        "Produces one combined design doc covering every subsystem at once",
+        "Writes implementation code"
+      ]
+    }
+  ]
+}