oe-sdk 0.1.0a1__tar.gz

oe_sdk-0.1.0a1/.agents/skills/generate-adr/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: generate-adr
+description: |
+  Analyse changes on the current branch (versus the default branch) and draft
+  Markdown Architectural Decision Records (MADRs) into docs/decisions/.
+  Surfaces the architecturally significant choices made on the branch, proposes
+  one ADR per distinct decision, and writes NNNN-title.md files using the MADR
+  4.x template. Use whenever the user wants to record design rationale from a
+  branch, capture architecture decisions before opening a PR, produce ADRs, or
+  document a technology/library/pattern choice that has just landed in the
+  diff, even if the user does not explicitly say "ADR".
+---
+
+<aim>
+
+Turn a branch's diff into durable design rationale. Read the changes versus
+the default branch, spot the architecturally significant decisions, and write
+them up as MADR-format records in `docs/decisions/`. One ADR per distinct
+decision, numbered, assertive, and honest about trade-offs. Follow the spirit
+of Olaf Zimmermann's ADR creation guidance: brief executive summaries,
+considered options with real trade-offs, and a clear verdict.
+
+</aim>
+
+<preflight>
+
+Run these checks first. Stop and report clearly if any fail.
+
+1. **Inside a git repo with a clean enough state to diff:**
+   ```bash
+   git rev-parse --is-inside-work-tree
+   ```
+
+2. **Not on the default branch** (nothing to diff against otherwise):
+   ```bash
+   git branch --show-current
+   ```
+   If the output matches the repo's default branch (`main`, `master`, or
+   whatever `origin/HEAD` resolves to), stop:
+   > "You're on the default branch, so there's no branch diff to analyse.
+   > Switch to a feature branch and rerun."
+
+3. **Default branch is resolvable:**
+   ```bash
+   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
+   ```
+   If this is empty, fall back to `main`. If `main` does not exist locally,
+   ask the user what the base branch should be.
+
+</preflight>
+
+## Workflow
+
+### Step 1: Locate (or choose) the ADR directory
+
+Probe for an existing ADR location in this order:
+
+1. `docs/decisions/` (MADR's own convention)
+2. `docs/adr/`
+3. `docs/architecture/decisions/`
+4. `adr/` at repo root
+5. Any directory matching `**/NNNN-*.md` where `NNNN` is four digits
+
+If more than one exists, use the one with the most files. If none exist,
+default to `docs/decisions/` and create it on write.
+
+Record the chosen directory. Scan it for the highest existing `NNNN` prefix
+so the next ADR picks up from `NNNN + 1` (zero-padded to four digits).
+
+### Step 2: Gather branch context
+
+Run these in parallel:
+
+```bash
+BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+BASE=${BASE:-main}
+
+if git show-ref --verify --quiet "refs/remotes/origin/${BASE}"; then
+  BASE_REF="origin/${BASE}"
+elif git show-ref --verify --quiet "refs/heads/${BASE}"; then
+  BASE_REF="${BASE}"
+else
+  echo "Could not resolve base branch: ${BASE}" >&2
+  exit 1
+fi
+
+git log --no-pager "${BASE_REF}..HEAD" --oneline
+git diff --no-pager --stat "${BASE_REF}...HEAD"
+git diff --no-pager "${BASE_REF}...HEAD"
+```
+
+### Step 3: Identify architecturally significant decisions
+
+Read the diff and extract the decisions that deserve a record. Signals to
+look for, roughly in descending order of significance:
+
+- New or swapped runtime dependencies (package.json, pyproject.toml,
+  requirements.txt, go.mod, Cargo.toml, Gemfile, etc.)
+- New top-level modules, packages, or services
+- Database schema changes, new migrations, new storage engines
+- New or changed external contracts: API endpoints, event schemas,
+  message formats, SDK versions
+- Infrastructure changes: Terraform, Helm, Dockerfiles, CI configs that
+  shift where or how the system runs
+- Replacement of an existing implementation (the "we used X, now we use Y"
+  shape)
+- Introduction of a new cross-cutting pattern: caching, async/queues,
+  auth/authz, feature flags, observability
+- Non-trivial changes to shared abstractions, base classes, or protocols
+
+Ignore pure refactors, formatting, lockfile-only changes, and typo fixes
+unless the commit messages frame them as intentional decisions.
+
+Group related changes into a single decision. A single ADR can span many
+files if they all serve one choice (e.g. "adopt Redis for rate limiting"
+might touch code, tests, Helm values, and a dependency file). Don't split
+one decision into multiple ADRs just because it is wide.
+
+### Step 4: Propose the ADR slate
+
+Present the proposed ADRs to the user as a short list. For each entry give:
+
+- A working title (imperative, specific, no filler)
+- One sentence framing the problem
+- The files or areas of the diff that motivate it
+
+Then ask:
+
+> "Here's what I'd like to record. Shall I draft all of them, or do you want
+> to drop, merge, or add any? You can also tell me to write a specific one
+> first."
+
+Honour edits. If the user merges two proposals, keep the combined decision's
+scope in mind when drafting. If they drop one, drop it fully.
+
+### Step 5: For each approved decision, draft the ADR
+
+Follow the MADR 4.x template (see `references/madr-template.md` for the
+full canonical form). Every ADR must have:
+
+- YAML frontmatter with `status: proposed`, `date: <today, YYYY-MM-DD>`,
+  and `decision-makers` set to the branch's commit authors (dedup, drop
+  `[bot]` accounts).
+- A short, descriptive H1 title.
+- `## Context and Problem Statement` — two or three sentences. Use terms
+  from the domain vocabulary visible in the diff. Frame the problem as a
+  question where possible; you want readers curious.
+- `## Decision Drivers` — bullets covering the forces that shaped the
+  decision (quality attributes, constraints, existing conventions in the
+  repo). Keep them specific to the situation, not generic.
+- `## Considered Options` — at least two, ideally three. One of them must
+  be a real alternative; placeholder "do nothing" options are fine only if
+  they genuinely reflect a status quo worth weighing. Read the diff for
+  clues about what was *not* chosen (e.g. imports that were considered,
+  libraries mentioned in comments, removed code that hints at prior attempts).
+- `## Decision Outcome` — a single sentence naming the chosen option and
+  the primary reason. Assertive voice. No hedging.
+- `### Consequences` — mix good and bad, at least one of each. Cover
+  operational and maintenance impact, not only developer ergonomics.
+- `### Confirmation` — how you'd verify the decision was actually adopted
+  (tests, metrics, CI checks, code review rules). Concrete if possible.
+- `## Pros and Cons of the Options` — one subsection per considered option
+  with a short description plus bulleted pros and cons. This is what lets a
+  reader in six months see the trade-space.
+- `## More Information` — optional. Only include links and references that
+  genuinely help (issue trackers, vendor docs, prior ADRs). Skip if empty;
+  don't pad.
+
+File name: `NNNN-title-with-dashes.md`, lowercase, four-digit prefix
+continuing the repo's sequence, kebab-case title derived from the ADR's H1.
+
+### Step 6: Write each ADR and confirm
+
+Write the files with `mkdir -p <adr-dir>` as needed. Then summarise back to
+the user:
+
+```
+Drafted <N> ADR(s) in <adr-dir>:
+  <NNNN>-<slug>.md — <title>
+  ...
+
+Each is marked `status: proposed`. Review, edit as you see fit, and flip the
+status to `accepted` when you're ready.
+```
+
+### Step 7: Offer to commit
+
+Ask the user whether they'd like the ADRs committed to the current branch:
+
+> "Do you want me to commit these ADRs to the current branch? I'll only stage
+> the new files, not anything else you have in flight. Reply 'yes' to commit,
+> or 'no' to leave them unstaged for you to handle."
+
+If the user says yes:
+
+```bash
+git add <adr-dir>/<NNNN>-<slug>.md ...
+git commit -m "docs(adr): add <N> ADR(s) for <branch-name>" \
+           -m "<bullet list of ADR titles>"
+```
+
+Use only the new ADR paths in the `git add` invocation so nothing else the
+user has staged or modified gets pulled in. Report the commit SHA back.
+
+If the user says no (or anything other than yes), leave the files on disk
+unstaged and confirm:
+
+> "Left the ADRs unstaged. Review and commit when you're ready."
+
+Do not push. Do not open a PR. That's a separate workflow.
+
+## Tone and quality guardrails
+
+Before you finalise each ADR, check it against the anti-patterns in
+`references/anti-patterns.md`. Specifically:
+
+- No marketing language or unsubstantiated superlatives.
+- At least one real alternative, not a straw-man.
+- Cost and risk stated alongside benefit.
+- Confidence level honest; if you're unsure, say `status: proposed` and
+  note the uncertainty in `## More Information`.
+- Keep the whole thing tight. If a section has nothing to say, omit it.
+  Empty headings are worse than no heading.
+
+The ADR is meant to read like a journal entry from the decision maker:
+specific, grounded in the actual diff, and useful to whoever reads it next
+quarter when something breaks.
+
+## Reference files
+
+- `references/madr-template.md` — full MADR 4.x template with placeholders.
+- `references/anti-patterns.md` — Zimmermann's ADR anti-patterns with
+  examples; consult before finalising any ADR.

oe_sdk-0.1.0a1/.agents/skills/generate-adr/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "generate-adr",
+  "evals": [
+    {
+      "id": 1,
+      "name": "single-decision-library-swap",
+      "prompt": "I'm on a feature branch where I swapped our in-house retry logic for the `tenacity` library across the HTTP client layer. I've also added `tenacity>=8.2` to pyproject.toml, removed the old retry/ module, and updated three call sites. Generate any ADRs you think this branch warrants.",
+      "expected_output": "A single ADR in docs/decisions/ (NNNN-<slug>.md) using MADR format, capturing the decision to adopt tenacity over the in-house retry helper. Should include at least two considered options (tenacity, keep in-house, optionally backoff/other libs), real trade-offs, and a confirmation strategy. Skill should also ask whether to commit.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "multi-decision-branch",
+      "prompt": "This branch does two things: (1) introduces Redis for distributed rate limiting (new redis dependency, new helm values block, new RateLimiter abstraction) and (2) moves our background jobs off threading onto asyncio with a new asyncio.TaskGroup-based runner. Record these properly.",
+      "expected_output": "Two separate ADRs in docs/decisions/, numbered sequentially. One for the Redis-based rate limiter decision, one for the asyncio concurrency model. Each self-contained, neither trying to cover the other. Skill should also ask whether to commit.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "database-technology-choice",
+      "prompt": "I'm introducing a new service that needs a primary datastore. On this branch I've picked Postgres, added migrations, and wired up SQLAlchemy. Draft the ADR.",
+      "expected_output": "A single ADR using MADR. Must name at least two real alternatives (e.g. MySQL, SQLite, a managed option, or a document store) rather than a straw-man. Decision drivers should reference operational concerns (backups, team familiarity, managed service availability), not just developer ergonomics.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "refactor-only-branch",
+      "prompt": "This branch renames a bunch of functions, moves some modules around, and fixes typos. Generate ADRs for it.",
+      "expected_output": "The skill should recognise there are no architecturally significant decisions here and respond by saying so, rather than inventing an ADR. If it does write anything, it should be at most one ADR clearly scoped to a meaningful decision, not one per rename.",
+      "files": []
+    }
+  ]
+}

oe_sdk-0.1.0a1/.agents/skills/generate-adr/references/anti-patterns.md

@@ -0,0 +1,90 @@
+# ADR anti-patterns
+
+Adapted from Olaf Zimmermann's "How to create Architectural Decision Records
+— and how not to" (ozimmer.ch, 2023). Consult this list before finalising
+any ADR. If a draft smells like one of these, rewrite it.
+
+## Subjectivity patterns
+
+### Fairy Tale (Wishful Thinking)
+
+A shallow justification with only upsides. Pros listed, cons absent.
+
+Bad: "We decided for a load balancer because it balances load, which is a
+good thing."
+
+Fix: name at least one concrete cost, risk, or trade-off. If you truly can't
+find one, you're not looking hard enough, or the decision isn't worth a
+record.
+
+### Sales Pitch
+
+Marketing language. Adjectives and adverbs that can't be backed by evidence.
+
+Bad: "We chose this outstanding technology because it is unrivalled in the
+marketplace; its splendid performance shines everywhere."
+
+Fix: delete every adjective and adverb you can't substantiate. Link to the
+benchmark, issue tracker, or prior experience that supports the claim, or
+remove the claim.
+
+### Free Lunch Coupon
+
+No consequences documented, or only trivially harmless ones. Long-term and
+operational costs hidden.
+
+Bad: "We decided for event-based architecture because it decouples the
+communication participants."
+
+Fix: explicitly name the design, test, and operational cost. Mention who
+pays it (developers, on-call, consumers of the API).
+
+### Dummy Alternative
+
+A fake option to make the preferred choice shine.
+
+Bad: "We decided to use Postgres. We could implement our own relational
+database, but this takes time and effort."
+
+Fix: find a real alternative. For most decisions there's at least one
+industry-standard competitor worth naming. If there genuinely isn't,
+explain why — that's the actual decision.
+
+## Time-dimension patterns
+
+### Sprint (Rush)
+
+Only one option. Only short-term consequences considered.
+
+Fix: search for alternatives (online, professional networks, the team's own
+history). Report on the search, even briefly. Add at least a sentence on
+mid-term consequences.
+
+### Tunnel Vision
+
+Local view only. Developer experience covered, operations and maintenance
+ignored.
+
+Fix: name sysadmins, SREs, and maintainers explicitly in Decision Drivers
+or Consequences. Score the chosen solution against manageability and
+evolvability.
+
+### Maze
+
+Topic drifts. Discussion centres on irrelevant detail.
+
+Fix: keep the title and problem statement in view while writing. If a
+paragraph doesn't serve the stated question, cut it.
+
+## Quality checklist
+
+Before marking an ADR ready for review:
+
+- Does every adjective earn its place?
+- Is there at least one genuine alternative?
+- Is there at least one real trade-off in Consequences?
+- Would an operator or maintainer recognise their concerns in the ADR?
+- If someone asked "why this, not that?" in review, is the answer already
+  in the document?
+- Is the word count proportionate to the stakes? One page for routine
+  choices; a few pages only when the problem is genuinely wicked.

oe_sdk-0.1.0a1/.agents/skills/generate-adr/references/madr-template.md

@@ -0,0 +1,100 @@
+# MADR 4.x Template
+
+Use this as the canonical template when drafting a new ADR. Remove any
+optional sections (marked below) that you don't need, rather than leaving
+them empty.
+
+```markdown
+---
+# status options: proposed | rejected | accepted | deprecated | superseded by ADR-NNNN
+status: proposed
+date: YYYY-MM-DD
+decision-makers: [list of people involved in the decision]
+# consulted: [optional list of SMEs and others with two-way communication]
+# informed: [optional list of people kept up-to-date, one-way communication]
+---
+
+# {short title, representative of solved problem and found solution}
+
+## Context and Problem Statement
+
+{Describe the context and problem statement in two or three sentences, or as
+an illustrative story. Frame the problem as a question where possible, and
+link to issue trackers or design docs where useful.}
+
+## Decision Drivers
+
+* {driver 1, e.g. a force, facing concern, quality attribute}
+* {driver 2}
+* ...
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because {justification: e.g. only
+option that meets a k.o. criterion; resolves a key driver; comes out best
+when weighed against the others}.
+
+### Consequences
+
+* Good, because {positive consequence, e.g. improvement of a desired quality}
+* Bad, because {negative consequence, e.g. cost, complexity, new failure mode}
+* ...
+
+### Confirmation
+
+{How will implementation of and compliance with this decision be confirmed?
+Code review rules, automated tests, CI checks, a dashboard metric, a runbook
+reference. Concrete if possible.}
+
+## Pros and Cons of the Options
+
+### {title of option 1}
+
+{description, 1-2 sentences, or a link}
+
+* Good, because {argument}
+* Good, because {argument}
+* Neutral, because {argument}
+* Bad, because {argument}
+
+### {title of option 2}
+
+{description}
+
+* Good, because {argument}
+* Bad, because {argument}
+
+### {title of option 3}
+
+{description}
+
+* Good, because {argument}
+* Bad, because {argument}
+
+## More Information
+
+{Optional. Links to related ADRs, vendor documentation, benchmarks, issue
+trackers, prior art. Omit the section entirely if there's nothing worth
+linking.}
+```
+
+## File naming
+
+- Pattern: `NNNN-title-with-dashes.md`
+- `NNNN` is a zero-padded four-digit sequence (`0001`, `0002`, ...)
+- Title is kebab-case, lowercase, derived from the ADR's H1
+- Example: `0007-use-postgres-for-rate-limiter-state.md`
+
+## Status lifecycle
+
+- `proposed` — drafted, not yet agreed
+- `accepted` — agreed and being enacted
+- `rejected` — considered and ruled out
+- `deprecated` — no longer applicable
+- `superseded by ADR-NNNN` — a later ADR replaces this one