with one click
write-spec
// When the user mentions creating, writing, or updating a spec, or when chained from /discuss before /write-ticket, invoke this.
// When the user mentions creating, writing, or updating a spec, or when chained from /discuss before /write-ticket, invoke this.
| name | write-spec |
| description | Spec-authoring primitive for explicit spec requests or workflow chains; creates or updates behavioral specs for caller-visible workflow behavior. |
| argument-hint | [area name, or spec file path to update] |
Target: $ARGUMENTS
ws-print-infra spec-conventions.md (Bash) before any write or update — conventions are canonical there.judge: directory-vs-flat.ws-spec-build-index (no args) after every write or update./proceed → continue with appropriate next step./write-ticket. Exit.$ARGUMENTS — area name, file path, or description.judge: directory-vs-flat to choose the file structure.
b. Write the spec body following the spec-format template. Apply judge: idea-level before inserting any 🚧 entries.
c. Run ws-spec-build-index (no args) for cleanup and verification.
d. Add the spec to the listing in ai-docs/_index.md.ws-generate-spec-stem <descriptive-slug> to get a collision-free {#YYMMDD-slug}.
c. Insert the anchor — on a heading line or anywhere in body text (not heading-only).
d. Apply judge: idea-level before adding any 🚧 Planned callouts. Remove 🚧 from confirmed-implemented features as needed.
e. Run ws-spec-build-index (no args) for cleanup and verification.judge: split-trigger after writing — if any section warrants its own file, extract it to <area>/<section>.md and replace the original section with See [section.md](section.md).ai-docs/_index.md if the listing changed) then commit:
git add <file(s)> && git commit -m "$(cat <<'EOF'\n...\nEOF\n)". Do not use git add -A. Chaining in one invocation minimizes interleave risk from concurrent sessions.Evaluate whether the work introduces or modifies behavior a caller can observe from outside the implementation. Internal restructuring, refactors that preserve external behavior, or tooling changes with no public-facing surface are not spec-relevant. Any addition to or change of a callable interface, user-visible output, or documented convention qualifies.
When about to write a 🚧 entry: write it. Then emit this session reminder: "Session reminder: a non-epic, non-research ready/ ticket must exist before this session ends for this 🚧 entry to be valid per spec-conventions." Do not ask the user whether to defer — write the entry and remind.
Use a directory (<area>/index.md + child files) when the area has or will have sub-sections split across multiple files. Use a flat file (<area>.md) for a single, self-contained feature surface. When uncertain, start flat — convert to directory when the split trigger fires.
Extract a section into its own file when it has:
> [!note] Constraints block, ORAny one condition is sufficient.
After writing or updating a spec file:
ws-spec-build-index
Scans all *.md files under ai-docs/spec/ automatically. Removes any features: and stems: frontmatter blocks. No file arguments accepted. Output: [fix] for auto-applied cleanup (e.g. features: removed — <path>), [warn] for items needing human judgment (duplicate stems, staleness, anchor integrity). Parse failures and missing directory emit [error] to stderr. Always exits 0.
---
title: <Area / Feature Name>
summary: <One-line external-perspective summary>
---
# <Area / Feature Name>
<One-two sentence summary.>
## Implemented Feature {#YYMMDD-implemented-feature}
Behavioral description. Pseudo-code where it aids clarity.
A specific sub-concept within a section can also carry an anchor. {#YYMMDD-sub-concept}
> [!note] Constraints
> - Intentional limitation or out-of-scope boundary.
> [!note] Planned 🚧
> Will gain X capability. Current behavior unchanged until implemented.
## 🚧 New Feature {#YYMMDD-new-feature}
Planned behavior description — what the caller will observe once implemented.
Anchoring rules:
ws-generate-spec-stem <descriptive-slug> to obtain a {#YYMMDD-slug} before inserting any anchor.[stem/pN]) in headings or 🚧 markers — implementation traceability is via commits referencing spec-stems.renamed-spec: <old-stem> → <new-stem>.Spec documents are the pivot for discussion sessions — when the topic is "what does this currently do from the outside," the spec must answer without requiring source exploration. Every authoring choice optimizes for drift resistance at the behavioral level: describe what callers observe, not what the implementation does, so that internal refactors preserving behavior do not invalidate the spec. When a rule is ambiguous, apply whichever interpretation a reader could verify without reading source code.
[HINT] Download the complete skill directory including SKILL.md and all related files