sdd-flow 1.3.3 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/CONTRIBUTING.md +25 -0
- package/LICENSE +21 -21
- package/README.md +402 -168
- package/README.pt-BR.md +387 -0
- package/bin/cli.js +162 -424
- package/docs/architecture.md +91 -0
- package/docs/distribution.md +64 -0
- package/docs/formats.md +215 -0
- package/docs/local-testing.pt-BR.md +196 -0
- package/docs/methodology.pt-BR.md +139 -0
- package/docs/migration.md +76 -0
- package/docs/quality-gates.pt-BR.md +160 -0
- package/docs/quality.md +56 -0
- package/docs/releases.pt-BR.md +105 -0
- package/docs/setup-documents.pt-BR.md +120 -0
- package/docs/usage.pt-BR.md +310 -0
- package/docs/validation.md +101 -0
- package/lib/adapters.js +115 -0
- package/lib/check.js +221 -0
- package/lib/context.js +117 -0
- package/lib/documents.js +71 -0
- package/lib/handoff.js +81 -0
- package/lib/history.js +16 -0
- package/lib/install.js +181 -0
- package/lib/io.js +119 -0
- package/lib/legacy-hashes.json +31 -0
- package/lib/markdown.js +71 -0
- package/lib/project.js +200 -0
- package/lib/quality.js +24 -0
- package/lib/revisions.js +79 -0
- package/lib/verification.js +267 -0
- package/package.json +55 -32
- package/templates/AGENTS.md +12 -50
- package/templates/QUICKSTART.md +16 -70
- package/templates/agents/AGENTS.md +58 -92
- package/templates/agents/DECISIONS.md +5 -21
- package/templates/agents/POLICIES.md +14 -0
- package/templates/agents/PROJECT.md +35 -145
- package/templates/agents/QUALITY.md +19 -0
- package/templates/agents/RULES.md +24 -132
- package/templates/agents/SETUP.md +38 -224
- package/templates/agents/config.yaml +13 -0
- package/templates/agents/current/_template.md +19 -0
- package/templates/agents/decisions/_template.md +22 -0
- package/templates/agents/prompts/conventional-commit.md +11 -51
- package/templates/agents/prompts/intake.md +23 -0
- package/templates/agents/prompts/pr-template.md +12 -21
- package/templates/agents/prompts/quality.md +57 -0
- package/templates/agents/prompts/rpi-close.md +23 -0
- package/templates/agents/prompts/rpi-implement.md +35 -68
- package/templates/agents/prompts/rpi-plan.md +87 -117
- package/templates/agents/prompts/rpi-research.md +21 -67
- package/templates/agents/prompts/rpi-validate.md +40 -103
- package/templates/agents/prompts/skill-call.md +11 -29
- package/templates/agents/prompts/task-create.md +13 -42
- package/templates/agents/skills/_template/SKILL.md +11 -37
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/claude-code/settings.json +0 -34
- package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/opencode/opencode.json +0 -18
|
@@ -1,224 +1,38 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
.
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
SKILL.md
|
|
40
|
-
specs/
|
|
41
|
-
[empty] ← Auto-populated as features are developed
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
**Files to adjust per project:** `PROJECT.md`, `DECISIONS.md`, `agents/skills/<name>/SKILL.md`
|
|
45
|
-
**Never modify:** `AGENTS.md` (root), `agents/AGENTS.md`, `agents/RULES.md`, all `agents/prompts/`
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## AI-Assisted Setup
|
|
50
|
-
|
|
51
|
-
Use the prompt below in a new agent session to configure the entire workflow automatically. The agent will read your project and produce all required files.
|
|
52
|
-
|
|
53
|
-
### Setup Prompt
|
|
54
|
-
|
|
55
|
-
Copy and use this prompt in your agentic IDE:
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
Read agents/AGENTS.md, agents/RULES.md, and agents/SETUP.md.
|
|
59
|
-
|
|
60
|
-
Your job is to configure this project's SDD workflow by producing three outputs:
|
|
61
|
-
agents/PROJECT.md, agents/DECISIONS.md, and one skill folder per relevant capability
|
|
62
|
-
in agents/skills/.
|
|
63
|
-
|
|
64
|
-
## Input sources (use what is available, in this order of priority)
|
|
65
|
-
|
|
66
|
-
1. PRD or requirements document — if provided, extract stack, architecture, and rules from it
|
|
67
|
-
2. Existing project files — scan the codebase: package.json, pyproject.toml, tsconfig.json,
|
|
68
|
-
README, src/ structure, config files, and any existing documentation
|
|
69
|
-
3. Ask me — if neither is available or if critical information is missing, ask before generating
|
|
70
|
-
|
|
71
|
-
## Output 1 — agents/PROJECT.md
|
|
72
|
-
|
|
73
|
-
Produce a dense, scannable file. Prefer tables over paragraphs. Include:
|
|
74
|
-
|
|
75
|
-
- Project name and purpose (1–2 sentences)
|
|
76
|
-
- Runtime, framework, and key libraries (actual versions if detectable)
|
|
77
|
-
- Persistence layer and access method
|
|
78
|
-
- Frontend stack (if any)
|
|
79
|
-
- File and module structure (table: path → responsibility)
|
|
80
|
-
- Architecture patterns in use (e.g. layered, repository, MVC)
|
|
81
|
-
- Stack Rules: rules already enforced in the codebase
|
|
82
|
-
(naming conventions, forbidden patterns, mandatory abstractions, etc.)
|
|
83
|
-
|
|
84
|
-
## Output 2 — agents/DECISIONS.md
|
|
85
|
-
|
|
86
|
-
For new projects: leave the header only, no entries yet.
|
|
87
|
-
For existing projects: document architectural decisions already present in the codebase.
|
|
88
|
-
Look for: chosen libraries over alternatives, folder organization rationale,
|
|
89
|
-
patterns used consistently, anything that would be a "why did we do it this way" question.
|
|
90
|
-
Format each entry as:
|
|
91
|
-
### [YYYY-MM-DD] Decision title
|
|
92
|
-
**Context:** why this decision existed
|
|
93
|
-
**Decision:** what was chosen
|
|
94
|
-
**Consequences:** what this implies going forward
|
|
95
|
-
|
|
96
|
-
## Output 3 — agents/skills/<name>/SKILL.md
|
|
97
|
-
|
|
98
|
-
Identify which capability domains exist in this project and create one folder per domain,
|
|
99
|
-
each containing a single SKILL.md file.
|
|
100
|
-
Common domains: ui-components, data-access, auth, validation, api-integration, error-handling.
|
|
101
|
-
Only create skills that are actually relevant to this project — do not create generic placeholders.
|
|
102
|
-
|
|
103
|
-
Each SKILL.md must follow this structure:
|
|
104
|
-
# Skill: [Capability Name]
|
|
105
|
-
|
|
106
|
-
## When to use this skill
|
|
107
|
-
[Specific task types that should load this skill]
|
|
108
|
-
|
|
109
|
-
## Patterns
|
|
110
|
-
[Correct approach with concise code examples from this project's stack]
|
|
111
|
-
|
|
112
|
-
## Anti-patterns
|
|
113
|
-
[What NOT to do, with reason]
|
|
114
|
-
|
|
115
|
-
## Checklist
|
|
116
|
-
- [ ] Items the agent must verify before finishing a task using this skill
|
|
117
|
-
|
|
118
|
-
## Constraints
|
|
119
|
-
|
|
120
|
-
- Produce only the three outputs above — no other files
|
|
121
|
-
- Do not create specs or implement any feature
|
|
122
|
-
- Do not run git commands
|
|
123
|
-
- If any critical information is missing and cannot be inferred, ask before generating
|
|
124
|
-
- After delivering all files, wait for my review and approval
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
## Manual Setup (alternative)
|
|
130
|
-
|
|
131
|
-
If you prefer to fill the files yourself:
|
|
132
|
-
|
|
133
|
-
### Step 1 — Fill in PROJECT.md
|
|
134
|
-
|
|
135
|
-
| Placeholder | What to write |
|
|
136
|
-
|---|---|
|
|
137
|
-
| `[FILL: project name and purpose]` | 1–2 sentences describing what the project does |
|
|
138
|
-
| `[FILL: runtime / framework]` | e.g. Node.js + Express, Python + FastAPI |
|
|
139
|
-
| `[FILL: persistence layer]` | e.g. PostgreSQL, MongoDB, Google Sheets |
|
|
140
|
-
| `[FILL: frontend]` | e.g. React + Tailwind, Vue, plain HTML |
|
|
141
|
-
| `[FILL: file/module structure]` | Key files and their responsibilities |
|
|
142
|
-
| `[FILL: architecture patterns]` | e.g. layered, repository pattern, MVC |
|
|
143
|
-
| `[FILL: stack-specific rules]` | Rules unique to your stack |
|
|
144
|
-
|
|
145
|
-
> PROJECT.md is read on every session. Keep it dense — every token counts.
|
|
146
|
-
|
|
147
|
-
### Step 2 — Fill in DECISIONS.md
|
|
148
|
-
|
|
149
|
-
**New project:** leave empty — decisions are recorded as they happen during implementation.
|
|
150
|
-
|
|
151
|
-
**Existing project:** document decisions already made before starting specs. This prevents the agent from re-deciding things already settled. For each decision, record: context, what was chosen, and consequences.
|
|
152
|
-
|
|
153
|
-
### Step 3 — Create Skills
|
|
154
|
-
|
|
155
|
-
Create one folder per capability inside `agents/skills/`, each containing a `SKILL.md` file.
|
|
156
|
-
|
|
157
|
-
**New project:** base skills on your planned stack.
|
|
158
|
-
**Existing project:** extract patterns from the actual codebase — look at how data access, validation, and UI are already handled, and encode those patterns into skills.
|
|
159
|
-
|
|
160
|
-
| Skill folder | When to create |
|
|
161
|
-
|---|---|
|
|
162
|
-
| `agents/skills/ui-components/SKILL.md` | Project has a UI layer |
|
|
163
|
-
| `agents/skills/data-access/SKILL.md` | Project touches a database or persistence layer |
|
|
164
|
-
| `agents/skills/auth/SKILL.md` | Project has authentication or authorization |
|
|
165
|
-
| `agents/skills/validation/SKILL.md` | Project validates user or external input |
|
|
166
|
-
| `agents/skills/api-integration/SKILL.md` | Project calls external APIs |
|
|
167
|
-
| `agents/skills/error-handling/SKILL.md` | Project has a defined error format or logging strategy |
|
|
168
|
-
|
|
169
|
-
Use `agents/skills/_template/SKILL.md` as the starting point for each new skill.
|
|
170
|
-
|
|
171
|
-
> The "When to use this skill" section is critical — it is what the agent reads to decide whether to load the skill for a given task.
|
|
172
|
-
|
|
173
|
-
### Step 4 — Activate harness configs (optional)
|
|
174
|
-
|
|
175
|
-
If you use Claude Code or OpenCode, copy the relevant config to add an enforcement layer at the tool level:
|
|
176
|
-
|
|
177
|
-
**Claude Code:**
|
|
178
|
-
```bash
|
|
179
|
-
mkdir -p .claude && cp agents/harness/claude-code/settings.json .claude/settings.json
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
**OpenCode:**
|
|
183
|
-
```bash
|
|
184
|
-
cp agents/harness/opencode/opencode.json opencode.json
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
These configs add an enforcement layer at the tool level, complementing the behavioral rules in `RULES.md`. The provided examples block or ask confirmation for certain commands — adjust them to match your team's needs. If you use hooks (Claude Code only), also run:
|
|
188
|
-
|
|
189
|
-
```bash
|
|
190
|
-
chmod +x agents/harness/claude-code/.hooks/*.sh
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
### Step 5 — Validate Before First Spec
|
|
194
|
-
|
|
195
|
-
Before starting the first RPIV cycle, confirm:
|
|
196
|
-
|
|
197
|
-
- [ ] Root `AGENTS.md` is present and unmodified
|
|
198
|
-
- [ ] `agents/PROJECT.md` has no `[FILL: ...]` placeholders remaining
|
|
199
|
-
- [ ] `agents/DECISIONS.md` reflects existing architectural decisions (existing projects)
|
|
200
|
-
- [ ] At least one skill folder exists in `agents/skills/` (e.g. `agents/skills/data-access/SKILL.md`)
|
|
201
|
-
- [ ] `agents/AGENTS.md` and `agents/RULES.md` are unmodified
|
|
202
|
-
- [ ] `agents/SETUP.md` is deleted
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## Starting Your First Spec
|
|
207
|
-
|
|
208
|
-
When setup is complete:
|
|
209
|
-
|
|
210
|
-
1. Create the folder: `agents/specs/001-feature-name/`
|
|
211
|
-
2. Run the Research phase using `agents/prompts/rpi-research.md`
|
|
212
|
-
3. Follow the RPIV cycle through to validation
|
|
213
|
-
|
|
214
|
-
---
|
|
215
|
-
|
|
216
|
-
## Language Recommendation
|
|
217
|
-
|
|
218
|
-
| File | Recommended language |
|
|
219
|
-
|---|---|
|
|
220
|
-
| `AGENTS.md` (root), `agents/AGENTS.md`, `agents/RULES.md`, `agents/prompts/` | **English** — read every session, token-sensitive |
|
|
221
|
-
| `agents/PROJECT.md` | **English** — read every session, token-sensitive |
|
|
222
|
-
| `agents/skills/` | **English** — read per task, token-sensitive |
|
|
223
|
-
| `agents/DECISIONS.md` | Team's language — written rarely, read occasionally |
|
|
224
|
-
| `agents/specs/` (RESEARCH, SPEC, TASK, etc.) | Team's language — scoped per feature |
|
|
1
|
+
# Initial project setup
|
|
2
|
+
|
|
3
|
+
1. Inspect the actual project and any supplied requirements. Distinguish observed facts, inferred conventions and unknown decisions. Do not invent historical rationale.
|
|
4
|
+
2. Fill PROJECT.md with a short map. Record mandatory project constraints in POLICIES.md; keep detailed procedures in conditional skills.
|
|
5
|
+
3. Configure mode, autonomy and approval in config.yaml. Keep the new-project step default unless the user chooses batch; preserve an existing project's chosen autonomy. User authorization for several tasks or all tasks may override step for that request without changing the standing preference. Use exact check commands from project configuration. If no automated runner exists, acceptance may use manual or inspection evidence.
|
|
6
|
+
Choose quality.tdd and project criteria in QUALITY.md. Checks default to required/local; classify genuinely unavailable external checks explicitly. Do not require production access to finish implementation. See prompts/quality.md when needed.
|
|
7
|
+
Set documentation.language to the team's language (for example pt-BR or en); auto follows the user's language until resolved. Use UTF-8 and preserve normal spelling and diacritics in project documents. Keep schema keys, IDs and original quotes unchanged.
|
|
8
|
+
4. Create current capability documents and ADRs only where useful. Use the examples in current/_template.md and decisions/_template.md; select active documents in each change.
|
|
9
|
+
5. Create project skills only for recurring procedures. Copy skills/_template/SKILL.md into a folder matching its name, fill name and description, and link longer references. Validate discovery with sdd skills list.
|
|
10
|
+
6. Run sdd doctor, resolve missing setup and review the resulting project settings.
|
|
11
|
+
7. Remove this setup guide after configuration.
|
|
12
|
+
|
|
13
|
+
Do not generate feature code during setup. Do not create generic skills or impose layered architecture on every project.
|
|
14
|
+
Use sdd harness claude-code or sdd harness opencode to install native command and skill entry points.
|
|
15
|
+
These adapters do not change native runtime permissions or install dependencies.
|
|
16
|
+
|
|
17
|
+
For an existing project, adopt observed architecture and tests as a baseline. Do not rewrite existing
|
|
18
|
+
features, invent historical specs or refactor the application during setup. Record uncertainties explicitly.
|
|
19
|
+
For a new project, record only choices that were actually authorized; resolve material unknowns before implementation.
|
|
20
|
+
For broad requirements, follow prompts/intake.md and choose an observable first delivery.
|
|
21
|
+
|
|
22
|
+
Start from the user's goal or supplied PRD, ADR/system design, design system, examples and constraints.
|
|
23
|
+
Formal documents are optional; do not demand a complete document set before helping.
|
|
24
|
+
For a new project identify intended users, observable first outcome and essential constraints;
|
|
25
|
+
propose unknown material choices rather than inventing requirements or creating the whole architecture upfront.
|
|
26
|
+
For an existing project inspect manifests, entry points, modules, data/contracts, UI conventions and tests.
|
|
27
|
+
Explain what is observed, intended or uncertain. Code and docs may disagree; do not silently treat an existing bug as the business rule.
|
|
28
|
+
Keep original source references and active/superseded decisions. Use harness readers for PDFs/images;
|
|
29
|
+
when needed, reference a reviewed UTF-8 excerpt in CLI sources, with its original document provenance.
|
|
30
|
+
Review test commands and their environment before establishing a safe baseline; record unavailable checks honestly.
|
|
31
|
+
Ask only about material gaps/conflicts not answerable from the project. Adopt the baseline without changing feature code.
|
|
32
|
+
|
|
33
|
+
No fixed questionnaire or three-document bundle is required. Resolve the goal, known sources, material constraints
|
|
34
|
+
and safe verification options; ask only for missing information that affects a real decision.
|
|
35
|
+
Optional sdd docs creates reference drafts; --types prd,sd,ds,adr,roadmap selects relevant presets.
|
|
36
|
+
PRD describes product intent, system design the solution structure, ADRs individual decisions and design system the UI contract.
|
|
37
|
+
Preserve existing document names/locations; map authoritative sources in PROJECT.md instead of duplicating them.
|
|
38
|
+
Generate/fill only requested or useful references. Never invent approved decisions or bulk-load docs/ into every task.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: capability
|
|
4
|
+
id: capability-name
|
|
5
|
+
description: Describe the behavior and invariants of this capability.
|
|
6
|
+
status: active
|
|
7
|
+
changes: []
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Capability contract
|
|
11
|
+
|
|
12
|
+
## Behavior
|
|
13
|
+
|
|
14
|
+
Describe observable current behavior, important error cases and invariants.
|
|
15
|
+
Link schemas and source code instead of duplicating every field.
|
|
16
|
+
|
|
17
|
+
## Dependencies
|
|
18
|
+
|
|
19
|
+
Link contracts of affected integrations. Keep historical change details in specs.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: decision
|
|
4
|
+
id: decision-name
|
|
5
|
+
description: Explain the decision and when it applies.
|
|
6
|
+
status: active
|
|
7
|
+
superseded_by: null
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Decision
|
|
11
|
+
|
|
12
|
+
## Context
|
|
13
|
+
|
|
14
|
+
Record evidence and constraints. Label inferred rationale instead of presenting it as historical fact.
|
|
15
|
+
|
|
16
|
+
## Decision
|
|
17
|
+
|
|
18
|
+
State the choice and scope.
|
|
19
|
+
|
|
20
|
+
## Consequences
|
|
21
|
+
|
|
22
|
+
Describe relevant trade-offs. When replaced, keep this ADR and mark it superseded.
|
|
@@ -1,51 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
2. In English
|
|
13
|
-
- Use a scope when it makes sense (e.g. auth, api, ui, db, config, setup)
|
|
14
|
-
- Include a short body with bullet points if the change warrants it
|
|
15
|
-
|
|
16
|
-
## Output format
|
|
17
|
-
|
|
18
|
-
**[Primary language]:**
|
|
19
|
-
`<message>`
|
|
20
|
-
|
|
21
|
-
**EN:**
|
|
22
|
-
`<message>`
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
## Commit Types
|
|
27
|
-
|
|
28
|
-
| Type | When to use | SemVer impact |
|
|
29
|
-
|---|---|---|
|
|
30
|
-
| `feat` | New feature or capability | minor |
|
|
31
|
-
| `fix` | Bug fix | patch |
|
|
32
|
-
| `refactor` | Code change with no behavior change | none |
|
|
33
|
-
| `perf` | Performance improvement | none |
|
|
34
|
-
| `docs` | Documentation only | none |
|
|
35
|
-
| `style` | Formatting, whitespace (no logic change) | none |
|
|
36
|
-
| `test` | Adding or fixing tests | none |
|
|
37
|
-
| `build` | Build system or external dependency changes | none |
|
|
38
|
-
| `ci` | CI/CD configuration changes | none |
|
|
39
|
-
| `chore` | Maintenance tasks (no src or test changes) | none |
|
|
40
|
-
| `revert` | Reverts a previous commit | depends |
|
|
41
|
-
|
|
42
|
-
Use `!` suffix (e.g. `feat!:`) to indicate a breaking change (major in SemVer).
|
|
43
|
-
|
|
44
|
-
## Examples
|
|
45
|
-
|
|
46
|
-
```
|
|
47
|
-
feat(auth): add Google OAuth login
|
|
48
|
-
fix(api): correct JSON parsing error in response handler
|
|
49
|
-
refactor(db): replace raw queries with repository pattern
|
|
50
|
-
feat!: change authentication token format (breaking change)
|
|
51
|
-
```
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: utility
|
|
4
|
+
description: Suggest a commit message describing the actual reviewed change.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Suggest a commit
|
|
8
|
+
|
|
9
|
+
Inspect the actual diff and summarize the concrete behavior in a Conventional Commit message.
|
|
10
|
+
Use the project's language and scope conventions. Distinguish breaking changes explicitly.
|
|
11
|
+
Suggest a message without creating a commit unless the user authorized that action.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: procedure
|
|
4
|
+
description: Turn a broad request into manageable, linked outcomes before implementation.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Triage a broad request
|
|
8
|
+
|
|
9
|
+
1. Identify whether this is a new project, adoption of an existing codebase, a scoped change, or a revision.
|
|
10
|
+
2. Preserve original sources. Inspect an index or relevant sections before loading long documents.
|
|
11
|
+
3. Find a cohesive observable outcome for the next iteration. Propose separate specs for independent
|
|
12
|
+
deliverables, meaningful domain boundaries or uncertainty that should be resolved separately.
|
|
13
|
+
4. Share lasting constraints through current capability contracts and project policies instead of copying
|
|
14
|
+
them into every spec. Record real dependencies in change.yaml.
|
|
15
|
+
5. Use sdd context ID --inspect to diagnose the composed packet. This measures bytes of the selected
|
|
16
|
+
context, not project size or a model's exact token window. Nothing is removed automatically.
|
|
17
|
+
6. Narrow by task, choose explicit source/reference sections, or split the delivery plan. Keep shared
|
|
18
|
+
invariants and blocking assumptions visible. Raising the budget is an explicit choice, not the default remedy.
|
|
19
|
+
7. Ask only about material uncertainty or changed user-visible scope. Continue research and routine choices
|
|
20
|
+
within existing authorization. Explain the proposed next iteration and its acceptance criteria.
|
|
21
|
+
|
|
22
|
+
The CLI cannot intercept text pasted directly into a chat or force every coding tool to follow this process.
|
|
23
|
+
Follow this procedure before implementation when a user gives an oversized or multi-feature request.
|
|
@@ -1,21 +1,12 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- [ ] TC01
|
|
14
|
-
- [ ] TC02
|
|
15
|
-
- [ ] TC03
|
|
16
|
-
|
|
17
|
-
## Risks
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
## Screenshots (if applicable)
|
|
21
|
-
-
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: utility
|
|
4
|
+
description: Describe the final behavior, validation and limitations for reviewers.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Pull request
|
|
8
|
+
|
|
9
|
+
Lead with the concrete problem and resulting behavior. Include relevant verification,
|
|
10
|
+
the tested input/commit, material limitations and migration steps.
|
|
11
|
+
Describe the final change for someone who has not seen the conversation.
|
|
12
|
+
Do not treat a passing command as proof of every requirement; identify manual evidence and unverified cases.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: procedure
|
|
4
|
+
description: Select meaningful quality evidence without imposing a stack or a production environment.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Quality practices
|
|
8
|
+
|
|
9
|
+
Load this procedure when defining or reviewing test strategy, quality thresholds or environment limitations.
|
|
10
|
+
Project-specific criteria belong in QUALITY.md, mandatory constraints in POLICIES.md and tool settings in their native files.
|
|
11
|
+
|
|
12
|
+
## Acceptance by examples
|
|
13
|
+
|
|
14
|
+
Explore concrete examples with the developer: initial state, action and observable result.
|
|
15
|
+
Include relevant boundaries, invalid input, permissions and integration failures.
|
|
16
|
+
Store the examples in the existing SPEC acceptance descriptions, linked to requirement IDs.
|
|
17
|
+
BDD does not require Gherkin files, Cucumber or duplicate specifications. Do not invent business approval.
|
|
18
|
+
|
|
19
|
+
## Test-first and TDD
|
|
20
|
+
|
|
21
|
+
Follow config quality.tdd (optional, preferred or required). For a reproducible defect, add a regression test when feasible.
|
|
22
|
+
Use small RED–GREEN–REFACTOR cycles: observe the intended failing test, implement the behavior, then improve structure.
|
|
23
|
+
A setup/import/syntax error is not automatically evidence of the intended behavioral failure.
|
|
24
|
+
Record useful command/run references in task evidence; keep detailed logs outside default context.
|
|
25
|
+
Partial verification can record RED and subsequent GREEN runs; expected RED is not a final approved result.
|
|
26
|
+
Do not claim TDD merely because the final suite passes. The CLI does not certify the chronological practice.
|
|
27
|
+
|
|
28
|
+
## Metrics and analysis
|
|
29
|
+
|
|
30
|
+
Use coverage to find untested behavior, and review assertions, not only percentages.
|
|
31
|
+
Complexity identifies code needing examination; do not split functions mechanically to game a score.
|
|
32
|
+
Choose tools/thresholds for the project's language, baseline, risk and change. Track legacy findings separately.
|
|
33
|
+
Mutation tests, dependency checks, security analysis and load tests are conditional, not universal requirements.
|
|
34
|
+
An advisory metric must not be the sole evidence for a required acceptance criterion.
|
|
35
|
+
|
|
36
|
+
## Missing environments and user handoff
|
|
37
|
+
|
|
38
|
+
Run available, authorized local checks. Do not demand production/homologation access to complete implementation.
|
|
39
|
+
Do not call missing access a passing test, or an actual behavior failure merely a missing environment.
|
|
40
|
+
Use external on the actual environment-dependent check or manual/inspection criterion.
|
|
41
|
+
Use kind: verification and status: deferred only for genuine external verification tasks, with by and reason.
|
|
42
|
+
Implementation tasks cannot be deferred as if their code were complete.
|
|
43
|
+
|
|
44
|
+
Run sdd handoff ID; fill the returned JSON with reason, responsible role, environment, prerequisites,
|
|
45
|
+
short steps, observable expected result, safety constraints and the condition for resuming.
|
|
46
|
+
When no safe test exists, use environment: unavailable, explain why and leave steps empty.
|
|
47
|
+
For an actionable test, use an isolated/non-production environment or a genuinely read-only production observation.
|
|
48
|
+
Do not suggest production writes, deletions, load, permission changes or real-data manipulation just to prove success.
|
|
49
|
+
If an operation cannot be shown to be safe, defer it rather than improvise. A JSON field cannot prove safety.
|
|
50
|
+
|
|
51
|
+
Run sdd verify ID --handoff PATH. External commands are not run by default.
|
|
52
|
+
Use --run-external only when execution in the actual target environment is available and authorized;
|
|
53
|
+
the flag itself grants no permission. Preserve actual failures, partial results and warnings.
|
|
54
|
+
|
|
55
|
+
Full limited verification can close the implementation with explicit pending verification and USER_TESTS.md.
|
|
56
|
+
It is not a successful external test, a release approval or evidence that production works.
|
|
57
|
+
When access/results become available, reopen and verify with actual evidence. Keep the earlier closure in history.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: procedure
|
|
4
|
+
phase: close
|
|
5
|
+
description: Consolidate implementation and close with truthful verification status and explicit limitations.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Consolidate and close
|
|
9
|
+
|
|
10
|
+
Update the selected active capability contracts to describe implemented behavior and distinguish any unverified external behavior.
|
|
11
|
+
Add this spec ID to each document's changes list. Link code schemas rather than copying all fields.
|
|
12
|
+
Record durable architectural decisions in individual ADRs; mark replaced ADRs superseded.
|
|
13
|
+
Keep research alternatives and execution detail in change history.
|
|
14
|
+
|
|
15
|
+
Perform final verification after consolidation, so its digest includes the updated contracts.
|
|
16
|
+
Review the result and actual scope. Close with sdd close ID --by NAME --archive after actual review authorization.
|
|
17
|
+
If no capability contract needs updating, provide --note explaining why no lasting contract changed.
|
|
18
|
+
Partial, failed, missing or stale receipts must not close a change. A full limited receipt can close implementation
|
|
19
|
+
when external limitations have a current handoff. Retain USER_TESTS.md and pending verification in closure/history.
|
|
20
|
+
Never describe that result as external success or production/release approval. Lack of a real environment alone must not block progress.
|
|
21
|
+
|
|
22
|
+
Archiving preserves identity and reserves its number. Use sdd reopen ID --by NAME --reason REASON
|
|
23
|
+
for new work on a closed change; a new verification is required.
|
|
@@ -1,68 +1,35 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
- **Check TEST.md for impact** — if any test case covers behavior changed by this task:
|
|
37
|
-
- Update the affected test case(s) in TEST.md if the expected behavior changed
|
|
38
|
-
- Record in PROGRESS.md which test cases were affected and why
|
|
39
|
-
- If VALIDATION.md exists and covers those cases, mark the affected rows as `⚠️ Needs re-validation`
|
|
40
|
-
5. **Stop and wait for confirmation** before moving to the next task
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## Emerging scope
|
|
45
|
-
|
|
46
|
-
If unexpected work is discovered during implementation, apply **R15** before continuing:
|
|
47
|
-
|
|
48
|
-
1. Describe the emerging work in one sentence
|
|
49
|
-
2. Apply the decision table:
|
|
50
|
-
- Modifies files already in this spec's scope → add task to current `TASK.md`
|
|
51
|
-
- Small gap or planning oversight → add task to current `TASK.md`
|
|
52
|
-
- New module, entity, or feature goal not in `SPEC.md` → new spec
|
|
53
|
-
- Explicitly in `SPEC.md` "Out of scope" → new spec
|
|
54
|
-
- Crosses a domain boundary → new spec
|
|
55
|
-
3. State the chosen action with justification
|
|
56
|
-
4. **Stop and wait for developer confirmation** before proceeding
|
|
57
|
-
|
|
58
|
-
Never decide silently. Never create a new spec or add a task without surfacing the decision first.
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
## Constraints
|
|
63
|
-
|
|
64
|
-
- Do not anticipate future tasks
|
|
65
|
-
- Do not refactor code outside the current task's scope
|
|
66
|
-
- Do not add dependencies without recording them in DECISIONS.md
|
|
67
|
-
- Do not run git commands
|
|
68
|
-
- If there is ambiguity about scope or approach, **ask before generating code**
|
|
1
|
+
---
|
|
2
|
+
schema_version: 2
|
|
3
|
+
kind: procedure
|
|
4
|
+
phase: implement
|
|
5
|
+
description: Execute approved cohesive outcomes with bounded context.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Implement
|
|
9
|
+
|
|
10
|
+
Run sdd check ID --phase implement. Resolve a missing/stale approval against the actual user authorization.
|
|
11
|
+
Select a pending task whose dependencies are done; light changes may execute directly from acceptance.
|
|
12
|
+
Load sdd context ID --phase implement --task T01 when a task exists.
|
|
13
|
+
Use sdd skills list for metadata discovery and load only relevant bodies.
|
|
14
|
+
|
|
15
|
+
State the intended outcome. Implement the scoped behavior and tests together.
|
|
16
|
+
Inspect existing code and read additional references when needed; record why additional context matters.
|
|
17
|
+
Check affected callers/contracts and the planned regression baseline before editing shared behavior.
|
|
18
|
+
After the focused change, run the relevant consumer/integration regressions; a passing isolated unit test is insufficient when callers are affected.
|
|
19
|
+
Do not adjust expected behavior simply to make tests pass.
|
|
20
|
+
Follow quality.tdd and use small regression/TDD cycles when applicable; preserve useful RED/GREEN run references.
|
|
21
|
+
Read quality.md for strategy details. Do not claim test-first practice solely from final green tests.
|
|
22
|
+
|
|
23
|
+
Check the task's verify condition using observable evidence before marking status: done.
|
|
24
|
+
Keep status only in TASK.md; an optional STATE.md records blockers and the next action without duplicating the task table.
|
|
25
|
+
Do not create an append-only execution diary in always-loaded files.
|
|
26
|
+
|
|
27
|
+
Follow configured autonomy as the standing default. New projects default to step: implement and verify
|
|
28
|
+
one task, then stop for review unless the user already authorized specific additional tasks or all tasks
|
|
29
|
+
in this scope. Follow that authorization without stopping between those tasks or asking again; it does
|
|
30
|
+
not require changing config.yaml. Plan approval alone does not override step. Batch may also be the
|
|
31
|
+
project's standing configuration. In every case, verify/update tasks individually and respect dependencies.
|
|
32
|
+
Ask when behavior, scope or permissions materially change. Continue routine implementation choices inside approved scope.
|
|
33
|
+
Use partial verification for early feedback. Consolidate lasting capability contracts before final verification.
|
|
34
|
+
If only external verification lacks access, finish available implementation/local checks and prepare sdd handoff ID.
|
|
35
|
+
Keep external verification deferred explicitly; do not ask the user to perform risky production actions just to close the spec.
|