sdd-flow 1.3.3 → 2.0.0

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.
Files changed (70) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/CONTRIBUTING.md +25 -0
  3. package/LICENSE +21 -21
  4. package/README.md +113 -168
  5. package/README.pt-BR.md +100 -0
  6. package/bin/cli.js +162 -424
  7. package/docs/architecture.md +91 -0
  8. package/docs/distribution.md +64 -0
  9. package/docs/formats.md +212 -0
  10. package/docs/local-testing.pt-BR.md +195 -0
  11. package/docs/methodology.pt-BR.md +133 -0
  12. package/docs/migration.md +75 -0
  13. package/docs/quality-gates.pt-BR.md +160 -0
  14. package/docs/quality.md +56 -0
  15. package/docs/releases.pt-BR.md +186 -0
  16. package/docs/setup-documents.pt-BR.md +120 -0
  17. package/docs/usage.pt-BR.md +305 -0
  18. package/docs/validation.md +95 -0
  19. package/lib/adapters.js +115 -0
  20. package/lib/check.js +221 -0
  21. package/lib/context.js +117 -0
  22. package/lib/documents.js +71 -0
  23. package/lib/handoff.js +81 -0
  24. package/lib/history.js +16 -0
  25. package/lib/install.js +181 -0
  26. package/lib/io.js +119 -0
  27. package/lib/legacy-hashes.json +31 -0
  28. package/lib/markdown.js +71 -0
  29. package/lib/project.js +200 -0
  30. package/lib/quality.js +24 -0
  31. package/lib/revisions.js +79 -0
  32. package/lib/verification.js +267 -0
  33. package/package.json +55 -32
  34. package/templates/AGENTS.md +12 -50
  35. package/templates/QUICKSTART.md +16 -70
  36. package/templates/agents/AGENTS.md +54 -92
  37. package/templates/agents/DECISIONS.md +5 -21
  38. package/templates/agents/POLICIES.md +14 -0
  39. package/templates/agents/PROJECT.md +35 -145
  40. package/templates/agents/QUALITY.md +19 -0
  41. package/templates/agents/RULES.md +22 -132
  42. package/templates/agents/SETUP.md +38 -224
  43. package/templates/agents/config.yaml +13 -0
  44. package/templates/agents/current/_template.md +19 -0
  45. package/templates/agents/decisions/_template.md +22 -0
  46. package/templates/agents/prompts/conventional-commit.md +11 -51
  47. package/templates/agents/prompts/intake.md +23 -0
  48. package/templates/agents/prompts/pr-template.md +12 -21
  49. package/templates/agents/prompts/quality.md +57 -0
  50. package/templates/agents/prompts/rpi-close.md +23 -0
  51. package/templates/agents/prompts/rpi-implement.md +31 -68
  52. package/templates/agents/prompts/rpi-plan.md +87 -117
  53. package/templates/agents/prompts/rpi-research.md +21 -67
  54. package/templates/agents/prompts/rpi-validate.md +40 -103
  55. package/templates/agents/prompts/skill-call.md +11 -29
  56. package/templates/agents/prompts/task-create.md +13 -42
  57. package/templates/agents/skills/_template/SKILL.md +11 -37
  58. package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
  59. package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
  60. package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
  61. package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
  62. package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
  63. package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
  64. package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
  65. package/templates/agents/harness/claude-code/settings.json +0 -34
  66. package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
  67. package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
  68. package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
  69. package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
  70. package/templates/agents/harness/opencode/opencode.json +0 -18
@@ -1,224 +1,38 @@
1
- # Agents Template — Setup Guide
2
-
3
- This template implements the **SDD (Spec Driven Development)** workflow using the **RPIV (Research → Plan → Implement → Validate)** methodology. It is LLM-agnostic and stack-agnostic.
4
-
5
- > After completing setup, delete this file from the project.
6
-
7
- ---
8
-
9
- ## Directory Structure
10
-
11
- ```
12
- AGENTS.md ← Entry point — auto-loaded by any harness (do not modify)
13
- opencode.json ← Optional: OpenCode harness config (copy from agents/harness/opencode/)
14
- .claude/
15
- settings.json ← Optional: Claude Code harness config (copy from agents/harness/claude-code/)
16
- agents/
17
- AGENTS.md ← Full workflow definition (do not modify)
18
- RULES.md ← Process rules: git, tasks, decisions (do not modify)
19
- PROJECT.md ← ⚠️ FILL THIS: stack, architecture, stack-specific rules
20
- DECISIONS.md ← Architectural decisions log (append-only)
21
- SETUP.md ← This file. Delete after setup is complete
22
- harness/ ← Optional enforcement configs per harness (copy to project root to activate)
23
- claude-code/
24
- settings.json ← Claude Code: example config — permissions + hooks (customize as needed)
25
- opencode/
26
- opencode.json ← OpenCode: example config — instructions + permissions (customize as needed)
27
- prompts/
28
- rpi-research.md ← Phase 1 prompt (do not modify)
29
- rpi-plan.md ← Phase 2 prompt (do not modify)
30
- rpi-implement.md ← Phase 3 prompt (do not modify)
31
- task-create.md ← Utility prompt (do not modify)
32
- skill-call.md ← Utility prompt (do not modify)
33
- conventional-commit.md ← Utility prompt (do not modify)
34
- pr-template.md ← Utility prompt (do not modify)
35
- skills/
36
- _template/
37
- SKILL.md ← Template for new skills (do not modify)
38
- [capability-name]/ ← ⚠️ CREATE: one folder per reusable capability
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. 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,13 @@
1
+ schema_version: 2
2
+ mode: standard
3
+ autonomy: batch
4
+ approval: required
5
+ documentation:
6
+ language: auto
7
+ quality:
8
+ tdd: preferred
9
+ context:
10
+ max_bytes: 48000
11
+ checks: []
12
+ verification:
13
+ exclude: []
@@ -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
- # Prompt: Conventional Commit Suggestion
2
-
3
- Based on the changes made in this task/feature, suggest commit messages following the Conventional Commits specification.
4
-
5
- ---
6
-
7
- ## Rules
8
-
9
- - Do not run git commands
10
- - Generate 2 suggestions:
11
- 1. In the team's primary language
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
- # Pull Request Template
2
-
3
- ## What was done
4
- -
5
-
6
- ## Why it was done
7
- -
8
-
9
- ## How to test
10
- -
11
-
12
- ## Acceptance criteria met
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,31 @@
1
- # Prompt: Implement (RPI — Phase 3)
2
-
3
- Use this prompt to implement a single task from an existing spec.
4
-
5
- ---
6
-
7
- ## Agent instruction
8
-
9
- You will implement **one single task** from an already planned feature.
10
-
11
- **Before starting, read:**
12
- - `agents/AGENTS.md`
13
- - `agents/PROJECT.md`
14
- - `agents/RULES.md`
15
- - `agents/specs/NNN-name/SPEC.md`
16
- - `agents/specs/NNN-name/TASK.md` — identify the first unchecked `[ ]`
17
- - `agents/specs/NNN-name/PROGRESS.md`
18
- - Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` — load the full `SKILL.md` only for skills relevant to this task
19
-
20
- **Expected input:**
21
- - Spec number (e.g. `001`)
22
- - Task to implement (e.g. `T03`) — if not provided, use the first unchecked `[ ]`
23
-
24
- ---
25
-
26
- ## Expected behavior
27
-
28
- 1. Declare which task will be implemented before generating any code
29
- 2. Implement only what is necessary for that single task
30
- 3. State exactly **which file** was created or modified
31
- 4. After completing:
32
- - Confirm the `verify:` condition on the completed task is met before marking it done
33
- - Mark `[x]` on the task in TASK.md
34
- - Update PROGRESS.md with what was done and any observations
35
- - Record relevant architectural decisions in DECISIONS.md
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: step stops after a task; batch continues through authorized tasks.
28
+ Ask when behavior, scope or permissions materially change. Continue routine implementation choices inside approved scope.
29
+ Use partial verification for early feedback. Consolidate lasting capability contracts before final verification.
30
+ If only external verification lacks access, finish available implementation/local checks and prepare sdd handoff ID.
31
+ Keep external verification deferred explicitly; do not ask the user to perform risky production actions just to close the spec.