Skip to content

Commit 7ff7347

Browse files
mark-hingstonmark-hingston
committed
chore: update templates and bump version
1 parent 530c644 commit 7ff7347

35 files changed

+1193
-45
lines changed

‎.specfirst/config.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
constraints: {}
2+
custom_vars: {}
3+
framework: ""
4+
language: ""
5+
project_name: specfirst
6+
protocol: todo-cli

‎.specfirst/protocols/api-feature.yaml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
approvals:
2+
- role: architect
3+
stage: design
4+
- role: product
5+
stage: design
6+
description: Accelerates API development with specification-driven design, implementation, and verification.
7+
name: api-feature
8+
stages:
9+
- id: clarify
10+
intent: exploration
11+
name: Requirements Clarification
12+
outputs:
13+
- requirements.md
14+
template: api-feature/clarify.md
15+
type: spec
16+
- depends_on:
17+
- clarify
18+
id: design
19+
inputs:
20+
- requirements.md
21+
intent: decision
22+
name: API Design
23+
outputs:
24+
- design.md
25+
template: api-feature/design.md
26+
type: spec
27+
- depends_on:
28+
- clarify
29+
- design
30+
id: decompose
31+
inputs:
32+
- requirements.md
33+
- design.md
34+
intent: planning
35+
name: Task Breakdown
36+
outputs:
37+
- tasks.yaml
38+
prompt:
39+
granularity: ticket
40+
max_tasks: 10
41+
template: api-feature/decompose.md
42+
type: decompose
43+
- depends_on:
44+
- clarify
45+
- design
46+
- decompose
47+
id: implementation
48+
inputs:
49+
- requirements.md
50+
- design.md
51+
- tasks.yaml
52+
intent: execution
53+
name: Implementation
54+
outputs: []
55+
source: decompose
56+
template: api-feature/implementation.md
57+
type: task_prompt
58+
version: "1.1"

‎.specfirst/protocols/multi-stage.yaml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: "multi-stage"
2+
version: "2.0"
3+
4+
stages:
5+
- id: requirements
6+
name: Requirements Gathering
7+
type: spec
8+
intent: exploration
9+
template: requirements.md
10+
depends_on: []
11+
outputs: [requirements.md]
12+
output:
13+
format: markdown
14+
sections:
15+
- Goals
16+
- Non-Goals
17+
- Assumptions
18+
- Constraints
19+
- Open Questions
20+
21+
- id: design
22+
name: System Design
23+
type: spec
24+
intent: decision
25+
template: design.md
26+
depends_on: [requirements]
27+
inputs: [requirements.md]
28+
outputs: [design.md]
29+
prompt:
30+
intent: design_outline
31+
rules:
32+
- Do not propose implementation details
33+
- Prefer interfaces over concrete choices
34+
output:
35+
format: markdown
36+
sections:
37+
- Architecture
38+
- Components
39+
- Interfaces
40+
- Trade-offs
41+
42+
- id: decompose
43+
name: Task Decomposition
44+
type: decompose
45+
intent: planning
46+
template: decompose.md
47+
depends_on: [requirements, design]
48+
inputs: [requirements.md, design.md]
49+
outputs: [tasks.yaml]
50+
prompt:
51+
intent: task_decomposition
52+
granularity: ticket
53+
max_tasks: 12
54+
prefer_parallel: true
55+
rules:
56+
- Prefer parallelizable tasks
57+
- Surface unknowns explicitly
58+
- Tasks must be independently reviewable
59+
required_fields:
60+
- id
61+
- title
62+
- goal
63+
- acceptance_criteria
64+
- dependencies
65+
- files_touched
66+
- risk_level
67+
- estimated_scope
68+
- test_plan
69+
output:
70+
format: yaml
71+
72+
- id: implement
73+
name: Implementation
74+
type: task_prompt
75+
intent: execution
76+
template: implementation.md
77+
depends_on: [requirements, design, decompose]
78+
inputs: [requirements.md, design.md, tasks.yaml]
79+
source: decompose
80+
outputs: []

‎.specfirst/protocols/todo-cli.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: todo-cli-protocol
2+
stages:
3+
- id: clarify
4+
intent: exploration
5+
name: Requirements Clarification
6+
outputs:
7+
- requirements.md
8+
template: todo-cli/clarify.md
9+
type: spec
10+
- depends_on:
11+
- clarify
12+
id: design
13+
inputs:
14+
- requirements.md
15+
name: System Design
16+
outputs:
17+
- design.md
18+
template: todo-cli/design.md
19+
type: spec
20+
- depends_on:
21+
- clarify
22+
- design
23+
id: breakdown
24+
inputs:
25+
- requirements.md
26+
- design.md
27+
name: Task Decomposition
28+
outputs:
29+
- tasks.yaml
30+
prompt:
31+
granularity: ticket
32+
max_tasks: 5
33+
template: todo-cli/decompose.md
34+
type: decompose
35+
- depends_on:
36+
- clarify
37+
- design
38+
- breakdown
39+
id: codes
40+
inputs:
41+
- requirements.md
42+
- design.md
43+
- tasks.yaml
44+
name: Task Implementation
45+
source: breakdown
46+
template: todo-cli/implementation.md
47+
type: task_prompt
48+
version: "1.1"

‎.specfirst/state.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"protocol": "api-feature",
3+
"current_stage": "",
4+
"completed_stages": [],
5+
"started_at": "2026-01-12T09:37:37.337159Z",
6+
"spec_version": "",
7+
"stage_outputs": {},
8+
"attestations": {},
9+
"epistemics": {
10+
"confidence": {
11+
"overall": ""
12+
}
13+
}
14+
}

‎.specfirst/templates/api-feature/clarify.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# {{ .StageName }} - {{ .ProjectName }}
2+
3+
You are performing a requirements clarification step for a software-building task.
4+
5+
Your goal is to transform the user's request into a clear, bounded set of requirements
6+
that can be safely designed, decomposed, and implemented without guesswork.
7+
8+
## Rules
9+
- Do NOT design the solution.
10+
- Do NOT propose architecture or implementation details.
11+
- Focus only on scope, intent, constraints, and definition of done.
12+
- Prefer explicit statements over assumptions.
13+
- If something is unclear, surface it as an open question.
14+
- If you must proceed without an answer, state the assumption explicitly.
15+
- Keep the output concise and structured.
16+
17+
## Fast-Path Check (Internal)
18+
Before writing the full document, determine whether the user input already contains:
19+
- Clearly defined scope
20+
- Explicit acceptance criteria or definition of done
21+
- Known constraints or stated assumptions
22+
23+
If all are present:
24+
- Use the FAST-PATH.
25+
- Produce a compressed version of the document using the standard headings.
26+
- Begin the document with the line: `FAST-PATH USED`.
27+
28+
If any are missing:
29+
- Perform full clarification.
30+
- Begin the document with the line: `FULL CLARIFICATION REQUIRED`.
31+
32+
## Output Format
33+
Produce one document named `requirements.md` with the following sections,
34+
in this exact order and with these exact headings:
35+
36+
### 1. Problem Statement
37+
- 1-3 sentences describing the problem being solved and why.
38+
39+
### 2. Users & Primary Use Cases
40+
- Bullet list of user types and what they need to do.
41+
42+
### 3. In Scope
43+
- Explicit list of what will be built or changed.
44+
45+
### 4. Out of Scope / Non-Goals
46+
- Explicit exclusions.
47+
- This section is mandatory.
48+
49+
### 5. Acceptance Criteria
50+
- Testable conditions.
51+
- Use checklists or Given/When/Then where possible.
52+
53+
### 6. Constraints
54+
- Technical constraints (stack, APIs, data, performance).
55+
- Non-technical constraints (security, compliance, timelines).
56+
57+
### 7. Open Questions & Assumptions
58+
- Blocking questions that affect scope or behavior.
59+
- If unanswered, list the assumption being made.
60+
61+
## Stopping Conditions
62+
If there are unresolved blocking questions and no safe assumptions can be made:
63+
- Stop.
64+
- Ask the user the minimum number of questions required to proceed.
65+
- Do not continue to downstream stages.
66+
67+
## Output Format Constraints
68+
CRITICAL: You must output ONLY the raw markdown content for the file.
69+
- Do NOT include any conversational text (e.g. "Here is the file...", "I will now...").
70+
- Do NOT include markdown code block fences (```markdown ... ```) around the content.
71+
- Start directly with the markdown content (e.g. # Title).

‎.specfirst/templates/api-feature/decompose.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# {{ .StageName }} - {{ .ProjectName }}
2+
3+
## Context
4+
{{- range .Inputs }}
5+
<artifact name="{{ .Name }}">
6+
{{ .Content }}
7+
</artifact>
8+
9+
{{- end }}
10+
11+
## Requirements Contract
12+
You must follow the clarified requirements exactly.
13+
14+
- Treat In Scope and Out of Scope / Non-Goals as hard boundaries.
15+
- Use Acceptance Criteria as the definition of done.
16+
- Respect all stated Constraints.
17+
- Treat listed Assumptions as true unless explicitly challenged.
18+
19+
If you believe the requirements are incorrect, incomplete, or unsafe:
20+
- Stop.
21+
- Explain the issue.
22+
- Propose a revision to requirements.md.
23+
- Do NOT silently override requirements.
24+
25+
## Task
26+
Break down the API design into implementable tasks.
27+
28+
Each task should be:
29+
- Independently completable
30+
- Testable
31+
- Reviewable
32+
- Small enough to finish in 1-4 hours
33+
34+
## Output Format
35+
YAML list of tasks with this structure:
36+
37+
```yaml
38+
tasks:
39+
- id: T1
40+
title: "Short task name"
41+
goal: "What this task accomplishes"
42+
acceptance_criteria:
43+
- "Criterion 1"
44+
- "Criterion 2"
45+
dependencies: [] # IDs of tasks that must complete first
46+
files_touched:
47+
- "path/to/file.go"
48+
risk_level: "low|medium|high"
49+
estimated_scope: "S|M|L"
50+
test_plan:
51+
- "How to verify this task"
52+
```
53+
54+
## Decomposition Guidelines
55+
56+
### Good Task Boundaries
57+
- Implement single endpoint
58+
- Add database migration
59+
- Write integration test suite
60+
- Add monitoring/alerts
61+
62+
### Avoid
63+
- Tasks mixing infrastructure + business logic
64+
- Tasks spanning multiple endpoints
65+
- "Finish everything" tasks
66+
67+
### Ordering
68+
Order tasks by:
69+
1. Dependencies first (data models, migrations)
70+
2. Core logic
71+
3. Tests and monitoring
72+
4. Documentation
73+
74+
## Parameters
75+
- Granularity: {{ if .Prompt }}{{ .Prompt.Granularity }}{{ else }}ticket{{ end }}
76+
- Max tasks: {{ if .Prompt }}{{ .Prompt.MaxTasks }}{{ else }}10{{ end }}
77+
78+
## Assumptions
79+
- Design has been approved by architect and product
80+
- (List other assumptions)
81+
82+
83+
## Output Format Constraints
84+
CRITICAL: You must output ONLY the raw markdown content for the file.
85+
- Do NOT include any conversational text (e.g. "Here is the file...", "I will now...").
86+
- Do NOT include markdown code block fences (```markdown ... ```) around the content.
87+
- Start directly with the markdown content (e.g. # Title).

0 commit comments

Comments
 (0)