init-design

Skill: init-design

Set up and carry out a new design in docs/design/designs/<name>/. Follows the conventions established in platform-actors — a brief README index, problem statement, scope, architecture decisions, open questions, and per-concern sub-documents. Ends with scaffolded stubs for each planned document.

---

Trigger

Invoked when the user asks to start a design for a new feature, module, or cross-cutting concern. Examples:

• "start a design for X"
• "set up the design docs for X"
• "run init-design on X"

---

Steps

1. Clarify scope (ask the user)

Before writing anything, ask two questions in a single message:

a. Pull in related context? Should I scan the repo for existing code, specs, or design docs relevant to <feature>? (Relevant modules, OpenAPI specs, existing ORM models, etc.) This shapes the problem statement and identifies constraints before you commit to an approach.

b. Documents to create? Besides README.md, which concern-level docs do you want scaffolded now? Suggest a default list based on the feature — the platform-actors design used: actors.md, access-scenarios.md, endpoints.md, openapi-sketch.yaml, per-actor subdirs (each with README.md, auth.md, endpoints.md), authorization-server/. Say which you want, or say "suggest" and I'll propose a list with rationale.

Wait for the user's answers before proceeding.

2. Pull in related context (if yes)

Search for:

• Existing source modules that the feature touches (grep for the feature noun in src/, openapi/)
• Existing design docs that mention the feature or its entities
• OpenAPI specs that will need extending
• ORM models and migrations relevant to the new entities
• Existing permission scopes in admin/core/permissions.py

Summarise findings in a short bullet list to the user before writing any docs. This becomes the raw material for the "Relationship to existing work" section of the README.

3. Write the README

docs/design/designs/<name>/README.md — the index and anchor doc for the design. Structure: