spec

Name: spec
Author: Codagent-AI

28stars1forks

How to install spec?

codagent-ai/agent-skills/spec

$npx -y skills add Codagent-AI/agent-skills --skill spec

Installs into the current project.

Summary

Drives interactive requirement discovery to produce spec files. Use when the user says "spec this", "write specs", "create specs", or "run the spec skill".

Files · 1

View on GitHub

SKILL.md

1	# Spec
2
3	## Overview
4
5	Help turn proposals into fully specified requirements through natural collaborative dialogue.
6
7	Start by reading the proposal's Capabilities section to know which spec files to create, then walk through each capability conversationally — asking questions one at a time to elicit behaviors, boundaries, error conditions, and edge cases. Once you have enough information for a capability, present the proposed requirements and scenarios for user approval, then write the spec file.
8
9	<HARD-GATE>
10	Do NOT write any spec files until you have presented the proposed requirements and scenarios to the user and received approval for that capability. Use the appropriate tool for asking the user a question or requesting input to get this approval. This applies to EVERY capability regardless of perceived simplicity.
11	</HARD-GATE>
12
13	## Anti-Pattern: "The Design Will Figure It Out"
14
15	Every capability needs its behavioral contract specified before design begins. Edge cases, error conditions, and boundaries that feel "obvious" are where misaligned assumptions cause the most rework. The spec can be short (a few scenarios for simple capabilities), but you MUST elicit them conversationally and get approval.
16
17	## Checklist
18
19	You MUST create a task for each of these items and complete them in order:
20
21	1. Read the proposal — identify the Capabilities section and the list of capabilities to spec. Skip if you just wrote the proposal in this session.
22	2. Survey related existing specs — before asking questions, scan any existing spec files in neighboring or overlapping capabilities. Identify: requirements this change might conflict with, behaviors already specified that this change depends on, and naming/terminology conventions to stay consistent with. For modified capabilities, locate the existing spec file now so you can copy its requirement blocks verbatim when writing the delta. Skip specs you already read earlier in this session.
23	3. For each capability — walk through the conversational requirement-discovery process:
24	a. Ask clarifying questions — one at a time, understand behaviors, boundaries, error conditions, edge cases
25	b. Present spec sections for approval — show the proposed requirements and scenarios, get user approval
26	c. Write the spec file — using the Artifact Template below
27	4. Write deferred-to-design markers — for scenarios that depend on unresolved architectural choices
28
29	## Process Flow
30
31	```dot
32	digraph spec {
33	"Read proposal capabilities" [shape=box];
34	"Survey existing specs" [shape=box];
35	"Pick next capability" [shape=box];
36	"Ask clarifying questions" [shape=box];
37	"Present spec sections" [shape=box];
38	"User approves?" [shape=diamond];
39	"Write spec file" [shape=box];
40	"More capabilities?" [shape=diamond];
41	"Done" [shape=box];
42
43	"Read proposal capabilities" -> "Survey existing specs";
44	"Survey existing specs" -> "Pick next capability";
45	"Pick next capability" -> "Ask clarifying questions";
46	"Ask clarifying questions" -> "Present spec sections";
47	"Present spec sections" -> "User approves?";
48	"User approves?" -> "Ask clarifying questions" [label="no, revise"];
49	"User approves?" -> "Write spec file" [label="yes"];
50	"Write spec file" -> "More capabilities?";
51	"More capabilities?" -> "Pick next capability" [label="yes"];
52	"More capabilities?" -> "Done" [label="no"];
53	}
54	```
55
56	## The Process
57
58	Reading the proposal:
59	- If the proposal was written earlier in this session, skip re-reading unless exact wording needs verification
60	- Otherwise, open the proposal's Capabilities section
61	- Use the capability names to determine which spec files to create (one per capability)
62	- Work through capabilities one at a time
63
64	Asking clarifying questions:
65	- Follow the `codagent:ask-questions` skill for how to ask questions (tool to use, batching strategy, question quality)
66	- Focus on: what the system does (behaviors), what it rejects (boundaries), what goes wrong (error conditions), unusual situations (edge cases)
67	- Prefer multiple-choice questions when possible, but open-ended is fine too
68	- Do NOT ask about architecture, patterns, or technical approach — that belongs in design
69	- Ask at least one targeted discovery question for each capability after surveying related specs, unless the proposal and existing specs already answer every behavior, boundary, error condition, and edge case needed for a testable spec. If you skip questions, state the concrete source that answered them.
70	- Ask only questions that change observable behavior or scope. If the uncertainty is implementation-only, leave it for design or implementation.
71	- When presenting options, include a recommended behavior and the trade-off in one or two sentences.
72	- Do NOT treat "does this spec loo

People who liked this also viewed

6 picks

Type

spec

28stars1forks

View on GitHub

How to install spec?

codagent-ai/agent-skills/spec

$npx -y skills add Codagent-AI/agent-skills --skill spec

Installs into the current project.

Summary

Drives interactive requirement discovery to produce spec files. Use when the user says "spec this", "write specs", "create specs", or "run the spec skill".

Files · 1

View on GitHub

SKILL.md

1	# Spec
2
3	## Overview
4
5	Help turn proposals into fully specified requirements through natural collaborative dialogue.
6
7	Start by reading the proposal's Capabilities section to know which spec files to create, then walk through each capability conversationally — asking questions one at a time to elicit behaviors, boundaries, error conditions, and edge cases. Once you have enough information for a capability, present the proposed requirements and scenarios for user approval, then write the spec file.
8
9	<HARD-GATE>
10	Do NOT write any spec files until you have presented the proposed requirements and scenarios to the user and received approval for that capability. Use the appropriate tool for asking the user a question or requesting input to get this approval. This applies to EVERY capability regardless of perceived simplicity.
11	</HARD-GATE>
12
13	## Anti-Pattern: "The Design Will Figure It Out"
14
15	Every capability needs its behavioral contract specified before design begins. Edge cases, error conditions, and boundaries that feel "obvious" are where misaligned assumptions cause the most rework. The spec can be short (a few scenarios for simple capabilities), but you MUST elicit them conversationally and get approval.
16
17	## Checklist
18
19	You MUST create a task for each of these items and complete them in order:
20
21	1. Read the proposal — identify the Capabilities section and the list of capabilities to spec. Skip if you just wrote the proposal in this session.
22	2. Survey related existing specs — before asking questions, scan any existing spec files in neighboring or overlapping capabilities. Identify: requirements this change might conflict with, behaviors already specified that this change depends on, and naming/terminology conventions to stay consistent with. For modified capabilities, locate the existing spec file now so you can copy its requirement blocks verbatim when writing the delta. Skip specs you already read earlier in this session.
23	3. For each capability — walk through the conversational requirement-discovery process:
24	a. Ask clarifying questions — one at a time, understand behaviors, boundaries, error conditions, edge cases
25	b. Present spec sections for approval — show the proposed requirements and scenarios, get user approval
26	c. Write the spec file — using the Artifact Template below
27	4. Write deferred-to-design markers — for scenarios that depend on unresolved architectural choices
28
29	## Process Flow
30
31	```dot
32	digraph spec {
33	"Read proposal capabilities" [shape=box];
34	"Survey existing specs" [shape=box];
35	"Pick next capability" [shape=box];
36	"Ask clarifying questions" [shape=box];
37	"Present spec sections" [shape=box];
38	"User approves?" [shape=diamond];
39	"Write spec file" [shape=box];
40	"More capabilities?" [shape=diamond];
41	"Done" [shape=box];
42
43	"Read proposal capabilities" -> "Survey existing specs";
44	"Survey existing specs" -> "Pick next capability";
45	"Pick next capability" -> "Ask clarifying questions";
46	"Ask clarifying questions" -> "Present spec sections";
47	"Present spec sections" -> "User approves?";
48	"User approves?" -> "Ask clarifying questions" [label="no, revise"];
49	"User approves?" -> "Write spec file" [label="yes"];
50	"Write spec file" -> "More capabilities?";
51	"More capabilities?" -> "Pick next capability" [label="yes"];
52	"More capabilities?" -> "Done" [label="no"];
53	}
54	```
55
56	## The Process
57
58	Reading the proposal:
59	- If the proposal was written earlier in this session, skip re-reading unless exact wording needs verification
60	- Otherwise, open the proposal's Capabilities section
61	- Use the capability names to determine which spec files to create (one per capability)
62	- Work through capabilities one at a time
63
64	Asking clarifying questions:
65	- Follow the `codagent:ask-questions` skill for how to ask questions (tool to use, batching strategy, question quality)
66	- Focus on: what the system does (behaviors), what it rejects (boundaries), what goes wrong (error conditions), unusual situations (edge cases)
67	- Prefer multiple-choice questions when possible, but open-ended is fine too
68	- Do NOT ask about architecture, patterns, or technical approach — that belongs in design
69	- Ask at least one targeted discovery question for each capability after surveying related specs, unless the proposal and existing specs already answer every behavior, boundary, error condition, and edge case needed for a testable spec. If you skip questions, state the concrete source that answered them.
70	- Ask only questions that change observable behavior or scope. If the uncertainty is implementation-only, leave it for design or implementation.
71	- When presenting options, include a recommended behavior and the trade-off in one or two sentences.
72	- Do NOT treat "does this spec loo

People who liked this also viewed

6 picks

Type