Rename workflow steps for lexical order

.claude/commands/formspec.1.design.md

@@ -0,0 +1,137 @@
+---
+description: Create a detailed feature design document
+argument-hint: <feature-name>
+allowed-tools: [Read, Write, Edit, Glob, Grep, Task]
+---
+
+# FormSpec Design
+
+You are creating a detailed natural-language design document for a single feature within a formally-specified system.
+
+## Steps
+
+### 1. Validate preconditions
+
+**spec/system.md must exist.** Check with Glob. If it does not exist, tell the user to run `/formspec.0.init` first and stop.
+
+**$ARGUMENTS must provide a feature name.** If empty, ask the user for a feature name. The feature name should be a short kebab-case identifier (e.g., `user-auth`, `billing`, `rate-limiting`).
+
+### 2. Read existing context
+
+Read these artifacts to understand the current system state:
+- `spec/system.md`
+- All existing feature design docs under `spec/features/` (use Glob for `spec/features/*/design.md`)
+
+Understanding existing features is critical — the new feature must be designed in the context of what already exists, and cross-feature impacts must be identified.
+
+### 3. Gather requirements
+
+Through conversation with the developer, establish what this feature does and why. Ask clarifying questions. Do not proceed to writing until you have a clear understanding of:
+- The feature's purpose and scope
+- How it interacts with existing features (if any)
+- Who uses it and how
+- What should NOT happen (failure modes, abuse scenarios)
+
+### 4. Generate the design document
+
+Create `spec/features/YYYY-MM-DD-<feature-name>/design.md` where YYYY-MM-DD is today's date.
+
+The document must have these sections, in this order:
+
+```markdown
+# Feature: <Feature Name>
+
+## Overview
+
+[What this feature does, why it exists, and how it fits into the broader system. Reference spec/system.md architectural constraints where relevant.]
+
+## User Stories
+
+[Numbered US-1, US-2, etc. Each story follows Given/When/Then format.]
+
+US-1: [Title]
+- **Given**: [precondition]
+- **When**: [action]
+- **Then**: [expected outcome]
+
+## Pathological and Adversarial Uses
+
+[What happens when users or attackers misuse this feature. Explicitly consider:]
+- [Abuse scenarios]
+- [Race conditions]
+- [Resource exhaustion]
+- [Privilege escalation]
+- [Any domain-specific attack vectors]
+
+## Edge Cases and Failure Modes
+
+[Boundary conditions, partial failures, timeout behavior, data corruption scenarios, unexpected input.]
+
+## Success Criteria
+
+[Numbered SC-1, SC-2, etc. Measurable outcomes — quantified where possible.]
+
+SC-1: [Criterion with measurable target]
+
+## Security Considerations
+
+[Authentication, authorization, input validation, data exposure risks. Even if the feature seems non-security-critical, consider what an attacker could do with it.]
+
+## Performance Constraints
+
+[Latency bounds, throughput requirements, resource limits. "None" is acceptable if genuinely unconstrained, but think carefully first.]
+
+## Interface Contract
+
+[How external actors interact with this feature. Include this section when the feature exposes an interface that other components, users, or systems consume. Omit it for purely internal features with no external surface.]
+
+[For each interface (CLI, API, wire protocol, library, etc.), describe:]
+- [Transport and framing (e.g., TCP with newline-delimited text, HTTP REST, gRPC, function calls)]
+- [Request/response schemas — the concrete structs, messages, or command-line arguments that are passed. Use the project's natural notation: Go struct literals, JSON schemas, protobuf definitions, CLI usage strings, etc.]
+- [Response types — success, error, and edge-case responses with their exact shapes]
+- [Error conventions — how errors are surfaced (status codes, error fields, exit codes)]
+
+[These schemas are the source of truth for documentation and implementation. The TLA+ specification remains abstract — it models the state transitions and properties, pulling in only those fields directly needed to reason about system behavior. The interface contract captures the concrete surface that the abstract model does not.]
+
+## Dependencies
+
+[Which other features this interacts with. For each dependency, describe the nature of the interaction and what assumptions are made.]
+
+## Open Questions
+
+[Anything that remains unclear. Tag each with [NEEDS CLARIFICATION]. If there are no open questions, omit this section entirely rather than writing "None".]
+
+## Amendments
+
+[Do NOT create this section in new design docs. It is added by `/formspec.2.formalize` when TLC counterexamples force design changes. If this section already exists in a design doc you are editing, preserve it — amendments are permanent records of corrections discovered through formal verification. Only remove an amendment if the requirement it annotates is itself removed through a larger redesign, or changed significantly enough that a plain rewrite is simpler than preserving the amendment history.]
+```
+
+**Quality bar**: The design must be specific enough that a different developer could implement it without further conversation. Vague statements like "should be fast" or "handle errors gracefully" are not acceptable — quantify or describe the specific behavior.
+
+### 5. Update spec/system.md
+
+Make three updates to `spec/system.md`:
+
+**Feature Index**: Add an entry linking to the new design document:
+```
+- [Feature Name](features/YYYY-MM-DD-feature-name/design.md) — one-line summary
+```
+
+**Changelog**: Add a dated entry describing what this feature adds, modifies, or deprecates:
+```
+### YYYY-MM-DD — Feature Name
+- Added: [what new capabilities this introduces]
+- Modified: [what existing behavior changes, if any]
+- Deprecated: [what this replaces, if anything]
+```
+
+**Cross-feature impacts**: If this feature impacts existing features (deprecates user stories, changes behavior, adds new constraints), document that explicitly in the Changelog. For example:
+```
+- Deprecates US-3 of 2026-02-10-user-auth: API key authentication replaced by OAuth
+```
+
+Also update the affected feature's design doc if the impact is significant enough to warrant it (add a note in its Dependencies section).
+
+### 6. Report
+
+Summarize what was created, highlight any cross-feature impacts, and note any open questions that need resolution before formalization. Suggest proceeding with `/formspec.2.formalize` to translate the design into a TLA+ specification.