Ak Dev Write Spec

Write a Spec for a Planned Change

Use this skill when asked to produce spec documents for Agent Kernel work before (or instead of) implementing it. A change is specified in three documents, written in strict order, all under docs/specs/<issue-number>-<short-title>/:

Do not skip ahead. design.md is the document humans review — it must exist and survive its review cycles before effort goes into spec.md. Writing a detailed spec against an unreviewed design wastes the detail work when the design changes.

The same directory may optionally hold a research/ subfolder — the supporting investigation that informed the design (provider surveys, prior-art comparisons, benchmarks, spike notes). It is not a fourth stage and not required; see Optional: research/.

This skill is for writing these documents, not for implementing the change they describe.

Which Stage Are You In?

Route from what the requester asked for and what already exists in docs/specs/<issue-number>-<short-title>/:

• No design.md yet, or the request is "write a spec/design for X" → Stage 1: write design.md and stop there.
• design.md exists and the requester says it is reviewed/approved (or asks for the implementation spec) → Stage 2: write spec.md.
• design.md and spec.md both exist and the requester asks for the plan/breakdown → Stage 3: write plan.md.
• Asked to update an existing document → update that document; if the update changes requirements in design.md, flag that downstream spec.md/plan.md need re-alignment.
• Asked to capture or record research — a provider survey, a prior-art comparison, a benchmark, a spike — → write it under research/ (optional; see Optional: research/). This can happen before design.md exists and does not, on its own, start Stage 1.

Never write spec.md in the same pass as a fresh design.md unless the requester explicitly says to skip the design review.

Why These Documents Are Held to a High Bar

The spec set is the contract the implementation PR is reviewed against: ak-dev-review-pr reviews any spec in a PR before reading code, extracts every must/should statement into a requirements checklist, and flags silent omissions and deviations in the implementation. A vague or unverified spec therefore produces noisy reviews and undetectable regressions. Two properties matter most:

1. Every factual claim about the current code is verified, not remembered. File paths, line numbers, config defaults, "this appears in N places" counts, and behavior descriptions will be re-checked by reviewers against the base branch. One wrong claim taints trust in all the others.
2. Every requirement is concrete enough to test. "Must retry 3 times with a 2-second delay and re-raise the last error" is checkable; "must handle connection failures robustly" is not.

Optional: research/ — Supporting Research

Some changes need real investigation before the design is credible — a survey of third-party providers, a comparison of prior-art approaches, a benchmark, or a throwaway spike. When that work happened, preserve it under an optional research/ subfolder of the spec directory rather than losing it or inlining it into design.md:

docs/specs/<issue-number>-<short-title>/
├── research/            # optional — supporting material, written before or alongside design.md
│   ├── README.md        # optional index of the research files and their one-line takeaways
│   └── <topic>.md       # one file per topic
├── design.md
├── spec.md
└── plan.md

• Optional, and not a stage. Skip it entirely for changes that need no investigation. It has no ordering slot of its own — it is written before or alongside design.md, never generated after plan.md to backfill.
• What goes in it: the raw material behind the design's decisions — provider/tool landscape surveys, prior-art abstraction comparisons, benchmark results, spike findings, decision logs, notes from external sources. One file per topic; a short research/README.md indexing them (with each file's one-line takeaway and status) helps but is not required.
• design.md distills; research/ backs. The design states the decision and cites the research file where a motivation or a decision leans on a finding (e.g. "per-session is the default — see research/lifecycle-survey.md"). Do not paste long surveys into design.md; that is exactly the padding the point-form format exists to avoid.
• A different bar. Research is held to the claims-are-true bar (property 1 above) — verified code citations, and external claims marked as verified or not — but not to the point-form / concise / review-cycle bar of design.md. It may be long-form and exploratory, and it is not rewritten every review cycle.
• Not requirements. ak-dev-review-pr does not extract requirements from research/ and does not hold it to the spec rubric; reviewers may consult it for context. It ships in the design PR as supporting material (see PR Guidance).
• When research is large or reusable — a landscape survey worth discovering from outside this one change — it may instead live as its own research-companion dev skill under .agents/skills/. Use research/ for change-scoped material; promote to a skill only when the research is a durable reference in its own right.

Inputs

• GitHub issue (required): the issue number plus a short title, e.g. issue #492 "Database Drivers Refactoring". Determines the output directory docs/specs/<issue-number>-<short-title>/ — the issue number, a hyphen, then a lowercase kebab-case slug of the change (e.g. docs/specs/492-shared-database-drivers/). If no issue exists, ask for one — do not invent a number.
• Change intent: what the change should accomplish, at whatever level of detail the requester has. Ambiguities you cannot resolve from the code become explicit open questions in design.md, not silent design decisions.

Stage 1: design.md — the Design Spec

design.md is read by an Agent Kernel expert to understand what is changing and why — in minutes, not an afternoon. It goes through multiple manual review cycles, so it is optimized for fast reading and per-point commenting: point form, hierarchical, complete.

Prepare

1. Load ak-dev-architecture — the design must fit the documented architecture (coupling direction, adapter pattern, config via AKConfig, pluggable interfaces), not re-derive it. Its House Patterns for New Features section is the rubric every design is held to: pluggable by default (ABC + factory + dotted-path BYO, even when one backend ships first), reuse of existing configuration over new knobs (existing config implicitly enables the feature where it applies), and classes over script-style functions. A design that departs from one of them says so in an explicit point with the reason; a silent departure is a review finding. When the change adds a component of a kind covered by an ak-dev-new-* skill (framework adapter, guardrail provider, knowledge base, messaging integration, multimodal storage, tracing provider, sandbox provider, queue transport), load that skill too — its checklist defines what "complete" means for the requirements.
2. Do a scoped evidence pass: read the code the change touches well enough that every point you write is verified, and record path:line for the claims that motivate the change. The document stays point-form, but the points must still be true.
3. If a research/ folder exists (or you just did investigation worth keeping), draw the Motivation and decisions from it and cite the relevant files instead of restating their surveys inline. If the investigation is worth preserving but isn't captured yet, write it under research/ first (see Optional: research/).

Format

Point form throughout — bullets, not paragraphs. Break points into sections and keep them hierarchical (a parent point with indented sub-points) so structure carries the meaning. Every point should be atomic enough for a reviewer to comment on it alone.

# #<issue-number>: <one-line summary of the change>

<2–3 sentence summary: what changes, where, and the one-sentence design idea.>

## Motivation

- <Point-form observations from the code, each with its `path:line` evidence>

## Requirements

### <Area or component>

- <Requirement>
  - <Sub-requirement / constraint / concrete value>
- <Requirement>

### <Next area>

...

## Non-goals

- <What this change deliberately does not do>

## Open questions

- <Decisions the requester/reviewer must make — never silently decided>

• Pluggability is a requirement, not an afterthought: when the change touches an external system, backend, or provider, the Requirements name the ABC, the factory (built-in short names, require_extra on optional SDKs, the dotted-path bring-your-own branch), and the contract test suite the backends subclass. One backend shipping first is fine; one backend being the only possible one is not.
• Configuration points are explicit about reuse: a ### Configuration area (or equivalent) states which existing AKConfig models and blocks the feature reuses or subclasses (_QueuesConfig, _ResponseStoreConfig, the _RedisConfig/_DynamoDBConfig/... connection models, presence-enabled blocks such as thread/schedule), whether already-configured components implicitly enable the feature, and every new field with a one-line reason it cannot be derived from existing config. "No new configuration" is a valid and preferred outcome; write it down so reviewers can confirm it. Do not add an enabled flag or a duplicate type selector when existing configuration can stand in for that decision.
• Components are classes: name the classes the change introduces (ABC, backends, factory, orchestrating manager/handler/runner, Pydantic models) and their single responsibility. A design whose components are module-level functions is redesigned before review, not after.
• Component diagram: add one simple diagram (Mermaid) only if it genuinely clarifies how components relate. Do not add more diagrams, sequence charts, or decoration — an over-diagrammed design is harder to review, not easier.
• Complete but concise: every requirement is present; no prose padding, no implementation detail (that belongs in spec.md). If a point needs a paragraph to explain, it is probably an implementation detail — push it down to Stage 2 or split it.
• Each requirement still concrete enough to test (see the high bar above) — point form is a format constraint, not a precision discount.

Review cycles

Deliver design.md and stop. The requester reviews it (typically over multiple cycles); apply their edits and keep the document in reviewable point form throughout. Only when they confirm the design is settled does Stage 2 begin.

Stage 2: spec.md — the Implementation Spec

spec.md details how the approved design is built: the detailed design and the implementation components. It follows design.md — every requirement there is covered here, and any deviation discovered while detailing goes back through design review rather than being silently absorbed.

Step 1: Load the Standards to Design Against

Load these skills before writing — the spec must fit the documented architecture, not re-derive it:

1. ak-dev-architecture — always. Design principles, core abstractions, coupling rules, directory structure.
2. ak-dev-code-quality — always. Conventions the implementation must follow (typing, logging, formatting, commit/PR rules).
3. ak-dev-testing-conventions — always. Testing requirements must use real patterns (pytest, async, monkeypatching config, existing test files and their patch targets).

Then route from the areas the change touches to the specialized ak-dev-new-* skills, exactly as ak-dev-review-pr Step 2 does. When the change adds a component of one of those kinds, the skill's checklist (factory registration, config section, optional-dependency extra, exports, tests, example) defines what "complete" means.

Step 2: Investigate the Current Code — the Evidence Pass

Before writing a word of detailed design, read the code the change touches and collect evidence:

• Read every file that will be created, modified, or deleted — fully, not just the region you expect to change.
• For each claim the spec will make, record path:line at the time of writing. Verify counts by enumerating: if you write "this logic appears in seven places", list the seven places.
• Check the supporting surfaces that specs routinely get wrong:
  • Config: the actual Pydantic classes in ak-py/src/agentkernel/core/config.py — field names, types, defaults, descriptions, and which sections are Optional (a missing block may raise AttributeError, ValueError, or nothing, depending on the default).
  • Optional dependencies: which extras in ak-py/pyproject.toml cover which imports, and which factory paths actually have try/except ImportError (only some do — verify per path, don't generalize).
  • Factories and wiring: SessionStoreBuilder, AttachmentStorageManager, ResponseStoreFactory, framework/provider factories — what selects the component and what error behavior each has.
  • Existing tests: which test files cover the area and what they monkeypatch — plan.md must name the patch targets that move.
  • Dev skills: grep .agents/skills/ for references to classes/files the change moves or renames; the plan's final step updates them.
• Note behavior asymmetries between the copies/paths you touch (e.g. one swallows errors where its twin propagates, one checks config where another doesn't). Each asymmetry forces a design decision the spec must make explicitly.