Produce a Google-style design doc that names the problem, proposes a solution,
considers alternatives honestly, and surfaces the risks the proposer least wants
to write down — well-architected by construction, then converged against review.
If any check fails, push back rather than proceeding.
-
Frame the problem. Ask only what is genuinely missing — what we're
building, who's affected, why now, what would count as success. Skip
anything the user already said. Three to five questions max; if the
user can't answer one, flag it as an open question rather than blocking.
-
Consult available knowledge surfaces. Before shaping the concept,
establish what enterprise context you can reach, and state which surface
you detected (or "none") in the concept. If you detect an internal
knowledge-retrieval surface this session (an enterprise-knowledge MCP tool,
an internal CLI, an in-repo doc set — public web search does not count),
load references/knowledge-surfaces.md, consult the design-relevant areas,
and treat a single unconfirmed source as lower-confidence. If not, ask
the user for the missing context and lower the confidence of any proposal
that leaned on it — as you degrade when desk-research is absent. Either way,
never fabricate landscape/standards/in-flight facts.
Ground the platform-service contract. The never-fabricate rule extends to
the binding contract of any managed service the design depends on. For every
managed service on a critical path, ground its binding contract —
non-configurable limits, scaling floors, cold-start behaviour, network /
identity requirements — in an authoritative source: a curated platform skill
for that vendor if one is installed; else the provider's official docs; else
desk-research. Carry source + confidence on each load-bearing figure, and
lower the confidence and flag any claim you could not ground. Never
assert a service contract from model memory — a binding limit recalled
wrong is the design miss that surfaces two days into the build, not at review.
This is scoped to load-bearing critical-path claims (a limit the design
actually depends on), not every service mention. On an unfamiliar managed
surface with no platform skill installed, recommend installing one rather
than guessing the number.
-
Shape the concept first (Stage 0). Before the full doc, draft a
≤½-page concept from assets/concept.md — problem + constraints, 1–2
candidate shapes, provider / provider-class, top 2–3 prioritized quality
attributes (rank by business-importance × architectural-risk) — and
wait for the user to agree the shape. This is shaping (context +
constraints + the choice), not the refused "just write the proposal
section" advocacy (see Anti-patterns). Make it well-architected by
construction: a named provider → references/well-architected-pillars.md
(it routes a Hetzner-class primitives provider to
references/cloud-primitives.md's capability gaps); a local-first start
→ references/local-dev.md; in all cases name the tradeoff / sensitivity
points (references/tradeoffs-and-sensitivity.md). No provider → still
produce the concept, forcing no provider/pillar scaffolding. No shipped
reference fits the domain → the leading-edge method
(references/leading-edge-domains.md): flag novelty, compose with desk-research
if present (degrade + lower confidence if absent), carry source + confidence.
Routing has a second, orthogonal axis — workload class: when an LLM or
agent is on the critical path — a generative or agentic workload (the
design generates text on the path, calls tools, takes autonomous action, or
runs an agent loop) — additionally load references/lens-genai-agentic.md and
shape the concept against the tier(s) that apply. This is additive to the
provider axis, not either/or — an agentic system on a named cloud loads
both the provider pillars and the agentic overlay; a plain generative
design (RAG/chat that only produces text) loads the overlay at its baseline
tier only. The overlay itself gates which tiers bite — do not enumerate its
concerns here.
-
Draft inline. Use the skeleton in assets/design-doc.md (load it
when you start the draft). Sections in order: TL;DR (≤3 sentences),
Context, Goals and Non-goals, Proposal, Alternatives Considered, Risks,
Rollout, Open Questions. Embed Mermaid diagrams where structural
reasoning genuinely needs a picture — not as decoration.
-
Self-check against the rubric in references/design-doc-rubric.md.
Walk it line by line; fix what fails before showing the draft.
Common failures:
- Non-goals empty or unconvincing → load
references/alternatives.md.
- Alternatives are strawmen → load
references/alternatives.md and
redraft until each could have been chosen by a reasonable engineer.
- No cross-cutting concerns named → load
references/nfr-checklist.md.
-
Converge against review. After the full draft, run
references/convergence-loop.md: obtain a review pass (from
architect-review if installed, else your embedded rubric self-check),
auto-resolve mechanical findings without asking, re-review, repeat to
the pass cap / stasis escape. Never auto-resolve a judgment finding —
surface the tradeoff / risk / low-confidence calls as explicit decisions.
-
Offer to save — config-driven, per-effort folder. Resolve where the
design effort lands, in this order, in this skill body. Reading is
prompt-only (Charter Principle 3): this skill reads a file and
reasons about a path — there is no engine, index, daemon, or watcher
behind it, and the only code that ever writes the layout file is the
install-time append. See
references/agentbundle-layout.md
for the [architecture] section's full schema.
Resolution order:
a. Repo-root config — read ./agentbundle-layout.toml
[architecture] output_dir. Repo-scope takes priority so that a
project or team convention applies when you're in this repo. The
file is adopter-owned, never shipped into a projected path:
[architecture]
output_dir = "docs/design"
b. User-profile config — read ~/.agentbundle/agentbundle-layout.toml
[architecture] output_dir. User-scope is the fallback — useful for
a personal vault when no repo convention is set.
c. Two-branch elicitation — when neither config resolves, ask which
branch fits — never a silent default:
- Repo branch — "Commit to this repo? Suggest:
docs/design/
(team-visible, version-controlled). Enter path or press Enter to
accept:" On accept, write output_dir = "<path>" to
./agentbundle-layout.toml [architecture].
- Personal/vault branch — "Write to a personal workspace (e.g.
Obsidian vault)? Enter the absolute path. Example:
~/Documents/<VaultName>/design/ (no default)." On accept, write
to ~/.agentbundle/agentbundle-layout.toml [architecture].
Once the base is resolved, each design effort gets its own
per-effort folder: <output_dir>/<topic-slug>/ where <topic-slug>
is a short (~2–5 word) kebab-case slug derived from the design doc's
title. The design doc, diagrams, and notes all go inside that folder —
not as a loose file beside it.
Anchor output_dir by the layout file's own location, never against
the ambient cwd: a repo-root file's output_dir is
repo-root-relative (an absolute value is permitted but warn it as
non-portable); a user-profile file's output_dir must be an
explicit absolute path (~-anchored is fine), and a relative value
there is an Ask-first deviation, never silently resolved.
Resolve, then surface, then write. After anchoring, resolve output_dir
to its full absolute path — ~-expand it and realpath-resolve it
so any symlink in the path is made visible and never silently followed
out of the intended root — and reject any .. escape. The ..
rejection and the realpath happen after anchoring, so a relative
repo-file value that escapes via .. (e.g. output_dir = "../../etc")
is caught regardless of which file supplied it; anchoring never blesses a
..-bearing value as in-tree. Then surface the resolved absolute path
to the adopter before creating the effort folder — the first write is
always preceded by the path you are about to write under.
A repo-root-sourced output_dir that resolves outside the repo tree —
or whose resolution required following a symlink out of the intended root
— is untrusted-origin: confirm the resolved absolute path with the
adopter before writing.
Saving is an offer, never automatic.
-
Decision-moment prompt. If the doc captures one or more discrete
decisions (technology choice, structural commitment, interface
contract), end with one sentence: " decision(s) here look
ADR-worthy — capture them with your ADR skill?" Don't couple to a
specific ADR implementation; let the user route.
