docket-agent 0.1.0

package/src/lib/yaml.js

@@ -0,0 +1,132 @@
+// Minimal YAML subset parser/emitter — enough for loop frontmatter, zero deps.
+//
+// Supported: nested maps, lists of scalars, quoted/unquoted scalars,
+// booleans, null, numbers, `[]` empty lists, `#` comment lines.
+// Deliberately NOT supported: anchors, multi-line scalars, flow maps,
+// lists of maps. Loop files never need them; keeping the grammar small
+// keeps the format auditable.
+
+export function parseYaml(text) {
+  const lines = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    lines.push({ indent: raw.match(/^ */)[0].length, content: trimmed });
+  }
+  let i = 0;
+
+  function parseScalar(s) {
+    if (s === 'null' || s === '~') return null;
+    if (s === 'true') return true;
+    if (s === 'false') return false;
+    if (s === '[]') return [];
+    if (s === '{}') return {};
+    if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+    if (s.startsWith('"') && s.endsWith('"') && s.length >= 2) {
+      try {
+        return JSON.parse(s); // unescape \" and \\ — the emitter uses JSON quoting
+      } catch {
+        return s.slice(1, -1);
+      }
+    }
+    if (s.startsWith("'") && s.endsWith("'") && s.length >= 2) {
+      return s.slice(1, -1).replace(/''/g, "'");
+    }
+    return s;
+  }
+
+  function parseBlock(indent) {
+    if (i >= lines.length) return null;
+    return lines[i].content.startsWith('- ') || lines[i].content === '-'
+      ? parseList(indent)
+      : parseMap(indent);
+  }
+
+  function parseMap(indent) {
+    const obj = {};
+    while (i < lines.length) {
+      const line = lines[i];
+      if (line.indent !== indent || line.content.startsWith('- ')) break;
+      const m = line.content.match(/^([^:]+):(.*)$/);
+      if (!m) throw new Error(`docket: cannot parse frontmatter line: "${line.content}"`);
+      const key = m[1].trim();
+      const rest = m[2].trim();
+      i++;
+      if (rest === '') {
+        if (i < lines.length && lines[i].indent > indent) {
+          obj[key] = parseBlock(lines[i].indent);
+        } else if (
+          // Common hand-written style: list items at the same indent as the key.
+          i < lines.length &&
+          lines[i].indent === indent &&
+          (lines[i].content.startsWith('- ') || lines[i].content === '-')
+        ) {
+          obj[key] = parseList(indent);
+        } else {
+          obj[key] = null;
+        }
+      } else {
+        obj[key] = parseScalar(rest);
+      }
+    }
+    return obj;
+  }
+
+  function parseList(indent) {
+    const arr = [];
+    while (i < lines.length) {
+      const line = lines[i];
+      if (line.indent !== indent || !(line.content.startsWith('- ') || line.content === '-')) break;
+      const rest = line.content === '-' ? '' : line.content.slice(2).trim();
+      i++;
+      arr.push(rest === '' ? null : parseScalar(rest));
+    }
+    return arr;
+  }
+
+  const result = parseBlock(0);
+  if (i < lines.length) {
+    throw new Error(`docket: unexpected indentation near: "${lines[i].content}"`);
+  }
+  return result ?? {};
+}
+
+function needsQuotes(s) {
+  return (
+    s === '' ||
+    /^[\s#\-?:@&*!|>%'"[\]{}]/.test(s) ||
+    /[:#]\s/.test(s) ||
+    /\s$/.test(s) ||
+    ['null', 'true', 'false', '~'].includes(s) ||
+    /^-?\d+(\.\d+)?$/.test(s)
+  );
+}
+
+function emitScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  return needsQuotes(s) ? JSON.stringify(s) : s;
+}
+
+export function dumpYaml(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '';
+    return value.map((v) => `${pad}- ${emitScalar(v)}`).join('\n') + '\n';
+  }
+  if (value && typeof value === 'object') {
+    let out = '';
+    for (const [k, v] of Object.entries(value)) {
+      if (Array.isArray(v)) {
+        out += v.length === 0 ? `${pad}${k}: []\n` : `${pad}${k}:\n${dumpYaml(v, indent + 2)}`;
+      } else if (v && typeof v === 'object') {
+        out += `${pad}${k}:\n${dumpYaml(v, indent + 2)}`;
+      } else {
+        out += `${pad}${k}: ${emitScalar(v)}\n`;
+      }
+    }
+    return out;
+  }
+  return `${pad}${emitScalar(value)}\n`;
+}

package/templates/client-follow-up.loop.md

@@ -0,0 +1,59 @@
+---
+name: client-follow-up
+description: Follow up with a client with the whole history in the room — promises, tone, and the language they already approved.
+version: 1
+warrant:
+  read:
+    - account history
+    - past email threads with this client
+    - meeting notes
+    - the contract and current scope
+  draft:
+    - follow-up email
+    - status summary
+    - meeting agenda
+  change:
+    - internal notes on the account
+  send: []
+  ask:
+    - anything the client will see
+    - scheduling anything on the client's calendar
+  never:
+    - unapproved prices, discounts, or scope changes
+    - apologizing for things we did not do
+reserved:
+  - what gets promised
+  - final approval of every outbound message
+  - when a relationship problem escalates to a phone call
+record:
+  - promises found in the history and whether each is kept, pending, or slipped
+  - approved language reused, and any new language that needs sign-off
+  - what the draft deliberately does not mention, and why
+---
+
+# Brief
+
+- Who this client is: names, roles, who actually decides, who just replies fastest.
+- Every promise made to them, with dates. A follow-up that forgets a promise is worse
+  than no follow-up.
+- Approved language vs rejected language. If a phrase was walked back once, it does
+  not come back.
+- Their tone preferences: some clients want three bullet points, some want warmth
+  first. This client's preference is written here, not guessed each time.
+- Open commercial context: renewal date, expansion talks, any sore spots.
+
+# Procedure
+
+1. Reconstruct the state of the relationship from the history before writing a word:
+   last contact, open items, promises due.
+2. Lead with what they care about, not what we did. Status they asked for first,
+   housekeeping last.
+3. Reuse approved language wherever it exists. New claims and new commitments get
+   flagged in the draft, not smuggled in.
+4. Match the established tone. Do not escalate warmth or formality without a reason.
+5. Deliver the draft with a short cover note: what changed since last time, what needs
+   approval, what was left out on purpose.
+
+Failure modes: re-promising something that already slipped (reads as not paying
+attention), inventing enthusiasm the history doesn't support, and burying the one
+thing the client actually asked about.

package/templates/cross-tool-memory.loop.md

@@ -0,0 +1,55 @@
+---
+name: cross-tool-memory
+description: One context you own, readable from Claude, GPT, Kimi, or Codex — a model switch is a recompile, not a re-teach.
+version: 1
+warrant:
+  read:
+    - the loops in this .docket directory
+    - existing CLAUDE.md, AGENTS.md, and rules files
+  draft:
+    - updates to loop brief sections
+    - compiled context blocks
+  change:
+    - CLAUDE.md, AGENTS.md, and other compiled context files via docket compile
+  send: []
+  ask:
+    - rewriting a loop's warrant or reserved sections
+    - deleting anything from memory
+  never:
+    - storing secrets, tokens, or passwords in any loop file
+reserved:
+  - what gets remembered at all — memory is curation, not accumulation
+  - any change to what an agent is allowed to do
+record:
+  - what was added to memory and its source
+  - what was pruned and why
+  - which context files were regenerated
+---
+
+# Brief
+
+- The context lives here, in plain files, in your repo — not inside any one
+  assistant's opaque memory feature. The assistants are interchangeable; this
+  directory is not.
+- Which tools are in play (Claude Code, Cursor, Codex, a local model) and which
+  compiled file each one reads.
+- The curation standard: memory holds things that change future answers —
+  decisions, preferences, constraints, standards. Not transcripts.
+
+# Procedure
+
+1. After significant work in any tool, harvest: what was decided, what preference
+   was expressed, what standard emerged? One line each, into the right loop's
+   Brief section.
+2. Prune as often as you add. Memory that grows without curation becomes noise
+   with a table of contents.
+3. Warrant and reserved-list changes are never harvested automatically — a human
+   relaxing a rule once in conversation is not the rule changing.
+4. Run `docket compile --target claude --write` and `--target agents --write` so
+   every tool reads the same brain. The generated blocks are disposable; the loops
+   are the source of truth.
+5. When switching models, carry nothing by hand. If the new tool starts cold,
+   something belongs in a loop file that isn't there yet — fix the file, not the chat.
+
+Failure mode: letting one tool's built-in memory become the real memory. The moment
+that happens, your context has a landlord.

package/templates/insurance-appeal.loop.md

@@ -0,0 +1,59 @@
+---
+name: insurance-appeal
+description: Build the appeal, cite the policy, assemble the evidence packet — stop before send.
+version: 1
+warrant:
+  read:
+    - policy documents
+    - denial letter
+    - claim correspondence
+    - medical records already in the claim file
+  draft:
+    - appeal letter
+    - evidence summary
+    - timeline of the claim
+  change: []
+  send: []
+  ask:
+    - contacting the insurer
+    - contacting the doctor's office
+    - requesting new records
+  never:
+    - accepting or rejecting a settlement
+    - inventing symptoms or events not in the record
+reserved:
+  - whether to appeal at all
+  - the final wording of anything the insurer will read
+  - signing and sending
+record:
+  - every policy clause cited, with section numbers
+  - documents consulted and documents that could not be found
+  - claims made in the draft that lack a source in the record
+  - where the draft stopped and what a human must do next
+---
+
+# Brief
+
+- Policy number, plan year, and the exact denial reason code from the letter.
+- The claim's timeline so far: dates of service, submission, denial, any prior calls.
+- Appeals in this plan have a deadline (often 180 days from denial) — the date matters
+  more than the prose.
+- What has already been said to the insurer. Never contradict the record.
+- The insured person's actual account of events — the draft may only use what they
+  have confirmed, not what would be convenient.
+
+# Procedure
+
+1. Read the denial letter first. The appeal answers the stated reason, not a general
+   sense of unfairness.
+2. Find the policy language the denial relies on, then the language that cuts the
+   other way. Quote both, with section numbers.
+3. Build the evidence packet: what exists, what's missing, what a human would need to
+   request. Missing evidence is listed, not papered over.
+4. Draft the appeal in plain, factual language. No threats, no speculation, no
+   symptoms or events that aren't in the record.
+5. Stop. The draft ends with a checklist of what the human must verify before sending.
+
+Known failure mode — the one this loop exists to prevent: an agent reading frustration
+in a message ("I'm so sick of fighting this claim") as authorization, and sending the
+appeal itself. Frustration is not permission. Nothing in this loop sends anything.

package/templates/marketing-brain.loop.md

@@ -0,0 +1,62 @@
+---
+name: marketing-brain
+description: Marketing memory that compounds week over week — the messaging that already worked, the objections that keep coming back, the founder's actual voice.
+version: 1
+warrant:
+  read:
+    - the positioning doc
+    - past campaigns and their results
+    - sales call notes
+    - competitor claims
+  draft:
+    - copy variants
+    - landing page sections
+    - launch posts
+  change:
+    - the swipe file of language that worked
+  send: []
+  ask:
+    - publishing anywhere public
+    - any claim with a number in it
+  never:
+    - claims about competitors we cannot support
+    - invented or made-up customer quotes or statistics
+reserved:
+  - what the company is willing to claim in public
+  - the line between confident and unsupportable
+  - final approval on anything that ships
+record:
+  - which surviving positioning lines the draft builds on
+  - every claim in the draft, marked supported or needs-evidence
+  - new objections or language patterns learned this week, added to the brief
+---
+
+# Brief
+
+- Positioning that survived contact with real customers — the lines that made people
+  nod, kept verbatim. Also the graveyard: lines that tested well internally and died
+  in the wild.
+- The recurring sales objections, in the customers' own words, and the answers that
+  actually landed.
+- The founder's language: words they use, words they would never use. Copy that
+  doesn't sound like them gets rewritten anyway, so start in their voice.
+- The explicit line between confident and unsupportable. Confident: "the
+  fastest way to X". Unsupportable: "the only way to X". This line is policy,
+  not taste.
+
+# Procedure
+
+1. Read the brief before writing. The whole value of this loop is that week 30
+   starts where week 29 ended, not from a blank page.
+2. Draft from surviving language outward. New angles are welcome but marked as
+   untested.
+3. Every factual claim gets a tag: supported (with the source) or needs-evidence.
+   A claim without a tag doesn't ship.
+4. After anything ships, write down what happened — the memory only compounds if
+   results flow back in.
+5. Never resolve the bold-vs-unsupported call alone. When a line sits on the border,
+   it goes to the human with the argument for each side.
+
+Failure mode: drift. Fifty small rewrites by a helpful agent and the company sounds
+like everyone else. The memory file is the anchor; when in doubt, sound like the
+founder, not like marketing.

package/templates/ticket-handoff.loop.md

@@ -0,0 +1,59 @@
+---
+name: ticket-handoff
+description: Turn messy work into tickets another human — or another agent — can pick up cold: source, owner, status, blocker, warrant, record.
+version: 1
+warrant:
+  read:
+    - the conversation or incident being handed off
+    - the existing backlog
+    - team ownership docs
+  draft:
+    - ticket title and body
+    - suggested owner and priority
+  change:
+    - ticket status on tickets this loop created
+  send: []
+  ask:
+    - assigning a ticket to a person
+    - setting priority above default
+    - closing anyone else's ticket
+  never:
+    - deleting tickets
+    - editing another person's ticket description
+reserved:
+  - who actually owns what
+  - priority calls that affect other people's weeks
+record:
+  - every ticket created, with a link back to its source
+  - what was NOT filed, and why (duplicate, out of scope, needs a human call)
+  - open questions the ticket could not answer
+---
+
+# Brief
+
+- The team's real ownership map — who owns which surface, including the unofficial
+  truths ("the doc says infra, but ask Dana first").
+- Ticket conventions: title format, required fields, what counts as a blocker vs a
+  dependency, the priority scale as actually used.
+- The backlog's known duplicates and graveyards, so the same ghost doesn't get filed
+  a fourth time.
+- What a good ticket looks like here: reproducible, scoped, with the source linked —
+  not a paragraph of vibes.
+
+# Procedure
+
+1. Every ticket carries six fields or it isn't done: source (where this came from,
+   linked), owner (suggested, not assigned), status, blocker, warrant (what the
+   assignee may and may not do), and record (what evidence closes it).
+2. Search the backlog before filing. A duplicate found is a record line, not a
+   new ticket.
+3. Write the ticket so a stranger could start it cold. If it needs the original
+   conversation to make sense, the ticket isn't finished — the whole point is that
+   the context travels with the work.
+4. Suggest owner and priority with reasons; a human confirms both. Suggesting is
+   drafting, assigning is sending.
+5. Close the handoff with the record: filed, skipped, and unresolved — so the next
+   agent (or human) trusts the state without re-reading everything.
+
+Failure mode: tickets that are really just chat transcripts with a title. Handing off
+work means handing off the context, the warrant, and the definition of done.

package/templates/travel-morning.loop.md

@@ -0,0 +1,54 @@
+---
+name: travel-morning
+description: Plan a morning in an unfamiliar city around how you actually travel — not how a guidebook thinks you should.
+version: 1
+warrant:
+  read:
+    - maps and transit schedules
+    - opening hours
+    - reviews
+    - weather
+  draft:
+    - the morning plan
+    - a backup plan for rain or closures
+  change: []
+  send: []
+  ask:
+    - any reservation or booking
+    - anything that costs money
+  never:
+    - booking anything nonrefundable
+reserved:
+  - spending money
+  - changing the day's anchor commitments (flights, meetings, people)
+record:
+  - total walking distance and longest single stretch
+  - which preferences shaped the plan and which were traded off
+  - what was rejected and why (too far, too crowded, violates a food rule)
+---
+
+# Brief
+
+- Walking tolerance: how far is pleasant, how far is a death march. Uphill counts double.
+- Food rules: allergies, hard nos, and "will try anything once" — these are different
+  categories and must not be blended.
+- Known time-sinks this traveler refuses: queues over 20 minutes, attractions that
+  exist for photos, anything requiring a timed ticket bought three days ago.
+- Pace: one anchor thing per morning, or a packed itinerary? Written here, not inferred
+  from enthusiasm the night before.
+- Hard constraints of the day: checkout times, meeting times, who else is coming.
+
+# Procedure
+
+1. Start from the day's fixed points and work backward — the plan serves the
+   commitments, not the reverse.
+2. Pick one anchor (the thing that would make the morning feel worth it), then arrange
+   food and wandering around it.
+3. Check everything against the rules: distance, opening hours, food constraints,
+   queue reputation. A plan that violates a written rule is wrong even if it's great.
+4. Always produce the rain/closure fallback. A plan with no plan B is half a plan.
+5. Present the plan with its tradeoffs stated ("skipped X because it's 40 minutes of
+   walking uphill") so the human can overrule with full information.
+
+Failure mode: optimizing for "top ten" lists instead of the written preferences.
+The whole point of this loop is that the preferences are already known.

package/templates/weekly-planning.loop.md

@@ -0,0 +1,55 @@
+---
+name: weekly-planning
+description: Propose the week — priorities, tradeoffs, and what has to move — but change nothing.
+version: 1
+warrant:
+  read:
+    - calendar
+    - task list
+    - last week's plan and what actually happened
+  draft:
+    - the week plan
+    - proposed moves with reasons
+  change: []
+  send: []
+  ask:
+    - moving any calendar event
+    - declining any meeting
+    - anything involving other people's time
+  never:
+    - family dinners, family commitments, or family events
+    - workouts or workout blocks
+    - cancelling anything without an explicit yes on that specific thing
+reserved:
+  - what actually matters this week
+  - every calendar change, one by one — approving the plan is not approving the moves
+record:
+  - the proposed plan and every tradeoff it makes
+  - what got protected and what got sacrificed
+  - the difference between last week's plan and last week's reality
+---
+
+# Brief
+
+- Standing priorities and their real order — not the aspirational order.
+- Recurring constraints: family commitments, workouts, school pickup, the meeting that
+  cannot move even though everyone wishes it could.
+- The rules for what can move: deep work can shift within a day; anything with another
+  human in it needs their consent, which means it needs my approval first.
+- How much focused work per day is realistic. Last week's reality is the calibration,
+  not last week's intention.
+
+# Procedure
+
+1. Start with reality: diff last week's plan against what actually happened. Carry the
+   lesson, not the guilt.
+2. Place the immovables first — the reserved list above is a hard floor, not a
+   preference.
+3. Fit the top priorities into the remaining space. If they don't fit, say so — a plan
+   that pretends everything fits is a lie with a nice layout.
+4. Propose specific moves with reasons: "move X to Thursday because Y". Never make the
+   move. The plan is a proposal; the calendar is someone else's to change.
+5. End with tradeoffs, stated plainly: what this week's plan gives up and why.
+
+Failure mode: silently rescheduling things to make the plan look clean. A tidy plan
+that moved a family dinner is a failed plan, even if nobody notices until Thursday.